Skip to content

Remote script recordings: surface scriptDeliveryFailure in SDK/CLI/MCP results and deliver batch step scripts #4564

Open

Description

@thymikee

Purpose

#4511 delivers a remote open --save-script=<path> recording to the caller file. When a script version cannot be written on the daemon, or downloaded and saved on the client, the action keeps its success and the daemon RPC response carries a typed scriptDeliveryFailure with a warning. Two gaps remain outside that PR, by maintainer decision:

  1. The SDK, CLI, and MCP results drop scriptDeliveryFailure, and the SDK close also drops the response warnings. A close whose final script was lost prints a plain Closed: <session>.
  2. A batch delivers no script versions from its steps. feat(remote): write the --save-script recording to the caller during the session and at close #4511 refuses a batch step that would close an armed remote recording (remote_script_batch_close_unsupported) so the final script is not lost silently.

Required behavior

1. Surface the delivery failure

  • The SDK results for open, close (both sessions.close and apps.close), snapshot, and screenshot carry scriptDeliveryFailure when the response has it.
  • The SDK close keeps the response warnings, as open already does.
  • CLI human output prints the warning, and CLI --json and MCP results carry the typed field.

Example SDK result:

const closed = await client.sessions.close();
// {
//   session: 'journey',
//   warnings: ['The remote script could not be saved to /work/journey.ad. ...'],
//   scriptDeliveryFailure: {
//     reason: 'script_delivery_failed',
//     cause: 'script_download_failed',
//     publicationId: '6f1c2a4e-...',
//     message: '...',
//     hint: '...',
//   },
//   identifiers: { session: 'journey' },
// }

Where the fields are dropped today:

  • sessions.close:
    close: async (options = {}) => {
    const session = resolveRequestSession(options);
    try {
    const data = await executeCommand<Record<string, unknown>>('close', options);
    return {
    session,
    shutdown: normalizeTargetShutdownResult(data.shutdown),
    provider: asOptionalRecord(data.provider),
    savedScript: readOptionalString(data, 'savedScript'),
    identifiers: { session },
    };
  • apps.open:
    open: async (options: AppOpenOptions) => {
    const session = resolveRequestSession(options);
    const data = await executeCommand<Record<string, unknown>>('open', options);
    await recordOpenedMetroSession(
    { ...mergeClientOptions(config, options), session },
    {
    explicitRuntime: options.runtime !== undefined,
    runtime: mergeClientOptions(config, options).runtime,
    sessionReused: data.sessionReused === true,
    },
    );
    const device = normalizeOpenDevice(data);
    const appBundleId = readOptionalString(data, 'appBundleId');
    const appId = appBundleId;
    const warnings = readResponseWarnings(data);
    return {
    session,
    ...(warnings.length > 0 ? { warnings } : {}),
    sessionStateDir: readOptionalString(data, 'sessionStateDir'),
    runnerLogPath: readOptionalString(data, 'runnerLogPath'),
    requestLogPath: readOptionalString(data, 'requestLogPath'),
    eventLogPath: readOptionalString(data, 'eventLogPath'),
    appName: readOptionalString(data, 'appName'),
    appBundleId,
    appId,
    selection: normalizeDeviceSelection(data.selection),
    startup: normalizeStartupSample(data.startup),
    runtime: normalizeRuntimeHints(data.runtime),
  • apps.close:
    close: async (options: AppCloseOptions = {}) => {
    const session = resolveRequestSession(options);
    const data = await executeCommand<Record<string, unknown>>('close', options);
    return {
    session,
    closedApp: options.app,
    shutdown: normalizeTargetShutdownResult(data.shutdown),
    savedScript: readOptionalString(data, 'savedScript'),
    identifiers: { session },
    };
    },
  • snapshot normalization:
    function normalizeSnapshotResult(
    data: Record<string, unknown>,
    session: string | undefined,
    ): CaptureSnapshotResult {
    const appBundleId = readOptionalString(data, 'appBundleId');
    return {
    nodes: readSnapshotNodes(data.nodes),
    ...(typeof data.truncated === 'boolean' ? { truncated: data.truncated } : {}),
    appName: readOptionalString(data, 'appName'),
  • screenshot normalization:
  • CLI and MCP serializers that rebuild these results (packages/command-output/src/).

2. Batch delivery

  • Materialize session-script artifacts found in batch step results (results[].data.artifacts) through the session-script owner, with each step's command and scope, in step order.
  • A batch step that closes the recording retires its client record, as a top-level close does, keeping the first error.
  • Then remove the remote_script_batch_close_unsupported refusal.

Where it is skipped today: materializeRemoteArtifacts reads only the top-level artifacts and scriptPublicationId (

export async function materializeRemoteArtifacts(
), and the refusal is in packages/daemon/src/sessions/handlers/session-batch.ts.

Completion conditions

  • A provider scenario closes a remote recording whose final download fails and asserts that the SDK result, CLI --json, and MCP output each carry scriptDeliveryFailure and the warning.
  • A provider scenario runs a remote open with --save-script, then a batch of wait and close, and asserts that the caller file holds the final script with its terminal close and that the client record is retired.
  • ADR 0016 drops the known-limitation note.

Dependencies

Blocked by: #4511.

Activity

  1. apex-sentinel-staging commented on Nov 15, 2026

    @apex-sentinel-staging

    Apex Sentinel · Issue review

    Suggested label: feature

    The issue explicitly presents follow-up enhancements after #​4511: propagate scriptDeliveryFailure and warnings through SDK/CLI/MCP results, and add batch support for remote script recording delivery. It provides concrete required behavior, code locations, and acceptance criteria, and contains no instruction-steering.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions