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
| Capability | Tier | Status | Evidence |
|---|---|---|---|
universal-capture | Closes circuit (Capture) | Evolving | Catalog, install dialect, honesty + precision-inject contract |
intelligence-gateway | User-facing front door | Evolving | Dual-protocol inference front door (Anthropic/OpenAI) |
agent-adapter-sdk | Closes circuit (Adapter) | Evolving | Generic client-adapter factory + per-adapter reality matrix |
agent-plugin-interop | Platform extension | Evolving | Agent Plugins v1.0.0 import as extensions |
agent-envelope-dispatch | Trust boundary | Evolving | MCP-to-Agent dispatch, bridge registration, fail-closed routing |
autonomous-agents | Core extension | Evolving | Governed 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
| Surface | Tier | Residency | Notes |
|---|---|---|---|
intelligence-gateway /api/cloud/v1/messages | — | cloud | Anthropic Messages path for host-lane inference |
intelligence-gateway /api/cloud/v1/chat/completions | — | cloud | OpenAI Chat Completions path for host-lane inference |
zephr hosts emit <platform> (CLI) | — | local | Emit a supported host integration pack |
zephr integrations list|install|remove|status | — | local | Integration pack lifecycle |
Egress
| Surface | Public service class | Payload class | Boundary owner |
|---|---|---|---|
| Host inference upstream | model-provider | user-content + identity + metadata | intelligence-gateway |
| Agent-plugin reverse-domain client | agent-client | metadata + source-code | agent-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-agentsruns 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-gatewayadmits on install token; a host with a revoked or absent token is rejected before model resolution.agent-envelope-dispatchis fail-closed: arequiresEnvelopeoperation 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.
Related capabilities
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.