QodeAssist/docs/target-architecture.md

# QodeAssist — Target Architecture (v1.0)

Status: design baseline, derived from the fixed use-case inventory below.
Scope: the complete plugin, designed "from scratch" — what the architecture
should be if nothing legacy constrained it. The current code (see
`architecture.md`) already converges on this; §10 lists the remaining deltas.

---

## 1. Use-case inventory (requirements baseline)

Every architectural decision below is justified by one of these. Features not
on this list (Rules system, legacy provider/model/template pickers, Stack A)
are intentionally out of scope.

| # | Use case | What the user gets |
|---|----------|--------------------|
| U1 | **Code completion** | Inline FIM/instruct suggestions via LSP; auto + manual trigger, multiline, smart-context suppression, accept full / word-by-word |
| U2 | **Chat assistant** | 4 placements (sidebar, bottom pane, editor tab, floating window); streaming text + thinking blocks + tool blocks + file-edit blocks (apply/undo); attachments, linked files, @-mentions, open-files sync; token counter; persisted history; one-click summarization; runtime agent + role pickers |
| U3 | **Quick refactor** | Selection + instruction by hotkey; custom-instructions library; separate agent; optional tools; streamed result inserted into the editor |
| U4 | **Tools** | read/create/edit file, search, find, list, build, diagnostics, terminal, todo, load_skill; per-tool enable |
| U5 | **Skills** | discovery from `.qodeassist/skills`, `.claude/skills`, `~/.claude/skills`; auto-injection, explicit `/` picker, always-on |
| U6 | **MCP** | server mode (expose plugin tools, HTTP/SSE + stdio bridge) and client hub (consume external tools in chat/refactor) |
| U7 | **Providers** | 13 `client_api` types over one GenericProvider; secrets store; local-server autostart; model listing |
| U8 | **Agents** | TOML profiles: `extends`, `[body]` table 1:1 with the wire request, Jinja partials, `match` rules, per-agent model override, per-pipeline rosters |
| U9 | **Roles** | JSON roles composed into `system_prompt` via `{{ agent_role(id) }}` |
| U10 | **Bench CLI** | headless agent testing on the same core stack, `.env` secrets |
| U11 | **Configuration UI** | settings pages for everything above; per-project settings; updater + status widget |

---

## 2. Design principles

1. **One stack.** Every LLM byte — completion, chat, compression, refactor,
   bench — flows through the same `Session` pipeline. No parallel legacy path.
2. **Hexagonal core.** The runtime (agents, sessions, providers, templates,
   prompt rendering) has zero Qt Creator dependencies. The IDE and the bench
   CLI are two hosts composing the same core; IDE-specific facts enter only
   through ports (document reading, project scanning, secrets, tool hosting).
3. **Configuration is declarative, code is mechanism.** What is sent (request
   `[body]`, system prompt, endpoint, model) lives in TOML/JSON/Jinja and is
   user-overridable; *how* it is sent (streaming, retries, tool loop, event
   routing) lives in C++ and is identical for all providers.
4. **Capability-driven behavior.** Providers and agents declare capabilities
   (tools, thinking, images, model listing); features and UI adapt to the
   declared set instead of switching on provider names.
5. **Single source of truth for conversation state.** `ConversationHistory`
   owns the messages; `ChatModel` and persistence are projections of it, never
   independent copies.
6. **Per-feature composition roots, no singletons.** Each feature constructs
   and owns its dependencies (`new` + parent); shared services are passed
   explicitly (constructor/setter, QML context properties for the chat).
7. **Streaming-first event model.** One typed `ResponseEvent` stream is the
   only contract between the core and every consumer. Deltas exist for live
   UI (chat); one-shot pipelines (completion, refactor, bench) ignore them,
   wait for `finished`, and read the final assistant message from history.
8. **Fail at load, not mid-conversation.** Agent profiles are validated when
   loaded (partials resolve, assembled body parses as JSON against a synthetic
   context), so a config error never surfaces as a silent runtime drop.

---

## 3. Layered model

```mermaid
flowchart TB
    subgraph HOSTS["Hosts — composition roots"]
        PLUGIN["Qt Creator plugin<br/>qodeassist.cpp"]
        BENCH["bench CLI"]
    end

    subgraph L5["L5 · Presentation"]
        LSP["LSP bridge<br/>inline suggestions"]
        QMLUI["ChatView QML<br/>4 placements"]
        RW["Refactor widgets"]
        SUI["Settings pages"]
    end

    subgraph L4["L4 · Features"]
        FCOMP["CompletionFeature"]
        FCHAT["ChatFeature"]
        FREF["RefactorFeature"]
    end

    subgraph L3["L3 · Capabilities"]
        CTX["ContextEngine<br/>ports + QtC adapters"]
        TOOLS["ToolKit"]
        SKILLS["SkillsEngine"]
        MCPH["McpHub<br/>client + server"]
    end

    subgraph L2["L2 · Core runtime — IDE-independent"]
        SM["SessionManager"]
        SESS["Session"]
        AGF["AgentFactory + AgentRouter"]
        AG["Agent"]
        PROV["GenericProvider"]
        TPL["JsonPromptTemplate"]
    end

    subgraph L1["L1 · Declarative config"]
        PCONF["providers/*.toml"]
        ACONF["agents/*.toml + partials/*.jinja"]
        ROST["rosters / pipelines"]
        ROLES["agent_roles/*.json"]
        SKCONF["skills/*.md"]
        SEC["SecretsStore"]
    end

    subgraph L0["L0 · Wire — LLMQore"]
        CLIENTS["*Client — SSE streaming"]
        TOOLFW["Tool framework"]
        MCPT["MCP transports"]
    end

    PLUGIN --> L4
    PLUGIN --> SUI
    BENCH --> SM
    LSP --> FCOMP
    QMLUI --> FCHAT
    RW --> FREF
    FCOMP --> SM
    FCHAT --> SM
    FREF --> SM
    FCOMP --> CTX
    FCHAT --> CTX
    FREF --> CTX
    FCHAT --> SKILLS
    FCHAT --> TOOLS
    FREF --> TOOLS
    TOOLS --> TOOLFW
    MCPH --> MCPT
    SM --> SESS
    SESS --> AG
    AGF --> AG
    AG --> PROV
    AG --> TPL
    AGF --> ACONF
    AGF --> PCONF
    AGF --> SEC
    AGF --> ROST
    TPL --> ROLES
    PROV --> CLIENTS
    SKILLS --> SKCONF
```

### Layer contracts

| Layer | Contains | May depend on | Must NOT depend on |
|-------|----------|---------------|--------------------|
| **L0 Wire** | LLMQore clients (one per wire protocol: Claude, OpenAI Chat, OpenAI Responses, Google, Ollama, Mistral, llama.cpp), tool framework, MCP transports | Qt Network | anything above |
| **L1 Config** | `ProviderInstance`, `AgentProfile` (+ loader/validator), rosters, roles, skills, secrets port | toml++, inja | Qt Creator, L2+ |
| **L2 Core** | `Agent`, `AgentFactory`, `AgentRouter`, `Provider`/`GenericProvider`, `JsonPromptTemplate`, `Session`, `SessionManager`, `ConversationHistory`, `SystemPromptBuilder`, `ResponseRouter`, `ToolContributorRegistry` | L0, L1 | Qt Creator, QML, features |
| **L3 Capabilities** | `ContextEngine` (ports + QtC adapters), `ToolKit` (built-in tools), `SkillsEngine`, `McpHub` | L0–L2, QtC APIs *only in adapters* | features, UI |
| **L4 Features** | `CompletionFeature`, `ChatFeature` (send/stream, compression, token counting, file edits), `RefactorFeature` | L2, L3 | each other |
| **L5 Presentation** | LSP bridge, ChatView QML, refactor widgets, settings pages | its feature | core internals |
| **Hosts** | plugin shell, bench CLI | everything (composition only) | — |

The hard rule that makes U10 (bench) and testability free: **L0–L2 build into
targets with no Qt Creator linkage.** Bench links L0–L2 plus a thin CLI host;
the plugin adds L3 adapters, L4, L5.

---

## 4. Core domain model

Rendered copy: [core-class-diagram.svg](core-class-diagram.svg) (regenerate
when the diagram below changes).

```mermaid
classDiagram
    direction TB
    class SessionManager {
        +acquire(agentName) Session
        +release(session)
        +toolContributors() ToolContributorRegistry
    }
    class Session {
        +send(blocks, toolPolicy)
        +cancel()
        +history() ConversationHistory
        +systemPrompt() SystemPromptBuilder
        +event(ResponseEvent)
        +finished(id, stopReason)
        +failed(id, ErrorInfo)
        +cancelled(id)
    }
    class ConversationHistory {
        +messages() vector~Message~
        +lastAssistantText() string
        +append(Message)
        +reset(vector~Message~)
    }
    class Message {
        +role Role
        +blocks vector~ContentBlock~
    }
    class SystemPromptBuilder {
        +setLayer(id, text, priority)
        +removeLayer(id)
        +compose() string
    }
    class ResponseRouter {
        +attach(BaseClient)
        +event(ResponseEvent)
    }
    class Agent {
        +config() AgentConfig
        +provider() Provider
        +promptTemplate() PromptTemplate
    }
    class AgentFactory {
        +create(name) Agent
        +configByName(name) AgentConfig
        +effectiveModel(name) string
    }
    class AgentRouter {
        +pickAgent(roster, fileCtx) string
    }
    class Provider {
        <<interface>>
        +capabilities() Capabilities
        +prepareRequest(request, ctx)
        +sendRequest(json) RequestID
        +cancelRequest(RequestID)
    }
    class GenericProvider {
        -client BaseClient
    }
    class PromptTemplate {
        <<interface>>
        +buildFullRequest(request, ctx)
    }
    class JsonPromptTemplate {
        -bodySpec QJsonObject
        -env InjaEnvironment
    }
    class ToolContributorRegistry {
        +registerContributor(fn)
        +applyTo(ToolsManager)
    }

    SessionManager o-- Session : pools
    SessionManager --> AgentFactory : builds via
    SessionManager --> ToolContributorRegistry
    Session *-- ConversationHistory
    Session *-- SystemPromptBuilder
    Session *-- ResponseRouter
    Session --> Agent
    ConversationHistory o-- Message
    Agent *-- Provider
    Agent *-- PromptTemplate
    AgentFactory ..> Agent : creates
    AgentFactory --> AgentRouter
    GenericProvider --|> Provider
    JsonPromptTemplate --|> PromptTemplate
```

Responsibilities, one line each:

- **Agent** — immutable bundle of *what to call*: resolved config + provider +
  compiled prompt template. No request state.
- **Session** — one conversation's runtime: owns history, system-prompt
  layers, response routing, the in-flight request, and the tool-execution
  loop (tool_use → execute → tool_result → continue). `send(blocks)` is the
  *only* entry point: every pipeline appends a user message and dispatches;
  there are no per-pipeline send variants. What differs between completion,
  chat, and refactor is the agent's template and the consumption mode (deltas
  vs final message), never the Session API.
- **SessionManager** — creates/pools sessions per agent; the single place
  features go to get one. Pooling (not per-message construction) covers the
  "fresh agent + provider + secrets read per request" latency cost. It reuses
  only the expensive parts (agent, provider, compiled template, secrets read):
  `acquire` hands out a session with cleared history and system-prompt
  layers, so one-shot pipelines never see a previous exchange.
- **AgentRouter** — the *only* agent picker. Every pipeline (completion, chat,
  compression, refactor) resolves its agent through
  `pickAgent(roster, {file, project})`; no feature-local picker logic.
- **GenericProvider** — one class for all 13 client APIs; varies only by
  LLMQore client factory + metadata. Request *shape* belongs to the template,
  never to the provider.
- **JsonPromptTemplate** — compiles the agent's `[body]` table; renders
  Jinja-bearing string values, splices raw JSON, drops empty keys; validated
  at load time.
- **SystemPromptBuilder** — ordered named layers (`agent.system`,
  `chat.context`, `refactor`, `compression`); features mutate only their own
  layer.
- **ResponseRouter / ResponseEvent** — adapts LLMQore client signals into one
  typed stream: `TextDelta`, `ThinkingDelta`, `ToolCallStart/End`,
  `ToolResult`, `Usage`, `Error`, `MessageStop`.
- **ToolContributorRegistry** — contributors (built-in ToolKit, SkillTool,
  McpHub) register once; `SessionManager` applies them to every new session's
  `ToolsManager`. This is how MCP tools reach chat *and* refactor (U6) without
  feature code knowing about MCP.

---

## 5. Runtime flows

### 5.1 Chat (U2) — the richest path

```mermaid
sequenceDiagram
    autonumber
    actor U as User
    participant V as ChatView QML
    participant F as ChatFeature
    participant SM as SessionManager
    participant S as Session
    participant T as JsonPromptTemplate
    participant P as GenericProvider
    participant C as LLMQore Client
    participant R as ResponseRouter

    U->>V: message + attachments
    V->>F: sendMessage(text, files, images)
    F->>SM: acquire(activeAgent)
    SM-->>F: Session (pooled)
    F->>S: systemPrompt().setLayer("chat.context", project + skills + linked files)
    F->>S: send(userBlocks, toolPolicy)
    S->>T: buildFullRequest(history, system, ctx)
    T-->>S: request JSON (body is 1:1 with the API)
    S->>P: sendRequest(json)
    P->>C: HTTP POST, SSE stream
    loop streaming
        C-->>R: chunk / thinking / tool_use / usage
        R-->>S: ResponseEvent
        S-->>F: event(ResponseEvent)
        F-->>V: ChatModel projection update
    end
    opt tool call requested
        S->>S: execute tool via ToolsManager
        S->>P: continue with tool_result
    end
    C-->>R: finalized
    R-->>S: MessageStop + Usage
    S-->>F: finished()
    F->>SM: release(session)
```

State ownership in chat: `Session.history()` is the truth. `ChatModel` is a
QML projection built from history events (`messageAdded`, `messageUpdated`);
`ChatSerializer`/`ChatHistoryStore` persist *history*, and restoring a chat
seeds a new session's history — never the other way around. File-edit blocks,
apply/undo, and the token counter are ChatFeature concerns layered on the
event stream.

### 5.2 Completion (U1)

```
LSP getCompletionsCycling
  → CompletionFeature
      agent   = AgentRouter.pickAgent(roster.codeCompletion, {file, project})
      session = SessionManager.acquire(agent)
      ctx     = ContextEngine: prefix/suffix + open-files context (policy from
                CodeCompletionSettings — editor policy, not agent config)
      session.send(blocks{completion context}, tools=off)
  on finished → history().lastAssistantText()
      → CodeHandler (output-mode post-processing) → LSP items
```

No special Session method: the completion context travels as the content of
an ordinary user message (a structured block carrying prefix/suffix + file
context), and the template context exposes it as `ctx.prefix` / `ctx.suffix`.
FIM vs instruct is *agent config* (template + body), not feature code: a FIM
agent's body renders `prefix`/`suffix` into FIM fields; an instruct agent's
body renders the same exchange as a chat-shaped request. The feature is
identical for both — and since completion has no incremental UI, it never
touches the delta stream: it waits for `finished` and reads the last message.

### 5.3 Quick refactor (U3)

```
Hotkey → RefactorFeature
  agent   = AgentRouter.pickAgent(roster.quickRefactor, {file, project})
  session = SessionManager.acquire(agent)
  session.systemPrompt().setLayer("refactor", tagged selection + output rules)
  session.send(blocks{instruction}, toolPolicy)
  on finished → history().lastAssistantText()
      → ResponseCleaner → RefactorResult → editor insert (accept/reject)
```

Same consumption mode as completion: the feature listens to
`Session::finished`/`failed` only (events at most drive a progress spinner
and cancel) and reads the result from history — it never connects to raw
client signals. Tool calls during refactor run inside the session's tool
loop; history's last assistant message is whatever the model produced after
the final tool round.

### 5.4 Compression (U2) and bench (U10)

Compression is ChatFeature reusing the same path with
`roster.chatCompression` and a `"compression"` system layer; the summary
starts a new history. Bench is a host: CLI args + `.env` secrets → L1 + L2
composition → `Session.send` → events printed to stdout. Anything bench can't
do without the IDE is, by construction, an L3+ concern.

---

## 6. Configuration model

```mermaid
erDiagram
    AGENT_PROFILE ||--o| AGENT_PROFILE : extends
    AGENT_PROFILE }o--|| PROVIDER_INSTANCE : provider_instance
    AGENT_PROFILE }o--o{ PARTIAL : includes
    AGENT_PROFILE }o--o{ ROLE : agent_role
    ROSTER }o--o{ AGENT_PROFILE : ranks
    MODEL_OVERRIDE |o--|| AGENT_PROFILE : overrides_model
    PROVIDER_INSTANCE }o--|| CLIENT_API : client_api
    PROVIDER_INSTANCE }o--o| SECRET : api_key_ref
    PROVIDER_INSTANCE ||--o| LAUNCH_CONFIG : autostarts

    AGENT_PROFILE {
        string name
        bool abstract
        string system_prompt "jinja, composes agent_role()"
        json body "request body, 1:1 with API"
        string endpoint "may contain MODEL placeholder"
        string model "default; override wins"
        bool enable_tools "capability hint"
        bool enable_thinking "capability hint"
        json match "file, path, project patterns"
    }
    PROVIDER_INSTANCE {
        string name
        string client_api
        string url
        string api_key_ref
    }
    ROLE {
        string id
        string systemPrompt
    }
    ROSTER {
        string pipeline "completion, chat, compression, refactor"
        list agents "ordered candidates"
    }
```

Rules of the config layer (full spec: `agent-templates-design.md`):

- `[body]` **is** the request body — field-by-field, deep-mergeable through
  `extends`; Jinja-bearing strings render and splice as raw JSON, literals
  pass through. No separate sampling/thinking merge machinery.
- `include` resolves only sandboxed partial roots (bundled `:/agents/partials/`,
  then user `partials/`); a missing partial is a load-time error.
- Two-level hierarchy: one abstract base per provider family, thin children.
- Per-agent model override lives in `agent_models.json` and is applied by
  `AgentFactory`; `${MODEL}` in `endpoint` covers URL-model providers.
- Roles are JSON managed by the Roles settings UI; profiles pull them in with
  `{{ agent_role("<id>") }}` — the only system-prompt edit point is the
  profile.
- Secrets never appear in TOML; `api_key_ref` resolves through the
  `SecretsStore` port (QtC keychain in the plugin, `.env` in bench).

---

## 7. Capabilities layer

**ContextEngine** replaces the monolithic ContextManager with three focused
services behind IDE-agnostic ports:

| Service | Port (L2-visible) | QtC adapter |
|---------|-------------------|-------------|
| `EditorContext` — current doc, selection, prefix/suffix | `IDocumentReader` | TextEditor API |
| `ProjectContext` — root, file listing, ignore filtering (`.qodeassistignore`), open files, changes | `IProjectScanner` | ProjectExplorer API |
| `TokenEstimator` — input estimates, calibrated by server usage | — (pure) | — |

**ToolKit** registers the built-in tools (U4) with the
`ToolContributorRegistry`; each tool declares a permission class (read /
write / execute) so per-tool enablement (settings) and confirmation policy
(terminal commands) live in one place.

**SkillsEngine** (U5): discovery + watching of the three skill roots; exposes
`catalogText()` (names + descriptions for the system prompt),
`alwaysOnBodies()`, and the `load_skill` tool; the `/` picker injects a
skill's body into a single message.

**McpHub** (U6): client side connects configured servers and contributes
their tools through the same registry (tools reach every session uniformly);
server side exposes ToolKit over HTTP/SSE + stdio bridge.

---

## 8. Cross-cutting policies

Architecture is the rules as much as the boxes. These policies bind every
layer and are part of the contract:

### 8.1 Threading

The core runs on the GUI thread; concurrency is the Qt event loop plus async
network I/O — no shared-state threading anywhere in L1–L4. Work that can
block (project scans, token estimation over large trees) hides behind L3
ports; an adapter may use worker threads internally but delivers results as
queued signals. Core types are therefore deliberately not thread-safe.

### 8.2 Request lifecycle

A session has at most one in-flight request; `send()` while in flight cancels
the previous request first. Every request terminates in exactly one of three
states — `finished(stopReason)`, `failed(error)`, `cancelled()` — and
cancellation is *not* an error: no consumer may string-match a message to
tell them apart.

### 8.3 Errors

Runtime errors are typed, not strings: `ErrorInfo { category, message,
providerDetail }` with categories `Config | Auth | Network | Provider |
Validation | Tool`. The category drives UI affordances (Auth → open provider
settings, Network → offer retry); free text is for logs only. Load-time
errors (principle 8) surface in the agents settings page, never as a failed
send.

### 8.4 Timeouts and retries

Transfer timeouts are per-pipeline policy (completion short, chat/refactor
from settings), applied by the feature — never baked into agent profiles. A
streaming request is never silently retried after the first byte; automatic
retry with capped backoff is allowed only for connection-phase failures.
Anything beyond that is an explicit user action.

### 8.5 Observability

One `RequestID` correlates feature → session → provider → client → events →
logs. Each layer logs under its own category (`qodeassist.session`,
`qodeassist.provider`, `qodeassist.tools`, …); request bodies are logged only
at debug level, and secrets are redacted unconditionally. `Usage` events are
the single source feeding the token counter, `TokenEstimator` calibration,
and the performance log.

### 8.6 Config compatibility

Agent profiles carry a `schema_version`; the loader migrates old user
configs forward or rejects them with an actionable message — silent
reinterpretation is forbidden. Bundled profiles are read-only resources that
user profiles shadow by name. Persisted chat history is versioned the same
way.

### 8.7 Security

Secrets exist only behind the `SecretsStore` port; they never reach TOML,
logs, or persisted chats. Tool permission classes (read / write / execute)
centralize the confirmation policy. The MCP server is opt-in and binds
loopback by default; skill and partial roots are sandboxed — nothing resolves
outside its declared directory.

### 8.8 Testing

The test pyramid follows the layers:

| Layer | Strategy |
|-------|----------|
| L1 | loader/validator unit tests; golden-file snapshots of every bundled profile's rendered body against a synthetic context — the same check as load-time validation, run in CI |
| L2 | `Session` / `ResponseRouter` replay tests over recorded SSE fixtures per provider; fake `BaseClient`, no network |
| L3 | contract tests against the ports; QtC adapters covered only by plugin integration |
| E2E | bench (U10) against live providers — the same composition the plugin uses |

Layering is enforced mechanically, not by review: each layer is its own
CMake target, and the core targets do not link Qt Creator — a violating
include fails the build.

---

## 9. Module / target layout

```
core/                       # no Qt Creator linkage — bench + tests link this
  config/                   # L1: ProviderInstance, AgentProfile, loaders,
                            #     validators, rosters, roles, secrets port
  providers/                # L2: Provider, GenericProvider, ProviderFactory,
                            #     ClaudeCacheControl
  prompt/                   # L2: JsonPromptTemplate, ContextRenderer, partials
  agents/                   # L2: Agent, AgentFactory, AgentRouter
  session/                  # L2: Session, SessionManager, ConversationHistory,
                            #     SystemPromptBuilder, ResponseRouter, events
  skills/                   # L3 (IDE-free part): SkillsEngine, loaders
ide/                        # Qt Creator adapters only
  context/                  # EditorContext, ProjectContext adapters, ignore
  tools/                    # built-in ToolKit (build, issues, editor edits…)
  mcp/                      # McpHub managers
features/
  completion/               # LSP bridge + CompletionFeature + CodeHandler
  chat/                     # ChatFeature: ClientInterface, ChatModel(projection),
                            #   Compressor, TokenCounter, FileEditController,
                            #   serializer/store
  refactor/                 # RefactorFeature + custom instructions
ui/
  ChatView qml/, widgets/, settings pages
hosts/
  plugin/                   # qodeassist.cpp — composition root, actions, panes
  bench/                    # CLI composition root
tests/
  config/                   # loader cases + golden rendered-body snapshots
  session/                  # SSE replay fixtures per provider, fake client
external/
  llmqore/ inja/ tomlplusplus/
```

Dependency direction is strictly downward in the table of §3; `features/*`
never include each other; `ui/*` talks only to its feature; `hosts/*` are the
only places allowed to know about everything.

---

## 10. Deltas from the current working tree

What "from scratch" changes relative to today's code — the migration
checklist to call the architecture done:

1. **Stack A physical teardown** — delete root `providers/*`,
   `pluginllmcore/*`, `ConfigurationManager`, legacy provider/model/template
   settings pages, and the Stack A registration + MCP loop in
   `qodeassist.cpp`. Runtime already has no consumers.
2. **Single history owner** — make `ChatModel` a projection of
   `Session::history()` (subscribe to history signals) instead of a parallel
   message store with seed-on-send; `ChatCompressor` reads history, not the
   model.
3. **Single send path** — delete `Session::sendCompletion(ContextData)`;
   the completion context becomes user-message content sent through the one
   `send()` (the completion handler already reads its result from history's
   last message). Move `QuickRefactorHandler` off raw `BaseClient` signals
   (`requestCompleted`/`requestFinalized`/`requestFailed`) onto
   `Session::finished`/`failed` + `history().lastAssistantText()`.
4. **Three-state request lifecycle** — add `cancelled` to `Session`; today
   `cancel()` emits `failed(id, "Cancelled by user")` and consumers must
   string-match to tell cancellation from failure (§8.2).
5. **Typed errors** — replace `lastError` strings and the `failed(QString)`
   payload with `ErrorInfo` categories (§8.3).
6. **One agent picker** — fold `pickCompletionAgent` / `pickRefactorAgent`
   remnants into `AgentRouter.pickAgent(roster, …)` exclusively; chat picker
   filters to the `chatAssistant` roster.
7. **MCP tools on session clients** — register MCP-contributed tools through
   `ToolContributorRegistry` so chat/refactor sessions get them (today they
   are registered only on dead Stack A providers).
8. **Session pooling** — `SessionManager.acquire/release` with a small pool
   per agent, replacing per-message agent + provider + secrets construction.
9. **ContextManager split** — extract `EditorContext` / `ProjectContext` /
   `TokenEstimator` behind ports; move QtC API use into `ide/context`.
10. **`[body]` model completion** — finish `agent-templates-design.md`
    (body-table rendering, sandboxed `include`, load-time validation, model
    override + `${MODEL}`, `schema_version` gate), delete sampling/thinking
    merge machinery.
11. **Message type unification** — one `Message`/`ContentBlock` shape from
    history to QML (roles, text, thinking, tool use/result, images); delete
    the parallel `ChatModel::Message` struct.
12. **Test scaffolding** — golden rendered-body snapshots + SSE replay
    fixtures (§8.8); CI builds the core targets without Qt Creator so a
    layering violation fails the build.
13. **Stale docs cleanup** — `project-rules.md` describes the removed Rules
    system; mark or delete.