# Initiative Brief — Make the Composer agent real: tool-calling over platform data ## Desired outcome The workspace Composer answers real questions about the operator's own platform data — grounded in what the system actually holds, showing what it consulted, and safe by construction — instead of echoing the message back. Asking "why does this work item have RFC in the title?" returns an answer read from that initiative's work item, not a guess and not an echo. ## Motivation The Composer is the platform's primary conversational surface and the one users reach for first. Today every message returns `Acknowledged: <your text>`, because the runtime is running its deterministic offline provider. That is not an unfinished feature so much as an unfinished last mile. The foundation shipped: a server-side runtime with a bounded context window, a swappable provider adapter, a capability registry with per-action authorization, a confirmation flow for mutations with durable audit receipts, and redacted telemetry. Two things are missing, and neither is small: 1. The only provider that can emit tool calls is the **mock**. The real provider (`agent_text`) is text-only by design, so even switched on it cannot look anything up. 2. The capability registry ships **one stubbed read** and **one mutate placeholder**. There is nothing real for a provider to call. The result is a surface that looks finished and answers nothing. Closing this converts a demo into the platform's actual front door. ## Current state - The `conversation_runtime` feature flag is **enabled** in the production database. - `CONVERSATION_RUNTIME_PROVIDER=agent_text` is now staged in OutShine's prod `.env` but **not yet active** — it takes effect on the next restart/deploy. - No `agent_configs` entry keyed `conversation_runtime` exists in Outsold. Until it does, a send under `agent_text` raises `RuntimeProviderError` and **fails outright** — strictly worse than the mock's echo. The Outsold bridge URL and service token are both configured. - `AgentTextRuntimeProvider` is explicitly text-only: "it does not emit tool calls (the mock covers tool orchestration)". - `build_default_registry()` returns `workspace.read_summary` (a stubbed read) and `workspace.request_action` (a mutate placeholder that is never executed). - Bounds already enforced: 20 messages / 12,000 characters of context per turn, and a hard ceiling of 3 provider↔tool round trips per message. - The client/server conversation contract mismatches were fixed server-side (outshine #456, #459); send and history now work end to end. - The confirmation and receipt paths exist in code but have never been exercised end to end from the client. ## Product principles - Answer from the platform's own data, never from model memory. An ungrounded answer about an operator's initiatives is worse than no answer. - When the assistant cannot answer, it says so plainly and names what it would need. - Every mutation is explicitly confirmed by the user and leaves a durable receipt visible in the conversation. - The user can see what the assistant consulted to produce an answer. - A misconfigured backend produces an honest, actionable message — never a silent echo and never an opaque failure. ## Architectural principles - Provider credentials stay server-side and resolve through the Outsold `agent_configs` registry. No provider key belongs in a workspace app or in OutShine's own `.env`. - The server adapts to the client contract, not the reverse (the direction established in #394/#416/#417/#428 and applied again in #456/#459). - Context is always bounded. No unbounded transcript ever reaches a provider. - Capabilities authorize per-action against the caller's real permissions. Being in a conversation grants nothing. - The provider stays swappable behind the adapter; the runtime never depends on one vendor's tool-call shape. ## Constraints - Single production box with 7.6 GiB RAM shared by every service. Builds and deploys serialize; a careless build has frozen this box before. - CI must stay fully offline. The mock remains the default so no test ever reaches a provider. - Per-turn cost and latency must be bounded and observable before this is enabled for real traffic. - Message content must never enter logs; telemetry stays counts and low-cardinality labels. - The workspace Composer's existing UX contract (send, history, receipts) must not regress. ## Invariants - The default provider is the offline mock. - No provider credential reaches the client or the logs. - Every tool call is authorized against the caller's actual permissions at call time. - Every mutation produces a durable, user-visible receipt. - Context handed to a provider is always bounded by both message count and character count. ## Expected behavior - Asking about an initiative, work item, or release returns an answer read from that record, including its actual text. - The answer shows what the assistant consulted, so the user can verify it. - Asking the assistant to change something produces an explicit confirmation prompt, and after confirming, a receipt that survives a reload. - While the assistant is doing multi-step work, the Composer shows that it is working rather than appearing hung. - If the provider is misconfigured or unavailable, the Composer says so plainly and the message is preserved. ## Open questions - Which provider and model for the `conversation_runtime` agent config — and what is the acceptable per-turn cost? - Which read capabilities land first? Proposed order: initiatives and work items (the reported use case), then workspace directory, then releases and worker health. - Should Orchestrator reads go through the canonical `/orchestrator/*` HTTP surface or a service-to-service call with the existing workspaces↔orchestrator service JWT? - Who owns the cost ceiling and monitors it once real traffic starts? - Does the confirmation flow need a UX pass before mutating capabilities are exposed, given its client paths have never run end to end? - Should tool-call support be added to `AgentTextRuntimeProvider` or land as a third provider, leaving the text-only bridge untouched for other callers?