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 component that owns one session’s worth of envelopes: it materializes a fresh RunContext per request, tracks streaming state for mode: "stream", persists checkpoints for mode: "long_running", and emits typed session-state envelopes that the Compiler consumes.

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
• Session checkpoint after every Critic verdict in long_running mode

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. Pulls prior session state (if session_id present) and stitches it into events[] for Perception.
5. Hands control to the Context Pack Compiler.

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.

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.

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.

Evaluation metrics

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