muonroi-cli 1.2.3 → 1.3.1

package/src/tools/registry.ts

@@ -7,40 +7,63 @@
  */
 
 import { dynamicTool, jsonSchema, type ToolSet } from "ai";
+import { analyzeImageFromSource, askVisionProxy, listCachedImages } from "../providers/mcp-vision-bridge.js";
+import { needsVisionProxy } from "../providers/vision-proxy.js";
+import type { AgentMode, TaskRequest, ToolResult } from "../types/index.js";
 import type { BashTool } from "./bash.js";
-import { readFile, writeFile, editFile } from "./file.js";
+import { editFile, readFile, writeFile } from "./file.js";
+import { FileTracker } from "./file-tracker.js";
 import { executeGrep } from "./grep.js";
-import type { ToolResult, TaskRequest } from "../types/index.js";
-import type { AgentMode } from "../types/index.js";
 
 interface ToolRegistryOpts {
   runTask?: (request: TaskRequest, abortSignal?: AbortSignal) => Promise<ToolResult>;
   runDelegation?: (request: TaskRequest, abortSignal?: AbortSignal) => Promise<ToolResult>;
   readDelegation?: (id: string) => Promise<ToolResult>;
   listDelegations?: () => Promise<ToolResult>;
+  modelId?: string;
 }
 
-const MAX_TOOL_OUTPUT_CHARS = 12_000;
+/**
+ * Default per-tool-call output cap in characters (~8k tokens).
+ *
+ * Read-side tools (read_file, grep, bash, process_logs) previously returned
+ * raw output uncapped, so a single large file read could dump ~28k tokens
+ * straight into the next LLM prompt. We now apply the cap uniformly to all
+ * tool results (head/tail-preserving), which is the primary cost-leak fix
+ * for sub-agent loops that read multiple files in one turn.
+ *
+ * Override with env `MUONROI_MAX_TOOL_OUTPUT_CHARS` (10_000–200_000).
+ */
+const DEFAULT_MAX_TOOL_OUTPUT_CHARS = 32_000;
+
+function resolveMaxToolOutputChars(): number {
+  const raw = process.env.MUONROI_MAX_TOOL_OUTPUT_CHARS;
+  if (!raw) return DEFAULT_MAX_TOOL_OUTPUT_CHARS;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n < 10_000 || n > 200_000) return DEFAULT_MAX_TOOL_OUTPUT_CHARS;
+  return Math.floor(n);
+}
+
+export const MAX_TOOL_OUTPUT_CHARS = resolveMaxToolOutputChars();
 
-function truncateOutput(text: string, maxChars = MAX_TOOL_OUTPUT_CHARS): string {
+export function truncateOutput(text: string, maxChars = MAX_TOOL_OUTPUT_CHARS): string {
   if (text.length <= maxChars) return text;
   const half = Math.floor(maxChars / 2);
-  return `${text.slice(0, half)}\n\n... [${text.length - maxChars} chars truncated] ...\n\n${text.slice(-half)}`;
+  return `${text.slice(0, half)}\n\n... [${text.length - maxChars} chars truncated; full output in transcript] ...\n\n${text.slice(-half)}`;
 }
 
 function formatResult(result: ToolResult): string {
   if (result.success) {
-    return result.output ?? "OK";
+    return truncateOutput(result.output ?? "OK");
   }
-  return `ERROR: ${result.error ?? result.output ?? "Unknown error"}`;
+  return truncateOutput(`ERROR: ${result.error ?? result.output ?? "Unknown error"}`);
 }
 
-export function createBuiltinTools(
-  bash: BashTool,
-  mode: AgentMode,
-  opts?: ToolRegistryOpts,
-): ToolSet {
+export function createBuiltinTools(bash: BashTool, mode: AgentMode, opts?: ToolRegistryOpts): ToolSet {
   const tools: ToolSet = {};
+  // One tracker per tool registry instance — shared across read/write/edit
+  // calls in the same session. Enforces "must read before edit/overwrite".
+  const fileTracker = new FileTracker();
 
   // read_file
   tools.read_file = dynamicTool({
@@ -55,14 +78,15 @@ export function createBuiltinTools(
       required: ["file_path"],
     }),
     execute: async (input: any) => {
-      const result = readFile(input.file_path, bash.getCwd(), input.start_line, input.end_line);
+      const result = readFile(input.file_path, bash.getCwd(), input.start_line, input.end_line, fileTracker);
       return formatResult(result);
     },
   });
 
   // grep
   tools.grep = dynamicTool({
-    description: "Fast regex content search across the codebase using ripgrep. Returns matching lines with file paths and line numbers.",
+    description:
+      "Fast regex content search across the codebase using ripgrep. Returns matching lines with file paths and line numbers.",
     inputSchema: jsonSchema({
       type: "object",
       properties: {
@@ -153,7 +177,8 @@ export function createBuiltinTools(
   if (mode === "agent") {
     // write_file
     tools.write_file = dynamicTool({
-      description: "Create a new file or overwrite an existing file with full content.",
+      description:
+        "Create a new file or overwrite an existing file with full content. SAFETY: overwriting an existing file requires you to call read_file on it first in the same session. New-file creation does not.",
       inputSchema: jsonSchema({
         type: "object",
         properties: {
@@ -163,7 +188,7 @@ export function createBuiltinTools(
         required: ["file_path", "content"],
       }),
       execute: async (input: any) => {
-        const result = await writeFile(input.file_path, input.content, bash.getCwd());
+        const result = await writeFile(input.file_path, input.content, bash.getCwd(), fileTracker);
         return {
           success: result.success,
           output: truncateOutput(result.output ?? ""),
@@ -175,7 +200,8 @@ export function createBuiltinTools(
 
     // edit_file
     tools.edit_file = dynamicTool({
-      description: "Replace a unique string in a file with new content. The old_string must appear exactly once.",
+      description:
+        "Replace a unique string in a file with new content. The old_string must appear exactly once. SAFETY: you must call read_file on the target in the same session before editing; if the file changed on disk after your read, re-read it first.",
       inputSchema: jsonSchema({
         type: "object",
         properties: {
@@ -186,7 +212,7 @@ export function createBuiltinTools(
         required: ["file_path", "old_string", "new_string"],
       }),
       execute: async (input: any) => {
-        const result = await editFile(input.file_path, input.old_string, input.new_string, bash.getCwd());
+        const result = await editFile(input.file_path, input.old_string, input.new_string, bash.getCwd(), fileTracker);
         return {
           success: result.success,
           output: truncateOutput(result.output ?? ""),
@@ -200,20 +226,22 @@ export function createBuiltinTools(
     if (opts?.runTask) {
       const runTask = opts.runTask;
       tools.task = dynamicTool({
-        description: "Delegate a focused foreground task to a sub-agent. Types: general (edit/execute), explore (read-only research), verify (sandbox validation), computer (desktop interaction).",
+        description:
+          "Delegate a focused foreground task to a sub-agent. Types: general (edit/execute), explore (read-only research), verify (sandbox validation), computer (desktop interaction).",
         inputSchema: jsonSchema({
           type: "object",
           properties: {
-            agent: { type: "string", description: "Sub-agent type: general, explore, verify, computer, or a custom sub-agent name" },
+            agent: {
+              type: "string",
+              description: "Sub-agent type: general, explore, verify, computer, or a custom sub-agent name",
+            },
             description: { type: "string", description: "Short description of the task" },
             prompt: { type: "string", description: "Detailed instructions for the sub-agent" },
           },
           required: ["agent", "description", "prompt"],
         }),
         execute: async (input: any) => {
-          const result = await runTask(
-            { agent: input.agent, description: input.description, prompt: input.prompt },
-          );
+          const result = await runTask({ agent: input.agent, description: input.description, prompt: input.prompt });
           return formatResult(result);
         },
       });
@@ -234,9 +262,11 @@ export function createBuiltinTools(
           required: ["agent", "description", "prompt"],
         }),
         execute: async (input: any) => {
-          const result = await runDelegation(
-            { agent: input.agent, description: input.description, prompt: input.prompt },
-          );
+          const result = await runDelegation({
+            agent: input.agent,
+            description: input.description,
+            prompt: input.prompt,
+          });
           return formatResult(result);
         },
       });
@@ -278,5 +308,81 @@ export function createBuiltinTools(
     }
   }
 
+  // Vision proxy tools — only for text-only models (DeepSeek, etc.)
+  if (opts?.modelId && needsVisionProxy(opts.modelId)) {
+    const cwd = bash.getCwd();
+
+    tools.analyze_image = dynamicTool({
+      description:
+        "Proactively analyze an image file via the vision proxy. " +
+        "Use this IMMEDIATELY when you encounter any image file (.png, .jpg, .gif, .webp, .svg, etc.) " +
+        "or when the user references an image. You CANNOT see images — this tool is your eyes. " +
+        "Accepts file paths, data URIs, or base64 strings. " +
+        "Optionally provide a question to focus the analysis.",
+      inputSchema: jsonSchema({
+        type: "object",
+        properties: {
+          image_source: {
+            type: "string",
+            description: "File path to the image, a data URI (data:image/...), or raw base64 string",
+          },
+          question: {
+            type: "string",
+            description:
+              "Optional specific question to focus the analysis (e.g. 'what text is in this image?', 'describe the layout')",
+          },
+        },
+        required: ["image_source"],
+      }),
+      execute: async (input: any) => {
+        return analyzeImageFromSource(input.image_source, input.question, cwd);
+      },
+    });
+
+    tools.ask_vision_proxy = dynamicTool({
+      description:
+        "Ask a follow-up question about a previously analyzed image, or analyze a new image with a specific question. " +
+        "Use this when you need to clarify visual details, compare elements, check colors, read text, etc. " +
+        "You can reference a cached image by ID, or provide a file path to analyze a new image.",
+      inputSchema: jsonSchema({
+        type: "object",
+        properties: {
+          question: {
+            type: "string",
+            description: "Your specific question about the image",
+          },
+          image_id_or_path: {
+            type: "string",
+            description:
+              "Cached image ID (e.g. img_1) OR a file path to a new image. If omitted, uses the most recent image.",
+          },
+        },
+        required: ["question"],
+      }),
+      execute: async (input: any) => {
+        return askVisionProxy(input.question, input.image_id_or_path, cwd);
+      },
+    });
+
+    tools.list_vision_cache = dynamicTool({
+      description:
+        "List all cached images available for ask_vision_proxy queries. " +
+        "Shows image IDs, sources, labels, and ages.",
+      inputSchema: jsonSchema({
+        type: "object",
+        properties: {},
+      }),
+      execute: async () => {
+        const cached = listCachedImages();
+        if (cached.length === 0) {
+          return "No cached images. Use analyze_image to analyze an image file, or take a screenshot with browser_take_screenshot.";
+        }
+        return cached
+          .map((c) => `${c.id}: ${c.label} (${c.source}, ${c.age})${c.hasDescription ? " [analyzed]" : ""}`)
+          .join("\n");
+      },
+    });
+  }
+
   return tools;
 }

package/src/types/index.ts

@@ -110,6 +110,7 @@ export interface VerifyRecipe {
   smokeTarget?: string;
   evidence: string[];
   notes: string[];
+  coverage?: number | null;
 }
 
 export interface VerifyEnvironmentManifest {
@@ -217,8 +218,159 @@ export interface StructuredResponse {
   data: Record<string, unknown>;
 }
 
+export type CouncilQuestionPhase = "clarify" | "preflight" | "plan-confirm" | "post-debate";
+
+export type CouncilOptionKind = "choice" | "freetext" | "chat";
+
+export interface CouncilQuestionOption {
+  label: string;
+  description?: string;
+  value: string;
+  kind: CouncilOptionKind;
+}
+
+export interface CouncilQuestionData {
+  questionId: string;
+  question: string;
+  context?: string;
+  /** @deprecated use options[] */
+  suggestions?: string[];
+  isRequired: boolean;
+  phase?: CouncilQuestionPhase;
+  options?: CouncilQuestionOption[];
+  defaultIndex?: number;
+}
+
+export type CouncilStatusPhase =
+  | "clarify"
+  | "plan_debate"
+  | "research"
+  | "opening"
+  | "exchange"
+  | "evaluate"
+  | "synthesis"
+  | "summary";
+
+export type CouncilStatusState = "start" | "tick" | "done" | "error";
+
+export interface CouncilStatusData {
+  statusId: string;
+  state: CouncilStatusState;
+  phase: CouncilStatusPhase;
+  label: string;
+  detail?: string;
+  role?: string;
+  elapsedMs?: number;
+  tokensIn?: number;
+  tokensOut?: number;
+  errorMessage?: string;
+}
+
+/** High-level lifecycle event for a council phase. Drives the phase timeline UI. */
+export type CouncilPhaseKind =
+  | "clarification"
+  | "clarification_round"
+  | "preflight"
+  | "debate_plan"
+  | "research"
+  | "opening"
+  | "round"
+  | "evaluation"
+  | "mid_research"
+  | "summary"
+  | "synthesis"
+  | "action_plan";
+
+export type CouncilPhaseState = "active" | "done" | "error";
+
+export interface CouncilPhaseEvent {
+  /** Stable id for upserts; e.g. "phase:research", "phase:round-1". */
+  phaseId: string;
+  kind: CouncilPhaseKind;
+  state: CouncilPhaseState;
+  label: string;
+  detail?: string;
+  elapsedMs?: number;
+  errorMessage?: string;
+  /** Monotonic ordering hint; ties broken by insertion order. */
+  sequence?: number;
+}
+
+export interface CouncilPreflightData {
+  preflightId: string;
+  problemStatement: string;
+  constraints: string[];
+  successCriteria: string[];
+  scope: string;
+  participants: Array<{ role: string; model: string }>;
+  researchNeeded: boolean;
+  /** True when the working directory has no source code — research should prefer internet. */
+  repoEmpty?: boolean;
+  /** True when the user can override the research decision after approving the brief. */
+  researchOverridable?: boolean;
+}
+
+export interface ExperienceWarningData {
+  confidence: number;
+  message: string;
+  why: string;
+  scopeLabel: string;
+  principleUuid: string;
+}
+
+export interface ExperienceInjectedData {
+  pointCount: number;
+  pointIds: string[];
+  scoreFloor: number;
+  taskType?: string;
+  domain?: string;
+}
+
+export type CouncilMessageKind = "debate" | "leader" | "synthesis" | "research";
+
+export interface CouncilInfoCardSection {
+  heading: string;
+  body: string;
+}
+
+export interface CouncilInfoCard {
+  title: string;
+  sections: CouncilInfoCardSection[];
+}
+
+export interface CouncilMessage {
+  kind: CouncilMessageKind;
+  speaker: { role: string; model: string };
+  partner?: { role: string }; // debate turns only
+  round?: number; // debate / leader only
+  text: string; // raw markdown body
+  toolCalls?: { name: string }[];
+  attempts?: number; // >1 → "recovered on retry" badge
+  failureReason?: string; // present → render inline skipped line, not a bubble
+  runId?: string; // reserved for future multi-session demux
+}
+
 export interface StreamChunk {
-  type: "content" | "tool_calls" | "tool_result" | "tool_approval_request" | "done" | "error" | "reasoning" | "structured_response";
+  type:
+    | "content"
+    | "tool_calls"
+    | "tool_result"
+    | "tool_approval_request"
+    | "council_question"
+    | "council_preflight"
+    | "council_status"
+    | "council_phase"
+    | "council_message"
+    | "council_info_card"
+    | "done"
+    | "error"
+    | "reasoning"
+    | "structured_response"
+    | "product_status_card"
+    | "experience_warning"
+    | "experience_injected"
+    | "push_notification"
+    | "halt";
   content?: string;
   toolCalls?: ToolCall[];
   toolCall?: ToolCall;
@@ -227,6 +379,17 @@ export interface StreamChunk {
   paymentPrecheck?: PaymentPrecheck;
   isAuthError?: boolean;
   structuredResponse?: StructuredResponse;
+  councilQuestion?: CouncilQuestionData;
+  councilPreflight?: CouncilPreflightData;
+  councilStatus?: CouncilStatusData;
+  councilPhase?: CouncilPhaseEvent;
+  councilMessage?: CouncilMessage;
+  councilInfoCard?: CouncilInfoCard;
+  productStatusCard?: import("../product-loop/types.js").ProductStatusCardData;
+  /** Populated when type === "halt". Contains structured recovery options. */
+  haltChunk?: import("../product-loop/types.js").HaltChunk;
+  experienceWarning?: ExperienceWarningData;
+  experienceInjected?: ExperienceInjectedData;
 }
 
 export type ReasoningEffort = "low" | "medium" | "high" | "xhigh";
@@ -256,8 +419,8 @@ export interface ModelInfo {
 }
 
 export type AgentMode = "agent" | "plan" | "ask";
-export type SessionStatus = "active" | "archived";
-export type UsageSource = "message" | "title" | "task" | "delegation" | "other";
+export type SessionStatus = "active" | "completed" | "archived";
+export type UsageSource = "message" | "title" | "task" | "delegation" | "council" | "other";
 
 export interface WorkspaceInfo {
   id: string;