Create, Send, Receive, Discover: The Core AxiOwl Workflow

Create, Send, Receive, Discover: The Core AxiOwl Workflow

AxiOwl's core workflow is built around four verbs: create a provider session, send a message to a known session, receive a reply through MCP, and discover provider sessions when the local routing table needs repair. In the current C++ implementation, those verbs are not marketing labels. They are concrete paths through axiowl.exe, the MCP server, the local registry, the message pipeline, discovery code, and provider-specific delivery edges.

The important idea is that AxiOwl does not route by guesswork. A friendly agent name can be used at the edge, but the trusted route is provider-owned session identity stored in the registry. Discovery can find or repair that identity. Create can enroll a new session when the provider returns a stable session id. Send can return an AxiOwl handoff receipt before provider delivery finishes. Receive happens when the other provider calls back through AxiOwl's MCP tool with real host metadata.

Sources read

Source repo: C:\Users\kjhgf\OneDrive\Documents\postfourth\axiowl-cplus

The Workflow Is A Routing Contract

The architecture overview describes the runtime path plainly:

user / provider MCP call / CLI
  -> axiowl.exe
  -> MCP or CLI command handler
  -> MessagePipeline
  -> registry target and sender resolution
  -> targeted discovery repair when needed
  -> provider_edges dispatch
  -> provider-specific delivery
  -> delivery logs and provider proof

That flow is why the four verbs belong together. create produces a provider session. discover turns provider state into registry rows. send resolves a sender and target from those rows. receive is the reverse send path, where a provider session replies through AxiOwl MCP and brings its own provider/session metadata with it.

The registry model makes that possible. An AgentRecord stores display_name, aliases, provider, provider_session_id, node_id, enabled, sendable, source, timestamps, and last_error. A visible name is useful, but a route is only trustworthy when AxiOwl can tie it to a provider, a node, and a provider session id.

Discover: Find Real Sessions Before Routing

Discovery is available directly from the CLI:

axiowl discover <codex|codex-cli|vscode-native|vscode-copilot|copilot-cli|antigravity|antigravity-cli|cursor|cursor-cli|claude-code-cli|opencode-cli|all> [--target <agent>] [--json]

The discovery report model includes the provider, node id, target name, source paths, discovered rows, issues, and counts for rows enrolled, updated, skipped, and evidence-only matches. Each discovered row carries display_name, provider, provider_session_id, node_id, status, sendable, has_enrollment_proof, source, evidence strings, last_seen_at, and last_error.

The merge logic is intentionally strict. Rows missing required identity fields are skipped. Rows without enough sendability proof are not silently enrolled. Manual registry rows are protected from discovery downgrades, though discovery can enrich them with aliases and timestamps. Local Codex discovery is especially careful: weak evidence can be counted as evidence-only, while stronger sources such as targeted desktop IPC owner proof can enroll a sendable row.

The send pipeline also uses discovery as a repair step. If a target is missing or the current registry row requires repair, MessagePipeline::find_target_with_single_miss_resolution logs the miss and runs one targeted discovery pass. If the target still is not present as an enabled, sendable, non-stale row, AxiOwl rejects the send with a summary of what discovery found.

Discovery is therefore not a substitute for delivery proof. It is the way AxiOwl keeps the local routing table current without pretending that every hint is a usable route.

Create: Open A Provider Session And Enroll It

The CLI create command is explicit about the target provider and requested display name:

axiowl create --provider <codex|codex-cli|antigravity|antigravity-cli|vscode-native|vscode-copilot|copilot-cli|cursor|cursor-cli|claude-code-cli|opencode-cli> --name <agent> [--body <message> | --stdin] [--from <agent>] [--from-node <node>] [--model <model>] [--cwd <cwd>]

The MCP equivalent is axiowl_create_agent, with provider, name, optional body, model, and cwd. The MCP path matters because it supplies provider-owned sender metadata. If a create request has an initial body, mcp_server.cpp resolves the host identity, registers the sender when possible, and passes the message to the CLI with --stdin and the resolved sender address.

On the CLI path, an initial message normally requires sender identity. AxiOwl builds a final visible body that says who the message is from and appends the exact MCP reply tool shape. Before provider dispatch, the create path validates that final visible body through the delivery worker in validation mode.

Provider creation is dispatched through create_with_provider in provider_edges.cpp. Current create edges exist for Codex, Codex CLI, Antigravity, Antigravity CLI, VS Code native, VS Code Copilot-backed sessions, Cursor, Cursor CLI, Claude Code CLI, Copilot CLI, and OpenCode CLI. The important limit is that a code path is not the same as supported status. The provider support matrix is the status source of truth.

When a provider accepts create, AxiOwl records create lifecycle events and tries to enroll the created session. Enrollment requires a stable provider session id. If the provider accepted the create but did not return a usable provider session id, AxiOwl says so and does not create a sendable registry row. If a session id is available, the created row becomes sendable, gets aliases, records source/method details, and can be used by later sends.

Remote create is explicitly unsupported in the local-provider build. The provider edge returns a loud failure explaining that remote create needs an explicit remote node and contract before it can be enabled.

Send: Handoff First, Provider Proof Later

The CLI send shape is:

axiowl send --to <agent> --body <message> [--from <agent>] [--from-node <node>] [--strict] [--run-id <uuid>] [--delivery-method <cursor-method|A|B|C|D|E>]
axiowl send --to <agent> --stdin [--from <agent>] [--from-node <node>] [--strict] [--run-id <uuid>] [--delivery-method <cursor-method|A|B|C|D|E>]

For provider-hosted use, the preferred path is the typed MCP tool:

axiowl_send_message({ "to": "<agent>", "body": "<message>" })

The MCP server's initialize instructions are direct: for sending, use axiowl_send_message; for creating chats, use axiowl_create_agent; do not construct raw argv, provide --from manually, or ask the chat to invent its own session id. The tool description also states the receipt boundary: success is an MCP-to-AxiOwl handoff receipt only, and provider delivery or reply is not implied.

MessagePipeline::send enforces the routing contract in order. It rejects an empty target or empty body. It resolves sender identity from the registry or final-visible relay metadata. If an explicit sender looks like a session id but is not registered, the pipeline runs one targeted sender discovery repair and tries again. If sender identity still cannot be resolved, the send fails loudly.

Only after sender identity is resolved does AxiOwl resolve the target. It prefers exact provider session matches, then sendable name or alias matches, and it favors newer rows when duplicate names exist. If the target is missing or stale, AxiOwl runs one targeted discovery repair across local provider surfaces. If the target is still missing, evidence-only, or not sendable, the send is rejected with a targeted discovery summary.

When the target is resolved and sendable, the receipt changes to:

state = accepted_by_axiowl
detail = axiowl_receipt_only

That is the local handoff boundary. The delivery worker receives a temp JSON request and starts detached for normal sends. It then dispatches through provider edges such as Codex desktop IPC, Codex CLI resume, VS Code bridge delivery, Cursor bridge command files, Antigravity provider calls, and other provider-specific paths.

The tests protect this behavior. test_send_returns_axiowl_receipt_then_starts_delivery_handoff expects accepted_by_axiowl to be true, accepted_by_provider to be false, the state to be accepted_by_axiowl, and the log to show the receipt boundary before provider delivery worker results. That distinction is essential for operators: a handoff receipt means AxiOwl accepted the request and started delivery work. A provider reply through MCP is stronger end-to-end proof.

Receive: A Reply Is Another Metadata-Backed Send

AxiOwl receive behavior is not a generic inbox command in the current Windows CLI. It is the return path through the target provider and MCP.

Before delivery, AxiOwl builds a final visible body. With a resolved sender, the body begins with Message from <sender>, includes the user's message, and appends an exact reply instruction:

mcp__axiowl.axiowl_send_message({
  "to": "<sender>",
  "body": "<full reply>"
})

When the pipeline has a run id and message id, the reply instruction also includes runId and receiptForMessageId for correlation. The core tests explicitly reject older shell fallback wording, old command-only instructions, and raw axiowl send --from helper text. The supported reply path is the MCP tool call.

When a provider replies through axiowl_send_message, mcp_server.cpp resolves identity from the host MCP metadata, registers the sender as source=mcp_sender_identity when the sender has a real display name and session id, and then invokes the CLI send path with the resolved sender address and node id. It also logs mcp_inbound_send_receipt, including the MCP request id, sender session id, sender name, sender provider, run id, receipt correlation, and whether AxiOwl accepted the handoff.

That is why receiving is tied to metadata. A reply must carry provider/session identity so AxiOwl can route future messages back to a real session, not to a guessed name.

Support Limits Operators Should Notice

The CLI help lists several provider values because the executable has broad command handlers and provider dispatch points. The support matrix is more precise about product status.

Supported surfaces in the matrix include Codex agents, Codex CLI, VS Code native agents, VS Code Copilot-backed extension use, Cursor agents, and Antigravity agents. The support bar is not just "AxiOwl wrote a config file" or "a provider edge exists." The bar requires discovery, installation of required integration pieces, named-session send, provider receipt, MCP reply, and correct provider-owned sender identity.

Several CLI-style surfaces are target status rather than final-supported status. Antigravity CLI, Claude Code CLI, OpenCode CLI, and Copilot CLI need provider-owned metadata proof or future metadata patches before they meet the final bar. Cursor CLI is marked unsupported in the matrix despite code paths existing, because the current accepted Cursor surface is the editor/agent window, not an assumed separate CLI product.

Remote is also intentionally out of scope for local-provider remediation builds. Discovery reports remote as excluded, remote create is unsupported, and the security docs say remote must not hide local provider failures. AxiOwl is designed to fail loudly when a route is unsupported or unproven.

Why The Workflow Matters

The create-send-receive-discover loop gives AxiOwl practical operating discipline:

For developers, this makes the system debuggable. Registry rows explain what AxiOwl thinks it can route to. Discovery reports explain what was found, skipped, enrolled, or downgraded. Delivery logs show where the request crossed from AxiOwl into provider-specific work. MCP logs show which provider session made the inbound call.

For operators, it means AxiOwl is conservative in the right places. It can use natural agent names, but it does not make those names the source of truth. The source of truth is a real provider session, discovered or created, stored in the registry, and used consistently when messages move in either direction.

Closing

Create, send, receive, and discover are the core AxiOwl workflow because they form one cycle. Discovery finds reachable sessions. Create adds new ones when the provider can return stable identity. Send moves a final visible message through the registry and provider edge. Receive brings the reply back through MCP with provider metadata attached. That cycle is what lets AxiOwl coordinate across different agent surfaces without pretending that every visible chat title is a stable address.

Image prompt:

Create a polished graphic image related to: the core AxiOwl create, send, receive, discover workflow.

Subject: a four-part technical workflow sculpture made of clean metallic modules: one module resembles a new empty terminal pane being generated, one shows glowing data packets crossing a bridge, one shows a receiving tray with luminous packets arriving, and one shows a radar-like scanner connected to small server blocks; all four modules are connected by precise circuit traces in a loop, with no readable labels.
Style: halfway between a clean symbolic icon and a realistic product/technical illustration; professional SaaS/technical marketing style; crisp edges; high detail; no text; no logos.
Background: solid #00ff00 chroma key green screen background covering the full canvas edge to edge.
Restrictions: no owl, no axolotl, no birds, no animals, no mascot, no text, no watermark.

Tagged