Skip to main content

​
Agent Control Plane Invariants

Status: Enforced contract for Phase 1 control-plane changes Scope: Normative invariants and guard tests. Architecture, schema rationale, and rollout phases remain in agent-control-plane. Future PRs that touch desktop/macos/agent/src/runtime, adapter bindings, control tools, request-scoped relay state, or startup reconciliation should name the invariant they affect and update the matching guard test.

​
Identity

​
Omi IDs and adapter-native IDs are separate namespaces

session_id, run_id, attempt_id, binding_id, artifact_id, delegation_id, and grant_id are Omi-owned. Adapter-native session IDs are opaque adapter data and live only in adapter_bindings.adapter_native_session_id or explicitly named compatibility fields such as adapterSessionId and legacyAdapterSessionId. Guard surface:
  • assertAdapterBindingContract rejects adapters that return an Omi session ID as their native session ID.
  • assertAdapterAttemptResultContract rejects terminal results that conflate or drift away from the binding’s adapter-native ID.
  • runtime-adapter.test.ts pins both failure modes.

​
An Omi session ID does not change when bindings change

Adapter changes, stale native sessions, process restarts, and model or MCP compatibility changes create a new binding generation or attempt under the same Omi session/run as appropriate. Guard surface:
  • adapter_bindings.binding_generation is monotonic per session/adapter.
  • Binding compatibility hashes include cwd, system prompt, and the adapter-effective MCP server set.
  • run-attempt-lifecycle.test.ts and adapter-binding.test.ts cover stale binding retry, compatibility changes, and request-scoped MCP env stripping.

​
Session execution profiles are immutable generations

Every session resolves one persisted SessionExecutionProfile containing its adapter, credential scope, model profile, working directory, execution role, and generation. Global preferences create the profile for future sessions only. An explicit user migration must carry the expected generation, must run in one transaction, and must reject a session with an active run. Migration creates a new profile generation and stales prior adapter bindings; it does not restart the shared daemon or mutate the session ID. Guard surface:
  • session-execution-profile.ts owns default preferences and profile migration.
  • session-execution-profile.test.ts covers next-session defaults, stale generation rejection, active-run rejection, binding invalidation, and restart.

​
Workstream identity is the reusable task-work boundary

For durable task work, the kernel resolves surface_kind=workstream, external_ref_kind=workstream, and external_ref_id=<workstream_id>. All task views linked to that workstream reuse one local conversation per owner/runtime. Task IDs may remain compatibility surface mappings during migration, but they do not own independent agent continuity. Guard surface:
  • surface_conversations and the existing session external-reference index are the only binding mechanism; there is no parallel workstream binding store.
  • workstream-continuity.test.ts covers reuse, task-session migration, and shared artifact history.

​
Authority

​
Owner authority comes from active Omi context

The active owner for a control operation comes from the Omi request, run, or attempt context. Tool-supplied ownerId values are guards: they can reject a request, but they do not authorize it. Guard surface:
  • control-tools.ts rejects owner-scoped adapter-originated calls without active request, run, or attempt context.
  • kernel.ts validates session, run, attempt, and artifact selectors against the active owner.
  • control-tools.test.ts covers mismatched guards, cold direct control, and concurrent owner-scoped tool calls.

​
Request-scoped state is keyed by client and request

A bare requestId is not unique under concurrent clients. Request-scoped control and relay maps must use (clientId, requestId). Guard surface:
  • jsonl-transport.ts stores adapter request correlation by JSON.stringify([clientId, requestId]); the kernel never treats that map as a tool grant.
  • tool-relay.test.ts, control-tools.test.ts, and the external-surface authority tests cover concurrent clients, missing client IDs, and run-bound execution.
Request/client IDs are correlation only. Cancellation resolves the durable run and active owner in the kernel; it cannot derive authority from a matching request map or a caller-supplied owner.

​
Intent routing and control application are one kernel boundary

Surfaces submit a typed proposal and syntax facts to route_intent. The kernel returns a typed decision and atomically applies any required control action. Swift does not classify the same text, infer dispatch from keywords, or repair a decision with a second resolver. Guard surface:
  • desktop-intent-router.test.ts covers all surfaces, typed validation, deterministic syntax facts, and route-and-apply atomicity.
  • convergence-authority-ratchet.test.ts forbids the retired Swift classifiers.

​
Physical tool authority is run/attempt scoped and single use

The kernel’s capability reference is process-local input to authorization, not a bearer exported to Swift. Authorization re-reads durable owner, session, run, attempt, profile generation, role, and manifest policy. It then persists the invocation claim before emitting authorized_tool_execution to Swift. The ledger transition is prepared → dispatched → succeeded|failed. On daemon restart, prepared → failed and dispatched → outcome_unknown. A non-idempotent write has never_auto_retry; no result may be accepted unless it echoes the complete immutable claim tuple, input hash, and generated manifest digest. Ordinary adapter tool_use events are display-only in Swift. Guard surface:
  • run-tool-capability.test.ts covers revocation, owner/attempt/profile checks, replay denial, manifest policy, restart reconciliation, and exact result claims.
  • AuthorizedToolExecutionTests.swift covers the physical executor boundary and cross-language canonical input hash.

​
Conversation durability has one sequence owner

The kernel journal is the only canonical conversation writer. A record/update, its monotonic sequence revision, and any backend outbox row commit together. Swift may stage presentation immediately and perform owner-bound HTTP, but it cannot acknowledge, reorder, or durably mutate a turn. Backend chat is a rollback-readable mirror in the existing message format. It is also an event-triggered import feed for genuinely remote client turns. The kernel reads owner-scoped bounded pages, deduplicates stable remote and canonical turn IDs, and advances a durable ID frontier. It never uses a timestamp or offset cursor. Swift uses the additive desktop reconciliation endpoint, whose Firestore document-ID cursor is validated inside the authenticated owner and requested app/session filter; the rollback message shape retains client_message_id, structured metadata, and resources. The idle outbox timer never polls backend history. Guard surface:
  • conversation-journal.test.ts covers producer idempotency, ordered replay, owner-scoped delivery/deletion, paged remote import, restart, and exact claims.
  • KernelTurnRecordedProjectionTests.swift covers sequence projection and the single Swift physical sync boundary.
  • KernelJournalBackendReconcileTests.swift and backend desktop-migration tests cover exact cursor wire shape, insertion between pages, reported-row scans, canonical identity, and structured metadata.
  • convergence-authority-ratchet.test.ts forbids direct writers and timestamp reconciliation cursors.

​
Context snapshots are kernel-selected and pinned per run

Swift can update typed source data with a revision and one of available, empty, unavailable, or redacted. It cannot send a system prompt, model, cwd, surface prompt JSON, or capability policy in a query. The kernel builds a session-scoped ContextSnapshot with content version, monotonic generation, renderer-policy version/fingerprint, recent journal turns, explicit source outcomes, active runs, and a non-bearer capability projection. Admission pins the snapshot used by the logical run. Queue delay and retries do not rebuild it from newer sources. An A→B→A content sequence may reuse content version A but must have a higher generation. Voice socket refresh identity uses content version plus renderer/capability fingerprints, not the monotonic audit generation, so unchanged material does not churn a warm provider session. Guard surface:
  • session-execution-profile.test.ts covers source outcomes, renderer policy, A→B→A generation, irrelevant-source selection, and admission/dispatch races.
  • KernelContractWireTests.swift forbids request-supplied runtime authority.

​
Lifecycle

​
Exactly one non-terminal attempt per run has execution authority

Only one attempt with status queued, starting, running, waiting_input, waiting_approval, or cancelling may exist for a run. Guard surface:
  • The kernel refuses to create a second active attempt.
  • SQLite enforces run_attempts_one_active_per_run_uq, a partial unique index on run_attempts(run_id) for active statuses.
  • The migration that introduces the index repairs legacy duplicate active attempts by orphaning older attempts and writing attempt.orphaned events in the same transaction before installing the index.
  • sqlite-store.test.ts verifies the storage-level invariant.

​
Silence, disappearance, and UI dismissal are not success

Run completion is determined only by a terminal kernel state persisted by the control plane. Startup reconciliation marks active attempts orphaned; it does not infer success from process disappearance. Guard surface:
  • reconcileStartup() updates active attempts to orphaned, marks non-resumable active bindings stale, and creates recovery dispatches for interrupted delegations. It also repairs rows written during a one-release downgrade window (missing immutable profiles or journal sequence metadata) and terminalizes orphaned pending/streaming journal turns with a bounded observable repair code. Every repair is idempotent across repeated opens.
  • sqlite-store.test.ts and run-attempt-lifecycle.test.ts cover startup reconciliation and idempotent recovery dispatch behavior.

​
Cancellation acknowledgement is truthful

dispatchAttempted and adapterAcknowledged are separate. A cancelled run is terminally cancelled even if partial text exists. adapterAcknowledged remains false unless the adapter independently confirms cancellation or the worker is known terminated. Guard surface:
  • CancelDispatchResult carries both fields.
  • Adapter capability expectations mark acknowledgement gaps as known_limitation with follow-up ticket references.

​
Binding Compatibility

​
Compatibility is determined by stable kernel-effective inputs

The kernel hashes the pinned profile generation, kernel policy, working directory, and stable MCP server configuration to decide whether a binding is reusable. If an adapter mutates MCP servers before passing them to its native runtime, it must implement effectiveMcpServers so the hash reflects what the adapter actually saw. Guard surface:
  • stableMcpServerConfig strips request-scoped MCP env keys before hashing.
  • RuntimeAdapter.effectiveMcpServers documents adapter mutation behavior.
  • run-attempt-lifecycle.test.ts covers request-scoped env changes and adapter-stripped MCP sets.

​
Process-local bindings are pinned or stale

Bindings with resume_fidelity = 'none' must be pinned to their worker while active. On restart they become stale and cannot be treated as native-resumable. Guard surface:
  • The capability matrix requires pinnedWorker for process-local production adapters.
  • Worker-pool tests enforce one active attempt per worker and idle pinned-worker retention.
  • Startup reconciliation marks active non-resumable bindings stale.

​
Adapter capabilities are explicit

Every production adapter must declare required, unsupported, or known_limitation for every capability key. Known limitations need a follow-up ticket. Guard surface:
  • ADAPTER_CAPABILITY_MATRIX is the source of truth.
  • runtime-adapter.test.ts verifies production expectations and ticketed known limitations.

​
Adapter credential scope is explicit and inherited

Every production adapter declares managed_cloud or local_user in ADAPTER_CAPABILITY_MATRIX. Sessions persist a provider boundary when the kernel creates them. Managed sessions may select only managed-cloud adapters; local-user sessions are pinned to the exact selected local adapter. Missing adapter arguments inherit that boundary, while unknown adapters fail closed. Signed desktop control, and the canonical top-level spawn_agent tool’s explicit provider selector for Hermes or OpenClaw, may establish a fresh local-provider session or resume an existing session against its persisted boundary, even when the control bridge itself uses managed-cloud routing. An adapter ID alone may not use that exception, and neither may cross a parent run’s boundary or override an existing session’s adapter. For model-driven external surfaces, that selector is valid only when the current user explicitly names the exact provider. The external-surface policy normalizes a matching provider, strips an invented/stale/mismatched provider, and therefore defaults generic delegation to the managed Omi adapter before the kernel mints a child session. A signed desktop UI selection remains explicit user control and follows the same provider-boundary rules. Guard surface:
  • execution-policy.ts is the shared resolver used by control tools and the kernel run-acceptance path.
  • runtime-adapter.test.ts, execution-policy.test.ts, and control-tools.test.ts exhaust production declarations, managed routing, directed and signed top-level local-provider starts, and signed local-session resumption.
  • external-surface-authority.test.ts verifies generic PTT delegation cannot select a local provider while an explicitly named provider is preserved.

​
Execution role owns agent-management authority

Sessions persist coordinator or leaf. Background, delegated, and floating pill sessions are created as leaves. Leaf tool projections omit agent creation and continuation tools, while the control relay and kernel independently reject stale or forged calls for every leaf-restricted tool (including send_agent_message). The relay loads the caller’s persisted policy by session id with an owner check and fails closed when that lookup cannot complete; surface-derived role exists only in the creation/legacy migration boundary. Persisted kernel state is authoritative afterward. spawnBackgroundAgent requires a coordinator caller session or an explicit trusted-user spawn. Guard surface:
  • omi-tool-manifest.test.ts verifies leaf capability projection.
  • control-tools.test.ts verifies server denial for every nested creation and continuation entry point, plus kernel spawn authority checks.
  • sqlite-store.test.ts verifies role and provider-boundary persistence.

​
Required control failures cannot become successful runs

Required spawn, delegate, and continuation operations remain unresolved after failure until the same logical operation succeeds. Transport correlation and adapter-selection fields do not define logical identity, so a corrected retry can resolve the obligation; an unrelated successful operation cannot. Guard surface:
  • pi-mono-adapter.test.ts covers terminal failure, matching retry success, and unrelated-success denial.
  • The kernel remains the only component that persists run and attempt terminal state; adapter outcomes are inputs to that transition, not an alternate store.

​
Persistence

Lifecycle state transitions and their durable events should commit in the same SQLite transaction. New store paths must use AgentStore.withTransaction when they persist both a state transition and an event row. Startup reconciliation must be deterministic and idempotent. Re-running it should either no-op or strictly refine stale interrupted state without producing duplicate recovery dispatches.

​
Product continuity never imports execution authority

Workstream context packets and continuation checkpoints contain bounded product summaries, selected events, task state, artifact heads, and provenance. They do not copy adapter transcripts or import another runtime’s run/attempt status. Each runtime establishes its own binding and remains authoritative for its local execution state. Checkpoint freshness is the backend workstream journal’s canonical event sequence, never the local kernel events.event_seq. Upserts are monotonic and import persists an expiring product-context packet for restart. Provenance uses the canonical typed EvidenceRef contract, including device-local scope rules; device-local or sensitive evidence cannot be exported without a resolved, export-specific dispatch. Export replaces sensitive source content with its redacted representation and removes source-runtime dispatch state before a target runtime can import it. Local task Candidates are outbox records until backend delivery. Delivery uses a stable idempotency key and stores a bounded receipt; after receipt, local state is forwarded or a projection of canonical resolution and must not remain in a local review queue. Pre-contract Candidate rows migrate as blocked. Reconciliation must supply the current account generation before an eligible pending row can enter the outbox; historical accepted, rejected, or expired rows remain non-deliverable. Creation and resolution receipts are bounded and retained separately. Guard surface:
  • workstream-continuity.test.ts covers bounded context, cross-runtime checkpoints, Candidate retry/receipt/projection, and rank-free open-loop snapshots.
  • sqlite-store.test.ts covers interrupted-delivery startup reconciliation.