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
6 changes: 4 additions & 2 deletions docs/adr/0016-active-session-script-publication.md
Original file line number Diff line number Diff line change
Expand Up @@ -204,12 +204,14 @@ 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 whose steps record or close an armed remote recording is not refused. The daemon collects the versions and the close that the batch's steps wrote, and delivers them on the batch response as one `scriptDeliveryReceipt` (#4595).
- 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).
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.
A batch delivers through one receipt the daemon's request owner answers on the batch reply, successful or failed (#4595). The daemon collects each executed step's script effects as the batch runner reports them, because a step's own reply travels inside a result entry a client must not read. The receipt names the newest full-script version of the recording, the plan position of a step that closed it, and the typed failures; it is answered only for a request whose nested steps fed it, so every single-command reply keeps the shape it had before. A client validates the receipt against its own record and its submitted plan, downloads at most its one version, and treats a receipt it cannot fully account for as authorizing nothing.
This receipt requires RPC protocol 3: protocol-2 clients ignore it, so admitting a batch close for them could leave the caller's final script undelivered. The health compatibility gate rejects those skewed peers before dispatch (ADR 0006).
Rejected: deriving delivery effects by interpreting the batch's step entries, partial results and failure position, because six review rounds kept finding answers that made a client deliver the wrong version, retire a recording that never closed, or drop a failure (#4582).
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
7 changes: 3 additions & 4 deletions packages/command-registry/src/batch-policy.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,9 @@
import { deriveStructuredBatchCommandNames } from './derive.ts';
import { commandDescriptors } from './registry.ts';
import { AppError } from '@agent-device/kernel/errors';
import { normalizeBatchCommandName } from '@agent-device/contracts/input-validation';

export { normalizeBatchCommandName };

/**
* The exact set of command names exposed through `batch`, as a narrow union.
Expand Down Expand Up @@ -71,10 +74,6 @@ function isStructuredBatchCommandName(command: string): command is StructuredBat
return structuredBatchCommandNames.has(command);
}

export function normalizeBatchCommandName(command: unknown): string {
return typeof command === 'string' ? command.trim().toLowerCase() : '';
}

/**
* The command a raw step value will RUN as, or undefined.
*
Expand Down
2 changes: 1 addition & 1 deletion packages/contracts/src/daemon-http.ts
Original file line number Diff line number Diff line change
Expand Up @@ -123,7 +123,7 @@ export function buildDaemonHttpLeaseHeaders(leaseId: string | undefined): Record
// Enforced, not just documented: `test/wire-compat/` digests the declarations
// that cross this boundary and fails when one changes shape without a bump or
// an acknowledged-compatible entry (#1432).
export const DAEMON_RPC_PROTOCOL_VERSION = 2;
export const DAEMON_RPC_PROTOCOL_VERSION = 3;

/**
* The largest serialized daemon request, in UTF-8 bytes, that any transport reads: the socket
Expand Down
1 change: 1 addition & 0 deletions packages/contracts/src/facades/command.ts
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@ export type { DaemonWireRequest, DaemonWireRequestMeta } from '../daemon-wire-re
export type { DispatchedCommand } from '../dispatched-command.ts';
export {
ANDROID_SHELL_TEXT_UNSUPPORTED_REASON,
normalizeBatchCommandName,
readOptionalInteger,
readOptionalNumber,
} from '../input-validation.ts';
Expand Down
5 changes: 5 additions & 0 deletions packages/contracts/src/input-validation.ts
Original file line number Diff line number Diff line change
Expand Up @@ -46,3 +46,8 @@ export function readOptionalNumber(
* because every producer and consumer of the reason already evaluates this module.
*/
export const ANDROID_SHELL_TEXT_UNSUPPORTED_REASON = 'android_shell_text_unsupported' as const;

/** Resolves a batch step command with the same whitespace and case rules on both peers. */
export function normalizeBatchCommandName(command: unknown): string {
return typeof command === 'string' ? command.trim().toLowerCase() : '';
}
Original file line number Diff line number Diff line change
Expand Up @@ -102,3 +102,23 @@ test('a daemon health payload without an upstream link or host arch parses as be
},
);
});

test.each(['daemon', 'upstream'] as const)(
'released protocol-2 %s cannot silently omit batch receipt delivery',
async (link) => {
const payload =
link === 'upstream' ? proxyHealth(2) : { ...DAEMON_LINK, rpcProtocolVersion: 2 };
await withHealthServer(payload, async (baseUrl) => {
await assert.rejects(
readRemoteDaemonHealth({ baseUrl, token: 't', pid: 0 }),
(error: unknown) => {
const failure = error as { code?: string; details?: Record<string, unknown> };
assert.equal(failure.code, 'COMMAND_FAILED');
assert.equal(failure.details?.remoteRpcProtocolVersion, 2);
assert.equal(failure.details?.supportedRpcProtocolVersion, DAEMON_RPC_PROTOCOL_VERSION);
return true;
},
);
});
},
);
38 changes: 36 additions & 2 deletions packages/daemon-client/src/daemon-client-rpc.ts
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,11 @@ 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 {
downloadRemoteArtifact,
materializeRemoteArtifacts,
settleScriptDeliveryReceiptOfFailure,
} 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';
Expand Down Expand Up @@ -102,7 +106,37 @@ async function rejectDaemonHttpRpcError(
stateDir,
requestId,
});
reject(appErrorFromDaemonError(localized, requestId));
reject(
appErrorFromDaemonError(
await settleFailedDeliveryReceipt(info, req, stateDir, localized),
requestId,
),
);
}

/**
* Settles the batch delivery receipt (#4595) a failed remote answer names: a batch that stopped
* mid-plan still delivers what its completed steps wrote, and the disclosure rides the error the
* caller receives. Never throws, so a receipt that cannot settle still leaves the original failure.
*/
async function settleFailedDeliveryReceipt(
info: DaemonInfo,
req: DaemonWireRequest,
stateDir: string,
error: DaemonError,
): Promise<DaemonError> {
if (!info.baseUrl) return error;
try {
return await settleScriptDeliveryReceiptOfFailure(
{ baseUrl: info.baseUrl, token: info.token },
req,
error,
stateDir,
downloadRemoteArtifact,
);
} catch {
return error;
}
}

function toDaemonHttpRpcError(error: {
Expand Down
Loading
Loading