ACP provider registry
Unshipped declaration codec, not an installed configuration interface or readiness proof. It describes provider bindings for acp-integration.v1, not another tool catalog.
Living doc, checked against the code 2026-11-14
acp-provider-registry.v1 — bounded operator declarations before ACP provider admission
Unshipped declaration codec, not an installed configuration interface or readiness proof. It describes provider bindings for acp-integration.v1, not another tool catalog. Tool exposure belongs to the tool index, its policy and the vulpine-tools Pi door. No provider is available yet, and nothing is installed or activated.
ProviderRegistry::decode in the Unix Rust boundary accepts explicitly supplied operator bytes. It has no file
loader, config path, PATH scan, executable probe, credential resolver, process, network listener, tool registration
or model call. Absent input gives an empty registry; malformed input refuses. A new snapshot is built completely or
refused, and the existing snapshot is never modified. Decoding never creates, resets or replaces installation
authority state.
Encoding and bounds
The root is a strict JSON object with schema: "vulpine.acp.providers.v1" and a required providers array; empty is
valid. A snapshot holds at most 1 MiB and 64 entries. JSON depth and node bounds are 32 and 65536. Duplicate JSON keys,
unknown fields at any typed level and duplicate provider IDs refuse. The 64-entry bound limits declaration memory; it
does not raise installation admission ceilings.
Each managed declaration requires:
| field | meaning / validation |
|---|---|
id |
1–64 ASCII characters, lowercase initial letter, then lowercase letters/digits/underscore/hyphen |
version |
1–64 ASCII letters/digits/dot/underscore/plus/hyphen; an adapter version label, not an observed executable version |
provenance |
review_sha256 digest reference and nonblank printable ASCII license declaration up to 128 bytes; not publication clearance |
exec, sha256, argv |
Absolute executable declaration up to 1024 bytes, no control characters or lexical dot/parent components; expected digest; at most 32 literal arguments, each at most 1024 bytes, at most 16 KiB total, no NUL |
roles, protocol_version |
Nonempty, unique outbound_client / inbound_agent; stable protocol version 1 |
capabilities |
Bounded, unique operation declarations described below |
loadout_id, loadout_digest |
Mandatory named managed-child loadout and expected digest |
platform_profile |
id, sha256, optional qualification_receipt digest reference |
limits |
Required positive integer lower ceilings described below |
authentication |
Required credential_refs array, at most eight unique identifiers; optional human_interface_ref identifier; never literal credential values |
attachment |
Absent/null only in this codec; a nonnull request refuses explicitly as unsupported |
Loadout, profile and authentication identifiers use the id syntax. Every digest is exactly 64 hexadecimal
characters and nonzero. Receipt references are claims: decoding never locates, authenticates or assesses the artifact.
The executable is neither opened nor hashed, so a nonexistent absolute path is a valid declaration but never
runnable. Arguments are literal, not shell commands or templates: $HOME stays literal.
limits accepts only frame_bytes (up to 1048576), output_bytes (up to 8388608), prompt_timeout_ms (up to
300000) and human_timeout_ms (up to 60000). Zero, negative, fractional, unknown or larger values refuse. Lower
values are retained; no running actor applies them yet. No other installation ceiling can be overridden here.
Capability declarations are not capabilities
Each capability has operation, implemented (an operator declaration), negotiation (baseline or
conditional) and an optional qualification_receipt. Six baseline declarations are mandatory, each claiming
implemented with baseline negotiation: initialize, session/new, session/prompt, session/update, session/cancel and
session/request_permission. The check sets a floor; it does not prove the implementations work.
The optional vocabulary is authenticate, session/load, fs/read_text_file and fs/write_text_file, each with conditional negotiation. Any other operation refuses. Declaring an optional operation does not advertise it on ACP.
discovery() returns only ID, version label, declared roles and Unqualified availability, even when every
receipt reference is supplied. It exposes no executable path, arguments, credential references or human-interface
reference. Debug output is redacted, and errors carry closed categories, never input content.
No declaration enables a role, mints a session identity or authority token, satisfies platform confinement, authenticates a human or authorizes a callback. Readiness stays implemented ∩ enabled ∩ authorized ∩ negotiated ∩ qualified. Model and peer arguments are never the operator configuration source.
Canonical identity and outbound bootstrap
A validated entry exposes registration_digest(): SHA-256 over the UTF-8 domain separator
vulpine.acp.provider-registration.v1, a zero byte, then canonical compact JSON of the complete typed declaration.
Object keys sort recursively. Absent or null optional fields serialize as explicit null. Roles and credential
references are sorted sets; capabilities sort by operation. Digest strings normalize to lowercase. Argument order
and all other literal values remain significant. Hashing reads no referenced executable or receipt.
OutboundBootstrap checks the managed/outbound role, canonical provider digest, executable/loadout identity,
nonempty invocation digests, positive generation, workspace and one-edge lineage before host preparation. The
installation store and invocation scope come from the trusted operator integration, never from tool or peer
arguments. Disabled durable policy refuses before preparation. The OutboundHost seam defaults to Unavailable; its one
native implementation, NativeProviderHost, is not installed. The bootstrap refuses nondefault lower limits until the executor enforces them.
One start attempt reserves a session, enters the gated launch, keeps the captured child and queues initialize on the
sole ACP writer. A correlated initialize reply and a session/new exchange still follow. into_parts() hands the
executor, host and partial session/capture state to a carrier. A failed or ambiguous start cannot be retried, and a
missing capture never proves that no child exists.
Captured duplex polling
OutboundCarrier consumes a fresh bootstrap handoff without another admission. It owns the original host and
executor and one 16 KiB input staging buffer. Each poll performs at most one nonblocking write, one read and one
protocol-record ingestion. Semantic updates pause reads until consumed. A permission callback stays backpressured
until the trusted interpreter binds it. Every read and write rechecks the durable identity facts in the same
transaction.
Correlated initialization leads to exactly one session/new request. Session setup has a fixed 30-second deadline that
no partial progress renews. EOF, malformed input, target mismatch and ambiguous writes stop the stream and keep the
uncertainty. into_recovery() returns the original host, closed executor and any persistence error. No concrete
native verifier ships.
Graceful control handoff
On disable, the supervisor calls DirectionalDrain::disable, then begin_drain on each ready carrier before any
normal poll, then poll_drain: at most one captured write, no reads, no new prompts or permissions. The five-second
queued-write bound and the ten-second directional deadline apply. A None pump result means only that the carrier
queue is flushed.
Allocation-scoped teardown
DirectionalDrain::tick_managed_allocation advances only the selected retained managed allocation with its original
host, after validating installation, epoch, direction, generation, ownership and clock. An invalid selector cannot
advance the drain clock. Progress stays installation-wide: one child’s completion never reports Complete while another
allocation is pending, and missing hosts stay unresolved.
Retained outbound controller
OutboundController takes a fixed batch of at most two captured carriers. Each round visits every slot once and
rotates the first slot; a failure closes only its slot. Disable schedules flush/local-close and scoped teardown on
different rounds. The driver ticks on readiness and on next_wake, a ten-millisecond watchdog capped by the remaining
drain deadline. Missing hosts stay Pending, or report CleanupUnknown after the original deadline. No slot is recycled.
Typed trusted command/event seam
OutboundController::control accepts Submit, Cancel, NextEvent and Status with a host-supplied
ControllerInvocation: the original SessionScope and a fresh DelegationLineage. It has no wire decoder and is
never built from model or peer arguments. Every command first validates epoch, generation, time, direction, actor,
identity, session binding and captured birth. NextEvent transfers at most one retained update, permission callback or
completion, in that order. bind_control_permission and deliver_control_permission create no human route or grant.
Revoked, draining or recovered actors refuse all access.
Effect invocation lifetime preparation
catalog/pi/extensions/vulpine-tools/acp/invocation.ts is an unregistered, provider-optional Effect adapter. It
installs no binding, endpoint, tool or listener. It rejects extra authority or address fields with Schema, permits one
in-flight call with no queue, and retires on protocol failure, uncertainty, interruption or lifecycle invalidation.
Flag-off and session replacement discard late replies.
OutboundController::control_record decodes at most 256 bytes per status/cancel or streamed submission record. It
rejects duplicate or extra keys, unknown operations, bad UTF-8 and selectors outside 0–1. Cancel returns
requested: true, not queued.
Owned native caller connection
NativeCaller is an inactive macOS/Linux implementation. It keeps an accepted Tokio UnixStream and borrows the host’s
original caller Child; kernel peer PID/UID/GID must match that live child and the non-root host. One exchange uses a
monotonic sequence/length header, one nonblocking read or write per poll, a fixed 30-second exchange limit and a
5-second reply window. NativeHost adds uninstalled startup and intake under the same 30-second deadline.
start_bootstrapped adds a private FD3 launch capability with a nonce/HMAC host proof; Bun is refused. No launcher,
listener, SDK hook or native binding is installed.