muonroi-cli 1.3.4 → 1.4.1

package/src/council/llm.ts

@@ -1,967 +0,0 @@
-import * as fs from "node:fs";
-import type { ToolSet } from "ai";
-import { generateText, stepCountIs } from "ai";
-import { getDefaultEEClient } from "../ee/intercept.js";
-import { emitMatches } from "../ee/render.js";
-import type { McpToolBundle } from "../mcp/runtime.js";
-import { buildMcpToolSet } from "../mcp/runtime.js";
-import { loadKeyForProvider } from "../providers/keychain.js";
-import { createProviderFactory, detectProviderForModel, resolveModelRuntime } from "../providers/runtime.js";
-import type { BashTool } from "../tools/bash.js";
-import { createBuiltinTools as createTools } from "../tools/registry.js";
-import type { AgentMode, CouncilStatusPhase, StreamChunk } from "../types/index.js";
-import { appendCostLog } from "../usage/cost-log.js";
-import { projectCostUSD } from "../usage/estimator.js";
-import { loadMcpServers } from "../utils/settings.js";
-import { withVisibleRetry } from "../utils/visible-retry.js";
-import { buildResearchSystemPrompt } from "./prompts.js";
-import type { CouncilLLM, CouncilStats, ToolTraceEmitter, UsageCallback } from "./types.js";
-
-// ── Debug logging (off unless MUONROI_COUNCIL_DEBUG_LOG points at a writable file) ──
-//
-// Writes a JSONL record per llm.{generate,debate,research} call with full input
-// sizes, output text, reasoning text, finish reason, usage tokens, and errors.
-// Used by scripts/e2e-council-debug.ts to confirm WHY a turn returned empty —
-// e.g. reasoning model exhausting maxTokens on thinking-only output.
-
-interface DebugCallRecord {
-  ts: string;
-  kind: "generate" | "debate" | "research";
-  modelId: string;
-  resolvedModelId?: string;
-  provider?: string;
-  systemChars: number;
-  promptChars: number;
-  maxTokens?: number;
-  durationMs: number;
-  ok: boolean;
-  textChars: number;
-  textHead: string;
-  reasoningChars?: number;
-  reasoningHead?: string;
-  finishReason?: string;
-  toolCallCount?: number;
-  toolNames?: string[];
-  usage?: unknown;
-  error?: string;
-}
-
-function getDebugLogPath(): string | null {
-  const p = process.env.MUONROI_COUNCIL_DEBUG_LOG;
-  return p && p.length > 0 ? p : null;
-}
-
-function writeDebugRecord(rec: DebugCallRecord): void {
-  const path = getDebugLogPath();
-  if (!path) return;
-  try {
-    fs.appendFileSync(path, JSON.stringify(rec) + "\n", "utf-8");
-  } catch {
-    // Logging must never break the council run.
-  }
-}
-
-function head(s: unknown, n = 300): string {
-  const str = typeof s === "string" ? s : s == null ? "" : String(s);
-  return str.length > n ? str.slice(0, n) + "…" : str;
-}
-
-// ── Tool trace helpers (CQ-22) ────────────────────────────────────────────────
-
-const TRACE_ARG_LIMIT = 2048;
-
-function truncate(value: unknown): string {
-  const s = typeof value === "string" ? value : (JSON.stringify(value) ?? "");
-  return s.length > TRACE_ARG_LIMIT ? s.slice(0, TRACE_ARG_LIMIT) + "…[truncated]" : s;
-}
-
-function emitToolTrace(toolName: string, args: unknown, result: unknown, persistTrace?: ToolTraceEmitter): void {
-  if (!persistTrace) return;
-  const traceText = `[Council Tool Trace] tool=${toolName} ` + `args=${truncate(args)} ` + `result=${truncate(result)}`;
-  persistTrace(traceText);
-}
-
-/**
- * Maximum size (in characters) of any single tool result that we feed back to
- * the model between debate steps. Without this cap a single grep / web-fetch
- * can put 100s of KB into the next step's context, and with stepCountIs(4)
- * the per-call message stack inflates quadratically across rounds — the root
- * cause of "Request Entity Too Large" and 3M-token-against-1M-limit errors
- * we observed in real sessions.
- *
- * 8KB per tool result × 4 steps × N participants × rounds keeps the worst
- * case in the hundreds-of-KB range instead of the multi-MB range, while
- * preserving enough content for evidence-based debate.
- */
-const TOOL_RESULT_CAP_CHARS = 8000;
-
-function capToolResult(result: unknown): unknown {
-  if (result == null) return result;
-  if (typeof result === "string") {
-    return result.length > TOOL_RESULT_CAP_CHARS
-      ? result.slice(0, TOOL_RESULT_CAP_CHARS) +
-          `\n…[truncated to ${TOOL_RESULT_CAP_CHARS} chars by council to protect context]`
-      : result;
-  }
-  try {
-    const serialized = JSON.stringify(result);
-    if (serialized.length <= TOOL_RESULT_CAP_CHARS) return result;
-    // Object too large — fall back to a string summary so the model still has
-    // a usable, smaller payload instead of the raw blob.
-    return {
-      _truncated: true,
-      _originalSize: serialized.length,
-      preview: serialized.slice(0, TOOL_RESULT_CAP_CHARS) + "…",
-    };
-  } catch {
-    return result;
-  }
-}
-
-/**
- * Wrap each tool in the set with EE PreToolUse intercept check AND cap the
- * result size that flows back into the LLM between steps. Both behaviors are
- * applied for every debate-time tool call.
- */
-function wrapToolsWithEeCheck(tools: ToolSet, tenantId: string): ToolSet {
-  const wrapped: ToolSet = {};
-  for (const [name, tool] of Object.entries(tools)) {
-    if (!tool || typeof (tool as { execute?: unknown }).execute !== "function") {
-      wrapped[name] = tool;
-      continue;
-    }
-    wrapped[name] = {
-      ...tool,
-      execute: async (args: unknown, opts: unknown) => {
-        // Fire EE PreToolUse intercept (non-blocking, fail-open)
-        try {
-          const client = getDefaultEEClient();
-          const resp = await client.intercept({
-            toolName: name,
-            toolInput: args,
-            cwd: process.cwd(),
-            tenantId,
-            scope: { kind: "global" },
-          });
-          emitMatches(resp?.matches);
-        } catch {
-          /* fail-open — tool must execute regardless */
-        }
-        const raw = await (tool as { execute: (args: unknown, opts: unknown) => unknown }).execute(args, opts);
-        return capToolResult(raw);
-      },
-    };
-  }
-  return wrapped;
-}
-
-/**
- * Extract token counts from an AI SDK `generateText` result.usage object.
- * Defensive — different providers expose slightly different field names.
- */
-function extractUsage(raw: unknown): { inputTokens: number; outputTokens: number; cachedInputTokens: number } {
-  const u = (raw ?? {}) as Record<string, unknown>;
-  const details = (u.inputTokenDetails ?? {}) as Record<string, unknown>;
-  const rawNested = (u.raw ?? {}) as Record<string, unknown>;
-  const num = (v: unknown): number => (typeof v === "number" && Number.isFinite(v) ? v : 0);
-  return {
-    inputTokens: num(u.inputTokens) || num(u.promptTokens),
-    outputTokens: num(u.outputTokens) || num(u.completionTokens),
-    cachedInputTokens:
-      num(u.cachedInputTokens) || num(details.cacheReadTokens) || num(rawNested.prompt_cache_hit_tokens),
-  };
-}
-
-/**
- * Best-effort cost-log append for council LLM calls. Failures are swallowed.
- * Returns the parsed usage so callers can forward it via an onUsage callback
- * (sprint-runner uses this to commit with real token counts, not chars/4).
- */
-function logCouncilCost(args: {
-  callsite: string;
-  role?: string;
-  provider: string;
-  modelId: string;
-  rawUsage: unknown;
-  systemChars: number;
-  promptChars: number;
-  durationMs: number;
-  stepCount?: number;
-}): { inputTokens: number; outputTokens: number; cachedInputTokens: number } {
-  const usage = extractUsage(args.rawUsage);
-  appendCostLog({
-    ts: Date.now() - args.durationMs,
-    provider: args.provider,
-    model: args.modelId,
-    estimatedUsd: projectCostUSD(args.provider, args.modelId, usage.inputTokens, usage.outputTokens),
-    callsite: args.callsite,
-    role: args.role,
-    phase: "council",
-    systemChars: args.systemChars,
-    promptChars: args.promptChars,
-    actualInputTokens: usage.inputTokens,
-    actualOutputTokens: usage.outputTokens,
-    cachedInputTokens: usage.cachedInputTokens,
-    stepCount: args.stepCount,
-    durationMs: args.durationMs,
-  }).catch(() => undefined);
-  return usage;
-}
-
-// ── Mock-LLM bypass (agent harness / E2E tests) ──────────────────────────────
-//
-// When `globalThis.__muonroiMockLlm` is set (injected by --mock-llm startup),
-// council LLM calls are short-circuited through the mock fixture rather than
-// hitting a real provider.  This mirrors the hook already present in
-// src/providers/adapter.ts for the streaming path.
-
-declare global {
-  // biome-ignore lint/suspicious/noExplicitAny: intentionally untyped global
-  var __muonroiMockLlm: any;
-}
-
-function getMockLlm(): { complete(req: { prompt: string }): Promise<{ text: string }> } | null {
-  // biome-ignore lint/suspicious/noExplicitAny: intentionally untyped global access
-  return (globalThis as any).__muonroiMockLlm ?? null;
-}
-
-/**
- * Per-LLM-call deadline. Without this, a stuck TCP connection to a provider
- * (e.g. api.deepseek.com going silent mid-stream) makes a single generateText
- * call hang forever. `runDebate` uses Promise.all per round so one stuck pair
- * freezes the whole round and the TUI shows "composing…" indefinitely.
- *
- * Range 60_000–1_800_000 ms. Default 300_000 (5 minutes) — generous enough
- * for reasoning models that take 2-3 min on long prompts, tight enough that
- * a truly dead socket fails fast and `debateWithRetry` can fall back.
- */
-const COUNCIL_LLM_TIMEOUT_MS = (() => {
-  const raw = Number.parseInt(process.env.MUONROI_COUNCIL_LLM_TIMEOUT_MS ?? "", 10);
-  if (Number.isFinite(raw) && raw >= 60_000 && raw <= 1_800_000) return raw;
-  return 300_000;
-})();
-
-/**
- * Combine an optional parent AbortSignal with a wall-clock deadline. Returns
- * the merged signal plus a `cleanup` thunk the caller must invoke once the
- * underlying request settles so the timeout timer doesn't keep the process
- * alive past the call.
- */
-function withTimeoutSignal(
-  parent: AbortSignal | undefined,
-  timeoutMs: number,
-): { signal: AbortSignal; cleanup: () => void } {
-  const controller = new AbortController();
-  const timer = setTimeout(() => {
-    controller.abort(new Error(`council LLM call exceeded ${timeoutMs}ms deadline (timeout)`));
-  }, timeoutMs);
-  let parentListener: (() => void) | null = null;
-  if (parent) {
-    if (parent.aborted) {
-      clearTimeout(timer);
-      controller.abort(parent.reason);
-    } else {
-      parentListener = () => controller.abort(parent.reason);
-      parent.addEventListener("abort", parentListener, { once: true });
-    }
-  }
-  return {
-    signal: controller.signal,
-    cleanup: () => {
-      clearTimeout(timer);
-      if (parent && parentListener) parent.removeEventListener("abort", parentListener);
-    },
-  };
-}
-
-/**
- * Race a promise against a wall-clock deadline. AI SDK occasionally fails to
- * honour `abortSignal` mid-tool-execution (observed: deepseek-v4-flash with
- * MCP verification tools sitting on a stuck firecrawl HTTP request, the
- * controller.abort fires but generateText keeps awaiting the tool result).
- * This race guarantees the surrounding code receives an Error within
- * `deadlineMs`, regardless of what the SDK does internally. The in-flight
- * request is still aborted via `controller.abort` for cleanup; this layer
- * just ensures the caller is not blocked past the deadline.
- */
-async function withDeadlineRace<T>(fn: () => Promise<T>, deadlineMs: number, label: string): Promise<T> {
-  let timer: ReturnType<typeof setTimeout> | null = null;
-  const deadline = new Promise<never>((_, reject) => {
-    timer = setTimeout(() => {
-      reject(new Error(`${label} exceeded ${deadlineMs}ms deadline (timeout)`));
-    }, deadlineMs);
-  });
-  try {
-    return await Promise.race([fn(), deadline]);
-  } finally {
-    if (timer) clearTimeout(timer);
-  }
-}
-
-export function createCouncilLLM(
-  bash: BashTool,
-  mode: AgentMode,
-  sessionId: string | undefined,
-  stats: CouncilStats,
-): CouncilLLM {
-  return {
-    async generate(
-      modelId: string,
-      system: string,
-      prompt: string,
-      maxTokens = 4096,
-      onUsage?: UsageCallback,
-    ): Promise<string> {
-      const mock = getMockLlm();
-      if (mock) {
-        stats.calls++;
-        const result = await mock.complete({ prompt });
-        return result.text;
-      }
-      const providerId = detectProviderForModel(modelId);
-      const key = await loadKeyForProvider(providerId);
-      const { factory } = createProviderFactory(providerId, { apiKey: key });
-      const runtime = resolveModelRuntime(factory, modelId);
-      const t0 = Date.now();
-      const { signal: timedSignal, cleanup: cleanupTimeout } = withTimeoutSignal(undefined, COUNCIL_LLM_TIMEOUT_MS);
-      try {
-        const result = await withDeadlineRace(
-          () =>
-            withVisibleRetry(
-              () =>
-                generateText({
-                  model: runtime.model,
-                  system,
-                  prompt,
-                  maxOutputTokens: maxTokens,
-                  temperature: 0.7,
-                  // Visible retry (src/utils/visible-retry.ts) replaces SDK's silent
-                  // exponential backoff (2,4,8,16,32s). When SiliconFlow rate-limits
-                  // with 429, user now sees "[retry] rate-limited (429) — waiting Xs
-                  // before attempt N/6" instead of a 62s blank window that looks hung.
-                  maxRetries: 0,
-                  ...(runtime.providerOptions ? { providerOptions: runtime.providerOptions } : {}),
-                  abortSignal: timedSignal,
-                }),
-              { label: "council.generate" },
-            ),
-          COUNCIL_LLM_TIMEOUT_MS + 5_000,
-          "council.generate",
-        );
-        cleanupTimeout();
-        stats.calls++;
-        const durMs = Date.now() - t0;
-        const callUsage = logCouncilCost({
-          callsite: "council.generate",
-          provider: providerId,
-          modelId,
-          rawUsage: (result as { usage?: unknown }).usage,
-          systemChars: system.length,
-          promptChars: prompt.length,
-          durationMs: durMs,
-        });
-        onUsage?.(callUsage);
-        writeDebugRecord({
-          ts: new Date().toISOString(),
-          kind: "generate",
-          modelId,
-          resolvedModelId: runtime.modelInfo?.id,
-          provider: providerId,
-          systemChars: system.length,
-          promptChars: prompt.length,
-          maxTokens,
-          durationMs: durMs,
-          ok: true,
-          textChars: (result.text ?? "").length,
-          textHead: head(result.text),
-          reasoningChars: (result as { reasoningText?: string }).reasoningText?.length,
-          reasoningHead: head((result as { reasoningText?: string }).reasoningText ?? ""),
-          finishReason: (result as { finishReason?: string }).finishReason,
-          usage: (result as { usage?: unknown }).usage,
-        });
-        return result.text;
-      } catch (err) {
-        cleanupTimeout();
-        writeDebugRecord({
-          ts: new Date().toISOString(),
-          kind: "generate",
-          modelId,
-          resolvedModelId: runtime.modelInfo?.id,
-          provider: providerId,
-          systemChars: system.length,
-          promptChars: prompt.length,
-          maxTokens,
-          durationMs: Date.now() - t0,
-          ok: false,
-          textChars: 0,
-          textHead: "",
-          error: err instanceof Error ? err.message : String(err),
-        });
-        throw err;
-      }
-    },
-
-    async debate(
-      modelId: string,
-      system: string,
-      prompt: string,
-      signal?: AbortSignal,
-      persistTrace?: ToolTraceEmitter,
-      options?: { enableVerificationTools?: boolean },
-      onUsage?: UsageCallback,
-    ): Promise<{ text: string; toolCalls: Array<{ toolName: string; result?: unknown }> }> {
-      const mock = getMockLlm();
-      if (mock) {
-        stats.calls++;
-        const result = await mock.complete({ prompt });
-        return { text: result.text, toolCalls: [] };
-      }
-      const providerId = detectProviderForModel(modelId);
-      const key = await loadKeyForProvider(providerId);
-      const { factory } = createProviderFactory(providerId, { apiKey: key });
-      const runtime = resolveModelRuntime(factory, modelId);
-
-      // Verification tools — re-introduced after the no-tools fix (session
-      // a7a5690d2049). The original failure was stepCountIs(4) + full toolset
-      // letting reasoning models exhaust steps on exploratory tool chains and
-      // return text="" finishReason="tool-calls". We now expose a TINY
-      // read-only set (grep, read_file) under stepCountIs(2) — at most one
-      // verification call, then forced text. Tier gate: only balanced/premium
-      // models get tools (fast/reasoning-heavy Flash variants skip them).
-      let verificationTools: ToolSet | undefined;
-      let mcpBundleForDebate: McpToolBundle | null = null;
-      if (options?.enableVerificationTools) {
-        try {
-          const builtins = createTools(bash, mode);
-          // Strict allowlist — NO bash/edit/write/task in debate verification.
-          const ALLOWED = new Set(["grep", "read_file"]);
-          const filtered: ToolSet = {};
-          for (const [name, tool] of Object.entries(builtins)) {
-            if (ALLOWED.has(name)) filtered[name] = tool;
-          }
-          // Optional MCP read-only tools (web_fetch / web_search / context7).
-          try {
-            mcpBundleForDebate = await buildMcpToolSet(loadMcpServers());
-            if (mcpBundleForDebate?.tools) {
-              for (const [name, tool] of Object.entries(mcpBundleForDebate.tools)) {
-                if (/tavily|web[_-]?fetch|web[_-]?search|context7|firecrawl|exa/i.test(name)) {
-                  filtered[name] = tool;
-                }
-              }
-            }
-          } catch {
-            /* MCP optional — debate continues with builtins only */
-          }
-          verificationTools = wrapToolsWithEeCheck(filtered, sessionId ?? "council-debate");
-        } catch {
-          /* fail-open: no tools */
-        }
-      }
-
-      const t0 = Date.now();
-      const { signal: timedSignal, cleanup: cleanupTimeout } = withTimeoutSignal(signal, COUNCIL_LLM_TIMEOUT_MS);
-      try {
-        const result = await withDeadlineRace(
-          () =>
-            withVisibleRetry(
-              () =>
-                generateText({
-                  model: runtime.model,
-                  system,
-                  prompt,
-                  ...(verificationTools && Object.keys(verificationTools).length > 0
-                    ? { tools: verificationTools, stopWhen: stepCountIs(2) }
-                    : {}),
-                  // Reasoning models (deepseek-v4-*, anthropic thinking) consume part
-                  // of this budget on reasoning_tokens before producing user-visible
-                  // text. E2E showed 2048 caused finishReason=length on 3KB debate
-                  // prompts. 6144 leaves ~4000 tokens for text after typical reasoning
-                  // overhead and avoids cuts mid-thought.
-                  maxOutputTokens: 6144,
-                  temperature: 0.7,
-                  // Visible retry (src/utils/visible-retry.ts) replaces SDK's silent
-                  // exponential backoff (2,4,8,16,32s). When SiliconFlow rate-limits
-                  // with 429, user now sees "[retry] rate-limited (429) — waiting Xs
-                  // before attempt N/6" instead of a 62s blank window that looks hung.
-                  maxRetries: 0,
-                  ...(runtime.providerOptions ? { providerOptions: runtime.providerOptions } : {}),
-                  abortSignal: timedSignal,
-                }),
-              { label: "council.debate" },
-            ),
-          COUNCIL_LLM_TIMEOUT_MS + 5_000,
-          "council.debate",
-        );
-        cleanupTimeout();
-        stats.calls++;
-        // No tool calls expected, but the AI SDK shape still has the field —
-        // pass through for type compatibility.
-        const toolCalls = (result.toolCalls ?? []) as Array<{
-          toolName: string;
-          args?: unknown;
-          input?: unknown;
-          result?: unknown;
-        }>;
-        for (const tc of toolCalls) {
-          emitToolTrace(tc.toolName, tc.args ?? tc.input ?? {}, tc.result, persistTrace);
-        }
-        const debateUsage = logCouncilCost({
-          callsite: "council.debate",
-          role: "debater",
-          provider: providerId,
-          modelId,
-          rawUsage: (result as { usage?: unknown }).usage,
-          systemChars: system.length,
-          promptChars: prompt.length,
-          durationMs: Date.now() - t0,
-          stepCount: toolCalls.length,
-        });
-        onUsage?.(debateUsage);
-        writeDebugRecord({
-          ts: new Date().toISOString(),
-          kind: "debate",
-          modelId,
-          resolvedModelId: runtime.modelInfo?.id,
-          provider: providerId,
-          systemChars: system.length,
-          promptChars: prompt.length,
-          maxTokens: 6144,
-          durationMs: Date.now() - t0,
-          ok: true,
-          textChars: (result.text ?? "").length,
-          textHead: head(result.text),
-          reasoningChars: (result as { reasoningText?: string }).reasoningText?.length,
-          reasoningHead: head((result as { reasoningText?: string }).reasoningText ?? ""),
-          finishReason: (result as { finishReason?: string }).finishReason,
-          toolCallCount: toolCalls.length,
-          toolNames: toolCalls.map((t) => t.toolName),
-          usage: (result as { usage?: unknown }).usage,
-        });
-        return {
-          text: result.text,
-          toolCalls: toolCalls as Array<{ toolName: string; result?: unknown }>,
-        };
-      } catch (err: unknown) {
-        cleanupTimeout();
-        const errMsg = err instanceof Error ? err.message : String(err);
-        writeDebugRecord({
-          ts: new Date().toISOString(),
-          kind: "debate",
-          modelId,
-          resolvedModelId: runtime.modelInfo?.id,
-          provider: providerId,
-          systemChars: system.length,
-          promptChars: prompt.length,
-          maxTokens: 6144,
-          durationMs: Date.now() - t0,
-          ok: false,
-          textChars: 0,
-          textHead: "",
-          error: errMsg,
-        });
-        return { text: `[debate failed: ${errMsg}]`, toolCalls: [] };
-      } finally {
-        await mcpBundleForDebate?.close().catch(() => {});
-      }
-    },
-
-    async research(
-      modelId: string,
-      topic: string,
-      conversationContext: string,
-      signal?: AbortSignal,
-      persistTrace?: ToolTraceEmitter,
-      options?: { internetFirst?: boolean },
-      onUsage?: UsageCallback,
-    ): Promise<string> {
-      const mock = getMockLlm();
-      if (mock) {
-        stats.calls++;
-        const result = await mock.complete({ prompt: topic });
-        return result.text;
-      }
-      const providerId = detectProviderForModel(modelId);
-      const key = await loadKeyForProvider(providerId);
-      const { factory } = createProviderFactory(providerId, { apiKey: key });
-      const runtime = resolveModelRuntime(factory, modelId);
-
-      const builtinTools = createTools(bash, mode);
-
-      // CQ-03: Lazy MCP bundle per research call — fail-open so builtins remain available
-      let mcpBundle: McpToolBundle | null = null;
-      try {
-        mcpBundle = await buildMcpToolSet(loadMcpServers());
-      } catch {
-        // MCP spawn failed — research continues with builtin tools only
-      }
-
-      const mergedResearchTools: ToolSet = { ...builtinTools, ...(mcpBundle?.tools ?? {}) };
-      const allTools: ToolSet = wrapToolsWithEeCheck(mergedResearchTools, sessionId ?? "council-research");
-
-      // CQ-04: Detect URL in topic — inject mandatory browser instruction into system prompt
-      const hasUrl = /https?:\/\/\S+/.test(topic);
-      const internetFirst = options?.internetFirst === true;
-      const systemPrompt = buildResearchSystemPrompt(hasUrl, internetFirst);
-
-      // Warn early if internet-first mode is requested but no internet/browser tools are loaded.
-      const internetToolAvailable = Object.keys(allTools).some((n) =>
-        /tavily|web[_-]?fetch|web[_-]?search|playwright|chrome|context7|firecrawl|exa/i.test(n),
-      );
-      const internetGapWarning =
-        internetFirst && !internetToolAvailable
-          ? `\n\n## Research Gap\n- Internet-first mode requested but no browser/search tool ` +
-            `(tavily, web-fetch, playwright, chrome-devtools, context7) is available. ` +
-            `Findings will be limited to what the model already knows.`
-          : "";
-
-      const userPrompt = conversationContext
-        ? `## Context\n${conversationContext}\n\n---\n\n## Research Topic\n${topic}\n\nInvestigate and report findings.`
-        : `## Research Topic\n${topic}\n\nInvestigate and report findings.`;
-
-      const t0 = Date.now();
-      // Research is multi-step tool-using so give it 2x the standard deadline.
-      const researchTimeoutMs = Math.min(COUNCIL_LLM_TIMEOUT_MS * 2, 1_800_000);
-      const { signal: timedSignal, cleanup: cleanupTimeout } = withTimeoutSignal(signal, researchTimeoutMs);
-      try {
-        const result = await withDeadlineRace(
-          () =>
-            withVisibleRetry(
-              () =>
-                generateText({
-                  model: runtime.model,
-                  system: systemPrompt,
-                  prompt: userPrompt,
-                  tools: allTools,
-                  stopWhen: stepCountIs(15),
-                  maxOutputTokens: 4096,
-                  temperature: 0.3,
-                  // Visible retry (src/utils/visible-retry.ts) replaces SDK's silent
-                  // exponential backoff (2,4,8,16,32s). When SiliconFlow rate-limits
-                  // with 429, user now sees "[retry] rate-limited (429) — waiting Xs
-                  // before attempt N/6" instead of a 62s blank window that looks hung.
-                  maxRetries: 0,
-                  ...(runtime.providerOptions ? { providerOptions: runtime.providerOptions } : {}),
-                  abortSignal: timedSignal,
-                }),
-              { label: "council.research" },
-            ),
-          researchTimeoutMs + 5_000,
-          "council.research",
-        );
-        cleanupTimeout();
-        const researchUsage = logCouncilCost({
-          callsite: "council.research",
-          role: "researcher",
-          provider: providerId,
-          modelId,
-          rawUsage: (result as { usage?: unknown }).usage,
-          systemChars: systemPrompt.length,
-          promptChars: userPrompt.length,
-          durationMs: Date.now() - t0,
-          stepCount: (result.toolCalls ?? []).length,
-        });
-        onUsage?.(researchUsage);
-        writeDebugRecord({
-          ts: new Date().toISOString(),
-          kind: "research",
-          modelId,
-          resolvedModelId: runtime.modelInfo?.id,
-          provider: providerId,
-          systemChars: systemPrompt.length,
-          promptChars: userPrompt.length,
-          maxTokens: 4096,
-          durationMs: Date.now() - t0,
-          ok: true,
-          textChars: (result.text ?? "").length,
-          textHead: head(result.text),
-          reasoningChars: (result as { reasoningText?: string }).reasoningText?.length,
-          reasoningHead: head((result as { reasoningText?: string }).reasoningText ?? ""),
-          finishReason: (result as { finishReason?: string }).finishReason,
-          toolCallCount: (result.toolCalls ?? []).length,
-          toolNames: (result.toolCalls ?? []).map((t) => (t as { toolName: string }).toolName),
-          usage: (result as { usage?: unknown }).usage,
-        });
-
-        // Emit tool traces (CQ-22)
-        const researchToolCalls = (result.toolCalls ?? []) as Array<{
-          toolName: string;
-          args?: unknown;
-          input?: unknown;
-          result?: unknown;
-        }>;
-        for (const tc of researchToolCalls) {
-          emitToolTrace(tc.toolName, tc.args ?? tc.input ?? {}, tc.result, persistTrace);
-        }
-
-        // CQ-04: When URL present, verify at least one browser tool was invoked
-        if (hasUrl) {
-          // Use result.toolCalls (flat array across all steps) — more reliably typed than steps[].toolCalls
-          const browserUsed = researchToolCalls.some(
-            (tc) => tc.toolName.includes("playwright") || tc.toolName.includes("chrome"),
-          );
-          if (!browserUsed) {
-            stats.calls++;
-            return (
-              result.text +
-              "\n\n## Research Gap\n" +
-              "- URL was present in topic but no browser tool was invoked. " +
-              "Frontend findings unverified."
-            );
-          }
-        }
-
-        stats.calls++;
-        return result.text + internetGapWarning;
-      } catch (err: unknown) {
-        cleanupTimeout();
-        const errMsg = err instanceof Error ? err.message : String(err);
-        writeDebugRecord({
-          ts: new Date().toISOString(),
-          kind: "research",
-          modelId,
-          resolvedModelId: runtime.modelInfo?.id,
-          provider: providerId,
-          systemChars: systemPrompt.length,
-          promptChars: userPrompt.length,
-          maxTokens: 4096,
-          durationMs: Date.now() - t0,
-          ok: false,
-          textChars: 0,
-          textHead: "",
-          error: errMsg,
-        });
-        return (
-          `## Source Code Findings\n[Research failed: ${errMsg}]\n\n` +
-          `## Internet Findings\n_Not performed._\n\n` +
-          `## Frontend Findings (live)\n_Not performed._`
-        );
-      } finally {
-        await mcpBundle?.close().catch(() => {});
-      }
-    },
-  };
-}
-
-interface TracedGenerateArgs {
-  phase: CouncilStatusPhase;
-  label: string;
-  detail?: string;
-  role?: string;
-  modelId: string;
-  system: string;
-  prompt: string;
-  maxTokens?: number;
-  /** Tick interval in ms. Default 1000. Set 0 to disable ticks. */
-  tickIntervalMs?: number;
-}
-
-/**
- * Wraps `llm.generate` with start/tick/done status chunks so the UI can show
- * a live spinner row (e.g. `● Researching codebase... (12s)`).
- *
- * Returns the generated text via the AsyncGenerator return value.
- */
-export async function* tracedGenerate(
-  llm: CouncilLLM,
-  args: TracedGenerateArgs,
-): AsyncGenerator<StreamChunk, string, unknown> {
-  const statusId =
-    typeof crypto !== "undefined" && "randomUUID" in crypto
-      ? crypto.randomUUID()
-      : `status-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
-  const start = Date.now();
-  const tickInterval = args.tickIntervalMs ?? 1000;
-
-  yield {
-    type: "council_status",
-    councilStatus: {
-      statusId,
-      state: "start",
-      phase: args.phase,
-      label: args.label,
-      detail: args.detail,
-      role: args.role,
-      elapsedMs: 0,
-    },
-  };
-
-  // Race generate vs ticks: drain ticks between generate slices using Promise.race.
-  let resolved = false;
-  let resultText = "";
-  let resultErr: unknown = null;
-
-  const generatePromise = (async () => {
-    try {
-      resultText = await llm.generate(args.modelId, args.system, args.prompt, args.maxTokens);
-    } catch (err) {
-      resultErr = err;
-    } finally {
-      resolved = true;
-    }
-  })();
-
-  while (!resolved) {
-    if (tickInterval <= 0) {
-      await generatePromise;
-      break;
-    }
-    const tickPromise = new Promise<void>((resolve) => setTimeout(resolve, tickInterval));
-    await Promise.race([generatePromise, tickPromise]);
-    if (resolved) break;
-    yield {
-      type: "council_status",
-      councilStatus: {
-        statusId,
-        state: "tick",
-        phase: args.phase,
-        label: args.label,
-        detail: args.detail,
-        role: args.role,
-        elapsedMs: Date.now() - start,
-      },
-    };
-  }
-
-  await generatePromise;
-
-  if (resultErr) {
-    const errMsg = resultErr instanceof Error ? resultErr.message : String(resultErr);
-    yield {
-      type: "council_status",
-      councilStatus: {
-        statusId,
-        state: "error",
-        phase: args.phase,
-        label: args.label,
-        detail: args.detail,
-        role: args.role,
-        elapsedMs: Date.now() - start,
-        errorMessage: errMsg,
-      },
-    };
-    throw resultErr;
-  }
-
-  yield {
-    type: "council_status",
-    councilStatus: {
-      statusId,
-      state: "done",
-      phase: args.phase,
-      label: args.label,
-      detail: args.detail,
-      role: args.role,
-      elapsedMs: Date.now() - start,
-    },
-  };
-
-  return resultText;
-}
-
-interface TracedAsyncArgs {
-  phase: CouncilStatusPhase;
-  label: string;
-  detail?: string;
-  role?: string;
-  tickIntervalMs?: number;
-}
-
-/**
- * Generic version of {@link tracedGenerate} for arbitrary async work
- * (e.g. `llm.research`, `Promise.all` over multiple model calls).
- */
-export async function* tracedAsync<T>(
-  fn: () => Promise<T>,
-  args: TracedAsyncArgs,
-): AsyncGenerator<StreamChunk, T, unknown> {
-  const statusId =
-    typeof crypto !== "undefined" && "randomUUID" in crypto
-      ? crypto.randomUUID()
-      : `status-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
-  const start = Date.now();
-  const tickInterval = args.tickIntervalMs ?? 1000;
-
-  yield {
-    type: "council_status",
-    councilStatus: {
-      statusId,
-      state: "start",
-      phase: args.phase,
-      label: args.label,
-      detail: args.detail,
-      role: args.role,
-      elapsedMs: 0,
-    },
-  };
-
-  let resolved = false;
-  let result: T | undefined;
-  let err: unknown = null;
-
-  const work = (async () => {
-    try {
-      result = await fn();
-    } catch (e) {
-      err = e;
-    } finally {
-      resolved = true;
-    }
-  })();
-
-  while (!resolved) {
-    if (tickInterval <= 0) {
-      await work;
-      break;
-    }
-    const tick = new Promise<void>((resolve) => setTimeout(resolve, tickInterval));
-    await Promise.race([work, tick]);
-    if (resolved) break;
-    yield {
-      type: "council_status",
-      councilStatus: {
-        statusId,
-        state: "tick",
-        phase: args.phase,
-        label: args.label,
-        detail: args.detail,
-        role: args.role,
-        elapsedMs: Date.now() - start,
-      },
-    };
-  }
-
-  await work;
-
-  if (err) {
-    const errMsg = err instanceof Error ? err.message : String(err);
-    yield {
-      type: "council_status",
-      councilStatus: {
-        statusId,
-        state: "error",
-        phase: args.phase,
-        label: args.label,
-        detail: args.detail,
-        role: args.role,
-        elapsedMs: Date.now() - start,
-        errorMessage: errMsg,
-      },
-    };
-    throw err;
-  }
-
-  yield {
-    type: "council_status",
-    councilStatus: {
-      statusId,
-      state: "done",
-      phase: args.phase,
-      label: args.label,
-      detail: args.detail,
-      role: args.role,
-      elapsedMs: Date.now() - start,
-    },
-  };
-
-  return result as T;
-}