Skip to content

feat(remote): surface a script delivery failure on every caller surface - #4582

Draft
thymikee wants to merge 5 commits into
mainfrom
feat/script-delivery-surfaces
Draft

thymikee wants to merge 5 commits into
mainfrom
feat/script-delivery-surfaces

Conversation

@thymikee

@thymikee thymikee commented Nov 16, 2026 •

Copy link
Copy Markdown
Member

Closes #4564.

An action that records a remote script version keeps its success when that version cannot reach the caller file. The wire already answered scriptDeliveryFailure; nothing above it passed the field on, so a caller read a stale file as current.

readScriptDeliveryFailure in the kernel reads the field from a response, and readScriptDeliveryDisclosure adds the paired warning. Every result that can carry a script version now spreads both: the SDK open, sessions.close, apps.close, snapshot and screenshot results, the CLI human output and --json payload, and the MCP tool text and structured content.

batch now delivers the session script its answer carries, through the same session-script owner a single response uses. The destination still comes only from the record this client's own open --save-script wrote, so a response never chooses a path and a script of another publication writes nothing. That removes remote_script_batch_close_unsupported, which existed only because a batch delivered nothing.

Every script version is the whole recording from the open, so a batch is owed AT MOST ONE download: one linear, bounded scan reads the plan's finished steps and the batch payload itself, and keeps the newest version of the open publication, wherever it was named. Delivery is authorized by the plan the client submitted, never by the answer: the completed prefix comes from the plan, and on a failed batch it is cross-checked against the failing step and executed count the error reports. Entries outside that prefix, or naming another command, are reported exactly as the daemon answered them, with no download and no retirement, and a retirement follows only a close the plan itself ran and finished — with or without an artifact, so a recording the daemon could not finish is still forgotten. Each candidate is validated by the publisher's own guards before anything is looked up or requested. A batch that fails after a step closed still delivers what the finished steps recorded, and keeps its own error. The batch payload carries scriptDeliveryFailure when this client's own delivery, or a step that finished, reports one for the open publication and no version saved after that report supersedes it, and only the warning written beside that failure rides up: the batch's own payload is the channel the CLI Warning: lines, --json and the MCP tool text read. Step names resolve through normalizeBatchCommandName, and one exported isPublishableScriptVersion serves both the publisher and the batch scan, while sessionScriptDelivery takes an explicit closedPublicationId rather than a faked command: 'close'.

Tests cover each surface's disclosure and batch delivery end to end. ADR 0016 drops its known-limitation note.

🤖 Generated with Claude Code

@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Size Report

Metric Base Current Diff
Installed (including dependencies) 6.32 MB 6.33 MB +5.7 kB
Package (unpacked) 6.32 MB 6.33 MB +5.7 kB
Package (download) 1.92 MB 1.92 MB +1.3 kB

Startup median (7 runs, lower is better):

Scenario Base Current Diff
CLI --version 24.7 ms 20.9 ms -3.7 ms
CLI --help 45.0 ms 44.4 ms -0.7 ms

@thymikee
thymikee force-pushed the feat/script-delivery-surfaces branch from d03f541 to 4556e33 Compare November 16, 2026 11:24
@thymikee

thymikee commented Nov 16, 2026 •

Copy link
Copy Markdown
Member Author

Thanks for this. I reviewed 4556e33 and found two things to fix before merge. CI is green (21 checks, none failing), and there are no conflicts.

A script delivery failure that the daemon reports on a batch step never reaches the batch result. disclosedDelivery lifts the typed scriptDeliveryFailure only from this client's own payload, and from the finished steps it lifts only warnings (remote-batch-script-delivery.ts#L283). Example: batch [wait, close], where remoteCloseScript cannot write the final script. The client delivers the older wait version and sets savedScript. It then lifts only the warning text, and the session is already closed, so nothing else adds the field. The caller file lacks the terminal close, and the CLI --json, SDK and MCP batch results show savedScript with no top-level scriptDeliveryFailure. An agent that reads the typed field will treat the stale file as current, and remote-proxy.md:129 and ADR 0016 promise the field reaches the batch result. The rule the code must satisfy: the batch payload carries scriptDeliveryFailure whenever this client's delivery, or any finished step, reports one for the open publication and no newer delivered version supersedes it. This client's own failure wins. Otherwise read each step through readScriptDeliveryFailure in plan order, keep the last one for the publication, and lift only its paired warning. Please add a provider or unit case where a step answers a daemon-side scriptDeliveryFailure.

normalizeStepCommand is a verbatim copy of normalizeBatchCommandName (remote-batch-script-delivery.ts#L323, original in batch-policy.ts#L74). The batch-policy doc says every caller that decides something about a step must resolve the name through that function. Here the copy decides plan authorization and the close and retire decision. If the daemon's normalization changes, for example with alias resolution, a finished close stops matching, the final script is not delivered and the record is not retired. Please import normalizeBatchCommandName from @agent-device/command-registry/batch-policy and add the workspace dependency to packages/remote/package.json. Remote is rank 4 and command-registry rank 1, so the layering allows it.

Not blocking, and you can take or leave these: isUsableVersion (L265) restates the guard in publishScriptVersion, so one exported isPublishableScriptVersion in session-script-destination.ts could serve both; no test covers the open, apps.close, snapshot and screenshot disclosure spreads or their serializers (index.ts#L614), so deleting any one leaves CI green, and one table-driven normalizer test would pin them; disclosedDelivery lifts every finished step's warnings onto the batch, so unrelated capture warnings and warnings from a superseded write also appear, and lifting only the warning paired with the typed failure fixes that (L294); deliverBatchScript fakes command: 'close' so the retirement rule applies (L173), and an explicit closedPublicationId input on sessionScriptDelivery would be clearer; the bare catch { return undefined; } in materializeRemoteBatchPartialArtifacts emits no diagnostic (daemon-artifacts.ts#L531), where the owner emits a session_script_delivery_failed warn; the batch path returns top-level artifacts exactly as the daemon answered, while the single path drops failed script artifacts and sets localPath (L30); readScriptDeliveryFailure is a kernel and wire-surface export with one reader, so the doc's claim that every surface uses it does not yet hold (contracts.ts#L230), and the fix above would make remote a second reader; the snapshot spread sets warnings again from the same data.warnings already read two lines above, so adding only scriptDeliveryFailure, as screenshot does, is enough.

Could the batch side be much smaller? Keep the five SDK spreads and the serializer helper. Give sessionScriptDelivery an explicit retire input and export one publishable-version predicate. Then replace the 333-line module with about 60 lines in daemon-artifacts.ts. Read the plan through normalizeBatchCommandName, take the finished prefix (with the step === executed + 1 check on the error path), collect script artifacts from the top level and finished steps, and pick the highest revision. Run the single-response owner on that artifact, with retire set when a finished plan step is close. Lift disclosure with readScriptDeliveryFailure: this client's failure, else the last finished step's failure for that publication, plus only its paired warning. That would remove DeliveryContext, isUsableVersion, normalizeStepCommand and the withBatchDisclosure/disclosedDelivery pair, and fix both findings above. It needs a small API change in session-script-destination.ts and a workspace dependency from remote on command-registry. Do you see a reason to keep the larger module?

The CodeQL thread on the polynomial regex in session-script-destination.ts no longer applies: the flagged hunk is gone at 4556e33, and withoutTrailingSlashes now uses a loop, so it can be resolved (thread).

The first finding comes from reading the path from remoteCloseScript write failure through step data to disclosedDelivery, and no run has reproduced it. Only the open, close, snapshot and screenshot CLI --json formatters were traced for scriptDeliveryFailure, and the MCP error result of a failed batch was not traced. A device run is not needed for this change. After the two fixes, the merge needs a green CI run on the new head.

thymikee and others added 5 commits November 16, 2026 14:19
An action that records a remote script version keeps its success when that
version cannot reach the caller file, so the caller needs one field that says
the file is stale. `readScriptDeliveryFailure` reads it from a response, and
every result that can carry a script version now spreads it beside the
warning: the SDK open, close, snapshot and screenshot results, the CLI human
output and `--json`, and the MCP tool text and structured content.

A batch delivers the script versions its own steps record. Each step is
published through the session-script owner under its own command name, in step
order, so a step that closes the recording retires the caller record the way a
standalone close does, and a step that only records a version leaves the record
open for the next one. The destination still comes only from the record this
client's own `open --save-script` wrote, so a response never chooses a path, and
a step script of another publication still writes nothing. That retires the
`remote_script_batch_close_unsupported` refusal, which existed only because a
batch delivered nothing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…tted

A batch answer carries one entry per step, and the client delivered whatever
the answer named. That made the response the authority over a caller-owned
record: an entry planted in place of a `wait` step could name this client's
publication and retire it, and its artifact list was unbounded, so one answer
asking for a thousand duplicate versions spent a thousand downloads. Delivery
now runs on the plan THIS client submitted: an entry must be the plan's own
command at the plan's own position and a step that finished, and anything else
is reported exactly as the daemon answered it, with no download, no destination
and no retirement. Of the versions one payload names, only the newest is taken,
and a duplicate or a version no newer than one already accepted is dropped
before any request, which caps one answer at one download per submitted step.

A `close` step that names this client's publication now reaches the owner even
when it carries no artifact, so a recording the daemon could not finish is
still forgotten instead of staying active beside a file that never gained its
final version.

A failed batch reports the steps it finished in the error's `partialResults`,
which never reached the code that materializes a successful response. Those
steps are delivered before the error is rehydrated, under the same plan bound,
so `[wait, close, snapshot]` that fails on `snapshot` still writes the final
script and still ends the recording; the batch error itself stands.

A batch's own output reads the batch payload, so a step's warning and typed
`scriptDeliveryFailure` are lifted onto it: the CLI `Warning:` line, the MCP
tool text and `--json` and structured content now say the caller file is stale,
instead of printing only "OK Closed: journey".

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A batch answer is untrusted input, and the per-step delivery path read it
step by step. A failing step's report could carry successful entries for
steps that never ran, so a forged partial result retired a close the caller
never ran. A malformed publication ID threw while it was interpolated, which
turned a successful batch into a client failure. Filtering revisions
re-scanned every earlier version, so a large answer blocked the caller. And a
successful batch whose steps carried no script stopped before its own payload,
leaving the caller's file stale behind a newer version the daemon had stamped.

Deliver at most ONE version per batch. Every version is the whole recording,
so only the newest of the open publication matters: one linear, bounded scan
reads the plan's finished steps and the batch payload and keeps that one, and
one delivery goes through the session-script owner.

Derive the completed prefix from the submitted plan and cross-check it against
the step and executed count the error names, so entries at or after the failure
authorize no download and no retirement. Retire only when that prefix contains
the close step, with or without an artifact. Validate each candidate with the
publisher's own guards, so no response value reaches a record lookup, a path,
or a download request.

Reports #4564 review findings 1 to 5.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ints

ADR 0016 said every recorded action costs one download without naming the
batch case, and the ledger rationale still described the per-step path this
module no longer takes.

Reports #4564 review finding 5.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ler path

The batch script owner is replaced by one delivery path: read the plan the caller
submitted, take its finished prefix, pick the newest publishable version the answer
names, and run the single-response owner on that one artifact. `sessionScriptDelivery`
takes an explicit `closedPublicationId` instead of a faked `command: 'close'`, and
`isPublishableScriptVersion` is one predicate used by the publisher and the batch scan.
Step names resolve through `normalizeBatchCommandName`, so the plan check and the
daemon's own step naming cannot drift apart.

A finished step's `scriptDeliveryFailure` now reaches the batch payload: this client's
own failure wins, otherwise the last finished step's failure for that publication,
unless the saved version came from a later step. Only the warning written beside that
failure rides up. A step entry outside the finished prefix, or one whose report does not
describe the submitted plan, authorizes nothing. The failed-batch catch emits the
`session_script_delivery_failed` diagnostic, and the batch path rewrites the answer's own
artifact list the way a single response does.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@thymikee
thymikee force-pushed the feat/script-delivery-surfaces branch from a385901 to f09f36f Compare November 16, 2026 13:22
@thymikee

Copy link
Copy Markdown
Member Author

Yes — it could, and it now is. f09f36fcb7 adopts that design; I see no reason to keep the larger module. It is rebased on current main, so the tree is conflict-free again.

Line counts

Before After
Batch owner remote-batch-script-delivery.ts, 333 lines (218 code) inline in daemon-artifacts.ts, 159 lines (120 code)
Batch answer readers (plan, finished prefix, disclosure) inside that module remote-batch-answer.ts, 127 lines (86 code)
Production delta of this round −81 lines (307 added, 388 deleted)

The batch side is 286 lines in two places instead of 333 in one. The second file exists so those readers stay off the client's eager import path: daemon-artifacts.ts sits in packages/daemon-client/src/index.ts's closure, and the eager-closure gate fails a static edge from it to command-registry/batch-policy, so the readers load on demand with the script owner. Production code for this round is net smaller; tests are larger. remote-batch-script-delivery.ts is deleted, and DeliveryContext, isUsableVersion, normalizeStepCommand and the withBatchDisclosure/disclosedDelivery pair are gone. sessionScriptDelivery takes closedPublicationId instead of a faked command: 'close', isPublishableScriptVersion is one exported predicate used by publishScriptVersion and the batch scan, and the plan resolves through normalizeBatchCommandName (workspace dependency and tsconfig reference added).

Finding 1 — a step's daemon-side failure now reaches the batch payload

The disclosure takes this client's own failure first, else the last finished step's failure whose publicationId matches, and lifts only the warning written beside that one failure. A version saved from a later step supersedes it. Covered by a finished step that reports a write failure is disclosed when an older version is delivered (your [wait, close] case: savedScript and the typed failure on one payload) and a close step that names the publication retires the record with no artifact to deliver (no version to deliver), plus a step failure superseded by a newer delivered version is not disclosed and a batch step that cannot save its version discloses it on the batch payload. Dropping the step branch turns the first two red, and both are red at 4556e33.

Finding 2 — one normalizer

Imported from @agent-device/command-registry/batch-policy; a batch step named with other case or spaces still authorizes its delivery and retirement pins that the plan check and the daemon's step naming agree.

Cross-check items

  • The finished-prefix reader requires step === executed + 1, step <= plan.length, and that the normalized failing command is the plan's entry at that position. a failed remote batch whose step report disagrees with its entries delivers nothing and a failed remote batch whose report does not describe the submitted plan delivers nothing cover these, and the RPC fixture no longer submits step: 3 against a two-step plan. Dropping the command check turns the second one red.
  • The cap tests now pin which candidate survives: a batch reads at most its bound of step artifacts and keeps the newest version of the payload, a batch that names three hundred script versions keeps the bounded candidate and costs one download, a batch that names one hundred script versions in one step stops at the per-payload bound. Raising either bound to unbounded turns all three red, and each says which artifact then leaks in.
  • The failed-batch catch emits the session_script_delivery_failed warn diagnostic: a failed batch whose step entries cannot be read reports the delivery failure.
  • The batch path rewrites the answer's own artifacts the way the single path does: a script entry that did not arrive is dropped, the delivered one carries localPath.

Non-blocking notes, taken

  • One table-driven test per owner pins the spreads and the serializers: packages/client/src/__tests__/index-script-delivery-disclosure.test.ts (sessions.close, apps.close, apps.open, capture.snapshot, capture.screenshot, each also with a malformed failure object) and packages/command-output/src/output/result-serialization-script-delivery.test.ts (open, session close, snapshot); screenshot --json is pinned in src/cli/commands/__tests__/screenshot.test.ts. Removing one spread, or the serializer helper's typed field, turns one of them red.
  • The snapshot spread sets only scriptDeliveryFailure, since the annotations reader two lines above already read warnings from the same payload.
  • readScriptDeliveryFailure now has remote as a second reader, so the doc claim holds.

remote-proxy.md and ADR 0016 state the disclosure rule now (own failure, else the last finished step's unless superseded; only the paired warning) instead of the earlier wording. The CodeQL thread was already resolved; the flagged hunk is gone.

This branch has not been deployed

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

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

2 participants