@cam5/baby-bird 0.1.0 → 0.1.1

package/dist/{chunk-RWSCST2I.js → chunk-7ALXKEST.js}

@@ -2,8 +2,8 @@
 import { z } from "zod";
 var LlmExcerptRefSchema = z.object({
   hunk: z.string().min(1),
-  /** Optional [start, end] range of new-file line numbers to narrow the hunk. */
-  lines: z.tuple([z.number().int().nonnegative(), z.number().int().nonnegative()]).optional(),
+  /** Optional [start, end] new-file line numbers to narrow the hunk; fewer than two numbers means the whole hunk. */
+  lines: z.array(z.number().int().nonnegative()).optional(),
   note: z.string().optional()
 });
 var LlmSectionSchema = z.object({
@@ -139,22 +139,27 @@ var CLAUDE_BASE = ["claude", "-p", "--no-session-persistence", "--setting-source
 var BUILTIN_PRESETS = Object.freeze({
   claude: {
     command: [...CLAUDE_BASE],
+    kind: "claude",
     description: "Claude Code CLI with its default model"
   },
   "claude-sonnet": {
     command: [...CLAUDE_BASE, "--model", "sonnet", "--effort", "high"],
+    kind: "claude",
     description: "Claude Code CLI, Sonnet at high effort"
   },
   "claude-opus": {
     command: [...CLAUDE_BASE, "--model", "opus", "--effort", "high"],
+    kind: "claude",
     description: "Claude Code CLI, Opus at high effort"
   },
   "claude-fable": {
     command: [...CLAUDE_BASE, "--model", "fable", "--effort", "high"],
+    kind: "claude",
     description: "Claude Code CLI, Fable at high effort"
   },
   "claude-haiku": {
     command: [...CLAUDE_BASE, "--model", "haiku"],
+    kind: "claude",
     description: "Claude Code CLI, Haiku (fast and cheap)"
   },
   llm: {
@@ -163,9 +168,11 @@ var BUILTIN_PRESETS = Object.freeze({
   }
 });
 var PromptViaSchema = z2.enum(["stdin", "arg"]);
+var LlmKindSchema = z2.enum(["plain", "claude"]);
 var LlmPresetSchema = z2.object({
   command: z2.array(z2.string()).min(1),
   promptVia: PromptViaSchema.optional(),
+  kind: LlmKindSchema.optional(),
   description: z2.string().optional()
 });
 var ConfigSchema = z2.object({
@@ -175,6 +182,9 @@ var ConfigSchema = z2.object({
     args: z2.array(z2.string()),
     command: z2.array(z2.string()).min(1).nullable(),
     promptVia: PromptViaSchema.nullable(),
+    kind: LlmKindSchema.nullable(),
+    /** Claude kind only: pass --json-schema so the CLI validates the answer itself. Off by default (see README). */
+    jsonSchema: z2.boolean(),
     timeoutMs: z2.number().int().positive(),
     maxPromptBytes: z2.number().int().positive(),
     env: z2.record(z2.string(), z2.string())
@@ -190,7 +200,11 @@ var ConfigSchema = z2.object({
     color: z2.enum(["auto", "always", "never"]),
     pager: z2.enum(["auto", "always", "never"]),
     maxExcerptLines: z2.number().int().positive(),
-    width: z2.number().int().positive().nullable()
+    width: z2.number().int().positive().nullable(),
+    /** Language-aware token colors in excerpts (needs a 256-color terminal for the add/del tints). */
+    highlight: z2.enum(["auto", "always", "never"]),
+    /** Background tint palette for added/removed lines. */
+    theme: z2.enum(["dark", "light"])
   }),
   cache: z2.object({
     enabled: z2.boolean(),
@@ -211,6 +225,8 @@ var DEFAULT_CONFIG = {
     args: [],
     command: null,
     promptVia: null,
+    kind: null,
+    jsonSchema: false,
     timeoutMs: 18e4,
     maxPromptBytes: 2e5,
     env: {}
@@ -229,7 +245,7 @@ var DEFAULT_CONFIG = {
       "**/*.map"
     ]
   },
-  render: { color: "auto", pager: "auto", maxExcerptLines: 60, width: null },
+  render: { color: "auto", pager: "auto", maxExcerptLines: 60, width: null, highlight: "auto", theme: "dark" },
   cache: { enabled: true, dir: null }
 };
 function userConfigPath(env = process.env) {
@@ -343,9 +359,9 @@ function allPresets(config) {
 }
 function resolveLlm(config) {
   const { llm } = config;
-  const common = { timeoutMs: llm.timeoutMs, maxPromptBytes: llm.maxPromptBytes, env: llm.env };
+  const common2 = { timeoutMs: llm.timeoutMs, maxPromptBytes: llm.maxPromptBytes, env: llm.env, jsonSchema: llm.jsonSchema };
   if (llm.command) {
-    return { command: [...llm.command, ...llm.args], promptVia: llm.promptVia ?? "stdin", preset: null, ...common };
+    return { command: [...llm.command, ...llm.args], promptVia: llm.promptVia ?? "stdin", kind: llm.kind ?? "plain", preset: null, ...common2 };
   }
   const presets = allPresets(config);
   const preset = presets[llm.preset];
@@ -356,8 +372,9 @@ function resolveLlm(config) {
   return {
     command: [...preset.command, ...llm.args],
     promptVia: llm.promptVia ?? preset.promptVia ?? "stdin",
+    kind: llm.kind ?? preset.kind ?? "plain",
     preset: llm.preset,
-    ...common
+    ...common2
   };
 }
 function shellSplit(input) {
@@ -767,7 +784,8 @@ function materializeTour(input) {
         continue;
       }
       files.add(hit.file.path);
-      const lines = sliceHunk(hit.hunk, ref.lines, input.maxExcerptLines);
+      const range = ref.lines && ref.lines.length >= 2 ? [ref.lines[0], ref.lines[1]] : void 0;
+      const lines = sliceHunk(hit.hunk, range, input.maxExcerptLines);
       const excerpt = {
         file: hit.file.path,
         hunkId: hit.hunk.id,
@@ -851,8 +869,8 @@ function sliceHunk(hunk, range, maxLines) {
 }
 
 // src/core/prompt/template.ts
-var PROMPT_VERSION = 2;
-var PROMPT_HEADER = `You are writing a guided code tour of a change for a reviewer who has not seen it before.
+var PROMPT_VERSION = 3;
+var PROMPT_HEADER_TEXT = `You are writing a guided code tour of a change for a reviewer who has not seen it before.
 
 A code tour is an ordered list of sections. Each section explains one coherent part of the change: what it does, why it is there, and how it connects to the rest. Sections are ordered the way a reader should encounter them: start with the change that makes everything else make sense (a new type, an interface, a data model, a configuration knob), then the code that builds on it, then wiring and plumbing, then tests and housekeeping.
 
@@ -862,7 +880,7 @@ A code tour is an ordered list of sections. Each section explains one coherent p
 - Group by concept, not by file. A section may span many files, and a file may appear in several sections.
 - Every file in the change must be claimed by at least one section. Put unrelated housekeeping (formatting, generated code, renames, dependency bumps) in one short final section rather than sprinkling it around.
 - A section's description is 2 to 5 sentences of plain prose written for a colleague. Lead with the purpose (why), then what changed, then anything a reviewer should look at carefully: behavior changes, edge cases, risk. Do not narrate line by line and do not restate the diff.
-- Choose 1 to 3 excerpts per section: the hunks that best show the idea. Reference hunks by their id exactly as given (for example "F2.H1"). Optionally narrow a hunk with "lines": [start, end] using NEW-file line numbers as they appear in the diff. Never quote code in the JSON; the real diff is rendered from your references.
+- Choose 1 to 3 excerpts per section: the hunks that best show the idea. Reference hunks by their id exactly as given (for example "F2.H1"). Narrow a hunk to the interesting part with "lines": [start, end] using NEW-file line numbers as they appear in the diff; prefer 10 to 30 lines over a whole hunk. Use an empty "lines" array for the whole hunk. Never quote code in the JSON; the real diff is rendered from your references.
 - Give each excerpt a short "note" (under 15 words) saying what to look at.
 - The tour "title" is a short imperative phrase naming the change, like a good commit subject. The "summary" is 2 to 4 sentences describing the whole change and its motivation.
 - Use the pull request description and commit messages as evidence of intent, but trust the diff over them when they disagree.
@@ -871,7 +889,7 @@ A code tour is an ordered list of sections. Each section explains one coherent p
 
 ## Output
 
-Respond with ONLY a JSON object: no prose before or after it, and no code fences.
+%%OUTPUT_INSTRUCTION%%
 
 {
   "title": "Short imperative title",
@@ -889,6 +907,12 @@ Respond with ONLY a JSON object: no prose before or after it, and no code fences
   ]
 }
 `;
+var OUTPUT_PLAIN = "Respond with ONLY a JSON object: no prose before or after it, and no code fences.";
+var OUTPUT_STRUCTURED = "Submit the tour through the structured output tool. Its input is the tour object itself, with title, summary and sections as top-level fields exactly as shown below (do not nest them under another key). Do not write prose before it.";
+function promptHeader(structured) {
+  return PROMPT_HEADER_TEXT.replace("%%OUTPUT_INSTRUCTION%%", structured ? OUTPUT_STRUCTURED : OUTPUT_PLAIN);
+}
+var PROMPT_HEADER = promptHeader(false);
 var REPAIR_SUFFIX = (reason) => `
 
 ---
@@ -901,6 +925,7 @@ Respond again with ONLY the JSON object described above. No prose, no code fence
 var KEEP_LINES = 40;
 var MAX_PR_BODY_BYTES = 12e3;
 function buildPrompt(input) {
+  const header = promptHeader(Boolean(input.structured));
   const context = renderContext(input);
   const truncation = { truncated: [], omitted: [] };
   const blocks = input.diff.files.map((file) => {
@@ -917,7 +942,7 @@ function buildPrompt(input) {
   });
   const text = (b) => b.mode === "full" ? b.full : b.mode === "truncated" ? b.truncated : b.omitted;
   const total = () => bytes(diffPreamble(truncation)) + blocks.reduce((n, b) => n + bytes(text(b)), 0);
-  const budget = input.maxBytes - bytes(PROMPT_HEADER) - bytes(context) - 8;
+  const budget = input.maxBytes - bytes(header) - bytes(context) - 8;
   if (total() > budget) {
     const bySize = [...blocks].sort((a, b) => bytes(b.full) - bytes(a.full));
     for (const block of bySize) {
@@ -934,7 +959,7 @@ function buildPrompt(input) {
       truncation.omitted.push(block.file.path);
     }
   }
-  const prompt = [PROMPT_HEADER, context, diffPreamble(truncation), ...blocks.map(text)].join("\n");
+  const prompt = [header, context, diffPreamble(truncation), ...blocks.map(text)].join("\n");
   return { prompt, truncation };
 }
 function bytes(s) {
@@ -1326,32 +1351,237 @@ async function nearestAncestorBranch(branch, headSha, defaultBranch, cwd, debug)
   return best?.name ?? null;
 }
 
+// src/core/prompt/json-schema.ts
+var TOUR_JSON_SCHEMA = {
+  type: "object",
+  description: "The tour itself. Its fields (title, summary, sections) are the top-level properties of this object; do not wrap them in another key.",
+  additionalProperties: false,
+  required: ["title", "summary", "sections"],
+  properties: {
+    title: { type: "string", description: "Short imperative title naming the change, like a good commit subject." },
+    summary: { type: "string", description: "2 to 4 sentences describing the whole change and its motivation." },
+    sections: {
+      type: "array",
+      description: "Ordered sections of the tour, 2 to 8 of them.",
+      items: {
+        type: "object",
+        additionalProperties: false,
+        required: ["title", "description", "files", "excerpts"],
+        properties: {
+          title: { type: "string" },
+          description: { type: "string", description: "Why, then what, then what to watch. 2 to 5 sentences." },
+          files: { type: "array", items: { type: "string" }, description: "Paths this section is about, exactly as listed." },
+          excerpts: {
+            type: "array",
+            description: "1 to 3 hunks that best show the idea.",
+            items: {
+              type: "object",
+              additionalProperties: false,
+              required: ["hunk", "lines", "note"],
+              properties: {
+                hunk: { type: "string", description: 'A hunk id exactly as given in the diff, e.g. "F2.H1".' },
+                lines: {
+                  type: "array",
+                  items: { type: "integer" },
+                  description: "Empty for the whole hunk, or [start, end] new-file line numbers to narrow it."
+                },
+                note: { type: "string", description: "Under 15 words: what to look at. May be empty." }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+};
+
+// src/llm/claude-stream.ts
+var isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+var ClaudeStreamParser = class {
+  constructor(onEvent = () => {
+  }) {
+    this.onEvent = onEvent;
+  }
+  onEvent;
+  buffer = "";
+  text = "";
+  partialJson = "";
+  messageStructured = null;
+  resultStructured = null;
+  resultText = null;
+  isError = false;
+  errorMessage;
+  usage = {};
+  unparsed = 0;
+  push(chunk) {
+    this.buffer += chunk;
+    let idx;
+    while ((idx = this.buffer.indexOf("\n")) !== -1) {
+      const line = this.buffer.slice(0, idx);
+      this.buffer = this.buffer.slice(idx + 1);
+      this.handleLine(line);
+    }
+  }
+  finish() {
+    if (this.buffer.trim()) this.handleLine(this.buffer);
+    this.buffer = "";
+    const result = this.resultStructured ?? this.messageStructured ?? (this.partialJson.trim() || null) ?? (this.resultText?.trim() || null) ?? (this.text.trim() || null);
+    const outcome = { result, isError: this.isError, usage: this.usage, unparsedLines: this.unparsed };
+    if (this.errorMessage) outcome.errorMessage = this.errorMessage;
+    return outcome;
+  }
+  handleLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed) return;
+    let ev;
+    try {
+      ev = JSON.parse(trimmed);
+    } catch {
+      this.unparsed++;
+      return;
+    }
+    if (!isObject(ev)) return;
+    switch (ev.type) {
+      case "stream_event":
+        if (isObject(ev.event)) this.handleStreamEvent(ev.event);
+        break;
+      case "assistant":
+        if (isObject(ev.message)) this.handleAssistant(ev.message);
+        break;
+      case "user":
+        if (isObject(ev.message)) this.handleUser(ev.message);
+        break;
+      case "result":
+        this.handleResult(ev);
+        break;
+      default:
+        break;
+    }
+  }
+  handleStreamEvent(event) {
+    switch (event.type) {
+      case "message_start": {
+        const model = isObject(event.message) && typeof event.message.model === "string" ? event.message.model : void 0;
+        if (model) {
+          this.usage.model = model;
+          this.onEvent({ type: "usage", model });
+        }
+        break;
+      }
+      case "content_block_start": {
+        const block = isObject(event.content_block) ? event.content_block : {};
+        if (block.type === "text" || block.type === "tool_use") {
+          this.text = "";
+          this.partialJson = "";
+          this.onEvent({ type: "answer-start" });
+        }
+        break;
+      }
+      case "content_block_delta": {
+        const delta = isObject(event.delta) ? event.delta : {};
+        if (delta.type === "thinking_delta") {
+          const text = typeof delta.thinking === "string" ? delta.thinking : "";
+          this.onEvent(text ? { type: "thinking", text } : { type: "thinking-pulse" });
+        } else if (delta.type === "text_delta" && typeof delta.text === "string" && delta.text) {
+          this.text += delta.text;
+          this.onEvent({ type: "text", text: delta.text });
+        } else if (delta.type === "input_json_delta" && typeof delta.partial_json === "string" && delta.partial_json) {
+          this.partialJson += delta.partial_json;
+          this.onEvent({ type: "text", text: delta.partial_json });
+        }
+        break;
+      }
+      case "message_delta": {
+        if (isObject(event.usage)) this.recordUsage(event.usage);
+        break;
+      }
+      default:
+        break;
+    }
+  }
+  handleAssistant(message) {
+    if (!Array.isArray(message.content)) return;
+    for (const block of message.content) {
+      if (isObject(block) && block.type === "tool_use" && isObject(block.input)) {
+        this.messageStructured = JSON.stringify(block.input);
+      }
+    }
+  }
+  /** Tool results the CLI feeds back, e.g. a structured-output validation failure. */
+  handleUser(message) {
+    if (!Array.isArray(message.content)) return;
+    for (const block of message.content) {
+      if (!isObject(block) || block.type !== "tool_result" || block.is_error !== true) continue;
+      const content = typeof block.content === "string" ? block.content : JSON.stringify(block.content ?? "");
+      this.onEvent({ type: "notice", text: `Answer rejected (${content.replace(/^Output does not match required schema:\s*/i, "schema: ").slice(0, 300)}); the model is retrying` });
+    }
+  }
+  handleResult(ev) {
+    if (isObject(ev.structured_output)) this.resultStructured = JSON.stringify(ev.structured_output);
+    if (typeof ev.result === "string") this.resultText = ev.result;
+    const subtype = typeof ev.subtype === "string" ? ev.subtype : "";
+    if (ev.is_error === true || subtype.startsWith("error")) {
+      this.isError = true;
+      const errors = Array.isArray(ev.errors) ? ev.errors.filter((e) => typeof e === "string").join("; ") : "";
+      this.errorMessage = errors || typeof ev.result === "string" && ev.result || subtype || "unknown error";
+    }
+    if (isObject(ev.usage)) this.recordUsage(ev.usage);
+    if (typeof ev.total_cost_usd === "number") this.usage.costUsd = ev.total_cost_usd;
+    this.onEvent({ type: "usage", ...this.usage });
+  }
+  recordUsage(usage) {
+    if (typeof usage.output_tokens === "number") this.usage.outputTokens = usage.output_tokens;
+    const details = usage.output_tokens_details;
+    if (isObject(details) && typeof details.thinking_tokens === "number") this.usage.thinkingTokens = details.thinking_tokens;
+    this.onEvent({ type: "usage", ...this.usage });
+  }
+};
+
 // src/llm/command.ts
 import { spawn } from "child_process";
+import { StringDecoder } from "string_decoder";
 var STDERR_TAIL_LINES = 20;
+var CLAUDE_STREAM_ARGS = ["--output-format", "stream-json", "--verbose", "--include-partial-messages"];
 var CommandProvider = class {
   constructor(opts) {
     this.opts = opts;
     if (opts.command.length === 0) throw new LlmFailedError("LLM command is empty.");
   }
   opts;
+  get kind() {
+    return this.opts.kind ?? "plain";
+  }
   describe() {
     return this.opts.command.map(shellQuote).join(" ");
   }
-  complete(prompt) {
+  /** The full argv that will run, including any flags added for the command kind. */
+  argv(prompt) {
+    let argv = [...this.opts.command];
+    if (this.kind === "claude") {
+      argv.push(...CLAUDE_STREAM_ARGS);
+      if (this.opts.jsonSchema) argv.push("--json-schema", JSON.stringify(this.opts.jsonSchema));
+    }
+    if (prompt !== void 0 && this.opts.promptVia === "arg") argv = argv.map((a) => a.replaceAll("{prompt}", prompt));
+    return argv;
+  }
+  complete(prompt, opts = {}) {
     const { promptVia, timeoutMs } = this.opts;
-    const argv = promptVia === "arg" ? this.opts.command.map((a) => a.replaceAll("{prompt}", prompt)) : this.opts.command;
-    const [bin, ...args] = argv;
+    const onEvent = opts.onEvent ?? (() => {
+    });
+    const [bin, ...args] = this.argv(prompt);
     const debug = this.opts.debug ?? (() => {
     });
     const started = Date.now();
-    debug(`running ${this.describe()} (prompt ${Buffer.byteLength(prompt)} bytes via ${promptVia})`);
+    debug(`running ${this.describe()}${this.kind === "claude" ? " (+stream-json)" : ""} (prompt ${Buffer.byteLength(prompt)} bytes via ${promptVia})`);
     return new Promise((resolve, reject) => {
       const env = { ...process.env, ...this.opts.env };
       delete env.CLAUDECODE;
       const child = spawn(bin, args, { cwd: this.opts.cwd, env, stdio: ["pipe", "pipe", "pipe"] });
+      const parser = this.kind === "claude" ? new ClaudeStreamParser(onEvent) : null;
+      const decoder = new StringDecoder("utf8");
       const out = [];
       const err = [];
+      let outBytes = 0;
       let settled = false;
       const finish = (fn) => {
         if (settled) return;
@@ -1365,7 +1595,16 @@ var CommandProvider = class {
           hint: "Raise llm.timeoutMs in your config, or pick a faster preset."
         })));
       }, timeoutMs);
-      child.stdout.on("data", (b) => out.push(b));
+      onEvent({ type: "started" });
+      child.stdout.on("data", (b) => {
+        outBytes += b.length;
+        if (parser) {
+          parser.push(decoder.write(b));
+        } else {
+          out.push(b);
+          onEvent({ type: "output", bytes: outBytes });
+        }
+      });
       child.stderr.on("data", (b) => err.push(b));
       child.on("error", (e) => {
         finish(() => {
@@ -1378,15 +1617,33 @@ var CommandProvider = class {
       });
       child.on("close", (code, signal) => {
         finish(() => {
-          const stdout = Buffer.concat(out).toString("utf8");
           const stderr = Buffer.concat(err).toString("utf8");
-          debug(`command exited with ${signal ? `signal ${signal}` : `code ${code}`} after ${Date.now() - started}ms; ${stdout.length} bytes of stdout`);
+          const tail = stderr.trim().split("\n").slice(-STDERR_TAIL_LINES).join("\n");
+          debug(`command exited with ${signal ? `signal ${signal}` : `code ${code}`} after ${Date.now() - started}ms; ${outBytes} bytes of stdout`);
+          if (parser) {
+            parser.push(decoder.end());
+            const outcome = parser.finish();
+            if (outcome.unparsedLines) debug(`${outcome.unparsedLines} non-JSON line(s) on stdout were ignored`);
+            if (outcome.isError) {
+              reject(new LlmFailedError(`Claude reported an error: ${outcome.errorMessage ?? "unknown"}`, { hint: tail || void 0 }));
+              return;
+            }
+            if (code !== 0) {
+              reject(new LlmFailedError(`LLM command failed (${signal ? `signal ${signal}` : `exit ${code}`}): ${this.describe()}${tail ? "\n" + tail : ""}`));
+              return;
+            }
+            if (!outcome.result) {
+              reject(new LlmFailedError("Claude produced no result.", { hint: "Run with --debug to see what came back." }));
+              return;
+            }
+            resolve(outcome.result);
+            return;
+          }
           if (code !== 0) {
-            const tail = stderr.trim().split("\n").slice(-STDERR_TAIL_LINES).join("\n");
             reject(new LlmFailedError(`LLM command failed (${signal ? `signal ${signal}` : `exit ${code}`}): ${this.describe()}${tail ? "\n" + tail : ""}`));
             return;
           }
-          resolve(stdout);
+          resolve(Buffer.concat(out).toString("utf8"));
         });
       });
       if (promptVia === "stdin") {
@@ -1410,21 +1667,30 @@ function createProvider(llm, opts = {}) {
     command: llm.command,
     promptVia: llm.promptVia,
     timeoutMs: llm.timeoutMs,
+    kind: llm.kind,
+    jsonSchema: llm.kind === "claude" && llm.jsonSchema ? TOUR_JSON_SCHEMA : void 0,
     env: llm.env,
     cwd: opts.cwd,
     debug: opts.debug
   });
 }
 
+// src/core/progress.ts
+var noProgress = { phase() {
+}, llm() {
+} };
+
 // src/core/tour.ts
 async function prepareTour(opts) {
   const debug = opts.debug ?? (() => {
   });
   const warn = opts.warn ?? (() => {
   });
+  const progress = opts.progress ?? noProgress;
   const { config } = opts;
   const llm = resolveLlm(config);
   const codehost = opts.codehost ?? createCodeHost(config, { debug });
+  progress.phase("Working out what to tour");
   const resolved = await resolveRange(opts.range ?? {}, {
     cwd: opts.cwd,
     exclude: config.git.exclude,
@@ -1433,6 +1699,7 @@ async function prepareTour(opts) {
     debug
   });
   debug(`source: ${JSON.stringify(resolved.source)}`);
+  progress.phase("Collecting the diff");
   const diff = await collectDiff(resolved.source, { cwd: opts.cwd, exclude: config.git.exclude, warn });
   if (diff.files.length === 0) {
     throw new NoChangesError("The selected range has no changes (after excludes).", "Check git.exclude in your config, or pass a different range.");
@@ -1440,7 +1707,8 @@ async function prepareTour(opts) {
   const commits = await collectCommits(resolved.source, opts.cwd);
   const context = { source: resolved.source, branch: resolved.branch, diff, commits };
   if (resolved.pullRequest) context.pullRequest = resolved.pullRequest;
-  const built = buildPrompt({ ...context, maxBytes: llm.maxPromptBytes });
+  progress.phase("Building the prompt");
+  const built = buildPrompt({ ...context, maxBytes: llm.maxPromptBytes, structured: llm.kind === "claude" && llm.jsonSchema });
   if (built.truncation.truncated.length || built.truncation.omitted.length) {
     warn(`Prompt exceeded ${llm.maxPromptBytes} bytes; truncated ${built.truncation.truncated.length} and omitted ${built.truncation.omitted.length} file diff(s).`);
   }
@@ -1454,11 +1722,13 @@ async function generateTour(opts, prepared) {
   });
   const warn = opts.warn ?? (() => {
   });
+  const progress = opts.progress ?? noProgress;
   const { config } = opts;
   const prep = prepared ?? await prepareTour(opts);
   const useCache = config.cache.enabled && !opts.noCache;
   const cache = useCache ? new TourCache(opts.cacheDir) : null;
   if (cache && !opts.refresh) {
+    progress.phase("Checking the cache");
     const hit = await cache.get(prep.cacheKey);
     if (hit) {
       debug(`cache hit: ${cache.pathFor(prep.cacheKey)}`);
@@ -1468,7 +1738,9 @@ async function generateTour(opts, prepared) {
   }
   const llm = resolveLlm(config);
   const provider = opts.provider ?? createProvider(llm, { cwd: opts.cwd, debug });
-  const output = await completeWithRepair(provider, prep.built.prompt, debug);
+  progress.phase(`Asking ${llm.preset ?? llm.command[0]}`);
+  const output = await completeWithRepair(provider, prep.built.prompt, debug, progress);
+  progress.phase("Assembling the tour");
   const tour = materializeTour({
     output,
     diff: prep.context.diff,
@@ -1485,14 +1757,16 @@ async function generateTour(opts, prepared) {
   }
   return { tour, fromCache: false, cacheKey: cache ? prep.cacheKey : null, cachePath, prompt: prep.built.prompt };
 }
-async function completeWithRepair(provider, prompt, debug) {
-  let raw = await provider.complete(prompt);
+async function completeWithRepair(provider, prompt, debug, progress) {
+  const onEvent = (event) => progress.llm(event);
+  let raw = await provider.complete(prompt, { onEvent });
   debug(`raw model output (attempt 1):
 ${raw}`);
   const first = parseOutput(raw);
   if (first.ok) return first.value;
   debug(`attempt 1 unusable: ${first.reason}; retrying with repair prompt`);
-  raw = await provider.complete(prompt + REPAIR_SUFFIX(first.reason));
+  progress.phase("Asking again (the first answer was not valid JSON)");
+  raw = await provider.complete(prompt + REPAIR_SUFFIX(first.reason), { onEvent });
   debug(`raw model output (attempt 2):
 ${raw}`);
   const second = parseOutput(raw);
@@ -1513,12 +1787,222 @@ function parseOutput(raw) {
 
 // src/render/cli.ts
 import pc from "picocolors";
+
+// src/render/highlight.ts
+import { common, createLowlight } from "lowlight";
+var lowlight = createLowlight(common);
+var BY_EXT = {
+  ts: "typescript",
+  mts: "typescript",
+  cts: "typescript",
+  tsx: "typescript",
+  js: "javascript",
+  mjs: "javascript",
+  cjs: "javascript",
+  jsx: "javascript",
+  json: "json",
+  jsonc: "json",
+  json5: "json",
+  py: "python",
+  pyi: "python",
+  rb: "ruby",
+  rake: "ruby",
+  gemspec: "ruby",
+  go: "go",
+  rs: "rust",
+  java: "java",
+  kt: "kotlin",
+  kts: "kotlin",
+  swift: "swift",
+  scala: "scala",
+  c: "c",
+  h: "c",
+  cc: "cpp",
+  cpp: "cpp",
+  cxx: "cpp",
+  hpp: "cpp",
+  hh: "cpp",
+  cs: "csharp",
+  m: "objectivec",
+  mm: "objectivec",
+  php: "php",
+  pl: "perl",
+  pm: "perl",
+  lua: "lua",
+  r: "r",
+  dart: "dart",
+  sh: "bash",
+  bash: "bash",
+  zsh: "bash",
+  fish: "bash",
+  yml: "yaml",
+  yaml: "yaml",
+  toml: "ini",
+  ini: "ini",
+  cfg: "ini",
+  conf: "ini",
+  md: "markdown",
+  markdown: "markdown",
+  html: "xml",
+  htm: "xml",
+  xml: "xml",
+  svg: "xml",
+  vue: "xml",
+  css: "css",
+  scss: "scss",
+  less: "less",
+  sql: "sql",
+  graphql: "graphql",
+  gql: "graphql",
+  diff: "diff",
+  patch: "diff",
+  makefile: "makefile",
+  mk: "makefile",
+  vb: "vbnet",
+  vbnet: "vbnet",
+  wasm: "wasm"
+};
+var BY_NAME = {
+  makefile: "makefile",
+  gnumakefile: "makefile",
+  dockerfile: "bash",
+  rakefile: "ruby",
+  gemfile: "ruby",
+  ".bashrc": "bash",
+  ".zshrc": "bash",
+  ".profile": "bash",
+  "cmakelists.txt": "cmake"
+};
+function languageForPath(path) {
+  const base = path.slice(path.lastIndexOf("/") + 1).toLowerCase();
+  const byName = BY_NAME[base];
+  if (byName && lowlight.registered(byName)) return byName;
+  const dot = base.lastIndexOf(".");
+  if (dot === -1) return null;
+  const lang = BY_EXT[base.slice(dot + 1)];
+  return lang && lowlight.registered(lang) ? lang : null;
+}
+function stylers(c) {
+  return {
+    keyword: c.magenta,
+    "selector-tag": c.magenta,
+    "template-tag": c.magenta,
+    doctag: c.magenta,
+    string: c.yellow,
+    regexp: c.yellow,
+    "template-variable": c.yellow,
+    subst: (s) => s,
+    comment: c.gray,
+    quote: c.gray,
+    number: c.cyan,
+    literal: c.cyan,
+    symbol: c.cyan,
+    bullet: c.cyan,
+    link: c.cyan,
+    title: c.blue,
+    section: c.blue,
+    "selector-id": c.blue,
+    "selector-class": c.blue,
+    type: c.cyan,
+    built_in: c.cyan,
+    class: c.cyan,
+    attr: c.blue,
+    attribute: c.blue,
+    property: c.blue,
+    variable: (s) => s,
+    params: (s) => s,
+    meta: c.gray,
+    tag: c.blue,
+    name: c.blue,
+    "selector-attr": c.blue,
+    "selector-pseudo": c.blue,
+    addition: (s) => s,
+    deletion: (s) => s,
+    emphasis: c.italic,
+    strong: c.bold
+  };
+}
+function highlightCode(code, lang, c) {
+  if (!lowlight.registered(lang)) return null;
+  let tree;
+  try {
+    tree = lowlight.highlight(lang, code);
+  } catch {
+    return null;
+  }
+  const map = stylers(c);
+  const lines = [""];
+  const visit = (node, style) => {
+    if (node.type === "text" && typeof node.value === "string") {
+      const parts = node.value.split("\n");
+      parts.forEach((part, i) => {
+        if (i > 0) lines.push("");
+        if (part) lines[lines.length - 1] += style ? style(part) : part;
+      });
+      return;
+    }
+    let own = style;
+    for (const cls of node.properties?.className ?? []) {
+      const scope = cls.startsWith("hljs-") ? cls.slice(5) : cls;
+      const s = map[scope];
+      if (s) {
+        own = s;
+        break;
+      }
+    }
+    for (const child of node.children ?? []) visit(child, own);
+  };
+  visit(tree, null);
+  const expected = code.split("\n").length;
+  if (lines.length !== expected) return null;
+  return lines;
+}
+var ANSI_RE = /\x1b\[[0-9;]*m/g;
+function stripAnsi(s) {
+  return s.replace(ANSI_RE, "");
+}
+function visibleLength(s) {
+  return stripAnsi(s).length;
+}
+var SOFT_RESET = "\x1B[39m\x1B[22m\x1B[23m\x1B[24m";
+function truncateAnsi(s, max) {
+  if (visibleLength(s) <= max) return s;
+  let out = "";
+  let seen = 0;
+  const limit = Math.max(0, max - 1);
+  for (let i = 0; i < s.length; ) {
+    if (s[i] === "\x1B") {
+      const m = /^\x1b\[[0-9;]*m/.exec(s.slice(i));
+      if (m) {
+        out += m[0];
+        i += m[0].length;
+        continue;
+      }
+    }
+    if (seen >= limit) break;
+    out += s[i];
+    seen++;
+    i++;
+  }
+  return out + SOFT_RESET + "\u2026";
+}
+function lineTint(type, theme) {
+  const code = theme === "dark" ? type === "add" ? 22 : 52 : type === "add" ? 194 : 224;
+  return { open: `\x1B[48;5;${code}m`, close: "\x1B[49m" };
+}
+function supports256Colors(env = process.env) {
+  if (env.TERM === "dumb") return false;
+  return Boolean(env.COLORTERM) || /256color|truecolor|direct/i.test(env.TERM ?? "") || Boolean(env.TERM_PROGRAM) || Boolean(env.WT_SESSION);
+}
+
+// src/render/cli.ts
 var MIN_WIDTH = 40;
 var MAX_WIDTH = 120;
 var CliRenderer = class {
   render(tour, opts) {
     const c = pc.createColors(opts.color);
     const width = Math.max(MIN_WIDTH, Math.min(MAX_WIDTH, opts.width));
+    const style = { highlight: Boolean(opts.color && opts.highlight), theme: opts.theme ?? "dark" };
     const out = [];
     out.push(...renderHeader(tour, c, width, opts.fromCache ?? false));
     out.push("");
@@ -1527,12 +2011,12 @@ var CliRenderer = class {
       if (!section) {
         throw new UsageError(`No section ${opts.section}; this tour has ${tour.sections.length} section${tour.sections.length === 1 ? "" : "s"}.`);
       }
-      out.push(...renderSection(section, opts.section, tour.sections.length, c, width));
+      out.push(...renderSection(section, opts.section, tour.sections.length, c, width, style));
     } else {
       out.push(...renderToc(tour, c, width));
       out.push("");
       tour.sections.forEach((s, i) => {
-        out.push(...renderSection(s, i + 1, tour.sections.length, c, width));
+        out.push(...renderSection(s, i + 1, tour.sections.length, c, width, style));
         out.push("");
       });
     }
@@ -1566,12 +2050,12 @@ function renderToc(tour, c, width) {
     const label = `  ${n}. ${s.title}`;
     const right = `${s.stats.files} file${s.stats.files === 1 ? "" : "s"} \xB7 ${statsLine(s.stats, c, true)}`;
     const rightPlain = `${s.stats.files} file${s.stats.files === 1 ? "" : "s"} \xB7 +${s.stats.additions} -${s.stats.deletions}`;
-    const gap = Math.max(2, width - visibleLength(label) - rightPlain.length);
+    const gap = Math.max(2, width - visibleLength2(label) - rightPlain.length);
     lines.push(label + " ".repeat(gap) + c.dim(right));
   }
   return lines;
 }
-function renderSection(s, index, count, c, width) {
+function renderSection(s, index, count, c, width, style) {
   const lines = [];
   lines.push(c.dim("\u2500".repeat(width)));
   lines.push(c.bold(`${index}. ${s.title}`) + c.dim(`   (${index}/${count})`));
@@ -1586,26 +2070,41 @@ function renderSection(s, index, count, c, width) {
   }
   for (const e of s.excerpts) {
     lines.push("");
-    lines.push(...renderExcerpt(e, c, width));
+    lines.push(...renderExcerpt(e, c, width, style));
   }
   return lines;
 }
-function renderExcerpt(e, c, width) {
+function renderExcerpt(e, c, width, style) {
   const lines = [];
   const title = `   ${c.cyan(e.file)}${c.dim(":" + e.newStart)}`;
   lines.push(e.note ? `${title}  ${c.italic(c.dim(e.note))}` : title);
   const maxNo = Math.max(...e.lines.map((l) => Math.max(l.oldNo ?? 0, l.newNo ?? 0)), 1);
   const w = String(maxNo).length;
-  const budget = Math.max(20, width - (3 + w * 2 + 5));
-  for (const l of e.lines) {
+  const budget = Math.max(20, width - (3 + w * 2 + 3) - 1);
+  const texts = e.lines.map((l) => expandTabs(l.text));
+  const lang = style.highlight ? languageForPath(e.file) : null;
+  const highlighted = lang ? highlightCode(texts.join("\n"), lang, c) : null;
+  e.lines.forEach((l, i) => {
     const oldNo = l.oldNo === void 0 ? " ".repeat(w) : String(l.oldNo).padStart(w);
     const newNo = l.newNo === void 0 ? " ".repeat(w) : String(l.newNo).padStart(w);
     const sign = l.type === "add" ? "+" : l.type === "del" ? "-" : " ";
-    const text = truncate(expandTabs(l.text), budget);
     const gutter = c.dim(`   ${oldNo} ${newNo} \u2502`);
-    const body = `${sign}${text}`;
-    lines.push(`${gutter}${l.type === "add" ? c.green(body) : l.type === "del" ? c.red(body) : body}`);
-  }
+    const plain = texts[i];
+    if (!highlighted) {
+      const body = `${sign}${truncate(plain, budget)}`;
+      lines.push(`${gutter}${l.type === "add" ? c.green(body) : l.type === "del" ? c.red(body) : body}`);
+      return;
+    }
+    const text = truncateAnsi(highlighted[i], budget);
+    const pad = " ".repeat(Math.max(0, budget - visibleLength(text)));
+    if (l.type === "ctx") {
+      lines.push(`${gutter} ${text}`);
+      return;
+    }
+    const tint = lineTint(l.type, style.theme);
+    const signStyled = l.type === "add" ? c.green(c.bold("+")) : c.red(c.bold("-"));
+    lines.push(`${gutter}${tint.open}${signStyled}${text}${pad}${tint.close}`);
+  });
   return lines;
 }
 function statsLine(stats, c, omitFiles = false) {
@@ -1645,7 +2144,7 @@ function truncate(s, max) {
 function expandTabs(s) {
   return s.replaceAll("	", "    ");
 }
-function visibleLength(s) {
+function visibleLength2(s) {
   return s.replace(/\x1b\[[0-9;]*m/g, "").length;
 }
 function relativeTime(iso, now = /* @__PURE__ */ new Date()) {
@@ -1727,6 +2226,7 @@ export {
   materializeTour,
   sliceHunk,
   PROMPT_VERSION,
+  promptHeader,
   buildPrompt,
   describeSource,
   GhCodeHost,
@@ -1739,10 +2239,14 @@ export {
   collectCommits,
   resolveRange,
   detectDefaultBranch,
+  TOUR_JSON_SCHEMA,
+  ClaudeStreamParser,
   CommandProvider,
   createProvider,
+  noProgress,
   prepareTour,
   generateTour,
+  supports256Colors,
   CliRenderer,
   describeSource2,
   wrap,
@@ -1750,4 +2254,4 @@ export {
   writeMaybePaged,
   writeStdout
 };
-//# sourceMappingURL=chunk-RWSCST2I.js.map
+//# sourceMappingURL=chunk-7ALXKEST.js.map