From f654964c868d45824aebefd33dc3668c0d2b460e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Mon, 16 Nov 2026 10:05:00 +0100 Subject: [PATCH 1/5] feat(remote): surface a script delivery failure on every caller surface An action that records a remote script version keeps its success when that version cannot reach the caller file, so the caller needs one field that says the file is stale. `readScriptDeliveryFailure` reads it from a response, and every result that can carry a script version now spreads it beside the warning: the SDK open, close, snapshot and screenshot results, the CLI human output and `--json`, and the MCP tool text and structured content. A batch delivers the script versions its own steps record. Each step is published through the session-script owner under its own command name, in step order, so a step that closes the recording retires the caller record the way a standalone close does, and a step that only records a version leaves the record open for the next one. The destination still comes only from the record this client's own `open --save-script` wrote, so a response never chooses a path, and a step script of another publication still writes nothing. That retires the `remote_script_batch_close_unsupported` refusal, which existed only because a batch delivered nothing. Co-Authored-By: Claude Opus 5.5 --- .../0016-active-session-script-publication.md | 4 +- packages/client/src/client-normalizers.ts | 29 +- packages/client/src/index.ts | 8 +- packages/client/src/screenshot-result.ts | 5 + .../src/output/result-serialization.ts | 24 +- packages/contracts/src/client-app.ts | 18 +- packages/contracts/src/client-capture.ts | 11 + packages/contracts/src/client-session.ts | 8 + ...sion-script-publication-capability.test.ts | 18 -- .../session-script-publication-capability.ts | 5 - .../handlers/__tests__/session-batch.test.ts | 54 ++-- .../handlers/__tests__/session.test.ts | 13 +- .../src/sessions/handlers/session-batch.ts | 15 - .../daemon/src/sessions/handlers/session.ts | 9 +- packages/kernel/src/contracts.ts | 23 ++ .../daemon-artifacts-batch-script.test.ts | 277 ++++++++++++++++++ packages/remote/src/daemon-artifacts.ts | 17 ++ .../src/remote-batch-script-delivery.ts | 129 ++++++++ scripts/layering/architecture-ownership.ts | 1 - src/cli/commands/screenshot.ts | 9 +- .../remote-script-publication.test.ts | 245 +++++++++++++++- test/wire-compat/closure-policy.ts | 2 + test/wire-compat/ledger.json | 8 +- test/wire-compat/surface.ts | 1 + website/docs/docs/remote-proxy.md | 11 +- website/docs/docs/replay-e2e.md | 2 +- 26 files changed, 843 insertions(+), 103 deletions(-) delete mode 100644 packages/daemon/src/core/__tests__/session-script-publication-capability.test.ts create mode 100644 packages/remote/src/__tests__/daemon-artifacts-batch-script.test.ts create mode 100644 packages/remote/src/remote-batch-script-delivery.ts diff --git a/docs/adr/0016-active-session-script-publication.md b/docs/adr/0016-active-session-script-publication.md index a7f4c2937b..9185be3fab 100644 --- a/docs/adr/0016-active-session-script-publication.md +++ b/docs/adr/0016-active-session-script-publication.md @@ -204,11 +204,11 @@ 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 delivers the script versions its steps record, in step order, and a batch step that closes the recording retires the caller record like a standalone close does. - The daemon reports the `script-artifacts` capability in `/health`, through a proxy in its upstream health; the client refuses a remote `--save-script` before dispatch without it. The destination keeps local `--save-script` semantics: the client creates a missing parent directory and checks no ancestor ownership, so another local user who can write an ancestor directory can redirect the file, locally and remotely alike (#4565). -Known limitation (#4564): the RPC response is the contract for `scriptDeliveryFailure`; the SDK, CLI, and MCP results do not carry it yet, the SDK close drops its warnings, and a batch delivers no step script versions. +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. 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/client/src/client-normalizers.ts b/packages/client/src/client-normalizers.ts index 52b3439fda..65afa866e1 100644 --- a/packages/client/src/client-normalizers.ts +++ b/packages/client/src/client-normalizers.ts @@ -24,7 +24,13 @@ import { isSerialAddressablePlatform, type AppleOS, } from '@agent-device/kernel/device'; -import { isSessionRuntimePlatform, type SessionRuntimeHints } from '@agent-device/kernel/contracts'; +import { + isSessionRuntimePlatform, + readScriptDeliveryFailure, + type ScriptDeliveryFailure, + type SessionRuntimeHints, +} from '@agent-device/kernel/contracts'; +import { readResponseWarnings } from '@agent-device/kernel/success-text'; import { AppError, type DaemonError } from '@agent-device/kernel/errors'; import { sanitizeErrorCause } from '@agent-device/kernel/redaction'; import type { SnapshotNode } from '@agent-device/kernel/snapshot'; @@ -486,3 +492,24 @@ export function buildMeta(options: InternalRequestOptions): DaemonWireRequest['m export function resolveSessionName(session: string | undefined): string { return session ?? DEFAULT_SESSION_NAME; } + +/** + * The disclosure fields a successful action carries when a remote recording's script version did not + * reach its caller file (ADR 0016, #4564). + * + * A script delivery failure never changes the outcome of the action that recorded the version, so + * the response stays successful and these two fields are the only channel that says the file is + * stale. Every SDK result that can carry a script version reads them through this one owner, so no + * surface can drop the disclosure while another keeps it. + */ +export function readScriptDeliveryDisclosure(data: Record): { + warnings?: string[]; + scriptDeliveryFailure?: ScriptDeliveryFailure; +} { + const warnings = readResponseWarnings(data); + const scriptDeliveryFailure = readScriptDeliveryFailure(data); + return { + ...(warnings.length > 0 ? { warnings } : {}), + ...(scriptDeliveryFailure === undefined ? {} : { scriptDeliveryFailure }), + }; +} diff --git a/packages/client/src/index.ts b/packages/client/src/index.ts index f9be775e68..50ee2b6cfa 100644 --- a/packages/client/src/index.ts +++ b/packages/client/src/index.ts @@ -49,6 +49,7 @@ import { normalizeTargetShutdownResult, readOptionalString, readRequiredString, + readScriptDeliveryDisclosure, readSnapshotNodes, resolveSessionName, } from './client-normalizers.ts'; @@ -70,7 +71,6 @@ import { readSnapshotKeyboardBandFact, } from '@agent-device/kernel/record'; import { readSnapshotViewportSize } from '@agent-device/kernel/rect'; -import { readResponseWarnings } from '@agent-device/kernel/success-text'; import { captureHostEnvironment } from '@agent-device/host-kit/process'; import type { HostEnvironment } from '@agent-device/kernel/source-value'; import { createLeaseClient } from './lease-client.ts'; @@ -273,6 +273,7 @@ export function createAgentDeviceClient( shutdown: normalizeTargetShutdownResult(data.shutdown), provider: asOptionalRecord(data.provider), savedScript: readOptionalString(data, 'savedScript'), + ...readScriptDeliveryDisclosure(data), identifiers: { session }, }; } finally { @@ -345,10 +346,9 @@ export function createAgentDeviceClient( const device = normalizeOpenDevice(data); const appBundleId = readOptionalString(data, 'appBundleId'); const appId = appBundleId; - const warnings = readResponseWarnings(data); return { session, - ...(warnings.length > 0 ? { warnings } : {}), + ...readScriptDeliveryDisclosure(data), sessionStateDir: readOptionalString(data, 'sessionStateDir'), runnerLogPath: readOptionalString(data, 'runnerLogPath'), requestLogPath: readOptionalString(data, 'requestLogPath'), @@ -381,6 +381,7 @@ export function createAgentDeviceClient( closedApp: options.app, shutdown: normalizeTargetShutdownResult(data.shutdown), savedScript: readOptionalString(data, 'savedScript'), + ...readScriptDeliveryDisclosure(data), identifiers: { session }, }; }, @@ -614,6 +615,7 @@ function optionalSnapshotResponseFields( ...readSerializedSnapshotCaptureAnnotations(data), ...(unchanged ? { unchanged: unchanged as CaptureSnapshotResult['unchanged'] } : {}), ...(snapshotDiagnostics ? { snapshotDiagnostics } : {}), + ...readScriptDeliveryDisclosure(data), ...(typeof data.fallbackScreenshotPath === 'string' ? { fallbackScreenshotPath: data.fallbackScreenshotPath } : {}), diff --git a/packages/client/src/screenshot-result.ts b/packages/client/src/screenshot-result.ts index 210c685066..d49a9fa86c 100644 --- a/packages/client/src/screenshot-result.ts +++ b/packages/client/src/screenshot-result.ts @@ -1,6 +1,7 @@ import type { ScreenshotResultData } from '@agent-device/contracts/capture'; import type { CaptureScreenshotResult } from '@agent-device/contracts/client'; import { isDeviceRotation } from '@agent-device/contracts/device'; +import { readScriptDeliveryDisclosure } from './client-normalizers.ts'; import { isRecord, parsePoint, parseRect, readRequiredString } from '@agent-device/kernel/record'; import { readResponseWarnings } from '@agent-device/kernel/success-text'; import type { ScreenshotOverlayRef } from '@agent-device/kernel/snapshot'; @@ -25,6 +26,7 @@ export function normalizeScreenshotCaptureResult( session: string, ): CaptureScreenshotResult { const screenshot = readScreenshotResultData(data); + const { scriptDeliveryFailure } = readScriptDeliveryDisclosure(data); return { path: readRequiredString(data, 'path'), width: screenshot?.width, @@ -34,7 +36,10 @@ export function normalizeScreenshotCaptureResult( pixelDensity: screenshot?.pixelDensity, ...(screenshot?.displayRotation ? { displayRotation: screenshot.displayRotation } : {}), overlayRefs: screenshot?.overlayRefs, + // `screenshot.warnings` is read from this same response, so it already carries the warning a + // failed script delivery adds. Only the typed field needs adding here. ...(screenshot?.warnings ? { warnings: screenshot.warnings } : {}), + ...(scriptDeliveryFailure ? { scriptDeliveryFailure } : {}), identifiers: { session }, }; } diff --git a/packages/command-output/src/output/result-serialization.ts b/packages/command-output/src/output/result-serialization.ts index cc7d5e1fba..f02655b7ac 100644 --- a/packages/command-output/src/output/result-serialization.ts +++ b/packages/command-output/src/output/result-serialization.ts @@ -10,6 +10,7 @@ import type { SessionCloseResult, } from '@agent-device/contracts/client'; import type { CloudArtifactsResult } from '@agent-device/contracts/observability'; +import type { ScriptDeliveryFailure } from '@agent-device/kernel/contracts'; import { publicSnapshotCaptureAnnotations } from '@agent-device/contracts/capture'; import { isSerialAddressablePlatform } from '@agent-device/kernel/device'; import { successText, withSuccessText } from '@agent-device/kernel/success-text'; @@ -92,6 +93,9 @@ export function serializeSnapshotResult(result: CaptureSnapshotResult): Record { + return { + ...(result.warnings?.length ? { warnings: result.warnings } : {}), + ...(result.scriptDeliveryFailure + ? { scriptDeliveryFailure: result.scriptDeliveryFailure } + : {}), + }; +} + export function serializeCloseResult( result: SessionCloseResult | AppCloseResult, ): Record { @@ -179,6 +200,7 @@ export function serializeCloseResult( session: result.session, ...(result.shutdown ? { shutdown: result.shutdown } : {}), ...('provider' in result && result.provider ? { provider: result.provider } : {}), + ...serializeScriptDeliveryDisclosure(result), ...successText( [ result.session ? `Closed: ${result.session}` : 'Closed', diff --git a/packages/contracts/src/client-app.ts b/packages/contracts/src/client-app.ts index a462387ed7..9a2ca879d2 100644 --- a/packages/contracts/src/client-app.ts +++ b/packages/contracts/src/client-app.ts @@ -8,7 +8,11 @@ import type { import type { JsonObject } from './json.ts'; import type { SessionSurface } from './session-surface.ts'; import type { TargetShutdownResult } from './target-shutdown-contract.ts'; -import type { DaemonInstallSource, SessionRuntimeHints } from '@agent-device/kernel/contracts'; +import type { + DaemonInstallSource, + ScriptDeliveryFailure, + SessionRuntimeHints, +} from '@agent-device/kernel/contracts'; import type { DaemonError } from '@agent-device/kernel/errors'; import type { PublicPlatform } from '@agent-device/kernel/device'; import type { @@ -113,6 +117,11 @@ export type AppOpenResult = AppOpenResultBase & type AppOpenResultBase = { session: string; warnings?: string[]; + /** + * ADR 0016 (#4564): a remote recording's first script version was not delivered. The open kept + * its success, so the caller file may hold no script at all, or an older one. + */ + scriptDeliveryFailure?: ScriptDeliveryFailure; sessionStateDir?: string; runnerLogPath?: string; requestLogPath?: string; @@ -161,6 +170,13 @@ export type AppCloseResult = { * — so a client that requested publication learns where the file landed. */ savedScript?: string; + /** ADR 0016 (#4564): the close's response warnings, kept so a lost final script is read, not skipped. */ + warnings?: string[]; + /** + * ADR 0016 (#4564): the final script of a remote recording was not delivered. The close kept its + * success, so this is the only channel that says the caller file still holds an older version. + */ + scriptDeliveryFailure?: ScriptDeliveryFailure; identifiers: AgentDeviceIdentifiers; }; diff --git a/packages/contracts/src/client-capture.ts b/packages/contracts/src/client-capture.ts index 1afdf01cf2..db9f48ad04 100644 --- a/packages/contracts/src/client-capture.ts +++ b/packages/contracts/src/client-capture.ts @@ -13,6 +13,7 @@ import type { SnapshotViewportSize, SnapshotVisibility, } from '@agent-device/kernel/snapshot'; +import type { ScriptDeliveryFailure } from '@agent-device/kernel/contracts'; import type { ScreenshotResultData } from './snapshot-types.ts'; import type { PostGestureOutcome } from './snapshot-model.ts'; import type { @@ -108,6 +109,11 @@ export type CaptureSnapshotResult = { * default-level `nodes` payload is intentionally omitted. */ refs?: Array<{ ref: string; label?: string }>; + /** + * ADR 0016 (#4564): a remote recording's script version this capture recorded was not delivered. + * The capture kept its success, so the caller file may hold an older version. + */ + scriptDeliveryFailure?: ScriptDeliveryFailure; } & PublicSnapshotCaptureAnnotations; export type CaptureScreenshotOptions = AgentDeviceRequestOverrides & { @@ -128,6 +134,11 @@ export type CaptureScreenshotOptions = AgentDeviceRequestOverrides & { export type CaptureScreenshotResult = ScreenshotResultData & { path: string; + /** + * ADR 0016 (#4564): a remote recording's script version this capture recorded was not delivered. + * The capture kept its success, so the caller file may hold an older version. + */ + scriptDeliveryFailure?: ScriptDeliveryFailure; identifiers: AgentDeviceIdentifiers; }; diff --git a/packages/contracts/src/client-session.ts b/packages/contracts/src/client-session.ts index 22e2e91be2..c44d143c56 100644 --- a/packages/contracts/src/client-session.ts +++ b/packages/contracts/src/client-session.ts @@ -3,6 +3,7 @@ import type { CloudProviderSessionResult } from './cloud-artifacts.ts'; import type { TargetShutdownResult } from './target-shutdown-contract.ts'; import type { AgentDeviceIdentifiers, AgentDeviceRequestOverrides } from './client-connection.ts'; +import type { ScriptDeliveryFailure } from '@agent-device/kernel/contracts'; export type SessionCloseResult = { session: string; @@ -14,6 +15,13 @@ export type SessionCloseResult = { * — so a client that requested publication learns where the file landed. */ savedScript?: string; + /** ADR 0016 (#4564): the close's response warnings, kept so a lost final script is read, not skipped. */ + warnings?: string[]; + /** + * ADR 0016 (#4564): the final script of a remote recording was not delivered. The close kept its + * success, so this is the only channel that says the caller file still holds an older version. + */ + scriptDeliveryFailure?: ScriptDeliveryFailure; identifiers: AgentDeviceIdentifiers; }; 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/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/sessions/handlers/__tests__/session-batch.test.ts b/packages/daemon/src/sessions/handlers/__tests__/session-batch.test.ts index 952e1bf521..57d2f8eb03 100644 --- a/packages/daemon/src/sessions/handlers/__tests__/session-batch.test.ts +++ b/packages/daemon/src/sessions/handlers/__tests__/session-batch.test.ts @@ -12,47 +12,43 @@ function batch(...commands: string[]): DaemonRequest { }; } -const refused = { - ok: false, - error: expect.objectContaining({ - code: 'INVALID_ARGS', - details: expect.objectContaining({ reason: 'remote_script_batch_close_unsupported' }), - }), -}; +test('a batch runs its steps in order and answers with one entry per step', async () => { + const invoke = vi.fn(async (req: DaemonRequest) => ({ + ok: true as const, + data: { step: req.command }, + })); + + const response = await runBatchCommands(batch('wait', 'close'), 'journey', invoke); + + expect(response).toMatchObject({ + ok: true, + data: { + results: [ + { command: 'wait', data: { step: 'wait' } }, + { command: 'close', data: { step: 'close' } }, + ], + }, + }); +}); test.each([ { name: 'close', close: 'close' }, { name: 'a close spelled differently', close: ' CLOSE ' }, -])('a batch with $name in an armed remote recording runs no step', async ({ close }) => { - const invoke = vi.fn(async () => ({ ok: true as const, data: {} })); - - await expect(runBatchCommands(batch('wait', close), 'journey', invoke, true)).resolves.toEqual( - refused, - ); - expect(invoke).not.toHaveBeenCalled(); -}); +])('a batch with $name closes the session it runs in', async ({ close }) => { + const invoke = vi.fn(async (_step: DaemonRequest) => ({ ok: true as const, data: {} })); -test.each([ - { name: 'a remote recording batch without close', commands: ['wait'], remote: true }, - { - name: 'a batch with close outside a remote recording', - commands: ['wait', 'close'], - remote: false, - }, -])('$name runs its steps', async ({ commands, remote }) => { - const invoke = vi.fn(async () => ({ ok: true as const, data: {} })); + await runBatchCommands(batch('wait', close), 'journey', invoke); - await runBatchCommands(batch(...commands), 'journey', invoke, remote); - - expect(invoke).toHaveBeenCalledTimes(commands.length); + expect(invoke.mock.calls.map(([step]) => step.command)).toEqual(['wait', 'close']); }); -test('malformed steps fail batch validation before the close check', async () => { +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..cd5ea20493 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 runs a batch that closes a remote recording', async () => { + // Closing the recording from a batch is supported: the step's own answer carries the final + // script, so the router must not stand between the caller and its terminal step. const sessionStore = makeSessionStore('agent-device-batch-route-'); sessionStore.publish( 'journey', @@ -54,7 +56,7 @@ test('the session router refuses a batch that would close an armed remote record scriptPublication: authoringPublication('armed', { remote: true }), }), ); - const invoke = vi.fn(async () => ({ ok: true as const, data: {} })); + const invoke = vi.fn(async (_step: DaemonRequest) => ({ ok: true as const, data: {} })); const response = await handleSessionCommands({ host: createTestHostEnvironment(), @@ -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.mock.calls.map(([step]) => step.command)).toEqual(['wait', 'close']); }); diff --git a/packages/daemon/src/sessions/handlers/session-batch.ts b/packages/daemon/src/sessions/handlers/session-batch.ts index e964d3a500..d6407d6575 100644 --- a/packages/daemon/src/sessions/handlers/session-batch.ts +++ b/packages/daemon/src/sessions/handlers/session-batch.ts @@ -1,5 +1,4 @@ import type { DaemonResponse } from '@agent-device/kernel/contracts'; -import { AppError } from '@agent-device/kernel/errors'; import { runBatch } from '@agent-device/command-registry/batch'; import type { DaemonInvokeFn, DaemonRequest } from '../../core/daemon-request.ts'; @@ -7,23 +6,9 @@ export async function runBatchCommands( req: DaemonRequest, sessionName: string, invoke: DaemonInvokeFn, - armedRemoteRecording = false, ): Promise { return await runBatch(req, sessionName, async (stepRequest, context) => { const step = stepRequest as DaemonRequest; - // ADR 0016: a batch delivers no script versions from its steps, so a step that closes an armed - // remote recording would lose the final script. The normalized steps are checked before the - // first one runs. - if ( - armedRemoteRecording && - context.stepNumber === 1 && - [step, ...context.remainingSteps].some((planned) => planned.command === 'close') - ) { - throw new AppError('INVALID_ARGS', 'A batch cannot close a remote script recording.', { - reason: 'remote_script_batch_close_unsupported', - hint: 'Run close on its own after the batch, so the final script reaches the --save-script file.', - }); - } return await invoke({ ...step, internal: { diff --git a/packages/daemon/src/sessions/handlers/session.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 9aa591d1dc..c352cdeaa4 100644 --- a/packages/kernel/src/contracts.ts +++ b/packages/kernel/src/contracts.ts @@ -222,6 +222,29 @@ export type ScriptDeliveryFailure = { cause?: string; }; +/** + * Reads a response's `scriptDeliveryFailure` (ADR 0016). A response that carries no such record, or + * one the field contract does not describe, answers `undefined`: no surface acts on a half-shaped + * failure, and every surface that shows one shows it through this reader. + */ +export function readScriptDeliveryFailure( + data: Record | undefined, +): ScriptDeliveryFailure | undefined { + const failure = data?.scriptDeliveryFailure; + if (!failure || typeof failure !== 'object' || Array.isArray(failure)) return undefined; + const { reason, publicationId, message, hint, cause } = failure as Partial; + if ( + reason !== 'script_delivery_failed' || + typeof publicationId !== 'string' || + typeof message !== 'string' || + typeof hint !== 'string' || + (cause !== undefined && typeof cause !== 'string') + ) { + return undefined; + } + return { reason, publicationId, message, hint, ...(cause === undefined ? {} : { cause }) }; +} + 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-batch-script.test.ts b/packages/remote/src/__tests__/daemon-artifacts-batch-script.test.ts new file mode 100644 index 0000000000..0015f039fb --- /dev/null +++ b/packages/remote/src/__tests__/daemon-artifacts-batch-script.test.ts @@ -0,0 +1,277 @@ +import fs from 'node:fs'; +import http from 'node:http'; +import path from 'node:path'; +import { afterEach, expect, test } from 'vitest'; +import type { 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'; + +const servers: http.Server[] = []; + +afterEach(async () => { + await Promise.all(servers.splice(0).map((server) => closeLoopbackServer(server))); +}); + +/** + * Serves the script versions it is given. An artifact ID it does not know answers 503, which is how + * these tests make one step's download fail. + */ +async function artifactServer(bodies: Record): Promise { + const server = http.createServer((req, res) => { + const id = decodeURIComponent(req.url?.replace('/artifacts/', '') ?? ''); + const body = bodies[id]; + if (body === undefined) { + res.writeHead(503).end('unavailable'); + return; + } + res.writeHead(200, { 'content-length': Buffer.byteLength(body) }); + res.end(body); + }); + servers.push(server); + return `http://127.0.0.1:${await listenOnLoopback(server)}`; +} + +function journey() { + // The real path, so a destination names the same file the publication renames into place. + const root = fs.realpathSync(mkdtempForTestSync('batch-script-')); + return { root, stateDir: path.join(root, 'state'), destination: path.join(root, 'journey.ad') }; +} + +function request(command: string, meta: DaemonWireRequest['meta'] = {}): DaemonWireRequest { + return { token: 't', session: 'journey', command, positionals: [], meta }; +} + +function script(artifactId: string, revision: number, publicationId: string): DaemonArtifact { + return { + field: 'savedScript', + artifactType: 'session-script', + artifactId, + scriptPublicationId: publicationId, + scriptRevision: revision, + }; +} + +function records(stateDir: string): string[] { + const directory = path.join(stateDir, 'remote-connections', 'session-scripts'); + return fs.existsSync(directory) + ? fs.readdirSync(directory).filter((n) => n.endsWith('.json')) + : []; +} + +/** Answers a request the way the daemon does and materializes the answer like the client. */ +function answer( + baseUrl: string, + stateDir: string, + req: DaemonWireRequest, + data: Record, +): Promise { + return materializeRemoteArtifacts( + { baseUrl, token: 't' }, + req, + { ok: true, data }, + createTestHostEnvironment(), + stateDir, + ); +} + +/** One batch step result, shaped the way the daemon runner answers. */ +function step(step: number, command: string, data: Record) { + return { step, command, ok: true, data, durationMs: 1 }; +} + +/** A remote `open --save-script` the daemon answered with version 1. */ +async function open(baseUrl: string, stateDir: string, destination: string) { + let publicationId = ''; + await sendRemoteScriptOpen( + { baseUrl, token: 't', capabilities: ['script-artifacts'] }, + { + ...request('open', { clientArtifactPaths: { savedScript: destination } }), + flags: { saveScript: true }, + }, + stateDir, + async (next) => { + publicationId = next.meta?.scriptPublicationId as string; + return await answer(baseUrl, stateDir, next, { + scriptPublicationId: publicationId, + artifacts: [script('v1', 1, publicationId)], + }); + }, + ); + return publicationId; +} + +/** The step results of a successful batch answer. */ +function batchSteps(response: DaemonResponse): Array> { + if (!response.ok) throw new Error(`Expected a successful batch, got ${JSON.stringify(response)}`); + return (response.data?.results ?? []) as Array>; +} + +test('a batch delivers each step script in step order and a close step retires the record', async () => { + const { stateDir, destination } = journey(); + const baseUrl = await artifactServer({ + v1: 'open Demo\n', + v2: 'open Demo\nwait 100\n', + v3: 'open Demo\nwait 100\nclose\n', + }); + const id = await open(baseUrl, stateDir, destination); + expect(records(stateDir)).toHaveLength(1); + + const response = await answer(baseUrl, stateDir, request('batch'), { + total: 2, + executed: 2, + totalDurationMs: 5, + results: [ + step(1, 'wait', { waited: true, artifacts: [script('v2', 2, id)] }), + step(2, 'close', { scriptPublicationId: id, artifacts: [script('v3', 3, id)] }), + ], + }); + + expect(fs.readFileSync(destination, 'utf8')).toBe('open Demo\nwait 100\nclose\n'); + // The terminal step retired the record, so no later version of that publication writes anything. + expect(records(stateDir)).toEqual([]); + // Each step reports its own version the way the same command alone would: its `savedScript` names + // the caller file, and its artifact carries the local path the client published. + const steps = batchSteps(response); + expect(steps.map((result) => result.command)).toEqual(['wait', 'close']); + expect(steps.map((result) => result.data.savedScript)).toEqual([destination, destination]); + expect(steps.map((result) => result.data.artifacts)).toEqual([ + [ + expect.objectContaining({ + artifactId: 'v2', + scriptRevision: 2, + localPath: destination, + }), + ], + [ + expect.objectContaining({ + artifactId: 'v3', + scriptRevision: 3, + localPath: destination, + }), + ], + ]); +}); + +test('a batch step whose download fails discloses the failure on that step and keeps the batch', async () => { + const { stateDir, destination } = journey(); + const baseUrl = await artifactServer({ v1: 'open Demo\n' }); + const id = await open(baseUrl, stateDir, destination); + + const response = await answer(baseUrl, stateDir, request('batch'), { + total: 1, + executed: 1, + totalDurationMs: 1, + results: [step(1, 'wait', { waited: true, artifacts: [script('gone', 2, id)] })], + }); + + // The step ran on the device, so the batch stands and the step says the caller file is stale. + expect(response.ok).toBe(true); + expect(batchSteps(response)[0]).toEqual({ + step: 1, + command: 'wait', + ok: true, + durationMs: 1, + data: expect.objectContaining({ + waited: true, + artifacts: [], + scriptDeliveryFailure: expect.objectContaining({ + reason: 'script_delivery_failed', + cause: 'script_download_failed', + publicationId: id, + }), + warnings: [expect.stringContaining('script')], + }), + }); + // A daemon-host path or status never rides along in the disclosure. + expect(JSON.stringify(response)).not.toContain('unavailable'); + expect(fs.readFileSync(destination, 'utf8')).toBe('open Demo\n'); + // The recording is not closed, so the record stays and a later version still lands. + expect(records(stateDir)).toHaveLength(1); + const later = await answer(baseUrl, stateDir, request('close'), { + scriptPublicationId: id, + artifacts: [script('v1', 3, id)], + }); + expect(later.ok).toBe(true); + expect(fs.readFileSync(destination, 'utf8')).toBe('open Demo\n'); + expect(records(stateDir)).toEqual([]); +}); + +test('a batch that closes keeps its success and retires the record when the final download fails', async () => { + const { stateDir, destination } = journey(); + const baseUrl = await artifactServer({ v1: 'open Demo\n' }); + const id = await open(baseUrl, stateDir, destination); + + const response = await answer(baseUrl, stateDir, request('batch'), { + total: 1, + executed: 1, + totalDurationMs: 1, + results: [step(1, 'close', { scriptPublicationId: id, artifacts: [script('gone', 2, id)] })], + }); + + // The session closed, so the record is gone even though the final script did not arrive. + expect(batchSteps(response)[0]?.data).toEqual( + expect.objectContaining({ + scriptDeliveryFailure: expect.objectContaining({ + cause: 'script_download_failed', + publicationId: id, + }), + }), + ); + expect(fs.readFileSync(destination, 'utf8')).toBe('open Demo\n'); + expect(records(stateDir)).toEqual([]); +}); + +test('a batch step script of another publication or of another field writes nothing', async () => { + const { root, stateDir, destination } = journey(); + const baseUrl = await artifactServer({ + v1: 'open Demo\n', + foreign: 'hostile\n', + }); + const id = await open(baseUrl, stateDir, destination); + const victim = path.join(root, 'victim.ad'); + + const response = await answer(baseUrl, stateDir, request('batch'), { + total: 2, + executed: 2, + totalDurationMs: 1, + results: [ + // Another publication's version, and one under a field this owner does not claim. + step(1, 'wait', { + artifacts: [script('foreign', 9, '00000000-0000-4000-8000-000000000000')], + }), + step(2, 'wait', { + artifacts: [{ ...script('foreign', 8, id), field: 'path', fileName: 'victim.ad' }], + }), + ], + }); + + expect(batchSteps(response).map((result) => result.data)).toEqual([ + { artifacts: [] }, + { artifacts: [] }, + ]); + expect(fs.readFileSync(destination, 'utf8')).toBe('open Demo\n'); + expect(fs.existsSync(victim)).toBe(false); +}); + +test('a batch answer with no step scripts is returned untouched', async () => { + const { stateDir, destination } = journey(); + const baseUrl = await artifactServer({ v1: 'open Demo\n' }); + await open(baseUrl, stateDir, destination); + const data = { + total: 1, + executed: 1, + totalDurationMs: 1, + results: [step(1, 'wait', { waited: true })], + }; + + const response = await answer(baseUrl, stateDir, request('batch'), data); + + expect(response).toEqual({ ok: true, data }); +}); diff --git a/packages/remote/src/daemon-artifacts.ts b/packages/remote/src/daemon-artifacts.ts index 9cd3662efe..3a7d5372fe 100644 --- a/packages/remote/src/daemon-artifacts.ts +++ b/packages/remote/src/daemon-artifacts.ts @@ -477,6 +477,20 @@ export async function materializeRemoteArtifacts( if (!info.baseUrl) return response; const endpoint = { baseUrl: info.baseUrl, token: info.token }; const artifacts = Array.isArray(response.data?.artifacts) ? response.data.artifacts : []; + // A batch answers with one entry per step, and a step's own script artifacts sit inside its + // result, so that response is delivered by the step-aware owner. It loads lazily and returns the + // response untouched when no step carries a script. + if (req.command === BATCH_COMMAND) { + const { deliverRemoteBatchScripts } = await import('./remote-batch-script-delivery.ts'); + return await deliverRemoteBatchScripts( + endpoint, + req, + response, + stateDir, + downloadRemoteArtifact, + isSessionScriptArtifact, + ); + } const download = (scripts?: SessionScriptDelivery) => downloadResponseArtifacts(endpoint, req, response, host, scripts); if ( @@ -490,6 +504,9 @@ export async function materializeRemoteArtifacts( return await scripts.settleAfter(download); } +/** Command name of the request that runs several steps under one response. */ +const BATCH_COMMAND = 'batch'; + async function downloadResponseArtifacts( endpoint: Required, req: DaemonWireRequest, diff --git a/packages/remote/src/remote-batch-script-delivery.ts b/packages/remote/src/remote-batch-script-delivery.ts new file mode 100644 index 0000000000..0444293857 --- /dev/null +++ b/packages/remote/src/remote-batch-script-delivery.ts @@ -0,0 +1,129 @@ +import type { DaemonWireRequest } from '@agent-device/contracts/command'; +import type { DaemonArtifact, DaemonResponse } from '@agent-device/kernel/contracts'; +import { isRecord } from '@agent-device/kernel/record'; +import type { downloadRemoteArtifact } from './daemon-artifacts.ts'; +import type { SessionScriptDelivery } from './session-script-destination.ts'; + +/** Command name the runner records for a step whose result carries none. */ +const UNKNOWN_STEP_COMMAND = 'batch'; + +/** + * Delivers the session scripts a `batch` response carries, in step order. + * + * A step's `data` is what that command would have answered on its own, so each step is delivered + * through the session-script owner under its own command name: a step that closes the recording + * retires this client's record, and a step that only records a version leaves the record open for + * the next step. The batch's own payload carries the version the daemon stamped after the last step, + * so it is delivered last under the batch's own command name — after a closing step retired the + * record, which drops that version instead of writing a stale one. The destination still comes only + * from the record this client's own `open --save-script` wrote, never from the response, which names + * artifacts and not paths. + * + * A step that cannot save its version keeps the batch successful and reports the typed failure on + * that step's result, the way the same command does on its own. + */ +export async function deliverRemoteBatchScripts( + endpoint: Readonly<{ baseUrl: string; token: string }>, + req: DaemonWireRequest, + response: Extract, + stateDir: string, + download: typeof downloadRemoteArtifact, + isScriptArtifact: (artifact: DaemonArtifact | undefined) => boolean, +): Promise { + const results = readBatchResults(response.data); + const nextResults: unknown[] = []; + for (const [index, result] of results.entries()) { + const delivered = await deliverScripts(endpoint, req, stateDir, download, isScriptArtifact, { + command: readString(result.command) ?? UNKNOWN_STEP_COMMAND, + // A copy: the session-script owner narrows the payload it is handed, and the daemon's own + // response object stays as it arrived. + data: isRecord(result.data) ? { ...result.data } : undefined, + }); + nextResults.push(delivered === undefined ? results[index] : { ...result, data: delivered }); + } + const data = { ...response.data, ...(results.length > 0 ? { results: nextResults } : {}) }; + // The batch's own payload last: it names the newest revision, and a closing step has already + // retired the record, so a script that arrived after the close is dropped rather than rewritten. + const deliveredPayload = await deliverScripts( + endpoint, + req, + stateDir, + download, + isScriptArtifact, + { + command: req.command, + data, + }, + ); + return { ok: true, data: deliveredPayload ?? data }; +} + +/** + * Delivers one payload's session-script artifacts — a step's result or the batch's own data — or + * answers `undefined` when that payload carries none and the caller reports it as the daemon + * answered it. + * + * The payload keeps the batch request's own endpoint, tenant and session, which is what lets it + * reach the record that armed the recording, and takes the command name of its own, which is what + * makes a terminal `close` retire that record. + */ +async function deliverScripts( + endpoint: Readonly<{ baseUrl: string; token: string }>, + req: DaemonWireRequest, + stateDir: string, + download: typeof downloadRemoteArtifact, + isScriptArtifact: (artifact: DaemonArtifact | undefined) => boolean, + payload: Readonly<{ command: string; data: Record | undefined }>, +): Promise | undefined> { + const data = payload.data; + const artifacts = Array.isArray(data?.artifacts) ? data.artifacts : []; + if (!data || !artifacts.some((artifact) => isScriptArtifact(artifact as DaemonArtifact))) { + return undefined; + } + const { sessionScriptDelivery } = await import('./session-script-destination.ts'); + const scripts = sessionScriptDelivery( + endpoint, + { ...req, command: payload.command }, + { ok: true, data }, + stateDir, + download, + ); + let published = data; + await scripts.settleAfter(async () => { + published = await publishStepArtifacts(scripts, data, isScriptArtifact); + return { ok: true, data: published }; + }); + return published; +} + +/** + * Publishes the session-script artifacts of one payload and keeps every other artifact as the daemon + * answered it. Only the session-script owner owns `savedScript`; a payload's other artifacts are the + * daemon's own outputs, which the daemon already wrote on its side. + */ +async function publishStepArtifacts( + scripts: SessionScriptDelivery, + data: Record, + isScriptArtifact: (artifact: DaemonArtifact | undefined) => boolean, +): Promise> { + const nextData = { ...data }; + const kept: DaemonArtifact[] = []; + for (const artifact of data.artifacts as DaemonArtifact[]) { + if (!isScriptArtifact(artifact)) { + kept.push(artifact); + continue; + } + await scripts.publish(artifact, nextData, kept); + } + nextData.artifacts = kept; + return nextData; +} + +function readBatchResults(data: unknown): ReadonlyArray> { + if (!isRecord(data) || !Array.isArray(data.results)) return []; + return data.results.filter((result): result is Record => isRecord(result)); +} + +function readString(value: unknown): string | undefined { + return typeof value === 'string' && value.length > 0 ? value : undefined; +} 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/src/cli/commands/screenshot.ts b/src/cli/commands/screenshot.ts index ec43610e0e..c1f7b32e85 100644 --- a/src/cli/commands/screenshot.ts +++ b/src/cli/commands/screenshot.ts @@ -33,7 +33,14 @@ export const screenshotCommand: ClientCommandHandler = async ({ await writeCommandOutput(flags, result, () => JSON.stringify(result, null, 2)); return true; } - const data = pickScreenshotResultData(result); + // The disclosure fields (ADR 0016, #4564) sit beside the capture fields on the result, and + // `pickScreenshotResultData` narrows the capture payload for its own callers, so `--json` adds them. + const data = { + ...pickScreenshotResultData(result), + ...(result.scriptDeliveryFailure + ? { scriptDeliveryFailure: result.scriptDeliveryFailure } + : {}), + }; await writeCommandOutput(flags, data, () => { const summary = result.overlayRefs ? `Annotated ${result.overlayRefs.length} refs onto ${result.path}` diff --git a/test/integration/provider-scenarios/remote-script-publication.test.ts b/test/integration/provider-scenarios/remote-script-publication.test.ts index 6172e98640..637c569582 100644 --- a/test/integration/provider-scenarios/remote-script-publication.test.ts +++ b/test/integration/provider-scenarios/remote-script-publication.test.ts @@ -12,6 +12,9 @@ import { assertRpcOk } from './assertions.ts'; import { createAndroidSettingsWorld } from './android-world.ts'; import { withProviderScenarioResource } from './harness.ts'; import { createProviderScenarioProxy } from './harness-proxy.ts'; +import { runCliCapture } from '../../../src/__tests__/cli-capture.ts'; +import { installIsolatedCliTestEnv } from '../../../src/__tests__/cli-test-env.ts'; +import { createCommandToolExecutor } from '../../../src/mcp/command-tools.ts'; /** A script version the daemon writes in its private directory. */ function isDaemonScriptPath(file: fs.PathLike): boolean { @@ -255,7 +258,7 @@ test('a failed final write keeps the close and the client forgets the recording' return realLinkSync(existing, target); }); - await client.sessions.close(); + const closeResult = await client.sessions.close(); const reply = proxy.forwarded.filter((r) => r.route === '/rpc').at(-1); assert.ok(reply); @@ -268,6 +271,15 @@ test('a failed final write keeps the close and the client forgets the recording' warning.includes(closed.data.scriptDeliveryFailure.hint), ), ); + // The SDK result carries the same typed failure and warning the wire answers, so a caller that + // never reads stdout sees the stale file. + assert.deepEqual(closeResult.scriptDeliveryFailure, closed.data.scriptDeliveryFailure); + assert.ok( + closeResult.warnings?.some((warning) => + warning.includes(closed.data.scriptDeliveryFailure.hint), + ), + JSON.stringify(closeResult.warnings), + ); assert.equal(fs.readFileSync(destination, 'utf8'), opened); const records = path.join(stateDir, 'remote-connections', 'session-scripts'); assert.deepEqual( @@ -438,3 +450,234 @@ test('close delivers the final script after it stops an app log', async () => { } }); }, 20_000); + +/** + * The caller surfaces a remote recording reads (#4564): an action whose script version did not + * arrive stays successful, so the SDK result, the CLI output and the MCP tool result are the only + * channels that say the caller file is stale. One gate refuses the artifact downloads of one + * surface's close at a time, so each surface answers its own failing delivery. + */ +test('the SDK, the CLI and MCP each disclose a failed final script delivery', async () => { + await withProviderScenarioResource(createAndroidSettingsWorld, async (world) => { + const root = mkdtempForTestSync('remote-script-surfaces-'); + const proxy = await createProviderScenarioProxy(world.daemon, { clientToken: 'script-client' }); + const upstream = new URL(proxy.baseUrl); + let refuseArtifacts = false; + const gate = http.createServer((req, res) => { + if (refuseArtifacts && req.url?.includes('/artifacts/')) { + res.writeHead(503).end('unavailable'); + return; + } + const forwarded = http.request( + { + host: upstream.hostname, + port: upstream.port, + method: req.method, + path: req.url, + headers: req.headers, + }, + (reply) => { + res.writeHead(reply.statusCode ?? 502, reply.headers); + reply.pipe(res); + }, + ); + forwarded.on('error', () => res.destroy()); + req.pipe(forwarded); + }); + const gateUrl = `http://127.0.0.1:${await listenOnLoopback(gate)}${upstream.pathname}`; + const remoteEnv = { + AGENT_DEVICE_DAEMON_BASE_URL: gateUrl, + AGENT_DEVICE_DAEMON_AUTH_TOKEN: 'script-client', + AGENT_DEVICE_DAEMON_TRANSPORT: 'http', + }; + const recordFiles = (stateDir: string) => + fs + .readdirSync(path.join(stateDir, 'remote-connections', 'session-scripts'), { + withFileTypes: true, + }) + .filter((entry) => entry.isFile() && entry.name.endsWith('.json')) + .map((entry) => entry.name); + try { + // The SDK: the typed failure and the warning ride the close result itself. + const sdkStateDir = path.join(root, 'sdk-state'); + const sdkFile = path.join(root, 'sdk.ad'); + const sdk = createAgentDeviceClient({ + daemonBaseUrl: gateUrl, + daemonAuthToken: 'script-client', + session: 'sdk-surfaces', + stateDir: sdkStateDir, + }); + await sdk.apps.open({ app: 'settings', saveScript: sdkFile, ...world.selection }); + refuseArtifacts = true; + const sdkClose = await sdk.sessions.close(); + refuseArtifacts = false; + assert.equal(sdkClose.scriptDeliveryFailure?.reason, 'script_delivery_failed'); + assert.ok( + sdkClose.warnings?.some((warning) => + warning.includes(sdkClose.scriptDeliveryFailure!.hint), + ), + JSON.stringify(sdkClose.warnings), + ); + assert.doesNotMatch(fs.readFileSync(sdkFile, 'utf8'), /^close/m); + assert.deepEqual(recordFiles(sdkStateDir), []); + + // The CLI with `--json`: an agent reading machine output gets the typed field. + const jsonStateDir = path.join(root, 'cli-json-state'); + const jsonFile = path.join(root, 'cli-json.ad'); + const cli = (argv: string[], stateDir: string) => + runCliCapture(argv, { + cwd: root, + env: { ...remoteEnv, AGENT_DEVICE_STATE_DIR: stateDir }, + useRealDaemonClient: true, + }); + const jsonOpen = await cli( + [ + 'open', + 'settings', + '--json', + '--session', + 'cli-json', + '--save-script', + jsonFile, + '--platform', + world.selection.platform, + '--serial', + world.selection.serial, + ], + jsonStateDir, + ); + assert.equal(jsonOpen.code, null, jsonOpen.stderr); + refuseArtifacts = true; + const jsonClose = await cli(['close', '--json', '--session', 'cli-json'], jsonStateDir); + refuseArtifacts = false; + assert.equal(jsonClose.code, null, jsonClose.stderr); + const jsonPayload = JSON.parse(jsonClose.stdout); + assert.equal(jsonPayload.success, true, jsonClose.stdout); + assert.equal(jsonPayload.data.scriptDeliveryFailure.reason, 'script_delivery_failed'); + assert.ok( + Array.isArray(jsonPayload.data.warnings) && + jsonPayload.data.warnings.some((warning: string) => + warning.includes(jsonPayload.data.scriptDeliveryFailure.hint), + ), + jsonClose.stdout, + ); + assert.doesNotMatch(fs.readFileSync(jsonFile, 'utf8'), /^close/m); + + // The CLI for a human: the warning is a line the terminal prints. + const humanStateDir = path.join(root, 'cli-human-state'); + const humanFile = path.join(root, 'cli-human.ad'); + const humanOpen = await cli( + [ + 'open', + 'settings', + '--session', + 'cli-human', + '--save-script', + humanFile, + '--platform', + world.selection.platform, + '--serial', + world.selection.serial, + ], + humanStateDir, + ); + assert.equal(humanOpen.code, null, humanOpen.stderr); + refuseArtifacts = true; + const humanClose = await cli(['close', '--session', 'cli-human'], humanStateDir); + refuseArtifacts = false; + assert.equal(humanClose.code, null, humanClose.stderr); + assert.match( + `${humanClose.stdout}${humanClose.stderr}`, + /Warning: .*remote script could not be saved/i, + ); + + // MCP: the tool text the model reads carries the warning, and machine output carries the field. + const mcpStateDir = path.join(root, 'mcp-state'); + const mcpFile = path.join(root, 'mcp.ad'); + const restoreEnv = installIsolatedCliTestEnv({ + ...remoteEnv, + AGENT_DEVICE_STATE_DIR: mcpStateDir, + }); + try { + const executor = createCommandToolExecutor({ structuredContent: 'always' }); + const mcpOpen = await executor.execute('open', { + app: 'settings', + session: 'mcp-surfaces', + saveScript: mcpFile, + ...world.selection, + }); + assert.equal(mcpOpen.isError, false, JSON.stringify(mcpOpen)); + refuseArtifacts = true; + const mcpClose = await executor.execute('close', { session: 'mcp-surfaces' }); + refuseArtifacts = false; + assert.equal(mcpClose.isError, false, JSON.stringify(mcpClose)); + assert.match( + mcpClose.content.map((part) => part.text ?? '').join('\n'), + /Warning: .*remote script could not be saved/i, + ); + assert.equal( + (mcpClose.structuredContent as { scriptDeliveryFailure?: { reason?: string } }) + ?.scriptDeliveryFailure?.reason, + 'script_delivery_failed', + ); + } finally { + restoreEnv(); + } + assert.doesNotMatch(fs.readFileSync(mcpFile, 'utf8'), /^close/m); + world.assertNoHostAdbCalls(); + } finally { + await closeLoopbackServer(gate); + await proxy.close(); + } + }); +}, 30_000); + +test('a remote batch delivers its step scripts and a close step ends the recording', async () => { + await withProviderScenarioResource(createAndroidSettingsWorld, async (world) => { + const root = mkdtempForTestSync('remote-script-batch-'); + const destination = path.join(root, 'journey.ad'); + const stateDir = path.join(root, 'client-state'); + const proxy = await createProviderScenarioProxy(world.daemon, { clientToken: 'script-client' }); + const client = createAgentDeviceClient({ + daemonBaseUrl: proxy.baseUrl, + daemonAuthToken: 'script-client', + session: 'batch-author', + stateDir, + }); + const records = path.join(stateDir, 'remote-connections', 'session-scripts'); + try { + await client.apps.open({ app: 'settings', saveScript: destination, ...world.selection }); + assert.match(fs.readFileSync(destination, 'utf8'), /^open /m); + + const batch = await client.batch.run({ + steps: [ + { command: 'wait', input: { selector: 'label="Apps"', ...world.selection } }, + { command: 'close', input: {} }, + ], + }); + + assert.equal(batch.executed, 2, JSON.stringify(batch)); + assert.deepEqual( + batch.results.map((result) => result.command), + ['wait', 'close'], + ); + // The caller file holds the final script, the terminal close included, and the client stops + // tracking a recording it no longer has. + const final = fs.readFileSync(destination, 'utf8'); + assert.match(final, /^wait /m); + assert.match(final, /^close/m); + assert.deepEqual( + fs.readdirSync(records).filter((name) => name.endsWith('.json')), + [], + ); + assert.deepEqual( + fs.readdirSync(records).filter((name) => name.startsWith('.agent-device-script-')), + [], + ); + world.assertNoHostAdbCalls(); + } finally { + await client.sessions.close().catch(() => undefined); + await proxy.close(); + } + }); +}, 20_000); diff --git a/test/wire-compat/closure-policy.ts b/test/wire-compat/closure-policy.ts index 84a93c1a70..d6b0d4109e 100644 --- a/test/wire-compat/closure-policy.ts +++ b/test/wire-compat/closure-policy.ts @@ -53,6 +53,8 @@ export const WIRE_CLOSURE_WAIVERS: Readonly> = { 'Byte-progress callback options for local upload rendering. The bytes counted are digested through the request/response declarations; these options never cross the wire.', 'packages/remote/src/upload-progress.ts#UploadProgressSink': 'A callback for client-local upload progress rendering. Its events never leave the client, unlike the daemon progress stream, whose envelope and events are listed.', + 'packages/remote/src/session-script-destination.ts#PublishOutcome': + "The client-local outcome of one script-version publish attempt: a path this process already wrote, or the error it hit. Only the failure branch crosses the boundary, and that is the listed ScriptDeliveryFailure; the destination is this client's own record, which a response never chooses.", 'packages/contracts/src/request-progress.ts#RequestProgressSink': 'A callback type (event) => void. The event it receives is RequestProgressEvent, which is listed; the sink itself never crosses the wire.', diff --git a/test/wire-compat/ledger.json b/test/wire-compat/ledger.json index 0eba21ea2f..4a5f95a0a3 100644 --- a/test/wire-compat/ledger.json +++ b/test/wire-compat/ledger.json @@ -33,6 +33,7 @@ "packages/kernel/src/contracts.ts#RESPONSE_LEVELS": "sha256:cef29c3b56c299e35a7fee8058b90dc4a6f65a46a420e4f11f77c8ca7d0359c8", "packages/kernel/src/contracts.ts#ResponseCost": "sha256:2a44de54e8b5c886b36da1500e22d634ec7e12961d2c93b689d2b1aa8c15f186", "packages/kernel/src/contracts.ts#ResponseLevel": "sha256:c7329d28e745b5e69b86aa1a686befa314b98248afbe5e0e2d7d395f0d777f9b", + "packages/kernel/src/contracts.ts#ScriptDeliveryFailure": "sha256:186881f8b2e6a0227a6d1a2c802d8f7356fee39d4137800a0c9fa65401aa2765", "packages/kernel/src/contracts.ts#SESSION_ISOLATION_MODES": "sha256:3d4b3048e22bb0ceccc98cf8fd93a87a1a1e2dad96fa03cffff6d0ecedb58689", "packages/kernel/src/contracts.ts#SessionIsolationMode": "sha256:beea941fe57b000902da28af15a27aa18d0c957408209e3ec372fcf7f605fa7c", "packages/kernel/src/contracts.ts#SESSION_RUNTIME_PLATFORMS": "sha256:6164fc8ca226b5beb3ba52a8dddd3c11633a8accec58b9f8972c44c8339a1bf7", @@ -41,6 +42,7 @@ "packages/kernel/src/contracts.ts#commandRpcParamsSchema": "sha256:d0ce05c236ce5b0b52631ab7b8a75d38859fbfba58cfb28dd3f9d84f2dba2c1f", "packages/kernel/src/contracts.ts#daemonRuntimeSchema": "sha256:3b99926ce9deb5d66186a55b1168011dc1ae4d010ada5ac5d79c4c7225a1f80f", "packages/kernel/src/contracts.ts#jsonRpcRequestSchema": "sha256:67e6b8a28b39a3883424a565ae7033c336dc2ea6b193e9b32bb98eb3e18dca7c", + "packages/kernel/src/contracts.ts#readScriptDeliveryFailure": "sha256:58e1f8cbe074e05fe8a273ed05fb4bd9e1fa03a227939d233301fbd9e8a8ac77", "packages/kernel/src/device.ts#PLATFORM_SELECTORS": "sha256:36e9da1cc660c0ddfb4cf52521f7f230341ff20e3ebda3405ba7c1799476c42d", "packages/kernel/src/device.ts#PlatformSelector": "sha256:61de3f003507ea2f53b396b0146c17670bf674a2db2132e19c462ca6c10cc8fd", "packages/kernel/src/errors.ts#DaemonError": "sha256:b392b10f461b774f82252f8a5958781450b101329d43827abca10b6511b6d588", @@ -153,7 +155,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:0e5729809b4a931560417f0e4c6d7717d81bcb64459324e534024ecf37f651f9", "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", @@ -241,8 +243,8 @@ }, { "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." + "digest": "sha256:0e5729809b4a931560417f0e4c6d7717d81bcb64459324e534024ecf37f651f9", + "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. #4564 hands a batch response to a step-aware owner, which reads each step's own session-script artifact and publishes it with that step's command name so a terminal step retires the client record. The request and response framing are unchanged: a batch answer already carried the step results, and the client only writes files it already owns the destination for. A released client keeps the batch payload as the daemon answered it." }, { "declaration": "packages/daemon-client/src/daemon-client-rpc.ts#buildHttpRpcPayload", diff --git a/test/wire-compat/surface.ts b/test/wire-compat/surface.ts index 4d39df06b4..323fd76881 100644 --- a/test/wire-compat/surface.ts +++ b/test/wire-compat/surface.ts @@ -294,6 +294,7 @@ export const WIRE_SURFACE: readonly WireSurfaceGroup[] = [ 'DaemonArtifactType', 'DaemonArtifactKnownType', 'ScriptDeliveryFailure', + 'readScriptDeliveryFailure', ), ...from( KERNEL_ERRORS, diff --git a/website/docs/docs/remote-proxy.md b/website/docs/docs/remote-proxy.md index 2cfffa7015..6868918c9c 100644 --- a/website/docs/docs/remote-proxy.md +++ b/website/docs/docs/remote-proxy.md @@ -117,14 +117,13 @@ A script version that is not delivered never fails the command that recorded it. fail to write it, or this machine may fail to download or save it, for example when it is larger than 8 MiB. The command still succeeds, and the file may keep the previous version; the next recorded action or `close` delivers the full recording again. If `close` cannot deliver the final script, -the session still closes and the file keeps the version from the last action. The daemon RPC -response carries a typed `scriptDeliveryFailure` and a warning. The CLI, SDK, and MCP results do -not carry `scriptDeliveryFailure` yet, and `close` shows no warning; see -[#4564](https://github.com/callstack/agent-device/issues/4564). +the session still closes and the file keeps the version from the last action. Every result that +recorded a version discloses it: the CLI prints a `Warning:` line 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. +batch steps are refused. A `batch` delivers the script versions its steps record, in step order, and +a `close` step retires the recording the same way a standalone `close` does. 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 diff --git a/website/docs/docs/replay-e2e.md b/website/docs/docs/replay-e2e.md index 5a96d58ea4..88cd502b73 100644 --- a/website/docs/docs/replay-e2e.md +++ b/website/docs/docs/replay-e2e.md @@ -74,7 +74,7 @@ agent-device open Settings --platform ios --session e2e --save-script ./workflow - With a local daemon, the script is written on the daemon host when the session closes. - With a remote daemon, outside a macOS app lease, the path is on your machine. The file appears when `open` returns, and each later recorded action in the session replaces it with the recording so far. `close` writes the final script there. A session that another process closes keeps the version from the last action. - A bare remote `open --save-script` writes `recording-.ad` in your working directory. -- If the file already exists, `open` fails unless you pass `--force`. Without `--force`, a file that appears before the first version arrives is kept too: `open` still succeeds, but the script is not saved there. The daemon RPC response carries a `scriptDeliveryFailure` and a warning; the CLI, SDK, and MCP results do not carry the failure yet ([#4564](https://github.com/callstack/agent-device/issues/4564)). With `--force`, the first version replaces it. After that, the session owns the file and replaces it on each update. +- 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. - The remote daemon must report the `script-artifacts` capability in its `/health` response. Through a proxy, the upstream daemon's health response must report it. Otherwise `open --save-script` fails before the app opens. - For a bare file name that could be read as another argument, use `--save-script=workflow.ad` or a path-like value such as `./workflow.ad`. From 50774eae255f97afb36595be52f922f509c61791 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Mon, 16 Nov 2026 11:09:47 +0100 Subject: [PATCH 2/5] fix(remote): deliver a batch answer only on the plan the caller submitted A batch answer carries one entry per step, and the client delivered whatever the answer named. That made the response the authority over a caller-owned record: an entry planted in place of a `wait` step could name this client's publication and retire it, and its artifact list was unbounded, so one answer asking for a thousand duplicate versions spent a thousand downloads. Delivery now runs on the plan THIS client submitted: an entry must be the plan's own command at the plan's own position and a step that finished, and anything else is reported exactly as the daemon answered it, with no download, no destination and no retirement. Of the versions one payload names, only the newest is taken, and a duplicate or a version no newer than one already accepted is dropped before any request, which caps one answer at one download per submitted step. A `close` step that names this client's publication now reaches the owner even when it carries no artifact, so a recording the daemon could not finish is still forgotten instead of staying active beside a file that never gained its final version. A failed batch reports the steps it finished in the error's `partialResults`, which never reached the code that materializes a successful response. Those steps are delivered before the error is rehydrated, under the same plan bound, so `[wait, close, snapshot]` that fails on `snapshot` still writes the final script and still ends the recording; the batch error itself stands. A batch's own output reads the batch payload, so a step's warning and typed `scriptDeliveryFailure` are lifted onto it: the CLI `Warning:` line, the MCP tool text and `--json` and structured content now say the caller file is stale, instead of printing only "OK Closed: journey". Co-Authored-By: Claude Opus 5.5 --- .../0016-active-session-script-publication.md | 3 + .../src/__tests__/daemon-client-rpc.test.ts | 227 ++++++++++++- .../daemon-client/src/daemon-client-rpc.ts | 35 ++- .../daemon-artifacts-batch-script.test.ts | 288 +++++++++++++++-- packages/remote/src/daemon-artifacts.ts | 54 ++++ .../src/remote-batch-script-delivery.ts | 297 +++++++++++++++--- .../remote-script-publication.test.ts | 255 +++++++++++++-- test/wire-compat/ledger.json | 6 +- website/docs/docs/remote-proxy.md | 5 +- 9 files changed, 1049 insertions(+), 121 deletions(-) diff --git a/docs/adr/0016-active-session-script-publication.md b/docs/adr/0016-active-session-script-publication.md index 9185be3fab..3b2b4e7217 100644 --- a/docs/adr/0016-active-session-script-publication.md +++ b/docs/adr/0016-active-session-script-publication.md @@ -205,6 +205,9 @@ It adds no state name, command, or flag: - 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 delivers the script versions its steps record, in step order, and a batch step that closes the recording retires the caller record like a standalone close does. + The submitted plan is the only authority for that delivery: an answer entry that is not the plan's own step at its own position, or that is not a step that finished, gets no download and no retirement, and one answer earns at most one download per submitted step. + The steps that finished of a FAILED batch are delivered too, from the error's `partialResults`, and the batch error stands. + A step's delivery warning and typed failure also ride the batch payload itself, because a batch's human and machine output read only that payload. - 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). diff --git a/packages/daemon-client/src/__tests__/daemon-client-rpc.test.ts b/packages/daemon-client/src/__tests__/daemon-client-rpc.test.ts index 243c3dd1ee..270bd70caa 100644 --- a/packages/daemon-client/src/__tests__/daemon-client-rpc.test.ts +++ b/packages/daemon-client/src/__tests__/daemon-client-rpc.test.ts @@ -1,7 +1,20 @@ -import { createTestHostEnvironment } from '@agent-device/test-kit'; import assert from 'node:assert/strict'; import { test } from 'vitest'; +import fs from 'node:fs'; +import http from 'node:http'; +import path from 'node:path'; import { AppError } from '@agent-device/kernel/errors'; +import type { DaemonWireRequest } from '@agent-device/contracts/command'; +import { + materializeRemoteArtifacts, + sendRemoteScriptOpen, +} from '@agent-device/remote/daemon-artifacts'; +import { + closeLoopbackServer, + createTestHostEnvironment, + listenOnLoopback, + mkdtempForTestSync, +} from '@agent-device/test-kit'; import { buildHttpRpcPayload, handleDaemonHttpResponseBody } from '../daemon-client-rpc.ts'; test('lease allocation transports an optional initial provider app', () => { @@ -219,3 +232,215 @@ test('lease allocation carries the device spec a proxy backend picks by', () => physical: true, }); }); + +/** + * A failed batch is an error, so nothing about it reaches the code that materializes a successful + * response's artifacts. The steps that DID finish have to be delivered from the error's + * `partialResults` all the same: `[wait, close, snapshot]` that fails on `snapshot` still owes the + * caller the final script the close step wrote, and still has to forget a recording the daemon no + * longer has. The batch's own error stands. + */ +test('a failed remote batch delivers the scripts of the steps that finished and keeps its error', async () => { + const finalScript = 'open Demo\nwait 100\nclose\n'; + const server = scriptServer({ v1: 'open Demo\n', final: finalScript }); + const baseUrl = `http://127.0.0.1:${await listenOnLoopback(server)}`; + const root = fs.realpathSync(mkdtempForTestSync('rpc-batch-partial-')); + const stateDir = path.join(root, 'state'); + const destination = path.join(root, 'journey.ad'); + const host = createTestHostEnvironment(); + try { + const publicationId = await openRemoteRecording(baseUrl, stateDir, destination); + + let rejected: unknown; + await new Promise((resolve) => { + handleDaemonHttpResponseBody( + JSON.stringify({ + error: { + data: { + code: 'COMMAND_FAILED', + message: 'Batch failed at step 3 (snapshot): snapshot failed', + details: { + step: 3, + command: 'snapshot', + executed: 2, + total: 3, + partialResults: [ + { step: 1, command: 'wait', ok: true, durationMs: 1, data: { waited: true } }, + { + step: 2, + command: 'close', + ok: true, + durationMs: 1, + data: { + scriptPublicationId: publicationId, + artifacts: [scriptArtifact('final', 2, publicationId)], + }, + }, + ], + }, + }, + }, + }), + { + info: { token: 'daemon-token', pid: 1, baseUrl }, + req: batchRequest('wait', 'close'), + stateDir, + host, + resolve: () => resolve(), + reject: (error) => { + rejected = error; + resolve(); + }, + }, + ); + }); + + assert.ok(rejected instanceof AppError, `Expected the batch error, got ${String(rejected)}`); + assert.match(rejected.message, /Batch failed at step 3 \(snapshot\)/); + assert.equal(rejected.details?.step, 3); + // The close step's script reached the caller file, and the client stopped tracking the recording. + assert.equal(fs.readFileSync(destination, 'utf8'), finalScript); + assert.deepEqual(activeScriptRecords(stateDir), []); + } finally { + await closeLoopbackServer(server); + } +}); + +/** + * A failed batch delivers only what the caller submitted. A step entry the plan never named earns no + * download and no retirement, even inside an error. + */ +test('a failed remote batch delivers nothing for a step the caller never submitted', async () => { + const server = scriptServer({ v1: 'open Demo\n', final: 'open Demo\nwait 100\nclose\n' }); + const baseUrl = `http://127.0.0.1:${await listenOnLoopback(server)}`; + const root = fs.realpathSync(mkdtempForTestSync('rpc-batch-unauthorized-')); + const stateDir = path.join(root, 'state'); + const destination = path.join(root, 'journey.ad'); + const host = createTestHostEnvironment(); + try { + const publicationId = await openRemoteRecording(baseUrl, stateDir, destination); + + await new Promise((resolve) => { + handleDaemonHttpResponseBody( + JSON.stringify({ + error: { + data: { + code: 'COMMAND_FAILED', + message: 'Batch failed at step 2 (wait): wait failed', + details: { + step: 2, + command: 'wait', + // The caller submitted one `wait` step; this entry claims a close of its publication. + partialResults: [ + { + step: 1, + command: 'close', + ok: true, + durationMs: 1, + data: { + scriptPublicationId: publicationId, + artifacts: [scriptArtifact('final', 2, publicationId)], + }, + }, + ], + }, + }, + }, + }), + { + info: { token: 'daemon-token', pid: 1, baseUrl }, + req: batchRequest('wait'), + stateDir, + host, + resolve: () => resolve(), + reject: () => resolve(), + }, + ); + }); + + assert.equal(fs.readFileSync(destination, 'utf8'), 'open Demo\n'); + assert.equal(activeScriptRecords(stateDir).length, 1); + } finally { + await closeLoopbackServer(server); + } +}); + +function batchRequest(...commands: string[]): DaemonWireRequest { + return { + token: 'daemon-token', + session: 'journey', + command: 'batch', + positionals: [], + flags: { batchSteps: commands.map((command) => ({ command })) }, + }; +} + +function scriptArtifact(artifactId: string, revision: number, publicationId: string) { + return { + field: 'savedScript', + artifactType: 'session-script', + artifactId, + scriptPublicationId: publicationId, + scriptRevision: revision, + }; +} + +/** Serves the script versions it is given; anything else answers 503. */ +function scriptServer(bodies: Record): http.Server { + return http.createServer((req, res) => { + const id = decodeURIComponent(req.url?.replace('/artifacts/', '') ?? ''); + const body = bodies[id]; + if (body === undefined) { + res.writeHead(503).end('unavailable'); + return; + } + res.writeHead(200, { 'content-length': Buffer.byteLength(body) }); + res.end(body); + }); +} + +/** A remote `open --save-script` the daemon answered with version 1, as this client arms it. */ +async function openRemoteRecording( + baseUrl: string, + stateDir: string, + destination: string, +): Promise { + let publicationId = ''; + await sendRemoteScriptOpen( + { baseUrl, token: 'daemon-token', capabilities: ['script-artifacts'] }, + { + token: 'daemon-token', + session: 'journey', + command: 'open', + positionals: [], + flags: { saveScript: true }, + meta: { clientArtifactPaths: { savedScript: destination } }, + }, + stateDir, + async (next) => { + publicationId = next.meta?.scriptPublicationId as string; + return await materializeRemoteArtifacts( + { baseUrl, token: 'daemon-token' }, + next, + { + ok: true, + data: { + scriptPublicationId: publicationId, + artifacts: [scriptArtifact('v1', 1, publicationId)], + }, + }, + createTestHostEnvironment(), + stateDir, + ); + }, + ); + assert.equal(fs.readFileSync(destination, 'utf8'), 'open Demo\n'); + return publicationId; +} + +function activeScriptRecords(stateDir: string): string[] { + const directory = path.join(stateDir, 'remote-connections', 'session-scripts'); + return fs.existsSync(directory) + ? fs.readdirSync(directory).filter((name) => name.endsWith('.json')) + : []; +} diff --git a/packages/daemon-client/src/daemon-client-rpc.ts b/packages/daemon-client/src/daemon-client-rpc.ts index 859a0a61a8..8507126beb 100644 --- a/packages/daemon-client/src/daemon-client-rpc.ts +++ b/packages/daemon-client/src/daemon-client-rpc.ts @@ -10,7 +10,10 @@ 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 { + materializeRemoteArtifacts, + materializeRemoteBatchPartialArtifacts, +} 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'; @@ -92,16 +95,28 @@ async function rejectDaemonHttpRpcError( reject(appErrorFromDaemonError(payload, requestId)); return; } - const localized = await localizeRemoteDaemonError(payload, { - endpoint: { - baseUrl: info.baseUrl, - token: info.token, - tenantId: req.meta?.tenantId, - leaseId: leaseScopeFromRequest(req).leaseId, - }, + // A failed batch still reports the steps it finished, and one of them may have closed this + // client's recording, so its script is delivered before the error reaches the caller. The batch + // error itself stands either way. + const delivered = await materializeRemoteBatchPartialArtifacts( + info, + req, + payload.details, stateDir, - requestId, - }); + ); + const localized = await localizeRemoteDaemonError( + delivered ? { ...payload, details: delivered } : payload, + { + endpoint: { + baseUrl: info.baseUrl, + token: info.token, + tenantId: req.meta?.tenantId, + leaseId: leaseScopeFromRequest(req).leaseId, + }, + stateDir, + requestId, + }, + ); reject(appErrorFromDaemonError(localized, requestId)); } diff --git a/packages/remote/src/__tests__/daemon-artifacts-batch-script.test.ts b/packages/remote/src/__tests__/daemon-artifacts-batch-script.test.ts index 0015f039fb..c14f308dba 100644 --- a/packages/remote/src/__tests__/daemon-artifacts-batch-script.test.ts +++ b/packages/remote/src/__tests__/daemon-artifacts-batch-script.test.ts @@ -44,8 +44,27 @@ function journey() { return { root, stateDir: path.join(root, 'state'), destination: path.join(root, 'journey.ad') }; } -function request(command: string, meta: DaemonWireRequest['meta'] = {}): DaemonWireRequest { - return { token: 't', session: 'journey', command, positionals: [], meta }; +function request( + command: string, + meta: DaemonWireRequest['meta'] = {}, + flags?: DaemonWireRequest['flags'], +): DaemonWireRequest { + return { + token: 't', + session: 'journey', + command, + positionals: [], + ...(flags ? { flags } : {}), + meta, + }; +} + +/** + * The plan a `batch` request carries: the daemon answers one entry per submitted step, and the + * client authorizes delivery only for the steps IT submitted (#4564 review). + */ +function batchPlan(...commands: string[]): DaemonWireRequest['flags'] { + return { batchSteps: commands.map((command) => ({ command })) }; } function script(artifactId: string, revision: number, publicationId: string): DaemonArtifact { @@ -113,6 +132,18 @@ function batchSteps(response: DaemonResponse): Array> { return (response.data?.results ?? []) as Array>; } +/** + * Nothing was delivered: no step names a caller file, and no artifact reports a published local + * path. The daemon's own artifact entries stay in the answer, field names and all, so the answer is + * checked for what this client would have added. + */ +function expectDeliveredNothing(response: DaemonResponse): void { + const text = JSON.stringify(response); + expect(text).not.toContain('"savedScript":'); + expect(text).not.toContain('"localPath":'); + expect(text).not.toContain('"scriptDeliveryFailure":'); +} + test('a batch delivers each step script in step order and a close step retires the record', async () => { const { stateDir, destination } = journey(); const baseUrl = await artifactServer({ @@ -123,15 +154,20 @@ test('a batch delivers each step script in step order and a close step retires t const id = await open(baseUrl, stateDir, destination); expect(records(stateDir)).toHaveLength(1); - const response = await answer(baseUrl, stateDir, request('batch'), { - total: 2, - executed: 2, - totalDurationMs: 5, - results: [ - step(1, 'wait', { waited: true, artifacts: [script('v2', 2, id)] }), - step(2, 'close', { scriptPublicationId: id, artifacts: [script('v3', 3, id)] }), - ], - }); + const response = await answer( + baseUrl, + stateDir, + request('batch', {}, batchPlan('wait', 'close')), + { + total: 2, + executed: 2, + totalDurationMs: 5, + results: [ + step(1, 'wait', { waited: true, artifacts: [script('v2', 2, id)] }), + step(2, 'close', { scriptPublicationId: id, artifacts: [script('v3', 3, id)] }), + ], + }, + ); expect(fs.readFileSync(destination, 'utf8')).toBe('open Demo\nwait 100\nclose\n'); // The terminal step retired the record, so no later version of that publication writes anything. @@ -164,7 +200,7 @@ test('a batch step whose download fails discloses the failure on that step and k const baseUrl = await artifactServer({ v1: 'open Demo\n' }); const id = await open(baseUrl, stateDir, destination); - const response = await answer(baseUrl, stateDir, request('batch'), { + const response = await answer(baseUrl, stateDir, request('batch', {}, batchPlan('wait')), { total: 1, executed: 1, totalDurationMs: 1, @@ -208,7 +244,7 @@ test('a batch that closes keeps its success and retires the record when the fina const baseUrl = await artifactServer({ v1: 'open Demo\n' }); const id = await open(baseUrl, stateDir, destination); - const response = await answer(baseUrl, stateDir, request('batch'), { + const response = await answer(baseUrl, stateDir, request('batch', {}, batchPlan('close')), { total: 1, executed: 1, totalDurationMs: 1, @@ -237,20 +273,25 @@ test('a batch step script of another publication or of another field writes noth const id = await open(baseUrl, stateDir, destination); const victim = path.join(root, 'victim.ad'); - const response = await answer(baseUrl, stateDir, request('batch'), { - total: 2, - executed: 2, - totalDurationMs: 1, - results: [ - // Another publication's version, and one under a field this owner does not claim. - step(1, 'wait', { - artifacts: [script('foreign', 9, '00000000-0000-4000-8000-000000000000')], - }), - step(2, 'wait', { - artifacts: [{ ...script('foreign', 8, id), field: 'path', fileName: 'victim.ad' }], - }), - ], - }); + const response = await answer( + baseUrl, + stateDir, + request('batch', {}, batchPlan('wait', 'wait')), + { + total: 2, + executed: 2, + totalDurationMs: 1, + results: [ + // Another publication's version, and one under a field this owner does not claim. + step(1, 'wait', { + artifacts: [script('foreign', 9, '00000000-0000-4000-8000-000000000000')], + }), + step(2, 'wait', { + artifacts: [{ ...script('foreign', 8, id), field: 'path', fileName: 'victim.ad' }], + }), + ], + }, + ); expect(batchSteps(response).map((result) => result.data)).toEqual([ { artifacts: [] }, @@ -271,7 +312,198 @@ test('a batch answer with no step scripts is returned untouched', async () => { results: [step(1, 'wait', { waited: true })], }; - const response = await answer(baseUrl, stateDir, request('batch'), data); + const response = await answer(baseUrl, stateDir, request('batch', {}, batchPlan('wait')), data); expect(response).toEqual({ ok: true, data }); }); + +test('a close step that names the publication retires the record with no artifact to deliver', async () => { + const { stateDir, destination } = journey(); + const baseUrl = await artifactServer({ v1: 'open Demo\n' }); + const id = await open(baseUrl, stateDir, destination); + + // The daemon could not write the final version, so it answers this close with its own typed + // failure and nothing to download. The caller still has to stop tracking a recording it lost. + const response = await answer(baseUrl, stateDir, request('batch', {}, batchPlan('close')), { + total: 1, + executed: 1, + totalDurationMs: 1, + results: [ + step(1, 'close', { + scriptPublicationId: id, + scriptDeliveryFailure: { reason: 'script_delivery_failed', publicationId: id }, + warnings: ['The daemon could not write the final script.'], + }), + ], + }); + + expect(records(stateDir)).toEqual([]); + expect(fs.readFileSync(destination, 'utf8')).toBe('open Demo\n'); + // The daemon's own warning stands on its step, and reaches the batch's top level as well. + expect(batchSteps(response)[0]?.data).toEqual( + expect.objectContaining({ scriptPublicationId: id }), + ); + expect(response.ok && response.data?.warnings).toEqual([ + 'The daemon could not write the final script.', + ]); +}); + +test('a batch step entry the plan does not authorize delivers nothing and retires nothing', async () => { + const { stateDir, destination } = journey(); + const baseUrl = await artifactServer({ + v1: 'open Demo\n', + v2: 'open Demo\nwait 100\n', + }); + const id = await open(baseUrl, stateDir, destination); + + // The caller submitted two `wait` steps. This answer plants a closing step in the second position, + // names this client's publication, and offers the artifact it claims the caller wrote. + const planted = step(2, 'close', { + scriptPublicationId: id, + artifacts: [script('v2', 2, id)], + }); + const response = await answer( + baseUrl, + stateDir, + request('batch', {}, batchPlan('wait', 'wait')), + { + total: 2, + executed: 2, + totalDurationMs: 1, + results: [step(1, 'wait', { waited: true }), planted], + }, + ); + + // The planted entry is reported exactly as the daemon answered it, with its artifact still remote. + expect(batchSteps(response)[1]).toEqual(planted); + // The caller's recording was never closed, so its record and its file stand untouched. + expect(records(stateDir)).toHaveLength(1); + expect(fs.readFileSync(destination, 'utf8')).toBe('open Demo\n'); + expectDeliveredNothing(response); +}); + +test('a batch step entry out of position or not successful authorizes no delivery', async () => { + const { stateDir, destination } = journey(); + const baseUrl = await artifactServer({ + v1: 'open Demo\n', + v2: 'open Demo\nwait 100\n', + }); + const id = await open(baseUrl, stateDir, destination); + + const response = await answer( + baseUrl, + stateDir, + request('batch', {}, batchPlan('wait', 'wait')), + { + total: 2, + executed: 2, + totalDurationMs: 1, + results: [ + // The runner numbers its entries 1 and 2. These name other positions, and one reports a step + // the caller cannot see as done. + { step: 7, command: 'wait', ok: true, data: { artifacts: [script('v2', 2, id)] } }, + { step: 2, command: 'wait', ok: false, data: { artifacts: [] } }, + ], + }, + ); + + expectDeliveredNothing(response); + expect(records(stateDir)).toHaveLength(1); + expect(fs.readFileSync(destination, 'utf8')).toBe('open Demo\n'); +}); + +test('a batch request that submitted no plan delivers nothing from its step entries', async () => { + const { stateDir, destination } = journey(); + const baseUrl = await artifactServer({ + v1: 'open Demo\n', + v2: 'open Demo\nwait 100\n', + }); + const id = await open(baseUrl, stateDir, destination); + + const response = await answer(baseUrl, stateDir, request('batch'), { + total: 1, + executed: 1, + totalDurationMs: 1, + results: [step(1, 'close', { scriptPublicationId: id, artifacts: [script('v2', 2, id)] })], + }); + + expectDeliveredNothing(response); + expect(records(stateDir)).toHaveLength(1); + expect(fs.readFileSync(destination, 'utf8')).toBe('open Demo\n'); +}); + +test('one batch answer asks for one download per step, whatever versions it names', async () => { + const { stateDir, destination } = journey(); + const requested: string[] = []; + const server = http.createServer((req, res) => { + const id = decodeURIComponent(req.url?.replace('/artifacts/', '') ?? ''); + requested.push(id); + if (id !== 'v3' && id !== 'v5') { + res.writeHead(503).end('unavailable'); + return; + } + const body = id === 'v3' ? 'open Demo\nwait 100\n' : 'open Demo\nwait 100\nsnapshot\n'; + res.writeHead(200, { 'content-length': Buffer.byteLength(body) }); + res.end(body); + }); + servers.push(server); + const baseUrl = `http://127.0.0.1:${await listenOnLoopback(server)}`; + const id = await open(baseUrl, stateDir, destination); + requested.length = 0; + + // One answer names every version of every step at once, including duplicates and versions older + // than one it already named. None of that may turn into one request each. + const repeats = (artifactId: string, revision: number, times: number) => + Array.from({ length: times }, () => script(artifactId, revision, id)); + await answer(baseUrl, stateDir, request('batch', {}, batchPlan('wait', 'snapshot')), { + total: 2, + executed: 2, + totalDurationMs: 1, + results: [ + step(1, 'wait', { + artifacts: [...repeats('gone', 2, 500), ...repeats('v3', 3, 2), ...repeats('gone', 1, 2)], + }), + step(2, 'snapshot', { + artifacts: [...repeats('gone', 4, 497), script('v5', 5, id), ...repeats('v3', 3, 2)], + }), + ], + }); + + expect(requested).toEqual(['v3', 'v5']); + expect(fs.readFileSync(destination, 'utf8')).toBe('open Demo\nwait 100\nsnapshot\n'); +}); + +test('a batch step that cannot save its version discloses it on the batch payload', async () => { + const { stateDir, destination } = journey(); + const baseUrl = await artifactServer({ v1: 'open Demo\n' }); + const id = await open(baseUrl, stateDir, destination); + + const response = await answer( + baseUrl, + stateDir, + request('batch', {}, batchPlan('wait', 'wait')), + { + total: 2, + executed: 2, + totalDurationMs: 1, + results: [ + step(1, 'wait', { artifacts: [script('gone', 2, id)] }), + step(2, 'wait', { artifacts: [script('gone', 3, id)] }), + ], + }, + ); + + // A batch's human and machine output reads the batch's own payload, so the failure and its + // warning have to be lifted there — a step's nested data never reaches the CLI or the MCP text. + expect(response.ok && response.data?.scriptDeliveryFailure).toEqual( + expect.objectContaining({ + reason: 'script_delivery_failed', + cause: 'script_download_failed', + publicationId: id, + }), + ); + const warnings = (response.ok ? response.data?.warnings : undefined) as string[] | undefined; + expect(warnings).toHaveLength(1); + expect(warnings?.[0]).toContain('script'); + expect(fs.readFileSync(destination, 'utf8')).toBe('open Demo\n'); +}); diff --git a/packages/remote/src/daemon-artifacts.ts b/packages/remote/src/daemon-artifacts.ts index 3a7d5372fe..1ab24c3256 100644 --- a/packages/remote/src/daemon-artifacts.ts +++ b/packages/remote/src/daemon-artifacts.ts @@ -8,6 +8,7 @@ import { buildRemoteTempArtifactPath, } from '@agent-device/contracts/daemon-http'; import { AppError } from '@agent-device/kernel/errors'; +import { isRecord } from '@agent-device/kernel/record'; import { resolveUserPath } from '@agent-device/host-kit/file'; import { leaseScopeFromRequest } from '@agent-device/contracts/lease-scope'; import { @@ -504,6 +505,59 @@ export async function materializeRemoteArtifacts( return await scripts.settleAfter(download); } +/** + * Delivers the session scripts of the steps a FAILED remote `batch` completed. + * + * The runner reports the steps that finished in the error's `details.partialResults`, so a + * recording that an earlier step closed would otherwise be lost just because a later step failed — + * `[wait, close, snapshot]` that fails on `snapshot` would keep neither the final script nor the + * retirement of the caller's record. The steps are delivered under the plan THIS client submitted, + * exactly as in a successful batch, and the caller keeps its own error either way. + * + * Answers the fields the error should disclose about that delivery — the steps' warnings and the + * first typed delivery failure — which a batch error's reader prints alongside the failure. Never + * throws: a request that the daemon answered still has to settle with its own error. + */ +export async function materializeRemoteBatchPartialArtifacts( + info: DaemonArtifactEndpoint, + req: DaemonWireRequest, + details: Record | undefined, + stateDir: string, +): Promise | undefined> { + const results = readSubmittedStepResults(details); + if (!info.baseUrl || req.command !== BATCH_COMMAND || results.length === 0) return undefined; + try { + const { deliverSubmittedStepScripts, readBatchPlan, withBatchDisclosure } = + await import('./remote-batch-script-delivery.ts'); + const delivered = await deliverSubmittedStepScripts( + { baseUrl: info.baseUrl, token: info.token }, + req, + stateDir, + downloadRemoteArtifact, + isSessionScriptArtifact, + readBatchPlan(req), + results, + ); + return delivered.disclosure || delivered.results + ? { + ...details, + ...(delivered.results ? { partialResults: delivered.results } : {}), + ...withBatchDisclosure(details, delivered.disclosure), + } + : undefined; + } catch { + return undefined; + } +} + +function readSubmittedStepResults( + details: Record | undefined, +): Array> { + const partialResults = details?.partialResults; + if (!Array.isArray(partialResults)) return []; + return partialResults.filter((result): result is Record => isRecord(result)); +} + /** Command name of the request that runs several steps under one response. */ const BATCH_COMMAND = 'batch'; diff --git a/packages/remote/src/remote-batch-script-delivery.ts b/packages/remote/src/remote-batch-script-delivery.ts index 0444293857..bb4ae93a74 100644 --- a/packages/remote/src/remote-batch-script-delivery.ts +++ b/packages/remote/src/remote-batch-script-delivery.ts @@ -1,26 +1,22 @@ import type { DaemonWireRequest } from '@agent-device/contracts/command'; import type { DaemonArtifact, DaemonResponse } from '@agent-device/kernel/contracts'; import { isRecord } from '@agent-device/kernel/record'; +import { readResponseWarnings } from '@agent-device/kernel/success-text'; +import { emitDiagnostic } from '@agent-device/host-kit/diagnostics'; import type { downloadRemoteArtifact } from './daemon-artifacts.ts'; import type { SessionScriptDelivery } from './session-script-destination.ts'; -/** Command name the runner records for a step whose result carries none. */ -const UNKNOWN_STEP_COMMAND = 'batch'; - /** - * Delivers the session scripts a `batch` response carries, in step order. - * - * A step's `data` is what that command would have answered on its own, so each step is delivered - * through the session-script owner under its own command name: a step that closes the recording - * retires this client's record, and a step that only records a version leaves the record open for - * the next step. The batch's own payload carries the version the daemon stamped after the last step, - * so it is delivered last under the batch's own command name — after a closing step retired the - * record, which drops that version instead of writing a stale one. The destination still comes only - * from the record this client's own `open --save-script` wrote, never from the response, which names - * artifacts and not paths. + * Delivers the session scripts a successful `batch` answer carries, in step order, and reports what + * did not arrive on the batch's own payload. * - * A step that cannot save its version keeps the batch successful and reports the typed failure on - * that step's result, the way the same command does on its own. + * A step's `data` is what that command would have answered alone, so the session-script owner runs + * it under its own command name: a `close` step retires this client's record, and a step that only + * records a version leaves the record open for the next one. The batch's own payload carries the + * version the daemon stamped after the last step, so it is delivered last — after a closing step + * retired the record, which drops it instead of writing a stale one. The plan bound, the download + * bound and the destination rule are `deliverSubmittedStepScripts`' and `deliverPayloadScripts`' + * own, and the batch's answer is built from what they report. */ export async function deliverRemoteBatchScripts( endpoint: Readonly<{ baseUrl: string; token: string }>, @@ -30,56 +26,186 @@ export async function deliverRemoteBatchScripts( download: typeof downloadRemoteArtifact, isScriptArtifact: (artifact: DaemonArtifact | undefined) => boolean, ): Promise { - const results = readBatchResults(response.data); - const nextResults: unknown[] = []; - for (const [index, result] of results.entries()) { - const delivered = await deliverScripts(endpoint, req, stateDir, download, isScriptArtifact, { - command: readString(result.command) ?? UNKNOWN_STEP_COMMAND, - // A copy: the session-script owner narrows the payload it is handed, and the daemon's own - // response object stays as it arrived. - data: isRecord(result.data) ? { ...result.data } : undefined, - }); - nextResults.push(delivered === undefined ? results[index] : { ...result, data: delivered }); - } - const data = { ...response.data, ...(results.length > 0 ? { results: nextResults } : {}) }; + const plan = readBatchPlan(req); + const steps = await deliverSubmittedStepScripts( + endpoint, + req, + stateDir, + download, + isScriptArtifact, + plan, + readBatchResults(response.data), + ); + if (steps.results === undefined && steps.disclosure === undefined) return response; + const data = { + ...response.data, + ...(steps.results ? { results: steps.results } : {}), + ...withBatchDisclosure(response.data, steps.disclosure), + }; // The batch's own payload last: it names the newest revision, and a closing step has already // retired the record, so a script that arrived after the close is dropped rather than rewritten. - const deliveredPayload = await deliverScripts( + const deliveredPayload = await deliverPayloadScripts( endpoint, req, stateDir, download, isScriptArtifact, - { - command: req.command, - data, - }, + { command: req.command, data, revisions: steps.revisions }, ); return { ok: true, data: deliveredPayload ?? data }; } +/** + * Delivers the session scripts of one batch's successful steps, in order, and answers the delivered + * entries plus what the batch payload must disclose. + * + * The plan THIS client submitted is the only authority here, never the answer: an entry must be the + * plan's own command at the plan's own position and a step that finished. An entry that is anything + * else is reported exactly as the daemon answered it — no download, no destination, and no + * retirement — so a daemon cannot retire the caller record or spend the caller's downloads by naming + * a step the caller never ran. A batch request that submitted no plan authorizes nothing at all. + * + * The successful steps of a FAILED batch reach this too: the runner reports them in + * `error.details.partialResults`, and a recording a completed step closed must still reach the caller + * file even though a later step failed. The caller keeps its own error either way. + */ +export async function deliverSubmittedStepScripts( + endpoint: Readonly<{ baseUrl: string; token: string }>, + req: DaemonWireRequest, + stateDir: string, + download: typeof downloadRemoteArtifact, + isScriptArtifact: (artifact: DaemonArtifact | undefined) => boolean, + plan: readonly string[], + results: ReadonlyArray>, +): Promise<{ + results?: Array>; + disclosure?: BatchDisclosure; + revisions: ScriptRevisions; +}> { + const nextResults: Array> = []; + const disclosure: BatchDisclosure = { warnings: [] }; + const revisions: ScriptRevisions = new Set(); + let touched = false; + for (const [index, result] of results.entries()) { + const plannedCommand = plan[index] ?? ''; + // An entry the plan does not authorize is reported exactly as the daemon answered it: no + // download, no destination, and no retirement. + if (plannedCommand === '' || !isSubmittedStep(result, plannedCommand, index)) { + emitDiagnostic({ + level: 'warn', + phase: 'session_script_batch_step_unauthorized', + data: { session: req.session, step: index + 1 }, + }); + nextResults.push(result); + continue; + } + const delivered = await deliverPayloadScripts( + endpoint, + req, + stateDir, + download, + isScriptArtifact, + { + command: plannedCommand, + // A copy: the session-script owner narrows the payload it is handed, and the daemon's own + // response object stays as it arrived. + data: isRecord(result.data) ? { ...result.data } : undefined, + revisions, + }, + ); + // A step's own disclosure rides the batch payload whether the daemon wrote it or this client did, + // and whether or not the step's payload itself changed. + collectBatchDisclosure( + disclosure, + isRecord(delivered) ? delivered : isRecord(result.data) ? result.data : {}, + ); + if (delivered === undefined) { + nextResults.push(result); + continue; + } + touched = true; + nextResults.push({ ...result, data: delivered }); + } + return { + ...(touched ? { results: nextResults } : {}), + ...(disclosure.warnings.length > 0 || disclosure.failure !== undefined ? { disclosure } : {}), + revisions, + }; +} + +/** + * The commands the caller submitted, in step order. A batch request with no plan authorizes nothing: + * with no way to tell a real step from a planted one, the answer's step entries are left alone. + */ +export function readBatchPlan(req: DaemonWireRequest): string[] { + const steps = req.flags?.batchSteps; + if (!Array.isArray(steps)) return []; + return steps.map((step) => normalizeStepCommand(isRecord(step) ? step.command : undefined)); +} + +/** The versions of this response already taken past the owner, keyed publication and revision. */ +type ScriptRevisions = Set; + +/** What a batch's steps disclose: every step's warning text, and the first typed failure. */ +type BatchDisclosure = { + warnings: string[]; + failure?: Record; +}; + +/** + * Whether one answer entry is the plan's own step at the plan's own position. The runner records the + * step's number and command on its result, so an entry must name the plan's command at that position + * and must be a step that finished successfully. + */ +function isSubmittedStep( + result: Record, + plannedCommand: string, + index: number, +): boolean { + return ( + result.step === index + 1 && + normalizeStepCommand(result.command) === plannedCommand && + result.ok === true + ); +} + +function normalizeStepCommand(command: unknown): string { + return typeof command === 'string' ? command.trim().toLowerCase() : ''; +} + /** * Delivers one payload's session-script artifacts — a step's result or the batch's own data — or - * answers `undefined` when that payload carries none and the caller reports it as the daemon - * answered it. + * answers `undefined` when there is nothing here for this client to deliver. * * The payload keeps the batch request's own endpoint, tenant and session, which is what lets it - * reach the record that armed the recording, and takes the command name of its own, which is what - * makes a terminal `close` retire that record. + * reach the record that armed the recording, and takes the command name the plan gives that step, + * which is what makes a terminal `close` retire that record. A `close` that names this client's + * publication goes through the owner even when it carries no artifact: the daemon may have failed to + * write the final version, and the caller still has to stop tracking a recording it no longer has. */ -async function deliverScripts( +async function deliverPayloadScripts( endpoint: Readonly<{ baseUrl: string; token: string }>, req: DaemonWireRequest, stateDir: string, download: typeof downloadRemoteArtifact, isScriptArtifact: (artifact: DaemonArtifact | undefined) => boolean, - payload: Readonly<{ command: string; data: Record | undefined }>, + payload: Readonly<{ + command: string; + data: Record | undefined; + revisions: ScriptRevisions; + }>, ): Promise | undefined> { const data = payload.data; - const artifacts = Array.isArray(data?.artifacts) ? data.artifacts : []; - if (!data || !artifacts.some((artifact) => isScriptArtifact(artifact as DaemonArtifact))) { - return undefined; - } + if (!data) return undefined; + const artifacts = Array.isArray(data.artifacts) ? data.artifacts : []; + const closing = payload.command === CLOSE_COMMAND; + const scriptCount = artifacts.filter((artifact) => + isScriptArtifact(artifact as DaemonArtifact), + ).length; + // A step's `data` is what that command would have answered on its own, so the session-script owner + // is the only owner of `savedScript` and of the retirement a close names. + const retires = closing && typeof data.scriptPublicationId === 'string'; + if (scriptCount === 0 && !retires) return undefined; const { sessionScriptDelivery } = await import('./session-script-destination.ts'); const scripts = sessionScriptDelivery( endpoint, @@ -90,40 +216,107 @@ async function deliverScripts( ); let published = data; await scripts.settleAfter(async () => { - published = await publishStepArtifacts(scripts, data, isScriptArtifact); + published = await publishOwnedScripts(scripts, data, isScriptArtifact, payload.revisions); return { ok: true, data: published }; }); - return published; + return published === data ? undefined : published; } /** * Publishes the session-script artifacts of one payload and keeps every other artifact as the daemon * answered it. Only the session-script owner owns `savedScript`; a payload's other artifacts are the * daemon's own outputs, which the daemon already wrote on its side. + * + * Of several script artifacts in one payload, only the newest is delivered, and a version no newer + * than one already taken in this response is dropped before any request. Without that, one answer + * naming a thousand duplicate versions of one step would ask for a thousand downloads, and a version + * older than one already published would only be refused by the owner after its bytes arrived. + * + * Together with the plan bound, that caps one answer at one download per submitted step whatever it + * names, which is the budget a caller pays for one batch. */ -async function publishStepArtifacts( +async function publishOwnedScripts( scripts: SessionScriptDelivery, data: Record, isScriptArtifact: (artifact: DaemonArtifact | undefined) => boolean, + revisions: ScriptRevisions, ): Promise> { const nextData = { ...data }; const kept: DaemonArtifact[] = []; - for (const artifact of data.artifacts as DaemonArtifact[]) { + const candidates: DaemonArtifact[] = []; + const listed = Array.isArray(data.artifacts) ? (data.artifacts as DaemonArtifact[]) : []; + for (const artifact of listed) { if (!isScriptArtifact(artifact)) { kept.push(artifact); continue; } - await scripts.publish(artifact, nextData, kept); + if (isNewerVersion(artifact, revisions)) candidates.push(artifact); } - nextData.artifacts = kept; + const newest = newestScriptVersion(candidates); + if (newest !== undefined) await scripts.publish(newest, nextData, kept); + if (Array.isArray(data.artifacts)) nextData.artifacts = kept; return nextData; } +/** + * Whether one script artifact names a revision newer than every accepted revision of its + * publication, claiming it for this response so a duplicate of it earns no download either. + */ +function isNewerVersion(artifact: DaemonArtifact, revisions: ScriptRevisions): boolean { + const revision = artifact.scriptRevision; + if (!Number.isSafeInteger(revision) || (revision as number) <= 0) return false; + const publicationId = artifact.scriptPublicationId ?? ''; + for (const accepted of revisions) { + if (!accepted.startsWith(`${publicationId}:`)) continue; + if ((revision as number) <= Number(accepted.slice(publicationId.length + 1))) return false; + } + revisions.add(`${publicationId}:${revision}`); + return true; +} + +function newestScriptVersion(candidates: readonly DaemonArtifact[]): DaemonArtifact | undefined { + let newest: DaemonArtifact | undefined; + for (const candidate of candidates) { + if ( + newest === undefined || + (candidate.scriptRevision as number) > (newest.scriptRevision as number) + ) { + newest = candidate; + } + } + return newest; +} + +/** + * Lifts the steps' disclosure onto the batch payload, the channel every caller surface reads: the + * CLI's `Warning:` lines, the MCP tool text, and `--json` and structured content all take the batch's + * own `warnings` and `scriptDeliveryFailure`, which a step's nested data cannot reach. + */ +export function withBatchDisclosure( + data: Record | undefined, + disclosure: BatchDisclosure | undefined, +): Record { + if (!disclosure) return {}; + const warnings = [ + ...new Set([...readResponseWarnings(data), ...disclosure.warnings].filter((w) => w !== '')), + ]; + return { + ...(warnings.length > 0 ? { warnings } : {}), + ...(disclosure.failure !== undefined ? { scriptDeliveryFailure: disclosure.failure } : {}), + }; +} + +function collectBatchDisclosure(disclosure: BatchDisclosure, data: Record): void { + for (const warning of readResponseWarnings(data)) { + if (!disclosure.warnings.includes(warning)) disclosure.warnings.push(warning); + } + const failure = data.scriptDeliveryFailure; + if (disclosure.failure === undefined && isRecord(failure)) disclosure.failure = failure; +} + +const CLOSE_COMMAND = 'close'; + function readBatchResults(data: unknown): ReadonlyArray> { if (!isRecord(data) || !Array.isArray(data.results)) return []; return data.results.filter((result): result is Record => isRecord(result)); } - -function readString(value: unknown): string | undefined { - return typeof value === 'string' && value.length > 0 ? value : undefined; -} diff --git a/test/integration/provider-scenarios/remote-script-publication.test.ts b/test/integration/provider-scenarios/remote-script-publication.test.ts index 637c569582..9e46dedc64 100644 --- a/test/integration/provider-scenarios/remote-script-publication.test.ts +++ b/test/integration/provider-scenarios/remote-script-publication.test.ts @@ -461,32 +461,10 @@ test('the SDK, the CLI and MCP each disclose a failed final script delivery', as await withProviderScenarioResource(createAndroidSettingsWorld, async (world) => { const root = mkdtempForTestSync('remote-script-surfaces-'); const proxy = await createProviderScenarioProxy(world.daemon, { clientToken: 'script-client' }); - const upstream = new URL(proxy.baseUrl); let refuseArtifacts = false; - const gate = http.createServer((req, res) => { - if (refuseArtifacts && req.url?.includes('/artifacts/')) { - res.writeHead(503).end('unavailable'); - return; - } - const forwarded = http.request( - { - host: upstream.hostname, - port: upstream.port, - method: req.method, - path: req.url, - headers: req.headers, - }, - (reply) => { - res.writeHead(reply.statusCode ?? 502, reply.headers); - reply.pipe(res); - }, - ); - forwarded.on('error', () => res.destroy()); - req.pipe(forwarded); - }); - const gateUrl = `http://127.0.0.1:${await listenOnLoopback(gate)}${upstream.pathname}`; + const gate = await createArtifactGate(proxy.baseUrl, () => refuseArtifacts); const remoteEnv = { - AGENT_DEVICE_DAEMON_BASE_URL: gateUrl, + AGENT_DEVICE_DAEMON_BASE_URL: gate.baseUrl, AGENT_DEVICE_DAEMON_AUTH_TOKEN: 'script-client', AGENT_DEVICE_DAEMON_TRANSPORT: 'http', }; @@ -502,7 +480,7 @@ test('the SDK, the CLI and MCP each disclose a failed final script delivery', as const sdkStateDir = path.join(root, 'sdk-state'); const sdkFile = path.join(root, 'sdk.ad'); const sdk = createAgentDeviceClient({ - daemonBaseUrl: gateUrl, + daemonBaseUrl: gate.baseUrl, daemonAuthToken: 'script-client', session: 'sdk-surfaces', stateDir: sdkStateDir, @@ -626,7 +604,7 @@ test('the SDK, the CLI and MCP each disclose a failed final script delivery', as assert.doesNotMatch(fs.readFileSync(mcpFile, 'utf8'), /^close/m); world.assertNoHostAdbCalls(); } finally { - await closeLoopbackServer(gate); + await gate.close(); await proxy.close(); } }); @@ -681,3 +659,228 @@ test('a remote batch delivers its step scripts and a close step ends the recordi } }); }, 20_000); + +/** + * A batch reports one entry per step, so a step whose script did not arrive is disclosure a caller + * surface would never read on its own (#4564 review). The client lifts the step's warning and typed + * failure onto the batch's own payload, which is the channel the CLI and the MCP tool text read. + */ +test('the CLI and MCP each disclose a failed script delivery of a batch step', async () => { + await withProviderScenarioResource(createAndroidSettingsWorld, async (world) => { + const root = mkdtempForTestSync('remote-script-batch-surfaces-'); + const proxy = await createProviderScenarioProxy(world.daemon, { clientToken: 'script-client' }); + let refuseArtifacts = false; + const gate = await createArtifactGate(proxy.baseUrl, () => refuseArtifacts); + const remoteEnv = { + AGENT_DEVICE_DAEMON_BASE_URL: gate.baseUrl, + AGENT_DEVICE_DAEMON_AUTH_TOKEN: 'script-client', + AGENT_DEVICE_DAEMON_TRANSPORT: 'http', + }; + const steps = JSON.stringify([ + { command: 'wait', input: { selector: 'label="Apps"', ...world.selection } }, + { command: 'close', input: {} }, + ]); + const cli = (argv: string[], stateDir: string) => + runCliCapture(argv, { + cwd: root, + env: { ...remoteEnv, AGENT_DEVICE_STATE_DIR: stateDir }, + useRealDaemonClient: true, + }); + try { + // The CLI for a human: the batch's own lines carry the step's warning. + const humanStateDir = path.join(root, 'cli-human-state'); + const humanFile = path.join(root, 'cli-batch.ad'); + const humanOpen = await cli( + [ + 'open', + 'settings', + '--session', + 'cli-batch', + '--save-script', + humanFile, + '--platform', + world.selection.platform, + '--serial', + world.selection.serial, + ], + humanStateDir, + ); + assert.equal(humanOpen.code, null, humanOpen.stderr); + refuseArtifacts = true; + const humanBatch = await cli( + ['batch', '--steps', steps, '--session', 'cli-batch'], + humanStateDir, + ); + refuseArtifacts = false; + assert.equal(humanBatch.code, null, humanBatch.stderr); + assert.match(`${humanBatch.stdout}${humanBatch.stderr}`, /Warning: .*script/i); + + // The CLI and MCP machine views: the typed failure rides the batch payload itself. + const jsonStateDir = path.join(root, 'cli-json-state'); + const jsonFile = path.join(root, 'cli-batch-json.ad'); + const jsonOpen = await cli( + [ + 'open', + 'settings', + '--json', + '--session', + 'cli-batch-json', + '--save-script', + jsonFile, + '--platform', + world.selection.platform, + '--serial', + world.selection.serial, + ], + jsonStateDir, + ); + assert.equal(jsonOpen.code, null, jsonOpen.stderr); + refuseArtifacts = true; + const jsonBatch = await cli( + ['batch', '--steps', steps, '--json', '--session', 'cli-batch-json'], + jsonStateDir, + ); + refuseArtifacts = false; + assert.equal(jsonBatch.code, null, jsonBatch.stderr); + const payload = JSON.parse(jsonBatch.stdout); + assert.equal(payload.success, true, jsonBatch.stdout); + assert.equal(payload.data.scriptDeliveryFailure.reason, 'script_delivery_failed'); + assert.ok( + payload.data.warnings.some((warning: string) => + warning.includes(payload.data.scriptDeliveryFailure.hint), + ), + jsonBatch.stdout, + ); + + const mcpStateDir = path.join(root, 'mcp-state'); + const mcpFile = path.join(root, 'mcp-batch.ad'); + const restoreEnv = installIsolatedCliTestEnv({ + ...remoteEnv, + AGENT_DEVICE_STATE_DIR: mcpStateDir, + }); + try { + const executor = createCommandToolExecutor({ structuredContent: 'always' }); + const mcpOpen = await executor.execute('open', { + app: 'settings', + session: 'mcp-batch', + saveScript: mcpFile, + ...world.selection, + }); + assert.equal(mcpOpen.isError, false, JSON.stringify(mcpOpen)); + refuseArtifacts = true; + const mcpBatch = await executor.execute('batch', { + session: 'mcp-batch', + steps: [ + { command: 'wait', input: { selector: 'label="Apps"', ...world.selection } }, + { command: 'close', input: {} }, + ], + }); + refuseArtifacts = false; + assert.equal(mcpBatch.isError, false, JSON.stringify(mcpBatch)); + assert.match( + mcpBatch.content.map((part) => part.text ?? '').join('\n'), + /Warning: .*script/i, + ); + assert.equal( + (mcpBatch.structuredContent as { scriptDeliveryFailure?: { reason?: string } }) + ?.scriptDeliveryFailure?.reason, + 'script_delivery_failed', + ); + } finally { + restoreEnv(); + } + world.assertNoHostAdbCalls(); + } finally { + await gate.close(); + await proxy.close(); + } + }); +}, 40_000); + +/** + * A batch that FAILS after a step closed the recording still owes the caller the final script and + * the end of the recording (#4564 review): the steps that finished ride the error's `partialResults` + * and are delivered before the batch error reaches the caller, which keeps its own failure. + */ +test('a failed remote batch delivers the finished close step and keeps its error', async () => { + await withProviderScenarioResource(createAndroidSettingsWorld, async (world) => { + const root = mkdtempForTestSync('remote-script-batch-failure-'); + const destination = path.join(root, 'journey.ad'); + const stateDir = path.join(root, 'client-state'); + const proxy = await createProviderScenarioProxy(world.daemon, { clientToken: 'script-client' }); + const client = createAgentDeviceClient({ + daemonBaseUrl: proxy.baseUrl, + daemonAuthToken: 'script-client', + session: 'batch-failure', + stateDir, + }); + const records = path.join(stateDir, 'remote-connections', 'session-scripts'); + try { + await client.apps.open({ app: 'settings', saveScript: destination, ...world.selection }); + + // The close ends the recording, so the last step has no session to act on and fails. + const failure = await client.batch + .run({ + steps: [ + { command: 'wait', input: { selector: 'label="Apps"', ...world.selection } }, + { command: 'close', input: {} }, + { command: 'back', input: {} }, + ], + }) + .catch((error: unknown) => error); + + const error = failure as { code?: string; message?: string; details?: Record }; + assert.equal(error.code, 'SESSION_NOT_FOUND', JSON.stringify(error)); + assert.match(String(error.message), /Batch failed at step 3/); + assert.equal(error.details?.step, 3); + // The close step's script reached the caller file and the record is retired, all the same. + const final = fs.readFileSync(destination, 'utf8'); + assert.match(final, /^wait /m); + assert.match(final, /^close/m); + assert.deepEqual( + fs.readdirSync(records).filter((name) => name.endsWith('.json')), + [], + ); + world.assertNoHostAdbCalls(); + } finally { + await client.sessions.close().catch(() => undefined); + await proxy.close(); + } + }); +}, 40_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. + */ +async function createArtifactGate( + upstreamUrl: string, + refused: () => boolean, +): Promise<{ baseUrl: string; close(): Promise }> { + const upstream = new URL(upstreamUrl); + const gate = http.createServer((req, res) => { + if (refused() && req.url?.includes('/artifacts/')) { + res.writeHead(503).end('unavailable'); + return; + } + const forwarded = http.request( + { + host: upstream.hostname, + port: upstream.port, + method: req.method, + path: req.url, + headers: req.headers, + }, + (reply) => { + res.writeHead(reply.statusCode ?? 502, reply.headers); + reply.pipe(res); + }, + ); + forwarded.on('error', () => res.destroy()); + req.pipe(forwarded); + }); + return { + baseUrl: `http://127.0.0.1:${await listenOnLoopback(gate)}${upstream.pathname}`, + close: () => closeLoopbackServer(gate), + }; +} diff --git a/test/wire-compat/ledger.json b/test/wire-compat/ledger.json index 4a5f95a0a3..fad1e789e2 100644 --- a/test/wire-compat/ledger.json +++ b/test/wire-compat/ledger.json @@ -63,7 +63,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:8d3d5a0e8a69c38b1087fddef15247e2b7101b5b5dfe45dac950bdc910459224", "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", @@ -443,8 +443,8 @@ }, { "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." + "digest": "sha256:8d3d5a0e8a69c38b1087fddef15247e2b7101b5b5dfe45dac950bdc910459224", + "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. #4564 (client-side only): before a failed remote batch's error is rehydrated, the client delivers the session scripts of the steps that finished, which the daemon already reported in the error's existing `partialResults`, and adds its own `warnings` and `scriptDeliveryFailure` to that record. Nothing new is required of a peer and nothing it sends is read differently; the delivery is one more artifact download on the route clients already use." }, { "declaration": "packages/remote/src/upload-client.ts#uploadDirectArtifact", diff --git a/website/docs/docs/remote-proxy.md b/website/docs/docs/remote-proxy.md index 6868918c9c..63d2a15be2 100644 --- a/website/docs/docs/remote-proxy.md +++ b/website/docs/docs/remote-proxy.md @@ -123,7 +123,10 @@ recorded a version discloses it: the CLI prints a `Warning:` line and carries a Remote `session save-script`, `close --save-script`, `replay --save-script`, and `--save-script` in batch steps are refused. A `batch` delivers the script versions its steps record, in step order, and -a `close` step retires the recording the same way a standalone `close` does. +a `close` step retires the recording the same way a standalone `close` does. When a later step fails, +the steps that already ran still deliver their scripts, and the batch error stands. A step whose +script did not arrive is reported once more on the batch result itself, so the `Warning:` line and +the `scriptDeliveryFailure` field reach the batch output rather than only the step's own entry. Direct RPC callers send `saveScript: true` with a random `meta.scriptPublicationId` of 16 to 64 letters, digits, or hyphens. Each script artifact carries that `scriptPublicationId` and a From 32bf7b15db6f23326c0dc0a47f5589813d7d2b60 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Mon, 16 Nov 2026 11:48:06 +0100 Subject: [PATCH 3/5] fix(remote): deliver one script version per batch, on the plan's prefix A batch answer is untrusted input, and the per-step delivery path read it step by step. A failing step's report could carry successful entries for steps that never ran, so a forged partial result retired a close the caller never ran. A malformed publication ID threw while it was interpolated, which turned a successful batch into a client failure. Filtering revisions re-scanned every earlier version, so a large answer blocked the caller. And a successful batch whose steps carried no script stopped before its own payload, leaving the caller's file stale behind a newer version the daemon had stamped. Deliver at most ONE version per batch. Every version is the whole recording, so only the newest of the open publication matters: one linear, bounded scan reads the plan's finished steps and the batch payload and keeps that one, and one delivery goes through the session-script owner. Derive the completed prefix from the submitted plan and cross-check it against the step and executed count the error names, so entries at or after the failure authorize no download and no retirement. Retire only when that prefix contains the close step, with or without an artifact. Validate each candidate with the publisher's own guards, so no response value reaches a record lookup, a path, or a download request. Reports #4564 review findings 1 to 5. Co-Authored-By: Claude Opus 5.5 --- .../0016-active-session-script-publication.md | 8 +- .../src/__tests__/daemon-client-rpc.test.ts | 71 +++ .../daemon-artifacts-batch-script.test.ts | 273 +++++++--- packages/remote/src/daemon-artifacts.ts | 78 ++- .../src/remote-batch-script-delivery.ts | 481 +++++++++--------- test/wire-compat/ledger.json | 6 +- website/docs/docs/remote-proxy.md | 11 +- website/docs/docs/replay-e2e.md | 2 +- 8 files changed, 579 insertions(+), 351 deletions(-) diff --git a/docs/adr/0016-active-session-script-publication.md b/docs/adr/0016-active-session-script-publication.md index 3b2b4e7217..802536c686 100644 --- a/docs/adr/0016-active-session-script-publication.md +++ b/docs/adr/0016-active-session-script-publication.md @@ -204,10 +204,10 @@ 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 delivers the script versions its steps record, in step order, and a batch step that closes the recording retires the caller record like a standalone close does. - The submitted plan is the only authority for that delivery: an answer entry that is not the plan's own step at its own position, or that is not a step that finished, gets no download and no retirement, and one answer earns at most one download per submitted step. - The steps that finished of a FAILED batch are delivered too, from the error's `partialResults`, and the batch error stands. - A step's delivery warning and typed failure also ride the batch payload itself, because a batch's human and machine output read only that payload. + A batch delivers the newest version its answer names, wherever it names it, and a batch that closes the recording retires the caller record like a standalone close does. Every version is the full recording, so one batch costs at most one download. + The submitted plan is the only authority for that delivery: a completed prefix is derived from it, an answer entry outside that prefix or naming another command gets no download, and a retirement follows only a close the plan itself ran and finished. + The steps that finished of a FAILED batch are delivered too, from the error's `partialResults`, cross-checked against the failing step the error names, and the batch error stands. + A delivery warning and typed failure ride the batch payload itself, because a batch's human and machine output read only that payload. - 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). diff --git a/packages/daemon-client/src/__tests__/daemon-client-rpc.test.ts b/packages/daemon-client/src/__tests__/daemon-client-rpc.test.ts index 270bd70caa..9b2d3597fa 100644 --- a/packages/daemon-client/src/__tests__/daemon-client-rpc.test.ts +++ b/packages/daemon-client/src/__tests__/daemon-client-rpc.test.ts @@ -365,6 +365,77 @@ test('a failed remote batch delivers nothing for a step the caller never submitt } }); +/** + * A failed batch reports the step that failed and how many steps ran. The runner puts an entry in + * `partialResults` ONLY for a step it finished before the failure, so successful entries for steps at + * or after the reported failure describe work that never happened. Neither a download nor the end of + * the caller's recording may follow from them: `[wait, close, snapshot]` that reports step 3 after 0 + * executed steps still owes the caller its file and its record. + */ +test('a failed remote batch whose step report disagrees with its entries delivers nothing', async () => { + const server = scriptServer({ v1: 'open Demo\n', final: 'open Demo\nwait 100\nclose\n' }); + const baseUrl = `http://127.0.0.1:${await listenOnLoopback(server)}`; + const root = fs.realpathSync(mkdtempForTestSync('rpc-batch-forged-')); + const stateDir = path.join(root, 'state'); + const destination = path.join(root, 'journey.ad'); + const host = createTestHostEnvironment(); + try { + const publicationId = await openRemoteRecording(baseUrl, stateDir, destination); + + let rejected: unknown; + await new Promise((resolve) => { + handleDaemonHttpResponseBody( + JSON.stringify({ + error: { + data: { + code: 'COMMAND_FAILED', + message: 'Batch failed at step 3 (snapshot): snapshot failed', + details: { + // Says nothing finished, and attaches a finished close of this client's publication. + step: 3, + command: 'snapshot', + executed: 0, + total: 3, + partialResults: [ + { step: 1, command: 'wait', ok: true, durationMs: 1, data: { waited: true } }, + { + step: 2, + command: 'close', + ok: true, + durationMs: 1, + data: { + scriptPublicationId: publicationId, + artifacts: [scriptArtifact('final', 2, publicationId)], + }, + }, + ], + }, + }, + }, + }), + { + info: { token: 'daemon-token', pid: 1, baseUrl }, + req: batchRequest('wait', 'close', 'snapshot'), + stateDir, + host, + resolve: () => resolve(), + reject: (error) => { + rejected = error; + resolve(); + }, + }, + ); + }); + + assert.ok(rejected instanceof AppError, `Expected the batch error, got ${String(rejected)}`); + // A close the caller never ran writes nothing and retires nothing. + assert.equal(fs.readFileSync(destination, 'utf8'), 'open Demo\n'); + assert.equal(activeScriptRecords(stateDir).length, 1); + } finally { + await closeLoopbackServer(server); + } +}); + function batchRequest(...commands: string[]): DaemonWireRequest { return { token: 'daemon-token', diff --git a/packages/remote/src/__tests__/daemon-artifacts-batch-script.test.ts b/packages/remote/src/__tests__/daemon-artifacts-batch-script.test.ts index c14f308dba..80699d3fd2 100644 --- a/packages/remote/src/__tests__/daemon-artifacts-batch-script.test.ts +++ b/packages/remote/src/__tests__/daemon-artifacts-batch-script.test.ts @@ -144,7 +144,7 @@ function expectDeliveredNothing(response: DaemonResponse): void { expect(text).not.toContain('"scriptDeliveryFailure":'); } -test('a batch delivers each step script in step order and a close step retires the record', async () => { +test('a batch delivers its newest script once and a close step retires the record', async () => { const { stateDir, destination } = journey(); const baseUrl = await artifactServer({ v1: 'open Demo\n', @@ -169,33 +169,22 @@ test('a batch delivers each step script in step order and a close step retires t }, ); + // Every version is the whole recording, so ONE download is owed: the newest of the batch. expect(fs.readFileSync(destination, 'utf8')).toBe('open Demo\nwait 100\nclose\n'); // The terminal step retired the record, so no later version of that publication writes anything. expect(records(stateDir)).toEqual([]); - // Each step reports its own version the way the same command alone would: its `savedScript` names - // the caller file, and its artifact carries the local path the client published. - const steps = batchSteps(response); - expect(steps.map((result) => result.command)).toEqual(['wait', 'close']); - expect(steps.map((result) => result.data.savedScript)).toEqual([destination, destination]); - expect(steps.map((result) => result.data.artifacts)).toEqual([ - [ - expect.objectContaining({ - artifactId: 'v2', - scriptRevision: 2, - localPath: destination, - }), - ], - [ - expect.objectContaining({ - artifactId: 'v3', - scriptRevision: 3, - localPath: destination, - }), - ], + // The batch's own payload says where the recording landed, the way a single response does. + expect(response.ok && response.data?.savedScript).toBe(destination); + // The steps are reported exactly as the daemon answered them: this client writes its own fields, not + // the daemon's entries. + expect(batchSteps(response).map((result) => result.command)).toEqual(['wait', 'close']); + expect(batchSteps(response).map((result) => result.data.artifacts)).toEqual([ + [expect.objectContaining({ artifactId: 'v2', scriptRevision: 2 })], + [expect.objectContaining({ artifactId: 'v3', scriptRevision: 3 })], ]); }); -test('a batch step whose download fails discloses the failure on that step and keeps the batch', async () => { +test('a batch script whose download fails discloses the failure and keeps the batch', async () => { const { stateDir, destination } = journey(); const baseUrl = await artifactServer({ v1: 'open Demo\n' }); const id = await open(baseUrl, stateDir, destination); @@ -207,25 +196,24 @@ test('a batch step whose download fails discloses the failure on that step and k results: [step(1, 'wait', { waited: true, artifacts: [script('gone', 2, id)] })], }); - // The step ran on the device, so the batch stands and the step says the caller file is stale. + // The step ran on the device, so the batch stands and the batch payload says the file is stale. expect(response.ok).toBe(true); + expect(response.ok && response.data?.scriptDeliveryFailure).toEqual( + expect.objectContaining({ + reason: 'script_delivery_failed', + cause: 'script_download_failed', + publicationId: id, + }), + ); + expect(response.ok && response.data?.warnings).toEqual([expect.stringContaining('script')]); + // The step's own entry is the daemon's answer, and a daemon-host path or status never rides along. expect(batchSteps(response)[0]).toEqual({ step: 1, command: 'wait', ok: true, durationMs: 1, - data: expect.objectContaining({ - waited: true, - artifacts: [], - scriptDeliveryFailure: expect.objectContaining({ - reason: 'script_delivery_failed', - cause: 'script_download_failed', - publicationId: id, - }), - warnings: [expect.stringContaining('script')], - }), + data: { waited: true, artifacts: [expect.objectContaining({ artifactId: 'gone' })] }, }); - // A daemon-host path or status never rides along in the disclosure. expect(JSON.stringify(response)).not.toContain('unavailable'); expect(fs.readFileSync(destination, 'utf8')).toBe('open Demo\n'); // The recording is not closed, so the record stays and a later version still lands. @@ -252,12 +240,10 @@ test('a batch that closes keeps its success and retires the record when the fina }); // The session closed, so the record is gone even though the final script did not arrive. - expect(batchSteps(response)[0]?.data).toEqual( + expect(response.ok && response.data?.scriptDeliveryFailure).toEqual( expect.objectContaining({ - scriptDeliveryFailure: expect.objectContaining({ - cause: 'script_download_failed', - publicationId: id, - }), + cause: 'script_download_failed', + publicationId: id, }), ); expect(fs.readFileSync(destination, 'utf8')).toBe('open Demo\n'); @@ -293,10 +279,8 @@ test('a batch step script of another publication or of another field writes noth }, ); - expect(batchSteps(response).map((result) => result.data)).toEqual([ - { artifacts: [] }, - { artifacts: [] }, - ]); + expectDeliveredNothing(response); + expect(batchSteps(response).map((result) => result.step)).toEqual([1, 2]); expect(fs.readFileSync(destination, 'utf8')).toBe('open Demo\n'); expect(fs.existsSync(victim)).toBe(false); }); @@ -432,17 +416,22 @@ test('a batch request that submitted no plan delivers nothing from its step entr expect(fs.readFileSync(destination, 'utf8')).toBe('open Demo\n'); }); -test('one batch answer asks for one download per step, whatever versions it names', async () => { +test('one batch answer asks for ONE download, whatever versions it names', async () => { const { stateDir, destination } = journey(); const requested: string[] = []; + const bodies: Record = { + v1: 'open Demo\n', + v3: 'open Demo\nwait 100\n', + v5: 'open Demo\nwait 100\nsnapshot\n', + }; const server = http.createServer((req, res) => { const id = decodeURIComponent(req.url?.replace('/artifacts/', '') ?? ''); requested.push(id); - if (id !== 'v3' && id !== 'v5') { + const body = bodies[id]; + if (body === undefined) { res.writeHead(503).end('unavailable'); return; } - const body = id === 'v3' ? 'open Demo\nwait 100\n' : 'open Demo\nwait 100\nsnapshot\n'; res.writeHead(200, { 'content-length': Buffer.byteLength(body) }); res.end(body); }); @@ -451,26 +440,188 @@ test('one batch answer asks for one download per step, whatever versions it name const id = await open(baseUrl, stateDir, destination); requested.length = 0; - // One answer names every version of every step at once, including duplicates and versions older - // than one it already named. None of that may turn into one request each. + // One answer names the same versions over and over, including ones older than the newest it names. + // Every version is the whole recording, so exactly one of them is owed: the newest. const repeats = (artifactId: string, revision: number, times: number) => Array.from({ length: times }, () => script(artifactId, revision, id)); - await answer(baseUrl, stateDir, request('batch', {}, batchPlan('wait', 'snapshot')), { - total: 2, - executed: 2, + const response = await answer( + baseUrl, + stateDir, + request('batch', {}, batchPlan('wait', 'snapshot')), + { + total: 2, + executed: 2, + totalDurationMs: 1, + results: [ + step(1, 'wait', { artifacts: [...repeats('v3', 3, 3), ...repeats('v1', 1, 2)] }), + step(2, 'snapshot', { artifacts: [script('v3', 3, id), script('v5', 5, id)] }), + ], + }, + ); + + expect(requested).toEqual(['v5']); + expect(response.ok && response.data?.savedScript).toBe(destination); + expect(fs.readFileSync(destination, 'utf8')).toBe('open Demo\nwait 100\nsnapshot\n'); +}); + +test('a batch reads at most its bound of script artifacts, whatever an answer names', async () => { + const { stateDir, destination } = journey(); + const requested: string[] = []; + const server = http.createServer((req, res) => { + const id = decodeURIComponent(req.url?.replace('/artifacts/', '') ?? ''); + requested.push(id); + res.writeHead(200, { 'content-length': Buffer.byteLength('open Demo\n') }); + res.end('open Demo\n'); + }); + servers.push(server); + const baseUrl = `http://127.0.0.1:${await listenOnLoopback(server)}`; + const id = await open(baseUrl, stateDir, destination); + requested.length = 0; + + // Ten step entries name a hundred script artifacts each, and the batch payload names a hundred more: + // 1,100 artifacts in one answer. The scan is bounded, and the caller is owed ONE download — the newest + // version, which the batch payload stamps after the last step and is always read first. + const many = (from: number) => + Array.from({ length: 100 }, (_, i) => script(`v-${from + i}`, from + i + 1, id)); + const results = Array.from({ length: 10 }, (_, stepIndex) => + step(stepIndex + 1, 'wait', { artifacts: many(stepIndex * 100) }), + ); + const response = await answer( + baseUrl, + stateDir, + request('batch', {}, batchPlan(...Array(10).fill('wait'))), + { + total: 10, + executed: 10, + totalDurationMs: 1, + scriptPublicationId: id, + artifacts: many(1000), + results, + }, + ); + + // Exactly one download, and it is the newest version the scan was allowed to keep. + expect(requested).toHaveLength(1); + expect(response.ok && response.data?.savedScript).toBe(destination); +}); + +test('a batch that names twenty thousand script versions still costs one bounded scan', async () => { + const { stateDir, destination } = journey(); + const requested: string[] = []; + const server = http.createServer((req, res) => { + const id = decodeURIComponent(req.url?.replace('/artifacts/', '') ?? ''); + requested.push(id); + res.writeHead(200, { 'content-length': Buffer.byteLength('open Demo\n') }); + res.end('open Demo\n'); + }); + servers.push(server); + const baseUrl = `http://127.0.0.1:${await listenOnLoopback(server)}`; + const id = await open(baseUrl, stateDir, destination); + requested.length = 0; + + // One answer names 20,000 versions of this publication, about 3 MB of JSON, in ascending order. + // Reading it costs this client a bounded scan, not one comparison per version it already saw. + const versions = Array.from({ length: 20_000 }, (_, i) => script(`v-${i}`, i + 1, id)); + const startedAt = Date.now(); + const response = await answer(baseUrl, stateDir, request('batch', {}, batchPlan('wait')), { + total: 1, + executed: 1, totalDurationMs: 1, - results: [ - step(1, 'wait', { - artifacts: [...repeats('gone', 2, 500), ...repeats('v3', 3, 2), ...repeats('gone', 1, 2)], - }), - step(2, 'snapshot', { - artifacts: [...repeats('gone', 4, 497), script('v5', 5, id), ...repeats('v3', 3, 2)], - }), - ], + results: [step(1, 'wait', { artifacts: versions })], }); - expect(requested).toEqual(['v3', 'v5']); - expect(fs.readFileSync(destination, 'utf8')).toBe('open Demo\nwait 100\nsnapshot\n'); + expect(Date.now() - startedAt).toBeLessThan(1000); + expect(requested).toHaveLength(1); + expect(response.ok && response.data?.savedScript).toBe(destination); +}); + +test('a successful batch delivers the newest version its own payload names', async () => { + const { stateDir, destination } = journey(); + const baseUrl = await artifactServer({ + v1: 'open Demo\n', + v9: 'open Demo\nsnapshot\n', + }); + const id = await open(baseUrl, stateDir, destination); + + // The caller ran plain steps whose answers carry nothing, and the daemon stamped its newest version + // on the batch payload itself, as it does after the last step of a recording. + const data = { + total: 1, + executed: 1, + totalDurationMs: 1, + scriptPublicationId: id, + artifacts: [script('v9', 9, id)], + results: [step(1, 'snapshot', { name: 'shot' })], + }; + const response = await answer( + baseUrl, + stateDir, + request('batch', {}, batchPlan('snapshot')), + data, + ); + + expect(response.ok && response.data?.savedScript).toBe(destination); + expect(fs.readFileSync(destination, 'utf8')).toBe('open Demo\nsnapshot\n'); + expect(records(stateDir)).toHaveLength(1); +}); + +test('a successful batch retires the record for a close its own payload names', async () => { + const { stateDir, destination } = journey(); + const baseUrl = await artifactServer({ + v1: 'open Demo\n', + v7: 'open Demo\nclose\n', + }); + const id = await open(baseUrl, stateDir, destination); + + // The plan ran `close`, and the answer names the publication on its own payload. A stale version the + // caller's file already holds may not be re-delivered, but the record still has to be retired. + const response = await answer(baseUrl, stateDir, request('batch', {}, batchPlan('close')), { + total: 1, + executed: 1, + totalDurationMs: 1, + scriptPublicationId: id, + artifacts: [script('v7', 7, id)], + results: [step(1, 'close', { closed: true })], + }); + + expect(response.ok && response.data?.savedScript).toBe(destination); + expect(fs.readFileSync(destination, 'utf8')).toBe('open Demo\nclose\n'); + expect(records(stateDir)).toEqual([]); +}); + +test('a malformed script publication ID is dropped and the batch still succeeds', async () => { + const { stateDir, destination } = journey(); + const baseUrl = await artifactServer({ v1: 'open Demo\n' }); + const id = await open(baseUrl, stateDir, destination); + + // Every ID and revision an answer carries is untrusted: an object that cannot become a string, a + // revision that is not a positive integer, and a missing artifact ID must all be dropped rather than + // reach a record lookup, a path, or a download request. + const malformed = (over: Record) => ({ + ...script('v2', 2, id), + ...over, + }); + const response = await answer( + baseUrl, + stateDir, + request('batch', {}, batchPlan('wait', 'wait', 'wait', 'wait')), + { + total: 4, + executed: 4, + totalDurationMs: 1, + results: [ + step(1, 'wait', { artifacts: [malformed({ scriptPublicationId: { toString: null } })] }), + step(2, 'wait', { artifacts: [malformed({ scriptRevision: '2' })] }), + step(3, 'wait', { artifacts: [malformed({ scriptRevision: 1.5 })] }), + step(4, 'wait', { artifacts: [malformed({ artifactId: { toString: null } })] }), + ], + }, + ); + + expect(response.ok).toBe(true); + expectDeliveredNothing(response); + expect(fs.readFileSync(destination, 'utf8')).toBe('open Demo\n'); + expect(records(stateDir)).toHaveLength(1); }); test('a batch step that cannot save its version discloses it on the batch payload', async () => { diff --git a/packages/remote/src/daemon-artifacts.ts b/packages/remote/src/daemon-artifacts.ts index 1ab24c3256..2bdb55ce86 100644 --- a/packages/remote/src/daemon-artifacts.ts +++ b/packages/remote/src/daemon-artifacts.ts @@ -8,7 +8,6 @@ import { buildRemoteTempArtifactPath, } from '@agent-device/contracts/daemon-http'; import { AppError } from '@agent-device/kernel/errors'; -import { isRecord } from '@agent-device/kernel/record'; import { resolveUserPath } from '@agent-device/host-kit/file'; import { leaseScopeFromRequest } from '@agent-device/contracts/lease-scope'; import { @@ -16,6 +15,7 @@ import { recordingExtensionForPlatform, } from '@agent-device/capture-kit/recording-output-path'; import { parsePerfRuntimeRequest } from '@agent-device/capture-kit/perf-runtime-plan'; +import type { DeliveryContext as BatchDeliveryContext } from './remote-batch-script-delivery.ts'; import type { SessionScriptDelivery } from './session-script-destination.ts'; import { uploadArtifact } from './upload-client.ts'; import { withUploadPreparationDeadline } from './upload-stream.ts'; @@ -483,14 +483,7 @@ export async function materializeRemoteArtifacts( // response untouched when no step carries a script. if (req.command === BATCH_COMMAND) { const { deliverRemoteBatchScripts } = await import('./remote-batch-script-delivery.ts'); - return await deliverRemoteBatchScripts( - endpoint, - req, - response, - stateDir, - downloadRemoteArtifact, - isSessionScriptArtifact, - ); + return await deliverRemoteBatchScripts(batchDeliveryContext(endpoint, req, stateDir), response); } const download = (scripts?: SessionScriptDelivery) => downloadResponseArtifacts(endpoint, req, response, host, scripts); @@ -506,17 +499,17 @@ export async function materializeRemoteArtifacts( } /** - * Delivers the session scripts of the steps a FAILED remote `batch` completed. + * Delivers the session script of the steps a FAILED remote `batch` had completed. * - * The runner reports the steps that finished in the error's `details.partialResults`, so a - * recording that an earlier step closed would otherwise be lost just because a later step failed — - * `[wait, close, snapshot]` that fails on `snapshot` would keep neither the final script nor the - * retirement of the caller's record. The steps are delivered under the plan THIS client submitted, - * exactly as in a successful batch, and the caller keeps its own error either way. + * The runner reports the finished steps in the error's `details.partialResults`, so a recording that an + * earlier step closed would be lost just because a later step failed. The completed prefix is derived + * from the plan THIS client submitted and cross-checked against the step the error names, so entries + * for steps at or after the failure authorize neither a download nor the retirement of the caller's + * record. The caller keeps its own error either way. * - * Answers the fields the error should disclose about that delivery — the steps' warnings and the - * first typed delivery failure — which a batch error's reader prints alongside the failure. Never - * throws: a request that the daemon answered still has to settle with its own error. + * Answers the fields the error should disclose about that delivery — the file it wrote, or a typed + * failure and its warning — which a batch error's reader prints alongside the failure. Never throws: a + * request the daemon answered still has to settle with its own error. */ export async function materializeRemoteBatchPartialArtifacts( info: DaemonArtifactEndpoint, @@ -524,43 +517,44 @@ export async function materializeRemoteBatchPartialArtifacts( details: Record | undefined, stateDir: string, ): Promise | undefined> { - const results = readSubmittedStepResults(details); - if (!info.baseUrl || req.command !== BATCH_COMMAND || results.length === 0) return undefined; + if (!info.baseUrl || req.command !== BATCH_COMMAND || !Array.isArray(details?.partialResults)) + return undefined; try { const { deliverSubmittedStepScripts, readBatchPlan, withBatchDisclosure } = await import('./remote-batch-script-delivery.ts'); - const delivered = await deliverSubmittedStepScripts( - { baseUrl: info.baseUrl, token: info.token }, - req, - stateDir, - downloadRemoteArtifact, - isSessionScriptArtifact, + const disclosure = await deliverSubmittedStepScripts( + batchDeliveryContext({ baseUrl: info.baseUrl, token: info.token }, req, stateDir), readBatchPlan(req), - results, + details, ); - return delivered.disclosure || delivered.results - ? { - ...details, - ...(delivered.results ? { partialResults: delivered.results } : {}), - ...withBatchDisclosure(details, delivered.disclosure), - } - : undefined; + return disclosure ? { ...details, ...withBatchDisclosure(details, disclosure) } : undefined; } catch { return undefined; } } -function readSubmittedStepResults( - details: Record | undefined, -): Array> { - const partialResults = details?.partialResults; - if (!Array.isArray(partialResults)) return []; - return partialResults.filter((result): result is Record => isRecord(result)); -} - /** Command name of the request that runs several steps under one response. */ const BATCH_COMMAND = 'batch'; +/** + * What the batch owner needs to deliver one payload: this client's endpoint and request, the file + * owner it writes under, and the two artifact helpers it may use. The owner never learns where a + * destination comes from; it is handed this client's own record of it. + */ +function batchDeliveryContext( + endpoint: Required, + req: DaemonWireRequest, + stateDir: string, +): BatchDeliveryContext { + return { + endpoint, + req, + stateDir, + download: downloadRemoteArtifact, + isScriptArtifact: isSessionScriptArtifact, + }; +} + async function downloadResponseArtifacts( endpoint: Required, req: DaemonWireRequest, diff --git a/packages/remote/src/remote-batch-script-delivery.ts b/packages/remote/src/remote-batch-script-delivery.ts index bb4ae93a74..ba6bd89eff 100644 --- a/packages/remote/src/remote-batch-script-delivery.ts +++ b/packages/remote/src/remote-batch-script-delivery.ts @@ -2,140 +2,69 @@ import type { DaemonWireRequest } from '@agent-device/contracts/command'; import type { DaemonArtifact, DaemonResponse } from '@agent-device/kernel/contracts'; import { isRecord } from '@agent-device/kernel/record'; import { readResponseWarnings } from '@agent-device/kernel/success-text'; -import { emitDiagnostic } from '@agent-device/host-kit/diagnostics'; import type { downloadRemoteArtifact } from './daemon-artifacts.ts'; -import type { SessionScriptDelivery } from './session-script-destination.ts'; /** - * Delivers the session scripts a successful `batch` answer carries, in step order, and reports what - * did not arrive on the batch's own payload. + * Delivers the session script a remote `batch` answer carries: AT MOST ONE version, the newest one + * this client's plan authorizes, wherever the answer names it — in a finished step's result or on the + * batch payload itself. * - * A step's `data` is what that command would have answered alone, so the session-script owner runs - * it under its own command name: a `close` step retires this client's record, and a step that only - * records a version leaves the record open for the next one. The batch's own payload carries the - * version the daemon stamped after the last step, so it is delivered last — after a closing step - * retired the record, which drops it instead of writing a stale one. The plan bound, the download - * bound and the destination rule are `deliverSubmittedStepScripts`' and `deliverPayloadScripts`' - * own, and the batch's answer is built from what they report. + * Every version is the whole recording from the `open`, so an older one is worth nothing and one batch + * never owes more than a single download. The batch's outcome is not changed here: a successful batch + * stays successful, a failed one keeps its own error, and a version that cannot be saved is reported + * the same way a single response reports it. + * + * The plan THIS client submitted is the only authority, never the answer. A step the caller never ran, + * or never finished, authorizes no download and no retirement, and a batch request that submitted no + * plan authorizes nothing at all. */ export async function deliverRemoteBatchScripts( - endpoint: Readonly<{ baseUrl: string; token: string }>, - req: DaemonWireRequest, + context: DeliveryContext, response: Extract, - stateDir: string, - download: typeof downloadRemoteArtifact, - isScriptArtifact: (artifact: DaemonArtifact | undefined) => boolean, ): Promise { - const plan = readBatchPlan(req); - const steps = await deliverSubmittedStepScripts( - endpoint, - req, - stateDir, - download, - isScriptArtifact, - plan, - readBatchResults(response.data), - ); - if (steps.results === undefined && steps.disclosure === undefined) return response; - const data = { - ...response.data, - ...(steps.results ? { results: steps.results } : {}), - ...withBatchDisclosure(response.data, steps.disclosure), - }; - // The batch's own payload last: it names the newest revision, and a closing step has already - // retired the record, so a script that arrived after the close is dropped rather than rewritten. - const deliveredPayload = await deliverPayloadScripts( - endpoint, - req, - stateDir, - download, - isScriptArtifact, - { command: req.command, data, revisions: steps.revisions }, - ); - return { ok: true, data: deliveredPayload ?? data }; + const data = isRecord(response.data) ? response.data : {}; + const plan = readBatchPlan(context.req); + const disclosure = await deliverBatchScript(context, plan, data, plan.length); + return disclosure === undefined + ? response + : { ok: true, data: { ...data, ...withBatchDisclosure(data, disclosure) } }; } /** - * Delivers the session scripts of one batch's successful steps, in order, and answers the delivered - * entries plus what the batch payload must disclose. - * - * The plan THIS client submitted is the only authority here, never the answer: an entry must be the - * plan's own command at the plan's own position and a step that finished. An entry that is anything - * else is reported exactly as the daemon answered it — no download, no destination, and no - * retirement — so a daemon cannot retire the caller record or spend the caller's downloads by naming - * a step the caller never ran. A batch request that submitted no plan authorizes nothing at all. + * Delivers the session script of the steps a FAILED remote `batch` had completed, and answers the + * fields its error should disclose about that delivery. * - * The successful steps of a FAILED batch reach this too: the runner reports them in - * `error.details.partialResults`, and a recording a completed step closed must still reach the caller - * file even though a later step failed. The caller keeps its own error either way. + * The runner reports the finished steps in the error's `details.partialResults`, so a recording that an + * earlier step closed would be lost just because a later step failed. The completed prefix is derived + * from the plan and cross-checked against the step the error names, so entries for steps at or after + * the failure — which the runner never produces — authorize neither a download nor the retirement of + * the caller's record. */ export async function deliverSubmittedStepScripts( - endpoint: Readonly<{ baseUrl: string; token: string }>, - req: DaemonWireRequest, - stateDir: string, - download: typeof downloadRemoteArtifact, - isScriptArtifact: (artifact: DaemonArtifact | undefined) => boolean, + context: DeliveryContext, plan: readonly string[], - results: ReadonlyArray>, -): Promise<{ - results?: Array>; - disclosure?: BatchDisclosure; - revisions: ScriptRevisions; -}> { - const nextResults: Array> = []; - const disclosure: BatchDisclosure = { warnings: [] }; - const revisions: ScriptRevisions = new Set(); - let touched = false; - for (const [index, result] of results.entries()) { - const plannedCommand = plan[index] ?? ''; - // An entry the plan does not authorize is reported exactly as the daemon answered it: no - // download, no destination, and no retirement. - if (plannedCommand === '' || !isSubmittedStep(result, plannedCommand, index)) { - emitDiagnostic({ - level: 'warn', - phase: 'session_script_batch_step_unauthorized', - data: { session: req.session, step: index + 1 }, - }); - nextResults.push(result); - continue; - } - const delivered = await deliverPayloadScripts( - endpoint, - req, - stateDir, - download, - isScriptArtifact, - { - command: plannedCommand, - // A copy: the session-script owner narrows the payload it is handed, and the daemon's own - // response object stays as it arrived. - data: isRecord(result.data) ? { ...result.data } : undefined, - revisions, - }, - ); - // A step's own disclosure rides the batch payload whether the daemon wrote it or this client did, - // and whether or not the step's payload itself changed. - collectBatchDisclosure( - disclosure, - isRecord(delivered) ? delivered : isRecord(result.data) ? result.data : {}, - ); - if (delivered === undefined) { - nextResults.push(result); - continue; - } - touched = true; - nextResults.push({ ...result, data: delivered }); - } - return { - ...(touched ? { results: nextResults } : {}), - ...(disclosure.warnings.length > 0 || disclosure.failure !== undefined ? { disclosure } : {}), - revisions, - }; + details: Record | undefined, +): Promise | undefined> { + return await deliverBatchScript( + context, + plan, + { results: details?.partialResults }, + readCompletedStepCount(plan, details), + ); } +/** What it takes to deliver one batch's script: this client's own endpoint, request and file owner. */ +export type DeliveryContext = Readonly<{ + endpoint: Readonly<{ baseUrl: string; token: string }>; + req: DaemonWireRequest; + stateDir: string; + download: typeof downloadRemoteArtifact; + isScriptArtifact: (artifact: DaemonArtifact | undefined) => boolean; +}>; + /** * The commands the caller submitted, in step order. A batch request with no plan authorizes nothing: - * with no way to tell a real step from a planted one, the answer's step entries are left alone. + * with no way to tell a real step from a planted one, the answer is left alone. */ export function readBatchPlan(req: DaemonWireRequest): string[] { const steps = req.flags?.batchSteps; @@ -143,180 +72,262 @@ export function readBatchPlan(req: DaemonWireRequest): string[] { return steps.map((step) => normalizeStepCommand(isRecord(step) ? step.command : undefined)); } -/** The versions of this response already taken past the owner, keyed publication and revision. */ -type ScriptRevisions = Set; +/** + * How many of the caller's steps had finished before a failure. The runner reports both the failing + * step's number and the number of steps it executed; the two must agree on one boundary before any + * step entry counts as finished, so a report that does not describe a step this client ran authorizes + * nothing. + */ +function readCompletedStepCount( + plan: readonly string[], + failure: Record | undefined, +): number { + if (failure === undefined) return plan.length; + const step = failure.step; + const executed = failure.executed; + if ( + typeof step !== 'number' || + typeof executed !== 'number' || + !Number.isSafeInteger(step) || + !Number.isSafeInteger(executed) || + step < 1 || + executed < 0 || + step !== executed + 1 + ) + return 0; + return Math.min(executed, plan.length); +} -/** What a batch's steps disclose: every step's warning text, and the first typed failure. */ -type BatchDisclosure = { - warnings: string[]; - failure?: Record; -}; +/** One plan step this client ran and finished, with the payload the daemon answered for it. */ +type FinishedStep = Readonly<{ command: string; data: Record | undefined }>; /** - * Whether one answer entry is the plan's own step at the plan's own position. The runner records the - * step's number and command on its result, so an entry must name the plan's command at that position - * and must be a step that finished successfully. + * The plan's own finished steps within the completed prefix, in plan order. Only the prefix is read, so + * the work is bounded by the plan the caller submitted rather than by what the answer carries. An entry + * that is not the plan's own command at the plan's own position, or that did not finish, is not + * authorized and is never read for a script. */ -function isSubmittedStep( - result: Record, +function readFinishedSteps( + data: Record, + plan: readonly string[], + completed: number, +): FinishedStep[] { + const results = Array.isArray(data.results) ? data.results : []; + const finished: FinishedStep[] = []; + for (let index = 0; index < completed; index += 1) { + const command = plan[index] ?? ''; + const result = results[index]; + if (isFinishedStep(result, command, index)) + finished.push({ command, data: isRecord(result.data) ? result.data : undefined }); + } + return finished; +} + +function isFinishedStep( + result: unknown, plannedCommand: string, index: number, -): boolean { +): result is Record { return ( + plannedCommand !== '' && + isRecord(result) && result.step === index + 1 && - normalizeStepCommand(result.command) === plannedCommand && - result.ok === true + result.ok === true && + normalizeStepCommand(result.command) === plannedCommand ); } -function normalizeStepCommand(command: unknown): string { - return typeof command === 'string' ? command.trim().toLowerCase() : ''; -} - /** - * Delivers one payload's session-script artifacts — a step's result or the batch's own data — or - * answers `undefined` when there is nothing here for this client to deliver. + * Delivers the newest version this batch is owed, or answers `undefined` when it is owed none. * - * The payload keeps the batch request's own endpoint, tenant and session, which is what lets it - * reach the record that armed the recording, and takes the command name the plan gives that step, - * which is what makes a terminal `close` retire that record. A `close` that names this client's - * publication goes through the owner even when it carries no artifact: the daemon may have failed to - * write the final version, and the caller still has to stop tracking a recording it no longer has. + * The session-script owner stays the only owner of `savedScript`, of the destination rule and of the + * retirement, and it is handed a payload of its own rather than the caller's response: the batch's + * payload is the daemon's answer, and what the delivery produced is merged onto it afterwards. The + * owner is asked under `close` when the plan ran a close, which is what lets it publish the final + * version and then retire this client's record exactly as a single `close` response does — including + * when the close carried no version, because the daemon may have failed to write it and the caller + * still has to stop tracking a recording it no longer has. */ -async function deliverPayloadScripts( - endpoint: Readonly<{ baseUrl: string; token: string }>, - req: DaemonWireRequest, - stateDir: string, - download: typeof downloadRemoteArtifact, - isScriptArtifact: (artifact: DaemonArtifact | undefined) => boolean, - payload: Readonly<{ - command: string; - data: Record | undefined; - revisions: ScriptRevisions; - }>, +async function deliverBatchScript( + context: DeliveryContext, + plan: readonly string[], + data: Record, + completed: number, ): Promise | undefined> { - const data = payload.data; - if (!data) return undefined; - const artifacts = Array.isArray(data.artifacts) ? data.artifacts : []; - const closing = payload.command === CLOSE_COMMAND; - const scriptCount = artifacts.filter((artifact) => - isScriptArtifact(artifact as DaemonArtifact), - ).length; - // A step's `data` is what that command would have answered on its own, so the session-script owner - // is the only owner of `savedScript` and of the retirement a close names. - const retires = closing && typeof data.scriptPublicationId === 'string'; - if (scriptCount === 0 && !retires) return undefined; + if (plan.length === 0 || completed < 1) return undefined; + const steps = readFinishedSteps(data, plan, completed); + const closing = steps.some((step) => step.command === CLOSE_COMMAND); + const versions = readScriptVersions(context, steps, data); + const publicationId = openPublicationId(steps, data, versions); + // Retirement follows the PLAN alone: a close this client ran and finished, and no field an answer + // carries. The owner finds this client's record by hashing the ID with its own endpoint, tenant and + // session, so an ID the daemon invents matches no record and retires nothing. + const retires = closing && typeof publicationId === 'string'; + const newest = newestScriptVersion(versions, publicationId); + if (newest === undefined && !retires) return undefined; const { sessionScriptDelivery } = await import('./session-script-destination.ts'); + const payload: Record = {}; + if (typeof publicationId === 'string') payload.scriptPublicationId = publicationId; const scripts = sessionScriptDelivery( - endpoint, - { ...req, command: payload.command }, - { ok: true, data }, - stateDir, - download, + context.endpoint, + { ...context.req, command: closing ? CLOSE_COMMAND : context.req.command }, + { ok: true, data: payload }, + context.stateDir, + context.download, ); - let published = data; await scripts.settleAfter(async () => { - published = await publishOwnedScripts(scripts, data, isScriptArtifact, payload.revisions); - return { ok: true, data: published }; + if (newest !== undefined) await scripts.publish(newest, payload, []); + return { ok: true, data: payload }; }); - return published === data ? undefined : published; + return disclosedDelivery(payload, steps); } /** - * Publishes the session-script artifacts of one payload and keeps every other artifact as the daemon - * answered it. Only the session-script owner owns `savedScript`; a payload's other artifacts are the - * daemon's own outputs, which the daemon already wrote on its side. - * - * Of several script artifacts in one payload, only the newest is delivered, and a version no newer - * than one already taken in this response is dropped before any request. Without that, one answer - * naming a thousand duplicate versions of one step would ask for a thousand downloads, and a version - * older than one already published would only be refused by the owner after its bytes arrived. + * Every session-script version this batch's answer carries, from the plan's finished steps AND the + * batch's own payload: a step may publish as it goes, and the daemon may stamp its newest version on + * the batch payload after the last step, so both are read whatever the other one holds. * - * Together with the plan bound, that caps one answer at one download per submitted step whatever it - * names, which is the budget a caller pays for one batch. + * One linear scan, bounded by MAX_SCRIPT_ARTIFACTS_PER_ENTRY artifacts per payload and + * MAX_SCRIPT_ARTIFACTS_PER_BATCH in total, so the cost stays bounded whatever an answer names. Each + * candidate must satisfy the same guards the publisher uses, so nothing this module cannot name is ever + * interpolated into a record lookup, a path, or a download request. */ -async function publishOwnedScripts( - scripts: SessionScriptDelivery, +function readScriptVersions( + context: DeliveryContext, + steps: readonly FinishedStep[], data: Record, - isScriptArtifact: (artifact: DaemonArtifact | undefined) => boolean, - revisions: ScriptRevisions, -): Promise> { - const nextData = { ...data }; - const kept: DaemonArtifact[] = []; - const candidates: DaemonArtifact[] = []; - const listed = Array.isArray(data.artifacts) ? (data.artifacts as DaemonArtifact[]) : []; - for (const artifact of listed) { - if (!isScriptArtifact(artifact)) { - kept.push(artifact); - continue; +): DaemonArtifact[] { + const versions: DaemonArtifact[] = []; + let scanned = 0; + // The batch's own payload is read first: the daemon stamps its newest version there after the last + // step, so the bound below keeps the version the caller is owed even by a crowded answer. + for (const payload of [data, ...steps.map((step) => step.data)]) { + const artifacts = Array.isArray(payload?.artifacts) + ? (payload.artifacts as DaemonArtifact[]) + : []; + for (const artifact of artifacts.slice(0, MAX_SCRIPT_ARTIFACTS_PER_ENTRY)) { + if (scanned >= MAX_SCRIPT_ARTIFACTS_PER_BATCH) return versions; + scanned += 1; + if (context.isScriptArtifact(artifact) && isUsableVersion(artifact)) versions.push(artifact); } - if (isNewerVersion(artifact, revisions)) candidates.push(artifact); } - const newest = newestScriptVersion(candidates); - if (newest !== undefined) await scripts.publish(newest, nextData, kept); - if (Array.isArray(data.artifacts)) nextData.artifacts = kept; - return nextData; + return versions; } /** - * Whether one script artifact names a revision newer than every accepted revision of its - * publication, claiming it for this response so a duplicate of it earns no download either. + * The publication this batch records, taken in order of authority: the ID the plan's own finished + * `close` step names, then the ID the first finished step names, then the ID the batch payload echoes, + * then the ID of the newest version the answer carries. Only versions of that one publication are + * delivered, and only a publication THIS client recorded can ever be published, so an ID the daemon + * invents costs no download and retires nothing. */ -function isNewerVersion(artifact: DaemonArtifact, revisions: ScriptRevisions): boolean { - const revision = artifact.scriptRevision; - if (!Number.isSafeInteger(revision) || (revision as number) <= 0) return false; - const publicationId = artifact.scriptPublicationId ?? ''; - for (const accepted of revisions) { - if (!accepted.startsWith(`${publicationId}:`)) continue; - if ((revision as number) <= Number(accepted.slice(publicationId.length + 1))) return false; - } - revisions.add(`${publicationId}:${revision}`); - return true; +function openPublicationId( + steps: readonly FinishedStep[], + data: Record, + versions: readonly DaemonArtifact[], +): string | undefined { + return [ + steps.find((step) => step.command === CLOSE_COMMAND)?.data?.scriptPublicationId, + steps.find((step) => typeof step.data?.scriptPublicationId === 'string')?.data + ?.scriptPublicationId, + data.scriptPublicationId, + newestScriptVersion(versions, undefined)?.scriptPublicationId, + ].find((id): id is string => typeof id === 'string'); } -function newestScriptVersion(candidates: readonly DaemonArtifact[]): DaemonArtifact | undefined { +/** + * The newest version of the open publication, or `undefined` when `publicationId` is not given and the + * newest version of any publication is wanted. Every version is the whole recording, so an older one is + * the same file with less of it: keeping only the newest is what makes one answer that names a thousand + * versions of one step, or of several steps, cost ONE download instead of a thousand. + */ +function newestScriptVersion( + versions: readonly DaemonArtifact[], + publicationId: string | undefined, +): DaemonArtifact | undefined { let newest: DaemonArtifact | undefined; - for (const candidate of candidates) { + for (const version of versions) { + if (publicationId !== undefined && version.scriptPublicationId !== publicationId) continue; if ( newest === undefined || - (candidate.scriptRevision as number) > (newest.scriptRevision as number) - ) { - newest = candidate; - } + (version.scriptRevision as number) > (newest.scriptRevision as number) + ) + newest = version; } return newest; } /** - * Lifts the steps' disclosure onto the batch payload, the channel every caller surface reads: the - * CLI's `Warning:` lines, the MCP tool text, and `--json` and structured content all take the batch's - * own `warnings` and `scriptDeliveryFailure`, which a step's nested data cannot reach. + * Whether one artifact names a version the publisher can act on: the guards `publishScriptVersion` + * uses. A malformed ID, revision or artifact ID is dropped here rather than reaching a record lookup, a + * download request, or an error message, and the response's own bytes never become a path component. + */ +function isUsableVersion(artifact: DaemonArtifact): boolean { + const revision = artifact.scriptRevision; + return ( + artifact.field === 'savedScript' && + typeof artifact.scriptPublicationId === 'string' && + typeof artifact.artifactId === 'string' && + Number.isSafeInteger(revision) && + (revision as number) > 0 + ); +} + +/** + * What one delivery and the plan's finished steps disclose on the caller's payload: the file that was + * written, and every script warning — the typed failure and its warning from this client's own + * delivery, and what the daemon disclosed on a step. A step's nested data reaches neither the CLI's + * `Warning:` lines nor the MCP tool text, so anything the caller has to see is lifted here. The + * daemon's answer itself is left intact. + */ +function disclosedDelivery( + payload: Record, + steps: readonly FinishedStep[], +): Record | undefined { + const failure = payload.scriptDeliveryFailure; + const disclosure: Record = {}; + if (payload.savedScript !== undefined) disclosure.savedScript = payload.savedScript; + if (isRecord(failure)) disclosure.scriptDeliveryFailure = failure; + const warnings = [ + ...new Set([ + ...readResponseWarnings(payload), + ...steps.flatMap((step) => readResponseWarnings(step.data)), + ]), + ].filter((warning) => warning !== ''); + if (warnings.length > 0) disclosure.warnings = warnings; + return Object.keys(disclosure).length > 0 ? disclosure : undefined; +} + +/** + * Lifts a batch's script disclosure onto the payload every caller surface reads: the CLI's `Warning:` + * lines, the MCP tool text, and `--json` and structured content all take the batch's own `warnings` and + * `scriptDeliveryFailure`, which a step's nested data cannot reach. */ export function withBatchDisclosure( data: Record | undefined, - disclosure: BatchDisclosure | undefined, + disclosure: Record | undefined, ): Record { if (!disclosure) return {}; const warnings = [ - ...new Set([...readResponseWarnings(data), ...disclosure.warnings].filter((w) => w !== '')), - ]; + ...new Set([...readResponseWarnings(data), ...readResponseWarnings(disclosure)]), + ].filter((warning) => warning !== ''); return { ...(warnings.length > 0 ? { warnings } : {}), - ...(disclosure.failure !== undefined ? { scriptDeliveryFailure: disclosure.failure } : {}), + ...(disclosure.scriptDeliveryFailure !== undefined + ? { scriptDeliveryFailure: disclosure.scriptDeliveryFailure } + : {}), + ...(disclosure.savedScript !== undefined ? { savedScript: disclosure.savedScript } : {}), }; } -function collectBatchDisclosure(disclosure: BatchDisclosure, data: Record): void { - for (const warning of readResponseWarnings(data)) { - if (!disclosure.warnings.includes(warning)) disclosure.warnings.push(warning); - } - const failure = data.scriptDeliveryFailure; - if (disclosure.failure === undefined && isRecord(failure)) disclosure.failure = failure; +function normalizeStepCommand(command: unknown): string { + return typeof command === 'string' ? command.trim().toLowerCase() : ''; } const CLOSE_COMMAND = 'close'; -function readBatchResults(data: unknown): ReadonlyArray> { - if (!isRecord(data) || !Array.isArray(data.results)) return []; - return data.results.filter((result): result is Record => isRecord(result)); -} +/** One payload is read for at most this many of its own script artifacts. */ +const MAX_SCRIPT_ARTIFACTS_PER_ENTRY = 32; + +/** One batch answer is read for at most this many script artifacts in total, across every payload. */ +const MAX_SCRIPT_ARTIFACTS_PER_BATCH = 64; diff --git a/test/wire-compat/ledger.json b/test/wire-compat/ledger.json index fad1e789e2..d1497044f6 100644 --- a/test/wire-compat/ledger.json +++ b/test/wire-compat/ledger.json @@ -155,7 +155,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:0e5729809b4a931560417f0e4c6d7717d81bcb64459324e534024ecf37f651f9", + "packages/remote/src/daemon-artifacts.ts#materializeRemoteArtifacts": "sha256:d26bb633f219192e9c9c1e93a7dab6869608224697c6ccba8ebb0c1591899574", "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", @@ -243,8 +243,8 @@ }, { "declaration": "packages/remote/src/daemon-artifacts.ts#materializeRemoteArtifacts", - "digest": "sha256:0e5729809b4a931560417f0e4c6d7717d81bcb64459324e534024ecf37f651f9", - "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. #4564 hands a batch response to a step-aware owner, which reads each step's own session-script artifact and publishes it with that step's command name so a terminal step retires the client record. The request and response framing are unchanged: a batch answer already carried the step results, and the client only writes files it already owns the destination for. A released client keeps the batch payload as the daemon answered it." + "digest": "sha256:d26bb633f219192e9c9c1e93a7dab6869608224697c6ccba8ebb0c1591899574", + "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. #4564 hands a batch response to a step-aware owner, which reads each step's own session-script artifact and publishes it with that step's command name so a terminal step retires the client record. The request and response framing are unchanged: a batch answer already carried the step results, and the client only writes files it already owns the destination for. A released client keeps the batch payload as the daemon answered it. #4564 also hands that owner a small context record built by a private helper, and the sibling `materializeRemoteBatchPartialArtifacts` delivers the finished steps of a FAILED batch from the error's existing `partialResults`; both read what the daemon already answered, so request and response framing are unchanged." }, { "declaration": "packages/daemon-client/src/daemon-client-rpc.ts#buildHttpRpcPayload", diff --git a/website/docs/docs/remote-proxy.md b/website/docs/docs/remote-proxy.md index 63d2a15be2..79f03e6660 100644 --- a/website/docs/docs/remote-proxy.md +++ b/website/docs/docs/remote-proxy.md @@ -122,11 +122,12 @@ recorded a version discloses it: the CLI prints a `Warning:` line and carries a `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` delivers the script versions its steps record, in step order, and -a `close` step retires the recording the same way a standalone `close` does. When a later step fails, -the steps that already ran still deliver their scripts, and the batch error stands. A step whose -script did not arrive is reported once more on the batch result itself, so the `Warning:` line and -the `scriptDeliveryFailure` field reach the batch output rather than only the step's own entry. +batch steps are refused. A `batch` delivers the newest version its answer names, whether a step +carried it or the batch result itself did, and a batch that closes the recording retires it the same +way a standalone `close` does. Every version is the full recording, so one batch costs at most one +download. When a later step fails, the script the steps that already ran recorded is still delivered, +and the batch error stands. A script that did not arrive is reported on the batch result itself, so +the `Warning:` line and the `scriptDeliveryFailure` field reach the batch output. 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 diff --git a/website/docs/docs/replay-e2e.md b/website/docs/docs/replay-e2e.md index 88cd502b73..b5b63aef6e 100644 --- a/website/docs/docs/replay-e2e.md +++ b/website/docs/docs/replay-e2e.md @@ -75,7 +75,7 @@ agent-device open Settings --platform ios --session e2e --save-script ./workflow - With a remote daemon, outside a macOS app lease, the path is on your machine. The file appears when `open` returns, and each later recorded action in the session replaces it with the recording so far. `close` writes the final script there. A session that another process closes keeps the version from the last action. - A bare remote `open --save-script` writes `recording-.ad` in your working directory. - If the file already exists, `open` fails unless you pass `--force`. Without `--force`, a file that appears before the first version arrives is kept too: `open` still succeeds, but the script is not saved there, 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. +- Remote `session save-script`, `close --save-script`, `replay --save-script`, and `--save-script` in batch steps are refused. A `batch` of recorded actions delivers the newest version once, because every version is the full recording. - The remote daemon must report the `script-artifacts` capability in its `/health` response. Through a proxy, the upstream daemon's health response must report it. Otherwise `open --save-script` fails before the app opens. - For a bare file name that could be read as another argument, use `--save-script=workflow.ad` or a path-like value such as `./workflow.ad`. From 1e431f5809f85a5c76a791e6931f97db81210b69 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Mon, 16 Nov 2026 11:49:29 +0100 Subject: [PATCH 4/5] docs(remote): state the one-download batch budget where the ledger points ADR 0016 said every recorded action costs one download without naming the batch case, and the ledger rationale still described the per-step path this module no longer takes. Reports #4564 review finding 5. Co-Authored-By: Claude Opus 5.5 --- docs/adr/0016-active-session-script-publication.md | 2 +- test/wire-compat/ledger.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/adr/0016-active-session-script-publication.md b/docs/adr/0016-active-session-script-publication.md index 802536c686..45cd8bd92b 100644 --- a/docs/adr/0016-active-session-script-publication.md +++ b/docs/adr/0016-active-session-script-publication.md @@ -215,7 +215,7 @@ Every result that can carry a script version discloses a failed delivery: the SD Rejected: a remote `session save-script` download, because it added a second publication path and a retry protocol. Rejected: delivery only at close, because a session that an external owner closes would lose its recording. Rejected: daemon-minted recording IDs bound through per-request claims, because the claim, binding, and tombstone protocol cost more than a client-minted ID that only its own client can match. -Consequence: each recorded action of a remote ARMED recording costs one script write and one artifact download. +Consequence: each recorded action of a remote ARMED recording costs one script write and one artifact download, except inside a batch, where the client takes only the newest version and one batch costs one download. This lifecycle is distinct from the ADR 0012 repair transaction. `session save-script` rejects a session with `saveScriptBoundary` set. diff --git a/test/wire-compat/ledger.json b/test/wire-compat/ledger.json index d1497044f6..fd693a060c 100644 --- a/test/wire-compat/ledger.json +++ b/test/wire-compat/ledger.json @@ -244,7 +244,7 @@ { "declaration": "packages/remote/src/daemon-artifacts.ts#materializeRemoteArtifacts", "digest": "sha256:d26bb633f219192e9c9c1e93a7dab6869608224697c6ccba8ebb0c1591899574", - "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. #4564 hands a batch response to a step-aware owner, which reads each step's own session-script artifact and publishes it with that step's command name so a terminal step retires the client record. The request and response framing are unchanged: a batch answer already carried the step results, and the client only writes files it already owns the destination for. A released client keeps the batch payload as the daemon answered it. #4564 also hands that owner a small context record built by a private helper, and the sibling `materializeRemoteBatchPartialArtifacts` delivers the finished steps of a FAILED batch from the error's existing `partialResults`; both read what the daemon already answered, so request and response framing are unchanged." + "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. #4564 hands a batch response to a batch script owner, which delivers AT MOST ONE version per batch: it takes the newest session-script version the answer carries, in a finished step or on the batch payload itself, publishes it through the session-script owner, and retires the client record only when the submitted plan itself ran and finished a close step. The request and response framing are unchanged: a batch answer already carried the step results, and the client only writes files it already owns the destination for. A released client keeps the daemon's own step entries as they were answered and adds its delivery fields to the batch payload. #4564 also hands that owner a small context record built by a private helper, and the sibling `materializeRemoteBatchPartialArtifacts` delivers the newest version of the steps a FAILED batch finished, from the error's existing `partialResults`; both read what the daemon already answered, so request and response framing are unchanged." }, { "declaration": "packages/daemon-client/src/daemon-client-rpc.ts#buildHttpRpcPayload", From f09f36fcb7a44f3ffc02abe4ead648e5ae876b10 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Mon, 16 Nov 2026 14:07:57 +0100 Subject: [PATCH 5/5] fix(remote): disclose a step's script failure on the batch, in a smaller path The batch script owner is replaced by one delivery path: read the plan the caller submitted, take its finished prefix, pick the newest publishable version the answer names, and run the single-response owner on that one artifact. `sessionScriptDelivery` takes an explicit `closedPublicationId` instead of a faked `command: 'close'`, and `isPublishableScriptVersion` is one predicate used by the publisher and the batch scan. Step names resolve through `normalizeBatchCommandName`, so the plan check and the daemon's own step naming cannot drift apart. A finished step's `scriptDeliveryFailure` now reaches the batch payload: this client's own failure wins, otherwise the last finished step's failure for that publication, unless the saved version came from a later step. Only the warning written beside that failure rides up. A step entry outside the finished prefix, or one whose report does not describe the submitted plan, authorizes nothing. The failed-batch catch emits the `session_script_delivery_failed` diagnostic, and the batch path rewrites the answer's own artifact list the way a single response does. Co-Authored-By: Claude Opus 5.5 --- .../0016-active-session-script-publication.md | 2 +- .../index-script-delivery-disclosure.test.ts | 111 +++++ packages/client/src/index.ts | 5 +- ...sult-serialization-script-delivery.test.ts | 79 ++++ .../src/__tests__/daemon-client-rpc.test.ts | 82 +++- packages/remote/package.json | 1 + .../daemon-artifacts-batch-script.test.ts | 380 ++++++++++++------ packages/remote/src/daemon-artifacts.ts | 173 ++++++-- packages/remote/src/remote-batch-answer.ts | 127 ++++++ .../src/remote-batch-script-delivery.ts | 333 --------------- .../remote/src/session-script-destination.ts | 47 ++- packages/remote/tsconfig.json | 1 + pnpm-lock.yaml | 3 + src/cli/commands/__tests__/screenshot.test.ts | 31 ++ test/wire-compat/ledger.json | 8 +- website/docs/docs/remote-proxy.md | 6 +- 16 files changed, 882 insertions(+), 507 deletions(-) create mode 100644 packages/client/src/__tests__/index-script-delivery-disclosure.test.ts create mode 100644 packages/command-output/src/output/result-serialization-script-delivery.test.ts create mode 100644 packages/remote/src/remote-batch-answer.ts delete mode 100644 packages/remote/src/remote-batch-script-delivery.ts diff --git a/docs/adr/0016-active-session-script-publication.md b/docs/adr/0016-active-session-script-publication.md index 45cd8bd92b..f6a7cce9d6 100644 --- a/docs/adr/0016-active-session-script-publication.md +++ b/docs/adr/0016-active-session-script-publication.md @@ -207,7 +207,7 @@ It adds no state name, command, or flag: A batch delivers the newest version its answer names, wherever it names it, and a batch that closes the recording retires the caller record like a standalone close does. Every version is the full recording, so one batch costs at most one download. The submitted plan is the only authority for that delivery: a completed prefix is derived from it, an answer entry outside that prefix or naming another command gets no download, and a retirement follows only a close the plan itself ran and finished. The steps that finished of a FAILED batch are delivered too, from the error's `partialResults`, cross-checked against the failing step the error names, and the batch error stands. - A delivery warning and typed failure ride the batch payload itself, because a batch's human and machine output read only that payload. + The batch payload carries `scriptDeliveryFailure` when this client's own delivery, or a finished step, reports one for the recording and no version this client saved came after that report; only the warning written beside that failure rides up, because a batch's human and machine output read only that payload. - 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). diff --git a/packages/client/src/__tests__/index-script-delivery-disclosure.test.ts b/packages/client/src/__tests__/index-script-delivery-disclosure.test.ts new file mode 100644 index 0000000000..a5eee35285 --- /dev/null +++ b/packages/client/src/__tests__/index-script-delivery-disclosure.test.ts @@ -0,0 +1,111 @@ +import assert from 'node:assert/strict'; +import { test } from 'vitest'; +import { createAgentDeviceClient } from '../index.ts'; +import type { DaemonResponse, ScriptDeliveryFailure } from '@agent-device/kernel/contracts'; +import { createClientTransport } from '@agent-device/test-kit'; + +/** + * A script version that did not reach the caller file keeps its action successful, so the typed + * failure and its paired warning are the only disclosure that the file is stale (ADR 0016, #4564). + * Every SDK result that can carry a script version reads both fields through + * `readScriptDeliveryDisclosure`; this table pins each one, so a spread that stops carrying either + * field fails here rather than quietly on one surface. + */ + +const WARNING = 'The session recorded version 2, but the daemon could not save it.'; + +const FAILURE: ScriptDeliveryFailure = { + reason: 'script_delivery_failed', + cause: 'script_write_failed', + publicationId: '0f61b0c2-6d1a-4d1f-9b7f-2a4f3a1c7d55', + message: WARNING, + hint: 'The file keeps the version from the last action that arrived.', +}; + +/** The two fields one answer carries at the top level of its payload. */ +const DISCLOSURE = { warnings: [WARNING], scriptDeliveryFailure: FAILURE }; + +/** One SDK action whose answer can carry a script version, with the answer it reads. */ +type DisclosureSurface = Readonly<{ + label: string; + command: string; + data: Record; + read: (client: ReturnType) => Promise; +}>; + +const SURFACES: DisclosureSurface[] = [ + { + label: 'sessions.close', + command: 'close', + data: { ...DISCLOSURE, savedScript: '/tmp/journey.ad' }, + read: async (client) => await client.sessions.close(), + }, + { + label: 'apps.close', + command: 'close', + data: { ...DISCLOSURE, savedScript: '/tmp/journey.ad' }, + read: async (client) => await client.apps.close(), + }, + { + label: 'apps.open', + command: 'open', + data: { ...DISCLOSURE, appBundleId: 'com.example.demo' }, + read: async (client) => await client.apps.open({ app: 'Demo' }), + }, + { + label: 'capture.snapshot', + command: 'snapshot', + data: { ...DISCLOSURE, nodes: [] }, + read: async (client) => await client.capture.snapshot(), + }, + { + label: 'capture.screenshot', + command: 'screenshot', + data: { ...DISCLOSURE, path: '/tmp/shot.png', width: 40, height: 20 }, + read: async (client) => await client.capture.screenshot(), + }, +]; + +function clientAnswering(command: string, data: Record) { + const setup = createClientTransport(async (req): Promise => { + if (req.command !== command) throw new Error(`Unexpected command: ${req.command}`); + return { ok: true, data: { session: 'qa', ...data } }; + }); + return createAgentDeviceClient(setup.config, { transport: setup.transport }); +} + +for (const surface of SURFACES) { + test(`the ${surface.label} result carries a failed script delivery`, async () => { + const client = clientAnswering(surface.command, surface.data); + + const result = (await surface.read(client)) as Record; + + assert.deepEqual(result.scriptDeliveryFailure, FAILURE, surface.label); + assert.deepEqual(result.warnings, [WARNING], surface.label); + }); + + test(`the ${surface.label} result names no disclosure for a delivered script`, async () => { + const plain = Object.fromEntries( + Object.entries(surface.data).filter( + ([key]) => key !== 'warnings' && key !== 'scriptDeliveryFailure', + ), + ); + const client = clientAnswering(surface.command, plain); + + const result = (await surface.read(client)) as Record; + + assert.equal('scriptDeliveryFailure' in result, false, surface.label); + assert.equal('warnings' in result, false, surface.label); + }); + + test(`the ${surface.label} result drops a malformed failure object`, async () => { + const client = clientAnswering(surface.command, { + ...surface.data, + scriptDeliveryFailure: { reason: 'script_delivery_failed' }, + }); + + const result = (await surface.read(client)) as Record; + + assert.equal('scriptDeliveryFailure' in result, false, surface.label); + }); +} diff --git a/packages/client/src/index.ts b/packages/client/src/index.ts index 50ee2b6cfa..b00e671665 100644 --- a/packages/client/src/index.ts +++ b/packages/client/src/index.ts @@ -606,6 +606,7 @@ function optionalSnapshotResponseFields( const snapshotDiagnostics = readSnapshotDiagnosticsSummary(data.snapshotDiagnostics); const presentedSurface = readPresentedSurfaceFact(data); const postGestureOutcome = readPostGestureOutcome(data.postGestureOutcome); + const { scriptDeliveryFailure } = readScriptDeliveryDisclosure(data); return { ...(keyboard ? { keyboard } : {}), ...(viewport ? { viewport } : {}), @@ -615,7 +616,9 @@ function optionalSnapshotResponseFields( ...readSerializedSnapshotCaptureAnnotations(data), ...(unchanged ? { unchanged: unchanged as CaptureSnapshotResult['unchanged'] } : {}), ...(snapshotDiagnostics ? { snapshotDiagnostics } : {}), - ...readScriptDeliveryDisclosure(data), + // `readSerializedSnapshotCaptureAnnotations` above already reads this response's `warnings`, so + // only the typed field needs adding here. + ...(scriptDeliveryFailure === undefined ? {} : { scriptDeliveryFailure }), ...(typeof data.fallbackScreenshotPath === 'string' ? { fallbackScreenshotPath: data.fallbackScreenshotPath } : {}), diff --git a/packages/command-output/src/output/result-serialization-script-delivery.test.ts b/packages/command-output/src/output/result-serialization-script-delivery.test.ts new file mode 100644 index 0000000000..27b83e9753 --- /dev/null +++ b/packages/command-output/src/output/result-serialization-script-delivery.test.ts @@ -0,0 +1,79 @@ +import { test } from 'vitest'; +import assert from 'node:assert/strict'; +import type { ScriptDeliveryFailure } from '@agent-device/kernel/contracts'; +import { + serializeCloseResult, + serializeOpenResult, + serializeSnapshotResult, +} from './result-serialization.ts'; + +/** + * A remote recording's script version that did not reach the caller file keeps its action + * successful, so machine output is where a caller learns the file is stale (ADR 0016, #4564). Every + * family that can report a script version emits the two fields through one helper; this table pins + * each of them, so a serializer that stops carrying either field fails here. + */ + +const WARNING = 'The session recorded version 2, but the daemon could not save it.'; + +const FAILURE: ScriptDeliveryFailure = { + reason: 'script_delivery_failed', + cause: 'script_write_failed', + publicationId: '0f61b0c2-6d1a-4d1f-9b7f-2a4f3a1c7d55', + message: WARNING, + hint: 'The file keeps the version from the last action that arrived.', +}; + +const DISCLOSURE = { warnings: [WARNING], scriptDeliveryFailure: FAILURE }; + +/** The machine output of each family whose result can carry a script version. */ +const outputs: Array<{ label: string; serialize: () => Record }> = [ + { + label: 'open', + serialize: () => serializeOpenResult({ session: 'qa', ...DISCLOSURE } as never), + }, + { + label: 'session close', + serialize: () => + serializeCloseResult({ + session: 'qa', + savedScript: '/tmp/journey.ad', + ...DISCLOSURE, + } as never), + }, + { + label: 'snapshot', + serialize: () => serializeSnapshotResult({ nodes: [], ...DISCLOSURE } as never), + }, +]; + +for (const output of outputs) { + test(`the ${output.label} machine output carries a failed script delivery`, () => { + const data = output.serialize(); + + assert.deepEqual(data.scriptDeliveryFailure, FAILURE); + assert.deepEqual(data.warnings, [WARNING]); + }); + + test(`the ${output.label} machine output omits a disclosure it was not given`, () => { + const withFields = output.serialize(); + const withoutFields = { ...withFields }; + delete withoutFields.scriptDeliveryFailure; + delete withoutFields.warnings; + + assert.notDeepEqual(withFields, withoutFields); + }); + + test(`the ${output.label} machine output keeps the failure beside an empty warning list`, () => { + const disclosed = { ...DISCLOSURE, warnings: [] }; + const empty = + output.label === 'open' + ? serializeOpenResult({ session: 'qa', ...disclosed } as never) + : output.label === 'snapshot' + ? serializeSnapshotResult({ nodes: [], ...disclosed } as never) + : serializeCloseResult({ session: 'qa', ...disclosed } as never); + + assert.deepEqual(empty.scriptDeliveryFailure, FAILURE); + assert.equal('warnings' in empty, false); + }); +} diff --git a/packages/daemon-client/src/__tests__/daemon-client-rpc.test.ts b/packages/daemon-client/src/__tests__/daemon-client-rpc.test.ts index 9b2d3597fa..68ff545d52 100644 --- a/packages/daemon-client/src/__tests__/daemon-client-rpc.test.ts +++ b/packages/daemon-client/src/__tests__/daemon-client-rpc.test.ts @@ -283,7 +283,8 @@ test('a failed remote batch delivers the scripts of the steps that finished and }), { info: { token: 'daemon-token', pid: 1, baseUrl }, - req: batchRequest('wait', 'close'), + // The report says step 3 failed after 2 finished steps, so the caller submitted three. + req: batchRequest('wait', 'close', 'snapshot'), stateDir, host, resolve: () => resolve(), @@ -436,6 +437,85 @@ test('a failed remote batch whose step report disagrees with its entries deliver } }); +/** + * The runner's step report has to describe a step of THIS caller's plan. A report that names a step + * the plan does not have, or names a step under another command, describes work this client never + * submitted, so it finishes nothing: no download, and no end to the caller's recording. + */ +test('a failed remote batch whose report does not describe the submitted plan delivers nothing', async () => { + const reports: Array< + Readonly<{ label: string; plan: string[]; details: Record }> + > = [ + { + // Names step 3 of a two-step plan. + label: 'a step the plan does not have', + plan: ['wait', 'close'], + details: { step: 3, command: 'snapshot', executed: 2 }, + }, + { + // Names a real step of a three-step plan under another command. + label: 'a command the plan does not name there', + plan: ['wait', 'close', 'snapshot'], + details: { step: 3, command: 'wait', executed: 2 }, + }, + ]; + + for (const report of reports) { + const server = scriptServer({ v1: 'open Demo\n', final: 'open Demo\nwait 100\nclose\n' }); + const baseUrl = `http://127.0.0.1:${await listenOnLoopback(server)}`; + const root = fs.realpathSync(mkdtempForTestSync('rpc-batch-report-mismatch-')); + const stateDir = path.join(root, 'state'); + const destination = path.join(root, 'journey.ad'); + try { + const publicationId = await openRemoteRecording(baseUrl, stateDir, destination); + + await new Promise((resolve) => { + handleDaemonHttpResponseBody( + JSON.stringify({ + error: { + data: { + code: 'COMMAND_FAILED', + message: `Batch failed at step ${String(report.details.step)}`, + details: { + ...report.details, + total: report.plan.length, + // A finished close of this client's publication, planted at the last executed step. + partialResults: [ + { step: 1, command: 'wait', ok: true, durationMs: 1, data: { waited: true } }, + { + step: 2, + command: 'close', + ok: true, + durationMs: 1, + data: { + scriptPublicationId: publicationId, + artifacts: [scriptArtifact('final', 2, publicationId)], + }, + }, + ], + }, + }, + }, + }), + { + info: { token: 'daemon-token', pid: 1, baseUrl }, + req: batchRequest(...report.plan), + stateDir, + host: createTestHostEnvironment(), + resolve: () => resolve(), + reject: () => resolve(), + }, + ); + }); + + assert.equal(fs.readFileSync(destination, 'utf8'), 'open Demo\n', report.label); + assert.equal(activeScriptRecords(stateDir).length, 1, report.label); + } finally { + await closeLoopbackServer(server); + } + } +}); + function batchRequest(...commands: string[]): DaemonWireRequest { return { token: 'daemon-token', diff --git a/packages/remote/package.json b/packages/remote/package.json index a9a7f4f239..2abc6f8ff6 100644 --- a/packages/remote/package.json +++ b/packages/remote/package.json @@ -6,6 +6,7 @@ "description": "Remote-daemon client plumbing: remote config profiles and their provenance, the persisted remote connection state, request artifact upload/download, and remote diagnostics localization. Internal workspace package bundled into the published agent-device artifact.", "dependencies": { "@agent-device/capture-kit": "workspace:*", + "@agent-device/command-registry": "workspace:*", "@agent-device/contracts": "workspace:*", "@agent-device/daemon-contracts": "workspace:*", "@agent-device/host-kit": "workspace:*", diff --git a/packages/remote/src/__tests__/daemon-artifacts-batch-script.test.ts b/packages/remote/src/__tests__/daemon-artifacts-batch-script.test.ts index 80699d3fd2..8888fc9256 100644 --- a/packages/remote/src/__tests__/daemon-artifacts-batch-script.test.ts +++ b/packages/remote/src/__tests__/daemon-artifacts-batch-script.test.ts @@ -10,7 +10,10 @@ import { listenOnLoopback, mkdtempForTestSync, } from '@agent-device/test-kit'; -import { materializeRemoteArtifacts } from '../daemon-artifacts.ts'; +import { + materializeRemoteArtifacts, + materializeRemoteBatchPartialArtifacts, +} from '../daemon-artifacts.ts'; import { sendRemoteScriptOpen } from '../session-script-destination.ts'; const servers: http.Server[] = []; @@ -20,12 +23,16 @@ afterEach(async () => { }); /** - * Serves the script versions it is given. An artifact ID it does not know answers 503, which is how - * these tests make one step's download fail. + * Serves the script versions it is given, and records what it was asked for. An artifact ID it does + * not know answers 503, which is how these tests make a download fail. */ -async function artifactServer(bodies: Record): Promise { +async function artifactServer( + bodies: Record, + requested: string[] = [], +): Promise { const server = http.createServer((req, res) => { const id = decodeURIComponent(req.url?.replace('/artifacts/', '') ?? ''); + requested.push(id); const body = bodies[id]; if (body === undefined) { res.writeHead(503).end('unavailable'); @@ -77,6 +84,17 @@ function script(artifactId: string, revision: number, publicationId: string): Da }; } +/** The failure the DAEMON writes when it could not save its own version of the recording. */ +function daemonFailure(publicationId: string, revision: number) { + return { + reason: 'script_delivery_failed', + cause: 'script_write_failed', + publicationId, + message: `The session recorded version ${revision}, but the daemon could not save it.`, + hint: 'The file keeps the version from the last action that arrived.', + }; +} + function records(stateDir: string): string[] { const directory = path.join(stateDir, 'remote-connections', 'session-scripts'); return fs.existsSync(directory) @@ -132,10 +150,16 @@ function batchSteps(response: DaemonResponse): Array> { return (response.data?.results ?? []) as Array>; } +/** The batch's own payload fields. */ +function payload(response: DaemonResponse): Record { + if (!response.ok) throw new Error(`Expected a successful batch, got ${JSON.stringify(response)}`); + return response.data ?? {}; +} + /** - * Nothing was delivered: no step names a caller file, and no artifact reports a published local - * path. The daemon's own artifact entries stay in the answer, field names and all, so the answer is - * checked for what this client would have added. + * Nothing was delivered: no field names a caller file, no artifact reports a published local path, + * and no delivery failure is claimed. The daemon's own artifact entries stay in the answer, field + * names and all, so the answer is checked for what this client would have added. */ function expectDeliveredNothing(response: DaemonResponse): void { const text = JSON.stringify(response); @@ -146,12 +170,17 @@ function expectDeliveredNothing(response: DaemonResponse): void { test('a batch delivers its newest script once and a close step retires the record', async () => { const { stateDir, destination } = journey(); - const baseUrl = await artifactServer({ - v1: 'open Demo\n', - v2: 'open Demo\nwait 100\n', - v3: 'open Demo\nwait 100\nclose\n', - }); + const requested: string[] = []; + const baseUrl = await artifactServer( + { + v1: 'open Demo\n', + v2: 'open Demo\nwait 100\n', + v3: 'open Demo\nwait 100\nclose\n', + }, + requested, + ); const id = await open(baseUrl, stateDir, destination); + requested.length = 0; expect(records(stateDir)).toHaveLength(1); const response = await answer( @@ -170,18 +199,14 @@ test('a batch delivers its newest script once and a close step retires the recor ); // Every version is the whole recording, so ONE download is owed: the newest of the batch. + expect(requested).toEqual(['v3']); expect(fs.readFileSync(destination, 'utf8')).toBe('open Demo\nwait 100\nclose\n'); // The terminal step retired the record, so no later version of that publication writes anything. expect(records(stateDir)).toEqual([]); - // The batch's own payload says where the recording landed, the way a single response does. - expect(response.ok && response.data?.savedScript).toBe(destination); - // The steps are reported exactly as the daemon answered them: this client writes its own fields, not - // the daemon's entries. + // The batch payload names the file, the way a single response does. + expect(payload(response).savedScript).toBe(destination); + // The steps are the daemon's own entries, unchanged. expect(batchSteps(response).map((result) => result.command)).toEqual(['wait', 'close']); - expect(batchSteps(response).map((result) => result.data.artifacts)).toEqual([ - [expect.objectContaining({ artifactId: 'v2', scriptRevision: 2 })], - [expect.objectContaining({ artifactId: 'v3', scriptRevision: 3 })], - ]); }); test('a batch script whose download fails discloses the failure and keeps the batch', async () => { @@ -193,38 +218,26 @@ test('a batch script whose download fails discloses the failure and keeps the ba total: 1, executed: 1, totalDurationMs: 1, - results: [step(1, 'wait', { waited: true, artifacts: [script('gone', 2, id)] })], + artifacts: [script('gone', 2, id)], + results: [step(1, 'wait', { waited: true })], }); // The step ran on the device, so the batch stands and the batch payload says the file is stale. expect(response.ok).toBe(true); - expect(response.ok && response.data?.scriptDeliveryFailure).toEqual( + expect(payload(response).scriptDeliveryFailure).toEqual( expect.objectContaining({ reason: 'script_delivery_failed', cause: 'script_download_failed', publicationId: id, }), ); - expect(response.ok && response.data?.warnings).toEqual([expect.stringContaining('script')]); - // The step's own entry is the daemon's answer, and a daemon-host path or status never rides along. - expect(batchSteps(response)[0]).toEqual({ - step: 1, - command: 'wait', - ok: true, - durationMs: 1, - data: { waited: true, artifacts: [expect.objectContaining({ artifactId: 'gone' })] }, - }); + // Like a single response: the failed script artifact does not stay in the list the caller reads. + expect(payload(response).artifacts).toEqual([]); + expect(payload(response).warnings).toEqual([expect.stringContaining('script')]); expect(JSON.stringify(response)).not.toContain('unavailable'); expect(fs.readFileSync(destination, 'utf8')).toBe('open Demo\n'); // The recording is not closed, so the record stays and a later version still lands. expect(records(stateDir)).toHaveLength(1); - const later = await answer(baseUrl, stateDir, request('close'), { - scriptPublicationId: id, - artifacts: [script('v1', 3, id)], - }); - expect(later.ok).toBe(true); - expect(fs.readFileSync(destination, 'utf8')).toBe('open Demo\n'); - expect(records(stateDir)).toEqual([]); }); test('a batch that closes keeps its success and retires the record when the final download fails', async () => { @@ -240,11 +253,8 @@ test('a batch that closes keeps its success and retires the record when the fina }); // The session closed, so the record is gone even though the final script did not arrive. - expect(response.ok && response.data?.scriptDeliveryFailure).toEqual( - expect.objectContaining({ - cause: 'script_download_failed', - publicationId: id, - }), + expect(payload(response).scriptDeliveryFailure).toEqual( + expect.objectContaining({ cause: 'script_download_failed', publicationId: id }), ); expect(fs.readFileSync(destination, 'utf8')).toBe('open Demo\n'); expect(records(stateDir)).toEqual([]); @@ -252,10 +262,7 @@ test('a batch that closes keeps its success and retires the record when the fina test('a batch step script of another publication or of another field writes nothing', async () => { const { root, stateDir, destination } = journey(); - const baseUrl = await artifactServer({ - v1: 'open Demo\n', - foreign: 'hostile\n', - }); + const baseUrl = await artifactServer({ v1: 'open Demo\n', foreign: 'hostile\n' }); const id = await open(baseUrl, stateDir, destination); const victim = path.join(root, 'victim.ad'); @@ -307,7 +314,9 @@ test('a close step that names the publication retires the record with no artifac const id = await open(baseUrl, stateDir, destination); // The daemon could not write the final version, so it answers this close with its own typed - // failure and nothing to download. The caller still has to stop tracking a recording it lost. + // failure and nothing to download. The caller still has to stop tracking a recording it lost, and + // it has to be told: the file is missing the terminal `close` and nothing else says so. + const failure = daemonFailure(id, 2); const response = await answer(baseUrl, stateDir, request('batch', {}, batchPlan('close')), { total: 1, executed: 1, @@ -315,21 +324,89 @@ test('a close step that names the publication retires the record with no artifac results: [ step(1, 'close', { scriptPublicationId: id, - scriptDeliveryFailure: { reason: 'script_delivery_failed', publicationId: id }, - warnings: ['The daemon could not write the final script.'], + scriptDeliveryFailure: failure, + warnings: [`${failure.message} ${failure.hint}`], }), ], }); expect(records(stateDir)).toEqual([]); expect(fs.readFileSync(destination, 'utf8')).toBe('open Demo\n'); - // The daemon's own warning stands on its step, and reaches the batch's top level as well. - expect(batchSteps(response)[0]?.data).toEqual( - expect.objectContaining({ scriptPublicationId: id }), + // The step's daemon-side write failure reaches the batch payload, with its paired warning. + expect(payload(response).scriptDeliveryFailure).toEqual(expect.objectContaining(failure)); + expect(payload(response).warnings).toEqual([`${failure.message} ${failure.hint}`]); +}); + +test('a finished step that reports a write failure is disclosed when an older version is delivered', async () => { + const { stateDir, destination } = journey(); + const baseUrl = await artifactServer({ v1: 'open Demo\n', v2: 'open Demo\nwait 100\n' }); + const id = await open(baseUrl, stateDir, destination); + + // `[wait, close]`: the `wait` step published version 2, the `close` step could not write its final + // version. The client saves what it can, and the batch result still has to carry the typed failure, + // because the caller file lacks the terminal `close`. + const failure = daemonFailure(id, 3); + const response = await answer( + baseUrl, + stateDir, + request('batch', {}, batchPlan('wait', 'close')), + { + total: 2, + executed: 2, + totalDurationMs: 1, + results: [ + step(1, 'wait', { artifacts: [script('v2', 2, id)] }), + step(2, 'close', { + scriptDeliveryFailure: failure, + warnings: ['Capture dropped 1 frame.'], + }), + ], + }, + ); + + expect(payload(response).savedScript).toBe(destination); + expect(fs.readFileSync(destination, 'utf8')).toBe('open Demo\nwait 100\n'); + expect(payload(response).scriptDeliveryFailure).toEqual(expect.objectContaining(failure)); + // Only the warning paired with THAT failure rides up, never every step's warnings. + expect(payload(response).warnings).toEqual([`${failure.message} ${failure.hint}`]); + // The recording is closed, so the caller stops tracking it. + expect(records(stateDir)).toEqual([]); +}); + +test('a step failure superseded by a newer delivered version is not disclosed', async () => { + const { stateDir, destination } = journey(); + const baseUrl = await artifactServer({ + v1: 'open Demo\n', + v3: 'open Demo\nwait 100\nsnapshot\n', + }); + const id = await open(baseUrl, stateDir, destination); + + // The first step's write failed, then the daemon published and stamped version 3. The caller file + // holds that newer version, so the stale step failure says nothing the caller still needs. + const response = await answer( + baseUrl, + stateDir, + request('batch', {}, batchPlan('wait', 'snapshot')), + { + total: 2, + executed: 2, + totalDurationMs: 1, + scriptPublicationId: id, + artifacts: [script('v3', 3, id)], + results: [ + step(1, 'wait', { + scriptDeliveryFailure: daemonFailure(id, 2), + warnings: ['The session recorded version 2, but the daemon could not save it.'], + }), + step(2, 'snapshot', { name: 'shot' }), + ], + }, ); - expect(response.ok && response.data?.warnings).toEqual([ - 'The daemon could not write the final script.', - ]); + + expect(payload(response).savedScript).toBe(destination); + expect(fs.readFileSync(destination, 'utf8')).toBe('open Demo\nwait 100\nsnapshot\n'); + expect(payload(response).scriptDeliveryFailure).toBeUndefined(); + expect(payload(response).warnings).toBeUndefined(); }); test('a batch step entry the plan does not authorize delivers nothing and retires nothing', async () => { @@ -416,27 +493,39 @@ test('a batch request that submitted no plan delivers nothing from its step entr expect(fs.readFileSync(destination, 'utf8')).toBe('open Demo\n'); }); -test('one batch answer asks for ONE download, whatever versions it names', async () => { +test('a batch step named with other case or spaces still authorizes its delivery and retirement', async () => { const { stateDir, destination } = journey(); - const requested: string[] = []; - const bodies: Record = { + const baseUrl = await artifactServer({ v1: 'open Demo\n', - v3: 'open Demo\nwait 100\n', - v5: 'open Demo\nwait 100\nsnapshot\n', - }; - const server = http.createServer((req, res) => { - const id = decodeURIComponent(req.url?.replace('/artifacts/', '') ?? ''); - requested.push(id); - const body = bodies[id]; - if (body === undefined) { - res.writeHead(503).end('unavailable'); - return; - } - res.writeHead(200, { 'content-length': Buffer.byteLength(body) }); - res.end(body); + v2: 'open Demo\nclose\n', }); - servers.push(server); - const baseUrl = `http://127.0.0.1:${await listenOnLoopback(server)}`; + const id = await open(baseUrl, stateDir, destination); + + // The daemon normalizes a step name before it runs it, and answers with that name. A caller that + // compared its own raw text would stop matching, deliver nothing and keep a dead record. + const response = await answer(baseUrl, stateDir, request('batch', {}, batchPlan(' CLOSE ')), { + total: 1, + executed: 1, + totalDurationMs: 1, + results: [step(1, 'close', { scriptPublicationId: id, artifacts: [script('v2', 2, id)] })], + }); + + expect(payload(response).savedScript).toBe(destination); + expect(fs.readFileSync(destination, 'utf8')).toBe('open Demo\nclose\n'); + expect(records(stateDir)).toEqual([]); +}); + +test('one batch answer asks for ONE download, whatever versions it names', async () => { + const { stateDir, destination } = journey(); + const requested: string[] = []; + const baseUrl = await artifactServer( + { + v1: 'open Demo\n', + v3: 'open Demo\nwait 100\n', + v5: 'open Demo\nwait 100\nsnapshot\n', + }, + requested, + ); const id = await open(baseUrl, stateDir, destination); requested.length = 0; @@ -460,29 +549,26 @@ test('one batch answer asks for ONE download, whatever versions it names', async ); expect(requested).toEqual(['v5']); - expect(response.ok && response.data?.savedScript).toBe(destination); + expect(payload(response).savedScript).toBe(destination); expect(fs.readFileSync(destination, 'utf8')).toBe('open Demo\nwait 100\nsnapshot\n'); }); -test('a batch reads at most its bound of script artifacts, whatever an answer names', async () => { +test('a batch reads at most its bound of step artifacts and keeps the newest version of the payload', async () => { const { stateDir, destination } = journey(); const requested: string[] = []; - const server = http.createServer((req, res) => { - const id = decodeURIComponent(req.url?.replace('/artifacts/', '') ?? ''); - requested.push(id); - res.writeHead(200, { 'content-length': Buffer.byteLength('open Demo\n') }); - res.end('open Demo\n'); - }); - servers.push(server); - const baseUrl = `http://127.0.0.1:${await listenOnLoopback(server)}`; + const baseUrl = await artifactServer( + { v1: 'open Demo\n', stamped: 'open Demo\nwait 100\n' }, + requested, + ); const id = await open(baseUrl, stateDir, destination); requested.length = 0; - // Ten step entries name a hundred script artifacts each, and the batch payload names a hundred more: - // 1,100 artifacts in one answer. The scan is bounded, and the caller is owed ONE download — the newest - // version, which the batch payload stamps after the last step and is always read first. + // Ten finished steps name a hundred script artifacts each, all newer than the version the batch + // payload itself stamps. The bounds stop this client reading them: it keeps the bounded payload + // version, which is scanned first, and the versions past a bound are never asked for. Deleting a + // bound would make a later step's newer version win this answer. const many = (from: number) => - Array.from({ length: 100 }, (_, i) => script(`v-${from + i}`, from + i + 1, id)); + Array.from({ length: 100 }, (_, i) => script(`step-${from + i}`, from + i + 1, id)); const results = Array.from({ length: 10 }, (_, stepIndex) => step(stepIndex + 1, 'wait', { artifacts: many(stepIndex * 100) }), ); @@ -495,44 +581,73 @@ test('a batch reads at most its bound of script artifacts, whatever an answer na executed: 10, totalDurationMs: 1, scriptPublicationId: id, - artifacts: many(1000), + artifacts: [script('stamped', 500, id)], results, }, ); - // Exactly one download, and it is the newest version the scan was allowed to keep. - expect(requested).toHaveLength(1); - expect(response.ok && response.data?.savedScript).toBe(destination); + expect(requested).toEqual(['stamped']); + expect(payload(response).savedScript).toBe(destination); + expect(fs.readFileSync(destination, 'utf8')).toBe('open Demo\nwait 100\n'); }); -test('a batch that names twenty thousand script versions still costs one bounded scan', async () => { +test('a batch that names three hundred script versions keeps the bounded candidate and costs one download', async () => { const { stateDir, destination } = journey(); const requested: string[] = []; - const server = http.createServer((req, res) => { - const id = decodeURIComponent(req.url?.replace('/artifacts/', '') ?? ''); - requested.push(id); - res.writeHead(200, { 'content-length': Buffer.byteLength('open Demo\n') }); - res.end('open Demo\n'); - }); - servers.push(server); - const baseUrl = `http://127.0.0.1:${await listenOnLoopback(server)}`; + const baseUrl = await artifactServer( + { v1: 'open Demo\n', 's2-r200': 'open Demo\nwait 100\n' }, + requested, + ); const id = await open(baseUrl, stateDir, destination); requested.length = 0; - // One answer names 20,000 versions of this publication, about 3 MB of JSON, in ascending order. - // Reading it costs this client a bounded scan, not one comparison per version it already saw. - const versions = Array.from({ length: 20_000 }, (_, i) => script(`v-${i}`, i + 1, id)); + // Three finished steps name a hundred versions each. Each payload is read for 32 of its own + // artifacts and the answer for 64 in all, so the scan stops at the second step and keeps revision + // 200. The third step names revision 999 first and is never inspected, so deleting the total bound + // would download `s3-r999`, and deleting the per-payload bound would download `s1-r64`. + const ascending = (from: number, to: number) => + Array.from({ length: to - from + 1 }, (_, i) => script(`s1-r${from + i}`, from + i, id)); + const descending = (from: number, to: number) => + Array.from({ length: to - from + 1 }, (_, i) => script(`s2-r${to - i}`, to - i, id)); const startedAt = Date.now(); - const response = await answer(baseUrl, stateDir, request('batch', {}, batchPlan('wait')), { + const response = await answer( + baseUrl, + stateDir, + request('batch', {}, batchPlan('wait', 'wait', 'wait')), + { + total: 3, + executed: 3, + totalDurationMs: 1, + results: [ + step(1, 'wait', { artifacts: ascending(1, 100) }), + step(2, 'wait', { artifacts: descending(101, 200) }), + step(3, 'wait', { artifacts: [script('s3-r999', 999, id)] }), + ], + }, + ); + + expect(requested).toEqual(['s2-r200']); + expect(Date.now() - startedAt).toBeLessThan(1000); + expect(payload(response).savedScript).toBe(destination); +}); + +test('a batch that names one hundred script versions in one step stops at the per-payload bound', async () => { + const { stateDir, destination } = journey(); + const requested: string[] = []; + const baseUrl = await artifactServer({ v1: 'open Demo\n' }, requested); + const id = await open(baseUrl, stateDir, destination); + requested.length = 0; + + // One payload is read for at most 32 of its own artifacts: revisions 1..32, revision 32 named last. + const versions = Array.from({ length: 100 }, (_, i) => script(`v-${i}`, i + 1, id)); + await answer(baseUrl, stateDir, request('batch', {}, batchPlan('wait')), { total: 1, executed: 1, totalDurationMs: 1, results: [step(1, 'wait', { artifacts: versions })], }); - expect(Date.now() - startedAt).toBeLessThan(1000); - expect(requested).toHaveLength(1); - expect(response.ok && response.data?.savedScript).toBe(destination); + expect(requested).toEqual(['v-31']); }); test('a successful batch delivers the newest version its own payload names', async () => { @@ -560,7 +675,7 @@ test('a successful batch delivers the newest version its own payload names', asy data, ); - expect(response.ok && response.data?.savedScript).toBe(destination); + expect(payload(response).savedScript).toBe(destination); expect(fs.readFileSync(destination, 'utf8')).toBe('open Demo\nsnapshot\n'); expect(records(stateDir)).toHaveLength(1); }); @@ -573,8 +688,7 @@ test('a successful batch retires the record for a close its own payload names', }); const id = await open(baseUrl, stateDir, destination); - // The plan ran `close`, and the answer names the publication on its own payload. A stale version the - // caller's file already holds may not be re-delivered, but the record still has to be retired. + // The plan ran `close`, and the answer names the publication on its own payload. const response = await answer(baseUrl, stateDir, request('batch', {}, batchPlan('close')), { total: 1, executed: 1, @@ -584,7 +698,7 @@ test('a successful batch retires the record for a close its own payload names', results: [step(1, 'close', { closed: true })], }); - expect(response.ok && response.data?.savedScript).toBe(destination); + expect(payload(response).savedScript).toBe(destination); expect(fs.readFileSync(destination, 'utf8')).toBe('open Demo\nclose\n'); expect(records(stateDir)).toEqual([]); }); @@ -646,15 +760,51 @@ test('a batch step that cannot save its version discloses it on the batch payloa // A batch's human and machine output reads the batch's own payload, so the failure and its // warning have to be lifted there — a step's nested data never reaches the CLI or the MCP text. - expect(response.ok && response.data?.scriptDeliveryFailure).toEqual( + expect(payload(response).scriptDeliveryFailure).toEqual( expect.objectContaining({ reason: 'script_delivery_failed', cause: 'script_download_failed', publicationId: id, }), ); - const warnings = (response.ok ? response.data?.warnings : undefined) as string[] | undefined; + const warnings = payload(response).warnings as string[]; expect(warnings).toHaveLength(1); - expect(warnings?.[0]).toContain('script'); + expect(warnings[0]).toContain('script'); expect(fs.readFileSync(destination, 'utf8')).toBe('open Demo\n'); }); + +/** + * The failed-batch path must not swallow a delivery problem: the caller keeps its batch error either + * way, so a diagnostic is the only trace that the steps that finished had a script nobody delivered. + */ +test('a failed batch whose step entries cannot be read reports the delivery failure', async () => { + const { stateDir, destination } = journey(); + const baseUrl = await artifactServer({ v1: 'open Demo\n' }); + const id = await open(baseUrl, stateDir, destination); + const partialResults: unknown[] = []; + Object.defineProperty(partialResults, 0, { + get(): never { + throw new Error('unreadable step entry'); + }, + enumerable: true, + configurable: true, + }); + + const { withDiagnosticsScope, countDiagnosticEventsByPhase } = + await import('@agent-device/host-kit/diagnostics'); + await withDiagnosticsScope({ command: 'batch' }, async () => { + const disclosure = await materializeRemoteBatchPartialArtifacts( + { baseUrl, token: 't' }, + request('batch', {}, batchPlan('wait', 'wait')), + { step: 2, command: 'wait', executed: 1, partialResults }, + stateDir, + ); + + expect(disclosure).toBeUndefined(); + expect(countDiagnosticEventsByPhase(['session_script_delivery_failed'])).toBe(1); + }); + // And the failure costs the caller nothing else: the recording and its file stand. + expect(id).toBeTruthy(); + expect(fs.readFileSync(destination, 'utf8')).toBe('open Demo\n'); + expect(records(stateDir)).toHaveLength(1); +}); diff --git a/packages/remote/src/daemon-artifacts.ts b/packages/remote/src/daemon-artifacts.ts index 2bdb55ce86..53dd4f4e90 100644 --- a/packages/remote/src/daemon-artifacts.ts +++ b/packages/remote/src/daemon-artifacts.ts @@ -15,7 +15,6 @@ import { recordingExtensionForPlatform, } from '@agent-device/capture-kit/recording-output-path'; import { parsePerfRuntimeRequest } from '@agent-device/capture-kit/perf-runtime-plan'; -import type { DeliveryContext as BatchDeliveryContext } from './remote-batch-script-delivery.ts'; import type { SessionScriptDelivery } from './session-script-destination.ts'; import { uploadArtifact } from './upload-client.ts'; import { withUploadPreparationDeadline } from './upload-stream.ts'; @@ -478,12 +477,12 @@ export async function materializeRemoteArtifacts( if (!info.baseUrl) return response; const endpoint = { baseUrl: info.baseUrl, token: info.token }; const artifacts = Array.isArray(response.data?.artifacts) ? response.data.artifacts : []; - // A batch answers with one entry per step, and a step's own script artifacts sit inside its - // result, so that response is delivered by the step-aware owner. It loads lazily and returns the - // response untouched when no step carries a script. + // A batch answers with one entry per step, and a step's own script artifact sits inside its result, + // so a batch is delivered by its own path rather than as one payload. if (req.command === BATCH_COMMAND) { - const { deliverRemoteBatchScripts } = await import('./remote-batch-script-delivery.ts'); - return await deliverRemoteBatchScripts(batchDeliveryContext(endpoint, req, stateDir), response); + const data = response.data ?? {}; + const disclosure = await deliverBatchScript(endpoint, req, data, stateDir); + return disclosure === undefined ? response : { ok: true, data: { ...data, ...disclosure } }; } const download = (scripts?: SessionScriptDelivery) => downloadResponseArtifacts(endpoint, req, response, host, scripts); @@ -499,17 +498,10 @@ export async function materializeRemoteArtifacts( } /** - * Delivers the session script of the steps a FAILED remote `batch` had completed. + * Delivers the session script of the steps a FAILED remote `batch` had completed, and answers the + * fields its error should disclose about that delivery. The caller keeps its own error either way. * - * The runner reports the finished steps in the error's `details.partialResults`, so a recording that an - * earlier step closed would be lost just because a later step failed. The completed prefix is derived - * from the plan THIS client submitted and cross-checked against the step the error names, so entries - * for steps at or after the failure authorize neither a download nor the retirement of the caller's - * record. The caller keeps its own error either way. - * - * Answers the fields the error should disclose about that delivery — the file it wrote, or a typed - * failure and its warning — which a batch error's reader prints alongside the failure. Never throws: a - * request the daemon answered still has to settle with its own error. + * Never throws: a request the daemon answered still has to settle with its own error. */ export async function materializeRemoteBatchPartialArtifacts( info: DaemonArtifactEndpoint, @@ -520,41 +512,150 @@ export async function materializeRemoteBatchPartialArtifacts( if (!info.baseUrl || req.command !== BATCH_COMMAND || !Array.isArray(details?.partialResults)) return undefined; try { - const { deliverSubmittedStepScripts, readBatchPlan, withBatchDisclosure } = - await import('./remote-batch-script-delivery.ts'); - const disclosure = await deliverSubmittedStepScripts( - batchDeliveryContext({ baseUrl: info.baseUrl, token: info.token }, req, stateDir), - readBatchPlan(req), - details, + const { readBatchPlan, readFinishedStepCount } = await import('./remote-batch-answer.ts'); + const plan = readBatchPlan(req.flags?.batchSteps); + const disclosure = await deliverBatchScript( + { baseUrl: info.baseUrl, token: info.token }, + req, + { results: details.partialResults }, + stateDir, + readFinishedStepCount(plan, details), ); - return disclosure ? { ...details, ...withBatchDisclosure(details, disclosure) } : undefined; - } catch { + return disclosure ? { ...details, ...disclosure } : undefined; + } catch (error) { + const { emitDiagnostic } = await import('@agent-device/host-kit/diagnostics'); + emitDiagnostic({ + level: 'warn', + phase: 'session_script_delivery_failed', + data: { session: req.session, error: String(error) }, + }); return undefined; } } -/** Command name of the request that runs several steps under one response. */ -const BATCH_COMMAND = 'batch'; - /** - * What the batch owner needs to deliver one payload: this client's endpoint and request, the file - * owner it writes under, and the two artifact helpers it may use. The owner never learns where a - * destination comes from; it is handed this client's own record of it. + * Delivers a remote `batch` answer's session script: AT MOST ONE version, the newest this client's own + * plan is owed. Every version is the whole recording, so an older one is worth nothing, and this never + * changes the batch's outcome. The plan is the only authority — a step the caller never ran, or never + * finished, authorizes no download and no retirement. */ -function batchDeliveryContext( +async function deliverBatchScript( endpoint: Required, req: DaemonWireRequest, + data: Record, stateDir: string, -): BatchDeliveryContext { - return { + finished?: number, +): Promise | undefined> { + // Both owners load on demand: the batch readers pull in the command registry, and the script owner + // the download path, neither of which the client evaluates for a response that names no script. + const [{ isPublishableScriptVersion, sessionScriptDelivery }, answer] = await Promise.all([ + import('./session-script-destination.ts'), + import('./remote-batch-answer.ts'), + ]); + const plan = answer.readBatchPlan(req.flags?.batchSteps); + const finishedCount = finished ?? plan.length; + const steps = answer.readFinishedSteps( + Array.isArray(data.results) ? data.results : [], + plan, + finishedCount, + ); + const listed = asArtifacts(data.artifacts); + // The batch's own payload is scanned FIRST: after the last step the daemon stamps its newest version + // there, and the bound below keeps that version even by an answer that crowds the step entries out. + const newest = newestScriptVersion( + [listed, ...steps.map((step) => asArtifacts(step.data?.artifacts))], + isPublishableScriptVersion, + ); + const version = newest?.artifact; + // Where that version came from, in plan order. The batch payload is stamped after the LAST step, so + // it sits past every step: a version from there supersedes a failure an earlier step reported. + const deliveredFrom = + newest === undefined ? undefined : newest.source === 0 ? steps.length : newest.source - 1; + const publication = batchPublicationId(steps, data) ?? version?.scriptPublicationId; + // A close the PLAN ran and finished ends the recording, and the caller stops tracking it — with or + // without a version to deliver. The owner locates the record by hashing this client's own endpoint, + // tenant and session with that ID, so an ID the daemon invents retires nothing. + const closed = answer.readFinishedClose(plan, finishedCount) ? publication : undefined; + if (version === undefined && closed === undefined) return undefined; + // The answer's own list is rewritten the way a single response's is: its session-script entries are + // the owner's to answer for, and the one it delivers comes back with `localPath`. + const listedScripts = listed.some(isSessionScriptArtifact); + const kept = listed.filter((artifact) => !isSessionScriptArtifact(artifact)); + const payload: Record = {}; + const scripts = sessionScriptDelivery( endpoint, req, + { ok: true, data: payload }, stateDir, - download: downloadRemoteArtifact, - isScriptArtifact: isSessionScriptArtifact, - }; + downloadRemoteArtifact, + closed, + ); + await scripts.settleAfter(async () => { + if (version !== undefined) await scripts.publish(version, payload, kept); + return { ok: true, data: payload }; + }); + return answer.readBatchDisclosure( + payload, + steps, + deliveredFrom, + publication, + listedScripts ? kept : undefined, + ); +} + +/** The recording this batch reports, from what the answer names: only a recorded one can be opened. */ +function batchPublicationId( + steps: ReadonlyArray<{ data: Record | undefined }>, + data: Record, +): string | undefined { + return [...steps.map((step) => step.data?.scriptPublicationId), data.scriptPublicationId].find( + (id): id is string => typeof id === 'string', + ); +} + +function asArtifacts(value: unknown): DaemonArtifact[] { + return Array.isArray(value) ? (value as DaemonArtifact[]) : []; +} + +/** + * The newest script version among these payloads' artifact lists, with the index of the list that + * carried it, or `undefined`. The scan is linear and bounded per list and in all, so one answer cannot + * make this client read what it is not owed, and a version past a bound is never inspected. Each + * candidate passes the publisher's own guard, so no response value that cannot name a version reaches + * a record lookup, a path, or a download request. + */ +function newestScriptVersion( + lists: readonly DaemonArtifact[][], + isPublishable: (artifact: DaemonArtifact | undefined) => boolean, +): { artifact: DaemonArtifact; source: number } | undefined { + let newest: { artifact: DaemonArtifact; source: number } | undefined; + let scanned = 0; + lists.forEach((list, source) => { + for (const artifact of list.slice(0, MAX_SCRIPT_ARTIFACTS_PER_ENTRY)) { + if (scanned >= MAX_SCRIPT_ARTIFACTS_PER_BATCH) return; + scanned += 1; + if (!isPublishable(artifact)) continue; + if (newest === undefined || (artifact.scriptRevision as number) > revisionOf(newest.artifact)) + newest = { artifact, source }; + } + }); + return newest; +} + +/** The revision one publishable artifact names. */ +function revisionOf(artifact: DaemonArtifact): number { + return artifact.scriptRevision as number; } +/** Command name of the request that runs several steps under one response. */ +const BATCH_COMMAND = 'batch'; + +/** One payload is read for at most this many of its own script artifacts. */ +const MAX_SCRIPT_ARTIFACTS_PER_ENTRY = 32; + +/** One batch answer is read for at most this many script artifacts in all. */ +const MAX_SCRIPT_ARTIFACTS_PER_BATCH = 64; + async function downloadResponseArtifacts( endpoint: Required, req: DaemonWireRequest, diff --git a/packages/remote/src/remote-batch-answer.ts b/packages/remote/src/remote-batch-answer.ts new file mode 100644 index 0000000000..e9089afafc --- /dev/null +++ b/packages/remote/src/remote-batch-answer.ts @@ -0,0 +1,127 @@ +/** + * What a remote `batch` answer says about its steps, read from the plan THIS client submitted. + * + * A batch answers one entry per step, and every field of that answer is untrusted. This module holds + * the readers that decide what the caller is owed: which steps finished, which script version is the + * newest of them, and which report the client has to disclose. `daemon-artifacts.ts` loads it only for + * a batch answer, because these readers pull in the command registry and the response readers the + * client's eager module closure does not otherwise evaluate. + */ + +import { normalizeBatchCommandName } from '@agent-device/command-registry/batch-policy'; +import { + readScriptDeliveryFailure, + type DaemonArtifact, + type ScriptDeliveryFailure, +} from '@agent-device/kernel/contracts'; +import { readResponseWarnings } from '@agent-device/kernel/success-text'; +import { isRecord } from '@agent-device/kernel/record'; + +/** One finished plan step: the payload the daemon answered for it, and the failure it reports. */ +export type BatchFinishedStep = Readonly<{ + data: Record | undefined; + failure?: ScriptDeliveryFailure; +}>; + +/** + * The plan THIS client submitted, each step named the way the daemon names a step: the runner + * normalizes a step name before it runs it, and answers with the normalized name. + */ +export function readBatchPlan(steps: unknown): string[] { + if (!Array.isArray(steps)) return []; + return steps.map((step) => normalizeBatchCommandName(isRecord(step) ? step.command : undefined)); +} + +/** + * How many steps had finished before a failure: the steps before the one the error names. The runner + * reports the failing step's number, how many steps it ran, and that step's command; all three must + * line up with the caller's own plan, so a report that does not describe a step this client ran + * finishes nothing, and no step entry can then authorize a download or a retirement. + */ +export function readFinishedStepCount( + plan: readonly string[], + failure: Record, +): number { + const { step, executed, command } = failure; + if ( + typeof step !== 'number' || + typeof executed !== 'number' || + !Number.isSafeInteger(step) || + !Number.isSafeInteger(executed) || + step < 1 || + executed < 0 || + step !== executed + 1 || + step > plan.length || + normalizeBatchCommandName(command) !== plan[step - 1] + ) + return 0; + return executed; +} + +/** The plan's own finished steps, in plan order: each entry must name that step and be a step that finished. */ +export function readFinishedSteps( + results: readonly unknown[], + plan: readonly string[], + finished: number, +): BatchFinishedStep[] { + const steps: BatchFinishedStep[] = []; + for (let index = 0; index < finished; index += 1) { + const result = results[index]; + if (!isRecord(result) || result.ok !== true || result.step !== index + 1) continue; + const command = normalizeBatchCommandName(result.command); + if (command === '' || command !== plan[index]) continue; + const data = isRecord(result.data) ? result.data : undefined; + steps.push({ data, failure: readScriptDeliveryFailure(data) }); + } + return steps; +} + +/** + * Whether the finished part of the plan ran the step that ends the recording: a close the caller never + * submitted, or never finished, leaves the recording open and the caller's record in place. + */ +export function readFinishedClose(plan: readonly string[], finished: number): boolean { + return plan.slice(0, finished).includes('close'); +} + +/** + * What one delivery discloses on the batch payload: the file it wrote, the answer's own artifact list, + * and ONE typed failure with the warning paired to it. This client's own failure wins; otherwise it is + * the last failure a finished step reported for this recording, unless the version this client saved + * came from a step AFTER the one that reported it. A step's nested data reaches neither the CLI's + * `Warning:` lines nor the MCP tool text, and a warning belonging to another report stays on its step. + */ +export function readBatchDisclosure( + payload: Record, + steps: readonly BatchFinishedStep[], + deliveredFrom: number | undefined, + publication: string | undefined, + artifacts: DaemonArtifact[] | undefined, +): Record | undefined { + // The LAST finished step that reports a failure of THIS recording, in plan order. + let reported: BatchFinishedStep | undefined; + let reportedAt = -1; + steps.forEach((step, index) => { + if (step.failure !== undefined && step.failure.publicationId === publication) { + reported = step; + reportedAt = index; + } + }); + // The version this client saved was published AFTER that step reported its failure, so the file is + // newer than the report and the report says nothing the caller still needs. + const superseded = deliveredFrom !== undefined && deliveredFrom > reportedAt; + const own = readScriptDeliveryFailure(payload); + const failure = own ?? (superseded ? undefined : reported?.failure); + const disclosure: Record = {}; + if (typeof payload.savedScript === 'string') disclosure.savedScript = payload.savedScript; + if (artifacts !== undefined) disclosure.artifacts = artifacts; + if (failure === undefined) return Object.keys(disclosure).length > 0 ? disclosure : undefined; + const source = own === undefined && reported !== undefined ? reported.data : payload; + disclosure.scriptDeliveryFailure = failure; + // Only the warning written beside this failure rides up, never every step's warnings. + const paired = readResponseWarnings(source).filter( + (warning) => warning.includes(failure.message) || warning.includes(failure.hint), + ); + disclosure.warnings = paired.length > 0 ? paired : [`${failure.message} ${failure.hint}`]; + return disclosure; +} diff --git a/packages/remote/src/remote-batch-script-delivery.ts b/packages/remote/src/remote-batch-script-delivery.ts deleted file mode 100644 index ba6bd89eff..0000000000 --- a/packages/remote/src/remote-batch-script-delivery.ts +++ /dev/null @@ -1,333 +0,0 @@ -import type { DaemonWireRequest } from '@agent-device/contracts/command'; -import type { DaemonArtifact, DaemonResponse } from '@agent-device/kernel/contracts'; -import { isRecord } from '@agent-device/kernel/record'; -import { readResponseWarnings } from '@agent-device/kernel/success-text'; -import type { downloadRemoteArtifact } from './daemon-artifacts.ts'; - -/** - * Delivers the session script a remote `batch` answer carries: AT MOST ONE version, the newest one - * this client's plan authorizes, wherever the answer names it — in a finished step's result or on the - * batch payload itself. - * - * Every version is the whole recording from the `open`, so an older one is worth nothing and one batch - * never owes more than a single download. The batch's outcome is not changed here: a successful batch - * stays successful, a failed one keeps its own error, and a version that cannot be saved is reported - * the same way a single response reports it. - * - * The plan THIS client submitted is the only authority, never the answer. A step the caller never ran, - * or never finished, authorizes no download and no retirement, and a batch request that submitted no - * plan authorizes nothing at all. - */ -export async function deliverRemoteBatchScripts( - context: DeliveryContext, - response: Extract, -): Promise { - const data = isRecord(response.data) ? response.data : {}; - const plan = readBatchPlan(context.req); - const disclosure = await deliverBatchScript(context, plan, data, plan.length); - return disclosure === undefined - ? response - : { ok: true, data: { ...data, ...withBatchDisclosure(data, disclosure) } }; -} - -/** - * Delivers the session script of the steps a FAILED remote `batch` had completed, and answers the - * fields its error should disclose about that delivery. - * - * The runner reports the finished steps in the error's `details.partialResults`, so a recording that an - * earlier step closed would be lost just because a later step failed. The completed prefix is derived - * from the plan and cross-checked against the step the error names, so entries for steps at or after - * the failure — which the runner never produces — authorize neither a download nor the retirement of - * the caller's record. - */ -export async function deliverSubmittedStepScripts( - context: DeliveryContext, - plan: readonly string[], - details: Record | undefined, -): Promise | undefined> { - return await deliverBatchScript( - context, - plan, - { results: details?.partialResults }, - readCompletedStepCount(plan, details), - ); -} - -/** What it takes to deliver one batch's script: this client's own endpoint, request and file owner. */ -export type DeliveryContext = Readonly<{ - endpoint: Readonly<{ baseUrl: string; token: string }>; - req: DaemonWireRequest; - stateDir: string; - download: typeof downloadRemoteArtifact; - isScriptArtifact: (artifact: DaemonArtifact | undefined) => boolean; -}>; - -/** - * The commands the caller submitted, in step order. A batch request with no plan authorizes nothing: - * with no way to tell a real step from a planted one, the answer is left alone. - */ -export function readBatchPlan(req: DaemonWireRequest): string[] { - const steps = req.flags?.batchSteps; - if (!Array.isArray(steps)) return []; - return steps.map((step) => normalizeStepCommand(isRecord(step) ? step.command : undefined)); -} - -/** - * How many of the caller's steps had finished before a failure. The runner reports both the failing - * step's number and the number of steps it executed; the two must agree on one boundary before any - * step entry counts as finished, so a report that does not describe a step this client ran authorizes - * nothing. - */ -function readCompletedStepCount( - plan: readonly string[], - failure: Record | undefined, -): number { - if (failure === undefined) return plan.length; - const step = failure.step; - const executed = failure.executed; - if ( - typeof step !== 'number' || - typeof executed !== 'number' || - !Number.isSafeInteger(step) || - !Number.isSafeInteger(executed) || - step < 1 || - executed < 0 || - step !== executed + 1 - ) - return 0; - return Math.min(executed, plan.length); -} - -/** One plan step this client ran and finished, with the payload the daemon answered for it. */ -type FinishedStep = Readonly<{ command: string; data: Record | undefined }>; - -/** - * The plan's own finished steps within the completed prefix, in plan order. Only the prefix is read, so - * the work is bounded by the plan the caller submitted rather than by what the answer carries. An entry - * that is not the plan's own command at the plan's own position, or that did not finish, is not - * authorized and is never read for a script. - */ -function readFinishedSteps( - data: Record, - plan: readonly string[], - completed: number, -): FinishedStep[] { - const results = Array.isArray(data.results) ? data.results : []; - const finished: FinishedStep[] = []; - for (let index = 0; index < completed; index += 1) { - const command = plan[index] ?? ''; - const result = results[index]; - if (isFinishedStep(result, command, index)) - finished.push({ command, data: isRecord(result.data) ? result.data : undefined }); - } - return finished; -} - -function isFinishedStep( - result: unknown, - plannedCommand: string, - index: number, -): result is Record { - return ( - plannedCommand !== '' && - isRecord(result) && - result.step === index + 1 && - result.ok === true && - normalizeStepCommand(result.command) === plannedCommand - ); -} - -/** - * Delivers the newest version this batch is owed, or answers `undefined` when it is owed none. - * - * The session-script owner stays the only owner of `savedScript`, of the destination rule and of the - * retirement, and it is handed a payload of its own rather than the caller's response: the batch's - * payload is the daemon's answer, and what the delivery produced is merged onto it afterwards. The - * owner is asked under `close` when the plan ran a close, which is what lets it publish the final - * version and then retire this client's record exactly as a single `close` response does — including - * when the close carried no version, because the daemon may have failed to write it and the caller - * still has to stop tracking a recording it no longer has. - */ -async function deliverBatchScript( - context: DeliveryContext, - plan: readonly string[], - data: Record, - completed: number, -): Promise | undefined> { - if (plan.length === 0 || completed < 1) return undefined; - const steps = readFinishedSteps(data, plan, completed); - const closing = steps.some((step) => step.command === CLOSE_COMMAND); - const versions = readScriptVersions(context, steps, data); - const publicationId = openPublicationId(steps, data, versions); - // Retirement follows the PLAN alone: a close this client ran and finished, and no field an answer - // carries. The owner finds this client's record by hashing the ID with its own endpoint, tenant and - // session, so an ID the daemon invents matches no record and retires nothing. - const retires = closing && typeof publicationId === 'string'; - const newest = newestScriptVersion(versions, publicationId); - if (newest === undefined && !retires) return undefined; - const { sessionScriptDelivery } = await import('./session-script-destination.ts'); - const payload: Record = {}; - if (typeof publicationId === 'string') payload.scriptPublicationId = publicationId; - const scripts = sessionScriptDelivery( - context.endpoint, - { ...context.req, command: closing ? CLOSE_COMMAND : context.req.command }, - { ok: true, data: payload }, - context.stateDir, - context.download, - ); - await scripts.settleAfter(async () => { - if (newest !== undefined) await scripts.publish(newest, payload, []); - return { ok: true, data: payload }; - }); - return disclosedDelivery(payload, steps); -} - -/** - * Every session-script version this batch's answer carries, from the plan's finished steps AND the - * batch's own payload: a step may publish as it goes, and the daemon may stamp its newest version on - * the batch payload after the last step, so both are read whatever the other one holds. - * - * One linear scan, bounded by MAX_SCRIPT_ARTIFACTS_PER_ENTRY artifacts per payload and - * MAX_SCRIPT_ARTIFACTS_PER_BATCH in total, so the cost stays bounded whatever an answer names. Each - * candidate must satisfy the same guards the publisher uses, so nothing this module cannot name is ever - * interpolated into a record lookup, a path, or a download request. - */ -function readScriptVersions( - context: DeliveryContext, - steps: readonly FinishedStep[], - data: Record, -): DaemonArtifact[] { - const versions: DaemonArtifact[] = []; - let scanned = 0; - // The batch's own payload is read first: the daemon stamps its newest version there after the last - // step, so the bound below keeps the version the caller is owed even by a crowded answer. - for (const payload of [data, ...steps.map((step) => step.data)]) { - const artifacts = Array.isArray(payload?.artifacts) - ? (payload.artifacts as DaemonArtifact[]) - : []; - for (const artifact of artifacts.slice(0, MAX_SCRIPT_ARTIFACTS_PER_ENTRY)) { - if (scanned >= MAX_SCRIPT_ARTIFACTS_PER_BATCH) return versions; - scanned += 1; - if (context.isScriptArtifact(artifact) && isUsableVersion(artifact)) versions.push(artifact); - } - } - return versions; -} - -/** - * The publication this batch records, taken in order of authority: the ID the plan's own finished - * `close` step names, then the ID the first finished step names, then the ID the batch payload echoes, - * then the ID of the newest version the answer carries. Only versions of that one publication are - * delivered, and only a publication THIS client recorded can ever be published, so an ID the daemon - * invents costs no download and retires nothing. - */ -function openPublicationId( - steps: readonly FinishedStep[], - data: Record, - versions: readonly DaemonArtifact[], -): string | undefined { - return [ - steps.find((step) => step.command === CLOSE_COMMAND)?.data?.scriptPublicationId, - steps.find((step) => typeof step.data?.scriptPublicationId === 'string')?.data - ?.scriptPublicationId, - data.scriptPublicationId, - newestScriptVersion(versions, undefined)?.scriptPublicationId, - ].find((id): id is string => typeof id === 'string'); -} - -/** - * The newest version of the open publication, or `undefined` when `publicationId` is not given and the - * newest version of any publication is wanted. Every version is the whole recording, so an older one is - * the same file with less of it: keeping only the newest is what makes one answer that names a thousand - * versions of one step, or of several steps, cost ONE download instead of a thousand. - */ -function newestScriptVersion( - versions: readonly DaemonArtifact[], - publicationId: string | undefined, -): DaemonArtifact | undefined { - let newest: DaemonArtifact | undefined; - for (const version of versions) { - if (publicationId !== undefined && version.scriptPublicationId !== publicationId) continue; - if ( - newest === undefined || - (version.scriptRevision as number) > (newest.scriptRevision as number) - ) - newest = version; - } - return newest; -} - -/** - * Whether one artifact names a version the publisher can act on: the guards `publishScriptVersion` - * uses. A malformed ID, revision or artifact ID is dropped here rather than reaching a record lookup, a - * download request, or an error message, and the response's own bytes never become a path component. - */ -function isUsableVersion(artifact: DaemonArtifact): boolean { - const revision = artifact.scriptRevision; - return ( - artifact.field === 'savedScript' && - typeof artifact.scriptPublicationId === 'string' && - typeof artifact.artifactId === 'string' && - Number.isSafeInteger(revision) && - (revision as number) > 0 - ); -} - -/** - * What one delivery and the plan's finished steps disclose on the caller's payload: the file that was - * written, and every script warning — the typed failure and its warning from this client's own - * delivery, and what the daemon disclosed on a step. A step's nested data reaches neither the CLI's - * `Warning:` lines nor the MCP tool text, so anything the caller has to see is lifted here. The - * daemon's answer itself is left intact. - */ -function disclosedDelivery( - payload: Record, - steps: readonly FinishedStep[], -): Record | undefined { - const failure = payload.scriptDeliveryFailure; - const disclosure: Record = {}; - if (payload.savedScript !== undefined) disclosure.savedScript = payload.savedScript; - if (isRecord(failure)) disclosure.scriptDeliveryFailure = failure; - const warnings = [ - ...new Set([ - ...readResponseWarnings(payload), - ...steps.flatMap((step) => readResponseWarnings(step.data)), - ]), - ].filter((warning) => warning !== ''); - if (warnings.length > 0) disclosure.warnings = warnings; - return Object.keys(disclosure).length > 0 ? disclosure : undefined; -} - -/** - * Lifts a batch's script disclosure onto the payload every caller surface reads: the CLI's `Warning:` - * lines, the MCP tool text, and `--json` and structured content all take the batch's own `warnings` and - * `scriptDeliveryFailure`, which a step's nested data cannot reach. - */ -export function withBatchDisclosure( - data: Record | undefined, - disclosure: Record | undefined, -): Record { - if (!disclosure) return {}; - const warnings = [ - ...new Set([...readResponseWarnings(data), ...readResponseWarnings(disclosure)]), - ].filter((warning) => warning !== ''); - return { - ...(warnings.length > 0 ? { warnings } : {}), - ...(disclosure.scriptDeliveryFailure !== undefined - ? { scriptDeliveryFailure: disclosure.scriptDeliveryFailure } - : {}), - ...(disclosure.savedScript !== undefined ? { savedScript: disclosure.savedScript } : {}), - }; -} - -function normalizeStepCommand(command: unknown): string { - return typeof command === 'string' ? command.trim().toLowerCase() : ''; -} - -const CLOSE_COMMAND = 'close'; - -/** One payload is read for at most this many of its own script artifacts. */ -const MAX_SCRIPT_ARTIFACTS_PER_ENTRY = 32; - -/** One batch answer is read for at most this many script artifacts in total, across every payload. */ -const MAX_SCRIPT_ARTIFACTS_PER_BATCH = 64; diff --git a/packages/remote/src/session-script-destination.ts b/packages/remote/src/session-script-destination.ts index a91c1bca70..e3752d44b3 100644 --- a/packages/remote/src/session-script-destination.ts +++ b/packages/remote/src/session-script-destination.ts @@ -88,9 +88,11 @@ export type SessionScriptDelivery = Readonly<{ /** * 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. + * recorded, and retires the record a close names: the one this request's own `close` answer names, or + * the one `closedPublicationId` names when the caller is answering for a close it already ran. A + * version that cannot be saved keeps the response successful and adds `scriptDeliveryFailure` and a + * warning. A close retires its record even when another artifact fails, and the first error is the one + * reported. */ export function sessionScriptDelivery( endpoint: Required, @@ -98,9 +100,14 @@ export function sessionScriptDelivery( response: Extract, stateDir: string, download: typeof downloadRemoteArtifact, + closedPublicationId?: unknown, ): SessionScriptDelivery { - const named = response.data?.scriptPublicationId; - const closedId = req.command === 'close' && typeof named === 'string' ? named : undefined; + const closedId = + typeof closedPublicationId === 'string' + ? closedPublicationId + : req.command === 'close' && typeof response.data?.scriptPublicationId === 'string' + ? response.data.scriptPublicationId + : undefined; const retire = async (): Promise => { if (closedId === undefined) return; const file = recordPath(stateDir, endpoint.baseUrl, req, closedId); @@ -151,6 +158,24 @@ export function sessionScriptDelivery( return delivery; } +/** + * Whether one artifact names a version this client can publish: the `savedScript` field, the + * session-script type, a string publication ID and artifact ID, and a positive integer revision. + * `publishScriptVersion` refuses anything else, and the batch path reads an untrusted answer through + * this same guard, so no response value that cannot name a version reaches a record lookup, a path, or + * a download request. + */ +export function isPublishableScriptVersion(artifact: DaemonArtifact | undefined): boolean { + return ( + artifact?.field === 'savedScript' && + artifact.artifactType === 'session-script' && + typeof artifact.scriptPublicationId === 'string' && + typeof artifact.artifactId === 'string' && + Number.isSafeInteger(artifact.scriptRevision) && + (artifact.scriptRevision as number) > 0 + ); +} + /** * 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 @@ -172,15 +197,9 @@ async function publishScriptVersion( ): Promise { const { endpoint, req, stateDir } = context; const { scriptPublicationId: id, scriptRevision: revision, artifactId } = artifact; - const file = - artifact.field === 'savedScript' && - artifact.artifactType === 'session-script' && - typeof id === 'string' && - typeof artifactId === 'string' && - Number.isSafeInteger(revision) && - (revision as number) > 0 - ? recordPath(stateDir, endpoint.baseUrl, req, id) - : undefined; + const file = isPublishableScriptVersion(artifact) + ? recordPath(stateDir, endpoint.baseUrl, req, id as string) + : undefined; const record = file ? readRecord(file) : undefined; if (!file || !record) { emitDiagnostic({ diff --git a/packages/remote/tsconfig.json b/packages/remote/tsconfig.json index c2bf98d842..943ef4aef0 100644 --- a/packages/remote/tsconfig.json +++ b/packages/remote/tsconfig.json @@ -12,6 +12,7 @@ "include": ["src"], "references": [ { "path": "../capture-kit" }, + { "path": "../command-registry" }, { "path": "../contracts" }, { "path": "../daemon-contracts" }, { "path": "../host-kit" }, diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 655e62ee8e..18eeb76772 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -1042,6 +1042,9 @@ importers: '@agent-device/capture-kit': specifier: workspace:* version: link:../capture-kit + '@agent-device/command-registry': + specifier: workspace:* + version: link:../command-registry '@agent-device/contracts': specifier: workspace:* version: link:../contracts diff --git a/src/cli/commands/__tests__/screenshot.test.ts b/src/cli/commands/__tests__/screenshot.test.ts index 626b916b45..dece774ae0 100644 --- a/src/cli/commands/__tests__/screenshot.test.ts +++ b/src/cli/commands/__tests__/screenshot.test.ts @@ -77,6 +77,37 @@ test('screenshot --json carries response-level warnings in the data', async () = assert.deepEqual(parsed.data.warnings, [CROP_WARNING]); }); +// ADR 0016 (#4564): a capture whose remote script version did not arrive keeps its success, so the +// typed failure has to ride the machine view this command prints. `pickScreenshotResultData` narrows +// the capture payload for its own callers, so this command adds the disclosure itself. +test('screenshot --json carries a failed script delivery of the capture', async () => { + const failure = { + reason: 'script_delivery_failed', + cause: 'script_write_failed', + publicationId: '0f61b0c2-6d1a-4d1f-9b7f-2a4f3a1c7d55', + message: 'The session recorded version 2, but the daemon could not save it.', + hint: 'The file keeps the version from the last action that arrived.', + }; + const client = clientReturning({ + path: '/tmp/shot.png', + width: 40, + height: 20, + warnings: [failure.message], + scriptDeliveryFailure: failure, + }); + const flags = { json: true } as CliFlags; + + const out = await withCapturedStdoutAsync(() => + screenshotCommand({ host: createTestHostEnvironment(), positionals: [], flags, client }), + ); + const parsed = JSON.parse(out) as { + data: { path: string; warnings?: string[]; scriptDeliveryFailure?: unknown }; + }; + + assert.deepEqual(parsed.data.scriptDeliveryFailure, failure); + assert.deepEqual(parsed.data.warnings, [failure.message]); +}); + test('screenshot --json at the default level still emits normalized screenshot metadata', async () => { const full = { path: '/tmp/shot.png', diff --git a/test/wire-compat/ledger.json b/test/wire-compat/ledger.json index fd693a060c..f03e752e69 100644 --- a/test/wire-compat/ledger.json +++ b/test/wire-compat/ledger.json @@ -155,7 +155,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:d26bb633f219192e9c9c1e93a7dab6869608224697c6ccba8ebb0c1591899574", + "packages/remote/src/daemon-artifacts.ts#materializeRemoteArtifacts": "sha256:06443554e8e7ebeb4826f08a5146a635c42e27eb5bef770f04276403fd8fcd58", "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", @@ -215,7 +215,7 @@ "packages/daemon-contracts/src/daemon-resolution.ts#readDaemonCapabilities": "sha256:e410d36be74d307f7e5d8ddae63af5aae77f8eef77951ce9eeb7724f2fefae88", "packages/remote/src/daemon-artifacts.ts#downloadResponseArtifacts": "sha256:42d78f01311e3e0c5f9099ef72e3c6258241e66204747aa176a55cd5191a2145", "packages/remote/src/session-script-destination.ts#SessionScriptDelivery": "sha256:741fafbb8e2b43e2e967b2f4206f1d60017a636f63e3cde68b6258fd4efefa18", - "packages/remote/src/session-script-destination.ts#publishScriptVersion": "sha256:9d6ceb538019c0ce30813fcf98d2484c5abc2d8fd7a3dfdd4141cf6430f086ff", + "packages/remote/src/session-script-destination.ts#publishScriptVersion": "sha256:34fc656a8423ed43bd04420fa28a7f911412cf69bb81ea7d755fe53ed2354ef5", "packages/remote/src/session-script-destination.ts#PublishOutcome": "sha256:a4ae6fc3298d3c560719591372edddbfa83ce749f4cf3f3e2ed1d8369313bd2d", "packages/remote/src/session-script-destination.ts#sendRemoteScriptOpen": "sha256:10ab07a6f276c7b03996c6b46fa218e03e7b1d21e2c95df5515dfb88095416b6", "packages/remote/src/session-script-destination.ts#RemoteEndpoint": "sha256:9c48e8e0ee14a25b85ebd930243fd263134836b35ecda55fb927919911263c15" @@ -243,8 +243,8 @@ }, { "declaration": "packages/remote/src/daemon-artifacts.ts#materializeRemoteArtifacts", - "digest": "sha256:d26bb633f219192e9c9c1e93a7dab6869608224697c6ccba8ebb0c1591899574", - "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. #4564 hands a batch response to a batch script owner, which delivers AT MOST ONE version per batch: it takes the newest session-script version the answer carries, in a finished step or on the batch payload itself, publishes it through the session-script owner, and retires the client record only when the submitted plan itself ran and finished a close step. The request and response framing are unchanged: a batch answer already carried the step results, and the client only writes files it already owns the destination for. A released client keeps the daemon's own step entries as they were answered and adds its delivery fields to the batch payload. #4564 also hands that owner a small context record built by a private helper, and the sibling `materializeRemoteBatchPartialArtifacts` delivers the newest version of the steps a FAILED batch finished, from the error's existing `partialResults`; both read what the daemon already answered, so request and response framing are unchanged." + "digest": "sha256:06443554e8e7ebeb4826f08a5146a635c42e27eb5bef770f04276403fd8fcd58", + "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. #4564 hands a batch response to a batch script owner, which delivers AT MOST ONE version per batch: it takes the newest session-script version the answer carries, in a finished step or on the batch payload itself, publishes it through the session-script owner, and retires the client record only when the submitted plan itself ran and finished a close step. The request and response framing are unchanged: a batch answer already carried the step results, and the client only writes files it already owns the destination for. A released client keeps the daemon's own step entries as they were answered and adds its delivery fields to the batch payload. #4564 also keeps that delivery inside this module, and the sibling `materializeRemoteBatchPartialArtifacts` delivers the newest version of the steps a FAILED batch finished, from the error's existing `partialResults`; both read what the daemon already answered, so request and response framing are unchanged. The batch path then answers the batch payload's own `artifacts` list the way a single response does, dropping the script entry it could not deliver and naming `localPath` on the one it did." }, { "declaration": "packages/daemon-client/src/daemon-client-rpc.ts#buildHttpRpcPayload", diff --git a/website/docs/docs/remote-proxy.md b/website/docs/docs/remote-proxy.md index 79f03e6660..cdddf86270 100644 --- a/website/docs/docs/remote-proxy.md +++ b/website/docs/docs/remote-proxy.md @@ -126,8 +126,10 @@ batch steps are refused. A `batch` delivers the newest version its answer names, carried it or the batch result itself did, and a batch that closes the recording retires it the same way a standalone `close` does. Every version is the full recording, so one batch costs at most one download. When a later step fails, the script the steps that already ran recorded is still delivered, -and the batch error stands. A script that did not arrive is reported on the batch result itself, so -the `Warning:` line and the `scriptDeliveryFailure` field reach the batch output. +and the batch error stands. The batch result carries `scriptDeliveryFailure` when this client's own +delivery, or a step that finished, reports one for the recording and no newer version was saved after +that report. Only the warning written beside that failure is reported with it, so a capture warning +from another step stays on its step. 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