Zephr Docs

Agent integration

This page groups the capabilities that connect an external coding agent or host to Zephr. The family has two honest halves: the ingress side — universal-capture (install dialect and precision-inject contract onto every supported agent), intelligence-gateway (the dual-protocol inference front door for Claude Code / Cursor / Codex), agent-adapter-sdk (the generic client-adapter factory), agent-plugin-interop (Agent Plugins v1.0.0 imported as Zephr extensions), and agent-envelope-dispatch (the MCP-to-Agent dispatch boundary); and the execution side — autonomous-agents (governed background-agent loops). memory records what an integrated agent learns; this page documents only the connection, not the belief lifecycle — see Memory.

Capability status

CapabilityTierStatusEvidence
universal-captureCloses circuit (Capture)EvolvingCatalog, install dialect, honesty + precision-inject contract
intelligence-gatewayUser-facing front doorEvolvingDual-protocol inference front door (Anthropic/OpenAI)
agent-adapter-sdkCloses circuit (Adapter)EvolvingGeneric client-adapter factory + per-adapter reality matrix
agent-plugin-interopPlatform extensionEvolvingAgent Plugins v1.0.0 import as extensions
agent-envelope-dispatchTrust boundaryEvolvingMCP-to-Agent dispatch, bridge registration, fail-closed routing
autonomous-agentsCore extensionEvolvingGoverned executor, scoped tools, and proposal-bound writes ship

autonomous-agents

autonomous-agents owns governed background-agent definitions and runs triggered through guard_agent_trigger, executing in the cloud worker plane with scoped tools, hard deny rules, evidence-gated writes, build-before-PR behavior, and bounded budget/timeout/rollback. The governed runtime ships with the queue consumer, model resolver, scoped tool executor, and proposal-bound write applier. Runs remain governed by hard deny rules, budget, timeout, and rollback boundaries.

universal-capture

universal-capture owns the catalog, install dialect, honesty contract, and precision-inject contract for hooks/MCP/skills/rules onto every supported coding agent. It is the capture entry point that feeds memory; it does not own belief lifecycle (that is memory).

intelligence-gateway

intelligence-gateway ships the dual-protocol inference front door: Anthropic Messages at /api/cloud/v1/messages (SSE content_block_* / message_delta) and OpenAI Chat Completions at /api/cloud/v1/chat/completions (SSE chat.completion.chunk).

Workflow

Both paths share one admit → resolve → inject-once → reserve → upstream → settle machine and host Claude Code, Cursor, and Codex on a user-opted custom endpoint. No other path accepts a host's custom-endpoint traffic.

Data flow

The admitted request receives context once, is reserved before the upstream call, streams through the selected protocol, and settles usage after completion.

agent-adapter-sdk

agent-adapter-sdk ships the generic CliSubprocessAdapter.for(spec, opts) factory and the per-adapter reality matrix that bind "any CLI agent" without a hand-written adapter per vendor. Lifecycle plumbing, scope resolution, HookPolicy enforcement, and fail-open semantics live in the factory; vendor differences (flag names, JSON field names, env vars, hook-event mapping) live in the spec — adding a vendor is a spec + parity test, not a new adapter file.

agent-plugin-interop

agent-plugin-interop ships Agent Plugins v1.0.0 package import as Zephr extensions (plugin.json, skills/, mcp.json, reverse-domain clients). It is the interop surface behind agent-envelope-dispatch; see Extensions for the extension runtime these plugs into.

agent-envelope-dispatch

agent-envelope-dispatch owns the MCP-to-Agent dispatch boundary: server-lifetime Agent composition, per-connection bridge registration, durable receipts, user-presence attestation, and fail-closed routing for requiresEnvelope operations. It prevents MCP tools from bypassing an Agent's capability, idempotency, and lifecycle contract while keeping hosted tenant contexts isolated from local bridge state.

Availability

SurfaceTierResidencyNotes
intelligence-gateway /api/cloud/v1/messages—cloudAnthropic Messages path for host-lane inference
intelligence-gateway /api/cloud/v1/chat/completions—cloudOpenAI Chat Completions path for host-lane inference
zephr hosts emit <platform> (CLI)—localEmit a supported host integration pack
zephr integrations list|install|remove|status—localIntegration pack lifecycle

Egress

SurfacePublic service classPayload classBoundary owner
Host inference upstreammodel-provideruser-content + identity + metadataintelligence-gateway
Agent-plugin reverse-domain clientagent-clientmetadata + source-codeagent-plugin-interop

agent-envelope-dispatch carries the requiresEnvelope boundary that prevents MCP tools from bypassing the Agent's capability contract; it holds no host-level credential in the envelope.

Limits and failures

Limits

  • autonomous-agents runs only through the configured model resolver, scoped tools, and proposal-bound write applier; deny rules and budgets can refuse a run before a write.

Failure modes

  • intelligence-gateway admits on install token; a host with a revoked or absent token is rejected before model resolution.
  • agent-envelope-dispatch is fail-closed: a requiresEnvelope operation that cannot prove envelope presence is refused rather than downgraded.

Recovery

Restore a valid installation token before retrying the gateway. Envelope failures require a new correctly admitted request; they are never downgraded to an untrusted path.

Troubleshooting

Confirm the host uses the intended protocol path, the installation token is present and active, and context injection occurs once before checking upstream-provider behavior.

autonomous-agents consumes external-signals triggers and governance deny rules; intelligence-gateway is the inference lane consumed by agent-platform; agent-envelope-dispatch is the trust boundary to agent-runtime. See Data flows: agent dispatch for the admit→resolve→inject sequence.