How to Repair AxiOwl Provider Integrations

Provider integration repair in AxiOwl is not a matter of blindly retrying the same send until something appears in a chat. AxiOwl has a stricter model: it discovers real provider sessions, records them in a durable local registry, resolves sender and target identity, runs a targeted discovery repair when a row is stale or missing, and only then dispatches through the selected provider edge.

That design is useful during repairs because it gives operators concrete places to look. A failure can be in discovery, registry state, MCP metadata, a provider bridge extension, a provider patch, provider auth, or the final delivery edge. Treating all of those as "the provider is broken" wastes time. AxiOwl's implementation is built to fail loudly so the repair can start at the right layer.

Start With The AxiOwl Boundary

AxiOwl is a local Windows coordinator for provider-to-provider messaging. The current repository describes the Windows desktop target as the home for the C++ runtime, CLI, MCP server, registry, discovery, provider edges, installer helper, provider extensions, and provider patches. The user docs summarize the job clearly: AxiOwl discovers provider sessions, records them in a local registry, sends messages to selected provider sessions, exposes an MCP tool for replies, and records receipts, logs, and delivery evidence.

The important operational point is that a send receipt is not the same as an end-to-end provider proof.

accepted_by_axiowl means AxiOwl accepted and validated the request and handed it to its delivery layer. If a provider path reports accepted_by_provider, that is stronger, but it still is not the same as a provider reply. The strongest proof is a response through AxiOwl MCP with correct provider-owned sender identity. A repair is complete only when the target can receive and the reply path can identify the sender correctly.

Check The Supported Surface First

Before changing files, confirm that the provider surface is supposed to work. The current support matrix lists supported surfaces such as Codex agents, Codex CLI, VS Code agents, Copilot through the VS Code bridge, Cursor agents, and Antigravity agents. It also lists several CLI surfaces as target rather than fully supported, including Antigravity CLI, Claude Code CLI, OpenCode CLI, and Copilot CLI.

That distinction matters during repair. A supported provider should be repaired until the full path works: discovery, install/config, send, provider receive, MCP reply, and correct sender identity. A target provider may have code or historical proof, but it should not be treated as fully repaired unless it meets the current metadata and response-backed proof bar.

The support matrix also calls out a hard rule for CLI providers: environment-only sender identity is not final support. The provider must supply usable metadata through MCP metadata, a provider patch, or another provider-owned mechanism.

Inspect The Registry Before The Provider

AxiOwl's registry is durable state, not a throwaway cache. It maps a human-readable agent name to a provider, provider session id, node id, aliases, sendability, source, timestamps, and last error. The architecture docs and registry implementation emphasize that AxiOwl should not invent provider facts. If a target is not known or not sendable, the correct behavior is a clear failure, not an optimistic send to the wrong place.

Start with:

axiowl status
axiowl list agents

For a local development build, the Windows desktop README shows the equivalent build-output form:

.\build\Debug\axiowl.exe status
.\build\Debug\axiowl.exe list agents

Look for the target chat by its real display name and inspect the provider, provider session id, node id, sendable state, source, and last error. A row that is present but not sendable is different from a row that is absent. A row with a stale display name is different from a row whose provider-owned session id still matches. A row created from evidence-only discovery is different from a row backed by enrollment proof.

Do not fix registry problems by making up session ids. The provider session id belongs to the provider adapter, not to the human operator.

Let Targeted Discovery Do Its Job

The message pipeline resolves the sender, then resolves the target. If the target is missing or needs repair, the discovery layer can run one targeted repair pass. The current discovery.cpp path checks local provider discovery in sequence across Codex, Codex CLI, VS Code native, VS Code Copilot-backed, Copilot CLI, Antigravity, Antigravity CLI, Cursor, Cursor CLI, Claude Code CLI, and OpenCode CLI. Remote discovery is explicitly out of scope for local targeted miss resolution in this code path.

When discovery finds a row, it does not automatically trust it. It checks whether the row has enrollment proof. Rows without proof can be recorded as evidence, but they are not promoted to sendable delivery targets. Existing manual rows are protected from discovery downgrade, while stale auto-discovered rows can be downgraded when proof disappears.

This is the repair behavior operators should expect:

• If a provider session is truly discoverable and sendable, targeted discovery can enroll or refresh it.
• If discovery only finds weak evidence, AxiOwl should refuse to send and explain that no sendable exact target row was found.
• If a known row is not sendable, the send should fail with target is known but not sendable and include last_error when available.
• If the registry provider does not match a provider edge, dispatch should fail as an unknown provider rather than falling through silently.

That makes the next repair step straightforward: read the log and repair the layer that failed, instead of overriding the registry.

Repair Install And Configuration Separately

The Windows MSI is responsible for the local runtime, PATH integration when selected, registry and runtime directories, logs, selected MCP configs, selected bridge extensions, selected provider patches, and discovery finalization. The installer behavior matrix is explicit that each provider checkbox should behave like a separate install unit.

That means a provider repair should be scoped to the selected provider. If Cursor is broken, a repair should not close or patch VS Code as collateral damage. If VS Code is unchecked, it should not be installed, patched, restarted, or uninstalled. If Codex integration is selected, the repair should touch AxiOwl-owned Codex config and plugin support, not unrelated user sessions or provider auth.

Useful paths during install diagnosis are:

%LOCALAPPDATA%\AxiOwl\logs
%LOCALAPPDATA%\AxiOwl\registry
%LOCALAPPDATA%\AxiOwl\runtime

For installer-level diagnosis, collect a verbose MSI log:

msiexec /i path\to\axiowl-activation-windows-installer.msi /l*v install.log

A successful installer run proves that selected install actions completed. It does not prove the provider message path works. After repair, still run discovery and send/receive validation.

Repair MCP Sender Identity

Many provider problems are not outbound delivery problems at all. They are reply identity problems.

The MCP server requires enough host metadata to identify the sending provider session. The implementation maps host kinds such as Codex, VS Code, VS Code Copilot, Cursor, Antigravity, Claude Code CLI, Copilot CLI, OpenCode CLI, and related surfaces to provider identities. If required metadata is missing, mcp_server.cpp is designed to reject the send or create action loudly. Examples include missing Antigravity conversation id, missing Cursor composer id, missing Claude session id, missing Copilot session id, and missing OpenCode session id.

Use the MCP path the way AxiOwl exposes it. Provider replies should use the typed MCP tool, not hand-built raw command lines. The tool description in the MCP server says axiowl_send_message uses the host MCP session ID as the stable sender identity key; AxiOwl resolves that key to the registered visible sender name before appending reply instructions.

For troubleshooting, axiowl_whoami is the useful first tool because it reports what AxiOwl sees as the current host session identity. If whoami cannot identify the session, a normal reply send will not be trustworthy either.

Repair Provider Edges Without Hiding Failures

Provider delivery is selected in provider_edges.cpp. Current dispatch includes edges for Codex, Codex CLI, VS Code native, VS Code Copilot-backed, Antigravity, Antigravity CLI, Cursor, Cursor CLI, Claude Code CLI, Copilot CLI, OpenCode CLI, and remote. Unknown providers return an explicit failure. Remote delivery returns an out-of-scope result for this local-provider remediation path.

That behavior is intentional. AxiOwl should not silently fall back from one provider family to another. The simple architecture plan states the contract directly: every send resolves sender, resolves target, builds the final visible body, chooses one provider edge, sends through that edge, records evidence, and returns a receipt. No provider is allowed to skip the sequence, rebuild the final visible body, or silently use another provider family.

When repairing a provider edge, preserve that contract. If VS Code native delivery fails because the bridge extension is stale, repair the VS Code bridge and patch state. If Cursor fails because a private patch-sensitive command path changed, repair Cursor's AxiOwl-owned bridge or patch and validate it. If a CLI provider lacks provider-owned metadata, do not declare success from a raw process launch.

Validate With A Real Send And Reply

Use a small message first:

axiowl send --to "Target chat name" --body "Please reply through AxiOwl with a short confirmation."

For multiline payloads, use stdin so shell quoting does not damage the message:

@'
Please reply through AxiOwl with a short confirmation.
'@ | axiowl send --to "Target chat name" --stdin

Read the receipt honestly. If it says accepted_by_axiowl, the local AxiOwl handoff worked. If it reports provider acceptance, the provider edge reported a stronger status. The repair is not done until the target provider sends a reply through AxiOwl MCP and AxiOwl can resolve the reply to the correct provider-owned sender identity.

This final reply step catches the failures that config-only checks miss: stale MCP transports, old extension folders, provider sessions opened before the new MCP config, changed private provider internals, missing metadata patches, auth problems, and evidence-only discovery rows.

Practical Repair Checklist

Use this order when a provider integration breaks:

1. Confirm the provider surface is supported or only target/experimental in the current support matrix.
2. Run axiowl status and axiowl list agents.
3. Check whether the target registry row is missing, stale, evidence-only, disabled, or not sendable.
4. Read %LOCALAPPDATA%\AxiOwl\logs, %LOCALAPPDATA%\AxiOwl\registry, and %LOCALAPPDATA%\AxiOwl\runtime.
5. If the installer was involved, collect a verbose MSI log and verify only the selected provider feature was touched.
6. Restart or reopen the provider session when the integration depends on newly installed MCP config or bridge code.
7. Use axiowl_whoami from the provider MCP context to verify sender identity.
8. Send a small message and require a real AxiOwl MCP reply as proof.
9. Do not promote evidence-only rows, guessed display names, or environment-only metadata to final support.

Closing

AxiOwl provider repair works best when each layer keeps its contract. Discovery finds candidate sessions. The registry records durable provider facts. MCP metadata identifies the sender. The message pipeline resolves the route and builds one final visible body. Provider edges do provider-specific delivery and report what happened.

When an integration fails, repair the broken layer and preserve the loud failure. That is how AxiOwl avoids routing a message to a stale chat, mistaking a local handoff for a provider reply, or treating a guessed session name as proof.