Backplane.AgentRuntime.Codex.Commands (backplane_agent_runtime v1.10.86)

Copy Markdown

Owner/incarnation-scoped native command inspection.

Pass the same trusted context used to construct a Codex local profile. Command IDs come from exec_command/write_stdin results. Logs are non-consuming; poll/3 alone advances a separate inspection byte cursor, initially zero. Neither operation drains the original write_stdin delivery cursor. A poll that observes confirmed terminal cleanup settles the existing native session and retains its final snapshot, as ordinary terminal collection does.

Reads return at most :max_bytes (default 65,536, maximum 1,048,576), with a byte cursor, total size and truncation flag. Byte ranges can split UTF-8 sequences. Pipe output retains the existing normalized line representation. Finalized logs are snapshots taken during ordinary terminal collection and remain available independently of backend job retention. Registry options :command_history_count, :command_history_bytes, :command_history_ttl bound recent records (defaults 64, 16 MiB, 300,000 ms). Expired or evicted records return :not_found; active cleanup obligations are never evicted. started_at is the admission timestamp; finished_at is the backend's terminal timestamp when available, otherwise nil. Times are Unix milliseconds.

remove/2 and clear_finished/1 remove finalized inspection only. They never terminate a command, remove an active session, or erase cleanup receipts. This API does not add model-callable tools or bypass tool admission.

Summary

Functions

Clear the context owner's finalized records and return the number removed.

Inspect current status and retained public metadata without consuming output.

List current and retained commands for the context's exact owner/incarnation.

Read a bounded non-consuming byte range, starting at :cursor (default zero).

Read and advance the independent inspection byte cursor.

Remove only a finalized inspection record; active commands return resource_conflict.

Functions

clear_finished(context)

Clear the context owner's finalized records and return the number removed.

inspect(context, id)

Inspect current status and retained public metadata without consuming output.

list(context)

List current and retained commands for the context's exact owner/incarnation.

log(context, id, opts \\ [])

Read a bounded non-consuming byte range, starting at :cursor (default zero).

poll(context, id, opts \\ [])

Read and advance the independent inspection byte cursor.

remove(context, id)

Remove only a finalized inspection record; active commands return resource_conflict.