diff --git a/docs/adr/0016-active-session-script-publication.md b/docs/adr/0016-active-session-script-publication.md index a7f4c2937b..f6a7cce9d6 100644 --- a/docs/adr/0016-active-session-script-publication.md +++ b/docs/adr/0016-active-session-script-publication.md @@ -204,15 +204,18 @@ 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 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. + 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). -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. -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/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/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..b00e671665 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 }, }; }, @@ -605,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 } : {}), @@ -614,6 +616,9 @@ function optionalSnapshotResponseFields( ...readSerializedSnapshotCaptureAnnotations(data), ...(unchanged ? { unchanged: unchanged as CaptureSnapshotResult['unchanged'] } : {}), ...(snapshotDiagnostics ? { snapshotDiagnostics } : {}), + // `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/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-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/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-client/src/__tests__/daemon-client-rpc.test.ts b/packages/daemon-client/src/__tests__/daemon-client-rpc.test.ts index 243c3dd1ee..68ff545d52 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,366 @@ 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 }, + // The report says step 3 failed after 2 finished steps, so the caller submitted three. + 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)}`); + 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); + } +}); + +/** + * 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); + } +}); + +/** + * 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', + 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/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/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 new file mode 100644 index 0000000000..8888fc9256 --- /dev/null +++ b/packages/remote/src/__tests__/daemon-artifacts-batch-script.test.ts @@ -0,0 +1,810 @@ +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, + materializeRemoteBatchPartialArtifacts, +} 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, 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, + 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'); + 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'] = {}, + 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 { + return { + field: 'savedScript', + artifactType: 'session-script', + artifactId, + scriptPublicationId: publicationId, + scriptRevision: revision, + }; +} + +/** 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) + ? 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>; +} + +/** 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 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); + expect(text).not.toContain('"savedScript":'); + expect(text).not.toContain('"localPath":'); + expect(text).not.toContain('"scriptDeliveryFailure":'); +} + +test('a batch delivers its newest script once and a close step retires the record', async () => { + const { stateDir, destination } = journey(); + 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( + 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)] }), + ], + }, + ); + + // 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 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']); +}); + +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); + + const response = await answer(baseUrl, stateDir, request('batch', {}, batchPlan('wait')), { + total: 1, + executed: 1, + totalDurationMs: 1, + 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(payload(response).scriptDeliveryFailure).toEqual( + expect.objectContaining({ + reason: 'script_delivery_failed', + cause: 'script_download_failed', + publicationId: id, + }), + ); + // 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); +}); + +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', {}, batchPlan('close')), { + 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(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([]); +}); + +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', {}, 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' }], + }), + ], + }, + ); + + 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); +}); + +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', {}, 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, 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, + totalDurationMs: 1, + results: [ + step(1, 'close', { + scriptPublicationId: id, + scriptDeliveryFailure: failure, + warnings: [`${failure.message} ${failure.hint}`], + }), + ], + }); + + expect(records(stateDir)).toEqual([]); + expect(fs.readFileSync(destination, 'utf8')).toBe('open Demo\n'); + // 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(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 () => { + 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('a batch step named with other case or spaces still authorizes its delivery and retirement', async () => { + const { stateDir, destination } = journey(); + const baseUrl = await artifactServer({ + v1: 'open Demo\n', + v2: 'open Demo\nclose\n', + }); + 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; + + // 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)); + 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(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 step artifacts and keeps the newest version of the payload', async () => { + const { stateDir, destination } = journey(); + const requested: string[] = []; + 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 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(`step-${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: [script('stamped', 500, id)], + results, + }, + ); + + 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 three hundred script versions keeps the bounded candidate and costs one download', async () => { + const { stateDir, destination } = journey(); + const requested: string[] = []; + 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; + + // 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', '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(requested).toEqual(['v-31']); +}); + +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(payload(response).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. + 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(payload(response).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 () => { + 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(payload(response).scriptDeliveryFailure).toEqual( + expect.objectContaining({ + reason: 'script_delivery_failed', + cause: 'script_download_failed', + publicationId: id, + }), + ); + const warnings = payload(response).warnings as string[]; + expect(warnings).toHaveLength(1); + 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 9cd3662efe..53dd4f4e90 100644 --- a/packages/remote/src/daemon-artifacts.ts +++ b/packages/remote/src/daemon-artifacts.ts @@ -477,6 +477,13 @@ 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 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 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); if ( @@ -490,6 +497,165 @@ export async function materializeRemoteArtifacts( return await scripts.settleAfter(download); } +/** + * 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. + * + * Never throws: a request 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> { + if (!info.baseUrl || req.command !== BATCH_COMMAND || !Array.isArray(details?.partialResults)) + return undefined; + try { + 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, ...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; + } +} + +/** + * 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. + */ +async function deliverBatchScript( + endpoint: Required, + req: DaemonWireRequest, + data: Record, + stateDir: string, + 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, + 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/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/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/__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/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..9e46dedc64 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,437 @@ 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' }); + 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 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: gate.baseUrl, + 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 gate.close(); + 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); + +/** + * 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/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..f03e752e69 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", @@ -61,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", @@ -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: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", @@ -213,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" @@ -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: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", @@ -441,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/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..cdddf86270 100644 --- a/website/docs/docs/remote-proxy.md +++ b/website/docs/docs/remote-proxy.md @@ -117,14 +117,19 @@ 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 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. 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 diff --git a/website/docs/docs/replay-e2e.md b/website/docs/docs/replay-e2e.md index 5a96d58ea4..b5b63aef6e 100644 --- a/website/docs/docs/replay-e2e.md +++ b/website/docs/docs/replay-e2e.md @@ -74,8 +74,8 @@ 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. -- Remote `session save-script`, `close --save-script`, `replay --save-script`, and `--save-script` in batch steps are refused. +- 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. 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`.