AxiOwl Delivery Receipts Explained

AxiOwl Delivery Receipts Explained

A delivery receipt in AxiOwl is not a vague success message. It is a boundary marker. It tells the operator which part of the AxiOwl send pipeline has accepted the work, which provider route was selected, and where to look for evidence. Just as importantly, it avoids promising facts that AxiOwl has not proven yet.

That distinction matters because AxiOwl sends messages across different agent surfaces: Codex sessions, VS Code chat sessions, Copilot-backed VS Code, Cursor agent windows, Antigravity, and several CLI-oriented provider targets. Those surfaces do not all expose the same APIs or confirmation signals. AxiOwl's receipt language is designed to keep those differences visible instead of hiding them behind a generic "sent successfully" line.

What a Receipt Actually Means

The current CLI receipt text is intentionally careful. When a message enters the AxiOwl pipeline and is accepted for handoff, the CLI prints an "AxiOwl handoff receipt" with a message ID, delivery state, provider, and delivery log path. When the state is accepted_by_axiowl, the receipt explicitly says that provider delivery, provider wake-up, and provider reply are not implied.

That is the core rule: a receipt says only what AxiOwl can prove at that point.

AxiOwl separates several facts that are often blurred together:

Those are not the same event. A delivery receipt may prove one or more of them, but it does not automatically prove all of them.

The Send Pipeline Behind the Receipt

The message pipeline implemented in message_pipeline.cpp creates a fresh message ID, records that the request entered AxiOwl, validates the target and body, resolves the sender, resolves the target through the registry, builds the final visible body, and hands the provider request to the delivery worker.

The design note for the pipeline summarizes the intended path this way:

CLI
-> local service
-> sender resolution
-> target resolution
-> final visible body builder
-> provider edge
-> evidence log
-> receipt

The implementation follows that shape. Before provider dispatch, the pipeline can already reject the send for concrete reasons: missing target, empty body, unresolved sender identity, target not found after targeted discovery, or a known target that is not sendable. These are not quiet failures. They become explicit receipt errors and delivery log entries.

When the route is valid, AxiOwl records message_accepted_by_axiowl, sets the receipt state to accepted_by_axiowl, and starts the delivery worker handoff. That receipt is useful, but bounded: it means the local AxiOwl pipeline accepted the request and started the handoff path.

Provider Acceptance Is a Stronger Claim

Provider acceptance is a separate signal. The delivery worker writes a request file, dispatches through deliver_to_provider, and parses a structured delivery_worker_result. Provider routing is registry-driven through provider edges such as codex, codex_cli, vscode_native, vscode_copilot_backed, antigravity, cursor, and related CLI targets.

When a provider edge reports a verified acceptance result, the CLI can show a provider delivery state. The delivery worker also records delivery stages such as provider_write_started, provider_write_succeeded, provider_handoff_started_unverified, or provider_write_failed.

This is why AxiOwl receipts avoid a single universal success phrase. A Cursor bridge command file, a VS Code native bridge action, a Codex provider edge, and an Antigravity path each have different proof mechanics. AxiOwl's job is to report the actual state it observed, not to flatten every provider into the same message.

A Reply Is Not the Same as a Send Receipt

AxiOwl's provider documentation repeatedly makes this point: a send receipt alone is not enough to mark a provider as fully proven. For Codex agents, the support note says the passing proof is a Codex reply through AxiOwl MCP. For VS Code native sessions, the stronger proof can be session-file evidence or an MCP reply. For Cursor agents, response-backed Cursor tests are the meaningful bar.

The provider support matrix states the broader support bar clearly. A provider is not supported merely because AxiOwl can write a config file or start a process. The provider must be discoverable, receive a message, reply through AxiOwl MCP, and carry correct provider-owned sender identity.

That is why the receipt boundary matters. A send receipt answers, "What happened to this outbound handoff?" A response-backed proof answers, "Did the target actually receive the message and reply through the expected AxiOwl identity path?" Those are related, but they are different pieces of evidence.

MCP Receipts Have Their Own Boundary

AxiOwl also exposes MCP tools. In mcp_server.cpp, the axiowl_send_message tool is described as a way to send a message through AxiOwl using the host MCP session ID as the stable sender identity key. Its description explicitly says success is an MCP-to-AxiOwl handoff receipt only; provider delivery and reply are not implied.

The MCP server logs mcp_inbound_send_receipt with fields such as the MCP request ID, target, body byte count, sender session ID, sender name, node, provider, host kind, identity source, CLI exit code, and a receipt boundary named mcp_tool_call_reached_axiowl_and_cli_returned_to_host.

That boundary is practical. It prevents an agent tool call from being mistaken for proof that a completely separate target agent already saw and handled the message. The MCP tool proves the tool request reached AxiOwl and the CLI returned to the host. The later provider and reply evidence has to come from the delivery path and any response-backed test.

Where Operators Look for Evidence

AxiOwl stores durable local evidence under its state root. On Windows, the state root is %LOCALAPPDATA%\AxiOwl; on Linux it uses $XDG_STATE_HOME/axiowl or ~/.axiowl. The implementation defines two relevant log paths:

logs/events.jsonl
logs/delivery.jsonl

The CLI prints the delivery log path in the receipt. The delivery log records staged events with the message ID, run ID, provider, target, session ID, node, stage, result, and detail. The evidence log records broader events, including sender identity metadata, request acceptance, delivery handoff results, delivery worker results, and MCP inbound receipts.

This matters during operations. If an operator has a message ID, they can inspect the staged delivery trail rather than guessing whether a failure happened during target resolution, local acceptance, delivery-worker handoff, provider write, or reply verification.

Why "Unknown" Is Better Than False Success

The historical receipts and logging plan includes an important principle: unknown is allowed when the truth is unknown, but unknown must never be displayed as success.

That principle fits the current implementation. Some provider paths can start a process, queue a bridge command, or hand work to a background worker before the final downstream behavior is visible. In those cases, AxiOwl should preserve uncertainty. A degraded or unverified path can still be operationally useful, but it should say what property was lost, such as not guaranteeing a live desktop window refresh or not yet proving the receiver's reply.

This is especially important for provider surfaces that depend on editor extensions, private hooks, command watchers, or session files. AxiOwl does not improve reliability by pretending those layers are simpler than they are. It improves reliability by making each boundary inspectable.

Practical Reading of Common Receipt States

In everyday use, the most important receipt states are straightforward:

accepted_by_axiowl means the request entered the AxiOwl pipeline, sender and target resolution got far enough for AxiOwl to accept the handoff, and provider delivery or reply is not implied by that receipt alone.

accepted_by_provider means the selected provider edge reported acceptance for that provider path.

provider_write_failed or a failed receipt means the target route or provider write failed loudly, with a reason attached.

provider_handoff_started_unverified means AxiOwl started a provider handoff but does not have the stronger provider confirmation required to call it a fully verified write.

accepted_by_live_upstream_relay is a special path where the message was appended to a live upstream relay outbox rather than going through the ordinary local provider route.

The receipt should always be read together with the message ID and delivery log. The message ID is the handle that lets an operator follow the evidence trail.

The Operator Value

Delivery receipts make AxiOwl safer to operate because they reduce ambiguity. A failed send can say that the target was missing from the registry. A local handoff can say that AxiOwl accepted the request but provider wake-up is not implied. A provider write can say which provider edge was used. A response-backed test can later prove that the receiver replied through AxiOwl MCP with the right identity.

That gives developers and operators a practical debugging model. Instead of asking, "Did the message send?" they can ask more precise questions:

AxiOwl's receipt design turns those questions into observable states.

Closing

AxiOwl delivery receipts are intentionally conservative. They do not exist to make every send look successful. They exist to mark the exact boundary AxiOwl has reached and to point operators toward the evidence needed for the next question.

That is the right behavior for a system that routes messages across multiple agent providers. In AxiOwl, a good receipt is not the loudest possible success message. It is the most accurate statement the software can prove.

Tagged , , , , , , ,