diff --git a/docs/adr/0016-active-session-script-publication.md b/docs/adr/0016-active-session-script-publication.md index 9e448469ad..547b37f080 100644 --- a/docs/adr/0016-active-session-script-publication.md +++ b/docs/adr/0016-active-session-script-publication.md @@ -204,12 +204,14 @@ 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. 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. 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..57e081d38c 100644 --- a/packages/command-registry/src/batch-policy.ts +++ b/packages/command-registry/src/batch-policy.ts @@ -1,6 +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/input-validation'; /** * The exact set of command names exposed through `batch`, as a narrow union. @@ -71,10 +72,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/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/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/contracts/src/facades/command.ts b/packages/contracts/src/facades/command.ts index f7b42f682c..d33d9d71ef 100644 --- a/packages/contracts/src/facades/command.ts +++ b/packages/contracts/src/facades/command.ts @@ -15,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-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/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..1bb6c97b0a --- /dev/null +++ b/packages/daemon/src/core/__tests__/request-script-delivery-ledger.test.ts @@ -0,0 +1,388 @@ +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('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) => { + 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-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/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/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/daemon/src/server/request-router.ts b/packages/daemon/src/server/request-router.ts index 899038a363..36ef848926 100644 --- a/packages/daemon/src/server/request-router.ts +++ b/packages/daemon/src/server/request-router.ts @@ -205,7 +205,11 @@ export function createRequestHandler(deps: RequestRouterDeps): DaemonInvokeFn { meta: { ...req.meta, requestId: resolveRequestTrackingId(req.meta?.requestId) }, }; } - return await reportEndedLeases(req, handleRequestOnLedger); + 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), + ); } 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..88ebed959b 100644 --- a/packages/kernel/src/contracts.ts +++ b/packages/kernel/src/contracts.ts @@ -245,6 +245,97 @@ 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 && !isReceiptClose(close)) 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() }), + }; +} + +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. + */ +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..1ec7c63363 --- /dev/null +++ b/packages/remote/src/__tests__/daemon-artifacts-script-receipt.test.ts @@ -0,0 +1,672 @@ +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: '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'); + 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); +}); + +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) => { + 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/daemon-artifacts.ts b/packages/remote/src/daemon-artifacts.ts index 9cd3662efe..634dc73a4a 100644 --- a/packages/remote/src/daemon-artifacts.ts +++ b/packages/remote/src/daemon-artifacts.ts @@ -462,6 +462,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 (args[2].details?.scriptDeliveryReceipt === undefined) 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 +500,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 && + 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 552e455650..078c8614e7 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/input-validation'; 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,92 @@ 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 ?? [])]; + for (const failure of failures) disclose(failure, undefined); + 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 }; + } + 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 +186,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 +217,121 @@ 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. 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, + req: DaemonWireRequest, + error: DaemonError, + stateDir: string, + download: typeof downloadRemoteArtifact, +): 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); + const honored = + receipt.close === undefined || (failedStep !== undefined && receipt.close.step < failedStep); + const data: Record = { ...(error.details ?? {}) }; + const settled = await settleScriptReceipt( + { endpoint, req, stateDir, download }, + honored ? receipt : withoutClose(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 } }; +} + +/** 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; + 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 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/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); -}); 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. 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) => { diff --git a/test/wire-compat/ledger.json b/test/wire-compat/ledger.json index bdabba0ca5..fd2951b454 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", @@ -240,11 +240,6 @@ "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", @@ -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", diff --git a/website/docs/docs/remote-proxy.md b/website/docs/docs/remote-proxy.md index 44cd873478..e9c452a5e4 100644 --- a/website/docs/docs/remote-proxy.md +++ b/website/docs/docs/remote-proxy.md @@ -122,13 +122,19 @@ 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 -`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` @@ -360,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 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`.