# Chat (`kb chat`) — design and roadmap This doc is the **source of truth** for how chat relates to `kb query` today and how we expect it to grow. Update it when behavior changes. ## Today: one dumb orchestrator, one “tool” Chat is intentionally minimal: 1. **Resolve the turn** — conversational mode may rewrite follow-ups into a standalone retrieval query (`src/cli/chat-conversation.ts`). 2. **Graph expansion** — same helpers as CLI query (`expandQueryWithGraph`, relation block for the LLM prompt). 3. **Run retrieval exactly like `kb query`** — both call **`runQueryTruthRetrieval()`** in `src/cli/query-truth-retrieval.ts`: `runIntentLoop` (same **`query_truth`** envelope the CLI builds after graph expansion and **only** optional **`--session`** rewrite — default CLI query uses the literal topic string, like chat) → router → **`read_facts`** (fact FTS + deep **`FactsQueryResearchOrchestrator`** when discovery is deep). **No** workspace markdown fallback. `DefaultIntentRouter` defaults **`query_truth`** to **`discoveryDepth: 'deep'`** when `--discovery` is omitted, so chat and CLI get the same research-style retrieval; chat passes **`discoveryDepth: 'deep'`** explicitly plus the chat retrieval limit. 4. **Conversational answer** — evidence from step 3 is passed to the chat system prompt + LLM (`src/cli/chat-cli.ts`, `src/prompts/chat-system.md`). 5. **Orchestration output** — `printReadDocumentsOrchestrationFooter()` prints the same minimal wire rows as `kb query` human mode: `retrieval>`, `matches>`, then a single **`sources>`** line with all hit **titles** (ids as fallback). With **`--debug`** / **`chat --debug`**, it instead prints one full provenance **`source>`** line per document (same shape as legacy query output). **`summary>`**, **`status>`**, and **`confidence>`** are only included when the user passed **`--verbose`** on **`kb chat`** (CLI) or **`chat --verbose`** in the TUI shell *before* the session starts; there is no mid-session toggle. Router fields like `explanation` / `provenance` stay on `IntentResult` for JSON and telemetry but are not duplicated in the human footer by default. **`query-session.json`:** only when **`kb query --session`** (not chat). So today’s “orchestrator” is **trivial**: always call **`runQueryTruthRetrieval()`** (not a second router shortcut), then the LLM, then the shared footer. Subprocess `kb query` is **not** spawned; in-process reuse keeps config, base, and telemetry aligned. ## Why not shell out to `kb query`? Calling the CLI in a loop would duplicate process startup, env, base resolution, and error surfaces. The orchestrator module is the **same contract** as query without a fork/exec boundary. ## Near future: richer chat orchestrator The next step is a small **turn router** in front of the loop: - Classify (rules + optional lightweight LLM): QUERY vs SUBMIT vs INVALIDATE vs DOCS vs GRAPH … - **QUERY** → keep calling **`runQueryTruthRetrieval()`** (via `executeChatQueryTruthRetrieval()`’s thin envelope builder). - Other intents → dispatch to the same handlers the CLI already uses, then summarize for chat. Principles: - **One owner per turn** — pick an intent once, run it, render with shared printers. - **Reuse CLI intent paths** — avoid a second implementation of query/submit/invalidate for chat. - **Orchestration lines stay wire-format** — `key> value` rows only from `Printer` / shared formatters so TUI and piped CLI stay consistent (`src/ui/orchestration-meta.ts`). ## Historical note Older revisions called `read_documents` directly from chat with hand-built inputs; that drifted from `kb query` (different limits, router `explanation` / `confidence` not shown in the default human footer, different augment order). The orchestrator + footer alignment fixes that; use **`--verbose`** when you want those extra human rows to match an explicit `kb query --verbose` session. ## See also - `src/cli/query-truth-retrieval.ts` — shared **`runQueryTruthRetrieval()`** for CLI `kb query` and chat - `src/cli/chat-query-orchestrator.ts` — builds chat **`query_truth`** envelope, delegates to shared retrieval - `src/cli/intent-cli.ts` — `printReadDocumentsOrchestrationFooter`, augment helpers - `src/intents/router.ts` — `query_truth` → **`read_facts`** routing - `src/core/TUI.md` — TUI command surface - `src/core/AGENT_LOOP.md` — full intent loop (retries, escalation); chat may adopt more of this later for QUERY turns

Chat (kb chat) — design and roadmap

This doc is the source of truth for how chat relates to kb query today and how we expect it to grow. Update it when behavior changes.

Today: one dumb orchestrator, one “tool”

Chat is intentionally minimal:

1. Resolve the turn — conversational mode may rewrite follow-ups into a standalone retrieval query (src/cli/chat-conversation.ts).
2. Graph expansion — same helpers as CLI query (expandQueryWithGraph, relation block for the LLM prompt).
3. Run retrieval exactly like kb query — both call runQueryTruthRetrieval() in src/cli/query-truth-retrieval.ts: runIntentLoop (same query_truth envelope the CLI builds after graph expansion and only optional --session rewrite — default CLI query uses the literal topic string, like chat) → router → read_facts (fact FTS + deep FactsQueryResearchOrchestrator when discovery is deep). No workspace markdown fallback. DefaultIntentRouter defaults query_truth to discoveryDepth: 'deep' when --discovery is omitted, so chat and CLI get the same research-style retrieval; chat passes discoveryDepth: 'deep' explicitly plus the chat retrieval limit.
4. Conversational answer — evidence from step 3 is passed to the chat system prompt + LLM (src/cli/chat-cli.ts, src/prompts/chat-system.md).
5. Orchestration output — printReadDocumentsOrchestrationFooter() prints the same minimal wire rows as kb query human mode: retrieval>, matches>, then a single sources> line with all hit titles (ids as fallback). With --debug / chat --debug, it instead prints one full provenance source> line per document (same shape as legacy query output). summary>, status>, and confidence> are only included when the user passed --verbose on kb chat (CLI) or chat --verbose in the TUI shell before the session starts; there is no mid-session toggle. Router fields like explanation / provenance stay on IntentResult for JSON and telemetry but are not duplicated in the human footer by default.

query-session.json: only when kb query --session (not chat).

So today’s “orchestrator” is trivial: always call runQueryTruthRetrieval() (not a second router shortcut), then the LLM, then the shared footer. Subprocess kb query is not spawned; in-process reuse keeps config, base, and telemetry aligned.

Why not shell out to kb query?

Calling the CLI in a loop would duplicate process startup, env, base resolution, and error surfaces. The orchestrator module is the same contract as query without a fork/exec boundary.

Near future: richer chat orchestrator

The next step is a small turn router in front of the loop:

• Classify (rules + optional lightweight LLM): QUERY vs SUBMIT vs INVALIDATE vs DOCS vs GRAPH …
• QUERY → keep calling runQueryTruthRetrieval() (via executeChatQueryTruthRetrieval()’s thin envelope builder).
• Other intents → dispatch to the same handlers the CLI already uses, then summarize for chat.

Principles:

• One owner per turn — pick an intent once, run it, render with shared printers.
• Reuse CLI intent paths — avoid a second implementation of query/submit/invalidate for chat.
• Orchestration lines stay wire-format — key> value rows only from Printer / shared formatters so TUI and piped CLI stay consistent (src/ui/orchestration-meta.ts).

Historical note

Older revisions called read_documents directly from chat with hand-built inputs; that drifted from kb query (different limits, router explanation / confidence not shown in the default human footer, different augment order). The orchestrator + footer alignment fixes that; use --verbose when you want those extra human rows to match an explicit kb query --verbose session.

See also

• src/cli/query-truth-retrieval.ts — shared runQueryTruthRetrieval() for CLI kb query and chat
• src/cli/chat-query-orchestrator.ts — builds chat query_truth envelope, delegates to shared retrieval
• src/cli/intent-cli.ts — printReadDocumentsOrchestrationFooter, augment helpers
• src/intents/router.ts — query_truth → read_facts routing
• src/core/TUI.md — TUI command surface
• src/core/AGENT_LOOP.md — full intent loop (retries, escalation); chat may adopt more of this later for QUERY turns