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

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.

Was this page helpful?