Gateway

aip-gateway is the composition boundary between native envelopes, runtime services, profiles, transports, and connectors. It remains a library crate so it can be embedded by aipd, tests, and product-specific host processes.

Responsibilities

• Accept native Envelope values.
• Negotiate handshakes and session creation.
• Return local manifests.
• Dispatch actions through aip-runtime handlers.
• Register outbound connectors and wire their capabilities into runtime handler routing.
• Route first-class delegation requests to configured remote peers.
• Route every native message family into lifecycle stores.
• Deliver asynchronous callbacks over native HTTP, native NATS, or in-process SSE.
• Convert runtime failures into typed AIP error envelopes.
• Preserve session and correlation metadata on responses.

aipd exposes the same gateway over native HTTP and, when configured, native NATS request/reply. It also exposes MCP and A2A compatibility ingress endpoints. Those endpoints translate profile DTOs into native envelopes before calling aip-gateway; they do not duplicate capability execution or lifecycle semantics.

When --storage-dir or AIPD_STORAGE_DIR is configured, aipd constructs the gateway with file-backed runtime stores for sessions, idempotency, event log, lifecycle state, and delegation graph state. Without that option the daemon remains ephemeral and uses in-memory stores.

Remote delegation routes are selected by delegate principal and/or child capability. Native HTTP routes post a DelegationRequest envelope to a peer endpoint and expect a DelegationResult envelope in response. Native NATS routes use request/reply on the configured subject. If no route matches, runtime falls back to local delegate execution.

Connector registration is also centralized at the gateway. A CapabilityProviderConnector contributes its manifest to discovery, every published capability is registered as an ActionHandler, and the connector is stored in the gateway registry for operator inspection and future routing extensions.

Native Message Routing

Message family	Gateway behavior or response
Handshake	Authenticates the declared client, negotiates profiles and capabilities, creates a session, and returns HandshakeResponse
ManifestRequest	Filters and returns the local Manifest
Manifest, HandshakeResponse	Validates or records the remote observation and returns EventStream
Action	Returns terminal ActionResult or queued Ack from the runtime scheduler
Action status, result, list, and event requests	Authorizes the query and returns the corresponding operational view
Action status, list, and event responses	Records the remote observation and returns EventStream
Session view, list, close, and resume requests	Authorizes and executes the requested session operation
Session view, list, and resume responses	Records the remote observation and returns EventStream
DelegationRequest	Validates the target and returns local or authenticated remote DelegationResult
DelegationResult	Authenticates and settles the stored delegation graph, then echoes the settled result
TransactionRequest	Executes plan, dry-run, commit, compensate, or reconcile and returns TransactionResult
Transaction query requests	Authorizes and returns TransactionView or a typed error
Transaction results and views	Records the remote observation and returns EventStream
ApprovalRequest, ApprovalDecision	Persists the policy lifecycle transition and returns EventStream
Approval query and list requests	Authorizes and returns approval records or lists
Approval records and lists	Records the remote observation and returns EventStream
Callback delivery query and list requests	Authorizes and returns durable outbox records or lists
Callback delivery records and lists	Records the remote observation and returns EventStream
Cancel	Cancels eligible action or session work and returns its runtime response
Heartbeat	Returns HeartbeatAck; received acknowledgements become observations
StreamChunk, Ack, ActionResult, Error	Ingests or records lifecycle state and returns EventStream
Escalation, EscalationResolution	Persists escalation lifecycle and returns EventStream
EventStreamRequest	Authorizes and returns a cursor-filtered EventStream
Received EventStream	Records the observation and returns its recorded EventStream
ChannelMessage, Conversation	Persists channel lifecycle and returns EventStream
ReceiptChain, AuditEvent, BatchSettlement	Validates and stores the payload, then returns the stored payload
Receipt, audit, and resource queries	Authorizes and returns the matching records, list, or resource result
Received audit/resource query results	Records the remote observation and returns EventStream

The gateway does not own product DTOs. Product-specific translation belongs in connector crates; profile-specific translation belongs in profile crates.