diff --git a/docs/adr/0016-active-session-script-publication.md b/docs/adr/0016-active-session-script-publication.md index 6ab35733c8..a7f4c2937b 100644 --- a/docs/adr/0016-active-session-script-publication.md +++ b/docs/adr/0016-active-session-script-publication.md @@ -6,6 +6,7 @@ Accepted. This ADR is implemented on `main`, including the #1349 identity-level destination-guard amendment. Implementation owners are `packages/daemon/src/sessions/handlers/session-script-publication.ts` and `packages/daemon/src/core/session-script-active-publication.ts`. +Remote delivery (#4511 amendment) is owned by `packages/daemon/src/core/session-script-publication-capability.ts` and, on the client, `packages/remote/src/session-script-destination.ts`. ## Rules at a glance @@ -25,6 +26,9 @@ This section is a normative summary. Every refusal happens before filesystem work and names its recovery. - Repair transactions (ADR 0012) are disjoint from this lifecycle. A session with `saveScriptBoundary` set refuses this action without a change to repair state. +- A remote recording is delivered, not published (#4511 amendment). + Each recorded action refreshes the caller's `--save-script` file, and close overwrites it with the final script. + `session save-script` refuses a remote recording. - `ReplayCommandResult.sessionActive` comes from the daemon's session store, never from a re-parse of the script. This signal lets a one-shot client keep the daemon alive on a close-less handoff. - Sensitive `fill` inputs must be recorded as placeholders through `fill --record-as ` (ADR 0017, shipped for #1348). @@ -172,6 +176,44 @@ This amendment deliberately does not answer one real question: should a *committ The old flag said yes. A change to that answer is a behavior change, not a derivation. +**Amendment (#4511, shipped).** A remote caller cannot read the daemon target, so a remote `open --save-script=` delivers its recording to the caller. +It adds no state name, command, or flag: + +- Before it sends the open, the client mints a random publication ID and records the destination and the `--force` grant under it in its state directory (`remote-connections/session-scripts/`), keyed by the endpoint, the tenant, the session, and that ID. + The open carries the ID in `meta.scriptPublicationId` and never the caller path. + A daemon answer that does not name the ID removes the record. + A failed open may still have armed the recording, so it keeps its record. +- The daemon arms the recording under that ID, which `open` and `close` name in `scriptPublicationId`. + After each successful request that records into the ARMED recording, the daemon writes the recording so far, without a terminal `close`, and returns it as a `session-script` artifact with the ID and a growing `scriptRevision`. + The close-time write is the final version and has the highest revision; close takes it from the close-time write itself, so a capture that close stops first never hides recorded actions. + Each version, the final one included, is a fresh 0600 file in a 0700 directory under the daemon's sessions directory, and is downloaded once. + It registers for download for the tenant that opened the recording, whatever the tenant, capture filters, or network marker of the request that recorded it. +- The client writes a version only to the destination of a record that matches its ID and scope, and only when its revision is newer than the last published one. + The `savedScript` field and the `session-script` type are reserved for this path, so a script artifact under another field writes nothing. + Thus, a daemon response never establishes a destination, and another publication's or another session's version writes nothing. + The download streams, capped at 8 MiB, into a new 0600 file, created exclusively and never through a symbolic link, in a 0700 staging directory beside the destination. + Under the record lock, the record names the version and the staged file's device and inode before the rename or link, and the next version settles that entry from the destination's identity. + A second name keeps the staged inode, and its staging directory, on disk while the record may name it, so no later file can reuse that inode; settling or retiring the entry removes the staging directory. + The record lists each staging directory before a download writes to it, so retiring or sweeping the record also removes the staging that a crashed download left behind. + The first version is linked exclusively, as a local close-time write is, unless the open granted `--force`; a symbolic or hard link at the destination is replaced as a directory entry and never written through. +- If this machine cannot download or save a version, the action also keeps its success and carries the same `scriptDeliveryFailure` and warning; a script delivery failure never changes the outcome of the action that recorded it. +- A close retires the record it names, even when the final version or another artifact fails, and reports the first error. + A record that outlives its open stays inert, because only its own ID matches it; creating a record removes records untouched for seven days. +- If the daemon cannot write a version, the action keeps its success and returns `scriptDeliveryFailure` (`script_delivery_failed`) and a warning without the daemon-host path; the caller file keeps the previous version. + A local close that cannot write its script still fails as before. +- Teardown without `close` writes no daemon file; the caller keeps the version from the last recorded action. +- At the public HTTP boundary, `saveScript` is accepted only as `true` on `open` with a well-formed publication ID. + `session save-script` refuses a remote recording (`remote_script_publication_unsupported`), and remote `close --save-script`, `replay --save-script`, and `--save-script` in batch steps stay refused. + A batch whose steps would close an armed remote recording is refused before any step runs (`remote_script_batch_close_unsupported`), because a batch delivers no script versions from its steps. +- The daemon reports the `script-artifacts` capability in `/health`, through a proxy in its upstream health; the client refuses a remote `--save-script` before dispatch without it. + +The destination keeps local `--save-script` semantics: the client creates a missing parent directory and checks no ancestor ownership, so another local user who can write an ancestor directory can redirect the file, locally and remotely alike (#4565). +Known limitation (#4564): the RPC response is the contract for `scriptDeliveryFailure`; the SDK, CLI, and MCP results do not carry it yet, the SDK close drops its warnings, and a batch delivers no step script versions. +Rejected: a remote `session save-script` download, because it added a second publication path and a retry protocol. +Rejected: delivery only at close, because a session that an external owner closes would lose its recording. +Rejected: daemon-minted recording IDs bound through per-request claims, because the claim, binding, and tombstone protocol cost more than a client-minted ID that only its own client can match. +Consequence: each recorded action of a remote ARMED recording costs one script write and one artifact download. + This lifecycle is distinct from the ADR 0012 repair transaction. `session save-script` rejects a session with `saveScriptBoundary` set. The refusal directs the caller to finish or abort the repair through its existing `replay --from` and teardown commit protocol. diff --git a/packages/command-surface/src/schema/command-overrides.ts b/packages/command-surface/src/schema/command-overrides.ts index ccbf4e7453..691b1dd020 100644 --- a/packages/command-surface/src/schema/command-overrides.ts +++ b/packages/command-surface/src/schema/command-overrides.ts @@ -160,7 +160,7 @@ const SCHEMA_ONLY_CLI_COMMAND_SCHEMAS = { text: { summary: 'Expose a local daemon through an HTTP tunnel', description: - 'Expose the local daemon HTTP contract through a tunnel-friendly reverse proxy.\n\nRun this on the host that has access to simulators/devices, expose the printed local proxy URL through a tunnel, then point another machine at the tunnel URL with connect proxy.\n\nThe proxy starts or reuses a local HTTP daemon, accepts /health, /rpc, /upload and resumable /upload/* routes, and /artifacts plus /artifacts/*, and also accepts the same routes under /agent-device/*. Health is unauthenticated for reachability probes. Other routes require the generated bearer token printed at startup, or the explicit --daemon-auth-token value when provided. The proxy rewrites authorized client requests to the upstream daemon token instead of exposing the local daemon token.\n\nFor a TLS-terminated tunnel, set --public-origin to the public HTTP(S) origin, for example --public-origin https://public.example:8443. Forwarded and X-Forwarded-* headers do not select upload ticket origins. For an ephemeral tunnel, obtain its public name first, then configure and restart the proxy. Without a fixed origin, Node uses the actual socket scheme and validated Host.\n\nUse the /agent-device base path when connecting through cloudflared, ngrok, or another shared origin. Treat the bearer token as a secret; anyone with it can control the proxied daemon. This direct proxy flow does not use agent-device auth.\n\nRemote captures write generated artifacts on the daemon. Screenshot, recording, performance, and trace paths select downloads on the client; they never select host files. Direct RPC callers download returned artifact IDs through /artifacts/. Remote requests ignore client cwd and refuse host tooling paths, --launch-console, and script publication.\n\nExamples:\n cloudflared tunnel --url http://127.0.0.1:4310\n agent-device proxy --port 4310 --public-origin https://example.trycloudflare.com\n agent-device connect proxy --daemon-base-url https://example.trycloudflare.com/agent-device --daemon-auth-token ', + 'Expose the local daemon HTTP contract through a tunnel-friendly reverse proxy.\n\nRun this on the host that has access to simulators/devices, expose the printed local proxy URL through a tunnel, then point another machine at the tunnel URL with connect proxy.\n\nThe proxy starts or reuses a local HTTP daemon, accepts /health, /rpc, /upload and resumable /upload/* routes, and /artifacts plus /artifacts/*, and also accepts the same routes under /agent-device/*. Health is unauthenticated for reachability probes. Other routes require the generated bearer token printed at startup, or the explicit --daemon-auth-token value when provided. The proxy rewrites authorized client requests to the upstream daemon token instead of exposing the local daemon token.\n\nFor a TLS-terminated tunnel, set --public-origin to the public HTTP(S) origin, for example --public-origin https://public.example:8443. Forwarded and X-Forwarded-* headers do not select upload ticket origins. For an ephemeral tunnel, obtain its public name first, then configure and restart the proxy. Without a fixed origin, Node uses the actual socket scheme and validated Host.\n\nUse the /agent-device base path when connecting through cloudflared, ngrok, or another shared origin. Treat the bearer token as a secret; anyone with it can control the proxied daemon. This direct proxy flow does not use agent-device auth.\n\nRemote captures write generated artifacts on the daemon. Screenshot, recording, performance, and trace paths select downloads on the client; they never select host files. Direct RPC callers download returned artifact IDs through /artifacts/. Remote requests ignore client cwd and refuse host tooling paths and --launch-console. A fresh open --save-script= arms recording; after each recorded action the client refreshes that caller file, and close writes the final script there. Remote session save-script, close/replay --save-script, and --save-script in batch steps remain refused.\n\nExamples:\n cloudflared tunnel --url http://127.0.0.1:4310\n agent-device proxy --port 4310 --public-origin https://example.trycloudflare.com\n agent-device connect proxy --daemon-base-url https://example.trycloudflare.com/agent-device --daemon-auth-token ', }, listUsageOverride: 'proxy', allowedFlags: ['proxyHost', 'proxyPort', 'publicOrigin', 'daemonAuthToken', 'stateDir'], diff --git a/packages/contracts/src/daemon-http.ts b/packages/contracts/src/daemon-http.ts index f03dabbdd2..26f063eab7 100644 --- a/packages/contracts/src/daemon-http.ts +++ b/packages/contracts/src/daemon-http.ts @@ -153,6 +153,8 @@ export type DaemonHealthPayload = { rpcProtocolVersion: number; instanceId?: string; hostArch?: string; + /** The subset of `DAEMON_CAPABILITIES` this daemon serves over HTTP; omitted by older daemons. */ + capabilities?: readonly string[]; /** The lease backends this daemon admits; a host checks it before relying on one. */ leaseBackends?: readonly string[]; upstream?: unknown; @@ -165,6 +167,7 @@ export function buildDaemonHealthPayload( upstream?: unknown; instanceId?: string; hostArch?: string; + capabilities?: readonly string[]; leaseBackends?: readonly string[]; } = {}, ): DaemonHealthPayload { @@ -175,6 +178,7 @@ export function buildDaemonHealthPayload( rpcProtocolVersion: DAEMON_RPC_PROTOCOL_VERSION, ...(options.instanceId !== undefined ? { instanceId: options.instanceId } : {}), ...(options.hostArch !== undefined ? { hostArch: options.hostArch } : {}), + ...(options.capabilities !== undefined ? { capabilities: options.capabilities } : {}), ...(options.leaseBackends !== undefined ? { leaseBackends: options.leaseBackends } : {}), ...(options.upstream !== undefined ? { upstream: options.upstream } : {}), }; diff --git a/packages/daemon-client/src/__tests__/daemon-client-lifecycle-recorded-fill.test.ts b/packages/daemon-client/src/__tests__/daemon-client-lifecycle-recorded-fill.test.ts index 006c0d90bb..54c5d0154c 100644 --- a/packages/daemon-client/src/__tests__/daemon-client-lifecycle-recorded-fill.test.ts +++ b/packages/daemon-client/src/__tests__/daemon-client-lifecycle-recorded-fill.test.ts @@ -17,8 +17,7 @@ test('remote fill recording errors give a recovery path the remote client suppor const remote = attachSessionAddressHints(response, {} as never, settings); assert.equal(remote.ok, false); if (remote.ok) return; - assert.match(remote.error.message, /remote clients cannot start one/); - assert.match(remote.error.message, /Connect to a local daemon/); + assert.equal(remote.error.message, response.error.message); assert.equal(remote.error.details?.reason, 'fill_record_as_requires_armed_recording'); const local = attachSessionAddressHints(response, {} as never, {} as never); diff --git a/packages/daemon-client/src/__tests__/index-script-capability.test.ts b/packages/daemon-client/src/__tests__/index-script-capability.test.ts new file mode 100644 index 0000000000..8b39250017 --- /dev/null +++ b/packages/daemon-client/src/__tests__/index-script-capability.test.ts @@ -0,0 +1,103 @@ +import http from 'node:http'; +import path from 'node:path'; +import { expect, test } from 'vitest'; +import { closeLoopbackServer, listenOnLoopback, mkdtempForTestSync } from '@agent-device/test-kit'; +import { DAEMON_HTTP_INSTANCE_MISMATCH_HEADER } from '@agent-device/contracts/daemon-http'; +import { sendToDaemon } from '../index.ts'; + +test.each([ + { name: 'legacy daemon', health: {}, supported: false }, + { + name: 'upgraded proxy with legacy daemon', + health: { capabilities: ['script-artifacts'], upstream: {} }, + supported: false, + }, + { + name: 'upgraded daemon', + health: { capabilities: ['script-artifacts'] }, + supported: true, + }, + { + name: 'forwarding proxy with upgraded daemon', + health: { upstream: { capabilities: ['script-artifacts'] } }, + supported: true, + }, +])('remote recording negotiates $name before dispatch', async ({ health, supported }) => { + let rpcCount = 0; + const server = http.createServer((req, res) => { + res.setHeader('content-type', 'application/json'); + if (req.url === '/health') { + res.end(JSON.stringify({ ok: true, ...health })); + return; + } + rpcCount += 1; + res.end(JSON.stringify({ jsonrpc: '2.0', id: 'test', result: { ok: true, data: {} } })); + }); + const root = mkdtempForTestSync('script-capability-'); + try { + const result = sendToDaemon( + { + command: 'open', + session: 'owned', + positionals: ['Demo'], + flags: { + daemonBaseUrl: `http://127.0.0.1:${await listenOnLoopback(server)}`, + saveScript: path.join(root, 'journey.ad'), + stateDir: path.join(root, 'state'), + }, + }, + { authToken: 'test' }, + ); + if (supported) await expect(result).resolves.toMatchObject({ ok: true }); + else + await expect(result).rejects.toMatchObject({ + code: 'INVALID_ARGS', + details: { reason: 'remote_script_artifacts_unsupported', daemonRequestSent: false }, + }); + expect(rpcCount).toBe(supported ? 1 : 0); + } finally { + await closeLoopbackServer(server); + } +}); + +test('a remote recording is not resent to a replacement daemon that cannot deliver scripts', async () => { + let rpcCount = 0; + let replaced = false; + const server = http.createServer((req, res) => { + res.setHeader('content-type', 'application/json'); + if (req.url === '/health') { + const health = replaced + ? { instanceId: 'legacy' } + : { instanceId: 'capable', capabilities: ['script-artifacts'] }; + res.end(JSON.stringify({ ok: true, ...health })); + return; + } + rpcCount += 1; + replaced = true; + res.statusCode = 409; + res.setHeader(DAEMON_HTTP_INSTANCE_MISMATCH_HEADER, 'true'); + res.end(JSON.stringify({ jsonrpc: '2.0', id: 'test', error: { code: -32000, message: 'x' } })); + }); + const root = mkdtempForTestSync('script-capability-retry-'); + try { + const result = sendToDaemon( + { + command: 'open', + session: 'owned', + positionals: ['Demo'], + flags: { + daemonBaseUrl: `http://127.0.0.1:${await listenOnLoopback(server)}`, + saveScript: path.join(root, 'journey.ad'), + stateDir: path.join(root, 'state'), + }, + }, + { authToken: 'test' }, + ); + await expect(result).rejects.toMatchObject({ + details: { reason: 'remote_script_artifacts_unsupported', daemonRequestSent: false }, + }); + expect(rpcCount).toBe(1); + } finally { + await closeLoopbackServer(server); + } +}); diff --git a/packages/daemon-client/src/daemon-client-lifecycle.ts b/packages/daemon-client/src/daemon-client-lifecycle.ts index 7268be98d0..cfea1614d7 100644 --- a/packages/daemon-client/src/daemon-client-lifecycle.ts +++ b/packages/daemon-client/src/daemon-client-lifecycle.ts @@ -285,6 +285,7 @@ async function ensureRemoteDaemon( hint: 'Fix or unset --daemon-base-url or AGENT_DEVICE_DAEMON_BASE_URL so the client targets a reachable daemon or the local one. If this CLI was connected with connect proxy, run agent-device disconnect to clear the saved connection and return to the local daemon.', }); } + remoteInfo.capabilities = (health.upstream ?? health).capabilities; remoteInfo.remoteInstanceId = health.instanceId; remoteInfo.remoteUpstreamInstanceId = health.upstream?.instanceId; return { info: remoteInfo, startedByClient: false }; @@ -551,19 +552,6 @@ export function attachSessionAddressHints( settings: DaemonClientSettings, ): DaemonResponse { if (!response.ok) { - if ( - settings.remoteBaseUrl && - response.error.details?.reason === 'fill_record_as_requires_armed_recording' - ) { - return { - ...response, - error: { - ...response.error, - message: - 'fill --record-as requires an armed script recording, but remote clients cannot start one. Connect to a local daemon, start a fresh session with open --save-script, then retry the fill, or omit --record-as.', - }, - }; - } return settings.ownedStateDir && isHeldRepairDivergence(response) ? attachRepairSessionAddressHint(response, settings.paths.baseDir) : response; diff --git a/packages/daemon-client/src/daemon-client-rpc.ts b/packages/daemon-client/src/daemon-client-rpc.ts index c96404fa47..859a0a61a8 100644 --- a/packages/daemon-client/src/daemon-client-rpc.ts +++ b/packages/daemon-client/src/daemon-client-rpc.ts @@ -43,7 +43,7 @@ export function handleDaemonHttpResponseBody( ); return; } - void resolveDaemonHttpResult(info, req, parsed.result, host, resolve, reject); + void resolveDaemonHttpResult(info, req, parsed.result, { host, stateDir }, resolve, reject); } catch (err) { reject( new AppError( @@ -155,14 +155,14 @@ async function resolveDaemonHttpResult( info: DaemonInfo, req: DaemonWireRequest, result: DaemonResponse, - host: HostEnvironment, + client: { host: HostEnvironment; stateDir: string }, resolve: (response: DaemonResponse | PromiseLike) => void, reject: (error: unknown) => void, ): Promise { try { resolve( info.baseUrl && result.ok - ? await materializeRemoteArtifacts(info, req, result, host) + ? await materializeRemoteArtifacts(info, req, result, client.host, client.stateDir) : result, ); } catch (error) { diff --git a/packages/daemon-client/src/daemon-client-transport.ts b/packages/daemon-client/src/daemon-client-transport.ts index 1808b54175..efd31c2c46 100644 --- a/packages/daemon-client/src/daemon-client-transport.ts +++ b/packages/daemon-client/src/daemon-client-transport.ts @@ -5,9 +5,11 @@ import net from 'node:net'; import { AppError, createRequestCanceledError } from '@agent-device/kernel/errors'; import { loadNodeHttpRequester, readNodeHttpResponseBody } from '@agent-device/host-kit/transport'; import { emitDiagnostic } from '@agent-device/host-kit/diagnostics'; -import type { - DaemonPaths, - DaemonTransportPreference, +import { + assertScriptArtifactsCapability, + readDaemonCapabilities, + type DaemonPaths, + type DaemonTransportPreference, } from '@agent-device/daemon-contracts/daemon-resolution'; import { readDaemonHttpProgressResponse, @@ -169,6 +171,7 @@ export type RemoteDaemonHealth = { rpcProtocolVersion?: number; instanceId?: string; hostArch?: string; + capabilities?: DaemonInfo['capabilities']; /** The daemon behind a proxy, as the proxy's health reported it. */ upstream?: RemoteDaemonHealthLink; /** The probe ran out of its time budget before an answer, rather than failing outright. */ @@ -177,7 +180,7 @@ export type RemoteDaemonHealth = { type RemoteDaemonHealthLink = Pick< RemoteDaemonHealth, - 'service' | 'version' | 'rpcProtocolVersion' | 'instanceId' | 'hostArch' + 'service' | 'version' | 'rpcProtocolVersion' | 'instanceId' | 'hostArch' | 'capabilities' >; export async function canConnect( @@ -376,6 +379,9 @@ function readHealthLink(parsed: Record): RemoteDaemonHealthLink typeof parsed.rpcProtocolVersion === 'number' ? parsed.rpcProtocolVersion : undefined, ...(typeof parsed.instanceId === 'string' ? { instanceId: parsed.instanceId } : {}), ...(typeof parsed.hostArch === 'string' ? { hostArch: parsed.hostArch } : {}), + ...(parsed.capabilities === undefined + ? {} + : { capabilities: readDaemonCapabilities(parsed.capabilities) }), }; } @@ -500,7 +506,10 @@ async function retryAfterRemoteInstanceMismatch( } info.remoteInstanceId = health.instanceId; info.remoteUpstreamInstanceId = health.upstream?.instanceId; + info.capabilities = (health.upstream ?? health).capabilities; (await loadRemoteHealthCache()).cacheRemoteDaemonHealth(info, health); + // A replacement daemon must still deliver the script that a remote recording asks for. + if (req.meta?.scriptPublicationId) assertScriptArtifactsCapability(info.capabilities); try { return await sendRequestWithTransport(info, req, statePaths, remainingMs, transport, options); } catch (error) { diff --git a/packages/daemon-client/src/index.ts b/packages/daemon-client/src/index.ts index 366c7c67d4..0f3a533c51 100644 --- a/packages/daemon-client/src/index.ts +++ b/packages/daemon-client/src/index.ts @@ -15,6 +15,7 @@ import { resolveCommandTimeoutPolicy } from '@agent-device/command-registry/regi import { resolveCommandRequestTimeoutMs } from '@agent-device/command-registry/timeout-policy'; import { prepareRemoteRequestArtifacts, + sendRemoteScriptOpen, type PreparedRemoteRequest, } from '@agent-device/remote/daemon-artifacts'; import type { DaemonClientSettings, EnsuredDaemon } from './daemon-client-lifecycle.ts'; @@ -154,20 +155,25 @@ async function sendToDaemonOnHost( async () => { const response = await withDiagnosticTimer( 'daemon_request', - async () => - await sendDaemonRequest( - info, - request, - settings.transportPreference, - settings.paths, - requestTimeoutMs, - { - host, - onProgress: options.onProgress, - signal: options.signal, - timeoutRecovery: resolveTimeoutRecovery(settings), - }, - ), + async () => { + const send = (sent: DaemonRequest) => + sendDaemonRequest( + info, + sent, + settings.transportPreference, + settings.paths, + requestTimeoutMs, + { + host, + onProgress: options.onProgress, + signal: options.signal, + timeoutRecovery: resolveTimeoutRecovery(settings), + }, + ); + if (!info.baseUrl || !request.meta?.clientArtifactPaths?.savedScript) + return await send(request); + return await sendRemoteScriptOpen(info, request, settings.paths.baseDir, send); + }, { requestId, command: req.command }, ); return attachSessionAddressHints(response, requestWithoutAuthFlag, settings); diff --git a/packages/daemon-contracts/src/daemon-resolution.ts b/packages/daemon-contracts/src/daemon-resolution.ts index 8248cb7187..22a990dac7 100644 --- a/packages/daemon-contracts/src/daemon-resolution.ts +++ b/packages/daemon-contracts/src/daemon-resolution.ts @@ -148,7 +148,7 @@ export function resolveDaemonTransportPreference( } /** What a daemon can do beyond the base RPC contract, published in its `daemon.json`. */ -export const DAEMON_CAPABILITIES = ['quiesce'] as const; +export const DAEMON_CAPABILITIES = ['quiesce', 'script-artifacts'] as const; export type DaemonCapability = (typeof DAEMON_CAPABILITIES)[number]; /** @@ -270,6 +270,19 @@ export function readDaemonLifecycleFence(input: unknown): DaemonLifecycleFence | return { pid: pid as number, processStartTime }; } +/** + * Refuses a remote `--save-script` before it is sent to a daemon that cannot deliver session + * scripts (ADR 0016), because such a daemon records to its own disk and never delivers. + */ +export function assertScriptArtifactsCapability(capabilities: readonly string[] | undefined): void { + if (capabilities?.includes('script-artifacts')) return; + throw new AppError('INVALID_ARGS', 'The remote daemon cannot deliver session scripts.', { + reason: 'remote_script_artifacts_unsupported', + daemonRequestSent: false, + hint: 'Upgrade the daemon that owns the session. Through a proxy, the upstream daemon must report the script-artifacts capability in its /health response.', + }); +} + export function readDaemonCapabilities(value: unknown): readonly DaemonCapability[] { if (!Array.isArray(value)) return []; return DAEMON_CAPABILITIES.filter((capability) => value.includes(capability)); diff --git a/packages/daemon/src/__tests__/support/session-factories.ts b/packages/daemon/src/__tests__/support/session-factories.ts index b5bb316aef..943f5b6e70 100644 --- a/packages/daemon/src/__tests__/support/session-factories.ts +++ b/packages/daemon/src/__tests__/support/session-factories.ts @@ -25,7 +25,7 @@ export function repairPublication( /** An authoring-variant `scriptPublication` literal for test setups. */ export function authoringPublication( status: 'armed' | 'aborted' | 'published', - opts?: { path?: string; force?: boolean }, + opts?: { path?: string; force?: boolean; remote?: boolean }, ): SessionScriptPublicationState { return { kind: 'authoring', @@ -34,6 +34,9 @@ export function authoringPublication( opts?.path !== undefined ? { kind: 'explicit', path: opts.path, force: opts?.force === true } : { kind: 'default', force: opts?.force === true }, + ...(opts?.remote + ? { remoteDelivery: { publicationId: 'publication-0001', revision: 0, tenantId: undefined } } + : {}), }; } diff --git a/packages/daemon/src/core/__tests__/session-script-publication-capability.test.ts b/packages/daemon/src/core/__tests__/session-script-publication-capability.test.ts new file mode 100644 index 0000000000..fde4b328f3 --- /dev/null +++ b/packages/daemon/src/core/__tests__/session-script-publication-capability.test.ts @@ -0,0 +1,18 @@ +import { expect, test } from 'vitest'; +import { isArmedRemoteRecording } from '../session-script-publication-capability.ts'; +import { + authoringPublication, + makeAuthoringSession, +} from '../../__tests__/support/session-factories.ts'; + +test.each([ + { name: 'an armed remote recording', status: 'armed', remote: true, expected: true }, + { name: 'an armed local recording', status: 'armed', remote: false, expected: false }, + { name: 'an aborted remote recording', status: 'aborted', remote: true, expected: false }, +] as const)('$name is an armed remote recording: $expected', ({ status, remote, expected }) => { + const session = makeAuthoringSession('journey', { + scriptPublication: authoringPublication(status, { remote }), + }); + + expect(isArmedRemoteRecording(session)).toBe(expected); +}); diff --git a/packages/daemon/src/core/__tests__/session-store-teardown-script.test.ts b/packages/daemon/src/core/__tests__/session-store-teardown-script.test.ts index 0368a4248c..7bff2bfb17 100644 --- a/packages/daemon/src/core/__tests__/session-store-teardown-script.test.ts +++ b/packages/daemon/src/core/__tests__/session-store-teardown-script.test.ts @@ -32,3 +32,56 @@ test('teardown of an armed ordinary recording whose script write fails still ret expect(store.retire(ref)).toBe(true); expect(fs.readFileSync(targetPath, 'utf8')).toBe('context platform=ios device="x"\n'); }); + +test('teardown of a remote recording writes no daemon file', () => { + const root = mkdtempForTestSync('agent-device-teardown-remote-script-'); + const store = new SessionStore(path.join(root, 'sessions'), createLiveTestHostEnvironment()); + const targetPath = path.join(root, 'daemon.ad'); + const ref = store.publish( + 'teardown-remote', + makeAuthoringSession('teardown-remote', { + scriptPublication: authoringPublication('armed', { + path: targetPath, + remote: true, + }), + actions: [{ ts: 1, command: 'open', positionals: ['Demo'], flags: {} }], + }), + ); + + store.finalizeRepairTeardown(ref); + expect(fs.existsSync(targetPath)).toBe(false); + expect(store.retire(ref)).toBe(true); +}); + +test.skipIf(process.platform === 'win32')( + 'a remote recording writes each version and its close-time script privately', + () => { + const root = mkdtempForTestSync('agent-device-remote-script-mode-'); + const store = new SessionStore(path.join(root, 'sessions'), createLiveTestHostEnvironment()); + const local = path.join(root, 'local.ad'); + const session = (name: string, remote: boolean) => + store.publish( + name, + makeAuthoringSession(name, { + scriptPublication: authoringPublication('armed', { path: local, remote }), + actions: [{ ts: 1, command: 'open', positionals: ['Demo'], flags: {} }], + }), + ); + const remote = session('remote', true); + + const version = store.writeRemoteScriptVersion(remote); + const closed = store.writeSessionLog(remote); + const localWrite = store.writeSessionLog(session('local', false)); + + const directory = path.join(root, 'sessions', 'remote-scripts'); + expect(fs.statSync(directory).mode & 0o777).toBe(0o700); + for (const result of [version, closed]) { + if (!result.written) throw new Error('remote script not written'); + expect(path.dirname(result.path)).toBe(directory); + expect(fs.statSync(result.path).mode & 0o777).toBe(0o600); + } + expect(localWrite).toMatchObject({ written: true, path: local }); + const umask = process.umask(); + expect(fs.statSync(local).mode & 0o777).toBe(0o666 & ~umask); + }, +); diff --git a/packages/daemon/src/core/capture-output-ownership.ts b/packages/daemon/src/core/capture-output-ownership.ts index d981df3dd8..7f51ff9071 100644 --- a/packages/daemon/src/core/capture-output-ownership.ts +++ b/packages/daemon/src/core/capture-output-ownership.ts @@ -1,4 +1,4 @@ -import type { DaemonResponseData } from '@agent-device/kernel/contracts'; +import type { DaemonArtifact, DaemonResponseData } from '@agent-device/kernel/contracts'; const CAPTURE_OUTPUT_OWNERSHIP = Symbol('captureOutputOwnership'); type CaptureOutputOwnership = 'daemon' | 'caller'; @@ -30,3 +30,30 @@ export function captureOutputTenantId(data: DaemonResponseData): string | undefi const capture: CaptureOutputData = data; return capture[CAPTURE_OUTPUT_OWNERSHIP]?.tenantId; } + +const DAEMON_DELIVERED_ARTIFACT = Symbol('daemonDeliveredArtifact'); +type DeliveredArtifact = DaemonArtifact & { + [DAEMON_DELIVERED_ARTIFACT]?: Readonly<{ tenantId: string | undefined }>; +}; + +/** + * Marks an artifact the daemon produced for the caller itself, such as a remote recording's script + * version. It is registered for download for `tenantId` alone, whatever the request's tenant, + * capture filters, or network marker say. The mark stays private when the response is serialized. + */ +export function asDaemonDeliveredArtifact( + artifact: DaemonArtifact, + tenantId: string | undefined, +): DaemonArtifact { + const delivered: DeliveredArtifact = artifact; + delivered[DAEMON_DELIVERED_ARTIFACT] = { tenantId }; + return delivered; +} + +/** The delivery of a daemon-delivered artifact, or `undefined` for any other artifact. */ +export function daemonDeliveredArtifact( + artifact: DaemonArtifact | undefined, +): Readonly<{ tenantId: string | undefined }> | undefined { + const delivered: DeliveredArtifact | undefined = artifact; + return delivered?.[DAEMON_DELIVERED_ARTIFACT]; +} diff --git a/packages/daemon/src/core/session-script-publication-capability.ts b/packages/daemon/src/core/session-script-publication-capability.ts index c78012816c..b6418f80dc 100644 --- a/packages/daemon/src/core/session-script-publication-capability.ts +++ b/packages/daemon/src/core/session-script-publication-capability.ts @@ -1,4 +1,13 @@ +import path from 'node:path'; import type { CommandFlags } from '@agent-device/contracts/command'; +import type { + DaemonRequestMeta, + DaemonResponse, + ScriptDeliveryFailure, +} from '@agent-device/kernel/contracts'; +import { readResponseWarnings } from '@agent-device/kernel/success-text'; +import type { SessionStore } from './session-store.ts'; +import { asDaemonDeliveredArtifact } from './capture-output-ownership.ts'; import type { SessionState } from './session-state.ts'; import { NO_SCRIPT_PUBLICATION, @@ -11,6 +20,8 @@ import { markAuthoringPublished, resolveScriptTarget, scriptTargetForce, + scriptTargetPath, + type RemoteScriptDelivery, } from './session-script-publication-state.ts'; import { expandSessionPath } from '@agent-device/host-kit/session-paths'; @@ -37,16 +48,37 @@ export function isAuthoringArmedSession(session: SessionState | undefined): bool return state.kind === 'authoring' && state.status === 'armed'; } -/** ADR 0016: `open --save-script[=]` on a fresh session arms ordinary authoring. */ +/** + * ADR 0016: `open --save-script[=]` on a fresh session arms ordinary authoring. A + * remote recording is delivered under the publication ID its caller minted. + */ export function armAuthoringOnOpen( session: SessionState, requested: { path?: string; force?: boolean }, hostCwd: string, + remote?: Omit, ): void { - session.scriptPublication = armAuthoring({ - path: requested.path !== undefined ? expandSessionPath(requested.path, hostCwd) : undefined, - force: requested.force === true, - }); + session.scriptPublication = armAuthoring( + { + path: requested.path !== undefined ? expandSessionPath(requested.path, hostCwd) : undefined, + force: requested.force === true, + }, + remote ? { ...remote, revision: 0 } : undefined, + ); +} + +/** + * The remote delivery an `open --save-script` asks for: the publication ID its client minted, when + * well formed, and the tenant that opens it. + */ +export function remoteScriptOpen( + meta: DaemonRequestMeta | undefined, +): Omit | undefined { + const publicationId = meta?.scriptPublicationId; + if (typeof publicationId !== 'string' || !/^[A-Za-z0-9-]{16,64}$/.test(publicationId)) { + return undefined; + } + return { publicationId, tenantId: meta?.tenantId }; } /** @@ -144,6 +176,19 @@ export function retargetActivePublication( }; } +/** Whether this session records into an armed remote recording that delivers to its caller. */ +export function isArmedRemoteRecording(session: SessionState | undefined): boolean { + return isAuthoringArmedSession(session) && remoteScriptDelivery(session) !== undefined; +} + +/** How a remote caller receives this session's script, if the recording was armed remotely. */ +export function remoteScriptDelivery( + session: SessionState | undefined, +): RemoteScriptDelivery | undefined { + const state = publicationState(session); + return state.kind === 'authoring' ? state.remoteDelivery : undefined; +} + /** Active publication succeeded: PUBLISHED is terminal, which is what stops recording. */ export function markActivePublicationDone(session: SessionState, writtenPath: string): void { session.scriptPublication = markAuthoringPublished(publicationState(session), writtenPath); @@ -174,3 +219,142 @@ export function effectiveWriteForce( export function isSessionScriptPublished(session: SessionState): boolean { return isScriptPublished(publicationState(session)); } + +/** + * The outcome of one script version of a remote recording: the daemon file the caller downloads, + * or why the version could not be written. + */ +type RemoteScriptVersion = + | Readonly<{ path: string }> + | Readonly<{ failure: Readonly<{ message: string; hint: string }> }>; + +/** What a close delivers for a remote recording: the recording it ended and its final version. */ +export type RemoteCloseScript = Readonly<{ + delivery: RemoteScriptDelivery; + version?: RemoteScriptVersion; +}>; + +/** Numbers the next version of a remote recording, so the caller keeps the newest one. */ +function stampNextRevision(session: SessionState): RemoteScriptDelivery | undefined { + const state = session.scriptPublication; + if (state?.kind !== 'authoring' || !state.remoteDelivery) return undefined; + const remoteDelivery = { ...state.remoteDelivery, revision: state.remoteDelivery.revision + 1 }; + session.scriptPublication = { ...state, remoteDelivery }; + return remoteDelivery; +} + +/** + * Adds one script version of a remote recording to a successful response. The artifact carries the + * publication ID and its revision, so the caller writes it only to the destination it recorded and + * keeps the newest version. It registers for the tenant that opened the recording, whoever sent + * this request. A failed version keeps the response successful and carries a typed + * `scriptDeliveryFailure` with the same publication ID and a warning. + */ +function withRemoteScriptVersion( + response: DaemonResponse, + delivery: RemoteScriptDelivery, + version: RemoteScriptVersion, +): DaemonResponse { + if (!response.ok) return response; + const { publicationId } = delivery; + const data = response.data ?? {}; + if ('failure' in version) { + const failure: ScriptDeliveryFailure = { + reason: 'script_delivery_failed', + publicationId, + ...version.failure, + }; + return { + ok: true, + data: { + ...data, + scriptDeliveryFailure: failure, + warnings: [...readResponseWarnings(data), `${failure.message} ${failure.hint}`], + }, + }; + } + const artifact = asDaemonDeliveredArtifact( + { + field: 'savedScript', + artifactType: 'session-script', + path: version.path, + fileName: path.basename(version.path), + scriptPublicationId: publicationId, + scriptRevision: delivery.revision, + }, + delivery.tenantId, + ); + const artifacts = Array.isArray(data.artifacts) ? data.artifacts : []; + return { ok: true, data: { ...data, artifacts: [...artifacts, artifact] } }; +} + +/** + * Captures the session's action count before a request. A successful request that then recorded + * into a remote armed session returns the new script version. When that version cannot be written, + * the action keeps its success and the response discloses the failed delivery. + */ +export function remoteScriptVersionDelivery( + sessionStore: SessionStore, + sessionName: string, +): (response: DaemonResponse) => DaemonResponse { + const before = sessionStore.lookup(sessionName)?.session; + const actionCountBefore = before && remoteScriptDelivery(before) ? before.actions.length : 0; + return (response) => { + if (!response.ok) return response; + const ref = sessionStore.lookup(sessionName); + const delivery = remoteScriptDelivery(ref?.session); + if (!ref || !delivery || ref.session.actions.length === actionCountBefore) return response; + const result = sessionStore.writeRemoteScriptVersion(ref); + if (result.written) { + const stamped = stampNextRevision(ref.session) ?? delivery; + return withRemoteScriptVersion(response, stamped, { path: result.path }); + } + if (!result.error) return response; + // The daemon diagnostic keeps the cause; its daemon-host path stays out of the response. + return withRemoteScriptVersion(response, delivery, { + failure: { + message: 'The action succeeded, but the daemon could not write the remote recording.', + hint: 'The --save-script file keeps the previous version. The next recorded action or close delivers the full recording again.', + }, + }); + }; +} + +/** + * Reads what a close of a remote recording delivers from the session that the close-time write + * just marked, because teardown may have replaced the session object before that write. A + * published final version is stamped after every earlier version, so it replaces the last one. + */ +export function remoteCloseScript( + session: SessionState, + writeFailed: boolean, +): RemoteCloseScript | undefined { + const state = session.scriptPublication; + if (state?.kind !== 'authoring' || !state.remoteDelivery) return undefined; + const delivery = state.remoteDelivery; + if (writeFailed) { + const message = 'The session was closed, but the daemon could not write its final script.'; + const hint = 'The --save-script file keeps the version from the last recorded action.'; + return { delivery, version: { failure: { message, hint } } }; + } + const writtenPath = state.status === 'published' ? scriptTargetPath(state) : undefined; + if (!writtenPath) return { delivery }; + return { delivery: stampNextRevision(session) ?? delivery, version: { path: writtenPath } }; +} + +/** + * A close of a remote recording names the recording it ended, so the caller retires its + * destination even when close publishes nothing, as for an aborted recording. When close could + * not write the final version, the close keeps its success and discloses the failed delivery. + */ +export function remoteCloseScriptDelivery( + response: DaemonResponse, + close: RemoteCloseScript | undefined, +): DaemonResponse { + if (!close || !response.ok) return response; + const named: DaemonResponse = { + ok: true, + data: { ...response.data, scriptPublicationId: close.delivery.publicationId }, + }; + return close.version ? withRemoteScriptVersion(named, close.delivery, close.version) : named; +} diff --git a/packages/daemon/src/core/session-script-publication-state.ts b/packages/daemon/src/core/session-script-publication-state.ts index 037eead69d..8522b237c1 100644 --- a/packages/daemon/src/core/session-script-publication-state.ts +++ b/packages/daemon/src/core/session-script-publication-state.ts @@ -25,6 +25,20 @@ export type SessionScriptTarget = | Readonly<{ kind: 'default'; force: boolean }> | Readonly<{ kind: 'explicit'; path: string; force: boolean }>; +/** + * A remote caller cannot read the daemon target, so each script version is returned as a + * `session-script` artifact. `publicationId` is the ID the caller minted for its open, so the caller + * writes a version only to the destination it recorded under that ID. `revision` numbers the + * versions, so the caller keeps the newest when downloads finish out of order. Only `tenantId`, the + * tenant that opened the recording, can download a version; an open without a tenant registers its + * versions like every other tenant-less artifact. + */ +export type RemoteScriptDelivery = Readonly<{ + publicationId: string; + revision: number; + tenantId: string | undefined; +}>; + /** * ADR 0012 decision 6 repair status. * @@ -47,6 +61,7 @@ export type SessionScriptPublicationState = kind: 'authoring'; status: 'armed' | 'aborted' | 'published'; target: SessionScriptTarget; + remoteDelivery?: RemoteScriptDelivery; }> | Readonly<{ kind: 'repair'; @@ -190,8 +205,14 @@ export function isScriptPublished(state: SessionScriptPublicationState): boolean /** ADR 0016: `open --save-script` on a fresh session arms ordinary authoring. */ export function armAuthoring( requested: Readonly<{ path?: string | undefined; force: boolean }>, + remoteDelivery?: RemoteScriptDelivery, ): SessionScriptPublicationState { - return { kind: 'authoring', status: 'armed', target: resolveScriptTarget(undefined, requested) }; + return { + kind: 'authoring', + status: 'armed', + target: resolveScriptTarget(undefined, requested), + ...(remoteDelivery ? { remoteDelivery } : {}), + }; } /** @@ -212,7 +233,7 @@ export function markAuthoringPublished( ): SessionScriptPublicationState { if (state.kind !== 'authoring') return state; return { - kind: 'authoring', + ...state, status: 'published', target: { kind: 'explicit', path: writtenPath, force: state.target.force }, }; diff --git a/packages/daemon/src/core/session-script-writer.ts b/packages/daemon/src/core/session-script-writer.ts index 10f279261e..be5050e645 100644 --- a/packages/daemon/src/core/session-script-writer.ts +++ b/packages/daemon/src/core/session-script-writer.ts @@ -1,4 +1,5 @@ import type { SessionAction } from '@agent-device/contracts/session'; +import crypto from 'node:crypto'; import fs from 'node:fs'; import path from 'node:path'; import { publicPlatformString } from '@agent-device/kernel/device'; @@ -129,7 +130,9 @@ export class SessionScriptWriter { appendCompleteSentinel: repairArmed, activePublication, }); - scriptPath = this.resolveScriptPath(session); + const remote = + session.scriptPublication?.kind === 'authoring' && session.scriptPublication.remoteDelivery; + scriptPath = remote ? this.remoteScriptPath() : this.resolveScriptPath(session); const scriptDir = path.dirname(scriptPath); if (!fs.existsSync(scriptDir)) fs.mkdirSync(scriptDir, { recursive: true }); // #1258: `options.force` is the caller's already-merged decision @@ -140,6 +143,7 @@ export class SessionScriptWriter { scriptPath, script: prepared.script, force: options?.force, + ...(remote ? { mode: 0o600 } : {}), }); // COMMITTED: idempotent guard above + teardown's abort/tombstone routing. if (repairArmed) { @@ -159,6 +163,18 @@ export class SessionScriptWriter { } } + /** + * A remote recording's caller downloads each version once, so every version, the close-time + * script included, gets a fresh private (0600) file in a private (0700) directory that only the + * daemon user can read. + */ + private remoteScriptPath(): string { + const directory = path.join(this.sessionsDir, 'remote-scripts'); + fs.mkdirSync(directory, { recursive: true, mode: 0o700 }); + fs.chmodSync(directory, 0o700); + return path.join(directory, `${crypto.randomUUID()}.ad`); + } + private resolveScriptPath(session: SessionState): string { const targetPath = scriptTargetPath(session.scriptPublication ?? NO_SCRIPT_PUBLICATION); if (targetPath) { @@ -285,13 +301,15 @@ function publishHealedScriptAtomically(params: { scriptPath: string; script: string; force?: boolean; + mode?: number; }): void { - const { scriptPath, script, force } = params; + const { scriptPath, script, force, mode } = params; try { publishFileSync({ destination: scriptPath, contents: script, publish: force ? 'replace' : 'link-exclusive', + ...(mode === undefined ? {} : { mode }), }); } catch (error) { if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error; diff --git a/packages/daemon/src/core/session-store.ts b/packages/daemon/src/core/session-store.ts index bd83252834..203d1277c2 100644 --- a/packages/daemon/src/core/session-store.ts +++ b/packages/daemon/src/core/session-store.ts @@ -25,7 +25,10 @@ import { type IdleSessionTombstone, } from './session-idle-tombstone.ts'; import { NO_SCRIPT_PUBLICATION, isRepairCommittable } from './session-script-publication-state.ts'; -import { effectiveWriteForce } from './session-script-publication-capability.ts'; +import { + effectiveWriteForce, + remoteScriptDelivery, +} from './session-script-publication-capability.ts'; import { isUncommittedRepairSession, repairSessionSourcePath, @@ -270,6 +273,10 @@ export class SessionStore { return result; } + writeRemoteScriptVersion(ref: SessionRef): SessionScriptWriteResult { + return this.scriptWriter.write(this.requireCurrent(ref)); + } + /** * ADR 0012 decision 6, R7 + commit semantics (C2/C5a, BLOCKER 2/3): the * teardown finalize step for a session (idle-reap or daemon shutdown). @@ -300,6 +307,8 @@ export class SessionStore { finalizeRepairTeardown(ref: SessionRef): void { const session = this.resolveCurrent(ref); if (!session) return; + // The remote caller already holds the latest version; a daemon-side teardown file would be orphaned. + if (remoteScriptDelivery(session)) return; this.recordRepairFinalizeCloseIfCommitting(ref); // #1258: no live request here (idle-reap/daemon-shutdown teardown), so // the only source of `force` is whatever was persisted on the session at diff --git a/packages/daemon/src/server/__tests__/request-finalization.test.ts b/packages/daemon/src/server/__tests__/request-finalization.test.ts index cc2f37d816..94fa4dcc58 100644 --- a/packages/daemon/src/server/__tests__/request-finalization.test.ts +++ b/packages/daemon/src/server/__tests__/request-finalization.test.ts @@ -4,6 +4,7 @@ import { finalizeDaemonResponse } from '../request-finalization.ts'; import type { DaemonRequest } from '../../core/daemon-request.ts'; import type { DaemonArtifactType, DaemonResponse } from '@agent-device/kernel/contracts'; import type { DownloadableArtifactRegistration } from '../../resources/artifact-tracking.ts'; +import { asDaemonDeliveredArtifact } from '../../core/capture-output-ownership.ts'; test('finalizeDaemonResponse preserves handler error hints from details', () => { const req: DaemonRequest = { @@ -384,3 +385,31 @@ test('finalizeDaemonResponse registers no display rotation outside the vocabular expect(tracked).toHaveLength(1); expect(tracked[0]).not.toHaveProperty('displayRotation'); }); + +test.each([ + { name: 'no tenant', requestTenant: undefined }, + { name: 'another tenant', requestTenant: 'tenant-b' }, +])( + 'a daemon-delivered artifact registers for its recording tenant on a request with $name', + ({ requestTenant }) => { + const registrations: DownloadableArtifactRegistration[] = []; + const req: DaemonRequest = { + token: 'token', + session: 'journey', + command: 'wait', + positionals: [], + meta: requestTenant ? { tenantId: requestTenant } : {}, + }; + const script = asDaemonDeliveredArtifact( + { field: 'savedScript', artifactType: 'session-script', path: '/tmp/script.ad' }, + 'tenant-a', + ); + + finalizeDaemonResponse(req, { ok: true, data: { artifacts: [script] } }, (registration) => { + registrations.push(registration); + return 'artifact-id'; + }); + + expect(registrations.map(({ tenantId }) => tenantId)).toEqual(['tenant-a']); + }, +); diff --git a/packages/daemon/src/server/http/daemon-runtime-quiesce.test.ts b/packages/daemon/src/server/http/daemon-runtime-quiesce.test.ts index b1a7944d0f..1d7b93476f 100644 --- a/packages/daemon/src/server/http/daemon-runtime-quiesce.test.ts +++ b/packages/daemon/src/server/http/daemon-runtime-quiesce.test.ts @@ -231,7 +231,7 @@ test('an idle daemon accepts a quiesce, drains and releases its state directory' const published = JSON.parse(fs.readFileSync(paths.infoPath, 'utf8')) as { capabilities?: unknown; }; - expect(published.capabilities).toEqual(['quiesce']); + expect(published.capabilities).toEqual(['quiesce', 'script-artifacts']); expect(await daemon.quiesce()).toEqual({ ok: true, data: { outcome: 'draining' } }); diff --git a/packages/daemon/src/server/http/http-authorization-script-admission.test.ts b/packages/daemon/src/server/http/http-authorization-script-admission.test.ts new file mode 100644 index 0000000000..071a5a8483 --- /dev/null +++ b/packages/daemon/src/server/http/http-authorization-script-admission.test.ts @@ -0,0 +1,62 @@ +import { expect, test } from 'vitest'; +import { DAEMON_HTTP_PUBLIC_NETWORK_ACCESS } from '@agent-device/contracts/daemon-http'; +import { restrictRemoteHttpRequest } from './http-authorization.ts'; +import type { DaemonRequest } from '../../core/daemon-request.ts'; + +const PUBLICATION_ID = '6f1c2a4e-0b7d-4c1e-9a55-3d2f8e7b6a10'; + +function restrict(request: Omit) { + return restrictRemoteHttpRequest( + { token: 'test', session: 'owned', ...request }, + false, + DAEMON_HTTP_PUBLIC_NETWORK_ACCESS, + ); +} + +test('a public open records under the publication ID its client minted', () => { + const result = restrict({ + command: 'open', + positionals: [], + flags: { saveScript: true }, + meta: { scriptPublicationId: PUBLICATION_ID }, + }); + + expect(result.flags?.saveScript).toBe(true); + expect(result.meta?.scriptPublicationId).toBe(PUBLICATION_ID); +}); + +test.each([ + { name: 'an open without a publication ID', command: 'open', flags: { saveScript: true } }, + { + name: 'a malformed publication ID', + command: 'open', + flags: { saveScript: true }, + meta: { scriptPublicationId: '../x' }, + }, + { + name: 'an open host path', + command: 'open', + flags: { saveScript: '/host/a.ad' }, + meta: { scriptPublicationId: PUBLICATION_ID }, + }, + { + name: 'a close', + command: 'close', + flags: { saveScript: true }, + meta: { scriptPublicationId: PUBLICATION_ID }, + }, + { + name: 'an input carrier', + command: 'open', + input: { saveScript: true }, + meta: { scriptPublicationId: PUBLICATION_ID }, + }, + { name: 'an active publication', command: 'session_save_script' }, +])('public script output refuses $name', ({ name: _name, ...request }) => { + expect(() => restrict({ positionals: [], ...request })).toThrowError( + expect.objectContaining({ + code: 'INVALID_ARGS', + details: expect.objectContaining({ reason: 'REMOTE_HOST_INPUT_DENIED' }), + }), + ); +}); diff --git a/packages/daemon/src/server/http/http-server.ts b/packages/daemon/src/server/http/http-server.ts index ac2ccf843d..ddfba3bda6 100644 --- a/packages/daemon/src/server/http/http-server.ts +++ b/packages/daemon/src/server/http/http-server.ts @@ -136,6 +136,7 @@ export async function createDaemonHttpServer(options: { JSON.stringify( buildDaemonHealthPayload('agent-device-daemon', readVersion(), { instanceId, + capabilities: ['script-artifacts'], hostArch, leaseBackends, }), diff --git a/packages/daemon/src/server/remote-host-input-policy.ts b/packages/daemon/src/server/remote-host-input-policy.ts index 4aa9b62e3f..3b866d5108 100644 --- a/packages/daemon/src/server/remote-host-input-policy.ts +++ b/packages/daemon/src/server/remote-host-input-policy.ts @@ -3,9 +3,9 @@ import { INTERNAL_COMMANDS } from '@agent-device/command-registry/catalog'; import { validateAndNormalizeBatchSteps } from '@agent-device/command-registry/batch'; import { DEFAULT_BATCH_MAX_STEPS } from '@agent-device/contracts/command'; import type { DaemonRequest } from '../core/daemon-request.ts'; +import { remoteScriptOpen } from '../core/session-script-publication-capability.ts'; const HOST_PATH_FIELDS = [ - 'saveScript', 'sessionSaveScript', 'launchConsole', 'baseline', @@ -56,9 +56,21 @@ function assertRemoteHostToolingInputs( const hostPath = HOST_PATH_FIELDS.find((field) => fields.some((record) => record && Object.hasOwn(record, field)), ); - if (hostPath || request.command === INTERNAL_COMMANDS.sessionSaveScript) { - throw remoteHostInputDenied(hostPath ?? 'command'); + // A remote recording names no host path: the client keeps its destination and sends the + // publication ID it minted (ADR 0016). + const remoteScript = + request.command === 'open' && + request.flags?.saveScript === true && + remoteScriptOpen(request.meta) !== undefined; + const invalidScript = fields.some( + (record) => + record && Object.hasOwn(record, 'saveScript') && (record !== request.flags || !remoteScript), + ); + if (invalidScript) throw remoteHostInputDenied('saveScript', REMOTE_SCRIPT_PUBLICATION_HINT); + if (hostPath === 'sessionSaveScript' || request.command === INTERNAL_COMMANDS.sessionSaveScript) { + throw remoteHostInputDenied(hostPath ?? 'command', REMOTE_SCRIPT_PUBLICATION_HINT); } + if (hostPath) throw remoteHostInputDenied(hostPath); const hostArgument = findRemoteFileUrlInput(request) ?? findRemoteHostArgument(request); if (hostArgument) throw remoteHostInputDenied(hostArgument); } @@ -146,6 +158,9 @@ function restrictRemoteBatchSteps(request: DaemonRequest): DaemonRequest { flags.batchMaxSteps ?? DEFAULT_BATCH_MAX_STEPS, ); flags.batchSteps = steps.map((step) => { + if (step.flags?.saveScript !== undefined) { + throw remoteHostInputDenied('saveScript', REMOTE_SCRIPT_PUBLICATION_HINT); + } const restricted = restrictRemoteHostInputs({ ...request, ...step }); return { ...step, @@ -181,11 +196,16 @@ function remoteCapturePositionals(request: DaemonRequest): string[] { return positionals; } -function remoteHostInputDenied(field: string): AppError { +const REMOTE_HOST_INPUT_HINT = + 'Omit host paths and download generated output artifacts by ID. Use a local daemon for host tooling.'; +const REMOTE_SCRIPT_PUBLICATION_HINT = + 'Record with open --save-script=: each recorded action and close refresh that file. Use a local daemon for session save-script.'; + +function remoteHostInputDenied(field: string, hint = REMOTE_HOST_INPUT_HINT): AppError { return new AppError('INVALID_ARGS', `Remote requests cannot supply the host input ${field}.`, { reason: 'REMOTE_HOST_INPUT_DENIED', field, retriable: false, - hint: 'Omit host paths and download generated output artifacts by ID. Use a local daemon for host tooling or script publication.', + hint, }); } diff --git a/packages/daemon/src/server/request-execution-scope.ts b/packages/daemon/src/server/request-execution-scope.ts index a030e354dd..4175bdb984 100644 --- a/packages/daemon/src/server/request-execution-scope.ts +++ b/packages/daemon/src/server/request-execution-scope.ts @@ -61,6 +61,7 @@ import { } from './request-execution-locks.ts'; import { isRequestCanceled, throwIfRequestCanceled } from '@agent-device/host-kit/request'; import { finalizeDaemonResponse } from './request-finalization.ts'; +import { remoteScriptVersionDelivery } from '../core/session-script-publication-capability.ts'; import { refreshRecordingHealth } from '../sessions/request-recording-health.ts'; import { runAdmittedLeaseWork } from './request-lease-work.ts'; import { assertMacOsAppLeaseProcess } from '../resources/macos-app-lease.ts'; @@ -739,8 +740,10 @@ export async function prepareLockedRequestScope(params: { // recovery producer below must name — `existingRef.session.name` is only the public name. const existingRef = binding.existingRef; const existingSession = existingRef?.session; + const deliverRemoteScript = remoteScriptVersionDelivery(sessionStore, scope.sessionName); updateDiagnosticsScope({ traceLogPath: existingSession?.trace?.outPath }); - const finalize = (response: DaemonResponse): DaemonResponse => { + const finalize = (handled: DaemonResponse): DaemonResponse => { + const response = deliverRemoteScript(handled); const finalized = finalizeDaemonResponse(lockedReq, response, trackDownloadableArtifact); if (shouldRecordEventForRequest(lockedReq)) { sessionStore.recordEvent( diff --git a/packages/daemon/src/server/request-finalization.ts b/packages/daemon/src/server/request-finalization.ts index 678fa72e30..06b515b4a8 100644 --- a/packages/daemon/src/server/request-finalization.ts +++ b/packages/daemon/src/server/request-finalization.ts @@ -14,7 +14,11 @@ import type { } from '@agent-device/kernel/contracts'; import { isDeviceRotation, type DeviceRotation } from '@agent-device/contracts/device'; import type { TrackDownloadableArtifact } from '../resources/artifact-tracking.ts'; -import { captureOutputOwnership, captureOutputTenantId } from '../core/capture-output-ownership.ts'; +import { + captureOutputOwnership, + captureOutputTenantId, + daemonDeliveredArtifact, +} from '../core/capture-output-ownership.ts'; /** A response artifact plus the capture facts the inventory reports beside it. */ type PendingArtifact = DaemonArtifact & { @@ -92,37 +96,49 @@ function registerDownloadableArtifacts( trackArtifact: TrackDownloadableArtifact, ): DaemonResponseData | undefined { if (!data) return data; - const pendingArtifacts = collectPendingArtifacts(req, data); - if (pendingArtifacts.length === 0) return data; - return { - ...data, - artifacts: pendingArtifacts.map((artifact) => { - const artifactPath = artifact.path as string; - return { - field: artifact.field, - // Omitted (not null/undefined-valued) when untyped, matching the - // optional wire contract on DaemonArtifact. - ...(artifact.artifactType !== undefined ? { artifactType: artifact.artifactType } : {}), - artifactId: trackArtifact({ - artifactPath, - tenantId: captureOutputTenantId(data) ?? req.meta?.tenantId, - artifactType: artifact.artifactType, - fileName: artifact.fileName, - ...(artifact.deleteAfterDownload === false ? { deleteAfterDownload: false } : {}), - ...(isDeviceRotation(artifact.displayRotation) - ? { displayRotation: artifact.displayRotation } - : {}), - }), + const register = (artifact: PendingArtifact): DaemonArtifact => { + const artifactPath = artifact.path as string; + const delivered = daemonDeliveredArtifact(artifact); + return { + field: artifact.field, + // Omitted (not null/undefined-valued) when untyped, matching the + // optional wire contract on DaemonArtifact. + ...(artifact.artifactType !== undefined ? { artifactType: artifact.artifactType } : {}), + artifactId: trackArtifact({ + artifactPath, + tenantId: delivered + ? delivered.tenantId + : (captureOutputTenantId(data) ?? req.meta?.tenantId), + artifactType: artifact.artifactType, fileName: artifact.fileName, - localPath: artifact.localPath, - }; - }), + ...(artifact.deleteAfterDownload === false ? { deleteAfterDownload: false } : {}), + ...(isDeviceRotation(artifact.displayRotation) + ? { displayRotation: artifact.displayRotation } + : {}), + }), + fileName: artifact.fileName, + localPath: artifact.localPath, + scriptPublicationId: artifact.scriptPublicationId, + scriptRevision: artifact.scriptRevision, + }; }; + if (captureOutputOwnership(data) === 'caller') { + // Caller-owned capture output stays at the caller path; a daemon-delivered artifact still registers. + if (!data.artifacts?.some(daemonDeliveredArtifact)) return data; + return { + ...data, + artifacts: data.artifacts.map((item) => + daemonDeliveredArtifact(item) ? register(item) : item, + ), + }; + } + const pendingArtifacts = collectPendingArtifacts(req, data); + if (pendingArtifacts.length === 0) return data; + return { ...data, artifacts: pendingArtifacts.map(register) }; } function collectPendingArtifacts(req: DaemonRequest, data: DaemonResponseData): PendingArtifact[] { const ownership = captureOutputOwnership(data); - if (ownership === 'caller') return []; const artifacts: PendingArtifact[] = Array.isArray(data.artifacts) ? [...data.artifacts] : []; const hasField = (field: string): boolean => artifacts.some((artifact) => artifact?.field === field); @@ -140,6 +156,7 @@ function collectPendingArtifacts(req: DaemonRequest, data: DaemonResponseData): typeof artifact.field === 'string' && typeof artifact.path === 'string' && (ownership === 'daemon' || + daemonDeliveredArtifact(artifact) !== undefined || (req.internal?.publicNetworkOnly && !['record', 'perf', 'trace'].includes(req.command)) || (typeof artifact.localPath === 'string' && artifact.localPath.length > 0) || (artifact.field === 'fallbackScreenshotPath' && artifact.artifactType === 'screenshot')), diff --git a/packages/daemon/src/server/request-router.ts b/packages/daemon/src/server/request-router.ts index 28f9d8e7e6..899038a363 100644 --- a/packages/daemon/src/server/request-router.ts +++ b/packages/daemon/src/server/request-router.ts @@ -905,9 +905,21 @@ function applyResponseLevelView( const level = req.meta?.responseLevel ?? 'default'; if (level === 'default') return response; const view = RESPONSE_VIEWS[req.command]; - return view ? { ok: true, data: view(response.data ?? {}, level) } : response; + if (!view) return response; + const data = response.data ?? {}; + // A view narrows a command's own result; remote script delivery facts are not part of it. + const delivery = Object.fromEntries( + SCRIPT_DELIVERY_FIELDS.filter((field) => data[field] !== undefined).map((field) => [ + field, + data[field], + ]), + ); + return { ok: true, data: { ...view(data, level), ...delivery } }; } +/** The remote recording facts (ADR 0016) that every response level keeps. */ +const SCRIPT_DELIVERY_FIELDS = ['scriptPublicationId', 'scriptDeliveryFailure'] as const; + // Diagnostic phases emitted once per real iOS-runner round-trip. `..._command_send` // is the command itself; `..._readiness_preflight` is the pre-command uptime probe // (a real network round-trip). The `..._skipped` / `..._recovered` markers do NOT diff --git a/packages/daemon/src/sessions/handlers/__tests__/session-batch.test.ts b/packages/daemon/src/sessions/handlers/__tests__/session-batch.test.ts new file mode 100644 index 0000000000..73a6e69f03 --- /dev/null +++ b/packages/daemon/src/sessions/handlers/__tests__/session-batch.test.ts @@ -0,0 +1,58 @@ +import { expect, test, vi } from 'vitest'; +import type { DaemonRequest } from '../../../core/daemon-request.ts'; +import { runBatchCommands } from '../session-batch.ts'; + +function batch(...commands: string[]): DaemonRequest { + return { + token: 't', + session: 'journey', + command: 'batch', + positionals: [], + flags: { batchSteps: commands.map((command) => ({ command, positionals: [] })) }, + }; +} + +const refused = { + ok: false, + error: expect.objectContaining({ + code: 'INVALID_ARGS', + details: expect.objectContaining({ reason: 'remote_script_batch_close_unsupported' }), + }), +}; + +test.each([ + { name: 'close', close: 'close' }, + { name: 'a close spelled differently', close: ' CLOSE ' }, +])('a batch with $name in an armed remote recording runs no step', async ({ close }) => { + const invoke = vi.fn(async () => ({ ok: true as const, data: {} })); + + await expect(runBatchCommands(batch('wait', close), 'journey', invoke, true)).resolves.toEqual( + refused, + ); + expect(invoke).not.toHaveBeenCalled(); +}); + +test.each([ + { name: 'a remote recording batch without close', commands: ['wait'], remote: true }, + { + name: 'a batch with close outside a remote recording', + commands: ['wait', 'close'], + remote: false, + }, +])('$name runs its steps', async ({ commands, remote }) => { + const invoke = vi.fn(async () => ({ ok: true as const, data: {} })); + + await runBatchCommands(batch(...commands), 'journey', invoke, remote); + + expect(invoke).toHaveBeenCalledTimes(commands.length); +}); + +test('malformed steps get the batch refusal', async () => { + const invoke = vi.fn(async () => ({ ok: true as const, data: {} })); + const req = { ...batch('wait'), flags: { batchSteps: 'close' } } as unknown as DaemonRequest; + + await expect(runBatchCommands(req, 'journey', invoke, true)).resolves.toMatchObject({ + ok: false, + error: { code: 'INVALID_ARGS' }, + }); +}); diff --git a/packages/daemon/src/sessions/handlers/__tests__/session-script-publication.test.ts b/packages/daemon/src/sessions/handlers/__tests__/session-script-publication.test.ts index c21f8f87b8..07b498bc8f 100644 --- a/packages/daemon/src/sessions/handlers/__tests__/session-script-publication.test.ts +++ b/packages/daemon/src/sessions/handlers/__tests__/session-script-publication.test.ts @@ -348,3 +348,26 @@ test('refuses mutating find steps that cannot enforce target identity on replay' }); expect(fs.existsSync(path.dirname(outputPath))).toBe(false); }); + +test('a remote recording refuses active publication and stays armed for close', () => { + const outputPath = path.join(root, 'remote', 'screen-x.ad'); + const session = armedSession({ + scriptPublication: authoringPublication('armed', { + path: outputPath, + remote: true, + }), + }); + store.publish('authoring', session); + expect( + handleSessionScriptPublication({ + req: request(), + sessionName: 'authoring', + sessionStore: store, + }), + ).toMatchObject({ + ok: false, + error: { details: { reason: 'remote_script_publication_unsupported' } }, + }); + expect(session.scriptPublication).toMatchObject({ status: 'armed' }); + expect(fs.existsSync(path.dirname(outputPath))).toBe(false); +}); diff --git a/packages/daemon/src/sessions/handlers/__tests__/session.test.ts b/packages/daemon/src/sessions/handlers/__tests__/session.test.ts index ee5c1e3880..9b90574dfb 100644 --- a/packages/daemon/src/sessions/handlers/__tests__/session.test.ts +++ b/packages/daemon/src/sessions/handlers/__tests__/session.test.ts @@ -1,11 +1,15 @@ import { daemonPlatformServicesFixture } from '../../../__tests__/support/platform-services-fixture.ts'; -import { expect, test } from 'vitest'; +import { expect, test, vi } from 'vitest'; import * as path from 'node:path'; import { handleSessionCommands } from '../../../__tests__/support/handlers/session-command-harness.ts'; import { makeSessionStore } from '../../../__tests__/support/store-factory.ts'; import { mkdtempForTestSync, createTestHostEnvironment } from '@agent-device/test-kit'; import { fakeCreateCommandSurface } from '../../../__tests__/support/command-surface-fake.ts'; import type { DaemonRequest } from '../../../core/daemon-request.ts'; +import { + authoringPublication, + makeAuthoringSession, +} from '../../../__tests__/support/session-factories.ts'; function request(command: string): DaemonRequest { return { token: 't', session: 'default', command, positionals: [], flags: {} }; @@ -41,3 +45,35 @@ test('the session router maps boot, shutdown and appstate straight to their hand expect(response.error.code, command).toBe('INVALID_ARGS'); } }); + +test('the session router refuses a batch that would close an armed remote recording', async () => { + const sessionStore = makeSessionStore('agent-device-batch-route-'); + sessionStore.publish( + 'journey', + makeAuthoringSession('journey', { + scriptPublication: authoringPublication('armed', { remote: true }), + }), + ); + const invoke = vi.fn(async () => ({ ok: true as const, data: {} })); + + const response = await handleSessionCommands({ + host: createTestHostEnvironment(), + createCommandSurface: fakeCreateCommandSurface, + platformServices: daemonPlatformServicesFixture(), + req: { + ...request('batch'), + session: 'journey', + flags: { batchSteps: [{ command: 'wait', positionals: ['100'] }, { command: 'close' }] }, + }, + sessionName: 'journey', + logPath: path.join(mkdtempForTestSync('daemon'), 'daemon.log'), + sessionStore, + invoke, + }); + + expect(response).toMatchObject({ + ok: false, + error: { details: { reason: 'remote_script_batch_close_unsupported' } }, + }); + expect(invoke).not.toHaveBeenCalled(); +}); diff --git a/packages/daemon/src/sessions/handlers/session-batch.ts b/packages/daemon/src/sessions/handlers/session-batch.ts index d6407d6575..e964d3a500 100644 --- a/packages/daemon/src/sessions/handlers/session-batch.ts +++ b/packages/daemon/src/sessions/handlers/session-batch.ts @@ -1,4 +1,5 @@ import type { DaemonResponse } from '@agent-device/kernel/contracts'; +import { AppError } from '@agent-device/kernel/errors'; import { runBatch } from '@agent-device/command-registry/batch'; import type { DaemonInvokeFn, DaemonRequest } from '../../core/daemon-request.ts'; @@ -6,9 +7,23 @@ export async function runBatchCommands( req: DaemonRequest, sessionName: string, invoke: DaemonInvokeFn, + armedRemoteRecording = false, ): Promise { return await runBatch(req, sessionName, async (stepRequest, context) => { const step = stepRequest as DaemonRequest; + // ADR 0016: a batch delivers no script versions from its steps, so a step that closes an armed + // remote recording would lose the final script. The normalized steps are checked before the + // first one runs. + if ( + armedRemoteRecording && + context.stepNumber === 1 && + [step, ...context.remainingSteps].some((planned) => planned.command === 'close') + ) { + throw new AppError('INVALID_ARGS', 'A batch cannot close a remote script recording.', { + reason: 'remote_script_batch_close_unsupported', + hint: 'Run close on its own after the batch, so the final script reaches the --save-script file.', + }); + } return await invoke({ ...step, internal: { diff --git a/packages/daemon/src/sessions/handlers/session-script-publication.ts b/packages/daemon/src/sessions/handlers/session-script-publication.ts index 89889ce656..806a36857e 100644 --- a/packages/daemon/src/sessions/handlers/session-script-publication.ts +++ b/packages/daemon/src/sessions/handlers/session-script-publication.ts @@ -6,6 +6,7 @@ import { effectiveWriteForce, isAuthoringArmedSession, markActivePublicationDone, + remoteScriptDelivery, retargetActivePublication, } from '../../core/session-script-publication-capability.ts'; import { isRepairArmedSession } from '../../core/session-replay-transaction.ts'; @@ -74,11 +75,12 @@ export function handleSessionScriptPublication(params: { }; } -type PublicationIneligibility = 'repair' | 'aborted' | 'published' | 'not-armed'; +type PublicationIneligibility = 'repair' | 'remote' | 'aborted' | 'published' | 'not-armed'; /** Why this session cannot publish its active recording, or `undefined` when it can. */ function publicationIneligibility(session: SessionState): PublicationIneligibility | undefined { if (isRepairArmedSession(session)) return 'repair'; + if (remoteScriptDelivery(session)) return 'remote'; const state = session.scriptPublication; if (state?.kind === 'authoring' && state.status !== 'armed') return state.status; return isAuthoringArmedSession(session) ? undefined : 'not-armed'; @@ -93,6 +95,15 @@ const PUBLICATION_INELIGIBILITY_ERRORS: Record A hint: 'Finish or abort the repair through replay --from and its existing close/teardown protocol.', }, ), + remote: () => + new AppError( + 'COMMAND_FAILED', + 'A remote recording is delivered to its --save-script path, not published from the session.', + { + reason: 'remote_script_publication_unsupported', + hint: 'The --save-script file already holds the recording through the last action, and close writes the final script there.', + }, + ), aborted: () => new AppError( 'COMMAND_FAILED', diff --git a/packages/daemon/src/sessions/handlers/session.ts b/packages/daemon/src/sessions/handlers/session.ts index e3dbd80e07..2a9290787a 100644 --- a/packages/daemon/src/sessions/handlers/session.ts +++ b/packages/daemon/src/sessions/handlers/session.ts @@ -7,6 +7,7 @@ import { } from '../../execution/handlers/session-selector-dispatch.ts'; import { handleSessionAppDeploymentCommand } from './session-app-deployment-route.ts'; import { runBatchCommands } from './session-batch.ts'; +import { isArmedRemoteRecording } from '../../core/session-script-publication-capability.ts'; import { handleSessionCloseCommands } from '../session-lifecycle/internal/session-close.ts'; import { handleSessionInventoryCommands } from '../session-lifecycle/internal/inventory.ts'; import { handleSessionOpenCommands } from '../session-lifecycle/internal/session-open.ts'; @@ -202,7 +203,13 @@ const SESSION_COMMAND_HANDLER_IMPLS = { open: handleSessionOpenCommandGroup, replay: handleReplayCommand, test: handleReplayTestCommand, - batch: async ({ req, sessionName, invoke }) => await runBatchCommands(req, sessionName, invoke), + batch: async ({ req, sessionName, sessionStore, invoke }) => + await runBatchCommands( + req, + sessionName, + invoke, + isArmedRemoteRecording(sessionStore.get(sessionName)), + ), close: handleSessionCloseCommandGroup, } satisfies Record; diff --git a/packages/daemon/src/sessions/session-lifecycle/internal/__tests__/session-close-script.test.ts b/packages/daemon/src/sessions/session-lifecycle/internal/__tests__/session-close-script.test.ts index 4b9bb192ec..0b38fb0b83 100644 --- a/packages/daemon/src/sessions/session-lifecycle/internal/__tests__/session-close-script.test.ts +++ b/packages/daemon/src/sessions/session-lifecycle/internal/__tests__/session-close-script.test.ts @@ -104,7 +104,7 @@ test('ordinary publication failure retains its close action after making the err ref, sessionStore, platformCloseError: undefined, - }); + }).error; expect(session.actions.map(({ command }) => command)).toEqual(['close']); expect(result).toMatchObject({ @@ -131,7 +131,7 @@ test('ordinary close keeps the inner hint for a failure reason it does not own', ref, sessionStore, platformCloseError: undefined, - }); + }).error; expect(result?.details).toMatchObject({ reason: 'unportable_ref', @@ -163,7 +163,7 @@ test('#1533: bare close on an aborted authoring session writes no script', () => ref, sessionStore, platformCloseError: undefined, - }), + }).error, ).toBeUndefined(); expect(sessionStore.get('aborted')?.scriptPublication).toEqual(authoringPublication('aborted')); @@ -186,7 +186,7 @@ test('#1533: an ordinary armed authoring session still publishes on bare close', ref, sessionStore, platformCloseError: undefined, - }), + }).error, ).toBeUndefined(); expect(fs.readdirSync(sessionsDir)).toHaveLength(1); @@ -213,7 +213,7 @@ test('ordinary close reports a filesystem failure of its script write instead of ref, sessionStore, platformCloseError: undefined, - }); + }).error; expect(result).toBeInstanceOf(AppError); expect(result).toMatchObject({ diff --git a/packages/daemon/src/sessions/session-lifecycle/internal/session-close-lifecycle-teardown.ts b/packages/daemon/src/sessions/session-lifecycle/internal/session-close-lifecycle-teardown.ts index 8a663bc6d4..7617fe4f34 100644 --- a/packages/daemon/src/sessions/session-lifecycle/internal/session-close-lifecycle-teardown.ts +++ b/packages/daemon/src/sessions/session-lifecycle/internal/session-close-lifecycle-teardown.ts @@ -3,6 +3,7 @@ import { inspectSessionLeaseRetainedOnClose } from '../../lease-lifecycle.ts'; import type { CloseApplicationFinalizationResult } from '@agent-device/contracts/application-lifecycle-runtime'; import type { TargetShutdownResult } from '@agent-device/contracts/device'; import type { DaemonRequest } from '../../../core/daemon-request.ts'; +import type { OrdinaryCloseScript } from './session-close-script.ts'; import type { SessionRef, SessionState } from '../../../core/session-state.ts'; import { SessionStore } from '../../../core/session-store.ts'; import { cleanupRetainedMaterializedPathsForSession } from '../../materialized-path-registry.ts'; @@ -29,7 +30,7 @@ export type PlatformCloseDispatcher = (params: { export type SessionCloseTeardownResult = Readonly<{ platformCloseError: unknown; retainExecutionHost: boolean; - saveScriptError?: Error; + saveScriptOutcome: OrdinaryCloseScript; shutdownResult?: TargetShutdownResult; shutdownPrepared: boolean; }>; @@ -51,7 +52,7 @@ export async function runSessionCloseTeardown(params: { ref: SessionRef; sessionStore: SessionStore; platformCloseError: unknown; - }): Error | undefined; + }): OrdinaryCloseScript; platformResourceCleanup: PlatformResourceCleanup; }): Promise { const { @@ -124,8 +125,8 @@ export async function runSessionCloseTeardown(params: { shutdownTarget: req.flags?.shutdown === true && lifecycle.owner.kind === 'local-family', })) ?? {}, ); - const saveScriptError = repairArmed - ? undefined + const saveScriptOutcome = repairArmed + ? {} : finalizeOrdinaryCloseScript({ req, ref, sessionStore, platformCloseError }); await attemptCleanup('materialized_paths', () => cleanupRetainedMaterializedPathsForSession(sessionName), @@ -133,7 +134,7 @@ export async function runSessionCloseTeardown(params: { return { platformCloseError, retainExecutionHost, - saveScriptError, + saveScriptOutcome, shutdownResult: finalization?.shutdown, shutdownPrepared: finalization !== undefined, }; diff --git a/packages/daemon/src/sessions/session-lifecycle/internal/session-close-script.ts b/packages/daemon/src/sessions/session-lifecycle/internal/session-close-script.ts index 7f78ca6e69..cd9407d53d 100644 --- a/packages/daemon/src/sessions/session-lifecycle/internal/session-close-script.ts +++ b/packages/daemon/src/sessions/session-lifecycle/internal/session-close-script.ts @@ -13,6 +13,8 @@ import { effectiveWriteForce, isSessionScriptPublished, markCloseGeneratedPublicationDone, + remoteCloseScript, + type RemoteCloseScript, } from '../../../core/session-script-publication-capability.ts'; import { abortRepairTransaction, @@ -80,12 +82,18 @@ export function buildRetriableRepairCloseFailureResponse( }; } +/** + * The close-time script write. A local failure is `error`, which fails the close. A remote + * recording's outcome, including a failed write, is `remote`, which the close discloses instead. + */ +export type OrdinaryCloseScript = Readonly<{ error?: AppError; remote?: RemoteCloseScript }>; + export function finalizeOrdinaryCloseScript(params: { req: DaemonRequest; ref: SessionRef; sessionStore: SessionStore; platformCloseError: unknown; -}): AppError | undefined { +}): OrdinaryCloseScript { const { req, ref, sessionStore, platformCloseError } = params; const session = sessionStore.requireCurrent(ref); if (!platformCloseError) { @@ -98,11 +106,11 @@ export function finalizeOrdinaryCloseScript(params: { const result = sessionStore.writeSessionLog(ref, { force: effectiveWriteForce(session, req.flags?.force), }); - if (result.written) { - markCloseGeneratedPublicationDone(session, result.path); - return undefined; - } - return result.error ? toOrdinaryCloseSaveScriptFailure(result.error) : undefined; + if (result.written) markCloseGeneratedPublicationDone(session, result.path); + const error = + !result.written && result.error ? toOrdinaryCloseSaveScriptFailure(result.error) : undefined; + const remote = remoteCloseScript(session, error !== undefined); + return remote ? { remote } : { error }; } function toOrdinaryCloseSaveScriptFailure(error: AppError): AppError { diff --git a/packages/daemon/src/sessions/session-lifecycle/internal/session-close.ts b/packages/daemon/src/sessions/session-lifecycle/internal/session-close.ts index ba8459ee6e..8add840bc0 100644 --- a/packages/daemon/src/sessions/session-lifecycle/internal/session-close.ts +++ b/packages/daemon/src/sessions/session-lifecycle/internal/session-close.ts @@ -19,7 +19,11 @@ import { isRepairArmedSession, recordRepairPlatformClose, } from '../../../core/session-replay-transaction.ts'; -import { isAuthoringArmedSession } from '../../../core/session-script-publication-capability.ts'; +import { + isAuthoringArmedSession, + remoteCloseScriptDelivery, + type RemoteCloseScript, +} from '../../../core/session-script-publication-capability.ts'; import type { SessionCleanupFailure } from '../../session-teardown.ts'; import { isWebSession } from '../../web-session-names.ts'; import { clearDeviceClaim } from '@agent-device/daemon-contracts/device-claims'; @@ -354,13 +358,14 @@ export async function handleSessionCloseCommands( }), ); if (closed.kind === 'response') return closed.response; - return buildCloseSuccessResponse({ + const response = buildCloseSuccessResponse({ session, repair, requestedSaveScript: Boolean(req.flags?.saveScript), shutdownResult: closed.shutdownResult, providerData: closed.providerData, }); + return remoteCloseScriptDelivery(response, closed.remoteScript); } /** @@ -386,6 +391,8 @@ type SessionCloseFinalization = kind: 'closed'; providerData?: Record; shutdownResult?: TargetShutdownResult; + /** What close delivers for a remote recording, taken from the close-time write (ADR 0016). */ + remoteScript?: RemoteCloseScript; }; // Everything between a settled repair decision and a success response: @@ -422,7 +429,7 @@ async function runCloseTeardownAndRelease(params: { const { platformCloseError, retainExecutionHost, - saveScriptError, + saveScriptOutcome, shutdownPrepared, shutdownResult, } = await runSessionCloseTeardown({ @@ -478,11 +485,12 @@ async function runCloseTeardownAndRelease(params: { if (!closeError) await clearDeviceClaim(session.deviceClaim, params.env); sessionStore.retire(ref, { retainExecutionHost }); if (closeError) throw closeError; - if (saveScriptError) throw saveScriptError; + if (saveScriptOutcome.error) throw saveScriptOutcome.error; return { kind: 'closed', providerData: leaseRelease.providerData, shutdownResult: leaseRelease.shutdownResult ?? shutdownResult, + remoteScript: saveScriptOutcome.remote, }; } diff --git a/packages/daemon/src/sessions/session-lifecycle/internal/session-open-execution.ts b/packages/daemon/src/sessions/session-lifecycle/internal/session-open-execution.ts index 977911dfe1..a6d2b9eee0 100644 --- a/packages/daemon/src/sessions/session-lifecycle/internal/session-open-execution.ts +++ b/packages/daemon/src/sessions/session-lifecycle/internal/session-open-execution.ts @@ -30,6 +30,7 @@ import { abortAuthoringOnSecondOpen, armAuthoringOnOpen, isAuthoringArmedSession, + remoteScriptOpen, } from '../../../core/session-script-publication-capability.ts'; import { isRequestCanceled } from '@agent-device/host-kit/request'; import { @@ -93,6 +94,7 @@ function applyOrdinaryScriptRecordingOpenOutcome(params: { session: SessionState; existingSession: SessionState | undefined; saveScriptRequested: boolean; + remoteDelivery: Parameters[3]; responseData: Record; hostCwd: string; }): void { @@ -100,7 +102,9 @@ function applyOrdinaryScriptRecordingOpenOutcome(params: { if (!existingSession && saveScriptRequested) { // The recorded `open` action's flag ingress applies the explicit path/force right after // this arm (`applyRecordedSaveScriptFlags`), exactly as the field writers used to split it. - armAuthoringOnOpen(session, {}, hostCwd); + armAuthoringOnOpen(session, {}, hostCwd, params.remoteDelivery); + const publicationId = params.remoteDelivery?.publicationId; + if (publicationId) responseData.scriptPublicationId = publicationId; return; } if (!isAuthoringArmedSession(existingSession)) return; @@ -406,6 +410,7 @@ export async function completeOpenCommand(params: { session: nextSession, existingSession: existingRef ? nextSession : undefined, saveScriptRequested: Boolean(req.flags?.saveScript), + remoteDelivery: remoteScriptOpen(req.meta), responseData: openResult, hostCwd: sessionStore.host.cwd, }); diff --git a/packages/kernel/src/contracts.ts b/packages/kernel/src/contracts.ts index 40f94588ae..9aa591d1dc 100644 --- a/packages/kernel/src/contracts.ts +++ b/packages/kernel/src/contracts.ts @@ -157,6 +157,8 @@ export type DaemonRequestMeta = { sessionIsolation?: SessionIsolationMode; uploadedArtifactId?: string; clientArtifactPaths?: Record; + /** The ID a remote client minted for its `open --save-script`; each script version carries it. */ + scriptPublicationId?: string; installSource?: DaemonInstallSource; retainMaterializedPaths?: boolean; materializedPathRetentionMs?: number; @@ -185,7 +187,8 @@ export type DaemonArtifactKnownType = | 'screen-recording-contact-sheet' | 'screen-recording-telemetry' | 'trace-log' - | 'test-artifacts'; + | 'test-artifacts' + | 'session-script'; export type DaemonArtifactType = DaemonArtifactKnownType | (string & {}); @@ -200,6 +203,23 @@ export type DaemonArtifact = { fileName?: string; localPath?: string; path?: string; + /** The remote `open --save-script` publication a `session-script` artifact belongs to. */ + scriptPublicationId?: string; + /** A `session-script` version number. Versions of one recording grow, so the newest one wins. */ + scriptRevision?: number; +}; + +/** + * A remote recording's script version that was not delivered (ADR 0016). The action that recorded + * it keeps its success; the response carries this beside a warning with the same text. + */ +export type ScriptDeliveryFailure = { + reason: 'script_delivery_failed'; + publicationId: string; + message: string; + hint: string; + /** Why the client could not download or save the version, when the client found the failure. */ + cause?: string; }; export type ResponseCost = { diff --git a/packages/remote/src/__tests__/artifact-download.test.ts b/packages/remote/src/__tests__/artifact-download.test.ts index 2490f83eb7..f49f2008b0 100644 --- a/packages/remote/src/__tests__/artifact-download.test.ts +++ b/packages/remote/src/__tests__/artifact-download.test.ts @@ -234,3 +234,50 @@ test('rejects redirect bodies and interrupted error bodies, and downloads succes fs.rmSync(tempRoot, { recursive: true, force: true }); } }); + +test('a private file that cannot be opened releases the response', async (t) => { + if (await skipWhenLoopbackUnavailable(t, 'artifact download response release')) return; + const tempRoot = mkdtempForTestSync('agent-device-artifact-private-open-'); + const destinationPath = path.join(tempRoot, 'script.ad'); + fs.symlinkSync(path.join(tempRoot, 'elsewhere.ad'), destinationPath); + let released: () => void = () => {}; + const responseReleased = new Promise((resolve) => { + released = resolve; + }); + const server = http.createServer((_req, res) => { + res.on('close', released); + res.writeHead(200); + const write = () => { + if (!res.destroyed) res.write('x'.repeat(1024), () => setTimeout(write, 5)); + }; + write(); + }); + const port = await listenOnLoopback(server); + + try { + await assert.rejects(() => + downloadTo(tempRoot, port, { destinationPath, privateFile: { maxBytes: 1024 * 1024 } }), + ); + await responseReleased; + assert.equal(fs.existsSync(path.join(tempRoot, 'elsewhere.ad')), false); + } finally { + await closeLoopbackServer(server); + } +}); + +test('a private file download never recreates a removed staging directory', async (t) => { + if (await skipWhenLoopbackUnavailable(t, 'private artifact download parent')) return; + const tempRoot = mkdtempForTestSync('agent-device-artifact-private-parent-'); + const destinationPath = path.join(tempRoot, 'retired-staging', 'script.ad'); + const server = http.createServer((_req, res) => res.end('open Demo\n')); + const port = await listenOnLoopback(server); + + try { + await assert.rejects(() => + downloadTo(tempRoot, port, { destinationPath, privateFile: { maxBytes: 1024 } }), + ); + assert.equal(fs.existsSync(path.dirname(destinationPath)), false); + } finally { + await closeLoopbackServer(server); + } +}); diff --git a/packages/remote/src/__tests__/daemon-artifacts-capture.test.ts b/packages/remote/src/__tests__/daemon-artifacts-capture.test.ts index 25e418ff9a..e8971e6356 100644 --- a/packages/remote/src/__tests__/daemon-artifacts-capture.test.ts +++ b/packages/remote/src/__tests__/daemon-artifacts-capture.test.ts @@ -105,6 +105,13 @@ test.for([ fileName: 'clip.mp4', expected: 'client/clip.mp4', }, + { + name: 'a close does not authorize an unrelated response artifact destination', + command: 'close', + localPath: 'outside/shot.png', + fileName: 'shot.png', + expected: 'cwd/shot.png', + }, { name: 'a record start refuses a response localPath', command: 'record', @@ -156,6 +163,7 @@ test.for([ }, }, createTestHostEnvironment(), + inRoot('state'), ); expect(response.ok && response.data?.path).toBe(inRoot(c.expected)); expect(fs.readFileSync(inRoot(c.expected), 'utf8')).toBe('artifact-bytes'); diff --git a/packages/remote/src/__tests__/daemon-artifacts-save-script.test.ts b/packages/remote/src/__tests__/daemon-artifacts-save-script.test.ts index 5cb0b64a60..2427cfd872 100644 --- a/packages/remote/src/__tests__/daemon-artifacts-save-script.test.ts +++ b/packages/remote/src/__tests__/daemon-artifacts-save-script.test.ts @@ -1,81 +1,96 @@ -/** - * #1802, the write half of the caller/daemon file split. - * - * Reading was fixed by sending script sources with the request. Writing has no symmetric path: - * `--save-script` publishes a healed `.ad` through the daemon's own `SessionScriptWriter`, at - * session teardown, on the daemon's disk — next to a source path that does not exist there. A - * remote request that would produce a file the caller can never see is refused here instead of - * appearing to succeed. - */ -import { createTestHostEnvironment } from '@agent-device/test-kit'; -import assert from 'node:assert/strict'; -import { test } from 'vitest'; -import { AppError } from '@agent-device/kernel/errors'; +import fs from 'node:fs'; +import path from 'node:path'; +import { expect, test } from 'vitest'; +import { createTestHostEnvironment, mkdtempForTestSync } from '@agent-device/test-kit'; import { prepareRemoteRequestArtifacts } from '../daemon-artifacts.ts'; -const REMOTE = { baseUrl: 'http://remote-mac.example.test:7777/agent-device', token: 'secret' }; -const LOCAL = { token: 'secret' }; -const NO_CANCELLATION = new AbortController().signal; +const REMOTE = { baseUrl: 'http://remote.example.test', token: 'test' }; +const signal = new AbortController().signal; -function replayRequest(saveScript?: boolean | string) { - return { - session: 'default', - command: 'replay', - positionals: ['./flows/login.ad'], - flags: saveScript === undefined ? {} : { saveScript }, - meta: { cwd: '/repo' }, - }; -} - -test('a remote daemon refuses --save-script, naming the caller/daemon split', async () => { - await assert.rejects( - async () => - await prepareRemoteRequestArtifacts( - replayRequest(true), - REMOTE, - NO_CANCELLATION, - createTestHostEnvironment(), - ), - (error: unknown) => - error instanceof AppError && - error.code === 'INVALID_ARGS' && - error.message.includes('written on the daemon host'), +test('remote open separates the caller output from the daemon target', async () => { + const root = mkdtempForTestSync('script-destination-'); + const result = await prepareRemoteRequestArtifacts( + { + session: 'owned', + command: 'open', + positionals: ['Demo'], + flags: { saveScript: 'output.ad' }, + meta: { cwd: root }, + }, + REMOTE, + signal, + createTestHostEnvironment(), ); + expect(result.clientArtifactPaths?.savedScript).toBe(path.join(root, 'output.ad')); + expect(result.positionals).toEqual(['Demo']); + expect(result.flags?.saveScript).toBe(true); }); -test('a remote daemon refuses an explicit --save-script output path too', async () => { - await assert.rejects( - async () => - await prepareRemoteRequestArtifacts( - replayRequest('./flows/login.healed.ad'), - REMOTE, - NO_CANCELLATION, - createTestHostEnvironment(), - ), - (error: unknown) => error instanceof AppError && error.code === 'INVALID_ARGS', - ); +test.each(['replay', 'close'])('remote %s save-script stays unsupported', async (command) => { + await expect( + prepareRemoteRequestArtifacts( + { session: 'owned', command, positionals: [], flags: { saveScript: true } }, + REMOTE, + signal, + createTestHostEnvironment(), + ), + ).rejects.toMatchObject({ details: { reason: 'remote_script_lifecycle_unsupported' } }); }); -test('a local daemon leaves --save-script untouched', async () => { - const prepared = await prepareRemoteRequestArtifacts( - replayRequest(true), - LOCAL, - NO_CANCELLATION, +test('existing client target refuses before dispatch unless force was granted', async () => { + const root = mkdtempForTestSync('script-existing-'); + const destination = path.join(root, 'output.ad'); + fs.writeFileSync(destination, 'original'); + const req = { + session: 'owned', + command: 'open', + positionals: ['Demo'], + flags: { saveScript: destination }, + }; + await expect( + prepareRemoteRequestArtifacts(req, REMOTE, signal, createTestHostEnvironment()), + ).rejects.toMatchObject({ code: 'COMMAND_FAILED', details: { reason: 'script_target_exists' } }); + const forced = await prepareRemoteRequestArtifacts( + { ...req, flags: { ...req.flags, force: true } }, + REMOTE, + signal, createTestHostEnvironment(), ); - - assert.equal(prepared.flags?.saveScript, true); - assert.deepEqual(prepared.positionals, ['./flows/login.ad']); + expect(forced.clientArtifactPaths?.savedScript).toBe(destination); + expect(fs.readFileSync(destination, 'utf8')).toBe('original'); }); -test('a remote replay without --save-script passes through unchanged', async () => { - const prepared = await prepareRemoteRequestArtifacts( - replayRequest(), - REMOTE, - NO_CANCELLATION, +test('local publication retains its path and flags', async () => { + const req = { + session: 'owned', + command: 'open', + positionals: ['Demo'], + flags: { saveScript: 'out.ad' }, + }; + const result = await prepareRemoteRequestArtifacts( + req, + { token: 'test' }, + signal, createTestHostEnvironment(), ); + expect(result.flags).toEqual(req.flags); + expect(result.clientArtifactPaths).toBeUndefined(); +}); - assert.deepEqual(prepared.positionals, ['./flows/login.ad']); - assert.equal(prepared.uploadedArtifactId, undefined); +test('remote open expands home on the caller', async () => { + const root = mkdtempForTestSync('script-home-'); + const home = path.join(root, 'caller-home'); + const result = await prepareRemoteRequestArtifacts( + { + session: 'owned', + command: 'open', + positionals: ['Demo'], + flags: { saveScript: '~/journey.ad' }, + meta: { cwd: root }, + }, + REMOTE, + signal, + createTestHostEnvironment({ env: { HOME: home } }), + ); + expect(result.clientArtifactPaths?.savedScript).toBe(path.join(home, 'journey.ad')); }); diff --git a/packages/remote/src/__tests__/daemon-artifacts-script-download.test.ts b/packages/remote/src/__tests__/daemon-artifacts-script-download.test.ts new file mode 100644 index 0000000000..f6f4604d42 --- /dev/null +++ b/packages/remote/src/__tests__/daemon-artifacts-script-download.test.ts @@ -0,0 +1,545 @@ +import fs from 'node:fs'; +import http from 'node:http'; +import path from 'node:path'; +import { afterEach, expect, test, vi } from 'vitest'; +import type { DaemonWireRequest } from '@agent-device/contracts/command'; +import type { DaemonArtifact, DaemonResponse } from '@agent-device/kernel/contracts'; +import * as file from '@agent-device/host-kit/file'; +import { + closeLoopbackServer, + createTestHostEnvironment, + listenOnLoopback, + mkdtempForTestSync, +} from '@agent-device/test-kit'; +import { AppError } from '@agent-device/kernel/errors'; +import { materializeRemoteArtifacts } from '../daemon-artifacts.ts'; +import { sendRemoteScriptOpen } from '../session-script-destination.ts'; + +vi.mock('@agent-device/host-kit/file', async (importOriginal) => { + const actual = await importOriginal(); + return { ...actual, publishFileSync: vi.fn(actual.publishFileSync) }; +}); + +type Served = { body: string; broken?: boolean; endless?: boolean }; +const servers: http.Server[] = []; + +afterEach(async () => { + vi.mocked(file.publishFileSync).mockClear(); + await Promise.all(servers.splice(0).map((server) => closeLoopbackServer(server))); +}); + +async function artifactServer(artifacts: Record): Promise { + const server = http.createServer((req, res) => { + const artifact = artifacts[decodeURIComponent(req.url?.replace('/artifacts/', '') ?? '')]; + if (!artifact) { + res.writeHead(404).end(); + return; + } + if (artifact.endless) { + res.writeHead(200); + const write = () => { + if (!res.destroyed) res.write(artifact.body, () => setImmediate(write)); + }; + write(); + return; + } + res.writeHead(200, { 'content-length': Buffer.byteLength(artifact.body) }); + if (!artifact.broken) { + res.end(artifact.body); + return; + } + res.flushHeaders(); + res.write(artifact.body.slice(0, 4)); + setImmediate(() => res.destroy()); + }); + servers.push(server); + return `http://127.0.0.1:${await listenOnLoopback(server)}`; +} + +function journey() { + // The real path, so a destination names the same file the publication renames into place. + const root = fs.realpathSync(mkdtempForTestSync('script-download-')); + const stateDir = path.join(root, 'state'); + return { root, stateDir, destination: path.join(root, 'caller', 'journey.ad') }; +} + +function request(command: string, meta: DaemonWireRequest['meta'] = {}): DaemonWireRequest { + return { token: 't', session: 'journey', command, positionals: [], meta }; +} + +function script(artifactId: string, revision: number, publicationId: string): DaemonArtifact { + return { + field: 'savedScript', + artifactType: 'session-script', + artifactId, + scriptPublicationId: publicationId, + scriptRevision: revision, + }; +} + +function records(stateDir: string): string[] { + const directory = path.join(stateDir, 'remote-connections', 'session-scripts'); + return fs.existsSync(directory) + ? fs.readdirSync(directory).filter((n) => n.endsWith('.json')) + : []; +} + +/** Answers a request the way the daemon does and materializes the answer like the client. */ +function answer( + baseUrl: string, + stateDir: string, + req: DaemonWireRequest, + data: Record, +): Promise { + const info = { baseUrl, token: 't' }; + return materializeRemoteArtifacts( + info, + req, + { ok: true, data }, + createTestHostEnvironment(), + stateDir, + ); +} + +/** A successful response whose script version could not be saved on this machine. */ +function deliveryFailure(cause: string) { + return expect.objectContaining({ + ok: true, + data: expect.objectContaining({ + scriptDeliveryFailure: expect.objectContaining({ reason: 'script_delivery_failed', cause }), + warnings: [expect.stringContaining('script')], + }), + }); +} + +/** A remote `open --save-script`: the daemon arms the publication it is sent, with version 1. */ +async function open( + baseUrl: string, + stateDir: string, + destination: string, + options: { force?: boolean; respond?: (id: string) => DaemonResponse } = {}, +) { + let sent: DaemonWireRequest | undefined; + let recordsAtSend: string[] = []; + const req = { + ...request('open', { clientArtifactPaths: { savedScript: destination } }), + flags: { saveScript: true, ...(options.force ? { force: true } : {}) }, + }; + const info = { baseUrl, token: 't', capabilities: ['script-artifacts'] }; + const response = await sendRemoteScriptOpen(info, req, stateDir, async (next) => { + sent = next; + recordsAtSend = records(stateDir); + const id = next.meta?.scriptPublicationId as string; + const reply = options.respond?.(id); + if (reply) return reply; + return answer(baseUrl, stateDir, next, { + scriptPublicationId: id, + artifacts: [script('v1', 1, id)], + }); + }); + const id = sent?.meta?.scriptPublicationId as string; + return { id, sent, recordsAtSend, response }; +} + +test('an open records its destination before it is sent, and sends only its publication ID', async () => { + const { stateDir, destination } = journey(); + const baseUrl = await artifactServer({ v1: { body: 'open Demo\n' } }); + + const { id, sent, recordsAtSend, response } = await open(baseUrl, stateDir, destination); + + expect(id).toMatch(/^[0-9a-f-]{36}$/); + expect(recordsAtSend).toHaveLength(1); + expect(sent?.meta?.clientArtifactPaths).toEqual({}); + expect(JSON.stringify(sent)).not.toContain(destination); + expect(response).toMatchObject({ ok: true, data: { savedScript: destination } }); + expect(fs.readFileSync(destination, 'utf8')).toBe('open Demo\n'); + if (process.platform !== 'win32') expect(fs.statSync(destination).mode & 0o777).toBe(0o600); +}); + +test('an older daemon is refused before the open is sent', async () => { + const { stateDir, destination } = journey(); + const send = vi.fn(); + const req = request('open', { clientArtifactPaths: { savedScript: destination } }); + + await expect( + sendRemoteScriptOpen({ baseUrl: 'http://127.0.0.1:9', token: 't' }, req, stateDir, send), + ).rejects.toMatchObject({ details: { reason: 'remote_script_artifacts_unsupported' } }); + expect(send).not.toHaveBeenCalled(); + expect(records(stateDir)).toEqual([]); +}); + +test.each([ + { + name: 'a refused open', + respond: (): DaemonResponse => ({ ok: false, error: { code: 'X', message: 'no' } }), + }, + { name: 'an open that armed nothing', respond: (): DaemonResponse => ({ ok: true, data: {} }) }, +])('$name removes its record', async ({ respond }) => { + const { stateDir, destination } = journey(); + + await open('http://127.0.0.1:9', stateDir, destination, { respond }).catch(() => undefined); + + expect(records(stateDir)).toEqual([]); +}); + +test('a failed open may have armed the recording, so it keeps its inert record', async () => { + const { stateDir, destination } = journey(); + const lost = new AppError('COMMAND_FAILED', 'Daemon request timed out', { + dispatched: 'unknown', + }); + + await expect( + open('http://127.0.0.1:9', stateDir, destination, { + respond: () => { + throw lost; + }, + }), + ).rejects.toBe(lost); + + expect(records(stateDir)).toHaveLength(1); +}); + +test('only a newer version of a recorded publication writes', async () => { + const { root, stateDir, destination } = journey(); + const baseUrl = await artifactServer({ + v1: { body: 'v1\n' }, + v2: { body: 'v2\n' }, + v3: { body: 'v3\n' }, + foreign: { body: 'foreign\n' }, + }); + const { id } = await open(baseUrl, stateDir, destination); + + await answer(baseUrl, stateDir, request('click'), { artifacts: [script('v3', 3, id)] }); + await answer(baseUrl, stateDir, request('click'), { artifacts: [script('v2', 2, id)] }); + const foreign = [ + answer(baseUrl, stateDir, request('click'), { + savedScript: '/daemon/x.ad', + artifacts: [script('foreign', 4, '00000000-0000-4000-8000-000000000000')], + }), + answer( + baseUrl, + stateDir, + { ...request('click'), session: 'other' }, + { + artifacts: [script('foreign', 4, id)], + }, + ), + answer(baseUrl, stateDir, request('click'), { + artifacts: [{ ...script('foreign', 4, id), artifactType: 'screenshot' }], + }), + ]; + + for (const response of await Promise.all(foreign)) { + expect(response).toEqual({ ok: true, data: { artifacts: [] } }); + } + expect(fs.readFileSync(destination, 'utf8')).toBe('v3\n'); + expect(fs.readdirSync(path.join(root, 'caller'))).toEqual(['journey.ad']); +}); + +test.each([ + { name: 'a regular file', link: false }, + { name: 'a symlink', link: true }, +])( + 'the first version never replaces $name that appeared while the open was pending', + async ({ link }) => { + const { root, stateDir, destination } = journey(); + const appeared = path.join(root, 'appeared.ad'); + fs.mkdirSync(path.dirname(destination), { recursive: true }); + fs.writeFileSync(appeared, 'appeared\n'); + if (link) fs.symlinkSync(appeared, destination); + else fs.renameSync(appeared, destination); + const baseUrl = await artifactServer({ v1: { body: 'open Demo\n' } }); + + const { response } = await open(baseUrl, stateDir, destination); + + expect(response).toEqual(deliveryFailure('script_target_exists')); + expect(response.ok && response.data?.savedScript).toBeUndefined(); + expect(fs.readFileSync(destination, 'utf8')).toBe('appeared\n'); + expect(fs.lstatSync(destination).isSymbolicLink()).toBe(link); + }, +); + +test('an open with --force replaces a file that appeared while it was pending', async () => { + const { stateDir, destination } = journey(); + fs.mkdirSync(path.dirname(destination), { recursive: true }); + fs.writeFileSync(destination, 'appeared\n'); + const baseUrl = await artifactServer({ v1: { body: 'open Demo\n' } }); + + await open(baseUrl, stateDir, destination, { force: true }); + + expect(fs.readFileSync(destination, 'utf8')).toBe('open Demo\n'); +}); + +test('a version over the size cap keeps the previous one and leaves no staging', async () => { + const { root, stateDir, destination } = journey(); + const baseUrl = await artifactServer({ + v1: { body: 'open Demo\n' }, + big: { body: 'x'.repeat(64 * 1024), endless: true }, + }); + const { id } = await open(baseUrl, stateDir, destination); + + await expect( + answer(baseUrl, stateDir, request('click'), { artifacts: [script('big', 2, id)] }), + ).resolves.toEqual(deliveryFailure('script_download_failed')); + expect(fs.readFileSync(destination, 'utf8')).toBe('open Demo\n'); + expect(fs.readdirSync(path.join(root, 'caller'))).toEqual(['journey.ad']); +}); + +test('close keeps its success and retires the record when its final download fails', async () => { + const { stateDir, destination } = journey(); + const baseUrl = await artifactServer({ + v1: { body: 'open Demo\n' }, + v2: { body: 'open Demo\nclose\n', broken: true }, + late: { body: 'late\n' }, + }); + const { id } = await open(baseUrl, stateDir, destination); + + await expect( + answer(baseUrl, stateDir, request('close'), { + scriptPublicationId: id, + artifacts: [script('v2', 2, id)], + }), + ).resolves.toEqual(deliveryFailure('script_download_failed')); + expect(records(stateDir)).toEqual([]); + await answer(baseUrl, stateDir, request('click'), { artifacts: [script('late', 3, id)] }); + expect(fs.readFileSync(destination, 'utf8')).toBe('open Demo\n'); +}); + +test('a close that publishes nothing still retires the record it names', async () => { + const { stateDir, destination } = journey(); + const baseUrl = await artifactServer({ v1: { body: 'open Demo\n' } }); + const { id } = await open(baseUrl, stateDir, destination); + + await answer(baseUrl, stateDir, request('close'), { scriptPublicationId: id }); + + expect(records(stateDir)).toEqual([]); +}); + +test.each([ + { name: 'is the destination', matches: true, expected: 'v1\n' }, + { name: 'is another file', matches: false, expected: 'v4\n' }, +])( + 'an interrupted version counts as published only when it $name', + async ({ matches, expected }) => { + const { stateDir, destination } = journey(); + const baseUrl = await artifactServer({ v1: { body: 'v1\n' }, v4: { body: 'v4\n' } }); + const { id } = await open(baseUrl, stateDir, destination); + const [name] = records(stateDir); + const recordFile = path.join(stateDir, 'remote-connections', 'session-scripts', name as string); + const stat = fs.statSync(matches ? destination : recordFile, { bigint: true }); + const record = JSON.parse(fs.readFileSync(recordFile, 'utf8')); + const staging = path.join(path.dirname(destination), '.agent-device-script-crashed'); + fs.mkdirSync(staging); + const publishing = { revision: 5, file: `${stat.dev}:${stat.ino}`, staging }; + fs.writeFileSync(recordFile, JSON.stringify({ ...record, publishing })); + + await answer(baseUrl, stateDir, request('click'), { artifacts: [script('v4', 4, id)] }); + + expect(fs.readFileSync(destination, 'utf8')).toBe(expected); + expect(fs.existsSync(staging)).toBe(false); + }, +); + +test.each([ + { name: 'while it lists the staging directory', failingWrite: 1, kept: false }, + { name: 'before the record names the version', failingWrite: 2, kept: false }, + { name: 'after the link, while the record names it', failingWrite: 3, kept: true }, +])( + 'a record write that fails $name keeps the staged file only while it is named', + async ({ failingWrite, kept }) => { + const { root, stateDir, destination } = journey(); + const baseUrl = await artifactServer({ v1: { body: 'open Demo\n' }, v2: { body: 'v2\n' } }); + const actual = await vi.importActual( + '@agent-device/host-kit/file', + ); + let writes = 0; + vi.mocked(file.publishFileSync).mockImplementation((options) => { + // The record created before the open is write 0; the publish writes follow it: listing the + // staging directory, naming the version, then recording its revision. + if (options.destination.endsWith('.json') && writes++ === failingWrite) { + throw new Error('record write failed'); + } + actual.publishFileSync(options); + }); + + const { id, response } = await open(baseUrl, stateDir, destination); + expect(response).toEqual(deliveryFailure('script_download_failed')); + vi.mocked(file.publishFileSync).mockImplementation(actual.publishFileSync); + const staging = () => + fs + .readdirSync(path.join(root, 'caller')) + .filter((n) => n.startsWith('.agent-device-script-')); + expect(staging()).toHaveLength(kept ? 1 : 0); + + // The next version settles the interrupted one and reclaims its staging directory. + await answer(baseUrl, stateDir, request('click'), { artifacts: [script('v2', 2, id)] }); + expect(fs.readFileSync(destination, 'utf8')).toBe('v2\n'); + expect(staging()).toEqual([]); + }, +); + +test('creating a record removes records nobody touched for a week', async () => { + const { stateDir, destination } = journey(); + const directory = path.join(stateDir, 'remote-connections', 'session-scripts'); + fs.mkdirSync(directory, { recursive: true }); + const stale = path.join(directory, 'stale.json'); + const fresh = path.join(directory, 'fresh.json'); + const staging = path.join(path.dirname(destination), '.agent-device-script-stale'); + fs.mkdirSync(staging, { recursive: true }); + const publishing = { revision: 1, file: '0:0', staging }; + const record = { destination, force: false, revision: 0, publishing, staging: [staging] }; + fs.writeFileSync(stale, JSON.stringify(record)); + fs.writeFileSync(fresh, '{}'); + const eightDaysAgo = new Date(Date.now() - 8 * 24 * 60 * 60 * 1000); + fs.utimesSync(stale, eightDaysAgo, eightDaysAgo); + + await open('http://127.0.0.1:9', stateDir, destination, { + respond: () => ({ ok: true, data: {} }), + }); + + expect(fs.existsSync(stale)).toBe(false); + expect(fs.existsSync(staging)).toBe(false); + expect(fs.existsSync(fresh)).toBe(true); +}); + +test('a recording whose first download failed still delivers later versions', async () => { + const { stateDir, destination } = journey(); + const baseUrl = await artifactServer({ + v1: { body: 'open Demo\n', broken: true }, + v2: { body: 'open Demo\nclose\n' }, + }); + const { id, response } = await open(baseUrl, stateDir, destination); + expect(response).toEqual(deliveryFailure('script_download_failed')); + + await answer(baseUrl, stateDir, request('close'), { + scriptPublicationId: id, + artifacts: [script('v2', 2, id)], + }); + + expect(fs.readFileSync(destination, 'utf8')).toBe('open Demo\nclose\n'); + expect(records(stateDir)).toEqual([]); +}); + +test('a session-script artifact under another field writes nothing', async () => { + const { root, stateDir, destination } = journey(); + const baseUrl = await artifactServer({ v1: { body: 'open Demo\n' }, hostile: { body: 'x\n' } }); + const { id } = await open(baseUrl, stateDir, destination); + const req = request('click', { cwd: root }); + + const response = await answer(baseUrl, stateDir, req, { + path: '/daemon/x.ad', + artifacts: [{ ...script('hostile', 2, id), field: 'path', fileName: 'victim.ad' }], + }); + + expect(response).toEqual({ ok: true, data: { artifacts: [] } }); + expect(fs.existsSync(path.join(root, 'victim.ad'))).toBe(false); + expect(fs.readFileSync(destination, 'utf8')).toBe('open Demo\n'); +}); + +test.skipIf(process.platform === 'win32' || process.getuid?.() === 0).each([ + { name: 'it publishes nothing', artifacts: false }, + { name: 'its final version also fails', artifacts: true }, +])( + 'a close keeps its success when its record cannot be retired and $name', + async ({ artifacts }) => { + const { stateDir, destination } = journey(); + const baseUrl = await artifactServer({ v1: { body: 'open Demo\n' }, v2: { body: 'final\n' } }); + const { id } = await open(baseUrl, stateDir, destination); + const directory = path.join(stateDir, 'remote-connections', 'session-scripts'); + fs.chmodSync(directory, 0o500); + let response: DaemonResponse; + try { + response = await answer(baseUrl, stateDir, request('close'), { + scriptPublicationId: id, + ...(artifacts ? { artifacts: [script('v2', 2, id)] } : {}), + }); + } finally { + fs.chmodSync(directory, 0o700); + } + expect(response).toEqual( + artifacts + ? deliveryFailure('script_download_failed') + : { ok: true, data: { scriptPublicationId: id } }, + ); + expect(records(stateDir)).toHaveLength(1); + }, +); + +test('retiring a record removes the staging a crashed download left behind', async () => { + const { stateDir, destination } = journey(); + const baseUrl = await artifactServer({ v1: { body: 'open Demo\n' } }); + const { id } = await open(baseUrl, stateDir, destination); + const [name] = records(stateDir); + const recordFile = path.join(stateDir, 'remote-connections', 'session-scripts', name as string); + const crashed = path.join(path.dirname(destination), '.agent-device-script-crashed'); + fs.mkdirSync(crashed); + fs.writeFileSync(path.join(crashed, 'script.ad'), 'partial'); + const record = JSON.parse(fs.readFileSync(recordFile, 'utf8')); + fs.writeFileSync(recordFile, JSON.stringify({ ...record, staging: [crashed] })); + + await answer(baseUrl, stateDir, request('close'), { scriptPublicationId: id }); + + expect(fs.existsSync(crashed)).toBe(false); + expect(records(stateDir)).toEqual([]); +}); + +test('a retirement that fails midway never leaves the record naming a removed anchor', async () => { + const { stateDir, destination } = journey(); + const baseUrl = await artifactServer({ v1: { body: 'open Demo\n' } }); + const { id } = await open(baseUrl, stateDir, destination); + const [name] = records(stateDir); + const recordFile = path.join(stateDir, 'remote-connections', 'session-scripts', name as string); + const staging = path.join(path.dirname(destination), '.agent-device-script-pending'); + fs.mkdirSync(staging); + fs.writeFileSync(path.join(staging, 'script.ad.anchor'), 'pending'); + const record = JSON.parse(fs.readFileSync(recordFile, 'utf8')); + const publishing = { revision: 2, file: '1:2', staging }; + fs.writeFileSync(recordFile, JSON.stringify({ ...record, publishing, staging: [staging] })); + const realRm = fs.rmSync; + const rm = vi.spyOn(fs, 'rmSync').mockImplementation((target, options) => { + if (String(target) === recordFile) throw new Error('record removal failed'); + realRm(target, options); + }); + + try { + await answer(baseUrl, stateDir, request('close'), { scriptPublicationId: id }); + } finally { + rm.mockRestore(); + } + + expect(fs.existsSync(staging)).toBe(false); + expect(JSON.parse(fs.readFileSync(recordFile, 'utf8')).publishing).toBeUndefined(); +}); + +test('a stale record that cannot be swept never blocks a new open', async () => { + const { stateDir, destination } = journey(); + const directory = path.join(stateDir, 'remote-connections', 'session-scripts'); + fs.mkdirSync(directory, { recursive: true }); + const stale = path.join(directory, 'stale.json'); + const stuck = path.join(path.dirname(destination), '.agent-device-script-stuck'); + fs.mkdirSync(stuck, { recursive: true }); + fs.writeFileSync( + stale, + JSON.stringify({ destination, force: false, revision: 0, staging: [stuck] }), + ); + const eightDaysAgo = new Date(Date.now() - 8 * 24 * 60 * 60 * 1000); + fs.utimesSync(stale, eightDaysAgo, eightDaysAgo); + const realRm = fs.rmSync; + const rm = vi.spyOn(fs, 'rmSync').mockImplementation((target, options) => { + if (String(target) === stuck) throw new Error('staging removal failed'); + realRm(target, options); + }); + + let opened: Awaited>; + try { + opened = await open('http://127.0.0.1:9', stateDir, destination, { + respond: (id) => ({ ok: true, data: { scriptPublicationId: id } }), + }); + } finally { + rm.mockRestore(); + } + + expect(opened.response).toMatchObject({ ok: true }); + expect(fs.existsSync(stale)).toBe(true); + expect(records(stateDir)).toHaveLength(2); +}); diff --git a/packages/remote/src/artifact-download.ts b/packages/remote/src/artifact-download.ts index d17ab10668..f6e9174388 100644 --- a/packages/remote/src/artifact-download.ts +++ b/packages/remote/src/artifact-download.ts @@ -3,6 +3,7 @@ import fs from 'node:fs'; // HTTP stack loads through `loadNodeHttpRequester` only when a remote daemon returns an artifact. import type http from 'node:http'; import path from 'node:path'; +import { Transform } from 'node:stream'; import { pipeline } from 'node:stream/promises'; import { AppError } from '@agent-device/kernel/errors'; import { loadNodeHttpRequester } from '@agent-device/host-kit/transport'; @@ -24,8 +25,19 @@ export type RemoteArtifactDownload = { timeoutMs?: number; /** Whether `destinationPath` is a caller-owned root rather than one file to create. */ isDirectory?: boolean; + /** + * Writes a new private file: created exclusively at 0600, never through a symbolic link, and + * stopped once it crosses `maxBytes`, whatever `Content-Length` announced. + */ + privateFile?: Readonly<{ maxBytes: number }>; }; +const PRIVATE_FILE_FLAGS = + fs.constants.O_WRONLY | + fs.constants.O_CREAT | + fs.constants.O_EXCL | + (fs.constants.O_NOFOLLOW ?? 0); + type DownloadDestination = { prepare(): Promise; cleanupOnError(): Promise; @@ -46,17 +58,52 @@ function buildDownloadDestination(params: RemoteArtifactDownload): DownloadDesti }; } return { + // A private file goes into a directory its caller allocated, which is never recreated here. prepare: async () => { - await fs.promises.mkdir(path.dirname(destinationPath), { recursive: true }); + if (!params.privateFile) + await fs.promises.mkdir(path.dirname(destinationPath), { recursive: true }); }, cleanupOnError: () => fs.promises.rm(destinationPath, { force: true }), materialize: async (res, signal) => { - await pipeline(res, fs.createWriteStream(destinationPath), { signal }); + const { privateFile } = params; + if (!privateFile) { + await pipeline(res, fs.createWriteStream(destinationPath), { signal }); + return destinationPath; + } + // A file that cannot be opened never consumes the response, so release its socket here. + const file = await fs.promises + .open(destinationPath, PRIVATE_FILE_FLAGS, 0o600) + .catch((error) => { + res.destroy(); + throw error; + }); + const limit = limitBytes(privateFile.maxBytes, params.artifactId); + await pipeline(res, limit, file.createWriteStream(), { signal }); return destinationPath; }, }; } +function limitBytes(maxBytes: number, artifactId: string): Transform { + let received = 0; + return new Transform({ + transform(chunk: Buffer, _encoding, callback) { + received += chunk.length; + if (received <= maxBytes) { + callback(null, chunk); + return; + } + callback( + new AppError('COMMAND_FAILED', `The remote artifact is larger than ${maxBytes} bytes.`, { + reason: 'artifact_too_large', + artifactId, + maxBytes, + }), + ); + }, + }); +} + /** Downloads an artifact and returns the exact file or directory published on the client. */ export async function downloadRemoteArtifactFromUrl( params: RemoteArtifactDownload, diff --git a/packages/remote/src/daemon-artifacts.ts b/packages/remote/src/daemon-artifacts.ts index 226980ad16..9cd3662efe 100644 --- a/packages/remote/src/daemon-artifacts.ts +++ b/packages/remote/src/daemon-artifacts.ts @@ -8,12 +8,14 @@ import { buildRemoteTempArtifactPath, } from '@agent-device/contracts/daemon-http'; import { AppError } from '@agent-device/kernel/errors'; +import { resolveUserPath } from '@agent-device/host-kit/file'; import { leaseScopeFromRequest } from '@agent-device/contracts/lease-scope'; import { appendRecordingExtensionWhenMissing, recordingExtensionForPlatform, } from '@agent-device/capture-kit/recording-output-path'; import { parsePerfRuntimeRequest } from '@agent-device/capture-kit/perf-runtime-plan'; +import type { SessionScriptDelivery } from './session-script-destination.ts'; import { uploadArtifact } from './upload-client.ts'; import { withUploadPreparationDeadline } from './upload-stream.ts'; import { createStderrUploadProgressReporter, type UploadProgressSink } from './upload-progress.ts'; @@ -76,7 +78,7 @@ async function prepareRemoteRequestArtifactsWithinBudget( }); } - assertRemoteDaemonSupportsSaveScript(req); + flags = prepareRemoteScriptOutput(req, flags, clientArtifactPaths, host); flags = applyRemoteArtifactCommand(req, positionals, flags, clientArtifactPaths, host); const remoteInstallSource = await prepareRemoteInstallSource( req, @@ -113,24 +115,36 @@ async function prepareRemoteRequestArtifactsWithinBudget( } /** - * #1802 (the other half of the caller/daemon file split): `--save-script` WRITES a `.ad` file, - * and the writer is the daemon's `SessionScriptWriter` — on the daemon's own disk, next to a - * source path that does not exist there. Reading was fixed by sending script sources with the - * request; writing has no such symmetric path yet (the healed script commits at session teardown, - * not in the replay response), so a remote request that would produce a file the caller can never - * see is refused here instead of appearing to succeed. Tracked for the return-the-healed-script - * response plumbing. + * A remote `open --save-script` names a caller file. The daemon allocates its own output and + * returns each script version as an artifact, which the client downloads to that file. */ -function assertRemoteDaemonSupportsSaveScript(req: Omit): void { - if (req.flags?.saveScript === undefined) return; - throw new AppError( - 'INVALID_ARGS', - '--save-script is not supported against a remote daemon: the healed script would be written on the daemon host, not on this machine.', - { - hint: 'Run the script against a local daemon to capture a healed .ad, or re-run without --save-script.', - command: req.command, - }, +function prepareRemoteScriptOutput( + req: Omit, + flags: DaemonWireRequest['flags'], + clientPaths: Record, + host: HostEnvironment, +): DaemonWireRequest['flags'] { + const requested = flags?.saveScript; + if (!requested) return flags; + if (req.command !== 'open') { + throw new AppError('INVALID_ARGS', 'Remote --save-script is supported only on a fresh open.', { + reason: 'remote_script_lifecycle_unsupported', + hint: 'Use open --save-script. A remote close writes the recording to that path. Remote repaired-script output is not supported.', + }); + } + const localPath = resolveUserPath( + typeof requested === 'string' ? requested : `recording-${Date.now()}.ad`, + { cwd: req.meta?.cwd ?? host.cwd, env: host.env }, ); + if (requested !== true && !req.flags?.force && fs.existsSync(localPath)) { + throw new AppError('COMMAND_FAILED', `A file already exists at ${localPath}.`, { + reason: 'script_target_exists', + path: localPath, + hint: 'Choose another output path or pass --force/--overwrite.', + }); + } + clientPaths.savedScript = localPath; + return { ...flags, saveScript: true }; } async function prepareRemoteInstallPackage( @@ -437,14 +451,54 @@ function hasNonEmptyString(value: unknown): value is string { return typeof value === 'string' && value.trim().length > 0; } +/** + * A remote `open --save-script` mints its publication ID and records its caller destination before + * it leaves (ADR 0016). The destination owner loads only for this request. + */ +export async function sendRemoteScriptOpen( + ...args: Parameters +): Promise { + const scripts = await import('./session-script-destination.ts'); + return await scripts.sendRemoteScriptOpen(...args); +} + +/** + * Downloads the artifacts of a successful remote response. A session script goes only where this + * client's own `open --save-script` recorded under `stateDir`, never where a response says; that + * owner loads only for a response that names a publication or carries a script artifact. + */ export async function materializeRemoteArtifacts( info: DaemonArtifactEndpoint, req: DaemonWireRequest, response: Extract, host: HostEnvironment, + stateDir: string, ): Promise { + if (!info.baseUrl) return response; + const endpoint = { baseUrl: info.baseUrl, token: info.token }; const artifacts = Array.isArray(response.data?.artifacts) ? response.data.artifacts : []; - if (artifacts.length === 0 || !info.baseUrl) return response; + const download = (scripts?: SessionScriptDelivery) => + downloadResponseArtifacts(endpoint, req, response, host, scripts); + if ( + response.data?.scriptPublicationId === undefined && + !artifacts.some(isSessionScriptArtifact) + ) { + return await download(); + } + const { sessionScriptDelivery } = await import('./session-script-destination.ts'); + const scripts = sessionScriptDelivery(endpoint, req, response, stateDir, downloadRemoteArtifact); + return await scripts.settleAfter(download); +} + +async function downloadResponseArtifacts( + endpoint: Required, + req: DaemonWireRequest, + response: Extract, + host: HostEnvironment, + scripts: SessionScriptDelivery | undefined, +): Promise { + const artifacts = Array.isArray(response.data?.artifacts) ? response.data.artifacts : []; + if (artifacts.length === 0) return response; const nextData = response.data ? { ...response.data } : {}; const nextArtifacts: DaemonArtifact[] = []; for (const artifact of artifacts) { @@ -452,10 +506,15 @@ export async function materializeRemoteArtifacts( nextArtifacts.push(artifact); continue; } + // `savedScript` and the session-script type are reserved for the session-script owner, which + // drops a script artifact under another field or of another type. + if (scripts && isSessionScriptArtifact(artifact)) { + await scripts.publish(artifact, nextData, nextArtifacts); + continue; + } const downloadPath = resolveMaterializedArtifactPath(artifact, req, host); const materializedPath = await downloadRemoteArtifact({ - baseUrl: info.baseUrl, - token: info.token, + ...endpoint, artifactId: artifact.artifactId, destinationPath: downloadPath, requestScope: req.meta, @@ -478,6 +537,10 @@ export async function materializeRemoteArtifacts( return { ok: true, data: nextData }; } +function isSessionScriptArtifact(artifact: DaemonArtifact | undefined): boolean { + return artifact?.field === 'savedScript' || artifact?.artifactType === 'session-script'; +} + /** * Whether this request finishes a capture whose destination this client named in an EARLIER * request (`record start`, a perf or trace start with an output path). The daemon echoes that @@ -529,6 +592,8 @@ type DownloadRemoteArtifactParams = { timeoutMs?: number; /** Whether `destinationPath` is a caller-owned root rather than one file to create. */ isDirectory?: boolean; + /** A capped download into a new private file (`artifact-download.ts`). */ + privateFile?: Readonly<{ maxBytes: number }>; }; export async function downloadRemoteArtifact( @@ -537,14 +602,10 @@ export async function downloadRemoteArtifact( // Remote artifact transfer is not part of routine CLI startup. Keep the HTTP/archive owner out // of the eager command graph and load it only after a remote response names an artifact. const { downloadRemoteArtifactFromUrl } = await import('./artifact-download.ts'); + const { baseUrl, ...download } = params; return await downloadRemoteArtifactFromUrl({ - artifactUrl: new URL(buildDaemonArtifactUrl(params.baseUrl, params.artifactId)), - token: params.token, - artifactId: params.artifactId, - destinationPath: params.destinationPath, - requestScope: params.requestScope, - ...(params.timeoutMs === undefined ? {} : { timeoutMs: params.timeoutMs }), - ...(params.isDirectory === undefined ? {} : { isDirectory: params.isDirectory }), + ...download, + artifactUrl: new URL(buildDaemonArtifactUrl(baseUrl, params.artifactId)), }); } diff --git a/packages/remote/src/session-script-destination.ts b/packages/remote/src/session-script-destination.ts new file mode 100644 index 0000000000..7c4e60c2e7 --- /dev/null +++ b/packages/remote/src/session-script-destination.ts @@ -0,0 +1,437 @@ +import crypto from 'node:crypto'; +import fs from 'node:fs'; +import path from 'node:path'; +import type { DaemonWireRequest } from '@agent-device/contracts/command'; +import type { + DaemonArtifact, + DaemonResponse, + ScriptDeliveryFailure, +} from '@agent-device/kernel/contracts'; +import { AppError } from '@agent-device/kernel/errors'; +import { readResponseWarnings } from '@agent-device/kernel/success-text'; +import { assertScriptArtifactsCapability } from '@agent-device/daemon-contracts/daemon-resolution'; +import { emitDiagnostic } from '@agent-device/host-kit/diagnostics'; +import { acquireProcessLock, publishFileSync, withProcessLock } from '@agent-device/host-kit/file'; +import { readCurrentOwnerIdentity } from '@agent-device/host-kit/process'; +import type { DaemonArtifactEndpoint, downloadRemoteArtifact } from './daemon-artifacts.ts'; + +/** The download stops at this size, so a daemon cannot fill the caller's disk. */ +const MAX_SCRIPT_BYTES = 8 * 1024 * 1024; +/** A record untouched for this long is removed the next time a record is created. */ +const STALE_RECORD_MS = 7 * 24 * 60 * 60 * 1000; +const RECORD_LOCK_TIMEOUT_MS = 30_000; + +/** + * This client's record of one remote `open --save-script`, keyed by the endpoint, tenant, session + * and the publication ID this client minted for that open. Only this client creates records, so a + * daemon response never establishes a destination. `revision` is the newest version published. + * `publishing` names a version, the staged file's identity, and its staging directory before the + * rename, so a crash between the rename and the revision update is settled from the destination's + * identity, and the staging directory is removed once nothing can name it. `staging` lists every + * staging directory allocated and not yet removed, so retiring or sweeping the record reclaims the + * ones a crashed download left behind. + */ +type ScriptRecord = Readonly<{ + destination: string; + force: boolean; + revision: number; + publishing?: Readonly<{ revision: number; file: string; staging: string }>; + staging?: readonly string[]; +}>; + +type RemoteEndpoint = DaemonArtifactEndpoint & { capabilities?: readonly string[] }; + +/** + * Sends a remote `open --save-script`. Before the open leaves, the client mints a publication ID + * and records the caller destination and the `--force` grant under it. The serialized request + * carries the ID and omits the destination. A daemon answer that does not name the ID removes the + * record. A failed open may still have armed the recording, so it keeps the record. A record that outlives its open stays inert: only artifacts of its + * own ID match it. + */ +export async function sendRemoteScriptOpen( + info: RemoteEndpoint, + req: DaemonWireRequest, + stateDir: string, + send: (req: DaemonWireRequest) => Promise, +): Promise { + assertScriptArtifactsCapability(info.capabilities); + const { savedScript: destination, ...clientArtifactPaths } = req.meta?.clientArtifactPaths ?? {}; + if (!info.baseUrl || !destination) throw new Error('A remote script open needs a destination.'); + const publicationId = crypto.randomUUID(); + const file = recordPath(stateDir, info.baseUrl, req, publicationId); + await createRecord(file, { destination, force: req.flags?.force === true, revision: 0 }); + const meta = { ...req.meta, clientArtifactPaths, scriptPublicationId: publicationId }; + const response = await send({ ...req, meta }); + if (!response.ok || response.data?.scriptPublicationId !== publicationId) { + // A record that cannot be removed stays inert, so the open's own outcome is reported. + await withRecordLock(file, async () => fs.rmSync(file, { force: true })).catch(() => {}); + } + return response; +} + +export type SessionScriptDelivery = Readonly<{ + /** Publishes one script artifact and names it in `data`, or drops it from the response. */ + publish( + artifact: DaemonArtifact, + data: Record, + kept: DaemonArtifact[], + ): Promise; + /** Runs the downloads of one response, then retires the record a close names. */ + settleAfter( + run: (scripts: SessionScriptDelivery) => Promise, + ): Promise; +}>; + +/** + * Publishes the session-script artifacts of one remote response to the destinations this client + * recorded, and retires the record that a close names. A version that cannot be saved keeps the + * response successful and adds `scriptDeliveryFailure` and a warning. A close retires its record + * even when another artifact fails, and the first error is the one reported. + */ +export function sessionScriptDelivery( + endpoint: Required, + req: DaemonWireRequest, + response: Extract, + stateDir: string, + download: typeof downloadRemoteArtifact, +): SessionScriptDelivery { + const named = response.data?.scriptPublicationId; + const closedId = req.command === 'close' && typeof named === 'string' ? named : undefined; + const retire = async (): Promise => { + if (closedId === undefined) return; + const file = recordPath(stateDir, endpoint.baseUrl, req, closedId); + await withRecordLock(file, async () => removeRecord(file)); + }; + const delivery: SessionScriptDelivery = { + publish: async (artifact, data, kept) => { + delete data[artifact.field]; + let published: string | undefined; + try { + published = await publishScriptVersion({ endpoint, req, stateDir, download }, artifact); + } catch (error) { + // A delivery failure never changes the outcome of the action that recorded the version. + const saved = error as AppError; + // Only a validated script artifact reaches the save, so its publication ID is a string. + const failure: ScriptDeliveryFailure = { + reason: 'script_delivery_failed', + cause: String(saved.details?.reason), + publicationId: String(artifact.scriptPublicationId), + message: saved.message, + hint: String(saved.details?.hint), + }; + data.scriptDeliveryFailure = failure; + data.warnings = [...readResponseWarnings(data), `${failure.message} ${failure.hint}`]; + emitDiagnostic({ + level: 'warn', + phase: 'session_script_delivery_failed', + data: { session: req.session, error: String(saved.cause ?? saved) }, + }); + return; + } + if (published === undefined) return; + data.savedScript = published; + kept.push({ ...artifact, localPath: published }); + }, + settleAfter: async (run) => { + // A record that cannot be retired stays inert, so the close keeps its own outcome. + const retireQuietly = () => + retire().catch((retireError: unknown) => + emitDiagnostic({ + level: 'warn', + phase: 'session_script_retire_failed', + data: { session: req.session, error: String(retireError) }, + }), + ); + let result: DaemonResponse; + try { + result = await run(delivery); + } catch (error) { + await retireQuietly(); + throw error; + } + await retireQuietly(); + return result; + }, + }; + return delivery; +} + +/** + * Publishes one version and returns the destination, or `undefined` when no record of this client + * matches the artifact. A version no newer than the one published is skipped. + * + * The download streams, capped at `MAX_SCRIPT_BYTES`, into a new private file in a private staging + * directory beside the destination, so it moves into place by one rename or link. The compare and + * the publish run under the record lock. The first version is linked exclusively unless the open + * granted `--force`, as a local close-time write is. + */ +async function publishScriptVersion( + context: Readonly<{ + endpoint: Required; + req: DaemonWireRequest; + stateDir: string; + download: typeof downloadRemoteArtifact; + }>, + artifact: DaemonArtifact, +): Promise { + const { endpoint, req, stateDir } = context; + const { scriptPublicationId: id, scriptRevision: revision, artifactId } = artifact; + const file = + artifact.field === 'savedScript' && + artifact.artifactType === 'session-script' && + typeof id === 'string' && + typeof artifactId === 'string' && + Number.isSafeInteger(revision) && + (revision as number) > 0 + ? recordPath(stateDir, endpoint.baseUrl, req, id) + : undefined; + const record = file ? readRecord(file) : undefined; + if (!file || !record) { + emitDiagnostic({ + level: 'warn', + phase: 'session_script_artifact_dropped', + data: { session: req.session, artifactId }, + }); + return undefined; + } + if ((revision as number) <= record.revision) return record.destination; + const directory = path.dirname(record.destination); + const pending = { named: false }; + let staging: string | undefined; + try { + await fs.promises.mkdir(directory, { recursive: true }); + staging = await withRecordLock(file, async () => allocateStaging(file, directory)); + if (!staging) return undefined; + const staged = path.join(staging, 'script.ad'); + await context.download({ + ...endpoint, + artifactId: artifactId as string, + destinationPath: staged, + requestScope: req.meta, + privateFile: { maxBytes: MAX_SCRIPT_BYTES }, + }); + const version = { revision: revision as number, staging, staged, pending }; + return await withRecordLock(file, async () => publishStaged(file, version)); + } catch (error) { + throw scriptSaveError(record.destination, artifactId, error, req.command === 'close'); + } finally { + const removed = staging; + if (removed && !pending.named) { + // A directory that cannot be released here stays listed, so retirement or the sweep removes it. + await withRecordLock(file, async () => releaseStaging(file, removed)).catch(() => undefined); + } + } +} + +/** Creates a staging directory and lists it in the record before any script bytes reach it. */ +function allocateStaging(file: string, directory: string): string | undefined { + const record = readRecord(file); + if (!record) return undefined; + const staging = fs.mkdtempSync(path.join(directory, '.agent-device-script-')); + try { + writeRecord(file, { ...record, staging: [...(record.staging ?? []), staging] }); + } catch (error) { + fs.rmSync(staging, { recursive: true, force: true }); + throw error; + } + return staging; +} + +/** + * Removes a staging directory the record can no longer name, then unlists it, so a directory that + * cannot be removed stays listed for retirement or the sweep. + */ +function releaseStaging(file: string, staging: string): void { + fs.rmSync(staging, { recursive: true, force: true }); + const record = readRecord(file); + if (record) writeRecord(file, withoutStaging(record, staging)); +} + +function withoutStaging(record: ScriptRecord, staging: string): ScriptRecord { + return { ...record, staging: (record.staging ?? []).filter((listed) => listed !== staging) }; +} + +/** + * Removes a record and every staging directory it lists. The record first stops naming an + * interrupted version, so no anchor is removed while the record names its inode, and a failure + * keeps the list. + */ +function removeRecord(file: string): void { + const record = readRecord(file); + if (record?.publishing) writeRecord(file, settlePublishing(record)); + for (const staging of record?.staging ?? []) { + fs.rmSync(staging, { recursive: true, force: true }); + } + fs.rmSync(file, { force: true }); +} + +/** + * Runs under the record lock. While `pending.named` is set the record may name the staged file, so + * the staged file stays on disk and no later file can reuse its inode and pass as that version. + */ +function publishStaged( + file: string, + version: Readonly<{ + revision: number; + staging: string; + staged: string; + pending: { named: boolean }; + }>, +): string | undefined { + const { revision, staging, staged, pending } = version; + const record = readRecord(file); + if (!record) return undefined; + let current = settlePublishing(record); + if (record.publishing) { + // Once the settled record is written, its staging directory can no longer be named. + writeRecord(file, current); + releaseStaging(file, record.publishing.staging); + current = withoutStaging(current, record.publishing.staging); + } + if (revision <= current.revision) return current.destination; + const publishing = { revision, file: fileIdentity(staged) ?? 'missing', staging }; + // A second name keeps the inode on disk after the rename while the record may name it. + fs.linkSync(staged, `${staged}.anchor`); + writeRecord(file, { ...current, publishing }); + pending.named = true; + const exclusive = current.revision === 0 && !current.force; + try { + if (exclusive) fs.linkSync(staged, current.destination); + else fs.renameSync(staged, current.destination); + } catch (error) { + writeRecord(file, settlePublishing({ ...current, publishing })); + pending.named = false; + throw error; + } + writeRecord(file, { ...current, revision }); + pending.named = false; + return current.destination; +} + +/** An interrupted version counts as published only when the destination is that very file. */ +function settlePublishing(record: ScriptRecord): ScriptRecord { + const { publishing, ...settled } = record; + if (!publishing) return record; + if (fileIdentity(record.destination) !== publishing.file) return settled; + return { ...settled, revision: Math.max(settled.revision, publishing.revision) }; +} + +function fileIdentity(file: string): string | undefined { + const stat = fs.lstatSync(file, { bigint: true, throwIfNoEntry: false }); + return stat ? `${stat.dev}:${stat.ino}` : undefined; +} + +function scriptSaveError( + destination: string, + artifactId: string | undefined, + error: unknown, + closing: boolean, +) { + const cause = error instanceof Error ? error : undefined; + // Only the exclusive link of the first version can find an existing entry. + const exists = (error as NodeJS.ErrnoException | undefined)?.code === 'EEXIST'; + const recovery = closing + ? 'The session is closed, so no later version follows.' + : 'The next recorded action or close delivers the full recording again.'; + return new AppError( + 'COMMAND_FAILED', + exists + ? `A file already exists at ${destination}.` + : `The remote script could not be saved to ${destination}.`, + { + reason: exists ? 'script_target_exists' : 'script_download_failed', + path: destination, + artifactId, + hint: exists + ? 'Remove the existing file, or start a new recording with open --save-script --force.' + : `The file may still hold the previous version. ${recovery}`, + }, + cause, + ); +} + +function recordPath( + stateDir: string, + baseUrl: string, + req: DaemonWireRequest, + publicationId: string, +): string { + const key = crypto + .createHash('sha256') + .update( + JSON.stringify([ + baseUrl.replace(/\/+$/, ''), + req.meta?.tenantId ?? '', + req.session ?? '', + publicationId, + ]), + ) + .digest('hex'); + return path.join(stateDir, 'remote-connections', 'session-scripts', `${key}.json`); +} + +/** Creates a record and removes the records nobody has touched for `STALE_RECORD_MS`. */ +async function createRecord(file: string, record: ScriptRecord): Promise { + const directory = path.dirname(file); + fs.mkdirSync(directory, { recursive: true, mode: 0o700 }); + const isStale = (entry: string) => + (fs.lstatSync(entry, { throwIfNoEntry: false })?.mtimeMs ?? Infinity) < + Date.now() - STALE_RECORD_MS; + for (const name of fs.readdirSync(directory)) { + const entry = path.join(directory, name); + if (!name.endsWith('.json') || !isStale(entry)) continue; + // Rechecked under the lock, so a record that a publish just refreshed stays. A record that + // cannot be swept now is retried by a later sweep and never blocks this open. + await withRecordLock(entry, async () => { + if (isStale(entry)) removeRecord(entry); + }).catch((error: unknown) => + emitDiagnostic({ + level: 'warn', + phase: 'session_script_sweep_failed', + data: { record: name, error: String(error) }, + }), + ); + } + writeRecord(file, record); +} + +/** A record that does not parse authorizes nothing. */ +function readRecord(file: string): ScriptRecord | undefined { + let record: Partial | null = null; + try { + record = JSON.parse(fs.readFileSync(file, 'utf8')); + } catch { + return undefined; + } + const publishing = record?.publishing; + const valid = + typeof record?.destination === 'string' && + typeof record.force === 'boolean' && + Number.isSafeInteger(record.revision) && + (publishing === undefined || + (Number.isSafeInteger(publishing?.revision) && + typeof publishing?.file === 'string' && + typeof publishing?.staging === 'string')) && + (record.staging === undefined || + (Array.isArray(record.staging) && + record.staging.every((staging) => typeof staging === 'string'))); + return valid ? (record as ScriptRecord) : undefined; +} + +function writeRecord(file: string, record: ScriptRecord): void { + publishFileSync({ destination: file, contents: `${JSON.stringify(record)}\n`, mode: 0o600 }); +} + +async function withRecordLock(file: string, task: () => Promise): Promise { + const { pid, startTime } = readCurrentOwnerIdentity(); + return await withProcessLock({ + acquire: () => + acquireProcessLock({ + lockDirPath: `${file}.lock`, + owner: { pid, startTime, acquiredAtMs: Date.now() }, + timeoutMs: RECORD_LOCK_TIMEOUT_MS, + description: 'remote session script record', + }), + task, + }); +} diff --git a/scripts/layering/architecture-ownership.ts b/scripts/layering/architecture-ownership.ts index bbfecadd20..fdd4efc310 100644 --- a/scripts/layering/architecture-ownership.ts +++ b/scripts/layering/architecture-ownership.ts @@ -249,15 +249,22 @@ export const ARCHITECTURE_OWNERSHIP = { kind: 'capability', root: 'packages/daemon/src/core/session-script-publication-capability.ts', exports: [ + 'RemoteCloseScript', 'abortAuthoringOnSecondOpen', 'applyRecordedSaveScriptFlags', 'armAuthoringOnOpen', 'effectiveWriteForce', + 'isArmedRemoteRecording', 'isAuthoringArmedSession', 'isSessionRecording', 'isSessionScriptPublished', 'markActivePublicationDone', 'markCloseGeneratedPublicationDone', + 'remoteCloseScript', + 'remoteCloseScriptDelivery', + 'remoteScriptDelivery', + 'remoteScriptOpen', + 'remoteScriptVersionDelivery', 'retargetActivePublication', ], }, diff --git a/src/commands/schema/cli-help.ts b/src/commands/schema/cli-help.ts index 801631a2ea..58715fb794 100644 --- a/src/commands/schema/cli-help.ts +++ b/src/commands/schema/cli-help.ts @@ -153,7 +153,7 @@ Escalate: Use this for reusable .ad script authoring (save-script), scripted destination guards, secret-safe fills, batch multi-step JSON, replay divergence/repair, and evidence recording. Script paths are the caller's: - replay and test resolve and read on the machine running the command, then send the script content (Maestro runFlow includes too) with the request. The same flows therefore run against a local daemon and against a remote one (AGENT_DEVICE_DAEMON_BASE_URL) with no copy step, and a missing script fails immediately, naming the path you typed. --save-script writes on the DAEMON host and is rejected against a remote daemon. + replay and test resolve and read on the machine running the command, then send the script content (Maestro runFlow includes too) with the request. The same flows therefore run against a local daemon and against a remote one (AGENT_DEVICE_DAEMON_BASE_URL) with no copy step, and a missing script fails immediately, naming the path you typed. Against a remote daemon, outside a macOS app lease, open --save-script= names a caller file: after each recorded action the client refreshes it with the recording so far, and close writes the final script there, as a local close does. An existing file is refused unless you pass --force. A session that another process closes keeps the version from the last recorded action. Remote session save-script, replay/close --save-script, and --save-script in batch steps are refused. A daemon without the script-artifacts capability is refused before the open. test --json marks a failed test with infrastructure: true only when the owning runtime classified a device, runner, boot, or transport failure. It remains a failed test; consumers may use the tag to distinguish "the oracle did not run" from a behavioral replay divergence without weakening either gate. Script line grammar: diff --git a/test/integration/provider-scenarios/harness-proxy.ts b/test/integration/provider-scenarios/harness-proxy.ts index 1d8f7aa38c..986768e979 100644 --- a/test/integration/provider-scenarios/harness-proxy.ts +++ b/test/integration/provider-scenarios/harness-proxy.ts @@ -214,7 +214,7 @@ function isAllowedUpstreamRoute(method: string | undefined, route: string): bool return /^\/upload\/direct\/[0-9a-f-]+$/i.test(route); case 'GET': return ( - ['/artifacts', '/artifacts/'].includes(route) || + ['/health', '/artifacts', '/artifacts/'].includes(route) || /^\/artifacts\/[0-9a-f-]+$/i.test(route) || /^\/sessions\/(?:[A-Za-z0-9._~-]|%[0-9A-Fa-f]{2})+\/requests\/(?:[A-Za-z0-9._~-]|%[0-9A-Fa-f]{2})+\/diagnostics$/.test( route, @@ -308,7 +308,9 @@ function recordUpstreamResponse( const contentType = Array.isArray(contentTypeHeader) ? contentTypeHeader.join(', ') : contentTypeHeader; - if (contentType?.includes('json') || contentType?.startsWith('text/')) { + // An artifact download is recorded too, so a scenario can compare the served bytes. + const textual = contentType?.includes('json') || contentType?.startsWith('text/'); + if (textual || entry.route.startsWith('/artifacts/')) { entry.responseBody = upstreamResponse.body.toString('utf8'); } } diff --git a/test/integration/provider-scenarios/remote-proxy-artifact-tenant.test.ts b/test/integration/provider-scenarios/remote-proxy-artifact-tenant.test.ts index d128c4ec91..45778445a1 100644 --- a/test/integration/provider-scenarios/remote-proxy-artifact-tenant.test.ts +++ b/test/integration/provider-scenarios/remote-proxy-artifact-tenant.test.ts @@ -154,6 +154,7 @@ test('Provider-backed integration proxy materializes tenant-owned test artifacts request, response, createTestHostEnvironment(), + path.join(tempDir, 'client-state'), ); assert.equal(materialized.ok, true); if (!materialized.ok) return; diff --git a/test/integration/provider-scenarios/remote-script-publication.test.ts b/test/integration/provider-scenarios/remote-script-publication.test.ts new file mode 100644 index 0000000000..6172e98640 --- /dev/null +++ b/test/integration/provider-scenarios/remote-script-publication.test.ts @@ -0,0 +1,440 @@ +import { buildDaemonRpcRequest } from '@agent-device/contracts/lease-scope'; +import type { DaemonWireRequest } from '@agent-device/contracts/command'; +import assert from 'node:assert/strict'; +import crypto from 'node:crypto'; +import fs from 'node:fs'; +import http from 'node:http'; +import path from 'node:path'; +import { test, vi } from 'vitest'; +import { createAgentDeviceClient } from '@agent-device/client'; +import { closeLoopbackServer, listenOnLoopback, mkdtempForTestSync } from '@agent-device/test-kit'; +import { assertRpcOk } from './assertions.ts'; +import { createAndroidSettingsWorld } from './android-world.ts'; +import { withProviderScenarioResource } from './harness.ts'; +import { createProviderScenarioProxy } from './harness-proxy.ts'; + +/** A script version the daemon writes in its private directory. */ +function isDaemonScriptPath(file: fs.PathLike): boolean { + return String(file).includes(`${path.sep}remote-scripts${path.sep}`); +} + +test('a remote recording keeps the caller script current and close writes the final script', async () => { + await withProviderScenarioResource( + () => createAndroidSettingsWorld({ nativeTextInjection: true }), + async (world) => { + const root = mkdtempForTestSync('remote-script-provider-'); + const destination = path.join(root, 'caller', 'journey.ad'); + fs.mkdirSync(path.dirname(destination)); + fs.writeFileSync(destination, 'an earlier recording\n'); + const proxy = await createProviderScenarioProxy(world.daemon, { + clientToken: 'script-client', + }); + const client = createAgentDeviceClient({ + daemonBaseUrl: proxy.baseUrl, + daemonAuthToken: 'script-client', + session: 'script-author', + stateDir: path.join(root, 'client-state'), + }); + try { + await assert.rejects( + client.apps.open({ app: 'settings', saveScript: destination, ...world.selection }), + (error: unknown) => { + assert.equal( + (error as { details?: { reason?: string } }).details?.reason, + 'script_target_exists', + ); + return true; + }, + ); + assert.equal(fs.readFileSync(destination, 'utf8'), 'an earlier recording\n'); + await client.apps.open({ + app: 'settings', + saveScript: destination, + force: true, + ...world.selection, + }); + assert.match(fs.readFileSync(destination, 'utf8'), /^open /m); + + await client.interactions.fill({ + selector: 'id="com.android.settings:id/search"', + text: 'fixture-input', + recordAs: 'SEARCH_TERM', + ...world.selection, + }); + await client.command.wait({ selector: 'label="Apps"', ...world.selection }); + const current = fs.readFileSync(destination, 'utf8'); + assert.match(current, /agent-device:target-v1/); + assert.ok(current.includes('${SEARCH_TERM}')); + assert.equal(current.includes('fixture-input'), false); + assert.equal(current.includes(root), false); + assert.doesNotMatch(current, /^close/m); + + const reply = proxy.forwarded.filter((r) => r.route === '/rpc').at(-1); + assert.ok(reply); + const raw = JSON.parse(reply.responseBody).result.data; + assert.notEqual(raw.savedScript, destination); + const artifact = raw.artifacts.find( + (a: { artifactType: string }) => a.artifactType === 'session-script', + ); + assert.ok(artifact?.artifactId); + const served = proxy.forwarded.find((r) => r.route === `/artifacts/${artifact.artifactId}`); + assert.equal(served?.responseBody, current); + + await client.sessions.close(); + const final = fs.readFileSync(destination, 'utf8'); + assert.ok(final.startsWith(current.trimEnd())); + assert.match(final, /^close/m); + + const replay = await client.replay.run({ + path: destination, + env: ['SEARCH_TERM=second-input'], + ...world.selection, + }); + assert.equal(replay.sessionActive, false); + world.assertNoHostAdbCalls(); + } finally { + await proxy.close(); + } + }, + ); +}, 20_000); + +test('raw remote RPC without a caller path receives script versions by artifact ID', async () => { + await withProviderScenarioResource(createAndroidSettingsWorld, async (world) => { + const proxy = await createProviderScenarioProxy(world.daemon, { clientToken: 'raw-client' }); + const rpc = async ( + command: string, + positionals: string[], + flags: DaemonWireRequest['flags'], + meta?: DaemonWireRequest['meta'], + ) => { + const response = await fetch(`${proxy.baseUrl}/rpc`, { + method: 'POST', + headers: { authorization: 'Bearer raw-client', 'content-type': 'application/json' }, + body: JSON.stringify( + buildDaemonRpcRequest( + { token: 'raw-client', session: 'raw-author', command, positionals, flags, meta }, + { id: command, includeTokenParam: false }, + ), + ), + }); + const reply = await response.json(); + assert.equal(response.status, reply.error ? 400 : 200); + return reply.result ?? { ok: false, error: reply.error.data }; + }; + type ScriptArtifact = { + artifactType: string; + artifactId: string; + path?: string; + scriptPublicationId?: string; + }; + const scriptArtifact = (data: { artifacts: ScriptArtifact[] }) => + data.artifacts.find((entry) => entry.artifactType === 'session-script'); + const download = async (data: { artifacts: ScriptArtifact[] }) => { + const artifact = scriptArtifact(data); + assert.ok(artifact?.artifactId); + assert.equal(artifact.path, undefined); + const url = `${proxy.baseUrl}/artifacts/${artifact.artifactId}`; + assert.equal((await fetch(url)).status, 401); + const downloaded = await fetch(url, { headers: { authorization: 'Bearer raw-client' } }); + assert.equal(downloaded.status, 200); + return await downloaded.text(); + }; + try { + const flags = { ...world.selection, saveScript: true }; + const unnamed = await rpc('open', ['settings'], flags); + assert.equal(unnamed.error?.details?.reason, 'REMOTE_HOST_INPUT_DENIED'); + const scriptPublicationId = crypto.randomUUID(); + const opened = await rpc('open', ['settings'], flags, { scriptPublicationId }); + assert.equal(opened.ok, true, JSON.stringify(opened)); + assert.match(await download(opened.data), /^open /m); + assert.equal(opened.data.scriptPublicationId, scriptPublicationId); + assert.equal(scriptArtifact(opened.data)?.scriptPublicationId, scriptPublicationId); + + const published = await rpc('session_save_script', [], {}); + assert.equal(published.ok, false); + assert.equal(published.error.details.reason, 'REMOTE_HOST_INPUT_DENIED'); + + const closed = await rpc('close', [], {}); + assert.equal(closed.ok, true, JSON.stringify(closed)); + assert.match(await download(closed.data), /^close/m); + assert.equal(closed.data.scriptPublicationId, scriptPublicationId); + assert.equal(scriptArtifact(closed.data)?.scriptPublicationId, scriptPublicationId); + world.assertNoHostAdbCalls(); + } finally { + await proxy.close(); + } + }); +}, 20_000); + +test('a failed script write keeps the action successful and discloses the delivery failure', async () => { + await withProviderScenarioResource(createAndroidSettingsWorld, async (world) => { + const proxy = await createProviderScenarioProxy(world.daemon, { clientToken: 'raw-client' }); + const realLinkSync = fs.linkSync; + const linkSpy = vi.spyOn(fs, 'linkSync'); + try { + assertRpcOk( + await proxy.callCommand( + 'raw-client', + 'open', + ['settings'], + { ...world.selection, saveScript: true }, + { meta: { scriptPublicationId: crypto.randomUUID() } }, + ), + ); + linkSpy.mockImplementation((existing, destination) => { + if (isDaemonScriptPath(destination)) { + throw Object.assign(new Error('disk full'), { code: 'ENOSPC' }); + } + return realLinkSync(existing, destination); + }); + const failed = assertRpcOk<{ + artifacts?: { artifactType?: string }[]; + scriptDeliveryFailure?: { reason: string; message: string; hint: string }; + warnings?: string[]; + }>(await proxy.callCommand('raw-client', 'wait', ['label="Apps"'], world.selection)); + assert.equal(failed.scriptDeliveryFailure?.reason, 'script_delivery_failed'); + assert.doesNotMatch(JSON.stringify(failed), /disk full|remote-scripts/); + assert.ok( + failed.warnings?.some((warning) => warning.includes(failed.scriptDeliveryFailure!.hint)), + ); + assert.equal( + failed.artifacts?.some((artifact) => artifact.artifactType === 'session-script') ?? false, + false, + ); + // A digest response narrows the command's result but keeps the delivery failure. + const digest = assertRpcOk<{ + nodeCount?: number; + scriptDeliveryFailure?: { reason: string }; + }>( + await proxy.callCommand('raw-client', 'snapshot', [], world.selection, { + meta: { responseLevel: 'digest' }, + }), + ); + assert.equal(typeof digest.nodeCount, 'number'); + assert.equal(digest.scriptDeliveryFailure?.reason, 'script_delivery_failed'); + + linkSpy.mockRestore(); + const delivered = assertRpcOk<{ + artifacts: { artifactType?: string; scriptRevision?: number }[]; + }>(await proxy.callCommand('raw-client', 'wait', ['label="Apps"'], world.selection)); + assert.equal( + delivered.artifacts.find((artifact) => artifact.artifactType === 'session-script') + ?.scriptRevision, + 2, + ); + assertRpcOk(await proxy.callCommand('raw-client', 'close')); + } finally { + linkSpy.mockRestore(); + await proxy.close(); + } + }); +}, 20_000); + +test('a failed final write keeps the close and the client forgets the recording', async () => { + await withProviderScenarioResource(createAndroidSettingsWorld, async (world) => { + const root = mkdtempForTestSync('remote-script-close-'); + const destination = path.join(root, 'journey.ad'); + const stateDir = path.join(root, 'client-state'); + const proxy = await createProviderScenarioProxy(world.daemon, { clientToken: 'script-client' }); + const client = createAgentDeviceClient({ + daemonBaseUrl: proxy.baseUrl, + daemonAuthToken: 'script-client', + session: 'close-failure', + stateDir, + }); + const realLinkSync = fs.linkSync; + const linkSpy = vi.spyOn(fs, 'linkSync'); + try { + await client.apps.open({ app: 'settings', saveScript: destination, ...world.selection }); + const opened = fs.readFileSync(destination, 'utf8'); + linkSpy.mockImplementation((existing, target) => { + if (isDaemonScriptPath(target)) { + throw Object.assign(new Error('disk full'), { code: 'ENOSPC' }); + } + return realLinkSync(existing, target); + }); + + await client.sessions.close(); + + const reply = proxy.forwarded.filter((r) => r.route === '/rpc').at(-1); + assert.ok(reply); + const closed = JSON.parse(reply.responseBody).result; + assert.equal(closed.ok, true); + assert.equal(closed.data.scriptDeliveryFailure.reason, 'script_delivery_failed'); + assert.doesNotMatch(reply.responseBody, /disk full/); + assert.ok( + closed.data.warnings.some((warning: string) => + warning.includes(closed.data.scriptDeliveryFailure.hint), + ), + ); + assert.equal(fs.readFileSync(destination, 'utf8'), opened); + const records = path.join(stateDir, 'remote-connections', 'session-scripts'); + assert.deepEqual( + fs.readdirSync(records).filter((name) => name.endsWith('.json')), + [], + ); + } finally { + linkSpy.mockRestore(); + await proxy.close(); + } + }); +}, 20_000); + +test('a failed refresh download through the client keeps the success of the one action it ran', async () => { + await withProviderScenarioResource( + () => createAndroidSettingsWorld({ nativeTextInjection: true }), + async (world) => { + const root = mkdtempForTestSync('remote-script-refresh-'); + const destination = path.join(root, 'journey.ad'); + let refuseArtifacts = false; + const proxy = await createProviderScenarioProxy(world.daemon, { + clientToken: 'script-client', + }); + const upstream = new URL(proxy.baseUrl); + const gate = http.createServer((req, res) => { + if (refuseArtifacts && req.url?.includes('/artifacts/')) { + res.writeHead(503).end('unavailable'); + return; + } + const forwarded = http.request( + { + host: upstream.hostname, + port: upstream.port, + method: req.method, + path: req.url, + headers: req.headers, + }, + (reply) => { + res.writeHead(reply.statusCode ?? 502, reply.headers); + reply.pipe(res); + }, + ); + forwarded.on('error', () => res.destroy()); + req.pipe(forwarded); + }); + const gatePort = await listenOnLoopback(gate); + const client = createAgentDeviceClient({ + daemonBaseUrl: `http://127.0.0.1:${gatePort}${upstream.pathname}`, + daemonAuthToken: 'script-client', + session: 'refresh', + stateDir: path.join(root, 'client-state'), + }); + try { + await client.apps.open({ app: 'settings', saveScript: destination, ...world.selection }); + const opened = fs.readFileSync(destination, 'utf8'); + + refuseArtifacts = true; + // The fill succeeded on the device, so a failed script download keeps its success. + await client.interactions.fill({ + selector: 'id="com.android.settings:id/search"', + text: 'fixture-input', + ...world.selection, + }); + assert.equal(world.textInjectionCalls.length, 1); + assert.equal(fs.readFileSync(destination, 'utf8'), opened); + + refuseArtifacts = false; + await client.sessions.close(); + const final = fs.readFileSync(destination, 'utf8'); + assert.match(final, /^fill /m); + assert.match(final, /^close/m); + assert.equal(world.textInjectionCalls.length, 1); + } finally { + await closeLoopbackServer(gate); + await proxy.close(); + } + }, + ); +}, 20_000); + +test('a direct daemon refreshes the caller script on every action and retires an aborted recording', async () => { + await withProviderScenarioResource(createAndroidSettingsWorld, async (world) => { + const root = mkdtempForTestSync('remote-script-direct-'); + const destination = path.join(root, 'journey.ad'); + const stateDir = path.join(root, 'client-state'); + const client = createAgentDeviceClient({ + daemonBaseUrl: world.daemon.baseUrl, + daemonAuthToken: world.daemon.token, + session: 'direct-author', + stateDir, + }); + const records = path.join(stateDir, 'remote-connections', 'session-scripts'); + const recordFiles = () => fs.readdirSync(records).filter((name) => name.endsWith('.json')); + + await client.apps.open({ app: 'settings', saveScript: destination, ...world.selection }); + await client.command.wait({ selector: 'label="Apps"', ...world.selection }); + assert.match(fs.readFileSync(destination, 'utf8'), /^wait /m); + await client.sessions.close(); + assert.match(fs.readFileSync(destination, 'utf8'), /^close/m); + assert.deepEqual(recordFiles(), []); + + const aborted = path.join(root, 'aborted.ad'); + await client.apps.open({ app: 'settings', saveScript: aborted, ...world.selection }); + assert.equal(recordFiles().length, 1); + const abortedBytes = fs.readFileSync(aborted, 'utf8'); + await client.apps.open({ app: 'settings', ...world.selection }); + await client.sessions.close(); + assert.deepEqual(recordFiles(), []); + assert.equal(fs.readFileSync(aborted, 'utf8'), abortedBytes); + world.assertNoHostAdbCalls(); + }); +}, 20_000); + +test('capture commands refresh the caller script through a proxy', async () => { + await withProviderScenarioResource(createAndroidSettingsWorld, async (world) => { + const root = mkdtempForTestSync('remote-script-capture-'); + const destination = path.join(root, 'journey.ad'); + const proxy = await createProviderScenarioProxy(world.daemon, { clientToken: 'script-client' }); + const client = createAgentDeviceClient({ + daemonBaseUrl: proxy.baseUrl, + daemonAuthToken: 'script-client', + session: 'capture-author', + stateDir: path.join(root, 'client-state'), + }); + try { + await client.apps.open({ app: 'settings', saveScript: destination, ...world.selection }); + await client.recording.trace({ + action: 'start', + path: path.join(root, 'session.trace'), + ...world.selection, + }); + assert.match(fs.readFileSync(destination, 'utf8'), /^trace "start"/m); + await client.observability.perf({ area: 'frames', ...world.selection }); + assert.match(fs.readFileSync(destination, 'utf8'), /^perf\b/m); + await client.sessions.close(); + } finally { + await proxy.close(); + } + }); +}, 20_000); + +test('close delivers the final script after it stops an app log', async () => { + await withProviderScenarioResource(createAndroidSettingsWorld, async (world) => { + const root = mkdtempForTestSync('remote-script-capture-close-'); + const destination = path.join(root, 'journey.ad'); + const stateDir = path.join(root, 'client-state'); + const proxy = await createProviderScenarioProxy(world.daemon, { clientToken: 'script-client' }); + const client = createAgentDeviceClient({ + daemonBaseUrl: proxy.baseUrl, + daemonAuthToken: 'script-client', + session: 'capture-close', + stateDir, + }); + try { + await client.apps.open({ app: 'settings', saveScript: destination, ...world.selection }); + await client.observability.logs({ action: 'start', ...world.selection }); + + await client.sessions.close(); + + assert.match(fs.readFileSync(destination, 'utf8'), /^close/m); + const records = path.join(stateDir, 'remote-connections', 'session-scripts'); + assert.deepEqual( + fs.readdirSync(records).filter((name) => name.endsWith('.json')), + [], + ); + } finally { + await proxy.close(); + } + }); +}, 20_000); diff --git a/test/integration/provider-scenarios/remote-test-artifacts-materialization.test.ts b/test/integration/provider-scenarios/remote-test-artifacts-materialization.test.ts index 913603296b..f9b7575c9e 100644 --- a/test/integration/provider-scenarios/remote-test-artifacts-materialization.test.ts +++ b/test/integration/provider-scenarios/remote-test-artifacts-materialization.test.ts @@ -108,6 +108,7 @@ test('the composed daemon and client path materializes the directory produced by request, response, createTestHostEnvironment(), + path.join(tempDir, 'client-state'), ); assert.equal(materialized.ok, true); if (!materialized.ok) return; diff --git a/test/wire-compat/ledger.json b/test/wire-compat/ledger.json index 6abd0a754c..7d2653dd98 100644 --- a/test/wire-compat/ledger.json +++ b/test/wire-compat/ledger.json @@ -3,8 +3,8 @@ "declarations": { "packages/contracts/src/daemon-http.ts#DAEMON_HTTP_BASE_PATH": "sha256:a1ada25c6f90d9c69c8c836538e8882547bf239559f7c1accacd0654355802dd", "packages/contracts/src/daemon-http.ts#DAEMON_HTTP_TENANT_HEADER": "sha256:ed49119d232500885f014ac73f6123d298d404c6c176abdae59cf324825927e5", - "packages/contracts/src/daemon-http.ts#DaemonHealthPayload": "sha256:ece08b91cc46c1397309a05a68f1e1be3999cd4b069c4c3b6bc5b75a5700f108", - "packages/contracts/src/daemon-http.ts#buildDaemonHealthPayload": "sha256:49a46bd62207a69a359e7c8be6f97c07748af21344452be1d32507b95ce4650b", + "packages/contracts/src/daemon-http.ts#DaemonHealthPayload": "sha256:466c1c0bb01d3b61ef67695c835bac2ac20e10f4c7d11a5d0f54963e5e4f792c", + "packages/contracts/src/daemon-http.ts#buildDaemonHealthPayload": "sha256:807a09e96c57595a5d903c07d35443e1e166496405ffd4787ff8450c15e3a890", "packages/contracts/src/daemon-http.ts#buildDaemonHttpAuthHeaders": "sha256:5548a44d6248ed858d19a0b2985ec4ae8a7181bae8294b85edf3c1b3b58e80d4", "packages/contracts/src/daemon-http.ts#buildDaemonHttpBaseUrl": "sha256:f92697208d9f42ec0dcfb006b6f2dce761bd5307db27ce2e52927fd7742e3a9a", "packages/contracts/src/daemon-http.ts#buildDaemonHttpTenantHeaders": "sha256:e38a5f0b5ab07ee3a5fe3db229d0de750888660c55bf31692e100002be96de1d", @@ -16,13 +16,13 @@ "packages/contracts/src/request-progress.ts#RequestProgressEvent": "sha256:2516c4d0a4e831f779d68e692158b863f6b42c78a7eaac6607ebbffe2d4b6ce5", "packages/kernel/src/contracts.ts#CommandRpcParams": "sha256:3a400b0d815920d9cf4c6236531931f6ba6f9debf7ac26915e0116b493f1c97a", "packages/kernel/src/contracts.ts#DAEMON_LOCK_POLICIES": "sha256:625cc33bb574aa6119add45878a0f6adc445244edc2957737da975f91605c786", - "packages/kernel/src/contracts.ts#DaemonArtifact": "sha256:967c919d878b83b6e0324c56c1bf41e63b0c31c2e42cf41cd5a12902c2b5034a", - "packages/kernel/src/contracts.ts#DaemonArtifactKnownType": "sha256:b16ce8169a6314168b36b42cc3c042f722781b49695cb290674f4e5216d83b3b", + "packages/kernel/src/contracts.ts#DaemonArtifact": "sha256:77dee23e48dc77febb33efadc85377cbbcd137389ae7b33e93ba31670565fdf6", + "packages/kernel/src/contracts.ts#DaemonArtifactKnownType": "sha256:4a55e654d15d4719a579df4aa1929dda1d52a4acf4c71e9ff78814ad09d6d233", "packages/kernel/src/contracts.ts#DaemonArtifactType": "sha256:5e5017276fefe880b8ab32001888011d2e02a8670f0978afdb9b56a77ab37f09", "packages/kernel/src/contracts.ts#DaemonInstallSource": "sha256:fe26e202e62d997cdd3855fd96002511783a6c26a9ce27210d7c6cc084c66e4e", "packages/kernel/src/contracts.ts#DaemonLockPolicy": "sha256:f33d0ce7200a7d97c11e91bd2889b5d9bc7f35935a5370a29930118d091468f4", "packages/kernel/src/contracts.ts#DaemonRequest": "sha256:911d93245b8dc557db897c4cac051030db673711bf3af51baa8b82248d509c57", - "packages/kernel/src/contracts.ts#DaemonRequestMeta": "sha256:95c8aabe103b00af574ab5e97762fb295e44f1f5b17b69b11b5493cc56e4c1a1", + "packages/kernel/src/contracts.ts#DaemonRequestMeta": "sha256:c2b14225388041f3a6e708c898c512f91b9b20e51a2656a1fa0d5bfa5989fa30", "packages/kernel/src/contracts.ts#DaemonResponse": "sha256:5f6cc08ed43f40c1cf17e33dd2b6b879dda1ac383de9c6c9a2c653929c21346b", "packages/kernel/src/contracts.ts#DaemonResponseData": "sha256:f16e61b7f0ea8cdae82349508383af2f97a4c16c8aa21952d833094673f86afc", "packages/kernel/src/contracts.ts#JsonRpcId": "sha256:5a5fdff1cd85971214117d69a8278d0ecaf21a6fa3f4582155d9b3d9cad1fbd0", @@ -58,15 +58,15 @@ "packages/daemon-client/src/daemon-client-progress.ts#shouldReadDaemonProgressStream": "sha256:27ac0a5299324aab39fa2c4fe0e0d32b1eb1515df47c7f4aa75a75d66b8b5a3e", "packages/daemon-client/src/daemon-client-rpc.ts#appErrorFromDaemonError": "sha256:ac4761006c71d93ccba9f8e37cbd4cf48283dbb22737c163dc9c1a878e154eea", "packages/daemon-client/src/daemon-client-rpc.ts#buildHttpRpcPayload": "sha256:8978ef89d3af866bd94fec52c586a0cbf3217ee9e60952fbc826e8208e5fa158", - "packages/daemon-client/src/daemon-client-rpc.ts#handleDaemonHttpResponseBody": "sha256:a57e0ba3d6d410f5aa2dfd08872e583227098b2795e35e2a6b5a28f764dd8d38", + "packages/daemon-client/src/daemon-client-rpc.ts#handleDaemonHttpResponseBody": "sha256:5d111b5cb758578d810f2540086d2730459a80ee56f2fb9c14555bd6fe4e1792", "packages/daemon-client/src/daemon-client-rpc.ts#parseDaemonHttpResponseBody": "sha256:0cbe39dbd09e321ec00854a1626a7d89b6344e59c6faabe2fe02504268b2d886", "packages/daemon-client/src/daemon-client-rpc.ts#rejectDaemonHttpRpcError": "sha256:a5cf6fd4a9abea34ec051f03d6e45e5aa248f480371fdf22f93de06622a57b47", - "packages/daemon-client/src/daemon-client-rpc.ts#resolveDaemonHttpResult": "sha256:b38df93a38bba4b350da2a78486f032a7f9344954dd11b7c09035bbc35c13a91", + "packages/daemon-client/src/daemon-client-rpc.ts#resolveDaemonHttpResult": "sha256:75226219f3d2475b59b297593346879c5211f56530a45494ff696b435e002bce", "packages/daemon-client/src/daemon-client-rpc.ts#toDaemonHttpRpcError": "sha256:888246763c48670e7da893054d025744654f8715c3b4906312617a2b5028316b", - "packages/daemon-client/src/daemon-client-transport.ts#RemoteDaemonHealth": "sha256:3bac36fa97090b273afe1128103e1bf476d05441fd9de41317f1b78775b88304", - "packages/daemon-client/src/daemon-client-transport.ts#RemoteDaemonHealthLink": "sha256:7702598468b4c82b4ffa93064cd6bdfec938c1c527f7e6007c0584f3884a6eea", + "packages/daemon-client/src/daemon-client-transport.ts#RemoteDaemonHealth": "sha256:1ff542dadff6d92233c464b7d09052d809f36186bb60acdb572c48bfc1eb5c1f", + "packages/daemon-client/src/daemon-client-transport.ts#RemoteDaemonHealthLink": "sha256:96a79a8ff5a078916ee7bffed1d9624d0ba9c0dcbd8e2c55f9abf37fccfef744", "packages/daemon-client/src/daemon-client-transport.ts#readDaemonHttpHealth": "sha256:6ce1f9be1e6a977130d0875003ac22da2de5e90b514a3b22b30b9347e63d81c7", - "packages/daemon-client/src/daemon-client-transport.ts#readHealthLink": "sha256:f56404b94d73da57de7248719c9136b760d2be8b4a53cde5315a2311b088425b", + "packages/daemon-client/src/daemon-client-transport.ts#readHealthLink": "sha256:b709f88901784e767a542acc27d90ba080e7b016e85d6053a59df3495454ae3b", "packages/daemon-client/src/daemon-client-transport.ts#readHealthPayload": "sha256:4e85ffc3e35e02379c393e9312344757e003cf1f0ad9eb8d1f77d90c81c861f1", "packages/daemon-client/src/daemon-client-transport.ts#readRemoteDaemonHealth": "sha256:df174d1ccf73851ca58bd75533fb4660424003b98bd9e41fe942cf3ab3698e5f", "packages/daemon/src/server/downloadable-artifact-http.ts#DownloadableArtifactHttpAuthorizer": "sha256:1b2702a929ca9170db2ca97c08e3ab67e17edb3ee75325a576c4c1b9cdbebb44", @@ -145,14 +145,14 @@ "packages/daemon/src/server/upload-http.ts#resolveUploadHttpRoute": "sha256:d744044d036a46221c3b8220179cc30e1e66b8619a4e5cd3f7dd5f8582817aba", "packages/daemon/src/server/upload-http.ts#sendJson": "sha256:c2317b4b14a10731684c9160038005965856150f05f8923765a3fa833d2ecae9", "packages/daemon/src/server/upload-http.ts#sendUploadedArtifactResponse": "sha256:9e418403448d58a96284fed605762fa71f9349bf2c70ad79df69b2b3e27487d6", - "packages/remote/src/artifact-download.ts#RemoteArtifactDownload": "sha256:f73a888f4f8c9d603701c505bb342787b1ca6559a13b15da2385e60349ecea8e", + "packages/remote/src/artifact-download.ts#RemoteArtifactDownload": "sha256:e87a625bdff05fa55f6321ff09a35496f59edd228a1d7420268d54fcc2982868", "packages/remote/src/artifact-download.ts#downloadRemoteArtifactFromUrl": "sha256:2e71ca375778c131e99a645a16b1f491d8dd6a10a3198d696e6138e46b601785", "packages/remote/src/daemon-artifacts.ts#DaemonArtifactEndpoint": "sha256:45226717ac52c0af2a62f74e91549582d95f4a4abc49be87989e026291a88c82", - "packages/remote/src/daemon-artifacts.ts#DownloadRemoteArtifactParams": "sha256:ba6d2f6ac51e05ccc5e0c940b355d62374e018b1ae6f6f744becf6e1760cbb63", + "packages/remote/src/daemon-artifacts.ts#DownloadRemoteArtifactParams": "sha256:3b0678250f72dca4ac1709103fd4c540dedd4d488eb3299ace5ce6b7c479676c", "packages/remote/src/daemon-artifacts.ts#buildDaemonArtifactUrl": "sha256:06dcde057809b507f70f7bb5cdef9bde6515be84b67e45865cf19e70b8636208", - "packages/remote/src/daemon-artifacts.ts#downloadRemoteArtifact": "sha256:f3ab09ce387577073ecc5bcd2528963e45f91b2c1e4cc57847c3e2732ccbb300", + "packages/remote/src/daemon-artifacts.ts#downloadRemoteArtifact": "sha256:3f3b6c01601c54ab2c76c8cb0946de623da4d24ba32254c75ae8a3993f66adcf", "packages/remote/src/daemon-artifacts.ts#isRemoteDaemon": "sha256:0f6a714c5f60ce4e8548d811b516d8b6241eca9f7e5414733732da395b8a00e7", - "packages/remote/src/daemon-artifacts.ts#materializeRemoteArtifacts": "sha256:fffe8ce578e8bcdea175d6a200bea364ffce0956c2cba65bea48d72c0aaea375", + "packages/remote/src/daemon-artifacts.ts#materializeRemoteArtifacts": "sha256:654a8f47f437430a0947a44d1c126c253448351f02cd8f46dd32bde13278f1cc", "packages/remote/src/daemon-artifacts.ts#resolveMaterializedArtifactPath": "sha256:660320cd62dfaeb4da80b86d6c072a5bcdbce3399723d43208a22d70b6e4a243", "packages/remote/src/remote-request-diagnostics.ts#RemoteDaemonErrorPayload": "sha256:8fbcbcdf4bae7b66a08e465a72593794f36364759f18f1a814cd39dfdb76f309", "packages/remote/src/remote-request-diagnostics.ts#RemoteDiagnosticsEndpoint": "sha256:c1d5fe2fe90c425502cf8b7c87d6606374d6af65b4e9faf942a416f683930bdc", @@ -206,33 +206,41 @@ "packages/contracts/src/device-inventory.ts#readDevicePin": "sha256:bb15ca2a086a881c6cf945c25d432c092be165e58165d229c25df69c4c9fafbd", "packages/proxy/src/daemon-proxy.ts#rewriteUploadDirectUrl": "sha256:b121db3ffb5a520b4b31810a2e28ff01c1a15d959514c9fbe2a61cd960d2af93", "packages/proxy/src/daemon-proxy.ts#rewriteUploadPreflightResponse": "sha256:332820b6f10e079632330c2c4996c4faa6f339e921f12f287bd83c9296df5ccd", - "packages/proxy/src/daemon-proxy.ts#rewrittenUploadPreflightResponse": "sha256:21d633d947cd72f5008bcc886a8f3ecd4f778b594d0654b8d0741db8594003db" + "packages/proxy/src/daemon-proxy.ts#rewrittenUploadPreflightResponse": "sha256:21d633d947cd72f5008bcc886a8f3ecd4f778b594d0654b8d0741db8594003db", + "packages/daemon-contracts/src/daemon-resolution.ts#DAEMON_CAPABILITIES": "sha256:3478986d0e7b0e55e965c087a7b1dfd3cc018abdb372dba256cf90d27e63ed0b", + "packages/daemon-contracts/src/daemon-resolution.ts#DaemonCapability": "sha256:2a5acf280a72e3d54c5ad7b52aece3ced37a30e4e721ef106a98e3bbd18ddbc3", + "packages/daemon-contracts/src/daemon-resolution.ts#readDaemonCapabilities": "sha256:e410d36be74d307f7e5d8ddae63af5aae77f8eef77951ce9eeb7724f2fefae88", + "packages/remote/src/daemon-artifacts.ts#downloadResponseArtifacts": "sha256:42d78f01311e3e0c5f9099ef72e3c6258241e66204747aa176a55cd5191a2145", + "packages/remote/src/session-script-destination.ts#SessionScriptDelivery": "sha256:741fafbb8e2b43e2e967b2f4206f1d60017a636f63e3cde68b6258fd4efefa18", + "packages/remote/src/session-script-destination.ts#publishScriptVersion": "sha256:b128203c4545f4f620211c917707173f97a67a3355cbfc2dbf4d08e719a994d2", + "packages/remote/src/session-script-destination.ts#sendRemoteScriptOpen": "sha256:10ab07a6f276c7b03996c6b46fa218e03e7b1d21e2c95df5515dfb88095416b6", + "packages/remote/src/session-script-destination.ts#RemoteEndpoint": "sha256:9c48e8e0ee14a25b85ebd930243fd263134836b35ecda55fb927919911263c15" }, "compatibleChanges": [ { "declaration": "packages/kernel/src/contracts.ts#DaemonRequestMeta", - "digest": "sha256:95c8aabe103b00af574ab5e97762fb295e44f1f5b17b69b11b5493cc56e4c1a1", - "rationale": "Adds the optional developerDir field: a local client's DEVELOPER_DIR, overlaid on the env of commands the daemon spawns for that request. A released daemon ignores the unknown meta key and keeps its own environment, exactly as before; a released client never sends it, so the new daemon inherits its own environment for that request. The remote HTTP surface strips it. Also adds the optional leaseRetainOnClose field, sent only on lease_allocate when the caller opts in: a released daemon ignores the unknown meta key and releases the lease on session close as before, and a released client never sends it. Adds the optional providerCredentialFingerprint field: a digest of the local caller's provider credential variables, which the daemon compares with its own on lease_allocate. A released daemon ignores the unknown meta key and allocates as before; a released client never sends it, so the new daemon skips the comparison. The client sends it only to a local daemon, and the remote HTTP surface strips it." + "digest": "sha256:c2b14225388041f3a6e708c898c512f91b9b20e51a2656a1fa0d5bfa5989fa30", + "rationale": "Adds the optional developerDir field: a local client's DEVELOPER_DIR, overlaid on the env of commands the daemon spawns for that request. A released daemon ignores the unknown meta key and keeps its own environment, exactly as before; a released client never sends it, so the new daemon inherits its own environment for that request. The remote HTTP surface strips it. Also adds the optional leaseRetainOnClose field, sent only on lease_allocate when the caller opts in: a released daemon ignores the unknown meta key and releases the lease on session close as before, and a released client never sends it. Adds the optional providerCredentialFingerprint field: a digest of the local caller's provider credential variables, which the daemon compares with its own on lease_allocate. A released daemon ignores the unknown meta key and allocates as before; a released client never sends it, so the new daemon skips the comparison. The client sends it only to a local daemon, and the remote HTTP surface strips it. #4511 adds the optional scriptPublicationId string, which a new client sends only on a remote open --save-script to a daemon that reports the script-artifacts capability. Any other request keeps its previous meta." }, { "declaration": "packages/kernel/src/contracts.ts#DaemonArtifactKnownType", - "digest": "sha256:b16ce8169a6314168b36b42cc3c042f722781b49695cb290674f4e5216d83b3b", - "rationale": "#2747 adds the 'screen-recording-contact-sheet' literal for the PNG that `record contact-sheet` publishes beside the recording it read. DaemonArtifactType already widens to `(string & {})`, so an artifactType value outside the known set was always valid on the wire; the literal only sharpens the type hint for code that opts into recognizing it. A released peer that does not know it never requests that field in a download and parses the artifact record by its `field`, so it carries the sheet as an unknown artifact instead of failing." + "digest": "sha256:4a55e654d15d4719a579df4aa1929dda1d52a4acf4c71e9ff78814ad09d6d233", + "rationale": "#2747 adds the 'screen-recording-contact-sheet' literal for the PNG that `record contact-sheet` publishes beside the recording it read. DaemonArtifactType already widens to `(string & {})`, so an artifactType value outside the known set was always valid on the wire; the literal only sharpens the type hint for code that opts into recognizing it. A released peer that does not know it never requests that field in a download and parses the artifact record by its `field`, so it carries the sheet as an unknown artifact instead of failing. #4511 adds the session-script literal the same way. A released client downloads it like any other file artifact named by its field; only a new client, which asked for remote script delivery, gives it a special destination." }, { "declaration": "packages/remote/src/daemon-artifacts.ts#DownloadRemoteArtifactParams", - "digest": "sha256:ba6d2f6ac51e05ccc5e0c940b355d62374e018b1ae6f6f744becf6e1760cbb63", - "rationale": "#2246 adds the optional isDirectory field. It is pure client-local state — never serialized, never sent to the daemon — that tells the CLIENT'S OWN download logic to extract a tar body instead of writing it verbatim; the GET /artifacts/:id request and response framing are unchanged. Every existing call site (screenshot, recording) omits it and keeps writing a single file exactly as before. The signature also names the client request as DaemonWireRequest and the response as the kernel DaemonResponse instead of the daemon package aliases; only compile-time type names moved." + "digest": "sha256:3b0678250f72dca4ac1709103fd4c540dedd4d488eb3299ace5ce6b7c479676c", + "rationale": "#2246 adds the optional isDirectory field. It is pure client-local state — never serialized, never sent to the daemon — that tells the CLIENT'S OWN download logic to extract a tar body instead of writing it verbatim; the GET /artifacts/:id request and response framing are unchanged. Every existing call site (screenshot, recording) omits it and keeps writing a single file exactly as before. The signature also names the client request as DaemonWireRequest and the response as the kernel DaemonResponse instead of the daemon package aliases; only compile-time type names moved. #4511 adds the optional client-local privateFile field, passed through to the downloader. It is never sent, and every existing call site omits it." }, { "declaration": "packages/remote/src/daemon-artifacts.ts#downloadRemoteArtifact", - "digest": "sha256:f3ab09ce387577073ecc5bcd2528963e45f91b2c1e4cc57847c3e2732ccbb300", - "rationale": "#2246 selects a file or directory destination once. Directory downloads stage and safely extract beside the destination, propagate timeout cancellation through both operations, and atomically rename the complete top-level entry; returning that local path is client-only state. The GET /artifacts/:id request and response framing, and every existing file artifact call site's behavior, are unchanged." + "digest": "sha256:3f3b6c01601c54ab2c76c8cb0946de623da4d24ba32254c75ae8a3993f66adcf", + "rationale": "#2246 selects a file or directory destination once. Directory downloads stage and safely extract beside the destination, propagate timeout cancellation through both operations, and atomically rename the complete top-level entry; returning that local path is client-only state. The GET /artifacts/:id request and response framing, and every existing file artifact call site's behavior, are unchanged. #4511 passes every download parameter, including the new client-local maxBytes, through to the downloader instead of copying each field. The GET /artifacts/:id request and response framing are unchanged." }, { "declaration": "packages/remote/src/daemon-artifacts.ts#materializeRemoteArtifacts", - "digest": "sha256:fffe8ce578e8bcdea175d6a200bea364ffce0956c2cba65bea48d72c0aaea375", - "rationale": "#2246 passes isDirectory only for the new test-artifacts type and uses the exact path the client materializer published. Existing screenshot and recording artifacts still report their requested file path; only the new directory response gains its suite-invocation segment. The signature also names the client request as DaemonWireRequest and the response as the kernel DaemonResponse instead of the daemon package aliases; only compile-time type names moved. The function now takes the client host as a parameter and resolves a relative local path against its working directory instead of the process's; the client binds the same directory, so nothing a peer parses moves." + "digest": "sha256:654a8f47f437430a0947a44d1c126c253448351f02cd8f46dd32bde13278f1cc", + "rationale": "#2246 passes isDirectory only for the new test-artifacts type and uses the exact path the client materializer published. Existing screenshot and recording artifacts still report their requested file path; only the new directory response gains its suite-invocation segment. The signature also names the client request as DaemonWireRequest and the response as the kernel DaemonResponse instead of the daemon package aliases; only compile-time type names moved. The function now takes the client host as a parameter and resolves a relative local path against its working directory instead of the process's; the client binds the same directory, so nothing a peer parses moves. #4511 takes the client state directory and gives the savedScript field its own path: the client writes a session-script artifact only to the destination that its own open --save-script recorded for that endpoint, tenant, session and scriptPublicationId, and only when its scriptRevision is newer than the version already published there. A savedScript artifact of another type, or one without a matching record, is dropped. A close retires the record that the optional response field scriptPublicationId names. The per-artifact download loop moved unchanged into a private helper, so other artifact kinds and the GET /artifacts/:id framing are unchanged." }, { "declaration": "packages/daemon-client/src/daemon-client-rpc.ts#buildHttpRpcPayload", @@ -336,28 +344,28 @@ }, { "declaration": "packages/contracts/src/daemon-http.ts#DaemonHealthPayload", - "digest": "sha256:ece08b91cc46c1397309a05a68f1e1be3999cd4b069c4c3b6bc5b75a5700f108", - "rationale": "#2650 adds an optional daemon instance ID to health metadata or reads it when present, #3047 adds an optional hostArch the same way, and #3229 adds an optional leaseBackends list the same way. Older peers ignore the added fields, and new clients keep probing legacy peers that send neither; existing fields and RPC envelopes are unchanged." + "digest": "sha256:466c1c0bb01d3b61ef67695c835bac2ac20e10f4c7d11a5d0f54963e5e4f792c", + "rationale": "#2650 adds an optional daemon instance ID to health metadata or reads it when present, #3047 adds an optional hostArch the same way, and #3229 adds an optional leaseBackends list the same way. Older peers ignore the added fields, and new clients keep probing legacy peers that send neither; existing fields and RPC envelopes are unchanged. #4511 adds an optional capabilities array the same way. Released clients ignore it; a new client treats an absent array as no capability." }, { "declaration": "packages/contracts/src/daemon-http.ts#buildDaemonHealthPayload", - "digest": "sha256:49a46bd62207a69a359e7c8be6f97c07748af21344452be1d32507b95ce4650b", - "rationale": "#2650 adds an optional daemon instance ID to health metadata or reads it when present, #3047 adds an optional hostArch the same way, and #3229 adds an optional leaseBackends list the same way. Older peers ignore the added fields, and new clients keep probing legacy peers that send neither; existing fields and RPC envelopes are unchanged." + "digest": "sha256:807a09e96c57595a5d903c07d35443e1e166496405ffd4787ff8450c15e3a890", + "rationale": "#2650 adds an optional daemon instance ID to health metadata or reads it when present, #3047 adds an optional hostArch the same way, and #3229 adds an optional leaseBackends list the same way. Older peers ignore the added fields, and new clients keep probing legacy peers that send neither; existing fields and RPC envelopes are unchanged. #4511 emits the optional capabilities array only when a caller supplies it, so every existing caller produces the previous payload." }, { "declaration": "packages/daemon-client/src/daemon-client-transport.ts#RemoteDaemonHealth", - "digest": "sha256:3bac36fa97090b273afe1128103e1bf476d05441fd9de41317f1b78775b88304", - "rationale": "#2650 adds an optional daemon instance ID to health metadata or reads it when present, #3047 adds an optional hostArch the same way, and #3229 adds an optional leaseBackends list the same way. Older peers ignore the added fields, and new clients keep probing legacy peers that send neither; existing fields and RPC envelopes are unchanged. A restart retry must tell a probe that ran out of time from one that failed, so the client can report the RPC deadline instead of 'Remote daemon is unavailable'. `timedOut` is client-local: the prober sets it on its own timeout and abort paths and never reads it from a /health payload. The health request and the accepted payload fields are unchanged, so a released daemon or proxy is probed and parsed exactly as before." + "digest": "sha256:1ff542dadff6d92233c464b7d09052d809f36186bb60acdb572c48bfc1eb5c1f", + "rationale": "#2650 adds an optional daemon instance ID to health metadata or reads it when present, #3047 adds an optional hostArch the same way, and #3229 adds an optional leaseBackends list the same way. Older peers ignore the added fields, and new clients keep probing legacy peers that send neither; existing fields and RPC envelopes are unchanged. A restart retry must tell a probe that ran out of time from one that failed, so the client can report the RPC deadline instead of 'Remote daemon is unavailable'. `timedOut` is client-local: the prober sets it on its own timeout and abort paths and never reads it from a /health payload. The health request and the accepted payload fields are unchanged, so a released daemon or proxy is probed and parsed exactly as before. #4511 adds optional parsed capabilities. A released daemon or proxy that sends none parses as before and only loses remote --save-script, which the client refuses before any RPC." }, { "declaration": "packages/daemon-client/src/daemon-client-transport.ts#RemoteDaemonHealthLink", - "digest": "sha256:7702598468b4c82b4ffa93064cd6bdfec938c1c527f7e6007c0584f3884a6eea", - "rationale": "#2650 adds an optional daemon instance ID to health metadata or reads it when present, #3047 adds an optional hostArch the same way, and #3229 adds an optional leaseBackends list the same way. Older peers ignore the added fields, and new clients keep probing legacy peers that send neither; existing fields and RPC envelopes are unchanged." + "digest": "sha256:96a79a8ff5a078916ee7bffed1d9624d0ba9c0dcbd8e2c55f9abf37fccfef744", + "rationale": "#2650 adds an optional daemon instance ID to health metadata or reads it when present, #3047 adds an optional hostArch the same way, and #3229 adds an optional leaseBackends list the same way. Older peers ignore the added fields, and new clients keep probing legacy peers that send neither; existing fields and RPC envelopes are unchanged. #4511 adds optional capabilities to the parsed link; a link without them parses exactly as before." }, { "declaration": "packages/daemon-client/src/daemon-client-transport.ts#readHealthLink", - "digest": "sha256:f56404b94d73da57de7248719c9136b760d2be8b4a53cde5315a2311b088425b", - "rationale": "#2650 adds an optional daemon instance ID to health metadata or reads it when present, #3047 adds an optional hostArch the same way, and #3229 adds an optional leaseBackends list the same way. Older peers ignore the added fields, and new clients keep probing legacy peers that send neither; existing fields and RPC envelopes are unchanged." + "digest": "sha256:b709f88901784e767a542acc27d90ba080e7b016e85d6053a59df3495454ae3b", + "rationale": "#2650 adds an optional daemon instance ID to health metadata or reads it when present, #3047 adds an optional hostArch the same way, and #3229 adds an optional leaseBackends list the same way. Older peers ignore the added fields, and new clients keep probing legacy peers that send neither; existing fields and RPC envelopes are unchanged. #4511 reads an optional capabilities array and omits the field when a peer does not send one, so a released payload parses to the same object." }, { "declaration": "packages/contracts/src/daemon-http.ts#DAEMON_HTTP_INSTANCE_HEADER", @@ -481,13 +489,13 @@ }, { "declaration": "packages/daemon-client/src/daemon-client-rpc.ts#handleDaemonHttpResponseBody", - "digest": "sha256:a57e0ba3d6d410f5aa2dfd08872e583227098b2795e35e2a6b5a28f764dd8d38", - "rationale": "#1801 client-side only: the RPC error branch now runs through `rejectDaemonHttpRpcError`, which reads a superset of the fields it read before and, for a remote daemon, replaces the daemon-host `logPath` with a caller-local copy. Every field a released daemon sends is still accepted; nothing new is required of the daemon. The signature also names the client request as DaemonWireRequest and the response as the kernel DaemonResponse instead of the daemon package aliases; only compile-time type names moved. The function now takes the client host as a parameter and resolves a relative local path against its working directory instead of the process's; the client binds the same directory, so nothing a peer parses moves. #4302 (client-side only): the two invalid-response rejections also gain details.reason 'daemon_response_invalid', so the client can disclose whether the request reached the device; nothing is sent or read differently." + "digest": "sha256:5d111b5cb758578d810f2540086d2730459a80ee56f2fb9c14555bd6fe4e1792", + "rationale": "#1801 client-side only: the RPC error branch now runs through `rejectDaemonHttpRpcError`, which reads a superset of the fields it read before and, for a remote daemon, replaces the daemon-host `logPath` with a caller-local copy. Every field a released daemon sends is still accepted; nothing new is required of the daemon. The signature also names the client request as DaemonWireRequest and the response as the kernel DaemonResponse instead of the daemon package aliases; only compile-time type names moved. The function now takes the client host as a parameter and resolves a relative local path against its working directory instead of the process's; the client binds the same directory, so nothing a peer parses moves. #4302 (client-side only): the two invalid-response rejections also gain details.reason 'daemon_response_invalid', so the client can disclose whether the request reached the device; nothing is sent or read differently. #4511 (client-side only): the success branch passes the client state directory along with the host, so remote artifact materialization can read the client's own record of a remote recording's destination. Nothing is sent or parsed differently." }, { "declaration": "packages/daemon-client/src/daemon-client-rpc.ts#resolveDaemonHttpResult", - "digest": "sha256:b38df93a38bba4b350da2a78486f032a7f9344954dd11b7c09035bbc35c13a91", - "rationale": "The client names its request as DaemonWireRequest (packages/contracts/src/daemon-wire-request.ts, a narrowing of the listed kernel DaemonRequest) and its response as the kernel DaemonResponse, instead of the daemon package's DaemonRequest/DaemonResponse aliases, so the daemon package is no longer a client import. The declaration's serialized fields, method names and framing are unchanged; only the compile-time type names in its signature moved, so a peer on protocol 2 parses exactly what it did. The function now takes the client host as a parameter and resolves a relative local path against its working directory instead of the process's; the client binds the same directory, so nothing a peer parses moves. #4302 (client-side only): when materializing a successful response's remote artifacts fails, the locally raised error (wrapped as an AppError when it is not one) also carries the command registry's dispatch verdict in details.dispatched, because the daemon already ran the request; the request, the response and the download are unchanged." + "digest": "sha256:75226219f3d2475b59b297593346879c5211f56530a45494ff696b435e002bce", + "rationale": "The client names its request as DaemonWireRequest (packages/contracts/src/daemon-wire-request.ts, a narrowing of the listed kernel DaemonRequest) and its response as the kernel DaemonResponse, instead of the daemon package's DaemonRequest/DaemonResponse aliases, so the daemon package is no longer a client import. The declaration's serialized fields, method names and framing are unchanged; only the compile-time type names in its signature moved, so a peer on protocol 2 parses exactly what it did. The function now takes the client host as a parameter and resolves a relative local path against its working directory instead of the process's; the client binds the same directory, so nothing a peer parses moves. #4302 (client-side only): when materializing a successful response's remote artifacts fails, the locally raised error (wrapped as an AppError when it is not one) also carries the command registry's dispatch verdict in details.dispatched, because the daemon already ran the request; the request, the response and the download are unchanged. #4511 (client-side only): it receives the client host and state directory together and forwards the state directory to artifact materialization; the request, the response and the download are unchanged." }, { "declaration": "packages/daemon-client/src/daemon-client-progress.ts#createInvalidDaemonResponseError", @@ -563,6 +571,16 @@ "declaration": "packages/daemon/src/server/upload-http.ts#handleUploadPreflight", "digest": "sha256:8f9915c23fbf86903bee4db02e1b45aa835bc4d234c8e9a0fe4da5e67da8163e", "rationale": "#4434 passes the origin validated by the HTTP ingress owner, or the explicitly configured publicOrigin, into the existing ticket producer. Protocol-2 clients receive the same uploadId and upload URL/header object, use the returned absolute URL, and keep the existing byte, range, authentication and finalize contracts. Forwarding headers no longer select authority under the documented operator migration; no wire field becomes required or changes interpretation." + }, + { + "declaration": "packages/kernel/src/contracts.ts#DaemonArtifact", + "digest": "sha256:77dee23e48dc77febb33efadc85377cbbcd137389ae7b33e93ba31670565fdf6", + "rationale": "#4511 adds the optional scriptPublicationId string and scriptRevision number, which a daemon sets only on a session-script artifact for a remote recording. A released client ignores the unknown fields and downloads the artifact like any other file named by its field; every existing field keeps its meaning." + }, + { + "declaration": "packages/remote/src/artifact-download.ts#RemoteArtifactDownload", + "digest": "sha256:e87a625bdff05fa55f6321ff09a35496f59edd228a1d7420268d54fcc2982868", + "rationale": "#4511 adds the optional client-local privateFile field: the download creates a new 0600 file exclusively, never through a symbolic link, and stops once it crosses maxBytes. It is never sent, and every existing call site omits it, so the GET /artifacts/:id framing is unchanged." } ] } diff --git a/test/wire-compat/surface.ts b/test/wire-compat/surface.ts index 61d685487b..2a1dc9ed83 100644 --- a/test/wire-compat/surface.ts +++ b/test/wire-compat/surface.ts @@ -142,6 +142,12 @@ export const WIRE_SURFACE: readonly WireSurfaceGroup[] = [ // URL builder below is its counterpart. ...from(REQUEST_DIAGNOSTICS_HTTP, 'resolveRequestDiagnosticsHttpRoute'), ...from(REMOTE_REQUEST_DIAGNOSTICS, 'buildRemoteRequestDiagnosticsUrl'), + ...from( + 'packages/daemon-contracts/src/daemon-resolution.ts', + 'DAEMON_CAPABILITIES', + 'DaemonCapability', + 'readDaemonCapabilities', + ), // Consumer side of /health: the client reads this payload and refuses a // mismatched peer from it, so a narrowed reader defeats the very check // ADR 0006 built. `readRemoteDaemonHealth` is where the comparison lives. @@ -439,8 +445,18 @@ export const WIRE_SURFACE: readonly WireSurfaceGroup[] = [ 'DownloadRemoteArtifactParams', 'downloadRemoteArtifact', 'materializeRemoteArtifacts', + 'downloadResponseArtifacts', 'resolveMaterializedArtifactPath', ), + // The client functions and types that write the remote open --save-script request field and + // read the session-script artifact fields (ADR 0016). + ...from( + 'packages/remote/src/session-script-destination.ts', + 'SessionScriptDelivery', + 'publishScriptVersion', + 'sendRemoteScriptOpen', + 'RemoteEndpoint', + ), ...from(ARTIFACT_DOWNLOAD, 'RemoteArtifactDownload', 'downloadRemoteArtifactFromUrl'), ], }, diff --git a/website/docs/docs/remote-proxy.md b/website/docs/docs/remote-proxy.md index 86d93fcf0f..2cfffa7015 100644 --- a/website/docs/docs/remote-proxy.md +++ b/website/docs/docs/remote-proxy.md @@ -104,12 +104,38 @@ while the artifact remains in inventory. Each download has a 15-minute maximum lifetime. When it reaches that limit, the daemon cancels it and cleans up after its pipeline stops. -Remote requests ignore `meta.cwd`. They refuse host tooling paths, `--launch-console`, and script -publication with reason `REMOTE_HOST_INPUT_DENIED`. They also refuse daemon host paths as `install` +Outside a macOS app lease, a fresh `open --save-script=` records the session to a file on +your machine. Each response that records an action returns a `session-script` artifact, and the +client replaces the file with it. `close` returns the final script. The client writes only to the +path that its own `open` named. If the file already exists, `open` fails unless you pass `--force`. +The daemon must report the `script-artifacts` capability in its `/health` response; through a +proxy, the upstream daemon's health response must report it. Otherwise `open --save-script` is +refused before the session starts. +A session that another process closes keeps the version from the last recorded action. + +A script version that is not delivered never fails the command that recorded it. The daemon may +fail to write it, or this machine may fail to download or save it, for example when it is larger +than 8 MiB. The command still succeeds, and the file may keep the previous version; the next recorded +action or `close` delivers the full recording again. If `close` cannot deliver the final script, +the session still closes and the file keeps the version from the last action. The daemon RPC +response carries a typed `scriptDeliveryFailure` and a warning. The CLI, SDK, and MCP results do +not carry `scriptDeliveryFailure` yet, and `close` shows no warning; see +[#4564](https://github.com/callstack/agent-device/issues/4564). + +Remote `session save-script`, `close --save-script`, `replay --save-script`, and `--save-script` in +batch steps are refused. A `batch` whose steps would close the recording is refused before any step +runs; run `close` on its own after the batch. + +Direct RPC callers send `saveScript: true` with a random `meta.scriptPublicationId` of 16 to 64 +letters, digits, or hyphens. Each script artifact carries that `scriptPublicationId` and a +`scriptRevision` that grows with each version. Download the artifacts by ID and keep the newest. + +Remote requests ignore `meta.cwd`. They refuse host tooling paths and `--launch-console` +with reason `REMOTE_HOST_INPUT_DENIED`. They also refuse daemon host paths as `install` and `reinstall` binaries, `push` payload files, and xctrace template files. `open` targets and launch URLs cannot use the `file:` scheme. Serve local web content over HTTP(S) instead. Upload binaries with the client, send `push` payloads as inline JSON, and name xctrace templates. Omit these inputs, or use a local daemon for -host tooling and script publication. Test suite artifacts also use a daemon-chosen output root. +host tooling. Test suite artifacts also use a daemon-chosen output root. ## Human takeover diff --git a/website/docs/docs/replay-e2e.md b/website/docs/docs/replay-e2e.md index 6c32202c5e..5a96d58ea4 100644 --- a/website/docs/docs/replay-e2e.md +++ b/website/docs/docs/replay-e2e.md @@ -71,7 +71,12 @@ agent-device open Settings --platform ios --session e2e --save-script ./workflow ``` - Missing parent directories are created. -- The script is written on the machine running the daemon, so `--save-script` is rejected when you use a remote daemon. +- With a local daemon, the script is written on the daemon host when the session closes. +- With a remote daemon, outside a macOS app lease, the path is on your machine. The file appears when `open` returns, and each later recorded action in the session replaces it with the recording so far. `close` writes the final script there. A session that another process closes keeps the version from the last action. +- A bare remote `open --save-script` writes `recording-.ad` in your working directory. +- If the file already exists, `open` fails unless you pass `--force`. Without `--force`, a file that appears before the first version arrives is kept too: `open` still succeeds, but the script is not saved there. The daemon RPC response carries a `scriptDeliveryFailure` and a warning; the CLI, SDK, and MCP results do not carry the failure yet ([#4564](https://github.com/callstack/agent-device/issues/4564)). With `--force`, the first version replaces it. After that, the session owns the file and replaces it on each update. +- Remote `session save-script`, `close --save-script`, `replay --save-script`, and `--save-script` in batch steps are refused. +- The remote daemon must report the `script-artifacts` capability in its `/health` response. Through a proxy, the upstream daemon's health response must report it. Otherwise `open --save-script` fails before the app opens. - For a bare file name that could be read as another argument, use `--save-script=workflow.ad` or a path-like value such as `./workflow.ad`. ## `.ad` line grammar