Skip to content
Merged
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
3 changes: 2 additions & 1 deletion docs/adr/0016-active-session-script-publication.md
Original file line number Diff line number Diff line change
Expand Up @@ -208,7 +208,8 @@ It adds no state name, command, or flag:
- 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.
Known limitation (#4595): a batch delivers no script versions from its steps, so closing an armed remote recording inside a batch stays refused.
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.
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);

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P3: The leveled snapshot branch returns the raw payload, so a malformed scriptDeliveryFailure reaches the caller unchecked. Pass that field through readScriptDeliveryFailure on the leveled path too, as presentedSurface already is.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At packages/client/src/index.ts, line 609:

<comment>The leveled snapshot branch returns the raw payload, so a malformed `scriptDeliveryFailure` reaches the caller unchecked. Pass that field through `readScriptDeliveryFailure` on the leveled path too, as `presentedSurface` already is.</comment>

<file context>
@@ -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 } : {}),
</file context>

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 }),

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P3: Add 'scriptDeliveryFailure' to the Pick<CaptureSnapshotResult, ...> union in optionalSnapshotResponseFields. The union is the documented list of fields this helper can return, and the new field is missing from it.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At packages/client/src/index.ts, line 621:

<comment>Add `'scriptDeliveryFailure'` to the `Pick<CaptureSnapshotResult, ...>` union in `optionalSnapshotResponseFields`. The union is the documented list of fields this helper can return, and the new field is missing from it.</comment>

<file context>
@@ -614,6 +616,9 @@ function optionalSnapshotResponseFields(
     ...(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 }
</file context>

...(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,72 @@
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;
/** Called with the disclosure fields, and with PLAIN input that names none of them. */
serialize: (input?: Record<string, unknown>) => Record<string, unknown>;
}> = [
{
label: 'open',
serialize: (input) => serializeOpenResult({ session: 'qa', ...input } as never),
},
{
label: 'session close',
serialize: (input) =>
serializeCloseResult({ session: 'qa', savedScript: '/tmp/journey.ad', ...input } as never),
},
{
label: 'snapshot',
serialize: (input) => serializeSnapshotResult({ nodes: [], ...input } as never),
},
];

for (const output of outputs) {
test(`the ${output.label} machine output carries a failed script delivery`, () => {
const data = output.serialize(DISCLOSURE);

assert.deepEqual(data.scriptDeliveryFailure, FAILURE);
assert.deepEqual(data.warnings, [WARNING]);
});

test(`the ${output.label} machine output omits a disclosure it was not given`, () => {
// PLAIN input: nothing here names a script, so a serializer that invents either field fails.
const data = output.serialize();

assert.equal('scriptDeliveryFailure' in data, false);
assert.equal('warnings' in data, false);
});

test(`the ${output.label} machine output keeps the failure beside an empty warning list`, () => {
const empty = output.serialize({ ...DISCLOSURE, warnings: [] });

assert.deepEqual(empty.scriptDeliveryFailure, FAILURE);
assert.equal('warnings' in empty, false);
});
}
24 changes: 23 additions & 1 deletion packages/command-output/src/output/result-serialization.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Expand Down Expand Up @@ -92,6 +93,9 @@ export function serializeSnapshotResult(result: CaptureSnapshotResult): Record<s
}),
...(result.unchanged ? { unchanged: result.unchanged } : {}),
...(result.snapshotDiagnostics ? { snapshotDiagnostics: result.snapshotDiagnostics } : {}),
// ADR 0016 (#4564): a remote recording's script this capture recorded did not reach the caller
// file. The capture still succeeded, so this is the only channel that says the file is stale.
...serializeScriptDeliveryDisclosure(result),
...(result.fallbackScreenshotPath
? { fallbackScreenshotPath: result.fallbackScreenshotPath }
: {}),
Expand Down Expand Up @@ -141,7 +145,7 @@ export function serializeOpenResult(result: AppOpenResult): Record<string, unkno
return withSuccessText(
{
session: result.session,
...(result.warnings?.length ? { warnings: result.warnings } : {}),
...serializeScriptDeliveryDisclosure(result),
...serializeOpenSessionPaths(result),
...(result.appName ? { appName: result.appName } : {}),
...(result.appBundleId ? { appBundleId: result.appBundleId } : {}),
Expand Down Expand Up @@ -172,13 +176,31 @@ function serializeOpenSessionPaths(result: AppOpenResult): Record<string, string
};
}

/**
* ADR 0016 (#4564): a remote recording's script version that did not reach the caller file, beside
* the warning that says so. The action kept its success, so machine output has to name the stale
* file rather than leave a caller assuming the file was written.
*/
function serializeScriptDeliveryDisclosure(result: {
warnings?: string[];
scriptDeliveryFailure?: ScriptDeliveryFailure;
}): Record<string, unknown> {
return {
...(result.warnings?.length ? { warnings: result.warnings } : {}),
...(result.scriptDeliveryFailure
? { scriptDeliveryFailure: result.scriptDeliveryFailure }
: {}),
};
}

export function serializeCloseResult(
result: SessionCloseResult | AppCloseResult,
): Record<string, unknown> {
return {
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',
Expand Down
Loading
Loading