small gleam coding and (not yet) persistent agent daemon with a detachable cli forked from okami.mom/albedo
albedo robot-docs operations.md
3.0 kB · 58 lines
Markdown
at main

Durable operation admission #

Session creation and input admission use identified operations and durable receipts. Acceptance records a decision. It does not mean that a turn completed or that external tool effects happened exactly once. The request and response contract is in openapi.yaml and session lifecycle and recovery.

Ownership and atomicity #

operations.gleam owns receipt lookup, duplicate checks, pending input, and operation outcomes. check_in returns an existing matching receipt before checking a new ID. A different fingerprint, kind, or target returns operation_conflict. admit_pending_then submits a transaction to the store writer. admit_pending_in records the receipt and stores the input in the session's inbox in that transaction. The inbox row carries the whole submission and shares the receipt's id. A pending input is a waiting inbox row with a pending receipt.

conversation.gleam commits identified session creation and its receipt together. create_child_identified also commits family membership and the initial task in the same transaction. The task is one inbox row: a letter from the parent that carries the child's first input under its receipt's id. The transaction fails if any part fails.

Recovery #

Clients retain the operation ID and request while resolving an uncertain result. The HTTP contract describes lookup, duplicate behavior, retention, and cancellation in the input recovery contract. operations.gleam stores delivery state and provides pending input recovery and cancellation. A client stopping its wait does not itself undo an accepted operation. Session state and transcript ownership are described in sessions.

Human shell identity #

Human shell commands have their own durable identity. shell_commands.gleam admits commands, records output and completion, and tracks transcript attachment and delivery. A finished command's receipt waits in the inbox under the command's id. Its interrupt_orphans_in marks orphaned running commands interrupted during recovery. Attachment to history alone does not establish provider delivery. mark_delivered_in records that state separately.

The shell-command response includes model_text_bytes, the UTF-8 byte count of its model-facing receipt before timestamping. The shell owner computes it from the same text it delivers. Clients use that count instead of rebuilding the receipt or guessing the session ID's size. See also sessions.