Crate a4aa 

a4aa — Adapter For All Agents

One crate owns every agent-client adaptation path a host needs:

• supervision — process-group spawn, full user environment inheritance with explicit overrides, bounded I/O, interrupt (SIGINT→grace→kill) and tree teardown;
• discovery — discovery: the allowlisted machine scan engine — {token}-rooted location templates, a host-supplied or card-projected discovery::ScanManifest, deny/admission rules and bounded probes;
• hostenv — hostenv: the user’s login-shell environment a fidelity launch resolves from (the GUI session’s environment is not the user’s);
• transports — piped stdio, Unix PTY (raw slave, streaming master), WebSocket and batch-only SSH remote spawn;
• lanes — proto::acp (official agent-client-protocol crate), proto::rpc (host-declared JSON-RPC methods), proto::cli (argv/stdin prompt, streamed output);
• runtime contracts — runtime: the host-neutral port vocabulary a composing host answers — provider identity, capability-evidence reducers, opaque session bindings, dispatch receipts and the caller-registration and target-runtime traits — plus protocol_selector, the evidence-reduction engine that pins one attempt to one protocol immutably;
• facade — Adapter produces a lane-erased AgentSession;
• sidecar — the a4aa serve binary speaks a4aa.v1 NDJSON-RPC on its own stdio, so hosts in any language reuse the identical adapters by spawning this crate.

Design invariants:

• Zero-assumption output. No lane forces a schema onto agent output; natural language is a valid turn result.
• Fail closed. Unknown inbound requests are rejected, unresolved secrets and unset permission handlers never grant.
• Explicit cancellation only. Cancel signals reach the agent solely from a caller’s cancel(); a dropped observer or transport error is never rewritten as user cancellation.
• Bounded resources. Output caps drain-and-discard; a chatty agent can never exhaust host memory or stall its own pipes.

Re-exports

pub use adapter::Adapter;

pub use adapter::AgentSession;

pub use adapter::BeforeTurn;

pub use adapter::LaneSession;

pub use adapter::PermissionHandler;

pub use adapter::TurnRequest;

pub use card::AgentCard;

pub use card::AgentSurface;

pub use card::AlternateLane;

pub use card::AttachmentSupport;

pub use card::CliSurface;

pub use card::CompletionDecl;

pub use card::DetectSurface;

pub use card::FeatureSurface;

pub use card::InstructionChannel;

pub use card::LiveUsage;

pub use card::ModelCatalog;

pub use card::OsPath;

pub use card::RpcCallDecl;

pub use card::RpcMcpDecl;

pub use card::RpcSurface;

pub use card::UsageSurface;

pub use dialect::adapt;

pub use dialect::CommandSurface;

pub use dialect::Dialect;

pub use dialect::McpSurface;

pub use dialect::PermissionSurface;

pub use dialect::PluginSurface;

pub use dialect::SubagentSurface;

pub use dialect::Target;

pub use discovery::DenySpec;

pub use discovery::HistoryScanRoot;

pub use discovery::HostRoots;

pub use discovery::ScanManifest;

pub use env::EnvPolicy;

pub use env::EnvSource;

pub use env::EnvValue;

pub use env::NoSecrets;

pub use env::SecretResolver;

pub use error::AdapterError;

pub use error::Result;

pub use hostenv::ShellEnvironmentStatus;

pub use mechanisms::AdaptationPlan;

pub use mechanisms::Artifact;

pub use mechanisms::ArtifactScope;

pub use mechanisms::CommandDecl;

pub use mechanisms::MechanismSet;

pub use mechanisms::PermissionDecl;

pub use mechanisms::PluginDecl;

pub use mechanisms::RuleDecl;

pub use mechanisms::SkillDecl;

pub use mechanisms::SubagentDecl;

pub use mechanisms::Support;

pub use mechanisms::SupportEntry;

pub use mechanisms::WriteMode;

pub use model::AgentEvent;

pub use model::AgentInfo;

pub use model::AgentSpec;

pub use model::BindingReceiptShape;

pub use model::Capabilities;

pub use model::CliLaneSpec;

pub use model::CommandSpec;

pub use model::LaneKind;

pub use model::LaneSpec;

pub use model::PromptChannel;

pub use model::RpcCallSpec;

pub use model::RpcCompletionSpec;

pub use model::RpcEnvelopeSpec;

pub use model::RpcLaneSpec;

pub use model::RpcMcpConfig;

pub use model::RpcMcpToolApproval;

pub use model::RpcTransport;

pub use model::SelectorPhase;

pub use model::SelectorSupport;

pub use model::SelectorSupportSet;

pub use model::SessionConfig;

pub use model::SessionRequest;

pub use model::SessionScope;

pub use model::StreamMode;

pub use model::TurnOutcome;

pub use native::cell;

pub use native::parse_iso_date;

pub use native::AwpPrimitives;

pub use native::Cell;

pub use native::ConfigLocations;

pub use native::InteractionSurfaces;

pub use native::McpMechanism;

pub use native::McpRegistration;

pub use native::NativeCapability;

pub use native::NativeStatus;

pub use observe::Direction;

pub use observe::Observer;

pub use observe::SharedObserver;

pub use proto::acp::PermissionDecision;

pub use proto::acp::PermissionPrompt;

pub use proto::acp::SessionDelegate;

pub use proto::rpc::RpcSessionDelegate;

pub use rpc::CallFailure;

pub use rpc::JsonRpcPeer;

pub use rpc::RpcDelegate;

pub use rpc::RpcErrorObject;

pub use runtime::reduce_execution_admission;

pub use runtime::reduce_readiness;

pub use runtime::AdapterFailure;

pub use runtime::CallerRegistrationPlan;

pub use runtime::CallerRegistrationReceipt;

pub use runtime::DurableNativeBinding;

pub use runtime::ExecutionAdmissionDecision;

pub use runtime::ExecutionAdmissionEvidence;

pub use runtime::InstructionPolicy;

pub use runtime::McpCallerIntegration;

pub use runtime::NativeResumeIdentity;

pub use runtime::PersistentTurnRuntime;

pub use runtime::ProviderId;

pub use runtime::ReadinessDecision;

pub use runtime::ReadinessEvidence;

pub use runtime::RegistrationApproval;

pub use runtime::RuntimeDispatchReceipt;

pub use runtime::RuntimeDriver;

pub use runtime::RuntimeDriverRegistry;

pub use runtime::RuntimeEventPart;

pub use runtime::RuntimeObservation;

pub use runtime::RuntimeTransition;

pub use runtime::SubagentCapabilities;

pub use runtime::SubagentContinueRequest;

pub use runtime::SubagentDispatchRequest;

pub use runtime::SubagentRuntimeAdapter;

pub use supervision::IoPlan;

pub use supervision::StdioKind;

pub use supervision::SupervisedChild;

pub use transport::ssh::SshRemote;

pub use transport::ssh::SshRemoteError;

pub use acop as context;

Modules

adapter

The unified adapter facade.

bounds

Bounded I/O helpers.

card

AgentCard — the complete per-agent descriptor an a4aa-<agent> crate exports.

dialect

Agent dialects: the descriptor per-agent crates declare, and the engine that adapts semantic MechanismSets onto them.

discovery

Allowlisted agent discovery on the host machine.

env

Agent process environment policy.

error

Typed adapter failures.

framing

Newline-delimited JSON framing.

hooks

hostenv

The host user’s login-shell environment.

mcp

MCP server declarations carried by a lane spec, and their translation into protocol-native registration surfaces.

mechanisms

Mechanism declarations and adaptation plans — the dialect-free contract.

model

Provider-neutral adapter model.

native

Native-capability tables: the reviewable, machine-checkable record of what each agent offers natively, what A4AA adapts, and what is still missing or reached through a non-native mechanism.

observe

Raw wire observation hooks.

proto

Protocol lanes: concrete ways to drive an agent over a transport.

protocol_selector

Capability evidence reduction and immutable protocol selection.

route

Provider route and model resolution against the supplier’s declared surface, plus the endpoint probe a caller may run before trusting a configured model reference.

rpc

Bidirectional JSON-RPC 2.0 peer over NDJSON framing.

runtime

Host-neutral agent runtime contracts — the L4/L5 boundary a composing host answers.

supervision

Supervised agent processes.

transport

Byte transports to an agent process.

Structs

HistoryRoot

A declared location in an agent’s history surface — ACOP’s own vocabulary. acop-<agent> codecs fill it from the owning descriptor (today: the a4aa-<agent> card’s history); ACOP never hardcodes store locations itself.

HookDecl

One lifecycle hook: a shell command the agent’s hook store invokes.

TokenUsage

Token counters an agent reported for a turn or event. Every field is optional: an absent counter is absent data, never a zero.

TranscriptUsage

Token-accounting locations inside persisted records — the artifact half of a4aa’s UsageSurface (live-wire and hosted counters stay there). Declared facts only: a counter the agent does not report stays absent. A usage consumer reads sessions through decode plus this spec — it never needs a parallel store adapter.

Enums

ExtensionKind

Generated-code dialects for HookSurface::Extension.

HookEvent

Semantic lifecycle event a hook attaches to. Hosts write these names; each dialect emitter maps them onto the agent’s native event names or reports the item unsupported.

HookIntent

What a hook is for. Dialects that cannot implement the requested intent report Unsupported; generated extension observers accept only Notify. An observation-only callback must never claim to enforce or rewrite.

HookSurface

How an agent stores lifecycle hooks.

StoreKind

How a history root is physically stored.

UsageTemporality

Whether a counter reading is the change over its window or a running total since the series origin — the declaration a store owes so a consumer never has to guess which shape a field is.