diff --git a/.changeset/remove-managed-client-lifecycle.md b/.changeset/remove-managed-client-lifecycle.md new file mode 100644 index 0000000000..8e67fa56e4 --- /dev/null +++ b/.changeset/remove-managed-client-lifecycle.md @@ -0,0 +1,5 @@ +--- +'agent-device': minor +--- + +Clients attach to an existing daemon and no longer start, replace, or retire it on timeout. This also applies to `client.replay.run()` and `client.replay.test()`; they no longer start a private daemon. Remove `daemonLifecycle: 'managed'` and call `ensureDaemon({ stateDir })` before creating a client for a detached daemon. To own a daemon in your process, call `startAgentDevice({ stateDir })` from `agent-device` and close its returned handle. CLI and MCP commands continue to ensure their daemon, including private one-shot replay/test startup and cleanup. diff --git a/README.md b/README.md index 17c0c4a8f7..b60a0acdfc 100644 --- a/README.md +++ b/README.md @@ -101,8 +101,9 @@ See [AI agent setup](https://agent-device.dev/docs/agent-setup) for per-client s `createAgentDeviceClient()` gives Node.js code typed access to the same commands, as model tools in your own agent or from orchestration code: ```ts -import { createAgentDeviceClient } from 'agent-device'; +import { createAgentDeviceClient, ensureDaemon, isAgentDeviceError } from 'agent-device'; +await ensureDaemon(); const client = createAgentDeviceClient({ session: 'qa-run' }); try { await client.apps.open({ app: 'com.apple.Preferences', platform: 'ios' }); @@ -110,7 +111,11 @@ try { const button = snapshot.nodes.find((node) => node.role === 'button'); if (button) await client.interactions.press({ ref: button.ref }); } finally { - await client.sessions.close(); + await client.sessions.close().catch((error) => { + if (isAgentDeviceError(error) && error.code === 'SESSION_NOT_FOUND') return; + console.error('Session cleanup failed:', error); + process.exitCode = 1; + }); } ``` diff --git a/docs/adr/0034-provider-plugin-registry.md b/docs/adr/0034-provider-plugin-registry.md index 21dec648cb..cee6b4a8f4 100644 --- a/docs/adr/0034-provider-plugin-registry.md +++ b/docs/adr/0034-provider-plugin-registry.md @@ -59,11 +59,11 @@ had to fake the store to load a plugin from its own dependencies (#3747). ## Daemon ownership -Clients retain managed and attach lifecycles. Managed clients may start a daemon; attach clients cannot start or replace one. An embedder calls `startAgentDevice({ stateDir, plugins?, host? })` from `agent-device` to own a runtime in its process. The main entry loads the runtime when called. The returned client and serializable `clientConfig` identify that exact instance. Attaching checks normal version and code compatibility before checking the instance pin. `close()` in the host process is the only way to shut an embedded runtime down, and returns its `ShutdownReport`. `daemon stop` refuses live embedded ownership with `daemon-owner-embedded` and live unrecognized ownership with `daemon-owner-unrecognized`, without a request or signal. The embedded-ownership refusal names the host PID and directs the caller to close the runtime there. Stop may retire an embedded or unrecognized registration when its recorded host lifetime has provably exited. The CLI cannot replace a live embedded runtime. Registration and its lock remain held while requests or platform owners are unfinished. +Clients attach to an existing daemon and cannot start or replace one. Call `ensureDaemon()` to start or replace a detached daemon explicitly. An embedder calls `startAgentDevice({ stateDir, plugins?, host? })` from `agent-device` to own a runtime in its process. The main entry loads the runtime when called. The returned client and serializable `clientConfig` identify that exact instance. Attaching checks normal version and code compatibility before checking the instance pin. `close()` in the host process is the only way to shut an embedded runtime down, and returns its `ShutdownReport`. `daemon stop` refuses live embedded ownership with `daemon-owner-embedded` and live unrecognized ownership with `daemon-owner-unrecognized`, without a request or signal. The embedded-ownership refusal names the host PID and directs the caller to close the runtime there. Stop may retire an embedded or unrecognized registration when its recorded host lifetime has provably exited. The CLI cannot replace a live embedded runtime. Registration and its lock remain held while requests or platform owners are unfinished. The embedder supplies plugin objects directly. They follow the built-ins through the same registry validation; this runtime does not read the plugin store. Plugin failures remain inventory data. Logging adapters, a separate package entry, and disposal protocols are not required to own a daemon: the library exposes the client, its attach configuration, and `close()`. -Decision history: owner-only close replaces external embedded shutdown so the CLI cannot end work its host owns; a proven host exit permits registration retirement. The former explicit-start target is dropped; the client lifecycle continues to choose startup behavior. The main-entry API replaces the proposed host subpath and optional host controls, keeping ownership and attachment on the existing runtime and client paths (#3757). +Decision history: owner-only close replaces external embedded shutdown so the CLI cannot end work its host owns; a proven host exit permits registration retirement. The former client-managed startup path was removed in 0.22; explicit ensuring keeps daemon replacement separate from attachment (#3759). The main-entry API replaces the proposed host subpath and optional host controls, keeping ownership and attachment on the existing runtime and client paths (#3757). ## Alternatives refused diff --git a/examples/sdk/client-session.ts b/examples/sdk/client-session.ts index d1a3f9261a..c8924b9f66 100644 --- a/examples/sdk/client-session.ts +++ b/examples/sdk/client-session.ts @@ -3,7 +3,7 @@ * a node, then close the session — with typed error handling via the * exported error helpers. * - * Demonstrates: `createAgentDeviceClient`, `AppError`, `isAgentDeviceError`, + * Demonstrates: `ensureDaemon`, `createAgentDeviceClient`, `AppError`, `isAgentDeviceError`, * and `normalizeAgentDeviceError` from the `agent-device` root export. * * Prerequisites: an `agent-device` daemon target (a booted iOS simulator). @@ -15,6 +15,7 @@ import { AppError, createAgentDeviceClient, + ensureDaemon, isAgentDeviceError, normalizeAgentDeviceError, } from 'agent-device'; @@ -47,6 +48,13 @@ function reportAgentDeviceError(error: unknown): void { } async function main(): Promise { + try { + await ensureDaemon(); + } catch (error) { + if (!isAgentDeviceError(error)) throw error; + reportAgentDeviceError(error); + return; + } const client = createAgentDeviceClient({ session: 'sdk-example', lockPolicy: 'reject', @@ -72,7 +80,13 @@ async function main(): Promise { if (!isAgentDeviceError(error)) throw error; reportAgentDeviceError(error); } finally { - await client.sessions.close(); + try { + await client.sessions.close(); + } catch (error) { + if (!isAgentDeviceError(error) || error.code !== 'SESSION_NOT_FOUND') { + reportAgentDeviceError(error); + } + } } } diff --git a/examples/sdk/contracts-result.ts b/examples/sdk/contracts-result.ts index ef3d28594a..7590ed379b 100644 --- a/examples/sdk/contracts-result.ts +++ b/examples/sdk/contracts-result.ts @@ -6,7 +6,8 @@ * Demonstrates: `centerOfRect` from `agent-device/contracts`, consumed * against the `CaptureSnapshotResult` shape returned by the root client. * - * Prerequisites: an `agent-device` daemon target with an app already open. + * Prerequisites: call `ensureDaemon()` to start the daemon, then open an app + * in the `sdk-example` session. * This file typechecks without one. * * Run: node --experimental-strip-types examples/sdk/contracts-result.ts diff --git a/packages/client/src/__tests__/index-daemon-lifecycle.test.ts b/packages/client/src/__tests__/index-daemon-lifecycle.test.ts index 9709f0c837..339fd03b4c 100644 --- a/packages/client/src/__tests__/index-daemon-lifecycle.test.ts +++ b/packages/client/src/__tests__/index-daemon-lifecycle.test.ts @@ -1,47 +1,57 @@ import { test } from 'vitest'; import assert from 'node:assert/strict'; -import type { - AgentDeviceDaemonTransport, - AgentDeviceDaemonTransportContext, - DaemonLifecycle, -} from '@agent-device/contracts/client'; +import type { AgentDeviceDaemonTransport } from '@agent-device/contracts/client'; import { createAgentDeviceClient } from '../index.ts'; -// `daemonLifecycle` is a client choice that only the transport can act on, so the client's job is to -// hand it over exactly and to refuse a value it does not know. +// A client always attaches, so `daemonLifecycle` is no longer a choice the transport acts on. The +// client's job is to accept `'attach'` (the only value, and the default) and to refuse any value that +// would mean managing a daemon, naming the explicit owners instead. function recordingTransport() { - const contexts: Array = []; + const seen: Array> = []; const transport: AgentDeviceDaemonTransport = async (_request, context) => { - contexts.push(context); + seen.push({ ...(context ?? {}) }); return { ok: true, data: { devices: [] } }; }; - return { contexts, transport }; + return { seen, transport }; } -test('the configured daemon lifecycle reaches the transport', async () => { - const { contexts, transport } = recordingTransport(); +test('a client sends no daemon-management knob to its transport', async () => { + const { seen, transport } = recordingTransport(); const attached = createAgentDeviceClient({ daemonLifecycle: 'attach' }, { transport }); const plain = createAgentDeviceClient({}, { transport }); - const managed = createAgentDeviceClient({ daemonLifecycle: 'managed' }, { transport }); - await attached.devices.list(); - await managed.devices.list(); await plain.devices.list(); + // `'attach'` is what every request does, so it is not a per-request option either: the transport + // gets the caller's cancellation and pin, and nothing about who owns the daemon. assert.deepEqual( - contexts.map((context) => context?.daemonLifecycle), - ['attach', 'managed', undefined], + seen.map((context) => 'daemonLifecycle' in context), + [false, false], + ); +}); + +test('the removed managed lifecycle is refused where the config is read', () => { + const { transport } = recordingTransport(); + + assert.throws( + () => createAgentDeviceClient({ daemonLifecycle: 'managed' as never }, { transport }), + (error: { code?: string; details?: { daemonLifecycle?: unknown; hint?: unknown } }) => { + assert.equal(error.code, 'INVALID_ARGS'); + assert.equal(error.details?.daemonLifecycle, 'managed'); + assert.match(String(error.details?.hint), /ensureDaemon\(\{ stateDir \}\)/); + assert.match(String(error.details?.hint), /startAgentDevice\(\{ stateDir \}\)/); + return true; + }, ); }); -test('an unknown daemon lifecycle is refused instead of becoming managed', () => { +test('an unknown daemon lifecycle is refused instead of attaching blindly', () => { const { transport } = recordingTransport(); - const mistyped = 'Attach' as DaemonLifecycle; assert.throws( - () => createAgentDeviceClient({ daemonLifecycle: mistyped }, { transport }), + () => createAgentDeviceClient({ daemonLifecycle: 'Attach' as never }, { transport }), (error: { code?: string }) => error.code === 'INVALID_ARGS', ); }); diff --git a/packages/client/src/index.ts b/packages/client/src/index.ts index bbcf23f54b..1da8a8fa9f 100644 --- a/packages/client/src/index.ts +++ b/packages/client/src/index.ts @@ -166,7 +166,6 @@ export function createAgentDeviceClient( await transport(request, { authToken: merged.daemonAuthToken, signal: merged.signal, - daemonLifecycle: merged.daemonLifecycle, ...(daemonBinding ? { daemonBinding } : {}), }), ); @@ -632,10 +631,17 @@ function optionalSnapshotResponseFields( } function readDaemonLifecycle(value: unknown): DaemonLifecycle | undefined { - if (value === undefined || value === 'attach' || value === 'managed') return value; - throw new AppError('INVALID_ARGS', "daemonLifecycle must be 'attach' or 'managed'.", { - daemonLifecycle: value, - }); + if (value === undefined || value === 'attach') return value; + throw new AppError( + 'INVALID_ARGS', + value === 'managed' + ? "daemonLifecycle must be 'attach'. The 'managed' lifecycle was removed in 0.22." + : "daemonLifecycle must be 'attach'.", + { + daemonLifecycle: value, + hint: "Drop daemonLifecycle, or set it to 'attach'. To start or replace a detached daemon, call ensureDaemon({ stateDir }). To own one in this process, call startAgentDevice({ stateDir }) from 'agent-device'.", + }, + ); } /** diff --git a/packages/contracts/src/client-connection.ts b/packages/contracts/src/client-connection.ts index 96bb4a55c9..19577ab673 100644 --- a/packages/contracts/src/client-connection.ts +++ b/packages/contracts/src/client-connection.ts @@ -18,19 +18,20 @@ import type { } from './remote-config-fields.ts'; /** - * Who owns the daemon on a client's state directory. + * The one daemon lifecycle a client config selects: `attach`. The transport connects to its registered + * daemon without starting, replacing, retiring or timeout-killing it, including replay/test calls. + * CLI/MCP can own a private daemon for one-shot replay/test; library client calls cannot. + * A missing daemon fails with `details.reason: 'daemon-not-running'`; an incompatible one uses + * `'daemon-incompatible'`. * - * - `managed`: the client starts a missing daemon and replaces an incompatible one itself, and may - * retire a hung one after a timeout. This is the default until 0.22. - * - `attach`: the client only connects to the daemon registered in the state directory. It never - * starts, replaces or kills one. A missing daemon fails with `details.reason: 'daemon-not-running'` - * and an incompatible one with `'daemon-incompatible'`; `ensureDaemon()` is the explicit way to - * start or replace one. + * `ensureDaemon()` is the explicit way to start or replace a detached daemon. `startAgentDevice()` + * imported from `agent-device` owns one in your process and refuses an already registered state + * directory. `ensureDaemon()` refuses to replace a daemon that holds another client's work. * - * Independent of `daemonTransport`, `daemonServerMode` and `daemonBaseUrl`: a remote connection - * never starts or retires a local daemon in either mode. + * Independent of `daemonTransport`, `daemonServerMode` and `daemonBaseUrl`: a remote connection never + * starts or retires a local daemon. */ -export type DaemonLifecycle = 'attach' | 'managed'; +export type DaemonLifecycle = 'attach'; /** What a client can learn about a daemon without talking to it: how it identifies itself on disk. */ export type DaemonIdentity = { @@ -89,8 +90,6 @@ export type DaemonConnection = { export type AgentDeviceDaemonTransportContext = { authToken?: string; - /** How this request treats the local daemon; `managed` when omitted. */ - daemonLifecycle?: DaemonLifecycle; /** See {@link DaemonBinding}. A client built with one sends this same pin on every request. */ daemonBinding?: DaemonBinding; /** @@ -109,7 +108,10 @@ export type AgentDeviceDaemonTransport = ( export type AgentDeviceClientConfig = RemoteConnectionProfileFields & CloudProviderProfileFields & { - /** See `DaemonLifecycle`. */ + /** + * See `DaemonLifecycle`. Only `'attach'` is accepted, and it is the default; the removed + * `'managed'` value fails validation instead of starting a daemon. + */ daemonLifecycle?: DaemonLifecycle; /** * Pins this client to one daemon instance: every request addresses that instance, authenticates @@ -191,10 +193,9 @@ export type AgentDeviceRequestOverrides = Pick< * daemon reset. * * The guarantee covers the daemon request, and the built-in transports enforce it; a custom - * transport receives the signal on its context and may implement cancellation differently. Two - * phases run outside it: a response-artifact download started after the response begins is not - * canceled, and a canceled one-shot replay still runs the existing cleanup that may tear down a - * daemon this client started. + * transport receives the signal on its context and may implement cancellation differently. One + * phase runs outside it: a response-artifact download started after the response begins is not + * canceled. */ signal?: AbortSignal; }; diff --git a/packages/daemon-client/src/__tests__/daemon-client-ensure-explicit-lifecycle.test.ts b/packages/daemon-client/src/__tests__/daemon-client-ensure-explicit-lifecycle.test.ts index 94985b11b5..63a780e0c5 100644 --- a/packages/daemon-client/src/__tests__/daemon-client-ensure-explicit-lifecycle.test.ts +++ b/packages/daemon-client/src/__tests__/daemon-client-ensure-explicit-lifecycle.test.ts @@ -99,7 +99,7 @@ test('attach reports a missing daemon without starting one', async (t) => { if (!(await withLoopback(t))) return; const { stateDir, paths } = stateDirAndPaths(); - const error = await failureOf(sendToDaemon(request(stateDir), { daemonLifecycle: 'attach' })); + const error = await failureOf(sendToDaemon(request(stateDir))); assert.equal(error.details?.reason, 'daemon-not-running'); assert.match(String(error.details?.hint), /agent-device devices --state-dir /); @@ -118,7 +118,7 @@ test('attach reports an incompatible daemon with both identities and leaves it r }); try { - const error = await failureOf(sendToDaemon(request(stateDir), { daemonLifecycle: 'attach' })); + const error = await failureOf(sendToDaemon(request(stateDir))); assert.equal(error.details?.reason, 'daemon-incompatible'); assert.equal(identityIn(error, 'daemon').version, '0.0.0-stale'); @@ -141,7 +141,7 @@ for (const ownership of ['detached', 'embedded'] as const) await closeLoopbackServer(closed.server); const { child } = await registerDaemon(paths, { httpPort: closed.port, ownership }); - const error = await failureOf(sendToDaemon(request(stateDir), { daemonLifecycle: 'attach' })); + const error = await failureOf(sendToDaemon(request(stateDir))); assert.equal(error.details?.reason, 'daemon-not-running'); assert.equal(identityIn(error, 'daemon').pid, child.pid); @@ -163,29 +163,29 @@ test('attach uses a compatible daemon and never lets a timeout retire it', async const send = vi.spyOn(transport, 'sendRequest'); try { - const response = await sendToDaemon(request(stateDir), { daemonLifecycle: 'attach' }); + const response = await sendToDaemon(request(stateDir)); assert.deepEqual(response, { ok: true, data: { via: 'live' } }); assert.equal(send.mock.calls.at(-1)?.[5]?.timeoutRecovery, 'none'); + // The removed per-request lifecycle knob cannot resurrect the old kill path: an omitted context + // attaches too, and still may not retire the daemon on a timeout. await sendToDaemon(request(stateDir)); - assert.equal(send.mock.calls.at(-1)?.[5]?.timeoutRecovery, 'retire-unresponsive'); + assert.equal(send.mock.calls.at(-1)?.[5]?.timeoutRecovery, 'none'); assert.equal(spawn.mock.calls.length, 0); } finally { await closeLoopbackServer(live.server); } }); -test('a remote connection never starts a local daemon in either lifecycle', async (t) => { +test('a remote connection never starts a local daemon', async (t) => { if (!(await withLoopback(t))) return; const { stateDir } = stateDirAndPaths(); const unreachable = await startScriptedDaemon(okResult({})); await closeLoopbackServer(unreachable.server); const remote = { daemonBaseUrl: `http://127.0.0.1:${unreachable.port}` }; - for (const daemonLifecycle of ['attach', 'managed'] as const) { - const error = await failureOf(sendToDaemon(request(stateDir, remote), { daemonLifecycle })); - assert.match(error.message, /Remote daemon is unavailable/); - } + const error = await failureOf(sendToDaemon(request(stateDir, remote))); + assert.match(error.message, /Remote daemon is unavailable/); assert.equal(spawn.mock.calls.length, 0); }); @@ -508,9 +508,7 @@ test('a live daemon on another transport is left alone when it cannot be asked t assert.equal(ensured.details?.reason, 'daemon-incompatible'); assert.equal(ensured.details?.mismatch, 'no-quiesce'); - const attached = await failureOf( - sendToDaemon(request(stateDir), { daemonLifecycle: 'attach' }), - ); + const attached = await failureOf(sendToDaemon(request(stateDir))); assert.equal(attached.details?.reason, 'daemon-incompatible'); assert.equal(attached.details?.mismatch, 'transport'); @@ -688,9 +686,7 @@ test('a registration whose process is gone is not running, whatever version it n ); try { - const attached = await failureOf( - sendToDaemon(request(stateDir), { daemonLifecycle: 'attach' }), - ); + const attached = await failureOf(sendToDaemon(request(stateDir))); assert.equal(attached.details?.reason, 'daemon-not-running'); // ensureDaemon replaces the dead registration without asking anyone to leave. diff --git a/packages/daemon-client/src/__tests__/daemon-client-ensuring.test.ts b/packages/daemon-client/src/__tests__/daemon-client-ensuring.test.ts index 53de2dc63c..b63a28422f 100644 --- a/packages/daemon-client/src/__tests__/daemon-client-ensuring.test.ts +++ b/packages/daemon-client/src/__tests__/daemon-client-ensuring.test.ts @@ -31,8 +31,9 @@ import { createEnsuredDaemonTransport, type sendToDaemon } from '../index.ts'; import * as ensureModule from '../daemon-client-ensure.ts'; // The CLI and MCP reach the daemon through `withEnsuredDaemon`. The transport underneath is a -// recorder, so what these tests read is the lifecycle each request was handed and what ensuring -// did to the state directory before it. +// recorder, so what these tests read is the context each request was handed — which ensuring passes +// through unchanged, since every request attaches — and what ensuring did to the state directory +// before it. const spawn = vi.mocked(runCmdDetachedMonitored); @@ -44,9 +45,13 @@ afterEach(async () => { }); function recordingTransport() { - const sent: Array<{ command: string; lifecycle: string | undefined }> = []; + const sent: Array<{ + command: string; + /** The exact context object the caller passed, proving ensuring hands it over unchanged. */ + context: unknown; + }> = []; const transport: typeof sendToDaemon = async (req, context) => { - sent.push({ command: req.command, lifecycle: context?.daemonLifecycle }); + sent.push({ command: req.command, context }); return { ok: true, data: {} }; }; return { sent, transport }; @@ -74,8 +79,8 @@ test('the first request ensures a missing daemon once and every request attaches assert.equal(spawn.mock.calls.length, 1); assert.deepEqual(sent, [ - { command: 'devices', lifecycle: 'attach' }, - { command: 'snapshot', lifecycle: 'attach' }, + { command: 'devices', context: undefined }, + { command: 'snapshot', context: undefined }, ]); } finally { await closeLoopbackServer(fresh.server); @@ -108,7 +113,7 @@ test('an idle incompatible daemon is replaced, and the replacement is reported', assert.deepEqual(replaced, [ { stateDir: paths.baseDir, pid: child.pid, reason: 'incompatible' }, ]); - assert.equal(sent[0]?.lifecycle, 'attach'); + assert.deepEqual(sent[0]?.context, undefined, 'ensuring hands the caller context through'); assert.deepEqual(leaver.clientSignals, [], 'the client signaled nothing'); } finally { await closeLoopbackServer(stale.server); @@ -146,7 +151,7 @@ test('a busy incompatible daemon fails the request before it is sent and keeps r } }); -test('a remote connection passes through without ensuring or choosing a lifecycle', async () => { +test('a remote connection passes through untouched by ensuring', async () => { const { stateDir } = stateDirAndPaths(); const { sent, transport } = recordingTransport(); const ensuring = withEnsuredDaemon(transport); @@ -156,8 +161,8 @@ test('a remote connection passes through without ensuring or choosing a lifecycl await ensuring(request('snapshot', { stateDir })); assert.deepEqual(sent, [ - { command: 'devices', lifecycle: undefined }, - { command: 'snapshot', lifecycle: undefined }, + { command: 'devices', context: undefined }, + { command: 'snapshot', context: undefined }, ]); assert.equal(spawn.mock.calls.length, 0); }); @@ -172,11 +177,11 @@ test('a one-shot replay on its own private daemon passes through, an explicit st try { await ensuring(request('replay', { daemonTransport: 'http' })); - assert.deepEqual(sent, [{ command: 'replay', lifecycle: undefined }]); + assert.deepEqual(sent, [{ command: 'replay', context: undefined }]); assert.equal(spawn.mock.calls.length, 0); await ensuring(request('replay', { stateDir, daemonTransport: 'http' })); - assert.equal(sent[1]?.lifecycle, 'attach'); + assert.equal(sent[1]?.command, 'replay'); assert.equal(spawn.mock.calls.length, 1); } finally { await closeLoopbackServer(fresh.server); @@ -270,7 +275,7 @@ test('a failed ensure is retried by the next request instead of being remembered launchesFreshDaemonAt(spawn, paths, fresh.port); await ensuring(request('devices', flags)); - assert.deepEqual(sent, [{ command: 'devices', lifecycle: 'attach' }]); + assert.deepEqual(sent, [{ command: 'devices', context: undefined }]); } finally { await closeLoopbackServer(stale.server); await closeLoopbackServer(fresh.server); @@ -323,10 +328,13 @@ test('a request canceled before it starts does not start a daemon', async (t) => const canceled = AbortSignal.abort(); try { - await ensuring(request('devices', { stateDir, daemonTransport: 'http' }), { signal: canceled }); + const signal = { signal: canceled } as const; + await ensuring(request('devices', { stateDir, daemonTransport: 'http' }), signal); - assert.equal(spawn.mock.calls.length, 0); - assert.deepEqual(sent, [{ command: 'devices', lifecycle: 'attach' }]); + assert.equal(spawn.mock.calls.length, 0, 'a caller that has given up starts nothing'); + assert.equal(sent.length, 1); + assert.equal(sent[0]?.command, 'devices'); + assert.strictEqual(sent[0]?.context, signal); } finally { await closeLoopbackServer(fresh.server); } diff --git a/packages/daemon-client/src/__tests__/daemon-client-lease-beat.test.ts b/packages/daemon-client/src/__tests__/daemon-client-lease-beat.test.ts index 9c57045dfd..8ef0e9d438 100644 --- a/packages/daemon-client/src/__tests__/daemon-client-lease-beat.test.ts +++ b/packages/daemon-client/src/__tests__/daemon-client-lease-beat.test.ts @@ -604,7 +604,6 @@ describe('buildUploadLeaseHeartbeat', () => { host: { env: process.env, cwd: process.cwd() }, paths: resolveDaemonPaths('/tmp/agent-device-upload-lease'), transportPreference: 'socket' as const, - daemonLifecycle: 'managed' as const, retireIncompatibleContender: true, serverMode: 'socket' as const, }; diff --git a/packages/daemon-client/src/__tests__/daemon-client-lifecycle-embedded.test.ts b/packages/daemon-client/src/__tests__/daemon-client-lifecycle-embedded.test.ts index 1e896dd48f..b689943598 100644 --- a/packages/daemon-client/src/__tests__/daemon-client-lifecycle-embedded.test.ts +++ b/packages/daemon-client/src/__tests__/daemon-client-lifecycle-embedded.test.ts @@ -33,7 +33,11 @@ vi.mock('@agent-device/host-kit/command', async (importOriginal) => ({ })); import { runCmdDetachedMonitored } from '@agent-device/host-kit/command'; import { createDaemonTransport, type sendToDaemon } from '../index.ts'; -import { resolveClientSettings, resolveTimeoutRecovery } from '../daemon-client-lifecycle.ts'; +import { + resolveClientSettings, + resolveTimeoutRecovery, + ensureStartedDaemon, +} from '../daemon-client-lifecycle.ts'; const spawn = vi.mocked(runCmdDetachedMonitored); @@ -52,6 +56,16 @@ function request(stateDir: string) { } as Parameters[0]; } +async function ownerRequest(stateDir: string) { + const host = createTestHostEnvironment(); + const settings = { + ...resolveClientSettings(request(stateDir), undefined, host), + retireIncompatibleContender: true, + }; + await ensureStartedDaemon(settings); + return await createDaemonTransport(host)(request(stateDir)); +} + function pinTo(info: { token: string; pid: number; processStartTime?: string }): DaemonBinding { return { token: info.token, pid: info.pid, processStartTime: info.processStartTime ?? '' }; } @@ -161,9 +175,7 @@ for (const [ownership, reason, message, hint] of [ } const killSpy = vi.spyOn(process, 'kill'); try { - const refusal = await refusalFrom( - createDaemonTransport(createTestHostEnvironment())(request(stateDir)), - ); + const refusal = await refusalFrom(ownerRequest(stateDir)); assert.equal(refusal.details?.reason, reason); assert.equal(refusal.message, message); assert.match(String(refusal.details?.hint), hint); @@ -216,7 +228,7 @@ test('the same record with no host owner is still the takeover this client perfo try { assert.equal(metadata.readDaemonInfo(paths.infoPath)?.ownership, 'detached'); - const response = await createDaemonTransport(createTestHostEnvironment())(request(stateDir)); + const response = await ownerRequest(stateDir); assert.equal(response.ok, true); assert.equal(spawn.mock.calls.length, 1, 'the detached contender was replaced'); @@ -243,7 +255,7 @@ for (const ownership of ['embedded', 'unrecognized', 'detached'] as const) const killSpy = vi.spyOn(process, 'kill'); try { - const response = await createDaemonTransport(createTestHostEnvironment())(request(stateDir)); + const response = await ownerRequest(stateDir); assert.equal(response.ok, true, JSON.stringify(response)); assert.equal(spawn.mock.calls.length, 1, 'the state directory was taken over, not wedged'); @@ -259,26 +271,28 @@ for (const ownership of ['embedded', 'unrecognized', 'detached'] as const) } }); -test('timeout recovery asks only whether this client may, and attach never may', () => { - const { stateDir } = stateDirAndPaths(); - const managed = resolveClientSettings( - request(stateDir), - undefined, - createTestHostEnvironment(), - 'managed', - ); - const attach = resolveClientSettings( - request(stateDir), +test('ordinary requests never authorize timeout retirement', () => { + const settings = resolveClientSettings( + request(stateDirAndPaths().stateDir), undefined, createTestHostEnvironment(), - 'attach', ); - // Recovery is the retirement's judgement, so the client decides only whether it may ask at all: an - // attach client never does, and every other lifecycle asks. The retirement answers for the record's - // owner — a live embedded or unrecognized one is refused without a signal, which - // daemon-registration-embedded-owner.test.ts pins at that seam for both modes. - assert.equal(resolveTimeoutRecovery(managed), 'retire-unresponsive'); - assert.equal(resolveTimeoutRecovery(attach), 'none'); + assert.equal(resolveTimeoutRecovery(settings), 'none'); +}); + +test('a library replay without a state directory attaches instead of owning a private daemon', () => { + const host = createTestHostEnvironment(); + const replay = { session: 'default', command: 'replay', positionals: [], flags: {} }; + const attached = resolveClientSettings(replay, undefined, host); + const owned = resolveClientSettings(replay, undefined, host, undefined, true); + try { + assert.equal(attached.ownedStateDir, undefined); + assert.equal(resolveTimeoutRecovery(attached), 'none'); + assert.ok(owned.ownedStateDir); + assert.equal(resolveTimeoutRecovery(owned), 'retire-unresponsive'); + } finally { + if (owned.ownedStateDir) fs.rmSync(owned.paths.baseDir, { recursive: true, force: true }); + } }); test('a matching pin does not bypass attach compatibility checks', async (t) => { @@ -403,7 +417,6 @@ test('a client that pins a local daemon and names a base URL is refused where se { ...request(stateDirAndPaths().stateDir), flags: { daemonBaseUrl: remote } }, undefined, createTestHostEnvironment(), - 'managed', pin, ), ], @@ -415,7 +428,6 @@ test('a client that pins a local daemon and names a base URL is refused where se request(stateDirAndPaths().stateDir), undefined, createTestHostEnvironment({ env: { AGENT_DEVICE_DAEMON_BASE_URL: remote } }), - 'managed', pin, ), ], @@ -458,12 +470,10 @@ test('a pinned client keeps its hands off the state directory it was given', asy request(stateDir), undefined, createTestHostEnvironment(), - 'managed', pin, ); // A private state directory would hold a daemon nobody started, and a pinned client starts none. - assert.equal(settings.daemonLifecycle, 'attach'); assert.equal(settings.ownedStateDir, undefined); assert.deepEqual(settings.daemonBinding, pin); assert.equal(settings.paths.baseDir, paths.baseDir); diff --git a/packages/daemon-client/src/__tests__/daemon-client-lifecycle.test.ts b/packages/daemon-client/src/__tests__/daemon-client-lifecycle.test.ts index d2ad20bbf3..d54c376ce2 100644 --- a/packages/daemon-client/src/__tests__/daemon-client-lifecycle.test.ts +++ b/packages/daemon-client/src/__tests__/daemon-client-lifecycle.test.ts @@ -32,12 +32,24 @@ vi.mock('@agent-device/host-kit/retry', async (importOriginal) => ({ })); import { resolveDaemonPaths } from '@agent-device/daemon-contracts/daemon-resolution'; import type { DaemonPaths } from '@agent-device/daemon-contracts/daemon-resolution'; -import { sendToDaemon } from '../index.ts'; +import { sendToDaemon as attach, createEnsuredDaemonTransport } from '../index.ts'; +import { ensureStartedDaemon, resolveClientSettings } from '../daemon-client-lifecycle.ts'; +import { captureHostEnvironment, readProcessStartTime } from '@agent-device/host-kit/process'; + +const ensuredTransport = createEnsuredDaemonTransport(); +async function ensureAndSend(req: Parameters[0]) { + if (req.command === 'replay' || req.command === 'test') return await ensuredTransport(req); + const host = captureHostEnvironment(process); + await ensureStartedDaemon({ + ...resolveClientSettings(req, undefined, host), + retireIncompatibleContender: true, + }); + return await attach(req); +} import { currentDaemonCodeSignature } from './code-signature-fixture.ts'; import { AppError } from '@agent-device/kernel/errors'; import { tryAcquireProcessLock, inspectProcessLock } from '@agent-device/host-kit/file'; import { runCmdDetachedMonitored, runCmdSync } from '@agent-device/host-kit/command'; -import { readProcessStartTime } from '@agent-device/host-kit/process'; import { sleep } from '@agent-device/host-kit/retry'; import { readVersion } from '@agent-device/host-kit/version'; @@ -281,7 +293,7 @@ function mockSocketErrorAfterWrite(failingPort: number): { }; } -test('sendToDaemon retains unknown metadata after a spawn failure', async () => { +test('ensureAndSend retains unknown metadata after a spawn failure', async () => { const stateDir = makeTempStateDir('agent-device-daemon-spawn-retry-'); const paths = resolveDaemonPaths(stateDir); vi.stubEnv('AGENT_DEVICE_STATE_DIR', stateDir); @@ -303,7 +315,7 @@ test('sendToDaemon retains unknown metadata after a spawn failure', async () => try { let thrown: unknown; try { - await sendToDaemon({ + await ensureAndSend({ session: 'default', command: 'spawn-retry-smoke', positionals: [], @@ -332,7 +344,7 @@ test('sendToDaemon retains unknown metadata after a spawn failure', async () => } }); -test('sendToDaemon reports early daemon exit with log tail and startup paths', async () => { +test('ensureAndSend reports early daemon exit with log tail and startup paths', async () => { const stateDir = makeTempStateDir('agent-device-daemon-early-exit-'); const paths = resolveDaemonPaths(stateDir); vi.stubEnv('AGENT_DEVICE_STATE_DIR', stateDir); @@ -351,7 +363,7 @@ test('sendToDaemon reports early daemon exit with log tail and startup paths', a try { let thrown: unknown; try { - await sendToDaemon({ + await ensureAndSend({ session: 'default', command: 'early-exit-smoke', positionals: [], @@ -394,7 +406,7 @@ test('daemon acquisition reclaims a proven reused owner before publication', asy installSpawnedHttpDaemon(paths, daemon.port); try { - const response = await sendToDaemon({ + const response = await ensureAndSend({ session: 'default', command: 'stale-lock-smoke', positionals: [], @@ -407,7 +419,7 @@ test('daemon acquisition reclaims a proven reused owner before publication', asy assert.equal(mockRunCmdDetached.mock.calls.length, 1); assert.equal(freshLock.state, 'held'); if (freshLock.state === 'held') assert.notEqual(freshLock.owner.startTime, staleStartTime); - assert.deepEqual(daemon.seenPaths, ['GET /health', 'POST /rpc']); + assert.deepEqual(daemon.seenPaths, ['GET /health', 'GET /health', 'POST /rpc']); } finally { if (stale.status === 'acquired') await stale.acquisition.release(); await closeLoopbackServer(daemon.server); @@ -415,7 +427,7 @@ test('daemon acquisition reclaims a proven reused owner before publication', asy } }); -test('sendToDaemon does not reuse reachable daemon metadata with mismatched version or signature', async (t) => { +test('ensureAndSend does not reuse reachable daemon metadata with mismatched version or signature', async (t) => { if (await skipWhenLoopbackUnavailable(t)) return; const cases: Array<{ @@ -454,7 +466,7 @@ test('sendToDaemon does not reuse reachable daemon metadata with mismatched vers const stderrCapture = beginStderrCapture(); try { - const response = await sendToDaemon({ + const response = await ensureAndSend({ session: 'default', command: `mismatch-${fixture.name}-smoke`, positionals: [], @@ -465,7 +477,7 @@ test('sendToDaemon does not reuse reachable daemon metadata with mismatched vers assert.deepEqual(response, { ok: true, data: { via: 'fresh-daemon' } }); assert.equal(mockRunCmdDetached.mock.calls.length, 1); assert.deepEqual(staleDaemon.seenPaths, []); - assert.deepEqual(freshDaemon.seenPaths, ['GET /health', 'POST /rpc']); + assert.deepEqual(freshDaemon.seenPaths, ['GET /health', 'GET /health', 'POST /rpc']); const staleVersion = fixture.version ?? readVersion(); assert.equal( stderrCapture.read(), @@ -482,7 +494,7 @@ test('sendToDaemon does not reuse reachable daemon metadata with mismatched vers } }); -test('sendToDaemon prints a takeover notice before replacing an unreachable daemon', async (t) => { +test('ensureAndSend prints a takeover notice before replacing an unreachable daemon', async (t) => { if (await skipWhenLoopbackUnavailable(t)) return; const stateDir = makeTempStateDir('agent-device-daemon-unreachable-takeover-'); @@ -500,7 +512,7 @@ test('sendToDaemon prints a takeover notice before replacing an unreachable daem const stderrCapture = beginStderrCapture(); try { - const response = await sendToDaemon({ + const response = await ensureAndSend({ session: 'default', command: 'unreachable-takeover-smoke', positionals: [], @@ -520,7 +532,7 @@ test('sendToDaemon prints a takeover notice before replacing an unreachable daem } }); -test('sendToDaemon replaces socket-only daemon metadata when HTTP transport is requested', async (t) => { +test('ensureAndSend replaces socket-only daemon metadata when HTTP transport is requested', async (t) => { if (await skipWhenLoopbackUnavailable(t)) return; const stateDir = makeTempStateDir('agent-device-daemon-http-takeover-'); @@ -536,7 +548,7 @@ test('sendToDaemon replaces socket-only daemon metadata when HTTP transport is r const stderrCapture = beginStderrCapture(); try { - const response = await sendToDaemon({ + const response = await ensureAndSend({ session: 'default', command: 'http-takeover-smoke', positionals: [], @@ -546,7 +558,7 @@ test('sendToDaemon replaces socket-only daemon metadata when HTTP transport is r assert.deepEqual(response, { ok: true, data: { via: 'fresh-http-daemon' } }); assert.equal(mockRunCmdDetached.mock.calls.length, 1); - assert.deepEqual(freshDaemon.seenPaths, ['GET /health', 'POST /rpc']); + assert.deepEqual(freshDaemon.seenPaths, ['GET /health', 'GET /health', 'POST /rpc']); assert.equal( stderrCapture.read(), `Replacing daemon (pid 999999, v${readVersion()}) in ${paths.baseDir}: unreachable\n`, @@ -573,7 +585,7 @@ test('sendToDaemon falls back from failed socket transport to HTTP using daemon }); try { - const response = await sendToDaemon({ + const response = await attach({ session: 'default', command: 'transport-fallback-smoke', positionals: [], @@ -609,7 +621,7 @@ test('sendToDaemon does not replay over HTTP after the socket request is written try { let thrown: unknown; try { - await sendToDaemon({ + await attach({ session: 'default', command: 'open', positionals: ['Demo'], @@ -666,7 +678,7 @@ function unheldDivergenceError(): Record { }; } -test('sendToDaemon keeps an owned ephemeral daemon alive and hints its --state-dir on a resumable repair divergence', async (t) => { +test('ensureAndSend keeps an owned ephemeral daemon alive and hints its --state-dir on a resumable repair divergence', async (t) => { if (await skipWhenLoopbackUnavailable(t)) return; const daemon = await startHttpDaemonErrorFixture(heldDivergenceError()); @@ -676,7 +688,7 @@ test('sendToDaemon keeps an owned ephemeral daemon alive and hints its --state-d }); try { - const response = await sendToDaemon({ + const response = await ensureAndSend({ session: 'default', command: 'replay', positionals: ['drifted.ad'], @@ -718,7 +730,7 @@ test('C1: keep-alive keys on repairSessionHeld, NOT resume.allowed — a HELD di }); try { - const response = await sendToDaemon({ + const response = await ensureAndSend({ session: 'default', command: 'replay', positionals: ['drifted.ad'], @@ -737,7 +749,7 @@ test('C1: keep-alive keys on repairSessionHeld, NOT resume.allowed — a HELD di } }); -test('sendToDaemon tears down an owned ephemeral daemon on an UNHELD divergence (no repairSessionHeld signal)', async (t) => { +test('ensureAndSend tears down an owned ephemeral daemon on an UNHELD divergence (no repairSessionHeld signal)', async (t) => { if (await skipWhenLoopbackUnavailable(t)) return; const daemon = await startHttpDaemonErrorFixture(unheldDivergenceError()); @@ -747,7 +759,7 @@ test('sendToDaemon tears down an owned ephemeral daemon on an UNHELD divergence }); try { - const response = await sendToDaemon({ + const response = await ensureAndSend({ session: 'default', command: 'replay', positionals: ['drifted.ad'], @@ -796,7 +808,7 @@ test('BLOCKER 2 (third follow-up): a shutdown-time repair commit failure is surf return originalRmdir(target, options); }); try { - const response = await sendToDaemon({ + const response = await ensureAndSend({ session: 'default', command: 'replay', positionals: ['flow.ad'], @@ -829,7 +841,7 @@ test('BLOCKER 2 (third follow-up): a shutdown-time repair commit failure is surf } }); -test('continuation: sendToDaemon keeps the daemon alive on a held divergence even WITHOUT --save-script on the request', async (t) => { +test('continuation: ensureAndSend keeps the daemon alive on a held divergence even WITHOUT --save-script on the request', async (t) => { if (await skipWhenLoopbackUnavailable(t)) return; // The `replay --from` continuation of a repair does NOT repeat --save-script @@ -843,7 +855,7 @@ test('continuation: sendToDaemon keeps the daemon alive on a held divergence eve }); try { - const response = await sendToDaemon({ + const response = await ensureAndSend({ session: 'default', command: 'replay', positionals: ['drifted.ad'], @@ -889,12 +901,12 @@ function activeReplaySuccessData(overrides: Record = {}): Recor async function replayLeavingSessionActive( daemonPort: number, requestId: string, -): Promise<{ response: Awaited>; ownedStateDir: string }> { +): Promise<{ response: Awaited>; ownedStateDir: string }> { let ownedStateDir = ''; installSpawnedHttpDaemonAtOwnedStateDir(daemonPort, (dir) => { ownedStateDir = dir; }); - const response = await sendToDaemon({ + const response = await ensureAndSend({ session: 'default', command: 'replay', positionals: ['open-only.ad'], @@ -911,7 +923,7 @@ function parseAddressHint(hint: string): { stateDir: string; session: string } { return { stateDir: match[1] ?? '', session: match[2] ?? '' }; } -test('sendToDaemon keeps an owned ephemeral daemon alive and hints its --state-dir when a close-less replay leaves the session active', async (t) => { +test('ensureAndSend keeps an owned ephemeral daemon alive and hints its --state-dir when a close-less replay leaves the session active', async (t) => { if (await skipWhenLoopbackUnavailable(t)) return; const daemon = await startHttpDaemonFixture(activeReplaySuccessData()); @@ -947,7 +959,7 @@ test('sendToDaemon keeps an owned ephemeral daemon alive and hints its --state-d } }); -test('closes the loop: a follow-up sendToDaemon using the hinted --state-dir/--session reaches the SAME kept-alive daemon, without spawning a new one', async (t) => { +test('closes the loop: a follow-up ensureAndSend using the hinted --state-dir/--session reaches the SAME kept-alive daemon, without spawning a new one', async (t) => { if (await skipWhenLoopbackUnavailable(t)) return; const daemon = await startHttpDaemonFixture(activeReplaySuccessData()); @@ -961,7 +973,7 @@ test('closes the loop: a follow-up sendToDaemon using the hinted --state-dir/--s assert.equal(hinted.stateDir, ownedStateDir); const spawnCallsBeforeFollowUp = mockRunCmdDetached.mock.calls.length; - const followUp = await sendToDaemon({ + const followUp = await ensureAndSend({ session: hinted.session, command: 'press', positionals: [], @@ -983,7 +995,7 @@ test('closes the loop: a follow-up sendToDaemon using the hinted --state-dir/--s } }); -test('sendToDaemon tears down an owned ephemeral daemon when replay reports the session was closed (sessionActive: false)', async (t) => { +test('ensureAndSend tears down an owned ephemeral daemon when replay reports the session was closed (sessionActive: false)', async (t) => { if (await skipWhenLoopbackUnavailable(t)) return; const daemon = await startHttpDaemonFixture(activeReplaySuccessData({ sessionActive: false })); @@ -993,7 +1005,7 @@ test('sendToDaemon tears down an owned ephemeral daemon when replay reports the }); try { - const response = await sendToDaemon({ + const response = await ensureAndSend({ session: 'default', command: 'replay', positionals: ['closed.ad'], @@ -1031,7 +1043,7 @@ test('ADR 0012 R7 x ADR 0016: a completed --save-script repair also keeps its ow }); try { - const response = await sendToDaemon({ + const response = await ensureAndSend({ session: 'default', command: 'replay', positionals: ['flow.ad'], @@ -1055,7 +1067,7 @@ test('ADR 0012 R7 x ADR 0016: a completed --save-script repair also keeps its ow } }); -test('issue #1384: sendToDaemon does not stop a client-started daemon at an explicit --state-dir when replay leaves the session active', async (t) => { +test('issue #1384: ensureAndSend does not stop a client-started daemon at an explicit --state-dir when replay leaves the session active', async (t) => { if (await skipWhenLoopbackUnavailable(t)) return; // The literal #1384 repro: an explicit AGENT_DEVICE_STATE_DIR/--state-dir @@ -1069,7 +1081,7 @@ test('issue #1384: sendToDaemon does not stop a client-started daemon at an expl installSpawnedHttpDaemon(paths, daemon.port); try { - const response = await sendToDaemon({ + const response = await ensureAndSend({ session: 'default', command: 'replay', positionals: ['open-only.ad'], @@ -1098,7 +1110,7 @@ test('issue #1384: sendToDaemon does not stop a client-started daemon at an expl } }); -test('sendToDaemon still tears down a `test` command owned ephemeral daemon even if its response data carried sessionActive:true', async (t) => { +test('ensureAndSend still tears down a `test` command owned ephemeral daemon even if its response data carried sessionActive:true', async (t) => { if (await skipWhenLoopbackUnavailable(t)) return; // `test` never actually sets this field in practice (its own per-file @@ -1112,7 +1124,7 @@ test('sendToDaemon still tears down a `test` command owned ephemeral daemon even }); try { - const response = await sendToDaemon({ + const response = await ensureAndSend({ session: 'default', command: 'test', positionals: ['suite.ad'], diff --git a/packages/daemon-client/src/__tests__/daemon-client-proxy-upstream.test.ts b/packages/daemon-client/src/__tests__/daemon-client-proxy-upstream.test.ts index b065efa2c6..fb1e1915d9 100644 --- a/packages/daemon-client/src/__tests__/daemon-client-proxy-upstream.test.ts +++ b/packages/daemon-client/src/__tests__/daemon-client-proxy-upstream.test.ts @@ -3,18 +3,18 @@ import { expect, test, vi } from 'vitest'; import { createTestHostEnvironment, mkdtempForTestSync } from '@agent-device/test-kit'; import { resolveDaemonPaths } from '@agent-device/daemon-contracts/daemon-resolution'; -const mocks = vi.hoisted(() => ({ ensureManagedDaemon: vi.fn() })); +const mocks = vi.hoisted(() => ({ ensureStartedDaemon: vi.fn() })); vi.mock('../daemon-client-lifecycle.ts', async (importOriginal) => ({ ...(await importOriginal()), - ensureManagedDaemon: mocks.ensureManagedDaemon, + ensureStartedDaemon: mocks.ensureStartedDaemon, })); import { ensureProxyUpstreamDaemon } from '../daemon-client-proxy-upstream.ts'; test('the proxy upstream is the managed local HTTP daemon of the resolved state dir', async () => { const stateDir = mkdtempForTestSync('agent-device-proxy-upstream-'); - mocks.ensureManagedDaemon.mockResolvedValue({ + mocks.ensureStartedDaemon.mockResolvedValue({ info: { httpPort: 54321, token: 'daemon-secret', pid: 4242 }, startedByClient: false, }); @@ -31,9 +31,9 @@ test('the proxy upstream is the managed local HTTP daemon of the resolved state token: 'daemon-secret', stateDir: resolveDaemonPaths(stateDir).baseDir, }); - const settings = mocks.ensureManagedDaemon.mock.calls[0]![0]; + const settings = mocks.ensureStartedDaemon.mock.calls[0]![0]; expect(settings).toMatchObject({ - daemonLifecycle: 'managed', + retireIncompatibleContender: true, transportPreference: 'http', serverMode: 'http', }); diff --git a/packages/daemon-client/src/__tests__/daemon-client-startup-budget.test.ts b/packages/daemon-client/src/__tests__/daemon-client-startup-budget.test.ts index fa6c00285c..86e4a493d0 100644 --- a/packages/daemon-client/src/__tests__/daemon-client-startup-budget.test.ts +++ b/packages/daemon-client/src/__tests__/daemon-client-startup-budget.test.ts @@ -21,7 +21,7 @@ import { startHttpDaemonFixture, skipWhenLoopbackUnavailable, } from '@agent-device/test-kit'; -import { isProcessAlive } from '@agent-device/host-kit/process'; +import { captureHostEnvironment, isProcessAlive } from '@agent-device/host-kit/process'; import { readVersion } from '@agent-device/host-kit/version'; import { spawnRegisteredDaemonFixture, @@ -50,7 +50,17 @@ vi.mock('@agent-device/host-kit/process', async (importOriginal) => { }); import { runCmdDetachedMonitored } from '@agent-device/host-kit/command'; import { sleep } from '@agent-device/host-kit/retry'; -import { sendToDaemon } from '../index.ts'; +import { sendToDaemon as attach } from '../index.ts'; +import { ensureStartedDaemon, resolveClientSettings } from '../daemon-client-lifecycle.ts'; + +async function sendToDaemon(req: Parameters[0]) { + const host = captureHostEnvironment(process); + await ensureStartedDaemon({ + ...resolveClientSettings(req, undefined, host), + retireIncompatibleContender: true, + }); + return await attach(req); +} const actualRetry = await vi.importActual( '@agent-device/host-kit/retry', diff --git a/packages/daemon-client/src/__tests__/daemon-client-startup-race.test.ts b/packages/daemon-client/src/__tests__/daemon-client-startup-race.test.ts index 13f97b6e42..ec9ac51152 100644 --- a/packages/daemon-client/src/__tests__/daemon-client-startup-race.test.ts +++ b/packages/daemon-client/src/__tests__/daemon-client-startup-race.test.ts @@ -12,6 +12,7 @@ import { import { readVersion } from '@agent-device/host-kit/version'; import { beginStderrCapture, + createTestHostEnvironment, closeLoopbackServer, mkdtempForTestSync, startHttpDaemonFixture, @@ -27,10 +28,15 @@ import { resolveDaemonPaths, type DaemonPaths, } from '@agent-device/daemon-contracts/daemon-resolution'; -import { sendToDaemon } from '../index.ts'; +import { createEnsuredDaemonTransport, sendToDaemon as attachToDaemon } from '../index.ts'; import * as lifecycle from '../daemon-client-lifecycle.ts'; import { DAEMON_STARTUP_EXIT_CODES } from '@agent-device/daemon-contracts/daemon-registration-owner'; +// The startup machinery's owner since 0.22 is the explicit ensure: the CLI and MCP transport ensures +// the shared daemon once and attaches every request to it. Driving it here keeps these startup rows +// on the seam that still starts a daemon; a plain client request only attaches. +const sendToDaemon = createEnsuredDaemonTransport(); + vi.mock('@agent-device/host-kit/command', async (importOriginal) => ({ ...(await importOriginal()), runCmdDetachedMonitored: vi.fn(), @@ -635,7 +641,12 @@ test.for([ }); const stderrCapture = beginStderrCapture(); try { - const pending = sendToDaemon(request(paths)); + const host = createTestHostEnvironment(); + const settings = { + ...lifecycle.resolveClientSettings(request(paths), undefined, host), + retireIncompatibleContender: true, + }; + const pending = lifecycle.ensureStartedDaemon(settings); if (expected.alive) await assert.rejects(pending, (error: unknown) => { assert.ok(error instanceof AppError); @@ -645,12 +656,14 @@ test.for([ return true; }); else { - assert.equal((await pending).ok, true); + assert.equal((await pending).startedByClient, true); await winner.exited; } assert.equal(joined, true); assert.equal(isProcessAlive(winner.pid), expected.alive); assert.equal(spawn.mock.calls.length, expected.launches); + assert.equal(http.rpcRequests.length, 0, 'ensuring never dispatches the request'); + if (!expected.alive) assert.equal((await attachToDaemon(request(paths))).ok, true); assert.equal(http.rpcRequests.length, expected.rpcs); assert.equal( stderrCapture.read().includes(`Replacing daemon (pid ${winner.pid}, v0.0.1)`), @@ -725,7 +738,7 @@ test.for(['default', 'private replay'] as const)( if (await skipWhenLoopbackUnavailable(t)) return; const http = await startHttpDaemonFixture({ devices: [], sessionActive: false }); const defaultPaths = resolveDaemonPaths(mkdtempForTestSync('daemon-missed-birth-')); - const ensure = vi.spyOn(lifecycle, 'ensureManagedDaemon'); + const ensure = vi.spyOn(lifecycle, 'ensureStartedDaemon'); let paths: DaemonPaths | undefined; let child: ReturnType | undefined; let now = Date.now(); @@ -763,8 +776,7 @@ test.for(['default', 'private replay'] as const)( : { session: 'default', command: 'replay', positionals: [], flags: {} }, ); assert.equal(response.ok, true); - assert.equal(ensure.mock.calls.length, 1); - assert.equal((await ensure.mock.results[0]!.value).startedByClient, true); + assert.equal(ensure.mock.calls.length, route === 'private replay' ? 1 : 0); assert.equal(spawn.mock.calls.length, 1); assert.equal(http.rpcRequests.length, 1); assert.ok(paths && child); diff --git a/packages/daemon-client/src/__tests__/daemon-client-timeout-route.test.ts b/packages/daemon-client/src/__tests__/daemon-client-timeout-route.test.ts index 542c7a2516..dfcc022418 100644 --- a/packages/daemon-client/src/__tests__/daemon-client-timeout-route.test.ts +++ b/packages/daemon-client/src/__tests__/daemon-client-timeout-route.test.ts @@ -364,7 +364,7 @@ for (const row of ROUTE_ROWS) { row.transport === 'remote' ? 'http' : row.transport, statePaths, TIMEOUT_MS, - { host: createTestHostEnvironment() }, + { host: createTestHostEnvironment(), timeoutRecovery: 'retire-unresponsive' }, ), row.hintPattern, ); @@ -412,7 +412,7 @@ test('request-timeout route: a reset never deletes a registration a replacement 'socket', statePaths, TIMEOUT_MS, - { host: createTestHostEnvironment() }, + { host: createTestHostEnvironment(), timeoutRecovery: 'retire-unresponsive' }, ), /The daemon could not be safely retired/, ); @@ -452,7 +452,7 @@ test('a refused timeout fallback preserves the timeout without an unhandled reje 'socket', paths, TIMEOUT_MS, - { host: createTestHostEnvironment() }, + { host: createTestHostEnvironment(), timeoutRecovery: 'retire-unresponsive' }, ), (error: unknown) => { assert.ok(error instanceof AppError); @@ -524,7 +524,7 @@ test('request-timeout route: the reset acts on the resolved state paths, not the 'http', resolvedPaths, TIMEOUT_MS, - { host: createTestHostEnvironment() }, + { host: createTestHostEnvironment(), timeoutRecovery: 'retire-unresponsive' }, ), /The daemon did not answer the liveness probe and was reset after the timeout/, ); diff --git a/packages/daemon-client/src/__tests__/index-host.test.ts b/packages/daemon-client/src/__tests__/index-host.test.ts index a7560f3126..e7ef097a8e 100644 --- a/packages/daemon-client/src/__tests__/index-host.test.ts +++ b/packages/daemon-client/src/__tests__/index-host.test.ts @@ -3,13 +3,6 @@ import { afterEach, expect, test, vi } from 'vitest'; const ensured = vi.hoisted(() => ({ settings: undefined as unknown })); -vi.mock('../daemon-client-lifecycle.ts', async (importOriginal) => ({ - ...(await importOriginal()), - ensureManagedDaemon: async (settings: unknown) => { - ensured.settings = settings; - throw new Error('stop before talking to a daemon'); - }, -})); vi.mock('../daemon-client-startup.ts', async (importOriginal) => ({ ...(await importOriginal()), observeLocalDaemon: async (settings: unknown) => { diff --git a/packages/daemon-client/src/__tests__/index-newer-daemon.test.ts b/packages/daemon-client/src/__tests__/index-newer-daemon.test.ts index afea8bfeae..005f921d51 100644 --- a/packages/daemon-client/src/__tests__/index-newer-daemon.test.ts +++ b/packages/daemon-client/src/__tests__/index-newer-daemon.test.ts @@ -63,7 +63,8 @@ test('sendToDaemon refuses to replace a reachable daemon newer than the client', }), (error: unknown) => { assert.ok(error instanceof AppError); - assert.match(error.message, /v999\.0\.0\) is newer than this client/); + assert.equal(error.details?.reason, 'daemon-incompatible'); + assert.equal(error.details?.mismatch, 'newer'); assert.match(String(error.details?.hint), /agent-device daemon stop --state-dir /); return true; }, @@ -112,7 +113,8 @@ test('sendToDaemon refuses a newer socket-only daemon when the client prefers ht }), (error: unknown) => { assert.ok(error instanceof AppError); - assert.match(error.message, /v999\.0\.0\) is newer than this client/); + assert.equal(error.details?.reason, 'daemon-incompatible'); + assert.equal(error.details?.mismatch, 'newer'); return true; }, ); diff --git a/packages/daemon-client/src/__tests__/index-policy-reuse.test.ts b/packages/daemon-client/src/__tests__/index-policy-reuse.test.ts index 5812ded6dc..d8cc9b7a41 100644 --- a/packages/daemon-client/src/__tests__/index-policy-reuse.test.ts +++ b/packages/daemon-client/src/__tests__/index-policy-reuse.test.ts @@ -21,7 +21,7 @@ import { } from '@agent-device/test-kit'; import { loadDaemonPolicy } from '@agent-device/daemon-contracts/daemon-policy-file'; import { resolveDaemonPaths } from '@agent-device/daemon-contracts/daemon-resolution'; -import { createDaemonTransport, sendToDaemon } from '../index.ts'; +import { createDaemonTransport, sendToDaemon, ensureProxyUpstreamDaemon } from '../index.ts'; // ADR 0029: a caller that names a daemon policy must not use a daemon that enforces another one. @@ -114,7 +114,11 @@ test('a caller naming a policy refuses a daemon another caller started without i const fixture = await startReusableDaemon({ policyDigest: undefined, publish: 'on-spawn' }); try { await assert.rejects( - () => sendSmoke(fixture.stateDir), + () => + ensureProxyUpstreamDaemon({ + stateDir: fixture.stateDir, + host: { env: process.env, cwd: process.cwd() }, + }), (error: unknown) => { assert.ok(error instanceof AppError); assert.equal(error.details?.reason, 'DAEMON_POLICY_MISMATCH'); diff --git a/packages/daemon-client/src/__tests__/index-stalled-probe.test.ts b/packages/daemon-client/src/__tests__/index-stalled-probe.test.ts index 39fdbe3509..a2e16f09db 100644 --- a/packages/daemon-client/src/__tests__/index-stalled-probe.test.ts +++ b/packages/daemon-client/src/__tests__/index-stalled-probe.test.ts @@ -13,7 +13,7 @@ import { } from '@agent-device/host-kit/process'; import { findProjectRoot, readVersion } from '@agent-device/host-kit/version'; import { resolveDaemonPaths } from '@agent-device/daemon-contracts/daemon-resolution'; -import { sendToDaemon } from '../index.ts'; +import { sendToDaemon, createEnsuredDaemonTransport } from '../index.ts'; import { closeLoopbackServer, listenOnLoopback, @@ -214,7 +214,8 @@ test('sendToDaemon refuses a live newer daemon whose first probe missed', async () => sendSmoke(stateDir), (error: unknown) => { assert.ok(error instanceof AppError); - assert.equal(error.details?.daemonVersion, NEWER_DAEMON_VERSION); + assert.equal(error.details?.reason, 'daemon-incompatible'); + assert.equal(error.details?.mismatch, 'newer'); return true; }, ); @@ -283,7 +284,12 @@ async function expectDeadDaemonReplaced( return; } - const response = await sendSmoke(stateDir); + const response = await createEnsuredDaemonTransport()({ + session: 'default', + command: 'stalled-probe-smoke', + positionals: [], + flags: { stateDir, daemonTransport: 'socket' }, + }); assert.deepEqual(response, { ok: true, data: { via: 'fresh-daemon' } }); assert.equal(mockSpawnDaemon.mock.calls.length, 1, 'the dead daemon was replaced'); @@ -300,10 +306,10 @@ async function expectDeadDaemonReplaced( } } -test('sendToDaemon replaces a daemon whose process is gone after a single probe', async (t) => { +test('createEnsuredDaemonTransport replaces a daemon whose process is gone after a single probe', async (t) => { await expectDeadDaemonReplaced(t, readVersion()); }); -test('sendToDaemon replaces a newer daemon whose process is gone after a single probe', async (t) => { +test('createEnsuredDaemonTransport replaces a newer daemon whose process is gone after a single probe', async (t) => { await expectDeadDaemonReplaced(t, NEWER_DAEMON_VERSION); }); diff --git a/packages/daemon-client/src/daemon-client-attach.ts b/packages/daemon-client/src/daemon-client-attach.ts index fd9407f802..26e1a35e26 100644 --- a/packages/daemon-client/src/daemon-client-attach.ts +++ b/packages/daemon-client/src/daemon-client-attach.ts @@ -1,5 +1,5 @@ import { AppError } from '@agent-device/kernel/errors'; -import { ensureManagedDaemon } from './daemon-client-lifecycle.ts'; +import { ensureStartedDaemon } from './daemon-client-lifecycle.ts'; import { assertDaemonPolicyMatches, observeLocalDaemon } from './daemon-client-startup.ts'; import type { DaemonClientSettings, @@ -9,13 +9,13 @@ import type { import { daemonBindingMismatchError } from './daemon-client-binding.ts'; import { daemonIncompatibleError, daemonNotRunningError } from './daemon-lifecycle-errors.ts'; -/** Resolves a managed daemon, or observes and verifies the one an attach client may use. */ +/** Resolves a remote or owned daemon, or verifies the daemon an attach client may use. */ export async function connectToDaemon( settings: DaemonClientSettings, healthRecovery?: RemoteHealthRecovery, ): Promise { - if (settings.remoteBaseUrl || settings.daemonLifecycle !== 'attach') { - return await ensureManagedDaemon(settings, healthRecovery); + if (settings.remoteBaseUrl || settings.ownedStateDir) { + return await ensureStartedDaemon(settings, healthRecovery); } const stateDir = settings.paths.baseDir; const observed = await observeLocalDaemon(settings, { refineUnreachable: true }).catch( diff --git a/packages/daemon-client/src/daemon-client-ensuring.ts b/packages/daemon-client/src/daemon-client-ensuring.ts index 7f7e360e3f..11c53f15af 100644 --- a/packages/daemon-client/src/daemon-client-ensuring.ts +++ b/packages/daemon-client/src/daemon-client-ensuring.ts @@ -46,7 +46,7 @@ export function withEnsuredDaemon( const stateDir = resolveDaemonPaths(target.stateDir, { env: host.env, cwd: host.cwd }).baseDir; // A caller that has already given up starts nothing: attaching refuses before any connection. if (context?.signal?.aborted) { - return await transport(req, { ...context, daemonLifecycle: 'attach' }); + return await transport(req, context); } // A finished ensure is kept for the rest of this transport's life. A rejected one is dropped so // the next request retries, and one whose daemon has since gone is dropped by the attach below. @@ -64,7 +64,7 @@ export function withEnsuredDaemon( return { relied: pending }; }; const { relied } = await ensure(); - const attach = async () => await transport(req, { ...context, daemonLifecycle: 'attach' }); + const attach = async () => await transport(req, context); try { return await attach(); } catch (error) { diff --git a/packages/daemon-client/src/daemon-client-lifecycle.ts b/packages/daemon-client/src/daemon-client-lifecycle.ts index 9b5bd71701..c56f51ba75 100644 --- a/packages/daemon-client/src/daemon-client-lifecycle.ts +++ b/packages/daemon-client/src/daemon-client-lifecycle.ts @@ -1,9 +1,5 @@ import type { DaemonWireRequest } from '@agent-device/contracts/command'; -import type { - DaemonBinding, - DaemonLifecycle, - EnsureDaemonOptions, -} from '@agent-device/contracts/client'; +import type { DaemonBinding, EnsureDaemonOptions } from '@agent-device/contracts/client'; import type { DaemonResponse } from '@agent-device/kernel/contracts'; import net from 'node:net'; import { AppError, normalizeError, type NormalizedError } from '@agent-device/kernel/errors'; @@ -40,11 +36,10 @@ export type DaemonClientSettings = { /** The environment and working directory this client reads, for every setting below and the launch. */ host: HostEnvironment; paths: DaemonPaths; - daemonLifecycle: DaemonLifecycle; /** - * Whether a daemon that wins a startup race may be retired when this client cannot use it. A - * managed client may; `ensureDaemon` may not, because it replaces a daemon only through a quiesce - * and judges the winner again instead. + * Whether a daemon that wins a startup race may be retired when this client cannot use it. An + * explicit owner that may start a daemon may; `ensureDaemon` may not, because it replaces a daemon + * only through a quiesce and judges the winner again instead. */ retireIncompatibleContender: boolean; transportPreference: DaemonTransportPreference; @@ -67,23 +62,23 @@ LOOPBACK_BLOCK_LIST.addAddress('::1', 'ipv6'); LOOPBACK_BLOCK_LIST.addSubnet('::ffff:127.0.0.0', 104, 'ipv6'); /** - * Whether a timed-out request may retire the daemon it was waiting on. An attach client never may: the - * daemon is not its to kill, and `ensureDaemon` is where an unresponsive one is replaced. Every other - * caller asks the retirement, which judges the record's owner before it signals anything. + * Whether a timed-out request may retire the daemon it was waiting on. Only the one-shot `replay` or + * `test` request that owns a private state directory may: that daemon answers to no one else, and its + * retirement judges the record's owner before it signals anything. Every other request attaches to a + * daemon it did not start, and `ensureDaemon` is where an unresponsive one is replaced. */ export function resolveTimeoutRecovery( - settings: DaemonClientSettings, + settings: Pick, ): 'retire-unresponsive' | 'none' { - if (settings.daemonLifecycle === 'attach') return 'none'; - return 'retire-unresponsive'; + return settings.ownedStateDir ? 'retire-unresponsive' : 'none'; } export function resolveClientSettings( req: Omit, suppliedAuthToken: string | undefined, host: HostEnvironment, - daemonLifecycle: DaemonLifecycle = 'managed', daemonBinding: DaemonBinding | undefined = undefined, + ownOneShot = false, ): DaemonClientSettings { const explicitStateDir = resolveExplicitStateDir(req, host.env); const remote = resolveRemoteClientSettings(req, suppliedAuthToken, host.env); @@ -101,12 +96,13 @@ export function resolveClientSettings( }, ); } - if (daemonBinding) daemonLifecycle = 'attach'; const transport = resolveTransportClientSettings(req.flags, remote.remoteBaseUrl, host.env); - // An attach client owns no daemon, and a private state directory would hold one nobody started. A - // pinned client owns one neither: it uses the instance it was given and starts nothing. + // A one-shot `replay` or `test` with no explicit state directory runs on a private daemon of its + // own: this request starts it, attaches to it, and retires it when it finishes. Nothing else does. + // A pinned client owns one neither: it uses the instance it was given and starts nothing. const ownedStateDir = - daemonLifecycle !== 'attach' && + ownOneShot && + daemonBinding === undefined && shouldUseOwnedReplayStateDir(req, explicitStateDir, remote.rawBaseUrl) ? createOwnedReplayStateDir() : undefined; @@ -115,8 +111,7 @@ export function resolveClientSettings( paths: ownedStateDir?.paths ?? resolveDaemonPaths(explicitStateDir, { env: host.env, cwd: host.cwd }), - daemonLifecycle, - retireIncompatibleContender: true, + retireIncompatibleContender: ownedStateDir !== undefined, transportPreference: transport.preference, serverMode: transport.serverMode, ownedStateDir, @@ -164,7 +159,8 @@ export function resolveLocalDaemonSettings( env: host.env, cwd: host.cwd, }), - daemonLifecycle: 'managed', + // `ensureDaemon` replaces a daemon only through a quiesce, so a contender it cannot use is + // judged again, never retired by this call. retireIncompatibleContender: false, transportPreference: transport.preference, serverMode: transport.serverMode, @@ -226,16 +222,13 @@ function shouldUseOwnedReplayStateDir( return isOneShotReplayCommand(req.command) && !explicitStateDir && !rawRemoteBaseUrl; } -/** - * How long the remote `/health` gate may re-probe a daemon that is there but not ready: the budget - * of the command waiting behind it. Without one, the first failed probe refuses. - */ +/** The command budget for recovering a remote daemon health probe. */ export type RemoteHealthRecovery = { budgetMs: number; signal: AbortSignal | undefined; }; -export async function ensureManagedDaemon( +export async function ensureStartedDaemon( settings: DaemonClientSettings, healthRecovery?: RemoteHealthRecovery, ): Promise { @@ -243,13 +236,13 @@ export async function ensureManagedDaemon( return await ensureRemoteDaemon(settings, healthRecovery); } - const ensured = await ensureLocalDaemon(settings); + const ensured = await startOrReuseLocalDaemon(settings); // Checked on both branches: a startup can resolve to a daemon another caller raced in. await assertDaemonPolicyMatches(ensured.info, settings.paths.baseDir, settings.host); return ensured; } -async function ensureLocalDaemon(settings: DaemonClientSettings): Promise { +async function startOrReuseLocalDaemon(settings: DaemonClientSettings): Promise { const reusable = await readReusableLocalDaemon(settings); if (reusable) return { info: reusable, startedByClient: false }; @@ -258,7 +251,7 @@ async function ensureLocalDaemon(settings: DaemonClientSettings): Promise { const remoteInfo: DaemonInfo = { transport: 'http', diff --git a/packages/daemon-client/src/daemon-client-proxy-upstream.ts b/packages/daemon-client/src/daemon-client-proxy-upstream.ts index 49dce4b81c..2beda96f7e 100644 --- a/packages/daemon-client/src/daemon-client-proxy-upstream.ts +++ b/packages/daemon-client/src/daemon-client-proxy-upstream.ts @@ -1,5 +1,5 @@ import type { HostEnvironment } from '@agent-device/kernel/source-value'; -import { ensureManagedDaemon, resolveClientSettings } from './daemon-client-lifecycle.ts'; +import { ensureStartedDaemon, resolveClientSettings } from './daemon-client-lifecycle.ts'; export type ProxyUpstreamDaemonOptions = { stateDir?: string; @@ -15,22 +15,27 @@ export type ProxyUpstreamDaemon = { export async function ensureProxyUpstreamDaemon( options: ProxyUpstreamDaemonOptions, ): Promise { - const settings = resolveClientSettings( - { - session: 'default', - command: 'proxy', - positionals: [], - flags: { - stateDir: options.stateDir, - daemonBaseUrl: '', - daemonTransport: 'http', - daemonServerMode: 'http', + // `proxy` owns the local daemon it forwards to: it starts a missing one and may retire a startup + // contender it cannot use. A client request never takes this path. + const settings = { + ...resolveClientSettings( + { + session: 'default', + command: 'proxy', + positionals: [], + flags: { + stateDir: options.stateDir, + daemonBaseUrl: '', + daemonTransport: 'http', + daemonServerMode: 'http', + }, }, - }, - undefined, - options.host, - ); - const daemon = await ensureManagedDaemon(settings); + undefined, + options.host, + ), + retireIncompatibleContender: true, + }; + const daemon = await ensureStartedDaemon(settings); return { httpPort: daemon.info.httpPort, token: daemon.info.token, diff --git a/packages/daemon-client/src/daemon-client-transport.ts b/packages/daemon-client/src/daemon-client-transport.ts index efd31c2c46..8eb1d37a30 100644 --- a/packages/daemon-client/src/daemon-client-transport.ts +++ b/packages/daemon-client/src/daemon-client-transport.ts @@ -47,9 +47,10 @@ type SendRequestOptions = { */ signal?: AbortSignal; /** - * What a timed-out request may do to the daemon. `retire-unresponsive`, the default, lets the - * liveness probe retire a daemon that answers nothing; `none` leaves every daemon alone, which is - * how an attach client and the quiesce request itself time out. + * What a timed-out request may do to the daemon. `none`, the default, leaves every daemon alone, + * which is how an attach client, a lease beat and the quiesce request itself time out. + * `retire-unresponsive` lets the liveness probe retire a daemon that answers nothing, and only the + * one-shot `replay` or `test` owner of a private state directory asks for it. */ timeoutRecovery?: 'retire-unresponsive' | 'none'; }; @@ -420,7 +421,7 @@ async function recoverFromTimeout( return await handleRequestTimeout({ info, statePaths, - retireUnresponsive: options.timeoutRecovery !== 'none', + retireUnresponsive: options.timeoutRecovery === 'retire-unresponsive', requestSent: error.details.daemonRequestSent !== false, ...timeoutRequestContext(req, isRemoteDaemon(info), expiredBudget), }); diff --git a/packages/daemon-client/src/index.ts b/packages/daemon-client/src/index.ts index 0f3a533c51..4e0362d083 100644 --- a/packages/daemon-client/src/index.ts +++ b/packages/daemon-client/src/index.ts @@ -71,6 +71,7 @@ async function sendToDaemonOnHost( req: Omit, options: DaemonTransportOptions, host: HostEnvironment, + ownOneShot = false, ): Promise { const { resolveClientSettings, resolveTimeoutRecovery, attachSessionAddressHints } = await import('./daemon-client-lifecycle.ts'); @@ -89,8 +90,8 @@ async function sendToDaemonOnHost( requestWithoutAuthFlag, options.authToken ?? flagAuthToken, host, - options.daemonLifecycle, options.daemonBinding, + ownOneShot, ); const requestTimeoutMs = resolveCommandRequestTimeoutMs( resolveCommandTimeoutPolicy(requestWithoutAuthFlag.command), @@ -194,7 +195,16 @@ export function createEnsuredDaemonTransport( let ensured: Promise | undefined; return async (req, context) => { ensured ??= import('./daemon-client-ensuring.ts').then(({ withEnsuredDaemon }) => - withEnsuredDaemon(options.host ? createDaemonTransport(options.host) : sendToDaemon, options), + withEnsuredDaemon( + async (request, context) => + await sendToDaemonOnHost( + request, + context ?? {}, + options.host ?? captureHostEnvironment(process), + true, + ), + options, + ), ); return await ( await ensured @@ -454,7 +464,7 @@ export async function resolveLocalDaemonCodeIdentity(): Promise { diff --git a/src/commands/schema/cli-help.ts b/src/commands/schema/cli-help.ts index 990ffcbb47..42c17bb139 100644 --- a/src/commands/schema/cli-help.ts +++ b/src/commands/schema/cli-help.ts @@ -422,8 +422,8 @@ Runner and daemon lifecycle (applies to simulators too): Each AGENT_DEVICE_STATE_DIR runs its own daemon. It self-exits after an idle window (default 5 minutes, matching the runner idle-stop default) once it has no open sessions, no in-flight requests, and no active recording; set AGENT_DEVICE_DAEMON_IDLE_TIMEOUT_MS to override, or 0 to disable idle reap. A client starting a local daemon waits while the daemon process stays alive and keeps publishing startup progress, so an overloaded host makes startup slower, not failed. It stops at a ceiling (default 120 s; set AGENT_DEVICE_DAEMON_STARTUP_TIMEOUT_MS to a positive integer number of milliseconds to override) and names the outcome in error details.reason: startup-exited (the process ended before registering), startup-stalled (alive, no startup progress for a fixed 60 s window the ceiling variable does not change), or startup-ceiling (a startup was still live when the ceiling passed — this client's daemon or another client's; the client stops its own launch and never signals another client's live daemon. Only a progressing own launch outlasts the 60 s stall window, so a ceiling set below 60 s also ends a silent own launch this way). details.phases carries the startup phase timings it observed and details.startupTimeoutMs the effective ceiling. Branch on details.reason, never on the message. The variable is read only when a client must start a daemon: a value that is not a positive integer fails with INVALID_ARGS before the daemon spawns, and a client that only attaches to or reuses a running daemon never reads it. On iOS simulators, open prepares app accessibility before launching an app or URL. If a running app has an empty accessibility tree after an earlier XCTest session, use open --relaunch, then snapshot -i. A preparation failure is logged and does not block launch. - A command that needs the shared local daemon starts it for its state dir when none runs (device status and device release --stale never contact one). When the running daemon comes from another version or build, the command replaces it only if the daemon reports no work: no in-flight request, session, repair session, or live lease (a streaming resumable upload and a host human-control hold that names no lease are not counted); otherwise it fails with details.reason daemon-busy and leaves the daemon alone. A daemon that agreed to leave is waited for up to 60 s and never signaled while it drains; one still running then fails with details.reason daemon-drain-timeout unless it answers nothing and is provably a daemon process, which is force-retired. A daemon from a release that predates this check is never replaced and fails with daemon-incompatible. End a busy or older daemon deliberately with agent-device daemon stop --state-dir . Node clients pick daemonLifecycle 'attach' (never starts or replaces a daemon; fails with daemon-not-running or daemon-incompatible) or 'managed' (the default until 0.22), and ensureDaemon() starts or replaces one explicitly. - daemon stop --state-dir stops a detached daemon with process signals after verifying its identity. For a live embedded runtime, stop refuses with details.reason daemon-owner-embedded and a hint naming the host PID. Close that runtime in its host process with the handle returned by startAgentDevice(). Stop refuses live unrecognized ownership with daemon-owner-unrecognized and sends no request or signal. Stop retires an embedded or unrecognized registration when its recorded host lifetime has provably exited. Without --clean, an unreadable daemon.json fails with daemon-record-unreadable. daemon status shows host-owned or owner-not-recognized. Managed clients reuse a matching embedded runtime. Takeover, drain, and timeout recovery refuse a live embedded or unrecognized owner without a signal; a provably exited owner is retired so the state directory stays usable. Detached stop and cleanup use the lifetime and ownership from one registration read. --clean requires proven detached ownership; embedded, unrecognized and unreadable records fail with daemon-clean-not-detached because that cleanup walks the owner's whole process tree. + A command that needs the shared local daemon starts it for its state dir when none runs (device status and device release --stale never contact one). When the running daemon comes from another version or build, the command replaces it only if the daemon reports no work: no in-flight request, session, repair session, or live lease (a streaming resumable upload and a host human-control hold that names no lease are not counted); otherwise it fails with details.reason daemon-busy and leaves the daemon alone. A daemon that agreed to leave is waited for up to 60 s and never signaled while it drains; one still running then fails with details.reason daemon-drain-timeout unless it answers nothing and is provably a daemon process, which is force-retired. A daemon from a release that predates this check is never replaced and fails with daemon-incompatible. End a busy or older daemon deliberately with agent-device daemon stop --state-dir . Node clients always attach: they never start, replace or retire a daemon, and fail with daemon-not-running or daemon-incompatible. ensureDaemon() starts or replaces one explicitly, and startAgentDevice() owns one in the client's own process. + daemon stop --state-dir stops a detached daemon with process signals after verifying its identity. For a live embedded runtime, stop refuses with details.reason daemon-owner-embedded and a hint naming the host PID. Close that runtime in its host process with the handle returned by startAgentDevice(). Stop refuses live unrecognized ownership with daemon-owner-unrecognized and sends no request or signal. Stop retires an embedded or unrecognized registration when its recorded host lifetime has provably exited. Without --clean, an unreadable daemon.json fails with daemon-record-unreadable. daemon status shows host-owned or owner-not-recognized. Clients attach to a matching embedded runtime. Explicit ensuring refuses to replace a live embedded or unrecognized owner; a provably exited owner can be retired so the state directory stays usable. Detached stop and cleanup use the lifetime and ownership from one registration read. --clean requires proven detached ownership; embedded, unrecognized and unreadable records fail with daemon-clean-not-detached because that cleanup walks the owner's whole process tree. On a machine shared by several agents, set AGENT_DEVICE_SESSION_IDLE_TIMEOUT_MS to also expire an individual session that has taken a host-global device claim and then received no commands for that long; the claim is released and the next command on that session answers SESSION_NOT_FOUND with details.reason SESSION_IDLE_EXPIRED naming the window and the device. Off by default, because on a shared host "idle" and "thinking" are indistinguishable: only set it where an abandoned claim blocking every other agent is the worse failure. Sessions holding a remote lease or any active capture (recording, logs, audio, performance, or trace) are never expired this way. A stale iOS runner lease — its owner process dead, or its AGENT_DEVICE_STATE_DIR deleted — is reclaimed automatically instead of failing with "is already owned by another agent-device daemon". A live owner's runner is also reclaimed when the requesting daemon holds the host-global device claim for that device: claims are exclusive, so holding one proves the runner's owner released the device and merely kept the runner warm. The error remains only for owners outside claim arbitration (a pre-claims build, or daemons pointed at different claim stores). diff --git a/test/integration/provider-scenarios/ios-fold.test.ts b/test/integration/provider-scenarios/ios-fold.test.ts index 61634d53e9..56820f0ddd 100644 --- a/test/integration/provider-scenarios/ios-fold.test.ts +++ b/test/integration/provider-scenarios/ios-fold.test.ts @@ -572,7 +572,6 @@ test.each([ // Exercise the real client envelope and HTTP transport, including timeout classification. const pending: Promise = createDaemonTransport(createTestHostEnvironment())( request, - { daemonLifecycle: 'attach' }, ).catch((error) => ({ ok: false, error: normalizeError(error) })); let settled = false; void pending.then( diff --git a/website/docs/docs/ai-sdk.md b/website/docs/docs/ai-sdk.md index b508497b0e..65b401e24b 100644 --- a/website/docs/docs/ai-sdk.md +++ b/website/docs/docs/ai-sdk.md @@ -19,8 +19,10 @@ Alternatively, pass a model from your configured AI SDK provider. See the AI SDK ```ts import { ToolLoopAgent } from 'ai'; +import { ensureDaemon, isAgentDeviceError } from 'agent-device'; import { createAgentDeviceTools } from 'agent-device/ai-sdk'; +await ensureDaemon(); const { tools, client } = await createAgentDeviceTools({ session: 'ai-sdk-agent', platform: 'ios', @@ -42,7 +44,11 @@ try { console.log(result.text); } finally { - await client.sessions.close(); + await client.sessions.close().catch((error) => { + if (isAgentDeviceError(error) && error.code === 'SESSION_NOT_FOUND') return; + console.error('Session cleanup failed:', error); + process.exitCode = 1; + }); } ``` diff --git a/website/docs/docs/aws-device-farm.md b/website/docs/docs/aws-device-farm.md index 0206b7b814..050b4e4e91 100644 --- a/website/docs/docs/aws-device-farm.md +++ b/website/docs/docs/aws-device-farm.md @@ -83,8 +83,9 @@ To drive AWS Device Farm only through MCP, see [Use a provider only through MCP] Configure the client directly when your Node.js process manages the AWS credentials and selectors: ```ts -import { createAgentDeviceClient } from 'agent-device'; +import { createAgentDeviceClient, ensureDaemon } from 'agent-device'; +await ensureDaemon(); const client = createAgentDeviceClient({ session: 'checkout-android', leaseProvider: 'aws-device-farm', diff --git a/website/docs/docs/browserstack.md b/website/docs/docs/browserstack.md index 827916213e..d5a02a01d2 100644 --- a/website/docs/docs/browserstack.md +++ b/website/docs/docs/browserstack.md @@ -90,8 +90,9 @@ To drive BrowserStack only through MCP, see [Use a provider only through MCP](/d Configure the client directly when your Node.js process manages the BrowserStack credentials and selectors instead of a saved CLI connection profile: ```ts -import { createAgentDeviceClient } from 'agent-device'; +import { createAgentDeviceClient, ensureDaemon } from 'agent-device'; +await ensureDaemon(); const client = createAgentDeviceClient({ session: 'checkout-android', leaseProvider: 'browserstack', diff --git a/website/docs/docs/client-api.md b/website/docs/docs/client-api.md index 2389160b23..4cd5b37611 100644 --- a/website/docs/docs/client-api.md +++ b/website/docs/docs/client-api.md @@ -90,18 +90,11 @@ if ('cloudArtifacts' in result) { ## Daemon lifecycle -A client talks to one local daemon per state directory. `daemonLifecycle` says who owns that daemon. +Client calls attach to the local daemon for their state directory without starting, replacing or stopping it, including after a timeout. This includes `client.replay.run()` and `client.replay.test()`. Only CLI/MCP one-shot replay/test operations start and clean up a private daemon. A missing daemon reports `daemon-not-running`; an incompatible daemon reports `daemon-incompatible`. -Close an embedded runtime in its host process with the handle returned by `startAgentDevice()`. `agent-device daemon stop --state-dir ` refuses a live runtime with `error.details.reason: 'daemon-owner-embedded'` and a hint naming the host PID. It sends no request or signal. If the recorded host lifetime has provably exited, `daemon stop` retires its abandoned registration. A record with live unrecognized ownership is also refused, with `daemon-owner-unrecognized`. Without `--clean`, an unreadable `daemon.json` fails with `daemon-record-unreadable`. +To migrate from `daemonLifecycle: 'managed'`, remove that option and call `ensureDaemon({ stateDir })` with the same `stateDir` as the client before creating it, including clients used only for replay/test. To own the daemon in your process instead, use `startAgentDevice()` as shown below. CLI and MCP commands continue to ensure the local daemon when needed. -A `'managed'` client reuses a matching embedded runtime. Takeover, drain, and timeout recovery refuse a live embedded or unrecognized owner without a signal. A provably exited owner is retired so you can reuse the state directory. - -| Mode | What the client does with the daemon | -| --- | --- | -| `'managed'` (default) | Starts a missing daemon, replaces one that does not match the client, and retires an unresponsive one after a timeout. | -| `'attach'` | Connects to the running daemon. Never starts, replaces or stops one, even after a timeout. | - -`'managed'` stays the default until 0.22. Use `'attach'` when your code, or another process, owns the daemon, and call `ensureDaemon()` to start or replace it deliberately: +Close an embedded runtime in its host process with the handle returned by `startAgentDevice()`. `agent-device daemon stop --state-dir ` refuses a live embedded runtime with `daemon-owner-embedded`. If the recorded host lifetime has provably exited, it retires the abandoned registration. A record with live unrecognized ownership is also refused, with `daemon-owner-unrecognized`. ```ts import { createAgentDeviceClient, ensureDaemon } from 'agent-device'; @@ -112,7 +105,7 @@ await ensureDaemon({ stateDir, onStart: (reason, previous) => console.log(`started a daemon: ${reason}`, previous), }); -const client = createAgentDeviceClient({ stateDir, daemonLifecycle: 'attach' }); +const client = createAgentDeviceClient({ stateDir }); ``` `ensureDaemon()` starts a daemon when none runs. It replaces a daemon that does not match the client only if that daemon holds no work: no request in flight, no session, no repair session and no live lease. A resumable upload still streaming and a host human-control hold that names no lease are not counted, so a replacement can end them. Otherwise it fails and leaves the daemon alone. Two cases retire a daemon without that proof, because it cannot be asked: a registered daemon that answers nothing on any transport, and one that times out on the quiesce request and then fails repeated liveness probes. A daemon that accepted the quiesce request is never signaled while it drains: the call waits up to 60 s for it to exit and clear its registration. One still running after that fails repeated liveness probes and is force-retired when its process is provably a daemon. A daemon that still answers, or whose process cannot be proven to be a daemon, fails the call with `daemon-drain-timeout`; a force retirement that cannot be confirmed fails it with `daemon_retirement_unconfirmed`. It returns `{ stateDir, daemon, started }`; `daemon` holds the pid, version and code identity, and no credentials. `onStart` runs when the call started a daemon: `'incompatible'` when it replaced a daemon that agreed to leave, with that daemon as `previous`, and `'missing'` otherwise. A `'missing'` start that also has a `previous` replaced a registered daemon that answered nothing, or one that accepted the request to leave and was force-retired after outlasting its drain. @@ -121,15 +114,15 @@ These failures carry a typed `error.details.reason`: | Reason | Meaning | | --- | --- | -| `daemon-not-running` | An `'attach'` client found no daemon to connect to. Call `ensureDaemon()`. | -| `daemon-incompatible` | The running daemon does not match the client. `details.daemon` and `details.client` hold both identities. For an embedded runtime, close it in its host process. For a detached daemon, use `agent-device daemon stop --state-dir `. Then call `ensureDaemon()`. A daemon from a release that predates quiescing cannot be asked to leave, so `ensureDaemon()` reports it the same way. | +| `daemon-not-running` | A client found no daemon to connect to. Call `ensureDaemon({ stateDir })` for the client's state directory. | +| `daemon-incompatible` | The running daemon does not match the client. `details.daemon` and `details.client` hold both identities. For an embedded runtime, close it in its host process. For a detached daemon, use `agent-device daemon stop --state-dir `. Then call `ensureDaemon({ stateDir })` for that directory. A daemon from a release that predates quiescing cannot be asked to leave, so `ensureDaemon()` reports it the same way. | | `daemon-busy` | `ensureDaemon()` found an incompatible daemon that still holds work. `details` counts `inFlightRequests`, `sessions`, `repairSessions` and `leases`. Wait for them to end and retry. | | `daemon-drain-timeout` | A daemon accepted the request to leave but was still running 60 s later and could not be force-retired, either because it still answers or because its process cannot be proven to be a detached daemon. It was not signaled. Retry once it has exited, or stop it with `agent-device daemon stop --state-dir `. | | `daemon-owner-embedded` | A live host process owns the daemon on `stateDir`, so this client neither replaced it nor retired it, and signaled nothing. A daemon that matches the client is still usable. Close the runtime in its host process with its `close()` handle. | | `daemon-owner-unrecognized` | The record on `stateDir` states an owner this version cannot read, so this client replaced nothing and signaled nothing. Update agent-device if the record comes from a newer build. Otherwise check what owns that process: a host that started it closes it with its own close, and otherwise remove `daemon.json` once that process is gone. | | `daemon-binding-mismatch` | A client pinned to one daemon instance reached another one instead. `details.mismatch` says which: `replaced`, `absent`, or `unaddressable`. Nothing was dispatched, started, or signaled. Take a fresh config from the host that owns the daemon, or start a host of your own. | -`ensureDaemon()` only ever manages the local daemon on `stateDir`. A client with `daemonBaseUrl` never starts or stops a local daemon in either mode, and `daemonLifecycle` does not change `daemonTransport` or `daemonServerMode`. +`ensureDaemon()` only ever manages the local daemon on `stateDir`. A client with `daemonBaseUrl` connects to the remote daemon and does not start or stop a local daemon. ## Running the daemon inside your process @@ -242,7 +235,7 @@ const controller = new AbortController(); await client.interactions.press({ ref: '@e12', signal: controller.signal }); ``` -With the built-in transport, a signal that is already aborted rejects the call without sending anything (`error.details.dispatched: 'no'`). Aborting while the request is in flight closes that request's connection, the daemon marks the request canceled, and the promise rejects with the typed canceled-request error (`error.details.reason: 'request_canceled'`, `error.details.dispatched: 'unknown'`). A custom transport receives the signal on its context and may cancel differently. The daemon and the session stay alive for other requests. On iOS, a command that already reached the device keeps running there, so the daemon holds the session while the device reports it running. Your promise still rejects at once. The hold ends when the device reports the command finished, when the command's own timeout runs out, or when the device cannot confirm the command (it never received it, or the status check fails). Only in the first case is the canceled work known to be over before the session's next request starts. An abort is not a timeout: it never triggers the runner cleanup or daemon reset that a timeout does. Cancellation covers only the daemon request, so a response-artifact download already underway is not stopped, and a canceled one-shot replay still runs the existing cleanup that can tear down a daemon this client started. +With the built-in transport, a signal that is already aborted rejects the call without sending anything (`error.details.dispatched: 'no'`). Aborting while the request is in flight closes that request's connection, the daemon marks the request canceled, and the promise rejects with the typed canceled-request error (`error.details.reason: 'request_canceled'`, `error.details.dispatched: 'unknown'`). A custom transport receives the signal on its context and may cancel differently. The daemon and the session stay alive for other requests. On iOS, a command that already reached the device keeps running there, so the daemon holds the session while the device reports it running. Your promise still rejects at once. The hold ends when the device reports the command finished, when the command's own timeout runs out, or when the device cannot confirm the command (it never received it, or the status check fails). Only in the first case is the canceled work known to be over before the session's next request starts. An abort is not a timeout: it never triggers the runner cleanup or daemon reset that a timeout does. Cancellation covers only the daemon request, so a response-artifact download already underway is not stopped. ```ts await client.command.wait({ diff --git a/website/docs/docs/eve.md b/website/docs/docs/eve.md index 890341c9b6..712a539ff6 100644 --- a/website/docs/docs/eve.md +++ b/website/docs/docs/eve.md @@ -15,7 +15,7 @@ pnpm add agent-device Add `agent/tools/agent_device.ts`: ```ts -import { createAgentDeviceClient } from 'agent-device'; +import { createAgentDeviceClient, ensureDaemon } from 'agent-device'; import { defineTool } from 'eve/tools'; import { z } from 'zod'; @@ -44,6 +44,7 @@ export default defineTool({ }), ]), async execute(input) { + await ensureDaemon(); switch (input.action) { case 'open': return await client.apps.open({ app: input.app, platform: input.platform }); diff --git a/website/docs/docs/testmu.md b/website/docs/docs/testmu.md index 4433c2c06a..cdc59a0260 100644 --- a/website/docs/docs/testmu.md +++ b/website/docs/docs/testmu.md @@ -155,8 +155,9 @@ and releases the lease when a command fails first. Add `providerDeviceType: 'rea The daemon reads `LT_USERNAME` and `LT_ACCESS_KEY` from its environment, unless a JavaScript host passes the plugin `testmu({ credentials })` instead. If you change credentials while the daemon runs, see [Change credentials while the daemon runs](/docs/device-clouds#change-credentials-while-the-daemon-runs). ```ts -import { createAgentDeviceClient } from 'agent-device'; +import { createAgentDeviceClient, ensureDaemon } from 'agent-device'; +await ensureDaemon(); const scope = { session: 'checkout-ios', tenant: 'testmu',