Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 6 additions & 3 deletions docs/adr/0016-active-session-script-publication.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
111 changes: 111 additions & 0 deletions packages/client/src/__tests__/index-script-delivery-disclosure.test.ts
Original file line number Diff line number Diff line change
@@ -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<string, unknown>;
read: (client: ReturnType<typeof createAgentDeviceClient>) => Promise<unknown>;
}>;

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<string, unknown>) {
const setup = createClientTransport(async (req): Promise<DaemonResponse> => {
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<string, unknown>;

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<string, unknown>;

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<string, unknown>;

assert.equal('scriptDeliveryFailure' in result, false, surface.label);
});
}
29 changes: 28 additions & 1 deletion packages/client/src/client-normalizers.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Expand Down Expand Up @@ -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<string, unknown>): {
warnings?: string[];
scriptDeliveryFailure?: ScriptDeliveryFailure;
} {
const warnings = readResponseWarnings(data);
const scriptDeliveryFailure = readScriptDeliveryFailure(data);
return {
...(warnings.length > 0 ? { warnings } : {}),
...(scriptDeliveryFailure === undefined ? {} : { scriptDeliveryFailure }),
};
}
11 changes: 8 additions & 3 deletions packages/client/src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,7 @@ import {
normalizeTargetShutdownResult,
readOptionalString,
readRequiredString,
readScriptDeliveryDisclosure,
readSnapshotNodes,
resolveSessionName,
} from './client-normalizers.ts';
Expand All @@ -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';
Expand Down Expand Up @@ -273,6 +273,7 @@ export function createAgentDeviceClient(
shutdown: normalizeTargetShutdownResult(data.shutdown),
provider: asOptionalRecord(data.provider),
savedScript: readOptionalString(data, 'savedScript'),
...readScriptDeliveryDisclosure(data),
identifiers: { session },
};
} finally {
Expand Down Expand Up @@ -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'),
Expand Down Expand Up @@ -381,6 +381,7 @@ export function createAgentDeviceClient(
closedApp: options.app,
shutdown: normalizeTargetShutdownResult(data.shutdown),
savedScript: readOptionalString(data, 'savedScript'),
...readScriptDeliveryDisclosure(data),
identifiers: { session },
};
},
Expand Down Expand Up @@ -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 } : {}),
Expand All @@ -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 }
: {}),
Expand Down
5 changes: 5 additions & 0 deletions packages/client/src/screenshot-result.ts
Original file line number Diff line number Diff line change
@@ -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';
Expand All @@ -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,
Expand All @@ -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 },
};
}
Expand Down
Original file line number Diff line number Diff line change
@@ -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<string, unknown> }> = [
{
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);
});
}
Loading
Loading