Conversation Manager

Reference Architecture

The Conversation Manager is the first component on the Decision plane. It receives an invokeAgent envelope from the channel surface and produces the materialized RunContext the rest of the runtime threads through.

Definition

A stateful reference-design component that owns session envelopes: it materializes RunContext for new work, tracks streaming state for mode: "stream", coordinates owned recovery points for mode: "long_running", and supplies normalized session inputs. A local SessionCheckpoint view remains a candidate deployment artifact. Durable recovery now uses the canonical ExecutionCheckpoint, RunExecutionState, operation and budget attachments; a local session view cannot replace them or authorize resume.

Why it exists

Every plane downstream assumes a Run Context that already carries identity, tenant, safety mode, and budget. Without this component there is no single owner of “what is true at the start of this turn.” It also normalizes channel quirks (chat / email / voice / API) so the Compiler sees one shape.

Inputs

• invokeAgent envelope — see API Contracts
• Session state from prior turns of the same session_id
• Channel adapter signals (typing indicators, attachments, locale hints)
• Pinned pack registry handle for context_pack_refs[] resolution

Outputs

• Materialized RunContext (run_id, trace_id, session_id, tenant_id, user, agent, safety_mode, run_budget)
• Normalized event stream consumed by Perception in the Cognitive Core
• Canonical execution checkpoints at safe owned recovery points, plus any separately versioned local session view

How it works

1. Validates the envelope against the API contract; rejects unpinned context_pack_refs[].
2. Resolves channel-specific normalization (e.g., voice ASR transcript → text + confidence).
3. Generates run_id; threads inbound trace.trace_id and session_id into the new RunContext.
4. Retrieves permitted prior state under the authenticated tenant/owner/namespace. A session ID alone cannot authorize access; prior text and attachments remain data-only. events[] is part of the documented Perception protocol, not a new top-level RunContext field.
5. Derives actual features and admits exact required profile/control revisions, then hands pinned inputs to the Context Pack Compiler. Applicable policy-expression errors stop compilation and are safely reported.

For a resume, retain the existing run/operation identity and original aggregate limits. Verify checkpoint bytes/pins against current stores, acquire current revision/ownership generation, fence stale workers where required, and revalidate contract support, authority, approval, boundary, external preconditions and budget. Changed artifact interpretation requires explicit migration/reauthorization. Pending cancellation and unknown effects survive restart; reconnecting a channel cannot silently replay queued writes. See Execution Contract.

Channel-aware input

The Conversation Manager owns channel-specific normalization so the Compiler always sees one shape. Channels are first-class typed inputs, not transport details.

Properties

• Each channel’s adapter normalizes into the shared event shape but preserves the channel-specific signals on event.metadata.channel.* for downstream layers (Attention can up-rank attachments; Critic can require higher confidence on voice transcripts).
• The RunContext.user.delegation.scopes may differ by channel; the Conversation Manager re-validates that the channel’s scopes cover the intent’s required permissions before handing off.
• Channel-specific failure modes (e.g., truncated ASR) surface as typed event.warnings[] the planner can act on.

Channel metadata is input, not authentication: email domains, phone numbers, ASR confidence, user role hints and notification delivery do not establish identity or consent. A personal/proactive trigger additionally needs verified owner/channel/device provenance, a current bounded standing mandate, separate personal/work scopes, remaining budget and an escalation/stop path. Recheck revocation and dispatch controls at every wake and effect, rather than extending authority from conversational wording.

Failure modes

• Envelope missing required fields — rejected with structured error before any plane runs.
• Channel normalization drops attachment hashes — caught by the evidence-coverage assertion later.
• Session resume against a different pack version than the original turn — refuse with pack_version_mismatch.
• Streaming back-pressure causing dropped events — mitigated by per-stream buffer with explicit truncated flag.
• Stale ownership, unsupported required fencing, revoked grant or expired approval on resume — reject recovery dispatch; preserve historical effect/accounting state.

Operational concerns

• p50 / p99 latency budget for envelope acceptance, separate from the Compiler budget.
• Per-tenant rate limits at acceptance, not at the Compiler.
• Long-running session storage cost and TTL banded by data_classification.
• Audit log of every accepted and rejected envelope.
• Minimize channel/session/audit payloads and govern actual inference, telemetry, cache, memory and export recipients, processors and retention; a shared device does not merge owner or employer namespaces.

Evaluation metrics

• Envelope-acceptance latency.
• Rejected-envelope rate by reason.
• Session-resume success rate.
• Trace-context propagation rate (target: 100%).