Record what happened to each action

An assistant says it saved a document. The application displayed no error, but the file still contains the previous draft. The failure becomes difficult to investigate if the task record contains only “save complete.” A useful record has to distinguish the requested change from the action sent to the application and the result actually observed.

The Boris integration specification proposed an action ledger for this purpose. Boris was described in the source record as an existing native agent interface; the ledger and related extensions are specified work, not independently demonstrated runtime behavior. The design gives each action several states so that recovery can ask a more precise question than whether the assistant remembers finishing.

The specified sequence includes planned, approved, dispatched, observed, and reconciled. Those names matter because they correspond to different evidence. A plan records intent. Approval records permission. Dispatch records that an executor received the request. Observation records what the executor or application returned. Reconciliation compares that record with the current resource state.

Follow a save all the way through

Consider an illustrative save operation for a project note. The user has authorized updating a particular working copy. The planned action identifies that file, its current content hash, and the intended change. A content hash is an identifier computed from the file’s bytes; a different hash establishes that the bytes differ, though it does not explain the difference.

The authorization record binds the intended operation to the permitted file. Dispatch then records which editor or file tool received the operation and gives the attempt a stable identifier. If the editor returns success, preserve that response without immediately assuming that the final acceptance criterion has passed.

Reopen the saved file. Check its location and content against the requested edit, then record the resulting hash. If the file contains the intended change, reconciliation can connect the observed result to the planned effect, while an older version leaves the action unresolved and provides evidence of the gap between a successful dispatch response and the saved content the user requested.

The distinction becomes particularly useful when the process stops after the save. On restart, the assistant can inspect the file and establish whether the intended effect already exists. It does not need to repeat the save merely because the last conversation turn never announced completion.

Keep attempts attached to one intended effect

A single action may require several attempts. Give the intended effect its own identity and retain separate attempt identifiers underneath it. Otherwise, retries can appear to be unrelated work, and the final report may count three dispatches as three completed tasks.

Each attempt should preserve its inputs, start and end observations, and any returned error. Keep the earlier attempt visible after a later one succeeds. An intermittent problem may become reproducible only when someone compares the failed attempt with the successful one, using the retained inputs to isolate a changed target version or environment condition rather than assuming that the later success explains the earlier failure.

Do not force every uncertainty into a binary success field. The executor may report partial completion or an ambiguous timeout. Those results change the permitted next action. If half a document was updated, replaying the entire mutation may overwrite a user’s intervening edits; if the target state cannot be inspected, the task may need a decision before it proceeds.

Make the record useful to a reviewer

The ledger should let a reader answer a practical question without reopening an entire conversation. Which file changed? What authorized the change? Which attempt produced it? Which observation established that the requested effect exists? Link the relevant receipt directly rather than asking the reviewer to infer the answer from surrounding prose.

This does not require exposing every low-level event in the main interface. A concise completion view can show the criterion, outcome, and verified artifact revision while retaining the underlying action history for investigation, provided the view is generated from the same authoritative state and cannot silently describe an unresolved action as complete.

Test the record with deliberately misleading situations. Return a successful tool response without saving the file. Save to the wrong directory. Change the file externally before reconciliation. Each case should leave different evidence and prevent an unsupported completion claim. For the illustrative project note, the task passes only when the reopened authorized file contains the requested revision and the recorded receipt identifies that same artifact.

Source notes

Based on the September 2026 Boris integration specification. The project-note save is illustrative. The specification’s action-ledger extensions have not been independently validated as a completed runtime.