# Runtime `aip-runtime` owns reusable in-process services for sessions, capabilities, action lifecycle, event streams, idempotency, escalation, audit, settlement state, and lease-aware queued work execution. It has no dependency on product connectors. ## Services | Service | Purpose | |---|---| | `SessionManager` | creates sessions and validates lifecycle transitions | | `DiscoveryService` | stores manifests and capability lookup metadata | | `IdempotencyStore` | returns cached results for replay-safe action keys | | `EventLog` | append-only event stream with cursor reads | | `LifecycleStore` | stores stream chunks, results, cancellations, escalations, conversations, receipt chains, audit events, and settlement batches | | `DelegationStore` | stores parent-child delegation graph edges and terminal delegation results | | `TransactionStore` | stores transaction and saga records, captured identity context, plans, terminal outcomes, and recoverable records | | `ActionQueue` | stores queued/running async actions, worker leases, and terminal results for restart recovery or worker execution | ## Action Path 1. Gateway receives an `Action` envelope. 2. Runtime checks idempotency. 3. Runtime resolves the target capability from discovery. 4. Runtime authorizes the caller through `aip-auth`. 5. Runtime dispatches to a registered `ActionHandler`. 6. Runtime stores idempotent results when a key is present. 7. Gateway returns an `ActionResult`. For `ActionMode::Async`, runtime validates the same capability, policy, and handler preconditions, returns an `Ack` with `queued` status, and executes the handler on the background scheduler. Terminal results are recorded in `LifecycleStore`, settled in `ActionQueue`, and dispatched to the action callback when one is present. Retryable failures are not recorded as terminal lifecycle results; the runtime stores `next_attempt_at` and continues the same action through a targeted leased retry path until it either succeeds, exhausts the retry budget, or enters the dead-letter queue. `RuntimeStores::durable_local` persists the async queue in `queued_actions.json`. On startup, embedders can call `recover_queued_actions` to replay queued or running actions through the same authorization, idempotency, handler, lifecycle, event, and callback path. `aipd` performs this recovery during daemon startup after registering built-in and connector handlers. `Runtime::recover_runtime_state(RuntimeRecoveryConfig)` is the unified restart entrypoint for protocol runtimes. It returns a `RuntimeRecoveryReport` covering pending approvals, recoverable transaction or saga records, queued action replay results, and running delegation recovery results. Lower-level recovery methods remain available for embedders that need to recover one category at a time, but production supervisors should prefer the report when they need a single auditable recovery artifact. For horizontally scaled workers, embedders can call `Runtime::run_queued_action_once(worker_id, lease_ttl_ms)`. The runtime claims one queued or expired action through `ActionQueueBackend::lease_next`, executes the registered handler, records lifecycle state, settles or dead-letters the queue record, emits `aip.action.worker_result`, and dispatches the callback. Retryable failures are rescheduled before terminal lifecycle settlement, and future retry windows are not leaseable until `next_attempt_at`. `Runtime::run_queue_worker_until_idle(QueueWorkerConfig)` is the standard finite worker drain for daemons and test harnesses. It repeatedly calls the same lease-aware path, sleeps between idle polls, honors retry windows, and returns a `QueueWorkerReport` with claimed attempts, terminal results, retry scheduling, failed attempts, and worker errors. The method is intentionally finite so process supervisors own shutdown, backpressure, and long-running loop policy. When a supervisor already knows the action to resume, it can use `Runtime::run_queued_action_by_id_once`; the claim is still atomic through `ActionQueueBackend::lease_action`. Backends must make `lease_next`, `renew_lease`, and `release_lease` atomic for their storage technology. The built-in file backend is single-host durable. `aip-storage-postgres` is the reference multi-process implementation and uses database transactions, row-level coordination, compare-and-set transitions, and durable queue state. Additional database or queue backends must preserve the same lease, fencing, retry, idempotency, and recovery contracts rather than only persisting serialized records. ## Transaction Path Transactional actions use `Action.transaction` and, when routed as first-class messages, `TransactionRequest` / `TransactionResult`. `DryRun` with `SchemaOnly` or `PolicyAndSchema` fidelity returns a runtime preview without handler execution. `DownstreamValidation` and `FullSimulation` dry-runs are sent to the registered handler with the dry-run transaction context and are recorded as dry-run transaction evidence without lifecycle commit. Action-level dry-runs that omit a transaction id are normalized with a generated `TransactionId` before preview, handler dispatch, and durable evidence persistence, so every dry-run record remains addressable and correlation-safe. `Plan` produces a typed `TransactionPlan` rather than opaque metadata. The plan captures the plan id, transaction id, action and capability binding, canonical plan-input hash, side effects, approval policy, compensation metadata, identity snapshot, and commit requirements. `Commit` must reference a known planned record and is rejected before handler execution if the capability, transaction id, input hash, tenant, or external-account identity no longer matches. `Compensate` checks that the target action completed, consults durable transaction records when they exist, enforces the compensation window, and then routes execution to the declared compensation capability. ## Delegation Path `DelegationRequest` creates a durable graph edge from a parent action to a child action. Runtime verifies that the requester matches the envelope actor, appends a delegation chain entry to the child action, and stores the edge before any execution starts. Runtime then asks its configured `DelegationRouter` whether the request should be sent to a remote peer. A router can settle the delegation by returning a `DelegationResult`; otherwise the runtime falls back to local handler execution as the delegate principal. Synchronous child actions return a terminal `DelegationResult`. Asynchronous child actions return a non-terminal `running` result, remain open in `DelegationStore`, and are settled by the background scheduler when the child handler completes. The final result includes a hash-linked `delegation_made` receipt chain. Runtime also emits `aip.delegation.requested` and `aip.delegation.completed` events so gateways and operators can inspect multi-agent workflow progress independently of the final result payload. When stream chunks are recorded for a delegated child action, runtime annotates the lifecycle event with `delegation_id` and `parent_action_id`. This lets parent workflows and observers correlate streaming child progress without parsing product-specific connector payloads. On startup, embedders can call `recover_running_delegations`. Recovery replays persisted `running` graph edges through the router first and then through local execution. Deployments should pair recovery with child action idempotency keys when remote peers may receive the same delegated request more than once. ## Lifecycle Path Non-action messages are also first-class. Heartbeats, cancellations, stream chunks, human escalation, channel messages, audit events, receipts, and settlements are stored or converted into event stream entries. This keeps the protocol useful for long-running multi-agent workflows instead of limiting the runtime to request/response tool calls.