Skip to content
Vulpine
Esc
↑↓navigate↵open⌘Jpreview
On this page

ACP agents

Accepted design, ADR 0065: independent off-by-default ACP client and agent roles beside the voice path; exact human-owned permission scopes, managed child confinement, herdr-fenced attachment, bounded lifecycle and unknown dispatch retention. Sixty-nine abstract qualification scenarios, including mandatory resource links without implicit fetching; no runtime implementation or activation.

Living doc, checked against the code 2026-11-14

acp-integration.v1 — the opt-in boundary between operator pi and ACP agents

Accepted design. Not activated: both directions are off by default. This is Vulpine’s local policy and lifecycle contract around stable ACP v1, not a new ACP wire version. ADR 0070 owns the architecture. The Scenario vectors are normative inputs. Their given, when and expect fields describe state-machine events, not raw ACP packets.

Native invocation lifetime

The native GPUI host owns the invocation and UI, the controller and the sole provider writer. Retirement is synchronous, permanent and serialized on that owner with bounded nonblocking write admission; after it, no effecting write is admitted. Node is a bound request/progress client. Its death or channel loss triggers retirement when observed, so writes may still be admitted in that interval, and writes admitted earlier may complete. Neither retirement nor host exit recalls buffered bytes or proves provider quiescence.

Roles and admission

  • Outbound: the operator’s Pi invokes Vulpine’s ACP client to use a registered provider. Fresh local children are managed; existing agents are attached through herdr. Outbound has no connection to the gateway’s brain pool.
  • Inbound: an external ACP client invokes Vulpine’s ACP agent, which owns a separate restricted Pi RPC child. The client’s human UI owns interactive approvals; Vulpine’s local loadout ceiling still applies. Unsupported methods refuse explicitly. The agent advertises no auth methods and no optional recovery.
  • Voice: not an ACP initiating interface. No route to remote shell, close, kill or gateway-only tools is added.
outbound_enabled inbound_enabled Admitted role
false false none; no ACP child, listener, discovery polling or model work
true false outbound only
false true inbound only
true true both; independent generations and allocations, shared installation resource ceiling

The flags are adapter policy; the gateway’s config does not read them, and no installed entry point takes them yet. Missing policy means both off; malformed policy refuses startup. Reconfiguration validates a complete snapshot before publishing it. A disable latches before the drain, and no invalid replacement undoes it. Only the operator config interface, never a tool call, can enable a direction, raise a ceiling or register a provider.

The effective tool policy intersects the tool registry’s door policy. Enabling the transport does not make a deferred or off tool callable. Disabling a direction invalidates its sessions’ interactive grants at once.

Provider binding

Each registry entry carries these typed fields, decoded before any spawn or attach:

Field Meaning
id, version, provenance Stable provider ID, adapter version and review/license provenance; never chosen from prose
exec, sha256, argv Operator-registered absolute executable, immutable digest and literal argument template; no shell/PATH lookup or unverified downloader
roles, protocol_version Qualified client/agent roles and stable wire version 1
capabilities Declared operations, negotiation requirements, implementation support and qualification receipt per operation
loadout_id, loadout_digest Mandatory for managed children; names immutable effective tool, extension, fs, network, credential and process policy
attachment Optional herdr backend/address binding and writer/callback proof; absent means no attach
platform_profile Host enforcement implementation and qualification receipt, or unavailable
limits Positive finite limits, no greater than installation ceilings
authentication Explicit credential references and permitted human-interface binding; never literal secrets in discovery metadata

Runtime capability = implemented ∩ enabled ∩ authorized ∩ negotiated ∩ qualified. A change of provider version or executable digest invalidates readiness. Warm identity includes provider/digest, role, model/config digest, loadout digest, principal, machine, workspace scope and authority generation. Policy-incompatible sessions never share a warm entry. A failed or unknown cleanup is never a reusable entry.

Capability matrix

baseline must pass before a role is ready. conditional is advertised and qualified separately. held is absent or unsupported in the initial profile. Outbound support describes the Vulpine client, not every target’s promises.

Surface Outbound client Inbound Pi agent Required behavior
initialize / version / capability exchange baseline baseline Agent returns requested version if supported, otherwise its latest supported version (initially 1); client refuses an unsupported response version. Retain negotiated facts; no mutation before initialized
session/new baseline baseline Scope and budget admission before allocation; bind opaque session to principal/generation
text and resource_link session/prompt; session/update baseline baseline Both prompt block kinds are mandatory in stable v1, without optional capability flags; ordered bounded updates, one prompt per session, preserved tool-call IDs and stop reason
session/cancel baseline baseline Cancel pending permissions, retain prompt slot until remote settlement or verified teardown
session/request_permission baseline handler baseline caller Exact offered IDs and scope; nested selected/cancelled shape; UI not available → cancelled
session/load and history conditional held initially No fabricated resume; ownership, workspace and authority revalidation; bounded replay with no duplicate live events
session/list / fork / resume extensions held held Not baseline; explicit unsupported response if requested
modes / model or config changes conditional held initially Enumerated known IDs only, cannot widen loadout; invalidates warm identity; no successful no-op
fs/read_text_file and fs/write_text_file conditional callbacks conditional delegation Resource checks independent of tool permission; delegated denial never falls back to local disk
terminal/create, output, wait_for_exit, kill, release conditional callbacks conditional delegation Session-owned terminal identity; output and execution budgets; release is not proof of process death
image/audio/embedded resource content held initially held initially Optional image, audio and embeddedContext capabilities remain false/absent; reject unsupported blocks before dispatch, never silently discard them. Embedded resource is not resource_link
MCP servers in session/new conditional held initially Validate/admit every requested server or reject setup; never accept then ignore
authenticate conditional conditional Advertise only real flows; absent auth capability does not mean anonymous remote authorization
usage / child-agent extensions held held Bilateral named/versioned negotiation; unknown usage is not zero or complete
draft v2 / HTTP or private carriers held held Separate negotiation and qualification; never label them stable-v1 stdio conformance

Forwarding keeps unknown optional fields within bounded payloads; absent, null and value stay distinct. Unknown methods get method-not-found. Malformed known tags or outcomes are protocol errors. Unknown notifications may be ignored with a bounded diagnostic, never read as permission or completion. stdout carries only protocol frames. Wire errors and stop reasons keep their schema meanings; local refusals are separate typed receipts, never new wire enum values.

A valid resource_link is accepted beside text with no optional prompt capability. Block order, the required uri and name, schema-valid metadata (title, description, mimeType, size, annotations, _meta) and bounded unknown fields are preserved. A link is a reference, not embedded resource content and not access to its target.

Outbound forwards the link block without dereferencing it. Inbound turns it into a labeled, JSON-escaped untrusted resource-reference record in Pi’s user input, keeping its fields and optional-field presence; metadata never becomes system instructions, tool configuration or grants. Nothing fetches the URI, opens a local file, resolves DNS or invokes a URI handler. Later model-requested access is a separate operation under the authority intersection. URI values and metadata follow the no-full-prompt logging policy.

The whole prompt is validated before dispatch against the selected schema. An unsupported embedded resource, image or audio block rejects the whole prompt, even after valid blocks. Frame, depth and node bounds cover all metadata, and the translated pi prompt, JSON escaping included, must fit the frame-byte ceiling. Over-budget translation is rejected before dispatch: nothing is truncated or dropped, and no grant is inferred from a URI scheme or size.

Authority and human interaction

Effective operation authority is:

installation policy ∩ immutable loadout ∩ invocation scope ∩ current writer/allocation ownership ∩ applicable grant.

A preauthorized operation runs only inside the configured restricted scope. Escalation needs a human grant and overrides no other term. No model judge, title match, keyword rule, mode flag or cache grants wider rights. An unknown operation or resource classification refuses.

Each pending human interaction records:

  • fresh unpredictable local nonce; authenticated principal and initiating interface binding;
  • direction, machine/address, connection generation, allocation generation and prompt identity;
  • peer session/call IDs, exact offered option IDs with semantic kinds, and canonical operation/resource digest;
  • creation time, fixed expiry and a single-use consumed state.

The UI shows the requested operation, target, once/persistent scope and consequences, and returns the nonce with the exact selected option ID. Commit atomically rechecks freshness, ownership, capability, ceiling and scope, consumes the nonce and records the selection sent on the wire. A once-only grant offered only a persistent allow answers cancelled; nothing widens, invents a once ID or reads denial into unknown vocabulary. Initial managed profiles permit only once grants; persistent options show as unavailable.

With a usable transport, a missing UI route, delivery error, expiry, cancellation, transport loss or flag-off settles the permission as cancelled. A duplicate or stale UI response after completion has no wire, audit or effect; the original selected/cancelled result stands. Invalid input before the first completion may settle it as cancelled once. Transport failure leaves delivery unknown, not approved. Human text inside a model message is not a UI response. Logs carry no secrets, full prompts, environment values or credentials; receipts hold scoped identities, typed reasons, digests and monotonic durations. Private request IDs are never spoken.

Outbound interactions route to the operator’s Pi UI bound at invocation. Inbound requests route over the client’s ACP connection only when the launch or registration establishes the initiating human interface; owning the connection does not prove a human. An automated client has no escalation route. A machine or principal change needs a new session.

A default-off unattended approval flag uses its own preauthorized scope. It never fabricates a human response, widens the intersection or changes the semantics above.

Managed child loadouts

A named loadout defines effective argv, model/provider, tools/extensions, workspace roots, writable scratch, isolated HOME/state, allowed environment keys, credential references, executable/process bounds and network destinations. The child inherits no ambient environment, user extension discovery, login-shell PATH, SSH agent or gateway credentials. Pi extensions are selected explicitly; caller overrides intersect policy. Child loadouts have no ACP delegation: depth is one edge, and invocation lineage rejects inbound/outbound re-entry.

Only explicit model-provider destinations and role-scoped credentials are admitted; the real user HOME is never an implicit auth source. Credential preparation is outside model control, and diagnostics carry no secret. Downloads, installation, self-update and model loading are operator actions, never handshake capabilities.

Filesystem enforcement covers parent/symlink replacement and subprocess access, not only canonicalize-then-open. Terminal and filesystem callbacks each recheck capability, ownership, path/resource scope and budget, and a denied delegated read or write stays denied. The same ceiling binds child-native tools. Without platform enforcement that denies raw escape routes, platform_profile is unavailable and no managed child starts. The macOS mechanism is not yet chosen; profiles alone do not confine Pi.

Attached agents are labeled external profile, not managed confinement. Only bridge operations are constrained. A request that needs the managed guarantee refuses attached mode.

Herdr attachment and cross-host callbacks

Discovery, observation, authenticated transport and exclusive writer acquisition are four separate steps. A record binds fleet machine, hc terminal address, provider session, connection/allocation generations and a fencing token from the authoritative owner. Labels and PIDs are evidence inputs, never a lock. Takeover is explicit, revokes the old owner and cannot replay its pending sends.

A callback stays on the allocation’s duplex ACP stream. For an attached remote agent, the provider bridge on that host binds it to the same session and fenced writer and carries it over the authenticated herdr machine route. A local hook path or env variable is not a cross-host channel, and no HTTP listener, raw ssh, terminal scraping or unguarded keys stand in. Without a demonstrated hc/provider primitive, that attachment capability is unavailable.

On severance, snapshots are readable with their age; mutations and approvals refuse before send. An ambiguous send stays dispatch_unknown and never replays. Cancel targets only the captured allocation. Detach drops our writer and transport only; shutdown never closes or kills the user’s existing agent. Voice remote close/kill stays forbidden.

Lifecycle, drain and uncertainty

Each direction moves off → starting → ready → draining → off; a startup failure returns to off. Admission checks the current generation atomically with the reservation, before any effect. Flag-off linearizes at the admission fence: it invalidates callbacks before teardown begins, so a concurrent approval cannot commit afterward.

Each prompt records four facts separately:

  1. dispatch: not_sent | sent | dispatch_unknown;
  2. local response: pending | returned (exactly once);
  3. remote prompt: running | settled | unknown;
  4. execution: active | quiescent | unknown.

agent_end may precede a Pi retry; only agent_settled settles the Pi prompt. A remote agent’s prompt response is a settlement claim, not proof its subprocesses stopped. Cancel acks, EOF, timeout, synthetic canceled results and a dropped task future are not quiescence. The prompt/admission permit is held until settlement or verified owned teardown, even after a local timeout.

Drain closes admission, revokes pending grants, cancels active prompts and waits within the fixed deadline. Managed children then get TERM, then KILL, only under verified allocation/birth ownership, with reaping and descendant accounting. Attached agents are detached, never killed; unsettled work stays unknown. Stale identity or unproved cleanup records cleanup_unknown, keeps the capacity reservation and needs reconciliation. The outcome survives a supervisor crash; a missing ledger record never means idle.

Before OS spawn, the allocation, capacity and terminal-record space are reserved durably under a unique launch intent. A platform-qualified launch gate holds the child from provider, model or tool effects until its birth identity and containment handle are bound to that intent. Recovery tells intent-before-spawn, spawn-before-identity-bind and bound-child-before-first-write apart. A platform that cannot recover or contain a child in that window has no managed launch. Reconciliation uses only the captured allocation and containment/birth evidence, never a PID or name scan. An unreadable, corrupt or missing journal refuses admission.

Before the first protocol write, dispatch intent is journaled with space reserved for its terminal outcome. Dispatch, write and ack are separate facts. Startup reads unresolved records before admitting work. A full journal refuses new work and never evicts unresolved records. Resolved entries may be pruned; unresolved ones need verified reconciliation or an operator disposition that records the uncertainty. An ambiguous mutation is never retried automatically.

Installation admission ownership

One installation is the operator-configured state root and its authenticated owner, shared by every adapter process on that host; callers cannot pick another root. One logical admission authority owns transactional durable reservations under it, serializes across OS processes and fences stale generations. It is local accounting, not a fleet plane or listener. After authority loss, no reservation is reused until recovery reconciles it. If authority or storage is unavailable, new work refuses. Both-off runs no admission worker and no polling.

A connection is reserved before an outbound provider launches or an inbound decoder, queue or handler is allocated. Refusal exits or closes without a session or provider child. The quota bounds admitted adapter work, not processes a user launches; a rejected entrypoint uses only bounded state and exits. Pre-initialize and sessionless connections share the installation connection cap. Connection memory is freed on verified local teardown; prompt and child reservations stay held, and reclaiming a connection proves no remote settlement. Handshake and sessionless idle expiry never reset on notifications or repeated initialize.

Initial design limits

Conservative defaults, not measured capacity. Limits compose across both roles. Lower overrides are allowed; raising an installation ceiling is an operator policy edit and needs requalification. Zero, negative, non-finite and unknown values refuse configuration.

Bound Default Exhaustion behavior
Connections per installation, including pre-session 8 Cross-process reservation before decoder/queue allocation; immediate refusal, no wait queue
Initialized sessionless connection idle deadline 30 s Close unless a session is admitted; starts at initialize completion, not reset by traffic
Sessions / owned children / active prompts per installation 4 / 2 / 2 Reserve atomically before spawn/write; immediate busy refusal, no waiting admission queue
Active prompts per session 1 Busy until settlement/verified teardown, including after local timeout
Pending outbound requests / inbound reverse handlers per connection 16 / 8 Busy or close for unbounded unsolicited work; no detached uncapped tasks
Pending human interactions 1 per session, 4 total Cancel excess; reserve before UI publication
Frame bytes / decoded depth / decoded nodes 1 MiB / 32 / 65536 Reject before unbounded allocation; close malformed/oversize stream
Data event queue per connection 128 entries AND 4 MiB Bounded backpressure with deadline, then cancel/close; never drop semantic events silently
Control reserve per connection 16 entries AND 64 KiB Separate from data; exhausted control channel closes rather than deadlocks cancellation
Streamed output per prompt / stderr tail per child 8 MiB / 64 KiB Output limit cancels; stderr ring retains bounded redacted diagnostics
Terminals per session / total 2 / 4 Reserve before create; descendants share child enforcement budget
Child process memory / descendants 512 MiB / 16 Host enforcement required; no profile readiness without it
Handshake / write stall / ordinary RPC deadline 10 s / 5 s / 30 s Includes queue wait; prompt and permission RPCs use their specific deadlines below
Prompt absolute deadline / human interaction expiry 300 s / 60 s Fixed, not reset by updates, retries or in-flight UI; human wait counts toward prompt deadline
Drain / TERM grace inside drain 10 s / 2 s Owned escalation only; deadline returns unknown if not verified
Resolved tombstones per connection 256 Never reuse a request ID within the connection generation; old/unknown reply cannot affect a new request
Journal 1024 records AND 8 MiB, reserve terminal space before send Unresolved records never evicted; admission stops before either cap
Resolved retention / delegation depth 7 days / 1 edge No recursive child delegation; no automatic expiry of unresolved records

A permission RPC expires at the earlier of interaction creation + the configured human expiry (60 s by default) and the parent prompt’s absolute deadline, including queue/UI delivery time; it is exempt from the ordinary 30 s RPC timeout, not from the 5 s write-stall limit. At the deadline, expiry wins over a concurrent selection. No peer notification, retry or UI activity extends either deadline.

Retained maps, mailboxes, promise/event chains, timers, reverse callbacks and replay buffers all count toward these budgets. Filesystem reads, prompt content and terminal output share the frame and output bounds. The control reserve does not admit unlimited cancellation frames.

Was this page helpful?