From ac3fe3e622f2526dfc5744032146d94ca6d4d826 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Tue, 17 Nov 2026 10:52:39 +0100 Subject: [PATCH 01/10] fix(remote): deliver batch recordings through one request receipt --- .../0016-active-session-script-publication.md | 5 +- packages/command-registry/src/batch-policy.ts | 7 +- packages/contracts/src/batch-step.ts | 12 + packages/contracts/src/facades/command.ts | 1 + .../daemon-client/src/daemon-client-rpc.ts | 38 +- .../request-script-delivery-ledger.test.ts | 373 ++++++++++++ ...sion-script-publication-capability.test.ts | 18 - packages/daemon/src/core/daemon-request.ts | 6 + .../core/request-script-delivery-ledger.ts | 187 ++++++ .../session-script-publication-capability.ts | 5 - packages/daemon/src/server/request-router.ts | 5 +- .../handlers/__tests__/session-batch.test.ts | 88 ++- .../handlers/__tests__/session.test.ts | 11 +- .../src/sessions/handlers/session-batch.ts | 23 +- .../daemon/src/sessions/handlers/session.ts | 9 +- packages/kernel/src/contracts.ts | 95 +++ .../daemon-artifacts-script-receipt.test.ts | 553 ++++++++++++++++++ packages/remote/src/daemon-artifacts.ts | 25 + .../remote/src/session-script-destination.ts | 203 ++++++- .../remote-script-publication.test.ts | 196 +++++++ 20 files changed, 1749 insertions(+), 111 deletions(-) create mode 100644 packages/daemon/src/core/__tests__/request-script-delivery-ledger.test.ts delete mode 100644 packages/daemon/src/core/__tests__/session-script-publication-capability.test.ts create mode 100644 packages/daemon/src/core/request-script-delivery-ledger.ts create mode 100644 packages/remote/src/__tests__/daemon-artifacts-script-receipt.test.ts diff --git a/docs/adr/0016-active-session-script-publication.md b/docs/adr/0016-active-session-script-publication.md index 9e448469ad..190b39b972 100644 --- a/docs/adr/0016-active-session-script-publication.md +++ b/docs/adr/0016-active-session-script-publication.md @@ -204,12 +204,13 @@ It adds no state name, command, or flag: - 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. + A batch whose steps record or close an armed remote recording is not refused. The daemon collects the versions and the close that the batch's steps wrote, and delivers them on the batch response as one `scriptDeliveryReceipt` (#4595). - 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). Every result that can carry a script version discloses a failed delivery: the SDK result, the CLI human output and `--json`, and the MCP tool result each carry `scriptDeliveryFailure` and the warning, so no caller reads a stale file as current. -Known limitation (#4595): a batch delivers no script versions from its steps, so closing an armed remote recording inside a batch stays refused. +A batch delivers through one receipt the daemon's request owner answers on the batch reply, successful or failed (#4595). The daemon collects each executed step's script effects as the batch runner reports them, because a step's own reply travels inside a result entry a client must not read. The receipt names the newest full-script version of the recording, the plan position of a step that closed it, and the typed failures; it is answered only for a request whose nested steps fed it, so every single-command reply keeps the shape it had before. A client validates the receipt against its own record and its submitted plan, downloads at most its one version, and treats a receipt it cannot fully account for as authorizing nothing. +Rejected: deriving delivery effects by interpreting the batch's step entries, partial results and failure position, because six review rounds kept finding answers that made a client deliver the wrong version, retire a recording that never closed, or drop a failure (#4582). 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. diff --git a/packages/command-registry/src/batch-policy.ts b/packages/command-registry/src/batch-policy.ts index 55bee20cb0..feaa02005b 100644 --- a/packages/command-registry/src/batch-policy.ts +++ b/packages/command-registry/src/batch-policy.ts @@ -1,6 +1,9 @@ import { deriveStructuredBatchCommandNames } from './derive.ts'; import { commandDescriptors } from './registry.ts'; import { AppError } from '@agent-device/kernel/errors'; +import { normalizeBatchCommandName } from '@agent-device/contracts/command'; + +export { normalizeBatchCommandName }; /** * The exact set of command names exposed through `batch`, as a narrow union. @@ -71,10 +74,6 @@ function isStructuredBatchCommandName(command: string): command is StructuredBat return structuredBatchCommandNames.has(command); } -export function normalizeBatchCommandName(command: unknown): string { - return typeof command === 'string' ? command.trim().toLowerCase() : ''; -} - /** * The command a raw step value will RUN as, or undefined. * diff --git a/packages/contracts/src/batch-step.ts b/packages/contracts/src/batch-step.ts index 11f617edba..8f08ed3df8 100644 --- a/packages/contracts/src/batch-step.ts +++ b/packages/contracts/src/batch-step.ts @@ -17,3 +17,15 @@ export type DaemonBatchStep = { flags?: Record; runtime?: SessionRuntimeHints; }; + +/** + * The command name a submitted step carries, as the daemon will RUN it. + * + * Declared here because both sides of the batch boundary read a step: the daemon normalizes it + * before its handler sees it, and a client that checks a daemon's answer against the plan it + * submitted resolves the same step to the same command. A caller that matched the raw value would + * read ` CLOSE ` as no command at all while the daemon runs `close`. + */ +export function normalizeBatchCommandName(command: unknown): string { + return typeof command === 'string' ? command.trim().toLowerCase() : ''; +} diff --git a/packages/contracts/src/facades/command.ts b/packages/contracts/src/facades/command.ts index f7b42f682c..1207aebaf6 100644 --- a/packages/contracts/src/facades/command.ts +++ b/packages/contracts/src/facades/command.ts @@ -7,6 +7,7 @@ export { readBatchStepInputObject, readBatchStepRecord, } from '../batch-contract.ts'; +export { normalizeBatchCommandName } from '../batch-step.ts'; export type { DaemonBatchStep } from '../batch-step.ts'; export type { CliFlags, DaemonExcludedCliFlag } from '../cli-flags.ts'; export type { CommandExecutionOptions, InternalRequestOptions } from '../request-envelope.ts'; diff --git a/packages/daemon-client/src/daemon-client-rpc.ts b/packages/daemon-client/src/daemon-client-rpc.ts index 859a0a61a8..7d6ac2077f 100644 --- a/packages/daemon-client/src/daemon-client-rpc.ts +++ b/packages/daemon-client/src/daemon-client-rpc.ts @@ -10,7 +10,11 @@ import { } from '@agent-device/kernel/errors'; import { sanitizeErrorCause } from '@agent-device/kernel/redaction'; import { createRequestId } from '@agent-device/host-kit/diagnostics'; -import { materializeRemoteArtifacts } from '@agent-device/remote/daemon-artifacts'; +import { + downloadRemoteArtifact, + materializeRemoteArtifacts, + settleScriptDeliveryReceiptOfFailure, +} from '@agent-device/remote/daemon-artifacts'; import { localizeRemoteDaemonError } from '@agent-device/remote/remote-request-diagnostics'; import type { DaemonInfo } from './daemon-client-metadata.ts'; import { DAEMON_REQUEST_MAX_BYTES } from '@agent-device/contracts/daemon-http'; @@ -102,7 +106,37 @@ async function rejectDaemonHttpRpcError( stateDir, requestId, }); - reject(appErrorFromDaemonError(localized, requestId)); + reject( + appErrorFromDaemonError( + await settleFailedDeliveryReceipt(info, req, stateDir, localized), + requestId, + ), + ); +} + +/** + * Settles the batch delivery receipt (#4595) a failed remote answer names: a batch that stopped + * mid-plan still delivers what its completed steps wrote, and the disclosure rides the error the + * caller receives. Never throws, so a receipt that cannot settle still leaves the original failure. + */ +async function settleFailedDeliveryReceipt( + info: DaemonInfo, + req: DaemonWireRequest, + stateDir: string, + error: DaemonError, +): Promise { + if (!info.baseUrl) return error; + try { + return await settleScriptDeliveryReceiptOfFailure( + { baseUrl: info.baseUrl, token: info.token }, + req, + error, + stateDir, + downloadRemoteArtifact, + ); + } catch { + return error; + } } function toDaemonHttpRpcError(error: { diff --git a/packages/daemon/src/core/__tests__/request-script-delivery-ledger.test.ts b/packages/daemon/src/core/__tests__/request-script-delivery-ledger.test.ts new file mode 100644 index 0000000000..fcda0eafea --- /dev/null +++ b/packages/daemon/src/core/__tests__/request-script-delivery-ledger.test.ts @@ -0,0 +1,373 @@ +import { expect, test } from 'vitest'; +import type { DaemonArtifact, DaemonResponse } from '@agent-device/kernel/contracts'; +import { readScriptDeliveryReceipt } from '@agent-device/kernel/contracts'; +import type { DaemonRequest } from '../daemon-request.ts'; +import { + collectBatchStepDelivery, + type ScriptDeliveryLedger, + reportScriptDelivery, +} from '../request-script-delivery-ledger.ts'; + +/** + * The batch delivery receipt's daemon owner (ADR 0016, #4595). Each case answers step replies the + * way a batch runner reports them and asserts what the ONE outer receipt says, because a client may + * act only on that receipt. + */ + +const ID = '3f2a1b0c-0000-4000-8000-000000000001'; +const OTHER = '9a8b7c6d-0000-4000-8000-000000000002'; + +/** The batch request an outermost client sends: its ledger is the one the request owner creates. */ +function batchRequest(steps: number): DaemonRequest { + return { + token: 't', + session: 'journey', + command: 'batch', + positionals: [], + flags: { batchSteps: Array.from({ length: steps }, () => ({ command: 'wait' })) }, + }; +} + +/** The ledger the request owner created for `outer`, as the batch runner sees it. */ +function ledgerOf(outer: DaemonRequest): ScriptDeliveryLedger { + const scriptDelivery = outer.internal?.scriptDelivery; + if (!scriptDelivery) throw new Error('the request owner answers its handlers on a ledger'); + return scriptDelivery; +} + +function script(artifactId: string, revision: number, publicationId = ID): DaemonArtifact { + return { + field: 'savedScript', + artifactType: 'session-script', + artifactId, + scriptPublicationId: publicationId, + scriptRevision: revision, + }; +} + +function failure(publicationId = ID) { + return { + reason: 'script_delivery_failed' as const, + publicationId, + message: 'The action succeeded, but the daemon could not write the remote recording.', + hint: 'The next recorded action delivers the full recording again.', + }; +} + +test('a request whose steps delivered nothing answers no receipt', async () => { + const response = await reportScriptDelivery(batchRequest(1), async () => ({ + ok: true, + data: { results: [] }, + })); + + expect(response).toEqual({ ok: true, data: { results: [] } }); +}); + +test('the versions, the failure and the close the steps answered become one receipt on the outer reply', async () => { + let scriptDelivery: ScriptDeliveryLedger | undefined; + const response = await reportScriptDelivery(batchRequest(2), async (outer) => { + scriptDelivery = ledgerOf(outer); + collectBatchStepDelivery( + outer, + { number: 1, command: 'wait' }, + { + ok: true, + data: { artifacts: [script('v2', 2)] }, + }, + ); + collectBatchStepDelivery( + outer, + { number: 2, command: ' CLOSE ' }, + { + ok: true, + data: { + scriptPublicationId: ID, + artifacts: [script('v3', 3)], + scriptDeliveryFailure: failure(), + }, + }, + ); + return { ok: true, data: { results: [{ ok: true }, { ok: true }] } }; + }); + + expect(response).toMatchObject({ + ok: true, + data: { + scriptDeliveryReceipt: { + publicationId: ID, + version: { artifactId: 'v3', scriptRevision: 3 }, + close: { step: 2 }, + failures: [{ message: failure().message }], + }, + }, + }); + expect(scriptDelivery?.nested).toBe(true); +}); + +test('a failed batch answers the receipt in the error details and keeps the original error', async () => { + const original: DaemonResponse = { + ok: false, + error: { code: 'COMMAND_FAILED', message: 'step 2 failed' }, + }; + + const response = await reportScriptDelivery(batchRequest(2), async (outer) => { + collectBatchStepDelivery( + outer, + { number: 1, command: 'wait' }, + { + ok: true, + data: { artifacts: [script('v2', 2)] }, + }, + ); + collectBatchStepDelivery(outer, { number: 2, command: 'tap' }, original); + return original; + }); + + if (!response.ok) { + expect(response.error.code).toBe('COMMAND_FAILED'); + expect(response.error.message).toBe('step 2 failed'); + expect(response.error.details).toMatchObject({ + scriptDeliveryReceipt: { publicationId: ID, version: { artifactId: 'v2' } }, + }); + } else { + throw new Error('a failed batch keeps failing'); + } +}); + +test('a step that failed contributes no version, no close, and no failure', async () => { + let scriptDelivery: ScriptDeliveryLedger | undefined; + await reportScriptDelivery(batchRequest(1), async (outer) => { + scriptDelivery = ledgerOf(outer); + collectBatchStepDelivery( + outer, + { number: 1, command: 'close' }, + { + ok: false, + error: { code: 'COMMAND_FAILED', message: 'close failed' }, + }, + ); + return { ok: false, error: { code: 'COMMAND_FAILED', message: 'close failed' } }; + }); + + expect(scriptDelivery?.versions.size).toBe(0); + expect(scriptDelivery?.close).toBeUndefined(); + expect(scriptDelivery?.failures.size).toBe(0); +}); + +test('a close names the recording only for the plan position that ran close', async () => { + let scriptDelivery: ScriptDeliveryLedger | undefined; + + await reportScriptDelivery(batchRequest(2), async (outer) => { + scriptDelivery = ledgerOf(outer); + // Only a `close` step's reply means a close; another command naming the ID means a version. + collectBatchStepDelivery( + outer, + { number: 1, command: 'save-script' }, + { + ok: true, + data: { scriptPublicationId: ID }, + }, + ); + return { ok: true, data: {} }; + }); + + expect(scriptDelivery?.close).toBeUndefined(); +}); + +test('a close whose final write failed names both the close and the failure', async () => { + const response = await reportScriptDelivery(batchRequest(1), async (outer) => { + collectBatchStepDelivery( + outer, + { number: 1, command: 'close' }, + { + ok: true, + data: { scriptPublicationId: ID, scriptDeliveryFailure: failure() }, + }, + ); + return { ok: true, data: {} }; + }); + + expect(response).toMatchObject({ + ok: true, + data: { + scriptDeliveryReceipt: { + publicationId: ID, + close: { step: 1 }, + failures: [{ message: failure().message }], + }, + }, + }); +}); + +test('a non-object artifact entry never hides a valid version', async () => { + const response = await reportScriptDelivery(batchRequest(1), async (outer) => { + collectBatchStepDelivery( + outer, + { number: 1, command: 'wait' }, + { + ok: true, + data: { + artifacts: [ + null, + 42, + 'script', + undefined, + script('v7', 7), + ] as unknown as DaemonArtifact[], + }, + }, + ); + return { ok: true, data: {} }; + }); + + expect(response).toMatchObject({ + ok: true, + data: { scriptDeliveryReceipt: { version: { artifactId: 'v7', scriptRevision: 7 } } }, + }); +}); + +test('a higher entry of another type never masks this recording’s version', async () => { + const response = await reportScriptDelivery(batchRequest(1), async (outer) => { + collectBatchStepDelivery( + outer, + { number: 1, command: 'wait' }, + { + ok: true, + data: { + artifacts: [{ ...script('shot', 99), artifactType: 'screenshot' }, script('mine', 4)], + }, + }, + ); + return { ok: true, data: {} }; + }); + + expect(response).toMatchObject({ + ok: true, + data: { scriptDeliveryReceipt: { publicationId: ID, version: { artifactId: 'mine' } } }, + }); +}); + +test('a version of another recording answers no receipt rather than guessing one', async () => { + // One reply delivers one recording. Facts for two of them are an anomaly, so nothing is delivered. + const response = await reportScriptDelivery(batchRequest(1), async (outer) => { + collectBatchStepDelivery( + outer, + { number: 1, command: 'wait' }, + { + ok: true, + data: { artifacts: [script('other', 99, OTHER), script('mine', 4)] }, + }, + ); + return { ok: true, data: {} }; + }); + + expect(response).toEqual({ ok: true, data: {} }); +}); + +test('a version on the batch reply itself is delivered even when no step carries one', async () => { + const response = await reportScriptDelivery(batchRequest(1), async (outer) => { + collectBatchStepDelivery(outer, { number: 1, command: 'wait' }, { ok: true, data: {} }); + return { ok: true, data: { artifacts: [script('outer', 3)] } }; + }); + + expect(response).toMatchObject({ + ok: true, + data: { scriptDeliveryReceipt: { version: { artifactId: 'outer', scriptRevision: 3 } } }, + }); +}); + +test('the newest version wins among the entries many steps carried', async () => { + const response = await reportScriptDelivery(batchRequest(3), async (outer) => { + for (const [number, revision] of [ + [1, 5], + [2, 6], + [3, 4], + ] as const) { + collectBatchStepDelivery( + outer, + { number, command: 'wait' }, + { + ok: true, + data: { artifacts: [script(`v${revision}`, revision)] }, + }, + ); + } + return { ok: true, data: {} }; + }); + + expect(response).toMatchObject({ + ok: true, + data: { scriptDeliveryReceipt: { version: { artifactId: 'v6', scriptRevision: 6 } } }, + }); +}); + +test('facts collected for two recordings answer no receipt rather than guessing one', async () => { + const response = await reportScriptDelivery(batchRequest(2), async (outer) => { + collectBatchStepDelivery( + outer, + { number: 1, command: 'wait' }, + { + ok: true, + data: { artifacts: [script('mine', 2)] }, + }, + ); + collectBatchStepDelivery( + outer, + { number: 2, command: 'wait' }, + { + ok: true, + data: { artifacts: [script('theirs', 2, OTHER)] }, + }, + ); + return { ok: true, data: {} }; + }); + + expect(response).toEqual({ ok: true, data: {} }); +}); + +test('a nested request keeps its delegating ledger and answers no receipt of its own', async () => { + const scriptDelivery: ScriptDeliveryLedger = { + nested: false, + versions: new Map(), + failures: new Map(), + }; + const nestedRequest: DaemonRequest = { + ...batchRequest(1), + command: 'wait', + internal: { scriptDelivery }, + }; + + const nested = await reportScriptDelivery(nestedRequest, async (inner) => { + collectBatchStepDelivery( + inner, + { number: 1, command: 'wait' }, + { + ok: true, + data: { artifacts: [script('v2', 2)] }, + }, + ); + return { ok: true, data: {} }; + }); + + expect(nested).toEqual({ ok: true, data: {} }); + expect(scriptDelivery.versions.get(ID)?.scriptRevision).toBe(2); +}); + +test('all failures in a maximum-sized batch leave its close receipt readable', async () => { + const response = await reportScriptDelivery(batchRequest(1000), async (outer) => { + for (let number = 1; number <= 1000; number++) { + collectBatchStepDelivery( + outer, + { number, command: number === 1000 ? 'close' : 'wait' }, + { + ok: true, + data: { scriptPublicationId: ID, scriptDeliveryFailure: failure() }, + }, + ); + } + return { ok: true, data: {} }; + }); + const receipt = readScriptDeliveryReceipt(response); + expect(receipt?.failures).toHaveLength(1000); + expect(receipt?.close).toEqual({ step: 1000 }); +}); 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 deleted file mode 100644 index fde4b328f3..0000000000 --- a/packages/daemon/src/core/__tests__/session-script-publication-capability.test.ts +++ /dev/null @@ -1,18 +0,0 @@ -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/daemon-request.ts b/packages/daemon/src/core/daemon-request.ts index c541c252fa..0b197e31d4 100644 --- a/packages/daemon/src/core/daemon-request.ts +++ b/packages/daemon/src/core/daemon-request.ts @@ -7,6 +7,7 @@ import type { WebSessionIdentity } from '@agent-device/kernel/device'; import type { DaemonWireRequest } from '@agent-device/contracts/command'; import type { RequestDispatchLedger } from './request-dispatch-ledger.ts'; import type { EndedLeaseLedger } from './request-ended-leases.ts'; +import type { ScriptDeliveryLedger } from './request-script-delivery-ledger.ts'; /** * The daemon's request vocabulary: the wire shape from `@agent-device/contracts/command` @@ -65,6 +66,11 @@ type DaemonRequestInternal = ReplayDispatchOptions & { * it reports it, once, on its reply. */ endedLeases?: EndedLeaseLedger; + /** + * The script-delivery effects the outermost request and its nested requests produced. Only the + * request that created it reports them, once, as one receipt on its reply (#4595). + */ + scriptDelivery?: ScriptDeliveryLedger; /** Authority minted only by the test suite for its own attempt-session cleanup. */ cleanupIntent?: 'suite-owned-test-session'; }; diff --git a/packages/daemon/src/core/request-script-delivery-ledger.ts b/packages/daemon/src/core/request-script-delivery-ledger.ts new file mode 100644 index 0000000000..8630bc9141 --- /dev/null +++ b/packages/daemon/src/core/request-script-delivery-ledger.ts @@ -0,0 +1,187 @@ +import type { + DaemonArtifact, + DaemonResponse, + ScriptDeliveryFailure, + ScriptDeliveryReceipt, +} from '@agent-device/kernel/contracts'; +import { readScriptDeliveryFailure } from '@agent-device/kernel/contracts'; +import { normalizeBatchCommandName } from '@agent-device/contracts/command'; +import type { DaemonRequest } from './daemon-request.ts'; +/** + * The script-delivery ledger of one daemon request (ADR 0016, #4595). + * + * A composite request (a `batch`) runs its steps as nested requests. A step that records into an + * armed remote recording writes a script version, and a step that runs `close` ends the recording. + * Each of those names its result on the reply of the NESTED request. A client must not read those + * step results to work out what it should have received: #4582 tried exactly that and every way a + * batch answer could mislead a client survived six review rounds. + * + * So the request that owns the outer reply collects the delivery facts its executed steps answered — + * as its own runner reports them, because only the runner knows which plan position ran what — and + * answers ONE receipt on that reply, successful or failed. A request that collected nothing answers + * no receipt, so every reply a single command gets keeps the shape it had before. + * + * Effects stay independent in the ledger: no version is merged into another, no failure is dropped + * because a version arrived, and a close is named only for a step that really ran one. + */ +export type ScriptDeliveryLedger = { + /** Whether a nested request fed this ledger: only a composite request answers a receipt. */ + nested: boolean; + /** Newest version per publication, among the versions the executed steps wrote. */ + versions: Map; + /** Every typed delivery failure a step disclosed, kept per publication. */ + failures: Map; + /** The step that closed the recording, and the 1-based plan position that reached it. */ + close?: { publicationId: string; step: number }; +}; + +/** + * Runs `handle` for an outermost request on a script ledger of its own and reports the delivery its + * nested requests fed into it on its reply: in `data` on success, in `error.details` on failure, + * because a failed batch still delivers what its completed steps wrote. A nested request already + * carries its delegating request's ledger and reports nothing. + * + * A request whose ledger no nested request fed answers NO receipt: only a composite collects nested + * effects, so every single-command reply keeps the shape it had before this receipt existed. + */ +export async function reportScriptDelivery( + req: DaemonRequest, + handle: (req: DaemonRequest) => Promise, +): Promise { + if (req.internal?.scriptDelivery) return await handle(req); + const scriptDelivery: ScriptDeliveryLedger = { + nested: false, + versions: new Map(), + failures: new Map(), + }; + const response = await handle({ ...req, internal: { ...req.internal, scriptDelivery } }); + if (response.ok) { + for (const version of sessionScriptVersions(response.data)) + collectVersion(scriptDelivery, version); + const failure = readScriptDeliveryFailure(response.data); + if (failure) collectFailure(scriptDelivery, failure); + } + if (!scriptDelivery.nested) return response; + const publicationId = onlyPublication(scriptDelivery); + if (publicationId === undefined) return response; + const receipt = receiptOf(scriptDelivery, publicationId); + if (!receipt) return response; + if (response.ok) { + return { ok: true, data: { ...response.data, scriptDeliveryReceipt: receipt } }; + } + return { + ok: false, + error: { + ...response.error, + details: { ...response.error.details, scriptDeliveryReceipt: receipt }, + }, + }; +} + +/** + * Records the script-delivery facts one executed batch step answered. + * + * Each fact is one the daemon's own handler answered for that step: the `session-script` version a + * recorded action wrote and registered for download, the typed failure of a version the daemon could + * not write, and the publication a `close` named on its reply. A failed step wrote no version and + * closed nothing, so it records nothing; its error reaches the batch error unchanged. + */ +export function collectBatchStepDelivery( + req: DaemonRequest, + step: Readonly<{ number: number; command: string }>, + response: DaemonResponse, +): void { + const scriptDelivery = req.internal?.scriptDelivery; + if (!scriptDelivery) return; + scriptDelivery.nested = true; + if (!response.ok) return; + const data = response.data ?? {}; + for (const version of sessionScriptVersions(data)) collectVersion(scriptDelivery, version); + const failure = readScriptDeliveryFailure(data); + if (failure) collectFailure(scriptDelivery, failure); + // A close names the recording it ended on its own reply, whether or not it wrote the final script. + // Only the runner knows this plan position ran `close`, and only this reply says it happened. + const closed = + typeof data.scriptPublicationId === 'string' ? data.scriptPublicationId : undefined; + if (closed && normalizeBatchCommandName(step.command) === 'close') { + scriptDelivery.close = { publicationId: closed, step: step.number }; + } +} + +/** + * Adds one version, keeping the newest per publication. A version is already a registered + * downloadable artifact of the recording, so a receipt names exactly what its writer registered. + */ +function collectVersion( + scriptDelivery: ScriptDeliveryLedger, + version: DaemonArtifact | undefined, +): void { + const publicationId = version?.scriptPublicationId; + const revision = version?.scriptRevision; + if (!publicationId || typeof revision !== 'number') return; + const known = scriptDelivery.versions.get(publicationId)?.scriptRevision; + if (typeof known === 'number' && known >= revision) return; + scriptDelivery.versions.set(publicationId, version); +} + +function collectFailure( + scriptDelivery: ScriptDeliveryLedger, + failure: ScriptDeliveryFailure, +): void { + const failures = scriptDelivery.failures.get(failure.publicationId); + if (failures) failures.push(failure); + else scriptDelivery.failures.set(failure.publicationId, [failure]); +} + +/** + * The one recording a receipt can name. A request that collected facts for two recordings — or for + * none — answers no receipt rather than guessing one, because one reply delivers one recording. + */ +function onlyPublication(scriptDelivery: ScriptDeliveryLedger): string | undefined { + const publications = new Set([ + ...scriptDelivery.versions.keys(), + ...scriptDelivery.failures.keys(), + ]); + if (scriptDelivery.close) publications.add(scriptDelivery.close.publicationId); + return publications.size === 1 ? [...publications][0] : undefined; +} + +function receiptOf( + scriptDelivery: ScriptDeliveryLedger, + publicationId: string, +): ScriptDeliveryReceipt | undefined { + const version = scriptDelivery.versions.get(publicationId); + const failures = scriptDelivery.failures.get(publicationId) ?? []; + const close = + scriptDelivery.close?.publicationId === publicationId ? scriptDelivery.close : undefined; + if (!version && failures.length === 0 && !close) return undefined; + return { + publicationId, + ...(version ? { version } : {}), + ...(close ? { close: { step: close.step } } : {}), + ...(failures.length > 0 ? { failures } : {}), + }; +} + +/** + * The `session-script` versions a reply names. Selection is linear in the entries one reply names; + * an entry that is not a full-script version — a non-object entry, another artifact type, a missing + * revision — is skipped rather than competing with one that is. + */ +function sessionScriptVersions(data: Record | undefined): DaemonArtifact[] { + const artifacts = Array.isArray(data?.artifacts) ? data.artifacts : []; + return artifacts.filter(isSessionScriptVersion); +} + +function isSessionScriptVersion( + artifact: unknown, +): artifact is DaemonArtifact & { scriptRevision: number; scriptPublicationId: string } { + if (!artifact || typeof artifact !== 'object') return false; + const candidate = artifact as Partial; + return ( + candidate.field === 'savedScript' && + candidate.artifactType === 'session-script' && + typeof candidate.scriptPublicationId === 'string' && + typeof candidate.scriptRevision === 'number' + ); +} diff --git a/packages/daemon/src/core/session-script-publication-capability.ts b/packages/daemon/src/core/session-script-publication-capability.ts index b6418f80dc..f8b4db3599 100644 --- a/packages/daemon/src/core/session-script-publication-capability.ts +++ b/packages/daemon/src/core/session-script-publication-capability.ts @@ -176,11 +176,6 @@ 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, diff --git a/packages/daemon/src/server/request-router.ts b/packages/daemon/src/server/request-router.ts index 899038a363..c3d8902cd2 100644 --- a/packages/daemon/src/server/request-router.ts +++ b/packages/daemon/src/server/request-router.ts @@ -108,6 +108,7 @@ import { } from '../execution/request-dispatch-disclosure.ts'; import { recordNestedRequests } from '../core/request-dispatch-ledger.ts'; import { handDownEndedLeases, reportEndedLeases } from '../core/request-ended-leases.ts'; +import { reportScriptDelivery } from '../core/request-script-delivery-ledger.ts'; import type { AndroidObservationAdapter } from '@agent-device/contracts/android-observation'; import type { CreateDaemonCommandSurface } from '@agent-device/contracts/daemon-command-surface'; import type { PlatformResourceCleanup } from '../core/platform-resource-cleanup.ts'; @@ -205,7 +206,9 @@ export function createRequestHandler(deps: RequestRouterDeps): DaemonInvokeFn { meta: { ...req.meta, requestId: resolveRequestTrackingId(req.meta?.requestId) }, }; } - return await reportEndedLeases(req, handleRequestOnLedger); + return await reportEndedLeases(req, (scoped) => + reportScriptDelivery(scoped, handleRequestOnLedger), + ); } async function handleRequestOnLedger(req: DaemonRequest): Promise { diff --git a/packages/daemon/src/sessions/handlers/__tests__/session-batch.test.ts b/packages/daemon/src/sessions/handlers/__tests__/session-batch.test.ts index 952e1bf521..03d1708ea1 100644 --- a/packages/daemon/src/sessions/handlers/__tests__/session-batch.test.ts +++ b/packages/daemon/src/sessions/handlers/__tests__/session-batch.test.ts @@ -1,5 +1,7 @@ import { expect, test, vi } from 'vitest'; +import type { DaemonResponse } from '@agent-device/kernel/contracts'; import type { DaemonRequest } from '../../../core/daemon-request.ts'; +import type { ScriptDeliveryLedger } from '../../../core/request-script-delivery-ledger.ts'; import { runBatchCommands } from '../session-batch.ts'; function batch(...commands: string[]): DaemonRequest { @@ -12,47 +14,83 @@ function batch(...commands: string[]): DaemonRequest { }; } -const refused = { - ok: false, - error: expect.objectContaining({ - code: 'INVALID_ARGS', - details: expect.objectContaining({ reason: 'remote_script_batch_close_unsupported' }), - }), -}; +function ledger(): ScriptDeliveryLedger { + return { nested: false, versions: new Map(), failures: new Map() }; +} + +function batchWithLedger(scriptDelivery: ScriptDeliveryLedger, ...commands: string[]) { + const req = batch(...commands); + return { req: { ...req, internal: { scriptDelivery } }, scriptDelivery }; +} 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 }) => { +])('a batch with $name runs its steps (#4595 removed the refusal)', 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(); + await expect(runBatchCommands(batch('wait', close), 'journey', invoke)).resolves.toMatchObject({ + ok: true, + }); + expect(invoke).toHaveBeenCalledTimes(2); }); -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: {} })); +test('each executed step runs on the outer request ledger and feeds it', async () => { + const { req, scriptDelivery } = batchWithLedger(ledger(), 'wait', 'CLOSE'); + const id = '3f2a1b0c-0000-4000-8000-000000000001'; + const invoke = vi.fn(async (step: DaemonRequest) => { + expect(step.internal?.scriptDelivery).toBe(scriptDelivery); + return step.command === 'wait' + ? { + ok: true as const, + data: { + artifacts: [ + { + field: 'savedScript', + artifactType: 'session-script', + artifactId: 'v2', + scriptPublicationId: id, + scriptRevision: 2, + }, + ], + }, + } + : { ok: true as const, data: { scriptPublicationId: id } }; + }); - await runBatchCommands(batch(...commands), 'journey', invoke, remote); + await runBatchCommands(req, 'journey', invoke); - expect(invoke).toHaveBeenCalledTimes(commands.length); + expect(scriptDelivery.nested).toBe(true); + expect(scriptDelivery.versions.get(id)?.scriptRevision).toBe(2); + expect(scriptDelivery.close).toEqual({ publicationId: id, step: 2 }); }); -test('malformed steps fail batch validation before the close check', async () => { +test('a failed step records nothing and the batch keeps its error', async () => { + const { req, scriptDelivery } = batchWithLedger(ledger(), 'wait', 'close'); + const failure = { + ok: false as const, + error: { code: 'COMMAND_FAILED' as const, message: 'tap failed' }, + }; + const invoke = vi.fn(async (step: DaemonRequest): Promise => + step.command === 'wait' ? { ok: true, data: {} } : failure, + ); + + await expect(runBatchCommands(req, 'journey', invoke)).resolves.toMatchObject({ + ok: false, + error: { message: expect.stringContaining('tap failed') }, + }); + expect(scriptDelivery.versions.size).toBe(0); + expect(scriptDelivery.failures.size).toBe(0); + expect(scriptDelivery.close).toBeUndefined(); +}); + +test('malformed steps fail batch validation before any step runs', 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({ + await expect(runBatchCommands(req, 'journey', invoke)).resolves.toMatchObject({ ok: false, error: { code: 'INVALID_ARGS' }, }); + expect(invoke).not.toHaveBeenCalled(); }); diff --git a/packages/daemon/src/sessions/handlers/__tests__/session.test.ts b/packages/daemon/src/sessions/handlers/__tests__/session.test.ts index 9b90574dfb..ec96fd855d 100644 --- a/packages/daemon/src/sessions/handlers/__tests__/session.test.ts +++ b/packages/daemon/src/sessions/handlers/__tests__/session.test.ts @@ -46,7 +46,9 @@ test('the session router maps boot, shutdown and appstate straight to their hand } }); -test('the session router refuses a batch that would close an armed remote recording', async () => { +test('the session router routes a batch over an armed remote recording to the batch runner', async () => { + // #4595 removed the route's close refusal: the route runs the plan and the outer request answers + // one delivery receipt for what its steps delivered. const sessionStore = makeSessionStore('agent-device-batch-route-'); sessionStore.publish( 'journey', @@ -71,9 +73,6 @@ test('the session router refuses a batch that would close an armed remote record invoke, }); - expect(response).toMatchObject({ - ok: false, - error: { details: { reason: 'remote_script_batch_close_unsupported' } }, - }); - expect(invoke).not.toHaveBeenCalled(); + expect(response).toMatchObject({ ok: true }); + expect(invoke).toHaveBeenCalledTimes(2); }); diff --git a/packages/daemon/src/sessions/handlers/session-batch.ts b/packages/daemon/src/sessions/handlers/session-batch.ts index e964d3a500..7ad8490c82 100644 --- a/packages/daemon/src/sessions/handlers/session-batch.ts +++ b/packages/daemon/src/sessions/handlers/session-batch.ts @@ -1,37 +1,28 @@ import type { DaemonResponse } from '@agent-device/kernel/contracts'; -import { AppError } from '@agent-device/kernel/errors'; import { runBatch } from '@agent-device/command-registry/batch'; +import { collectBatchStepDelivery } from '../../core/request-script-delivery-ledger.ts'; import type { DaemonInvokeFn, DaemonRequest } from '../../core/daemon-request.ts'; 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({ + const response = await invoke({ ...step, internal: { ...step.internal, webSession: req.internal?.webSession, ...(req.internal?.publicNetworkOnly ? { publicNetworkOnly: true } : {}), + ...(req.internal?.scriptDelivery ? { scriptDelivery: req.internal.scriptDelivery } : {}), executionPlan: { remainingSteps: context.remainingSteps }, }, }); + // ADR 0016 (#4595): the outer request owns the batch's script-delivery receipt, so each executed + // step hands its delivery effects to that ledger instead of the client reading step results. + collectBatchStepDelivery(req, { number: context.stepNumber, command: step.command }, response); + return response; }); } diff --git a/packages/daemon/src/sessions/handlers/session.ts b/packages/daemon/src/sessions/handlers/session.ts index 2a9290787a..e3dbd80e07 100644 --- a/packages/daemon/src/sessions/handlers/session.ts +++ b/packages/daemon/src/sessions/handlers/session.ts @@ -7,7 +7,6 @@ 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'; @@ -203,13 +202,7 @@ const SESSION_COMMAND_HANDLER_IMPLS = { open: handleSessionOpenCommandGroup, replay: handleReplayCommand, test: handleReplayTestCommand, - batch: async ({ req, sessionName, sessionStore, invoke }) => - await runBatchCommands( - req, - sessionName, - invoke, - isArmedRemoteRecording(sessionStore.get(sessionName)), - ), + batch: async ({ req, sessionName, invoke }) => await runBatchCommands(req, sessionName, invoke), close: handleSessionCloseCommandGroup, } satisfies Record; diff --git a/packages/kernel/src/contracts.ts b/packages/kernel/src/contracts.ts index c352cdeaa4..afc537722f 100644 --- a/packages/kernel/src/contracts.ts +++ b/packages/kernel/src/contracts.ts @@ -245,6 +245,101 @@ export function readScriptDeliveryFailure( return { reason, publicationId, message, hint, ...(cause === undefined ? {} : { cause }) }; } +/** + * What one daemon request delivered for a remote script recording (ADR 0016, #4595). A composite + * request (a `batch`) collects the script effects of its nested steps and answers ONE of these on + * its own reply, in `data` on success and in `error.details` on failure, so a client never + * reconstructs delivery from step results. + * + * `version` is the newest applicable full-script version of the recording — the client downloads at + * most it, once. `close` names the 1-based step of the submitted plan that ended the recording; a + * client retires its record only for a close its own plan carries. `failures` are the typed + * delivery failures the request owns, each paired with a warning of the same text. + */ +export type ScriptDeliveryReceipt = { + publicationId: string; + version?: DaemonArtifact; + close?: { step: number }; + failures?: ScriptDeliveryFailure[]; +}; + +/** How many `failures` one receipt may name; a receipt naming more authorizes nothing. */ +const SCRIPT_DELIVERY_RECEIPT_MAX_FAILURES = 1000; + +/** + * Reads the delivery receipt a response names (ADR 0016, #4595). A receipt the field contract does + * not describe in FULL authorizes nothing and answers `undefined`: a half-shaped `version`, `close` + * or `failures` entry is not repaired, because a client that acts on part of a receipt it cannot + * account for is exactly how a batch delivered the wrong version before. + */ +export function readScriptDeliveryReceipt( + response: DaemonResponse, +): ScriptDeliveryReceipt | undefined { + const body: Record | undefined = response.ok + ? response.data + : response.error.details; + const receipt = body?.scriptDeliveryReceipt; + if (!receipt || typeof receipt !== 'object' || Array.isArray(receipt)) return undefined; + const { publicationId, version, close, failures } = receipt as Partial; + if (typeof publicationId !== 'string' || publicationId.trim() !== publicationId) return undefined; + if (publicationId.length === 0) return undefined; + if (version !== undefined && !isScriptVersionArtifact(version, publicationId)) return undefined; + if ( + close !== undefined && + (close === null || + typeof close !== 'object' || + Array.isArray(close) || + typeof close.step !== 'number' || + !Number.isSafeInteger(close.step) || + close.step < 1) + ) { + return undefined; + } + if (failures !== undefined && !readsAsReceiptFailures(failures, publicationId)) return undefined; + return { + publicationId, + ...(version === undefined ? {} : { version: version as DaemonArtifact }), + ...(close === undefined ? {} : { close: { step: close.step } }), + ...(failures === undefined + ? {} + : { failures: (failures as readonly ScriptDeliveryFailure[]).slice() }), + }; +} + +/** + * Whether every named entry is a delivery failure of the recording the receipt names. The bound is + * checked before any entry is read, so an oversized answer costs nothing beyond its own size. + */ +function readsAsReceiptFailures( + failures: unknown, + publicationId: string, +): failures is readonly ScriptDeliveryFailure[] { + if (!Array.isArray(failures) || failures.length > SCRIPT_DELIVERY_RECEIPT_MAX_FAILURES) { + return false; + } + return failures.every((failure) => { + const read = readScriptDeliveryFailure({ scriptDeliveryFailure: failure }); + return read !== undefined && read.publicationId === publicationId; + }); +} + +/** Whether `version` is a `session-script` version of the recording the receipt names. */ +function isScriptVersionArtifact( + version: unknown, + publicationId: string, +): version is DaemonArtifact { + if (!version || typeof version !== 'object' || Array.isArray(version)) return false; + const artifact = version as Partial; + return ( + artifact.field === 'savedScript' && + artifact.artifactType === 'session-script' && + typeof artifact.artifactId === 'string' && + artifact.scriptPublicationId === publicationId && + Number.isSafeInteger(artifact.scriptRevision) && + (artifact.scriptRevision as number) > 0 + ); +} + export type ResponseCost = { wallClockMs: number; // Number of real iOS-runner round-trips made while serving the request (the diff --git a/packages/remote/src/__tests__/daemon-artifacts-script-receipt.test.ts b/packages/remote/src/__tests__/daemon-artifacts-script-receipt.test.ts new file mode 100644 index 0000000000..2aa9138a37 --- /dev/null +++ b/packages/remote/src/__tests__/daemon-artifacts-script-receipt.test.ts @@ -0,0 +1,553 @@ +import fs from 'node:fs'; +import http from 'node:http'; +import path from 'node:path'; +import { afterEach, expect, test } from 'vitest'; +import type { DaemonBatchStep, DaemonWireRequest } from '@agent-device/contracts/command'; +import type { DaemonArtifact, DaemonResponse } from '@agent-device/kernel/contracts'; +import { + closeLoopbackServer, + createTestHostEnvironment, + listenOnLoopback, + mkdtempForTestSync, +} from '@agent-device/test-kit'; +import { materializeRemoteArtifacts } from '../daemon-artifacts.ts'; +import { sendRemoteScriptOpen } from '../session-script-destination.ts'; + +/** + * The client half of the batch delivery receipt (ADR 0016, #4595). Every case answers a batch the + * way a daemon does and materializes the answer the way the real client does, so a receipt that + * would make this client deliver the wrong version, retire a recording that never closed, or drop a + * failure is caught here rather than in a step-result interpreter. + */ + +const servers: http.Server[] = []; + +afterEach(async () => { + await Promise.all(servers.splice(0).map((server) => closeLoopbackServer(server))); +}); + +async function artifactServer( + artifacts: Record, +): Promise { + const server = http.createServer((req, res) => { + const id = decodeURIComponent(req.url?.replace(/^\/+artifacts\//, '') ?? ''); + const served = artifacts[id]; + if (served === undefined) { + res.writeHead(404).end(); + return; + } + if (typeof served !== 'string') { + res.writeHead(503).end('unavailable'); + return; + } + res.writeHead(200, { 'content-length': Buffer.byteLength(served) }); + res.end(served); + }); + servers.push(server); + return `http://127.0.0.1:${await listenOnLoopback(server)}`; +} + +function world() { + const root = fs.realpathSync(mkdtempForTestSync('script-receipt-')); + const stateDir = path.join(root, 'state'); + return { root, stateDir, destination: path.join(root, 'caller', 'journey.ad') }; +} + +function batchRequest( + steps: DaemonBatchStep[], + meta: DaemonWireRequest['meta'] = {}, +): DaemonWireRequest { + return { + token: 't', + session: 'journey', + command: 'batch', + positionals: [], + flags: { batchSteps: steps }, + meta, + }; +} + +/** A `session-script` artifact of the recording this client opened. */ +function script(artifactId: string, revision: number, publicationId: string): DaemonArtifact { + return { + field: 'savedScript', + artifactType: 'session-script', + artifactId, + scriptPublicationId: publicationId, + scriptRevision: revision, + }; +} + +/** The one receipt field, as the daemon answers it on a batch response. */ +function receipt(version: unknown, extra: Record = {}) { + return { scriptDeliveryReceipt: { publicationId: version, ...extra } }; +} + +function records(stateDir: string): string[] { + const directory = path.join(stateDir, 'remote-connections', 'session-scripts'); + return fs.existsSync(directory) + ? fs.readdirSync(directory).filter((name) => name.endsWith('.json')) + : []; +} + +/** Opens a recording so the client holds a record and its first version, and reports the ID. */ +async function opened(baseUrl: string, stateDir: string, destination: string): Promise { + const openRequest: DaemonWireRequest = { + ...batchRequest([], { clientArtifactPaths: { savedScript: destination } }), + command: 'open', + flags: { saveScript: true }, + }; + let id = ''; + const response = await sendRemoteScriptOpen( + { baseUrl, token: 't', capabilities: ['script-artifacts'] }, + openRequest, + stateDir, + async (req) => { + id = req.meta?.scriptPublicationId as string; + return { + ok: true, + data: { scriptPublicationId: id, artifacts: [script('open-v1', 1, id)] }, + }; + }, + ); + await materializeRemoteArtifacts( + { baseUrl, token: 't' }, + openRequest, + response as Extract, + createTestHostEnvironment(), + stateDir, + ); + expect(fs.readFileSync(destination, 'utf8')).toBe('open Demo\n'); + return id; +} + +function answer( + baseUrl: string, + stateDir: string, + req: DaemonWireRequest, + data: Record, +): Promise { + return materializeRemoteArtifacts( + { baseUrl, token: 't' }, + req, + { ok: true, data }, + createTestHostEnvironment(), + stateDir, + ); +} + +test('a batch receipt delivers the newest full-script version to the caller file', async () => { + const { stateDir, destination } = world(); + const baseUrl = await artifactServer({ + 'open-v1': 'open Demo\n', + 'step-v2': 'open Demo\nwait "label=\\"Apps\\""\n', + }); + const id = await opened(baseUrl, stateDir, destination); + expect(records(stateDir)).toHaveLength(1); + + await answer( + baseUrl, + stateDir, + batchRequest([{ command: 'wait', input: {} }]), + receipt(id, { version: script('step-v2', 2, id) }), + ); + + expect(fs.readFileSync(destination, 'utf8')).toBe('open Demo\nwait "label=\\"Apps\\""\n'); +}); + +test('a batch receipt whose close its plan does not carry retires nothing', async () => { + const { stateDir, destination } = world(); + const baseUrl = await artifactServer({ + 'open-v1': 'open Demo\n', + 'step-v2': 'open Demo\nwait\n', + }); + const id = await opened(baseUrl, stateDir, destination); + + await answer( + baseUrl, + stateDir, + batchRequest([{ command: 'wait', input: {} }]), + receipt(id, { + version: script('step-v2', 2, id), + close: { step: 2 }, + }), + ); + + expect(records(stateDir)).toHaveLength(1); + expect(fs.existsSync(destination)).toBe(true); +}); + +test('a batch receipt whose close names a step beyond the plan retires nothing', async () => { + const { stateDir, destination } = world(); + const baseUrl = await artifactServer({ + 'open-v1': 'open Demo\n', + 'close-v2': 'open Demo\nclose\n', + }); + const id = await opened(baseUrl, stateDir, destination); + + await answer( + baseUrl, + stateDir, + batchRequest([ + { command: 'wait', input: {} }, + { command: 'tap', input: {} }, + ]), + receipt(id, { version: script('close-v2', 2, id), close: { step: 3 } }), + ); + + expect(records(stateDir)).toHaveLength(1); +}); + +test('a batch receipt whose close its plan carries delivers the final script and retires', async () => { + const { stateDir, destination } = world(); + const baseUrl = await artifactServer({ + 'open-v1': 'open Demo\n', + 'close-v2': 'open Demo\nwait\nclose\n', + }); + const id = await opened(baseUrl, stateDir, destination); + + await answer( + baseUrl, + stateDir, + batchRequest([ + { command: 'wait', input: {} }, + { command: 'CLOSE', input: {} }, + ]), + receipt(id, { version: script('close-v2', 2, id), close: { step: 2 } }), + ); + + expect(fs.readFileSync(destination, 'utf8')).toBe('open Demo\nwait\nclose\n'); + expect(records(stateDir)).toEqual([]); +}); + +test.each([ + { name: 'padded with whitespace', publicationId: ' padded-publication-id-0000000000 ' }, + { name: 'not a string', publicationId: 42 }, + { name: 'absent', publicationId: undefined }, +])( + 'a receipt whose publication ID is $name delivers and retires nothing', + async ({ publicationId }) => { + const { stateDir, destination } = world(); + const baseUrl = await artifactServer({ 'open-v1': 'open Demo\n', v2: 'open Demo\nwait\n' }); + const id = await opened(baseUrl, stateDir, destination); + + const response = await answer( + baseUrl, + stateDir, + batchRequest([ + { command: 'wait', input: {} }, + { command: 'close', input: {} }, + ]), + { + scriptDeliveryReceipt: { + publicationId, + version: script('v2', 2, id), + close: { step: 2 }, + }, + }, + ); + + expect(response.ok).toBe(true); + expect(records(stateDir)).toHaveLength(1); + expect(fs.readFileSync(destination, 'utf8')).toBe('open Demo\n'); + }, +); + +test('a receipt names at most one version and no other script artifact is downloaded', async () => { + const { stateDir, destination } = world(); + const downloads: string[] = []; + const server = http.createServer((req, res) => { + const id = decodeURIComponent(req.url?.replace(/^\/+artifacts\//, '') ?? ''); + downloads.push(id); + res.writeHead(200).end(id === 'v3' ? 'open Demo\nwait\nclose\n' : 'open Demo\n'); + }); + servers.push(server); + const baseUrl = `http://127.0.0.1:${await listenOnLoopback(server)}`; + const id = await opened(baseUrl, stateDir, destination); + downloads.length = 0; + + await answer( + baseUrl, + stateDir, + batchRequest([ + { command: 'wait', input: {} }, + { command: 'close', input: {} }, + ]), + { + scriptDeliveryReceipt: { + publicationId: id, + version: script('v3', 3, id), + close: { step: 2 }, + }, + artifacts: [ + script('v1', 1, id), + script('v2', 2, id), + script('v3', 3, id), + script('v4', 4, id), + ], + }, + ); + + expect(downloads).toEqual(['v3']); + expect(fs.readFileSync(destination, 'utf8')).toBe('open Demo\nwait\nclose\n'); + expect(records(stateDir)).toEqual([]); +}); + +test('a newer receipt version of the wrong artifact type authorizes nothing', async () => { + // A half-shaped receipt is not repaired: a client that acted on its close while dropping its + // version is how a batch retired a recording while its caller file stayed stale. + const { stateDir, destination } = world(); + const baseUrl = await artifactServer({ 'open-v1': 'open Demo\n', v2: 'not a script\n' }); + const id = await opened(baseUrl, stateDir, destination); + + await answer( + baseUrl, + stateDir, + batchRequest([ + { command: 'wait', input: {} }, + { command: 'close', input: {} }, + ]), + { + scriptDeliveryReceipt: { + publicationId: id, + version: { ...script('v2', 2, id), artifactType: 'screenshot' }, + close: { step: 2 }, + }, + }, + ); + + expect(fs.readFileSync(destination, 'utf8')).toBe('open Demo\n'); + expect(records(stateDir)).toHaveLength(1); +}); + +test('a newer receipt version for another recording never masks this recording’s version', async () => { + const { stateDir, destination } = world(); + const baseUrl = await artifactServer({ + 'open-v1': 'open Demo\n', + 'other-v9': 'an open of another recording\n', + v2: 'open Demo\nwait\nclose\n', + }); + const id = await opened(baseUrl, stateDir, destination); + + await answer( + baseUrl, + stateDir, + batchRequest([ + { command: 'wait', input: {} }, + { command: 'close', input: {} }, + ]), + { + scriptDeliveryReceipt: { + publicationId: id, + version: script('v2', 2, id), + close: { step: 2 }, + }, + artifacts: [{ ...script('other-v9', 9, cryptoRandomUUIDish()), field: 'savedScript' }], + }, + ); + + expect(fs.readFileSync(destination, 'utf8')).toBe('open Demo\nwait\nclose\n'); + expect(records(stateDir)).toEqual([]); +}); + +/** A well-formed publication ID belonging to a recording this client never opened. */ +function cryptoRandomUUIDish(): string { + return '0f6f0a3d-1b2c-4d5e-8f90-abcdef012345'; +} + +test('a receipt close with a failed final version still retires the record and discloses the failure', async () => { + // The daemon could not write the FINAL version, so the receipt names the newest one it did write + // — already published here — and the typed failure of the final write. + const { stateDir, destination } = world(); + const baseUrl = await artifactServer({ 'open-v1': 'open Demo\n' }); + const id = await opened(baseUrl, stateDir, destination); + const failure = { + reason: 'script_delivery_failed' as const, + publicationId: id, + message: 'The session was closed, but the daemon could not write its final script.', + hint: 'The --save-script file keeps the version from the last recorded action.', + }; + + const response = await answer( + baseUrl, + stateDir, + batchRequest([ + { command: 'wait', input: {} }, + { command: 'close', input: {} }, + ]), + { + scriptDeliveryReceipt: { + publicationId: id, + version: script('open-v1', 1, id), + close: { step: 2 }, + failures: [failure], + }, + }, + ); + + expect(response.ok).toBe(true); + const data = (response as Extract).data ?? {}; + expect(data.scriptDeliveryFailure).toEqual(failure); + expect(data.warnings).toEqual([expect.stringContaining(failure.hint)]); + expect(fs.readFileSync(destination, 'utf8')).toBe('open Demo\n'); + expect(records(stateDir)).toEqual([]); +}); + +test('a receipt publication failure and this client’s download failure are both disclosed', async () => { + const { stateDir, destination } = world(); + const baseUrl = await artifactServer({ 'open-v1': 'open Demo\n', v2: { refused: true } }); + const id = await opened(baseUrl, stateDir, destination); + const daemonFailure = { + reason: 'script_delivery_failed' as const, + publicationId: id, + message: 'The action succeeded, but the daemon could not write the remote recording.', + hint: 'DAEMON-HINT', + }; + + const response = await answer(baseUrl, stateDir, batchRequest([{ command: 'wait', input: {} }]), { + scriptDeliveryReceipt: { + publicationId: id, + version: script('v2', 2, id), + failures: [daemonFailure], + }, + }); + + const data = (response as Extract).data ?? {}; + const clientFailure = data.scriptDeliveryFailure as { reason: string; cause?: string }; + expect(clientFailure.reason).toBe('script_delivery_failed'); + expect(clientFailure.cause).toBe('script_download_failed'); + expect(data.warnings).toEqual([ + expect.stringContaining('DAEMON-HINT'), + expect.stringContaining('remote script could not be saved'), + ]); +}); + +test('a receipt naming no version delivers nothing and keeps the caller file', async () => { + const { stateDir, destination } = world(); + const baseUrl = await artifactServer({ 'open-v1': 'open Demo\n' }); + const id = await opened(baseUrl, stateDir, destination); + + const response = await answer(baseUrl, stateDir, batchRequest([{ command: 'wait', input: {} }]), { + scriptDeliveryReceipt: { + publicationId: id, + failures: [ + { + reason: 'script_delivery_failed', + publicationId: id, + message: 'The action succeeded, but the daemon could not write the remote recording.', + hint: 'DAEMON-HINT', + }, + ], + }, + }); + + const data = (response as Extract).data ?? {}; + expect(data.savedScript).toBeUndefined(); + expect(data.warnings).toEqual([expect.stringContaining('DAEMON-HINT')]); + expect(fs.readFileSync(destination, 'utf8')).toBe('open Demo\n'); + expect(records(stateDir)).toHaveLength(1); +}); + +test('a receipt naming more failures than the field contract allows authorizes nothing', async () => { + const { stateDir, destination } = world(); + const baseUrl = await artifactServer({ + 'open-v1': 'open Demo\n', + v2: 'open Demo\nwait\nclose\n', + }); + const id = await opened(baseUrl, stateDir, destination); + const failure = { + reason: 'script_delivery_failed', + publicationId: id, + message: 'The daemon could not write the remote recording.', + hint: 'DAEMON-HINT', + }; + + await answer( + baseUrl, + stateDir, + batchRequest([ + { command: 'wait', input: {} }, + { command: 'close', input: {} }, + ]), + { + scriptDeliveryReceipt: { + publicationId: id, + version: script('v2', 2, id), + close: { step: 2 }, + failures: Array.from({ length: 4_000 }, () => failure), + }, + }, + ); + + expect(fs.readFileSync(destination, 'utf8')).toBe('open Demo\n'); + expect(records(stateDir)).toHaveLength(1); +}); + +test('a receipt version entry that is not an object delivers nothing and keeps the batch outcome', async () => { + const { stateDir, destination } = world(); + const baseUrl = await artifactServer({ 'open-v1': 'open Demo\n' }); + const id = await opened(baseUrl, stateDir, destination); + + const response = await answer( + baseUrl, + stateDir, + batchRequest([{ command: 'wait', input: {} }]), + receipt(id, { version: null }), + ); + + expect(response.ok).toBe(true); + expect(fs.readFileSync(destination, 'utf8')).toBe('open Demo\n'); + expect(records(stateDir)).toHaveLength(1); +}); + +test('a malformed close receipt cannot throw or fall back to batch script artifacts', async () => { + const { stateDir, destination } = world(); + const baseUrl = await artifactServer({ 'open-v1': 'open Demo\n', v2: 'untrusted\n' }); + const id = await opened(baseUrl, stateDir, destination); + const response = await answer( + baseUrl, + stateDir, + batchRequest([{ command: 'close', input: {} }]), + { + ...receipt(id, { version: script('v2', 2, id), close: null }), + artifacts: [script('v2', 2, id)], + }, + ); + expect(response.ok).toBe(true); + expect(fs.readFileSync(destination, 'utf8')).toBe('open Demo\n'); + expect(records(stateDir)).toHaveLength(1); +}); + +test.each([ + { name: 'an unreached close', details: { step: 1, command: 'wait' } }, + { name: 'missing failure position', details: {} }, + { name: 'a position past the plan', details: { step: 3, command: 'close' } }, + { name: 'a different command', details: { step: 1, command: 'close' } }, +])('a failed batch with $name authorizes no delivery', async ({ details }) => { + const { settleScriptDeliveryReceiptOfFailure } = await import('../daemon-artifacts.ts'); + const { downloadRemoteArtifact } = await import('../daemon-artifacts.ts'); + const { stateDir, destination } = world(); + const baseUrl = await artifactServer({ 'open-v1': 'open Demo\n', v2: 'untrusted\n' }); + const id = await opened(baseUrl, stateDir, destination); + const error = { + code: 'COMMAND_FAILED' as const, + message: 'original batch failure', + details: { + ...details, + ...receipt(id, { version: script('v2', 2, id), close: { step: 2 } }), + }, + }; + const settled = await settleScriptDeliveryReceiptOfFailure( + { baseUrl, token: 't' }, + batchRequest([ + { command: 'wait', input: {} }, + { command: 'close', input: {} }, + ]), + error, + stateDir, + downloadRemoteArtifact, + ); + expect(settled).toEqual(error); + expect(fs.readFileSync(destination, 'utf8')).toBe('open Demo\n'); + expect(records(stateDir)).toHaveLength(1); +}); diff --git a/packages/remote/src/daemon-artifacts.ts b/packages/remote/src/daemon-artifacts.ts index 9cd3662efe..42c034e2d0 100644 --- a/packages/remote/src/daemon-artifacts.ts +++ b/packages/remote/src/daemon-artifacts.ts @@ -1,6 +1,7 @@ import type { HostEnvironment } from '@agent-device/kernel/source-value'; import type { DaemonWireRequest } from '@agent-device/contracts/command'; import type { DaemonArtifact, DaemonResponse } from '@agent-device/kernel/contracts'; +import { readScriptDeliveryReceipt } from '@agent-device/kernel/contracts'; import fs from 'node:fs'; import path from 'node:path'; import { @@ -462,6 +463,27 @@ export async function sendRemoteScriptOpen( return await scripts.sendRemoteScriptOpen(...args); } +/** + * Settles the batch delivery receipt a FAILED remote response names (ADR 0016, #4595): a batch that + * stopped mid-plan still delivers what its completed steps wrote. The destination owner loads only + * for an error that carries a receipt. + */ +export async function settleScriptDeliveryReceiptOfFailure( + ...args: Parameters< + typeof import('./session-script-destination.ts').settleScriptDeliveryReceiptOfFailure + > +): Promise< + Awaited< + ReturnType< + typeof import('./session-script-destination.ts').settleScriptDeliveryReceiptOfFailure + > + > +> { + if (!readScriptDeliveryReceipt({ ok: false, error: args[2] })) return args[2]; + const scripts = await import('./session-script-destination.ts'); + return await scripts.settleScriptDeliveryReceiptOfFailure(...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 @@ -479,8 +501,11 @@ export async function materializeRemoteArtifacts( const artifacts = Array.isArray(response.data?.artifacts) ? response.data.artifacts : []; const download = (scripts?: SessionScriptDelivery) => downloadResponseArtifacts(endpoint, req, response, host, scripts); + // A receipt is a delivery instruction of its own: a batch answer may carry one while naming no + // publication and no script artifact of its own (#4595). if ( response.data?.scriptPublicationId === undefined && + readScriptDeliveryReceipt(response) === undefined && !artifacts.some(isSessionScriptArtifact) ) { return await download(); diff --git a/packages/remote/src/session-script-destination.ts b/packages/remote/src/session-script-destination.ts index 552e455650..1a395e285e 100644 --- a/packages/remote/src/session-script-destination.ts +++ b/packages/remote/src/session-script-destination.ts @@ -2,11 +2,15 @@ import crypto from 'node:crypto'; import fs from 'node:fs'; import path from 'node:path'; import type { DaemonWireRequest } from '@agent-device/contracts/command'; +import { normalizeBatchCommandName } from '@agent-device/contracts/command'; import type { DaemonArtifact, DaemonResponse, ScriptDeliveryFailure, + ScriptDeliveryReceipt, } from '@agent-device/kernel/contracts'; +import { readScriptDeliveryReceipt } from '@agent-device/kernel/contracts'; +import type { DaemonError } 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'; @@ -88,11 +92,94 @@ export type SessionScriptDelivery = Readonly<{ ): Promise; }>; +/** + * Settles the one delivery receipt a response names (ADR 0016, #4595): at most one version + * downloaded, and a record retired only for a close validated against the plan this client submitted. + * + * The receipt is validated against THIS client's record — exact publication ID, tenant, session and + * endpoint. A receipt naming a recording this client never opened under that scope authorizes nothing + * and says so in the diagnostic, because a response never establishes a destination. + */ +async function settleScriptReceipt( + context: Readonly<{ + endpoint: Required; + req: DaemonWireRequest; + stateDir: string; + download: typeof downloadRemoteArtifact; + }>, + receipt: ScriptDeliveryReceipt, + disclose: (failure: ScriptDeliveryFailure, error: unknown) => void, +): Promise { + const { endpoint, req, stateDir } = context; + const failures = [...(receipt.failures ?? [])]; + const file = recordPath(stateDir, endpoint.baseUrl, req, receipt.publicationId); + const record = readRecord(file); + if (!record) { + emitDiagnostic({ + level: 'warn', + phase: 'session_script_artifact_dropped', + data: { session: req.session, publicationId: receipt.publicationId }, + }); + return { failures }; + } + // A daemon failure is disclosed whether or not this client can save anything: the caller's file is + // stale either way. + for (const failure of failures) disclose(failure, undefined); + const published = receipt.version + ? await publishScriptVersion(context, receipt.version) + : undefined; + if (published && 'failure' in published) disclose(published.failure, published.error); + const closesOwnPlan = receipt.close !== undefined && closesSubmittedPlan(req, receipt.close.step); + const destination = published && 'published' in published ? published.published : undefined; + return { + ...(closesOwnPlan ? { retire: file } : {}), + ...(destination !== undefined && receipt.version?.artifactId !== undefined + ? { artifactId: receipt.version.artifactId, published: destination } + : {}), + failures, + }; +} + +type ReceiptSettlement = { + retire?: string; + published?: string; + artifactId?: string; + failures: ScriptDeliveryFailure[]; +}; + +/** Retires a record without letting a failure here replace the request's own outcome. */ +function retireQuietly(req: DaemonWireRequest, file: string): Promise { + return withRecordLock(file, async () => removeRecord(file)).catch((retireError: unknown) => + emitDiagnostic({ + level: 'warn', + phase: 'session_script_retire_failed', + data: { session: req.session, error: String(retireError) }, + }), + ); +} + +/** + * Whether the batch plan this client submitted carries a `close` at 1-based position `step`. A + * position past the plan, one whose command is not `close`, or a request that submitted no plan + * authorizes no retirement. + */ +function closesSubmittedPlan(req: DaemonWireRequest, step: number): boolean { + if (req.command !== 'batch') return false; + const steps = req.flags?.batchSteps; + if (!Array.isArray(steps) || step > steps.length) return false; + return normalizeBatchCommandName(steps[step - 1]?.command) === 'close'; +} + /** * 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. + * + * A response that names a delivery receipt (#4595) delivers THROUGH that receipt: at most its one + * version is downloaded, and the receipt's failures and close are what the client acts on. The + * session-script artifacts such a response still lists are then dropped rather than downloaded, so + * one response never moves two versions. */ export function sessionScriptDelivery( endpoint: Required, @@ -101,27 +188,29 @@ export function sessionScriptDelivery( stateDir: string, download: typeof downloadRemoteArtifact, ): SessionScriptDelivery { + const context = { endpoint, req, stateDir, download }; + const receipt = req.command === 'batch' ? readScriptDeliveryReceipt(response) : undefined; 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)); - }; + // The receipt's own version is downloaded before the artifact loop runs, so the loop learns the + // published destination from here rather than downloading anything a second time. + let settled: ReceiptSettlement | undefined; const delivery: SessionScriptDelivery = { publish: async (artifact, data, kept) => { delete data[artifact.field]; - const outcome = await publishScriptVersion({ endpoint, req, stateDir, download }, artifact); + // The receipt is the one delivery instruction of this response; a step's or the batch's own + // artifact entry is the same version it already names, so it is never downloaded a second time. + if (req.command === 'batch') { + if (settled?.published && artifact.artifactId === settled.artifactId) { + data.savedScript = settled.published; + kept.push({ ...artifact, localPath: settled.published }); + } + return; + } + const outcome = await publishScriptVersion(context, artifact); if ('failure' in outcome) { // A delivery failure never changes the outcome of the action that recorded the version. - const { failure, error } = outcome; - 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(error) }, - }); + discloseDeliveryFailure(data, req, outcome.failure, outcome.error); return; } const { published } = outcome; @@ -130,25 +219,91 @@ export function sessionScriptDelivery( 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) }, - }), - ); + const data = response.data ?? {}; + settled = receipt + ? await settleScriptReceipt(context, receipt, (failure, error) => + discloseDeliveryFailure(data, req, failure, error), + ) + : undefined; try { return await run(delivery); } finally { - await retireQuietly(); + // A record that cannot be retired stays inert, so the request keeps its own outcome. + if (settled?.retire) await retireQuietly(req, settled.retire); + else if (closedId !== undefined) + await retireQuietly(req, recordPath(stateDir, endpoint.baseUrl, req, closedId)); } }, }; return delivery; } +/** + * Adds one delivery failure and its warning to a response body's disclosure fields. One field + * reports the latest failure; all earlier failures remain in the receipt and their paired warnings — + * the text of every failure still reaches the caller. + */ +function discloseDeliveryFailure( + data: Record, + req: DaemonWireRequest, + failure: ScriptDeliveryFailure, + error: unknown, +): void { + data.scriptDeliveryFailure = failure; + data.warnings = [...readResponseWarnings(data), `${failure.message} ${failure.hint}`]; + emitDiagnostic({ + level: 'warn', + phase: 'session_script_delivery_failed', + data: { session: req.session, ...(error === undefined ? {} : { error: String(error) }) }, + }); +} + +/** + * Settles the one delivery receipt a FAILED response names (#4595), where no successful-artifact + * path runs: a batch that stopped mid-plan still delivers what its completed steps wrote. The + * disclosure rides the error the caller receives, and a close validated against the submitted plan + * still retires the record. + */ +export async function settleScriptDeliveryReceiptOfFailure( + endpoint: Required, + req: DaemonWireRequest, + error: DaemonError, + stateDir: string, + download: typeof downloadRemoteArtifact, +): Promise { + const receipt = readScriptDeliveryReceipt({ ok: false, error }); + if (!receipt || req.command !== 'batch') return error; + const steps = req.flags?.batchSteps; + const failedStep = error.details?.step; + const failedCommand = error.details?.command; + if ( + !Array.isArray(steps) || + typeof failedStep !== 'number' || + !Number.isSafeInteger(failedStep) || + failedStep < 1 || + failedStep > steps.length || + typeof failedCommand !== 'string' || + normalizeBatchCommandName(steps[failedStep - 1]?.command) !== failedCommand || + (receipt.close !== undefined && receipt.close.step >= failedStep) + ) + return error; + const data: Record = { ...(error.details ?? {}) }; + const settled = await settleScriptReceipt( + { endpoint, req, stateDir, download }, + receipt, + (failure, failureError) => discloseDeliveryFailure(data, req, failure, failureError), + ); + if (settled.retire) await retireQuietly(req, settled.retire); + const disclosure: Record = { + ...(data.scriptDeliveryFailure === undefined + ? {} + : { scriptDeliveryFailure: data.scriptDeliveryFailure }), + ...(data.warnings === undefined ? {} : { warnings: data.warnings }), + }; + if (Object.keys(disclosure).length === 0) return error; + return { ...error, details: { ...(error.details ?? {}), ...disclosure } }; +} + /** * Publishes one version and returns the destination, `undefined` when no record of this client * matches the artifact, or a typed delivery failure. A version no newer than the one published is diff --git a/test/integration/provider-scenarios/remote-script-publication.test.ts b/test/integration/provider-scenarios/remote-script-publication.test.ts index 22249484d7..8502f28c60 100644 --- a/test/integration/provider-scenarios/remote-script-publication.test.ts +++ b/test/integration/provider-scenarios/remote-script-publication.test.ts @@ -609,6 +609,202 @@ test('the SDK, the CLI and MCP each disclose a failed final script delivery', as } }); }, 30_000); +test('a remote batch delivers one final script and retires the closed recording', async () => { + await withProviderScenarioResource(createAndroidSettingsWorld, async (world) => { + const root = mkdtempForTestSync('batch-script-final-'); + const destination = path.join(root, 'journey.ad'); + const stateDir = path.join(root, 'client-state'); + const proxy = await createProviderScenarioProxy(world.daemon, { clientToken: 'batch-client' }); + const client = createAgentDeviceClient({ + daemonBaseUrl: proxy.baseUrl, + daemonAuthToken: 'batch-client', + session: 'batch-script', + stateDir, + }); + try { + await client.apps.open({ app: 'settings', saveScript: destination, ...world.selection }); + const before = proxy.forwarded.length; + const result = await client.batch.run({ + steps: [ + { command: 'wait', input: { selector: 'label="Apps"' } }, + { command: 'close', input: {} }, + ], + ...world.selection, + }); + assert.equal(result.executed, 2); + const final = fs.readFileSync(destination, 'utf8'); + assert.match(final, /^open /m); + assert.match(final, /^wait /m); + assert.match(final, /^close/m); + assert.equal( + proxy.forwarded.slice(before).filter((r) => r.route.startsWith('/artifacts/')).length, + 1, + ); + assert.deepEqual( + fs + .readdirSync(path.join(stateDir, 'remote-connections', 'session-scripts')) + .filter((f) => f.endsWith('.json')), + [], + ); + world.assertNoHostAdbCalls(); + } finally { + await proxy.close(); + } + }); +}, 20_000); + +test('a failed remote batch delivers completed steps while retaining its original failure', async () => { + await withProviderScenarioResource(createAndroidSettingsWorld, async (world) => { + const root = mkdtempForTestSync('batch-script-partial-'); + const destination = path.join(root, 'journey.ad'); + const stateDir = path.join(root, 'client-state'); + const proxy = await createProviderScenarioProxy(world.daemon, { clientToken: 'batch-client' }); + const client = createAgentDeviceClient({ + daemonBaseUrl: proxy.baseUrl, + daemonAuthToken: 'batch-client', + session: 'batch-partial', + stateDir, + }); + try { + await client.apps.open({ app: 'settings', saveScript: destination, ...world.selection }); + const before = proxy.forwarded.length; + await assert.rejects( + client.batch.run({ + steps: [ + { command: 'wait', input: { selector: 'label="Apps"' } }, + { command: 'press', input: { selector: 'id="missing-batch-target"' } }, + { command: 'close', input: {} }, + ], + ...world.selection, + }), + (error: unknown) => { + assert.ok(error instanceof Error); + assert.match(error.message, /Batch failed at step 2/); + assert.equal((error as { details?: { step?: number } }).details?.step, 2); + return true; + }, + ); + assert.match(fs.readFileSync(destination, 'utf8'), /^wait /m); + assert.doesNotMatch(fs.readFileSync(destination, 'utf8'), /^close/m); + assert.equal( + proxy.forwarded.slice(before).filter((r) => r.route.startsWith('/artifacts/')).length, + 1, + ); + assert.equal( + fs + .readdirSync(path.join(stateDir, 'remote-connections', 'session-scripts')) + .filter((f) => f.endsWith('.json')).length, + 1, + ); + await client.sessions.close(); + world.assertNoHostAdbCalls(); + } finally { + await proxy.close(); + } + }); +}, 20_000); + +test('batch delivery failures reach SDK results and CLI/MCP human output', async () => { + await withProviderScenarioResource(createAndroidSettingsWorld, async (world) => { + const root = mkdtempForTestSync('batch-script-surfaces-'); + const proxy = await createProviderScenarioProxy(world.daemon, { clientToken: 'batch-client' }); + let refused = false; + const gate = await createArtifactGate(proxy.baseUrl, () => refused); + const steps = [ + { command: 'wait', input: { selector: 'label="Apps"' } }, + { command: 'close', input: {} }, + ]; + const env = { + AGENT_DEVICE_DAEMON_BASE_URL: gate.baseUrl, + AGENT_DEVICE_DAEMON_AUTH_TOKEN: 'batch-client', + AGENT_DEVICE_DAEMON_TRANSPORT: 'http', + }; + try { + const sdk = createAgentDeviceClient({ + daemonBaseUrl: gate.baseUrl, + daemonAuthToken: 'batch-client', + session: 'batch-sdk', + stateDir: path.join(root, 'sdk'), + }); + const sdkFile = path.join(root, 'sdk.ad'); + await sdk.apps.open({ app: 'settings', saveScript: sdkFile, ...world.selection }); + refused = true; + const result = await sdk.batch.run({ steps, ...world.selection }); + refused = false; + assert.equal( + (result.scriptDeliveryFailure as { reason: string }).reason, + 'script_delivery_failed', + ); + assert.match(JSON.stringify(result.warnings), /remote script could not be saved/i); + assert.doesNotMatch(fs.readFileSync(sdkFile, 'utf8'), /^close/m); + + const cliState = path.join(root, 'cli'); + const cli = (argv: string[]) => + runCliCapture(argv, { + env: { ...env, AGENT_DEVICE_STATE_DIR: cliState }, + useRealDaemonClient: true, + }); + const opened = await cli([ + 'open', + 'settings', + '--save-script', + path.join(root, 'cli.ad'), + '--session', + 'batch-cli', + '--platform', + world.selection.platform, + '--serial', + world.selection.serial, + ]); + assert.equal(opened.code, null, opened.stderr); + refused = true; + const output = await cli([ + 'batch', + '--steps', + JSON.stringify(steps), + '--session', + 'batch-cli', + ]); + refused = false; + assert.equal(output.code, null, output.stderr); + assert.match(output.stdout + output.stderr, /Warning: .*remote script could not be saved/i); + + const restore = installIsolatedCliTestEnv({ + ...env, + AGENT_DEVICE_STATE_DIR: path.join(root, 'mcp'), + }); + try { + const executor = createCommandToolExecutor({ structuredContent: 'always' }); + const opened = await executor.execute('open', { + app: 'settings', + saveScript: path.join(root, 'mcp.ad'), + session: 'batch-mcp', + ...world.selection, + }); + assert.equal(opened.isError, false, JSON.stringify(opened)); + refused = true; + const output = await executor.execute('batch', { + steps, + session: 'batch-mcp', + ...world.selection, + }); + refused = false; + assert.equal(output.isError, false, JSON.stringify(output)); + assert.match( + output.content.map((p) => p.text ?? '').join('\n'), + /Warning: .*remote script could not be saved/i, + ); + } finally { + restore(); + } + world.assertNoHostAdbCalls(); + } finally { + await gate.close(); + await proxy.close(); + } + }); +}, 30_000); + /** * A gate in front of the daemon proxy that answers the artifact downloads of a refused moment with * 503, which is how these scenarios make one delivery fail. From 45425df4af25334f9c1bf3eba9c0f6c51a423a23 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Tue, 17 Nov 2026 10:54:22 +0100 Subject: [PATCH 02/10] docs(remote): describe batch recording delivery --- website/docs/docs/replay-e2e.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/docs/replay-e2e.md b/website/docs/docs/replay-e2e.md index d34e6eb31c..f885fd9279 100644 --- a/website/docs/docs/replay-e2e.md +++ b/website/docs/docs/replay-e2e.md @@ -76,7 +76,7 @@ agent-device open Settings --platform ios --session e2e --save-script ./workflow - 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, and the result carries a `scriptDeliveryFailure` and a warning. 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. -- Steps of a remote `batch` do not update the file. A batch that would close a remote recording is refused; run `close` on its own after the batch. Batch delivery is tracked in [#4595](https://github.com/callstack/agent-device/issues/4595). +- A remote `batch` updates your file once with the recording from its completed steps, including the final script when a step closes the session. If a step fails, the batch keeps that error and delivers the recording from earlier completed steps. A delivery failure adds `scriptDeliveryFailure` and a warning; your file keeps its previous version. - 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`. From ced1185fe3f95f18b9538a07a828762cd9101c03 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Tue, 17 Nov 2026 10:58:47 +0100 Subject: [PATCH 03/10] refactor(remote): name receipt authorization checks --- packages/kernel/src/contracts.ts | 18 +++++------- .../remote/src/session-script-destination.ts | 28 +++++++++---------- 2 files changed, 21 insertions(+), 25 deletions(-) diff --git a/packages/kernel/src/contracts.ts b/packages/kernel/src/contracts.ts index afc537722f..88ebed959b 100644 --- a/packages/kernel/src/contracts.ts +++ b/packages/kernel/src/contracts.ts @@ -284,17 +284,7 @@ export function readScriptDeliveryReceipt( if (typeof publicationId !== 'string' || publicationId.trim() !== publicationId) return undefined; if (publicationId.length === 0) return undefined; if (version !== undefined && !isScriptVersionArtifact(version, publicationId)) return undefined; - if ( - close !== undefined && - (close === null || - typeof close !== 'object' || - Array.isArray(close) || - typeof close.step !== 'number' || - !Number.isSafeInteger(close.step) || - close.step < 1) - ) { - return undefined; - } + if (close !== undefined && !isReceiptClose(close)) return undefined; if (failures !== undefined && !readsAsReceiptFailures(failures, publicationId)) return undefined; return { publicationId, @@ -306,6 +296,12 @@ export function readScriptDeliveryReceipt( }; } +function isReceiptClose(close: unknown): close is { step: number } { + if (!close || typeof close !== 'object' || Array.isArray(close)) return false; + const step = (close as { step?: unknown }).step; + return typeof step === 'number' && Number.isSafeInteger(step) && step >= 1; +} + /** * Whether every named entry is a delivery failure of the recording the receipt names. The bound is * checked before any entry is read, so an oversized answer costs nothing beyond its own size. diff --git a/packages/remote/src/session-script-destination.ts b/packages/remote/src/session-script-destination.ts index 1a395e285e..3e5d451436 100644 --- a/packages/remote/src/session-script-destination.ts +++ b/packages/remote/src/session-script-destination.ts @@ -273,20 +273,9 @@ export async function settleScriptDeliveryReceiptOfFailure( ): Promise { const receipt = readScriptDeliveryReceipt({ ok: false, error }); if (!receipt || req.command !== 'batch') return error; - const steps = req.flags?.batchSteps; - const failedStep = error.details?.step; - const failedCommand = error.details?.command; - if ( - !Array.isArray(steps) || - typeof failedStep !== 'number' || - !Number.isSafeInteger(failedStep) || - failedStep < 1 || - failedStep > steps.length || - typeof failedCommand !== 'string' || - normalizeBatchCommandName(steps[failedStep - 1]?.command) !== failedCommand || - (receipt.close !== undefined && receipt.close.step >= failedStep) - ) - return error; + const failedStep = validatedFailedBatchStep(req, error); + if (failedStep === undefined) return error; + if (receipt.close !== undefined && receipt.close.step >= failedStep) return error; const data: Record = { ...(error.details ?? {}) }; const settled = await settleScriptReceipt( { endpoint, req, stateDir, download }, @@ -304,6 +293,17 @@ export async function settleScriptDeliveryReceiptOfFailure( return { ...error, details: { ...(error.details ?? {}), ...disclosure } }; } +function validatedFailedBatchStep(req: DaemonWireRequest, error: DaemonError): number | undefined { + const steps = req.flags?.batchSteps; + const step = error.details?.step; + const command = error.details?.command; + if (!Array.isArray(steps) || typeof step !== 'number' || !Number.isSafeInteger(step)) { + return undefined; + } + if (step < 1 || step > steps.length || typeof command !== 'string') return undefined; + return normalizeBatchCommandName(steps[step - 1]?.command) === command ? step : undefined; +} + /** * Publishes one version and returns the destination, `undefined` when no record of this client * matches the artifact, or a typed delivery failure. A version no newer than the one published is From 94ae1b4bd1c6f73a3652fdcdecce6a14e99ed3cb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Tue, 17 Nov 2026 11:17:56 +0100 Subject: [PATCH 04/10] perf(remote): load receipt owners only for batch delivery --- packages/command-registry/src/batch-policy.ts | 2 +- packages/contracts/src/batch-step.ts | 12 ------------ packages/contracts/src/facades/command.ts | 2 +- packages/contracts/src/input-validation.ts | 5 +++++ .../src/core/request-script-delivery-ledger.ts | 2 +- packages/daemon/src/server/request-router.ts | 3 ++- packages/remote/src/daemon-artifacts.ts | 5 ++--- packages/remote/src/session-script-destination.ts | 2 +- 8 files changed, 13 insertions(+), 20 deletions(-) diff --git a/packages/command-registry/src/batch-policy.ts b/packages/command-registry/src/batch-policy.ts index feaa02005b..7117b73984 100644 --- a/packages/command-registry/src/batch-policy.ts +++ b/packages/command-registry/src/batch-policy.ts @@ -1,7 +1,7 @@ import { deriveStructuredBatchCommandNames } from './derive.ts'; import { commandDescriptors } from './registry.ts'; import { AppError } from '@agent-device/kernel/errors'; -import { normalizeBatchCommandName } from '@agent-device/contracts/command'; +import { normalizeBatchCommandName } from '@agent-device/contracts/input-validation'; export { normalizeBatchCommandName }; diff --git a/packages/contracts/src/batch-step.ts b/packages/contracts/src/batch-step.ts index 8f08ed3df8..11f617edba 100644 --- a/packages/contracts/src/batch-step.ts +++ b/packages/contracts/src/batch-step.ts @@ -17,15 +17,3 @@ export type DaemonBatchStep = { flags?: Record; runtime?: SessionRuntimeHints; }; - -/** - * The command name a submitted step carries, as the daemon will RUN it. - * - * Declared here because both sides of the batch boundary read a step: the daemon normalizes it - * before its handler sees it, and a client that checks a daemon's answer against the plan it - * submitted resolves the same step to the same command. A caller that matched the raw value would - * read ` CLOSE ` as no command at all while the daemon runs `close`. - */ -export function normalizeBatchCommandName(command: unknown): string { - return typeof command === 'string' ? command.trim().toLowerCase() : ''; -} diff --git a/packages/contracts/src/facades/command.ts b/packages/contracts/src/facades/command.ts index 1207aebaf6..d33d9d71ef 100644 --- a/packages/contracts/src/facades/command.ts +++ b/packages/contracts/src/facades/command.ts @@ -7,7 +7,6 @@ export { readBatchStepInputObject, readBatchStepRecord, } from '../batch-contract.ts'; -export { normalizeBatchCommandName } from '../batch-step.ts'; export type { DaemonBatchStep } from '../batch-step.ts'; export type { CliFlags, DaemonExcludedCliFlag } from '../cli-flags.ts'; export type { CommandExecutionOptions, InternalRequestOptions } from '../request-envelope.ts'; @@ -16,6 +15,7 @@ export type { DaemonWireRequest, DaemonWireRequestMeta } from '../daemon-wire-re export type { DispatchedCommand } from '../dispatched-command.ts'; export { ANDROID_SHELL_TEXT_UNSUPPORTED_REASON, + normalizeBatchCommandName, readOptionalInteger, readOptionalNumber, } from '../input-validation.ts'; diff --git a/packages/contracts/src/input-validation.ts b/packages/contracts/src/input-validation.ts index 6a67c5c7c6..f9dd8de456 100644 --- a/packages/contracts/src/input-validation.ts +++ b/packages/contracts/src/input-validation.ts @@ -46,3 +46,8 @@ export function readOptionalNumber( * because every producer and consumer of the reason already evaluates this module. */ export const ANDROID_SHELL_TEXT_UNSUPPORTED_REASON = 'android_shell_text_unsupported' as const; + +/** Resolves a batch step command with the same whitespace and case rules on both peers. */ +export function normalizeBatchCommandName(command: unknown): string { + return typeof command === 'string' ? command.trim().toLowerCase() : ''; +} diff --git a/packages/daemon/src/core/request-script-delivery-ledger.ts b/packages/daemon/src/core/request-script-delivery-ledger.ts index 8630bc9141..d404309b20 100644 --- a/packages/daemon/src/core/request-script-delivery-ledger.ts +++ b/packages/daemon/src/core/request-script-delivery-ledger.ts @@ -5,7 +5,7 @@ import type { ScriptDeliveryReceipt, } from '@agent-device/kernel/contracts'; import { readScriptDeliveryFailure } from '@agent-device/kernel/contracts'; -import { normalizeBatchCommandName } from '@agent-device/contracts/command'; +import { normalizeBatchCommandName } from '@agent-device/contracts/input-validation'; import type { DaemonRequest } from './daemon-request.ts'; /** * The script-delivery ledger of one daemon request (ADR 0016, #4595). diff --git a/packages/daemon/src/server/request-router.ts b/packages/daemon/src/server/request-router.ts index c3d8902cd2..36ef848926 100644 --- a/packages/daemon/src/server/request-router.ts +++ b/packages/daemon/src/server/request-router.ts @@ -108,7 +108,6 @@ import { } from '../execution/request-dispatch-disclosure.ts'; import { recordNestedRequests } from '../core/request-dispatch-ledger.ts'; import { handDownEndedLeases, reportEndedLeases } from '../core/request-ended-leases.ts'; -import { reportScriptDelivery } from '../core/request-script-delivery-ledger.ts'; import type { AndroidObservationAdapter } from '@agent-device/contracts/android-observation'; import type { CreateDaemonCommandSurface } from '@agent-device/contracts/daemon-command-surface'; import type { PlatformResourceCleanup } from '../core/platform-resource-cleanup.ts'; @@ -206,6 +205,8 @@ export function createRequestHandler(deps: RequestRouterDeps): DaemonInvokeFn { meta: { ...req.meta, requestId: resolveRequestTrackingId(req.meta?.requestId) }, }; } + if (req.command !== 'batch') return await reportEndedLeases(req, handleRequestOnLedger); + const { reportScriptDelivery } = await import('../core/request-script-delivery-ledger.ts'); return await reportEndedLeases(req, (scoped) => reportScriptDelivery(scoped, handleRequestOnLedger), ); diff --git a/packages/remote/src/daemon-artifacts.ts b/packages/remote/src/daemon-artifacts.ts index 42c034e2d0..634dc73a4a 100644 --- a/packages/remote/src/daemon-artifacts.ts +++ b/packages/remote/src/daemon-artifacts.ts @@ -1,7 +1,6 @@ import type { HostEnvironment } from '@agent-device/kernel/source-value'; import type { DaemonWireRequest } from '@agent-device/contracts/command'; import type { DaemonArtifact, DaemonResponse } from '@agent-device/kernel/contracts'; -import { readScriptDeliveryReceipt } from '@agent-device/kernel/contracts'; import fs from 'node:fs'; import path from 'node:path'; import { @@ -479,7 +478,7 @@ export async function settleScriptDeliveryReceiptOfFailure( > > > { - if (!readScriptDeliveryReceipt({ ok: false, error: args[2] })) return args[2]; + if (args[2].details?.scriptDeliveryReceipt === undefined) return args[2]; const scripts = await import('./session-script-destination.ts'); return await scripts.settleScriptDeliveryReceiptOfFailure(...args); } @@ -505,7 +504,7 @@ export async function materializeRemoteArtifacts( // publication and no script artifact of its own (#4595). if ( response.data?.scriptPublicationId === undefined && - readScriptDeliveryReceipt(response) === undefined && + response.data?.scriptDeliveryReceipt === undefined && !artifacts.some(isSessionScriptArtifact) ) { return await download(); diff --git a/packages/remote/src/session-script-destination.ts b/packages/remote/src/session-script-destination.ts index 3e5d451436..9b06a7b161 100644 --- a/packages/remote/src/session-script-destination.ts +++ b/packages/remote/src/session-script-destination.ts @@ -2,7 +2,7 @@ import crypto from 'node:crypto'; import fs from 'node:fs'; import path from 'node:path'; import type { DaemonWireRequest } from '@agent-device/contracts/command'; -import { normalizeBatchCommandName } from '@agent-device/contracts/command'; +import { normalizeBatchCommandName } from '@agent-device/contracts/input-validation'; import type { DaemonArtifact, DaemonResponse, From 5e1d76046543ce5ec2fbf51ecfb666575eefd807 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Tue, 17 Nov 2026 11:17:57 +0100 Subject: [PATCH 05/10] chore(gates): require receipt-aware RPC peers and retire the old export --- .../0016-active-session-script-publication.md | 1 + packages/contracts/src/daemon-http.ts | 2 +- ...mon-client-transport-health-compat.test.ts | 20 +++++++++++++++++++ scripts/layering/architecture-ownership.ts | 1 - test/wire-compat/ledger.json | 20 +++++-------------- 5 files changed, 27 insertions(+), 17 deletions(-) diff --git a/docs/adr/0016-active-session-script-publication.md b/docs/adr/0016-active-session-script-publication.md index 190b39b972..d5a0abc88c 100644 --- a/docs/adr/0016-active-session-script-publication.md +++ b/docs/adr/0016-active-session-script-publication.md @@ -210,6 +210,7 @@ It adds no state name, command, or flag: 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). Every result that can carry a script version discloses a failed delivery: the SDK result, the CLI human output and `--json`, and the MCP tool result each carry `scriptDeliveryFailure` and the warning, so no caller reads a stale file as current. A batch delivers through one receipt the daemon's request owner answers on the batch reply, successful or failed (#4595). The daemon collects each executed step's script effects as the batch runner reports them, because a step's own reply travels inside a result entry a client must not read. The receipt names the newest full-script version of the recording, the plan position of a step that closed it, and the typed failures; it is answered only for a request whose nested steps fed it, so every single-command reply keeps the shape it had before. A client validates the receipt against its own record and its submitted plan, downloads at most its one version, and treats a receipt it cannot fully account for as authorizing nothing. +This receipt requires RPC protocol 3: protocol-2 clients ignore it, so admitting a batch close for them could leave the caller's final script undelivered. The health compatibility gate rejects those skewed peers before dispatch (ADR 0006). Rejected: deriving delivery effects by interpreting the batch's step entries, partial results and failure position, because six review rounds kept finding answers that made a client deliver the wrong version, retire a recording that never closed, or drop a failure (#4582). 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. diff --git a/packages/contracts/src/daemon-http.ts b/packages/contracts/src/daemon-http.ts index 26f063eab7..f3ad9d10fe 100644 --- a/packages/contracts/src/daemon-http.ts +++ b/packages/contracts/src/daemon-http.ts @@ -123,7 +123,7 @@ export function buildDaemonHttpLeaseHeaders(leaseId: string | undefined): Record // Enforced, not just documented: `test/wire-compat/` digests the declarations // that cross this boundary and fails when one changes shape without a bump or // an acknowledged-compatible entry (#1432). -export const DAEMON_RPC_PROTOCOL_VERSION = 2; +export const DAEMON_RPC_PROTOCOL_VERSION = 3; /** * The largest serialized daemon request, in UTF-8 bytes, that any transport reads: the socket diff --git a/packages/daemon-client/src/__tests__/daemon-client-transport-health-compat.test.ts b/packages/daemon-client/src/__tests__/daemon-client-transport-health-compat.test.ts index 1b36abd540..38c81b78e4 100644 --- a/packages/daemon-client/src/__tests__/daemon-client-transport-health-compat.test.ts +++ b/packages/daemon-client/src/__tests__/daemon-client-transport-health-compat.test.ts @@ -102,3 +102,23 @@ test('a daemon health payload without an upstream link or host arch parses as be }, ); }); + +test.each(['daemon', 'upstream'] as const)( + 'released protocol-2 %s cannot silently omit batch receipt delivery', + async (link) => { + const payload = + link === 'upstream' ? proxyHealth(2) : { ...DAEMON_LINK, rpcProtocolVersion: 2 }; + await withHealthServer(payload, async (baseUrl) => { + await assert.rejects( + readRemoteDaemonHealth({ baseUrl, token: 't', pid: 0 }), + (error: unknown) => { + const failure = error as { code?: string; details?: Record }; + assert.equal(failure.code, 'COMMAND_FAILED'); + assert.equal(failure.details?.remoteRpcProtocolVersion, 2); + assert.equal(failure.details?.supportedRpcProtocolVersion, DAEMON_RPC_PROTOCOL_VERSION); + return true; + }, + ); + }); + }, +); diff --git a/scripts/layering/architecture-ownership.ts b/scripts/layering/architecture-ownership.ts index fdd4efc310..fbb335ccab 100644 --- a/scripts/layering/architecture-ownership.ts +++ b/scripts/layering/architecture-ownership.ts @@ -254,7 +254,6 @@ export const ARCHITECTURE_OWNERSHIP = { 'applyRecordedSaveScriptFlags', 'armAuthoringOnOpen', 'effectiveWriteForce', - 'isArmedRemoteRecording', 'isAuthoringArmedSession', 'isSessionRecording', 'isSessionScriptPublished', diff --git a/test/wire-compat/ledger.json b/test/wire-compat/ledger.json index bdabba0ca5..1372aa1c91 100644 --- a/test/wire-compat/ledger.json +++ b/test/wire-compat/ledger.json @@ -1,5 +1,5 @@ { - "protocolVersion": 2, + "protocolVersion": 3, "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", @@ -62,7 +62,7 @@ "packages/daemon-client/src/daemon-client-rpc.ts#buildHttpRpcPayload": "sha256:8978ef89d3af866bd94fec52c586a0cbf3217ee9e60952fbc826e8208e5fa158", "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#rejectDaemonHttpRpcError": "sha256:51f17269ac0a02116ba8af33c9884b10b74f78bcb54c40f77dd887f1f08d8246", "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:1ff542dadff6d92233c464b7d09052d809f36186bb60acdb572c48bfc1eb5c1f", @@ -154,7 +154,7 @@ "packages/remote/src/daemon-artifacts.ts#buildDaemonArtifactUrl": "sha256:06dcde057809b507f70f7bb5cdef9bde6515be84b67e45865cf19e70b8636208", "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:654a8f47f437430a0947a44d1c126c253448351f02cd8f46dd32bde13278f1cc", + "packages/remote/src/daemon-artifacts.ts#materializeRemoteArtifacts": "sha256:6501d7e449f51e8462e4eb957ee54c2f4821879bd2184a6c25dd11ee71be9dea", "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", @@ -233,18 +233,13 @@ { "declaration": "packages/remote/src/daemon-artifacts.ts#DownloadRemoteArtifactParams", "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." + "rationale": "#2246 adds the optional isDirectory field. It is pure client-local state \u2014 never serialized, never sent to the daemon \u2014 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: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: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", "digest": "sha256:8978ef89d3af866bd94fec52c586a0cbf3217ee9e60952fbc826e8208e5fa158", @@ -308,7 +303,7 @@ { "declaration": "packages/daemon/src/server/http/http-authorization.ts#authorizeAuxiliaryHttpRequest", "digest": "sha256:1c323f97c3cefec8f95633b6abd127342bf75494bfb109d1cc6eadf3ceacaeae", - "rationale": "#2198 context: adds one optional field to the value this DAEMON-INTERNAL gate hands its own route handlers — sessionNamespace, the caller's tenant plus whether the daemon partitioned that caller's session names. Nothing about it is serialized: no request header is read that was not read before, no response field is added, and a refusal keeps the same 401 {ok:false,error,code} REST body sendRestJsonError already sent. What it enables is a refusal DROPPED, never one added — an unattested (client-declared) tenant no longer has the : prefix rule applied to it, because scopeRequestSession never applied that prefix to its sessions either. A released peer that now gets 200 where it got 401 is getting the ndjson record it asked for and already parses." + "rationale": "#2198 context: adds one optional field to the value this DAEMON-INTERNAL gate hands its own route handlers \u2014 sessionNamespace, the caller's tenant plus whether the daemon partitioned that caller's session names. Nothing about it is serialized: no request header is read that was not read before, no response field is added, and a refusal keeps the same 401 {ok:false,error,code} REST body sendRestJsonError already sent. What it enables is a refusal DROPPED, never one added \u2014 an unattested (client-declared) tenant no longer has the : prefix rule applied to it, because scopeRequestSession never applied that prefix to its sessions either. A released peer that now gets 200 where it got 401 is getting the ndjson record it asked for and already parses." }, { "declaration": "packages/daemon/src/server/request-diagnostics-http.ts#RequestDiagnosticsHttpAuthorizer", @@ -440,11 +435,6 @@ "digest": "sha256:6f68c317e4c0fe5de008ec1fe5e7e030a9d298ad4a7dfd561db933d22e12ae9e", "rationale": "Clients name a held agent-device lease in an optional x-agent-device-lease-id request header on upload, artifact download and request diagnostics HTTP calls, so a gateway can route them. Released daemons ignore unknown request headers and the proxy forwards only its allowlist, so routes, bodies and responses parse as before; with no lease held the request is unchanged (ADR 0006)." }, - { - "declaration": "packages/daemon-client/src/daemon-client-rpc.ts#rejectDaemonHttpRpcError", - "digest": "sha256:a5cf6fd4a9abea34ec051f03d6e45e5aa248f480371fdf22f93de06622a57b47", - "rationale": "Clients name a held agent-device lease in an optional x-agent-device-lease-id request header on upload, artifact download and request diagnostics HTTP calls, so a gateway can route them. Released daemons ignore unknown request headers and the proxy forwards only its allowlist, so routes, bodies and responses parse as before; with no lease held the request is unchanged (ADR 0006). The signature also names the client request as DaemonWireRequest and the kernel DaemonResponse instead of the daemon package aliases; only compile-time type names moved." - }, { "declaration": "packages/remote/src/upload-client.ts#uploadDirectArtifact", "digest": "sha256:93a36a9d3dea88064569517f3cdc34f27b33df6bf5f0c0ecc9efc29b47f24b77", From 9128f8495dcd8223d64aef9de8cd4b11b70aa1d4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Tue, 17 Nov 2026 11:46:01 +0100 Subject: [PATCH 06/10] fix(remote): disclose receipt failures after client record cleanup --- .../core/request-script-delivery-ledger.ts | 2 +- .../daemon-artifacts-script-receipt.test.ts | 53 +++++++++++++++++++ .../remote/src/session-script-destination.ts | 4 +- test/integration/support/exit-after-flush.ts | 3 +- .../support/provider-disconnect-fetch.mjs | 3 +- 5 files changed, 59 insertions(+), 6 deletions(-) diff --git a/packages/daemon/src/core/request-script-delivery-ledger.ts b/packages/daemon/src/core/request-script-delivery-ledger.ts index d404309b20..8630bc9141 100644 --- a/packages/daemon/src/core/request-script-delivery-ledger.ts +++ b/packages/daemon/src/core/request-script-delivery-ledger.ts @@ -5,7 +5,7 @@ import type { ScriptDeliveryReceipt, } from '@agent-device/kernel/contracts'; import { readScriptDeliveryFailure } from '@agent-device/kernel/contracts'; -import { normalizeBatchCommandName } from '@agent-device/contracts/input-validation'; +import { normalizeBatchCommandName } from '@agent-device/contracts/command'; import type { DaemonRequest } from './daemon-request.ts'; /** * The script-delivery ledger of one daemon request (ADR 0016, #4595). diff --git a/packages/remote/src/__tests__/daemon-artifacts-script-receipt.test.ts b/packages/remote/src/__tests__/daemon-artifacts-script-receipt.test.ts index 2aa9138a37..1e30388c83 100644 --- a/packages/remote/src/__tests__/daemon-artifacts-script-receipt.test.ts +++ b/packages/remote/src/__tests__/daemon-artifacts-script-receipt.test.ts @@ -551,3 +551,56 @@ test.each([ expect(fs.readFileSync(destination, 'utf8')).toBe('open Demo\n'); expect(records(stateDir)).toHaveLength(1); }); + +test.each(['success', 'failure'] as const)( + 'a %s receipt discloses daemon failures after the client record is gone', + async (outcome) => { + const { stateDir, destination } = world(); + const baseUrl = await artifactServer({ 'open-v1': 'open Demo\n', v2: 'must not publish\n' }); + const id = await opened(baseUrl, stateDir, destination); + for (const file of records(stateDir)) { + fs.unlinkSync(path.join(stateDir, 'remote-connections', 'session-scripts', file)); + } + const failure = { + reason: 'script_delivery_failed' as const, + publicationId: id, + message: 'The daemon could not write the final script.', + hint: 'The caller file keeps its earlier recording.', + }; + const plan = batchRequest([ + { command: 'close', input: {} }, + { command: 'press', input: {} }, + ]); + const delivery = receipt(id, { + version: script('v2', 2, id), + close: { step: 1 }, + failures: [failure], + }); + let disclosed: Record | undefined; + if (outcome === 'success') { + const response = await answer(baseUrl, stateDir, plan, delivery); + expect(response.ok).toBe(true); + if (response.ok) disclosed = response.data; + } else { + const { settleScriptDeliveryReceiptOfFailure, downloadRemoteArtifact } = + await import('../daemon-artifacts.ts'); + const error = await settleScriptDeliveryReceiptOfFailure( + { baseUrl, token: 't' }, + plan, + { + code: 'COMMAND_FAILED', + message: 'Original batch failure', + details: { step: 2, command: 'press', ...delivery }, + }, + stateDir, + downloadRemoteArtifact, + ); + expect(error.message).toBe('Original batch failure'); + disclosed = error.details; + } + expect(disclosed?.scriptDeliveryFailure).toEqual(failure); + expect(disclosed?.warnings).toEqual([`${failure.message} ${failure.hint}`]); + expect(fs.readFileSync(destination, 'utf8')).toBe('open Demo\n'); + expect(records(stateDir)).toEqual([]); + }, +); diff --git a/packages/remote/src/session-script-destination.ts b/packages/remote/src/session-script-destination.ts index 9b06a7b161..681999239f 100644 --- a/packages/remote/src/session-script-destination.ts +++ b/packages/remote/src/session-script-destination.ts @@ -112,6 +112,7 @@ async function settleScriptReceipt( ): Promise { const { endpoint, req, stateDir } = context; const failures = [...(receipt.failures ?? [])]; + for (const failure of failures) disclose(failure, undefined); const file = recordPath(stateDir, endpoint.baseUrl, req, receipt.publicationId); const record = readRecord(file); if (!record) { @@ -122,9 +123,6 @@ async function settleScriptReceipt( }); return { failures }; } - // A daemon failure is disclosed whether or not this client can save anything: the caller's file is - // stale either way. - for (const failure of failures) disclose(failure, undefined); const published = receipt.version ? await publishScriptVersion(context, receipt.version) : undefined; diff --git a/test/integration/support/exit-after-flush.ts b/test/integration/support/exit-after-flush.ts index 9c298fbeb5..a8857c24bc 100644 --- a/test/integration/support/exit-after-flush.ts +++ b/test/integration/support/exit-after-flush.ts @@ -1,3 +1,4 @@ +import { DAEMON_RPC_PROTOCOL_VERSION } from '@agent-device/contracts/daemon-http'; // #1596/#1706 fixture: writes an oversized payload through a real piped CLI // process so the parent must receive the trailing marker before either exit. import https, { type RequestOptions } from 'node:https'; @@ -49,7 +50,7 @@ async function routeFixtureRequest(request: Request, payloadMarker: string): Pro ok: true, service: 'agent-device-daemon', version: '0.20.6', - rpcProtocolVersion: 2, + rpcProtocolVersion: DAEMON_RPC_PROTOCOL_VERSION, }); case `POST ${DAEMON_BASE_URL}/rpc`: return await rpcResponse(request, payloadMarker); diff --git a/test/integration/support/provider-disconnect-fetch.mjs b/test/integration/support/provider-disconnect-fetch.mjs index 383e169cb0..11fc6b9b52 100644 --- a/test/integration/support/provider-disconnect-fetch.mjs +++ b/test/integration/support/provider-disconnect-fetch.mjs @@ -1,3 +1,4 @@ +import { DAEMON_RPC_PROTOCOL_VERSION } from '@agent-device/contracts/daemon-http'; import fs from 'node:fs'; import https from 'node:https'; import { EventEmitter } from 'node:events'; @@ -31,7 +32,7 @@ function createFixtureFetch(logPath) { ok: true, service: 'agent-device-daemon', version: '0.0.0-test', - rpcProtocolVersion: 2, + rpcProtocolVersion: DAEMON_RPC_PROTOCOL_VERSION, }), ), route('POST', `${DAEMON_BASE_URL}/rpc`, async (request) => { From d222cd6e623b3907559d62eb7c525cc111a55a52 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Tue, 17 Nov 2026 12:16:09 +0100 Subject: [PATCH 07/10] chore(gates): split runtime package boundary checks below the file limit --- .../package-boundaries-runtime.test.ts | 72 +++++++++++++++++++ scripts/layering/package-boundaries.test.ts | 70 ------------------ 2 files changed, 72 insertions(+), 70 deletions(-) create mode 100644 scripts/layering/package-boundaries-runtime.test.ts diff --git a/scripts/layering/package-boundaries-runtime.test.ts b/scripts/layering/package-boundaries-runtime.test.ts new file mode 100644 index 0000000000..a7ad3207ac --- /dev/null +++ b/scripts/layering/package-boundaries-runtime.test.ts @@ -0,0 +1,72 @@ +import assert from 'node:assert/strict'; +import { test } from 'node:test'; + +test('Node resolution enforces the exports map at runtime', () => { + // Real resolver, not the gate's model: a deep import is a resolution error, + // and the legal subpath realpaths OUTSIDE node_modules (pnpm symlink), which + // is what lets --experimental-strip-types load package sources in dev. + const resolved = import.meta.resolve('@agent-device/kernel/errors'); + assert.ok(resolved.endsWith('packages/kernel/src/errors.ts'), resolved); + for (const deep of [ + '@agent-device/kernel/src/errors.ts', + '@agent-device/kernel/internal-not-exported', + '@agent-device/kernel', + '@agent-device/contracts/not-an-export', + '@agent-device/contracts/src/gesture-plan.ts', + '@agent-device/contracts', + '@agent-device/contracts/src/snapshot-text.ts', + '@agent-device/contracts/src/facades/snapshot.ts', + '@agent-device/provider-webdriver/runtime', + '@agent-device/provider-webdriver/src/runtime.ts', + '@agent-device/provider-limrun/runtime', + '@agent-device/provider-limrun/src/runtime.ts', + '@agent-device/xml/internal/parser', + '@agent-device/xml/src/index.ts', + '@agent-device/ad-script/codec', + '@agent-device/ad-script/internal/script.ts', + '@agent-device/ad-script/src/index.ts', + '@agent-device/ad-replay/testing', + '@agent-device/ad-replay/internal/target-verification.ts', + '@agent-device/ad-replay/src/index.ts', + '@agent-device/selectors/internal/parse.ts', + '@agent-device/selectors/src/index.ts', + ]) { + assert.throws( + () => import.meta.resolve(deep), + /ERR_PACKAGE_PATH_NOT_EXPORTED|Package subpath|No "exports" main/, + `${deep} must not resolve`, + ); + } + + const contractsResolved = import.meta.resolve('@agent-device/contracts/interaction'); + assert.ok(contractsResolved.endsWith('packages/contracts/src/interaction.ts'), contractsResolved); + const contractsSnapshotResolved = import.meta.resolve('@agent-device/contracts/snapshot'); + assert.ok( + contractsSnapshotResolved.endsWith('packages/contracts/src/facades/snapshot.ts'), + contractsSnapshotResolved, + ); + const contractsReactNativeOverlayResolved = import.meta + .resolve('@agent-device/contracts/react-native-overlay'); + assert.ok( + contractsReactNativeOverlayResolved.endsWith('packages/contracts/src/react-native-overlay.ts'), + contractsReactNativeOverlayResolved, + ); + const providerWebDriverResolved = import.meta.resolve('@agent-device/provider-webdriver'); + assert.ok( + providerWebDriverResolved.endsWith('packages/provider-webdriver/src/index.ts'), + providerWebDriverResolved, + ); + const providerLimrunResolved = import.meta.resolve('@agent-device/provider-limrun'); + assert.ok( + providerLimrunResolved.endsWith('packages/provider-limrun/src/index.ts'), + providerLimrunResolved, + ); + const xmlResolved = import.meta.resolve('@agent-device/xml'); + assert.ok(xmlResolved.endsWith('packages/xml/src/index.ts'), xmlResolved); + const adScriptResolved = import.meta.resolve('@agent-device/ad-script'); + assert.ok(adScriptResolved.endsWith('packages/ad-script/src/index.ts'), adScriptResolved); + const adReplayResolved = import.meta.resolve('@agent-device/ad-replay'); + assert.ok(adReplayResolved.endsWith('packages/ad-replay/src/index.ts'), adReplayResolved); + const selectorsResolved = import.meta.resolve('@agent-device/selectors'); + assert.ok(selectorsResolved.endsWith('packages/selectors/src/index.ts'), selectorsResolved); +}); diff --git a/scripts/layering/package-boundaries.test.ts b/scripts/layering/package-boundaries.test.ts index 3748988247..c6c8063a00 100644 --- a/scripts/layering/package-boundaries.test.ts +++ b/scripts/layering/package-boundaries.test.ts @@ -929,73 +929,3 @@ test('the real tree parses, declares, and passes R11', () => { ); assert.deepEqual(checkPackageBoundaries(repoRoot), []); }); - -test('Node resolution enforces the exports map at runtime', () => { - // Real resolver, not the gate's model: a deep import is a resolution error, - // and the legal subpath realpaths OUTSIDE node_modules (pnpm symlink), which - // is what lets --experimental-strip-types load package sources in dev. - const resolved = import.meta.resolve('@agent-device/kernel/errors'); - assert.ok(resolved.endsWith('packages/kernel/src/errors.ts'), resolved); - for (const deep of [ - '@agent-device/kernel/src/errors.ts', - '@agent-device/kernel/internal-not-exported', - '@agent-device/kernel', - '@agent-device/contracts/not-an-export', - '@agent-device/contracts/src/gesture-plan.ts', - '@agent-device/contracts', - '@agent-device/contracts/src/snapshot-text.ts', - '@agent-device/contracts/src/facades/snapshot.ts', - '@agent-device/provider-webdriver/runtime', - '@agent-device/provider-webdriver/src/runtime.ts', - '@agent-device/provider-limrun/runtime', - '@agent-device/provider-limrun/src/runtime.ts', - '@agent-device/xml/internal/parser', - '@agent-device/xml/src/index.ts', - '@agent-device/ad-script/codec', - '@agent-device/ad-script/internal/script.ts', - '@agent-device/ad-script/src/index.ts', - '@agent-device/ad-replay/testing', - '@agent-device/ad-replay/internal/target-verification.ts', - '@agent-device/ad-replay/src/index.ts', - '@agent-device/selectors/internal/parse.ts', - '@agent-device/selectors/src/index.ts', - ]) { - assert.throws( - () => import.meta.resolve(deep), - /ERR_PACKAGE_PATH_NOT_EXPORTED|Package subpath|No "exports" main/, - `${deep} must not resolve`, - ); - } - - const contractsResolved = import.meta.resolve('@agent-device/contracts/interaction'); - assert.ok(contractsResolved.endsWith('packages/contracts/src/interaction.ts'), contractsResolved); - const contractsSnapshotResolved = import.meta.resolve('@agent-device/contracts/snapshot'); - assert.ok( - contractsSnapshotResolved.endsWith('packages/contracts/src/facades/snapshot.ts'), - contractsSnapshotResolved, - ); - const contractsReactNativeOverlayResolved = import.meta - .resolve('@agent-device/contracts/react-native-overlay'); - assert.ok( - contractsReactNativeOverlayResolved.endsWith('packages/contracts/src/react-native-overlay.ts'), - contractsReactNativeOverlayResolved, - ); - const providerWebDriverResolved = import.meta.resolve('@agent-device/provider-webdriver'); - assert.ok( - providerWebDriverResolved.endsWith('packages/provider-webdriver/src/index.ts'), - providerWebDriverResolved, - ); - const providerLimrunResolved = import.meta.resolve('@agent-device/provider-limrun'); - assert.ok( - providerLimrunResolved.endsWith('packages/provider-limrun/src/index.ts'), - providerLimrunResolved, - ); - const xmlResolved = import.meta.resolve('@agent-device/xml'); - assert.ok(xmlResolved.endsWith('packages/xml/src/index.ts'), xmlResolved); - const adScriptResolved = import.meta.resolve('@agent-device/ad-script'); - assert.ok(adScriptResolved.endsWith('packages/ad-script/src/index.ts'), adScriptResolved); - const adReplayResolved = import.meta.resolve('@agent-device/ad-replay'); - assert.ok(adReplayResolved.endsWith('packages/ad-replay/src/index.ts'), adReplayResolved); - const selectorsResolved = import.meta.resolve('@agent-device/selectors'); - assert.ok(selectorsResolved.endsWith('packages/selectors/src/index.ts'), selectorsResolved); -}); From 3610f78ba556fafa39ace5bd9b5d4be7416180be Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Tue, 17 Nov 2026 12:58:35 +0100 Subject: [PATCH 08/10] docs(remote): correct batch recording delivery through proxies --- website/docs/docs/remote-proxy.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/website/docs/docs/remote-proxy.md b/website/docs/docs/remote-proxy.md index 44cd873478..aad730a64f 100644 --- a/website/docs/docs/remote-proxy.md +++ b/website/docs/docs/remote-proxy.md @@ -122,9 +122,10 @@ recorded a version discloses it: the CLI prints a warning and carries a typed `scriptDeliveryFailure` in `--json`, and the SDK and MCP results carry the same field. 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. A batch delivers no script versions from its steps -([#4595](https://github.com/callstack/agent-device/issues/4595)). +batch steps are refused. A remote `batch` updates your file once with the recording from its +completed steps, including the final script when a step closes the session. If a step fails, the +batch keeps that error and delivers the recording from earlier completed steps. Delivery failures +add `scriptDeliveryFailure` and a warning, and your file may keep its previous version. 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 From ce3ba4437c81ed3be18a4e3583bab0f161b69913 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Tue, 17 Nov 2026 13:27:56 +0100 Subject: [PATCH 09/10] docs(remote): describe batch receipts for RPC callers --- website/docs/docs/remote-proxy.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/website/docs/docs/remote-proxy.md b/website/docs/docs/remote-proxy.md index aad730a64f..e9c452a5e4 100644 --- a/website/docs/docs/remote-proxy.md +++ b/website/docs/docs/remote-proxy.md @@ -129,7 +129,12 @@ add `scriptDeliveryFailure` and a warning, and your file may keep its previous v 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. +`scriptRevision` that grows with each version. For a single command, download the artifacts by ID +and keep the newest. For a batch, read `scriptDeliveryReceipt` from `data` on success or +`error.details` on failure: it names the `publicationId`, the optional newest full-script `version`, +the optional `close.step` (a 1-based position in your submitted plan), and any typed `failures`. +Download only that version, validate the close against your plan, and report the failures; do not +derive delivery from step results. 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` @@ -361,7 +366,7 @@ checks `upstream.leaseBackends` for `macos-app` before handing out a macOS app l daemons omit it. ```json -{"ok":true,"service":"agent-device-proxy","version":"0.21.17","rpcProtocolVersion":2,"instanceId":"5f0c2d7e-8a41-4b7e-9c3a-2e6d1f4b8a90","hostArch":"arm64","upstream":{"ok":true,"service":"agent-device-daemon","version":"0.21.17","rpcProtocolVersion":2,"instanceId":"b3e9a6c1-4d2f-4f8e-a0b7-7c5d9e1f2a34","hostArch":"arm64"}} +{"ok":true,"service":"agent-device-proxy","version":"0.21.39-dev","rpcProtocolVersion":3,"instanceId":"5f0c2d7e-8a41-4b7e-9c3a-2e6d1f4b8a90","hostArch":"arm64","upstream":{"ok":true,"service":"agent-device-daemon","version":"0.21.39-dev","rpcProtocolVersion":3,"instanceId":"b3e9a6c1-4d2f-4f8e-a0b7-7c5d9e1f2a34","hostArch":"arm64"}} ``` ## Clean up From 30cece8ef0b147245eda827b9723da50c2405e89 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Tue, 17 Nov 2026 13:40:04 +0100 Subject: [PATCH 10/10] fix(remote): deliver receipt versions when a batch names no step A batch that fails with no step position the plan can reconcile, or whose close sits at or past the failure, proves no close. Its receipt's version and typed failures are still facts the daemon answered about this client's own publication, so they settle and disclose instead of being dropped: silently losing them left the caller file stale with no warning. Only the retirement is dropped. An answer that cannot be reconciled with the plan authorizes nothing at all. Drop the batch-policy re-export of normalizeBatchCommandName so both peers read the contracts facade, prove the ledger's nested flag is load-bearing, and restore the ledger rationale escapes. --- .../0016-active-session-script-publication.md | 2 +- packages/command-registry/src/batch-policy.ts | 2 - packages/command-registry/src/batch.ts | 2 +- .../request-script-delivery-ledger.test.ts | 15 ++++ packages/daemon/src/core/daemon-policy.ts | 2 +- .../daemon/src/resources/macos-app-lease.ts | 2 +- .../daemon-artifacts-script-receipt.test.ts | 70 ++++++++++++++++++- .../remote/src/session-script-destination.ts | 40 +++++++++-- test/wire-compat/ledger.json | 4 +- 9 files changed, 124 insertions(+), 15 deletions(-) diff --git a/docs/adr/0016-active-session-script-publication.md b/docs/adr/0016-active-session-script-publication.md index d5a0abc88c..547b37f080 100644 --- a/docs/adr/0016-active-session-script-publication.md +++ b/docs/adr/0016-active-session-script-publication.md @@ -209,7 +209,7 @@ It adds no state name, command, or flag: 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). Every result that can carry a script version discloses a failed delivery: the SDK result, the CLI human output and `--json`, and the MCP tool result each carry `scriptDeliveryFailure` and the warning, so no caller reads a stale file as current. -A batch delivers through one receipt the daemon's request owner answers on the batch reply, successful or failed (#4595). The daemon collects each executed step's script effects as the batch runner reports them, because a step's own reply travels inside a result entry a client must not read. The receipt names the newest full-script version of the recording, the plan position of a step that closed it, and the typed failures; it is answered only for a request whose nested steps fed it, so every single-command reply keeps the shape it had before. A client validates the receipt against its own record and its submitted plan, downloads at most its one version, and treats a receipt it cannot fully account for as authorizing nothing. +A batch delivers through one receipt the daemon's request owner answers on the batch reply, successful or failed (#4595). The daemon collects each executed step's script effects as the batch runner reports them, because a step's own reply travels inside a result entry a client must not read. The receipt names the newest full-script version of the recording, the plan position of a step that closed it, and the typed failures; it is answered only for a request whose nested steps fed it, so every single-command reply keeps the shape it had before. A client validates the receipt against its own record and its submitted plan, downloads at most its one version, and treats a receipt it cannot fully account for as authorizing nothing. A failed batch whose answer names no step position the plan can reconcile, or whose close sits at or past that position, proves no close: the version and the failures still settle, because the daemon answered them about that client's own publication, and only the retirement is dropped. This receipt requires RPC protocol 3: protocol-2 clients ignore it, so admitting a batch close for them could leave the caller's final script undelivered. The health compatibility gate rejects those skewed peers before dispatch (ADR 0006). Rejected: deriving delivery effects by interpreting the batch's step entries, partial results and failure position, because six review rounds kept finding answers that made a client deliver the wrong version, retire a recording that never closed, or drop a failure (#4582). Rejected: a remote `session save-script` download, because it added a second publication path and a retry protocol. diff --git a/packages/command-registry/src/batch-policy.ts b/packages/command-registry/src/batch-policy.ts index 7117b73984..57e081d38c 100644 --- a/packages/command-registry/src/batch-policy.ts +++ b/packages/command-registry/src/batch-policy.ts @@ -3,8 +3,6 @@ import { commandDescriptors } from './registry.ts'; import { AppError } from '@agent-device/kernel/errors'; import { normalizeBatchCommandName } from '@agent-device/contracts/input-validation'; -export { normalizeBatchCommandName }; - /** * The exact set of command names exposed through `batch`, as a narrow union. * diff --git a/packages/command-registry/src/batch.ts b/packages/command-registry/src/batch.ts index ca1973fa89..8d10420444 100644 --- a/packages/command-registry/src/batch.ts +++ b/packages/command-registry/src/batch.ts @@ -19,13 +19,13 @@ import { DEFAULT_BATCH_MAX_STEPS, assertBatchStepCount, isValidBatchMaxSteps, + normalizeBatchCommandName, parseBatchStepRuntime, } from '@agent-device/contracts/command'; import { BATCH_DAEMON_STEP_KEYS, INHERITED_PARENT_FLAG_KEYS, assertBatchRuntimeCommandAllowed, - normalizeBatchCommandName, } from './batch-policy.ts'; import { resolveCommandRecordingEffect } from './registry.ts'; diff --git a/packages/daemon/src/core/__tests__/request-script-delivery-ledger.test.ts b/packages/daemon/src/core/__tests__/request-script-delivery-ledger.test.ts index fcda0eafea..1bb6c97b0a 100644 --- a/packages/daemon/src/core/__tests__/request-script-delivery-ledger.test.ts +++ b/packages/daemon/src/core/__tests__/request-script-delivery-ledger.test.ts @@ -63,6 +63,21 @@ test('a request whose steps delivered nothing answers no receipt', async () => { expect(response).toEqual({ ok: true, data: { results: [] } }); }); +test('a reply no nested step fed answers no receipt, even when it names script artifacts', async () => { + // A single command's own reply already delivers through its artifacts; a receipt on it would + // change every recorded action's shape. Only a request whose ledger its nested steps fed — a + // composite — answers one. + const response = await reportScriptDelivery(batchRequest(1), async () => ({ + ok: true, + data: { artifacts: [script('v2', 2)], scriptDeliveryFailure: failure() }, + })); + + expect(response).toEqual({ + ok: true, + data: { artifacts: [script('v2', 2)], scriptDeliveryFailure: failure() }, + }); +}); + test('the versions, the failure and the close the steps answered become one receipt on the outer reply', async () => { let scriptDelivery: ScriptDeliveryLedger | undefined; const response = await reportScriptDelivery(batchRequest(2), async (outer) => { diff --git a/packages/daemon/src/core/daemon-policy.ts b/packages/daemon/src/core/daemon-policy.ts index 81c6357bda..48ccd80819 100644 --- a/packages/daemon/src/core/daemon-policy.ts +++ b/packages/daemon/src/core/daemon-policy.ts @@ -1,4 +1,4 @@ -import { normalizeBatchCommandName } from '@agent-device/command-registry/batch-policy'; +import { normalizeBatchCommandName } from '@agent-device/contracts/command'; import type { AppDeviceResolver, ComposedDeviceInventoryGateways, diff --git a/packages/daemon/src/resources/macos-app-lease.ts b/packages/daemon/src/resources/macos-app-lease.ts index ba20ba0223..02115f333c 100644 --- a/packages/daemon/src/resources/macos-app-lease.ts +++ b/packages/daemon/src/resources/macos-app-lease.ts @@ -1,7 +1,7 @@ import type { HostEnvironment } from '@agent-device/kernel/source-value'; import type { DaemonResponse, DaemonResponseData } from '@agent-device/kernel/contracts'; import os from 'node:os'; -import { normalizeBatchCommandName } from '@agent-device/command-registry/batch-policy'; +import { normalizeBatchCommandName } from '@agent-device/contracts/command'; import { isRemoteTempArtifactPath } from '@agent-device/contracts/daemon-http'; import type { DeviceLease } from '@agent-device/contracts/device'; import { readMacOsAppBackend } from '@agent-device/contracts/session'; diff --git a/packages/remote/src/__tests__/daemon-artifacts-script-receipt.test.ts b/packages/remote/src/__tests__/daemon-artifacts-script-receipt.test.ts index 1e30388c83..1ec7c63363 100644 --- a/packages/remote/src/__tests__/daemon-artifacts-script-receipt.test.ts +++ b/packages/remote/src/__tests__/daemon-artifacts-script-receipt.test.ts @@ -519,10 +519,9 @@ test('a malformed close receipt cannot throw or fall back to batch script artifa }); test.each([ - { name: 'an unreached close', details: { step: 1, command: 'wait' } }, - { name: 'missing failure position', details: {} }, { name: 'a position past the plan', details: { step: 3, command: 'close' } }, { name: 'a different command', details: { step: 1, command: 'close' } }, + { name: 'a position that is not a number', details: { step: 'two', command: 'close' } }, ])('a failed batch with $name authorizes no delivery', async ({ details }) => { const { settleScriptDeliveryReceiptOfFailure } = await import('../daemon-artifacts.ts'); const { downloadRemoteArtifact } = await import('../daemon-artifacts.ts'); @@ -552,6 +551,73 @@ test.each([ expect(records(stateDir)).toHaveLength(1); }); +test('a failed batch whose close the plan never reached delivers the version and retires nothing', async () => { + // The position is reconciled with the plan and proves the close step never ran, so the version + // the completed steps wrote is still delivered — but nothing retires the record. + const { settleScriptDeliveryReceiptOfFailure } = await import('../daemon-artifacts.ts'); + const { downloadRemoteArtifact } = await import('../daemon-artifacts.ts'); + const { stateDir, destination } = world(); + const baseUrl = await artifactServer({ + 'open-v1': 'open Demo\n', + v2: 'open Demo\nwait\n', + }); + const id = await opened(baseUrl, stateDir, destination); + const settled = await settleScriptDeliveryReceiptOfFailure( + { baseUrl, token: 't' }, + batchRequest([ + { command: 'wait', input: {} }, + { command: 'close', input: {} }, + ]), + { + code: 'COMMAND_FAILED' as const, + message: 'original batch failure', + details: { + step: 1, + command: 'wait', + ...receipt(id, { version: script('v2', 2, id), close: { step: 2 } }), + }, + }, + stateDir, + downloadRemoteArtifact, + ); + expect(settled.message).toBe('original batch failure'); + expect(fs.readFileSync(destination, 'utf8')).toBe('open Demo\nwait\n'); + expect(records(stateDir)).toHaveLength(1); +}); + +test('a failed batch that names no position delivers the version and discloses, and retires nothing', async () => { + // A request deadline or a step that throws into the runner fails the batch with no step position. + // The version and failures are still facts about this client's publication, and dropping them + // would leave the caller file stale with no warning. An answer that cannot name where it stopped + // proves no close, so nothing retires. + const { settleScriptDeliveryReceiptOfFailure } = await import('../daemon-artifacts.ts'); + const { downloadRemoteArtifact } = await import('../daemon-artifacts.ts'); + const { stateDir, destination } = world(); + const baseUrl = await artifactServer({ + 'open-v1': 'open Demo\n', + v2: 'open Demo\nwait\nclose\n', + }); + const id = await opened(baseUrl, stateDir, destination); + const settled = await settleScriptDeliveryReceiptOfFailure( + { baseUrl, token: 't' }, + batchRequest([ + { command: 'wait', input: {} }, + { command: 'close', input: {} }, + ]), + { + code: 'COMMAND_FAILED' as const, + message: 'original batch failure', + details: receipt(id, { version: script('v2', 2, id), close: { step: 2 } }), + }, + stateDir, + downloadRemoteArtifact, + ); + expect(settled.message).toBe('original batch failure'); + expect(settled.details?.scriptDeliveryReceipt).toBeDefined(); + expect(fs.readFileSync(destination, 'utf8')).toBe('open Demo\nwait\nclose\n'); + expect(records(stateDir)).toHaveLength(1); +}); + test.each(['success', 'failure'] as const)( 'a %s receipt discloses daemon failures after the client record is gone', async (outcome) => { diff --git a/packages/remote/src/session-script-destination.ts b/packages/remote/src/session-script-destination.ts index 681999239f..078c8614e7 100644 --- a/packages/remote/src/session-script-destination.ts +++ b/packages/remote/src/session-script-destination.ts @@ -259,8 +259,9 @@ function discloseDeliveryFailure( /** * Settles the one delivery receipt a FAILED response names (#4595), where no successful-artifact * path runs: a batch that stopped mid-plan still delivers what its completed steps wrote. The - * disclosure rides the error the caller receives, and a close validated against the submitted plan - * still retires the record. + * disclosure rides the error the caller receives. A close retires the record only when the failure + * position is validated against the submitted plan and the close comes before that failure; nothing + * else proves the close ran. */ export async function settleScriptDeliveryReceiptOfFailure( endpoint: Required, @@ -271,13 +272,21 @@ export async function settleScriptDeliveryReceiptOfFailure( ): Promise { const receipt = readScriptDeliveryReceipt({ ok: false, error }); if (!receipt || req.command !== 'batch') return error; + // An error whose failure position cannot be reconciled with the submitted plan makes the whole + // answer untrustworthy, and an untrustworthy answer authorizes nothing. + if (unreconcilableFailurePosition(req, error)) return error; + // A validated position before the receipt's close proves the close step never ran, and a batch + // can stop with no position at all (a request deadline, or a step that threw inside the runner). + // Neither case proves a close, so the close is dropped; the version and the failures are facts the + // daemon answered about THIS client's publication, so they still settle. Silently dropping them + // would leave the caller file stale with no warning, which is what this disclosure exists for. const failedStep = validatedFailedBatchStep(req, error); - if (failedStep === undefined) return error; - if (receipt.close !== undefined && receipt.close.step >= failedStep) return error; + const honored = + receipt.close === undefined || (failedStep !== undefined && receipt.close.step < failedStep); const data: Record = { ...(error.details ?? {}) }; const settled = await settleScriptReceipt( { endpoint, req, stateDir, download }, - receipt, + honored ? receipt : withoutClose(receipt), (failure, failureError) => discloseDeliveryFailure(data, req, failure, failureError), ); if (settled.retire) await retireQuietly(req, settled.retire); @@ -291,6 +300,27 @@ export async function settleScriptDeliveryReceiptOfFailure( return { ...error, details: { ...(error.details ?? {}), ...disclosure } }; } +/** The receipt with its close dropped: its version and failures still settle, nothing retires. */ +function withoutClose(receipt: ScriptDeliveryReceipt): ScriptDeliveryReceipt { + return { + publicationId: receipt.publicationId, + ...(receipt.version === undefined ? {} : { version: receipt.version }), + ...(receipt.failures === undefined ? {} : { failures: receipt.failures }), + }; +} + +function unreconcilableFailurePosition(req: DaemonWireRequest, error: DaemonError): boolean { + const { step, command } = error.details ?? {}; + if (step === undefined && command === undefined) return false; + return validatedFailedBatchStep(req, error) === undefined; +} + +/** + * The batch step this error names, when the submitted plan carries exactly that command at exactly + * that position. An answer naming an unparseable position, a position past the plan, or a command + * the plan does not carry there cannot be reconciled with the plan the client sent, and the client + * acts on no part of an answer it cannot reconcile. + */ function validatedFailedBatchStep(req: DaemonWireRequest, error: DaemonError): number | undefined { const steps = req.flags?.batchSteps; const step = error.details?.step; diff --git a/test/wire-compat/ledger.json b/test/wire-compat/ledger.json index 1372aa1c91..fd2951b454 100644 --- a/test/wire-compat/ledger.json +++ b/test/wire-compat/ledger.json @@ -233,7 +233,7 @@ { "declaration": "packages/remote/src/daemon-artifacts.ts#DownloadRemoteArtifactParams", "digest": "sha256:3b0678250f72dca4ac1709103fd4c540dedd4d488eb3299ace5ce6b7c479676c", - "rationale": "#2246 adds the optional isDirectory field. It is pure client-local state \u2014 never serialized, never sent to the daemon \u2014 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." + "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", @@ -303,7 +303,7 @@ { "declaration": "packages/daemon/src/server/http/http-authorization.ts#authorizeAuxiliaryHttpRequest", "digest": "sha256:1c323f97c3cefec8f95633b6abd127342bf75494bfb109d1cc6eadf3ceacaeae", - "rationale": "#2198 context: adds one optional field to the value this DAEMON-INTERNAL gate hands its own route handlers \u2014 sessionNamespace, the caller's tenant plus whether the daemon partitioned that caller's session names. Nothing about it is serialized: no request header is read that was not read before, no response field is added, and a refusal keeps the same 401 {ok:false,error,code} REST body sendRestJsonError already sent. What it enables is a refusal DROPPED, never one added \u2014 an unattested (client-declared) tenant no longer has the : prefix rule applied to it, because scopeRequestSession never applied that prefix to its sessions either. A released peer that now gets 200 where it got 401 is getting the ndjson record it asked for and already parses." + "rationale": "#2198 context: adds one optional field to the value this DAEMON-INTERNAL gate hands its own route handlers — sessionNamespace, the caller's tenant plus whether the daemon partitioned that caller's session names. Nothing about it is serialized: no request header is read that was not read before, no response field is added, and a refusal keeps the same 401 {ok:false,error,code} REST body sendRestJsonError already sent. What it enables is a refusal DROPPED, never one added — an unattested (client-declared) tenant no longer has the : prefix rule applied to it, because scopeRequestSession never applied that prefix to its sessions either. A released peer that now gets 200 where it got 401 is getting the ndjson record it asked for and already parses." }, { "declaration": "packages/daemon/src/server/request-diagnostics-http.ts#RequestDiagnosticsHttpAuthorizer",