From d585a237f9a9c9e4306f6944ef82d042669b121a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Thu, 19 Nov 2026 14:34:25 +0100 Subject: [PATCH 1/2] fix(contracts): pair open runtime hints with their apply operation The invariant "runtime hints are optional only when no transport hint is requested" existed only as prose on OpenApplicationInput, so three producers threw reason 'runtime-hints-operation-missing' without setting dispatched, forcing a consumer-side reason exclusion in session-open-execution. OpenApplicationInput.runtimeHints is now one optional field pairing the requested values with the fact-admitted apply callback (OpenApplicationRuntimeHints), so a hints request cannot exist without its transport. The daemon producer pairs them in session-runtime; the Apple and Android lifecycle throw sites are deleted because the type makes the unadmitted state unconstructible (facts admission already refuses the open earlier). The clear-hints refusal in session-open-prepare sets dispatched: 'no' (it fires before any native effect), so the relaunch catch keys only on the dispatch disclosure and needs no reason-based exclusion. OpenApplicationInput is in-process only: it is absent from the wire-compat surface and from the agent-device/plugins type-only contract (ADR 0034), so no wire digest or plugin shape moves. --- .../application-lifecycle-interaction.test.ts | 1 - .../src/application-lifecycle-runtime.ts | 18 +++++++++---- .../application-lifecycle-runtime-fixture.ts | 7 +++--- .../session-open-execution-relaunch.test.ts | 4 +-- .../internal/session-open-execution.ts | 9 +++---- .../internal/session-open-prepare.ts | 3 +++ .../daemon/src/sessions/session-runtime.ts | 15 +++++++++++ .../platform-android/src/lifecycle.test.ts | 1 - packages/platform-android/src/lifecycle.ts | 15 +++-------- .../src/expo-dev-client-launch.test.ts | 25 ++++++++++++------- .../src/expo-dev-client-launch.ts | 7 +++--- .../src/lifecycle-expo-dev-client.test.ts | 14 +++++++++-- .../platform-apple/src/lifecycle.fixtures.ts | 1 - packages/platform-apple/src/lifecycle.ts | 15 +++-------- .../provider-limrun/src/lifecycle.test.ts | 1 - .../provider-revyl/src/interactor.test.ts | 1 - src/core/interactors/limrun-ios-files.test.ts | 6 +++-- 17 files changed, 82 insertions(+), 61 deletions(-) diff --git a/packages/contracts/src/application-lifecycle-interaction.test.ts b/packages/contracts/src/application-lifecycle-interaction.test.ts index 33b2414b73..b0bb5b3c6d 100644 --- a/packages/contracts/src/application-lifecycle-interaction.test.ts +++ b/packages/contracts/src/application-lifecycle-interaction.test.ts @@ -55,7 +55,6 @@ function openInput(overrides: Partial = {}): OpenApplicati prewarmRunnerBeforeOpen: false, enableTestIme: false, stateDir: '/state', - runtimeHints: {}, execution: {}, ...overrides, }; diff --git a/packages/contracts/src/application-lifecycle-runtime.ts b/packages/contracts/src/application-lifecycle-runtime.ts index 36a38e8b9c..b1e01d7e76 100644 --- a/packages/contracts/src/application-lifecycle-runtime.ts +++ b/packages/contracts/src/application-lifecycle-runtime.ts @@ -97,6 +97,16 @@ export type OpenApplicationPreparationInput = Readonly<{ */ export type OpenApplicationRunnerDemand = 'none' | 'possible' | 'required'; +/** + * A runtime-hints request paired with the fact-admitted operation that applies it natively. The + * pair is one field, so a hints request cannot exist without its transport; `openApplication` + * never imports or falls back to a sibling implementation behind a false runtime-hints fact. + */ +export type OpenApplicationRuntimeHints = Readonly<{ + values: RuntimeHintValues; + apply: (input: RuntimeHintsApplicationInput) => Promise; +}>; + /** The normalized public application launch, independent of daemon request shape. */ export type OpenApplicationInput = Readonly<{ target?: string; @@ -110,13 +120,11 @@ export type OpenApplicationInput = Readonly<{ prewarmRunnerBeforeOpen: boolean; enableTestIme: boolean; stateDir: string; - runtimeHints: RuntimeHintValues; /** - * The fact-admitted runtime-hint operation for this open. It is optional only when no - * transport hint is requested; `openApplication` never imports or falls back to a sibling - * implementation behind a false runtime-hints fact. + * The transport hints this open must apply natively, paired with their fact-admitted apply + * operation. Absent when the open requests no transport hint. */ - applyRuntimeHints?: (input: RuntimeHintsApplicationInput) => Promise; + runtimeHints?: OpenApplicationRuntimeHints; execution: ApplicationLifecycleExecution; }>; diff --git a/packages/daemon/src/__tests__/support/application-lifecycle-runtime-fixture.ts b/packages/daemon/src/__tests__/support/application-lifecycle-runtime-fixture.ts index 7ee0a65106..2e9f6ce49f 100644 --- a/packages/daemon/src/__tests__/support/application-lifecycle-runtime-fixture.ts +++ b/packages/daemon/src/__tests__/support/application-lifecycle-runtime-fixture.ts @@ -111,7 +111,8 @@ const openApplicationFixture = vi.fn( direct: ApplicationLifecycleRuntimeOperations, input: Parameters[0], ) => { - if (input.applyRuntimeHints) { + const runtimeHints = input.runtimeHints; + if (runtimeHints) { // The direct owner's close-before-relaunch happens inside its open; a hinted relaunch // must close before the hints land, so take the close here and open as a fresh launch. if (input.relaunch && input.target !== undefined) { @@ -120,10 +121,10 @@ const openApplicationFixture = vi.fn( surface: input.surface, execution: input.execution, }); - await input.applyRuntimeHints({ appId: input.appBundleId, values: input.runtimeHints }); + await runtimeHints.apply({ appId: input.appBundleId, values: runtimeHints.values }); return await direct.openApplication({ ...input, relaunch: false }); } - await input.applyRuntimeHints({ appId: input.appBundleId, values: input.runtimeHints }); + await runtimeHints.apply({ appId: input.appBundleId, values: runtimeHints.values }); } return await direct.openApplication(input); }, diff --git a/packages/daemon/src/sessions/session-lifecycle/internal/session-open-execution-relaunch.test.ts b/packages/daemon/src/sessions/session-lifecycle/internal/session-open-execution-relaunch.test.ts index 734e743228..27abb1ac8e 100644 --- a/packages/daemon/src/sessions/session-lifecycle/internal/session-open-execution-relaunch.test.ts +++ b/packages/daemon/src/sessions/session-lifecycle/internal/session-open-execution-relaunch.test.ts @@ -288,8 +288,8 @@ test('failed relaunch retains the claim for close while allowing daemon idle rea } }); -test.each([{ dispatched: 'no' as const }, { reason: 'runtime-hints-operation-missing' }])( - 'a relaunch refusal with confirmed or undispatched effects leaves the daemon active: %o', +test.each([{ dispatched: 'no' as const }])( + 'a relaunch refusal with undispatched effects leaves the daemon active: %o', async (details) => { const sessionStore = makeSessionStore(); publishSession(sessionStore, 'android-session', ANDROID_EMULATOR); diff --git a/packages/daemon/src/sessions/session-lifecycle/internal/session-open-execution.ts b/packages/daemon/src/sessions/session-lifecycle/internal/session-open-execution.ts index 14016896c7..7f1118a5bc 100644 --- a/packages/daemon/src/sessions/session-lifecycle/internal/session-open-execution.ts +++ b/packages/daemon/src/sessions/session-lifecycle/internal/session-open-execution.ts @@ -41,7 +41,7 @@ import { import { SessionStore } from '../../../core/session-store.ts'; import { countConfiguredRuntimeHints, - runtimeHintValues, + openApplicationRuntimeHints, setSessionRuntimeHintsForOpen, } from '../../session-runtime.ts'; import { STARTUP_SAMPLE_METHOD, type StartupPerfSample } from './session-startup-metrics.ts'; @@ -307,8 +307,7 @@ export async function completeOpenCommand(params: { prewarmRunnerBeforeOpen: req.flags?.maestro?.prewarmRunnerBeforeOpen === true, enableTestIme: shouldActivateAndroidTestIme(device, req), stateDir: sessionStore.resolveDaemonStateDir(), - runtimeHints: runtimeHintValues(runtimeHints), - applyRuntimeHints, + runtimeHints: openApplicationRuntimeHints(runtimeHints, applyRuntimeHints), execution: applicationLifecycleExecutionFromRequest( req, logPath, @@ -317,9 +316,7 @@ export async function completeOpenCommand(params: { }) .catch((error: unknown) => { const effectsConfirmedOrUndispatched = - error instanceof AppError && - (readDispatchDisclosure(error.details) === 'no' || - error.details?.reason === 'runtime-hints-operation-missing'); + error instanceof AppError && readDispatchDisclosure(error.details) === 'no'; if (!effectsConfirmedOrUndispatched) markUnconfirmedRelaunch(); throw error; }); diff --git a/packages/daemon/src/sessions/session-lifecycle/internal/session-open-prepare.ts b/packages/daemon/src/sessions/session-lifecycle/internal/session-open-prepare.ts index d3e2899998..ae4ac0f2d0 100644 --- a/packages/daemon/src/sessions/session-lifecycle/internal/session-open-prepare.ts +++ b/packages/daemon/src/sessions/session-lifecycle/internal/session-open-prepare.ts @@ -186,11 +186,14 @@ export async function prepareOpenCommandDetails(params: { }); if (runtimeHintPlan.clearRemovedRuntimeHints) { if (!clearRuntimeHints) { + // Refused before the clear runs, and preparation precedes the open dispatch, so no + // native effect has happened yet. throw new AppError( 'COMMAND_FAILED', 'Runtime hint clear operation was not admitted for this open.', { reason: 'runtime-hints-operation-missing', + dispatched: 'no', }, ); } diff --git a/packages/daemon/src/sessions/session-runtime.ts b/packages/daemon/src/sessions/session-runtime.ts index 89ec1834f5..141b57557e 100644 --- a/packages/daemon/src/sessions/session-runtime.ts +++ b/packages/daemon/src/sessions/session-runtime.ts @@ -1,6 +1,8 @@ import type { CommandFlags, DaemonWireRequest } from '@agent-device/contracts/command'; import { + type OpenApplicationRuntimeHints, type RuntimeHintValues, + type RuntimeHintsApplicationInput, hasRuntimeTransportHintValues, } from '@agent-device/contracts/application-lifecycle-runtime'; import { AppError, asAppError } from '@agent-device/kernel/errors'; @@ -54,6 +56,19 @@ export function hasRuntimeTransportHints(runtime: SessionRuntimeHints | undefine return hasRuntimeTransportHintValues(runtimeHintValues(runtime)); } +/** + * Pairs the open's requested transport hints with the fact-admitted apply operation, so the + * lifecycle input cannot carry a hints request without its transport. Absent when the open + * requests no transport hint; facts admission guarantees the operation whenever it is requested. + */ +export function openApplicationRuntimeHints( + runtime: SessionRuntimeHints | undefined, + apply: ((input: RuntimeHintsApplicationInput) => Promise) | undefined, +): OpenApplicationRuntimeHints | undefined { + if (apply === undefined || !hasRuntimeTransportHints(runtime)) return undefined; + return { values: runtimeHintValues(runtime), apply }; +} + function normalizeRuntimeStringInput( value: unknown, fieldName: 'metroHost' | 'bundleUrl' | 'launchUrl', diff --git a/packages/platform-android/src/lifecycle.test.ts b/packages/platform-android/src/lifecycle.test.ts index dc70a2b659..8ec48f2a55 100644 --- a/packages/platform-android/src/lifecycle.test.ts +++ b/packages/platform-android/src/lifecycle.test.ts @@ -150,7 +150,6 @@ function openInput(overrides: Partial = {}): OpenApplicati prewarmRunnerBeforeOpen: false, enableTestIme: false, stateDir: '/state', - runtimeHints: {}, execution: {}, ...overrides, }; diff --git a/packages/platform-android/src/lifecycle.ts b/packages/platform-android/src/lifecycle.ts index 89cd085bff..029288658a 100644 --- a/packages/platform-android/src/lifecycle.ts +++ b/packages/platform-android/src/lifecycle.ts @@ -3,7 +3,6 @@ import { type OpenApplicationInput, type OpenApplicationOutcome, type OpenApplicationTiming, - hasRuntimeTransportHintValues, } from '@agent-device/contracts/application-lifecycle-runtime'; import type { PlatformRuntimeHost } from '@agent-device/contracts/platform-runtime-operations'; import { @@ -122,18 +121,10 @@ async function openAndroidApplication( }); timing.relaunchCloseDurationMs = elapsed(closeStartedAtMs); } - if (hasRuntimeTransportHintValues(input.runtimeHints)) { - if (!input.applyRuntimeHints) { - throw new AppError( - 'COMMAND_FAILED', - 'Runtime hint operation was not admitted for this open.', - { - reason: 'runtime-hints-operation-missing', - }, - ); - } + const runtimeHints = input.runtimeHints; + if (runtimeHints) { const hintsStartedAtMs = Date.now(); - await input.applyRuntimeHints({ appId: input.appBundleId, values: input.runtimeHints }); + await runtimeHints.apply({ appId: input.appBundleId, values: runtimeHints.values }); timing.runtimeHintsDurationMs = elapsed(hintsStartedAtMs); } const openStartedAtMs = Date.now(); diff --git a/packages/platform-apple/src/expo-dev-client-launch.test.ts b/packages/platform-apple/src/expo-dev-client-launch.test.ts index 7eace90284..a70642c910 100644 --- a/packages/platform-apple/src/expo-dev-client-launch.test.ts +++ b/packages/platform-apple/src/expo-dev-client-launch.test.ts @@ -1,5 +1,8 @@ import { afterEach, expect, test, vi } from 'vitest'; -import type { OpenApplicationInput } from '@agent-device/contracts/application-lifecycle-runtime'; +import type { + OpenApplicationInput, + OpenApplicationRuntimeHints, +} from '@agent-device/contracts/application-lifecycle-runtime'; import { AppError, createRequestCanceledError } from '@agent-device/kernel/errors'; import { openInput as lifecycleOpenInput, simulator as SIMULATOR } from './lifecycle.fixtures.ts'; @@ -12,10 +15,14 @@ import { resolveExpoDevClientLaunchUrl } from './expo-dev-client-launch.ts'; const resolveScheme = vi.mocked(resolveIosSimulatorExpoDevClientScheme); +function hints(values: Record): OpenApplicationRuntimeHints { + return { values, apply: async () => {} }; +} + function openInput(overrides: Partial = {}): OpenApplicationInput { return { ...lifecycleOpenInput(), - runtimeHints: { metroHost: '127.0.0.1', metroPort: '8085' }, + runtimeHints: hints({ metroHost: '127.0.0.1', metroPort: '8085' }), ...overrides, }; } @@ -36,7 +43,7 @@ test.each([ ])('points an expo-dev-client at %s', async (_name, bundleUrl, expected) => { resolveScheme.mockResolvedValue('exp+dev-slug'); - const input = openInput(bundleUrl ? { runtimeHints: { bundleUrl } } : {}); + const input = openInput(bundleUrl ? { runtimeHints: hints({ bundleUrl }) } : {}); await expect(resolveExpoDevClientLaunchUrl(SIMULATOR, input)).resolves.toBe(expected); expect(resolveScheme).toHaveBeenCalledWith(SIMULATOR, 'com.example.app', { timeoutMs: 3_000, @@ -46,9 +53,9 @@ test.each([ test('points at the server origin of a bundle URL, not at the bundle itself', async () => { resolveScheme.mockResolvedValue('exp+dev-slug'); const input = openInput({ - runtimeHints: { + runtimeHints: hints({ bundleUrl: 'http://10.0.0.5:8090/.expo/.virtual-metro-entry.bundle?platform=ios&dev=true', - }, + }), }); await expect(resolveExpoDevClientLaunchUrl(SIMULATOR, input)).resolves.toBe( @@ -59,7 +66,7 @@ test('points at the server origin of a bundle URL, not at the bundle itself', as test('keeps a single pair of brackets around an IPv6 bundle URL host', async () => { resolveScheme.mockResolvedValue('exp+dev-slug'); const input = openInput({ - runtimeHints: { bundleUrl: 'http://[::1]:8090/index.bundle?platform=ios' }, + runtimeHints: hints({ bundleUrl: 'http://[::1]:8090/index.bundle?platform=ios' }), }); await expect(resolveExpoDevClientLaunchUrl(SIMULATOR, input)).resolves.toBe( @@ -70,10 +77,10 @@ test('keeps a single pair of brackets around an IPv6 bundle URL host', async () test('keeps the server mount when opening a path-prefixed Expo bundle', async () => { resolveScheme.mockResolvedValue('exp+dev-slug'); const input = openInput({ - runtimeHints: { + runtimeHints: hints({ bundleUrl: 'https://metro.example.test/tenant-42/.expo/.virtual-metro-entry.bundle?platform=ios', - }, + }), }); const launchUrl = await resolveExpoDevClientLaunchUrl(SIMULATOR, input); @@ -88,7 +95,7 @@ test.each([ 'exp+dev-slug', ], ['an open without an app bundle id', openInput({ appBundleId: undefined }), 'exp+dev-slug'], - ['hints without a host and port', openInput({ runtimeHints: {} }), 'exp+dev-slug'], + ['hints without a host and port', openInput({ runtimeHints: hints({}) }), 'exp+dev-slug'], ])('keeps the plain launch for %s', async (_name, input, scheme) => { resolveScheme.mockResolvedValue(scheme); diff --git a/packages/platform-apple/src/expo-dev-client-launch.ts b/packages/platform-apple/src/expo-dev-client-launch.ts index 5df34096e8..945789a144 100644 --- a/packages/platform-apple/src/expo-dev-client-launch.ts +++ b/packages/platform-apple/src/expo-dev-client-launch.ts @@ -13,10 +13,11 @@ export async function resolveExpoDevClientLaunchUrl( input: OpenApplicationInput, ): Promise { if (!input.appBundleId || input.runtimeLaunchUrl?.trim()) return undefined; + const values = input.runtimeHints?.values; const serverUrl = resolveRuntimeServerUrl({ - metroHost: input.runtimeHints.metroHost, - metroPort: input.runtimeHints.metroPort ? Number(input.runtimeHints.metroPort) : undefined, - bundleUrl: input.runtimeHints.bundleUrl, + metroHost: values?.metroHost, + metroPort: values?.metroPort ? Number(values.metroPort) : undefined, + bundleUrl: values?.bundleUrl, }); if (!serverUrl) return undefined; let scheme: string | undefined; diff --git a/packages/platform-apple/src/lifecycle-expo-dev-client.test.ts b/packages/platform-apple/src/lifecycle-expo-dev-client.test.ts index 8b304c2e3a..43a411c187 100644 --- a/packages/platform-apple/src/lifecycle-expo-dev-client.test.ts +++ b/packages/platform-apple/src/lifecycle-expo-dev-client.test.ts @@ -1,4 +1,8 @@ import { beforeEach, expect, test, vi } from 'vitest'; +import { + type OpenApplicationRuntimeHints, + hasRuntimeTransportHintValues, +} from '@agent-device/contracts/application-lifecycle-runtime'; import { alertNotFound } from './launch-confirmation.fixtures.ts'; import { launchUrlSimulator, openInput, resetUrlOwner } from './lifecycle.fixtures.ts'; @@ -33,11 +37,17 @@ test.each([ const { lifecycle, events } = launchUrlSimulator(async () => { throw alertNotFound(); }); + // The daemon producer pairs the values with the apply operation only when a transport + // hint is requested, so this mirrors that rule. + const hints: OpenApplicationRuntimeHints | undefined = hasRuntimeTransportHintValues( + runtimeHints, + ) + ? { values: runtimeHints, apply: applyRuntimeHints } + : undefined; await lifecycle.openApplication({ ...openInput(), - runtimeHints, - applyRuntimeHints, + runtimeHints: hints, execution: { plannedOperations: ['captureSnapshot'] }, }); diff --git a/packages/platform-apple/src/lifecycle.fixtures.ts b/packages/platform-apple/src/lifecycle.fixtures.ts index 911fb73d4f..9f76db715c 100644 --- a/packages/platform-apple/src/lifecycle.fixtures.ts +++ b/packages/platform-apple/src/lifecycle.fixtures.ts @@ -52,7 +52,6 @@ export function openInput(): OpenApplicationInput { prewarmRunnerBeforeOpen: false, enableTestIme: false, stateDir: '/tmp/agent-device-lifecycle-test', - runtimeHints: {}, execution: {}, }; } diff --git a/packages/platform-apple/src/lifecycle.ts b/packages/platform-apple/src/lifecycle.ts index abe7593755..3c4b0e5913 100644 --- a/packages/platform-apple/src/lifecycle.ts +++ b/packages/platform-apple/src/lifecycle.ts @@ -8,7 +8,6 @@ import { type OpenApplicationOutcome, type PrepareAppleRunnerInput, type PrepareAppleRunnerResult, - hasRuntimeTransportHintValues, } from '@agent-device/contracts/application-lifecycle-runtime'; import type { PlatformRuntimeHost } from '@agent-device/contracts/platform-runtime-operations'; import { @@ -257,22 +256,14 @@ async function applyAppleOpenRuntimeHints( localIosSimulator: boolean, timing: MutableOpenTiming, ): Promise { - if (!hasRuntimeTransportHintValues(input.runtimeHints)) return undefined; + const runtimeHints = input.runtimeHints; + if (!runtimeHints) return undefined; const startedAtMs = Date.now(); const devClientLaunchUrl = localIosSimulator ? await host.resolveDevClientLaunchUrl(binding.device, input) : undefined; if (!devClientLaunchUrl) { - if (!input.applyRuntimeHints) { - throw new AppError( - 'COMMAND_FAILED', - 'Runtime hint operation was not admitted for this open.', - { - reason: 'runtime-hints-operation-missing', - }, - ); - } - await input.applyRuntimeHints({ appId: input.appBundleId, values: input.runtimeHints }); + await runtimeHints.apply({ appId: input.appBundleId, values: runtimeHints.values }); } timing.runtimeHintsDurationMs = elapsed(startedAtMs); return devClientLaunchUrl; diff --git a/packages/provider-limrun/src/lifecycle.test.ts b/packages/provider-limrun/src/lifecycle.test.ts index 2e03de1690..95a2eaa085 100644 --- a/packages/provider-limrun/src/lifecycle.test.ts +++ b/packages/provider-limrun/src/lifecycle.test.ts @@ -283,7 +283,6 @@ test('a live Limrun lifecycle binding relaunches with its selected provider inte prewarmRunnerBeforeOpen: false, enableTestIme: false, stateDir: '/state', - runtimeHints: {}, execution: {}, }); expect(providerClose).not.toHaveBeenCalled(); diff --git a/packages/provider-revyl/src/interactor.test.ts b/packages/provider-revyl/src/interactor.test.ts index b92b68bcf4..4cb4ba3717 100644 --- a/packages/provider-revyl/src/interactor.test.ts +++ b/packages/provider-revyl/src/interactor.test.ts @@ -753,7 +753,6 @@ function relaunchInput(app: string) { prewarmRunnerBeforeOpen: false, enableTestIme: false, stateDir: '/tmp', - runtimeHints: {}, execution: { requestId: 'request-1' }, }; } diff --git a/src/core/interactors/limrun-ios-files.test.ts b/src/core/interactors/limrun-ios-files.test.ts index d676b69a31..bb2e7410ea 100644 --- a/src/core/interactors/limrun-ios-files.test.ts +++ b/src/core/interactors/limrun-ios-files.test.ts @@ -162,9 +162,11 @@ test('binary installed metadata uses shared Expo launch hints and explicit URL p prewarmRunnerBeforeOpen: false, enableTestIme: false, stateDir: f.directory, - runtimeHints: { metroHost: 'localhost', metroPort: '8081' }, + runtimeHints: { + values: { metroHost: 'localhost', metroPort: '8081' }, + apply: async () => {}, + }, execution: {}, - applyRuntimeHints: async () => {}, }; expect(await lifecycle.openApplication(input)).toMatchObject({ appBundleId: 'com.example.app' }); expect(vi.mocked(f.session.client.simctl).mock.calls.map(([args]) => args)).toContainEqual([ From c7f36a9cb97e9479b702528da86072ad6b96fe74 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Thu, 19 Nov 2026 19:25:51 +0100 Subject: [PATCH 2/2] fix(daemon): refuse unpaired transport hints at the builder, honest dispatch disclosure Review follow-ups on the runtime-hints pairing: - openApplicationRuntimeHints now refuses transport hints without the fact-admitted apply operation as a caller bug (dispatched: 'no', thrown while building the open input, before any dispatch) instead of silently dropping the request one layer up. - The clear-hints refusal in session-open-prepare now discloses dispatched: 'unknown': prepareApplicationOpen above may already have booted the device, a device-reaching step, so 'no' would overstate. - lifecycle-expo-dev-client.test passes the { values, apply } pair directly per case instead of re-declaring the producer rule inline. Generated by Mistral Vibe. Co-Authored-By: Mistral Vibe --- .../__tests__/session-runtime.test.ts | 31 +++++++++++++++- .../internal/session-open-prepare.ts | 7 ++-- .../daemon/src/sessions/session-runtime.ts | 12 +++++-- .../src/lifecycle-expo-dev-client.test.ts | 36 ++++++++++--------- 4 files changed, 64 insertions(+), 22 deletions(-) diff --git a/packages/daemon/src/sessions/__tests__/session-runtime.test.ts b/packages/daemon/src/sessions/__tests__/session-runtime.test.ts index 2435bf51bd..a7752a6da3 100644 --- a/packages/daemon/src/sessions/__tests__/session-runtime.test.ts +++ b/packages/daemon/src/sessions/__tests__/session-runtime.test.ts @@ -1,6 +1,10 @@ import { expect, test } from 'vitest'; import { daemonRuntimeSchema } from '@agent-device/kernel/contracts'; -import { resolveEffectiveOpenRuntimeHints, toRuntimePlatform } from '../session-runtime.ts'; +import { + openApplicationRuntimeHints, + resolveEffectiveOpenRuntimeHints, + toRuntimePlatform, +} from '../session-runtime.ts'; test.each(['ios', 'android', 'harmonyos'] as const)( '%s runtime survives wire admission and open normalization', @@ -29,3 +33,28 @@ test('non-leaf apple selector is not a runtime platform', () => { expect(toRuntimePlatform('apple')).toBeUndefined(); expect(() => daemonRuntimeSchema.parse({ platform: 'apple' })).toThrow(); }); + +test('openApplicationRuntimeHints pairs transport hints with the admitted apply operation', () => { + const apply = async () => {}; + expect(openApplicationRuntimeHints({ metroHost: '10.0.2.2', metroPort: 8081 }, apply)).toEqual({ + values: { metroHost: '10.0.2.2', metroPort: '8081' }, + apply, + }); +}); + +test('openApplicationRuntimeHints is absent without transport hints, even when apply is missing', () => { + expect(openApplicationRuntimeHints({ launchUrl: 'demo://open' }, undefined)).toBeUndefined(); + expect(openApplicationRuntimeHints(undefined, undefined)).toBeUndefined(); +}); + +test('openApplicationRuntimeHints refuses transport hints without apply as an undispatched caller bug', () => { + let caught: unknown; + try { + openApplicationRuntimeHints({ metroHost: '10.0.2.2', metroPort: 8081 }, undefined); + } catch (error) { + caught = error; + } + expect(caught).toMatchObject({ + details: { reason: 'runtime-hints-operation-missing', dispatched: 'no' }, + }); +}); diff --git a/packages/daemon/src/sessions/session-lifecycle/internal/session-open-prepare.ts b/packages/daemon/src/sessions/session-lifecycle/internal/session-open-prepare.ts index ae4ac0f2d0..742759e358 100644 --- a/packages/daemon/src/sessions/session-lifecycle/internal/session-open-prepare.ts +++ b/packages/daemon/src/sessions/session-lifecycle/internal/session-open-prepare.ts @@ -186,14 +186,15 @@ export async function prepareOpenCommandDetails(params: { }); if (runtimeHintPlan.clearRemovedRuntimeHints) { if (!clearRuntimeHints) { - // Refused before the clear runs, and preparation precedes the open dispatch, so no - // native effect has happened yet. + // prepareApplicationOpen above may already have booted the device — a device-reaching + // step of this operation — so the disclosure is 'unknown', not 'no' ('no' holds only + // while no step was dispatched). throw new AppError( 'COMMAND_FAILED', 'Runtime hint clear operation was not admitted for this open.', { reason: 'runtime-hints-operation-missing', - dispatched: 'no', + dispatched: 'unknown', }, ); } diff --git a/packages/daemon/src/sessions/session-runtime.ts b/packages/daemon/src/sessions/session-runtime.ts index 141b57557e..794b52fb8b 100644 --- a/packages/daemon/src/sessions/session-runtime.ts +++ b/packages/daemon/src/sessions/session-runtime.ts @@ -59,13 +59,21 @@ export function hasRuntimeTransportHints(runtime: SessionRuntimeHints | undefine /** * Pairs the open's requested transport hints with the fact-admitted apply operation, so the * lifecycle input cannot carry a hints request without its transport. Absent when the open - * requests no transport hint; facts admission guarantees the operation whenever it is requested. + * requests no transport hint. Transport hints without the admitted operation are a caller bug: + * the builder refuses them here, before any dispatch, so `dispatched: 'no'` holds. */ export function openApplicationRuntimeHints( runtime: SessionRuntimeHints | undefined, apply: ((input: RuntimeHintsApplicationInput) => Promise) | undefined, ): OpenApplicationRuntimeHints | undefined { - if (apply === undefined || !hasRuntimeTransportHints(runtime)) return undefined; + if (!hasRuntimeTransportHints(runtime)) return undefined; + if (apply === undefined) { + throw new AppError( + 'COMMAND_FAILED', + 'Transport runtime hints were requested without the fact-admitted apply operation; pair the hints with the operation or drop them.', + { reason: 'runtime-hints-operation-missing', dispatched: 'no' }, + ); + } return { values: runtimeHintValues(runtime), apply }; } diff --git a/packages/platform-apple/src/lifecycle-expo-dev-client.test.ts b/packages/platform-apple/src/lifecycle-expo-dev-client.test.ts index 43a411c187..160b6a6680 100644 --- a/packages/platform-apple/src/lifecycle-expo-dev-client.test.ts +++ b/packages/platform-apple/src/lifecycle-expo-dev-client.test.ts @@ -1,8 +1,4 @@ import { beforeEach, expect, test, vi } from 'vitest'; -import { - type OpenApplicationRuntimeHints, - hasRuntimeTransportHintValues, -} from '@agent-device/contracts/application-lifecycle-runtime'; import { alertNotFound } from './launch-confirmation.fixtures.ts'; import { launchUrlSimulator, openInput, resetUrlOwner } from './lifecycle.fixtures.ts'; @@ -15,39 +11,47 @@ vi.mock('./core/app-resolution.ts', async () => { }); const devClientLaunch = vi.hoisted(() => vi.fn<() => Promise>()); +const applyRuntimeHints = vi.hoisted(() => vi.fn(async () => {})); vi.mock('./expo-dev-client-launch.ts', () => ({ resolveExpoDevClientLaunchUrl: devClientLaunch })); beforeEach(() => { resetUrlOwner(); devClientLaunch.mockReset(); + applyRuntimeHints.mockReset(); }); const DEV_CLIENT_URL = 'exp+dev-slug://expo-development-client/?url=http%3A%2F%2F127.0.0.1%3A8085'; const METRO_HINTS = { metroHost: '127.0.0.1', metroPort: '8085' }; test.each([ - ['Expo development build', DEV_CLIENT_URL, METRO_HINTS, `open ${DEV_CLIENT_URL}`, 0, 1], - ['bare React Native app', undefined, METRO_HINTS, 'open', 1, 1], - ['app without Metro hints', DEV_CLIENT_URL, {}, 'open', 0, 0], + [ + 'Expo development build', + DEV_CLIENT_URL, + { values: METRO_HINTS, apply: applyRuntimeHints }, + `open ${DEV_CLIENT_URL}`, + 0, + 1, + ], + [ + 'bare React Native app', + undefined, + { values: METRO_HINTS, apply: applyRuntimeHints }, + 'open', + 1, + 1, + ], + ['app without Metro hints', DEV_CLIENT_URL, undefined, 'open', 0, 0], ] as const)( '%s opens through the appropriate route', async (_, url, runtimeHints, event, prefs, probes) => { devClientLaunch.mockResolvedValue(url); - const applyRuntimeHints = vi.fn(async () => {}); const { lifecycle, events } = launchUrlSimulator(async () => { throw alertNotFound(); }); - // The daemon producer pairs the values with the apply operation only when a transport - // hint is requested, so this mirrors that rule. - const hints: OpenApplicationRuntimeHints | undefined = hasRuntimeTransportHintValues( - runtimeHints, - ) - ? { values: runtimeHints, apply: applyRuntimeHints } - : undefined; await lifecycle.openApplication({ ...openInput(), - runtimeHints: hints, + runtimeHints, execution: { plannedOperations: ['captureSnapshot'] }, });