@within-7/minto 0.1.7 → 0.3.0

package/dist/utils/toolRiskClassification.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/utils/toolRiskClassification.ts"],
+  "sourcesContent": ["/**\n * Tool Risk Classification System\n *\n * Classifies tools into three risk levels for the Smart Safety Mode:\n * - safe: Read-only operations, no side effects\n * - monitored: Has side effects but reversible/low risk\n * - dangerous: Potentially destructive, requires confirmation\n */\n\nexport type RiskLevel = 'safe' | 'monitored' | 'dangerous'\n\n/**\n * Default risk levels for each tool type\n */\nexport const TOOL_RISK_LEVELS: Record<string, RiskLevel> = {\n  // \uD83D\uDFE2 Safe layer: Read-only, no side effects\n  Read: 'safe',\n  Glob: 'safe',\n  Grep: 'safe',\n  LS: 'safe',\n  WebSearch: 'safe',\n  WebFetch: 'safe',\n  Think: 'safe',\n  AskUserQuestion: 'safe',\n  MemoryRead: 'safe',\n  NotebookRead: 'safe',\n  TaskOutput: 'safe',\n  EnterPlanMode: 'safe',\n  ExitPlanMode: 'safe',\n  TaskList: 'safe',\n  TaskGet: 'safe',\n  Skill: 'safe',\n\n  // \uD83D\uDFE1 Monitored layer: Has side effects but reversible/low risk\n  Edit: 'monitored',\n  Write: 'monitored',\n  NotebookEdit: 'monitored',\n  MemoryWrite: 'monitored',\n  TodoWrite: 'monitored',\n  Task: 'monitored',\n  TaskCreate: 'monitored',\n  TaskUpdate: 'monitored',\n  TaskStop: 'monitored',\n\n  // \uD83D\uDD34 Dangerous layer: Requires confirmation (Bash handled separately)\n  Bash: 'dangerous',\n  MCPTool: 'dangerous',\n}\n\n/**\n * Safe Bash command patterns - automatically allowed even in Smart/Strict mode\n * These patterns match common development commands that are low-risk\n */\nexport const SAFE_BASH_PATTERNS: RegExp[] = [\n  // Git - all common operations\n  /^git\\s+(status|diff|log|branch|show|remote|fetch|pull|push|commit|add|checkout|merge|rebase|stash|tag|clone|init|config|rev-parse|symbolic-ref)/i,\n\n  // File viewing (read-only)\n  /^ls(\\s|$)/i,\n  /^cat\\s/i,\n  /^head\\s/i,\n  /^tail\\s/i,\n  /^pwd$/i,\n  /^echo\\s/i,\n  /^which\\s/i,\n  /^tree(\\s|$)/i,\n  /^date$/i,\n  /^whoami$/i,\n  /^find\\s/i,\n  /^wc\\s/i,\n  /^grep\\s/i,\n  /^rg\\s/i,\n  /^less\\s/i,\n  /^more\\s/i,\n  /^file\\s/i,\n  /^stat\\s/i,\n  /^du\\s/i,\n  /^df\\s/i,\n\n  // Package managers - common development operations\n  /^npm\\s+(install|i|ci|run|test|start|build|list|ls|outdated|view|info|init|publish|pack|version|audit|dedupe)/i,\n  /^npx\\s/i,\n  /^bun\\s+(install|i|add|remove|run|test|build|pm|create|init|link|unlink|update|outdated)/i,\n  /^bunx\\s/i,\n  /^yarn\\s+(install|add|remove|run|test|build|init|create|link|unlink|upgrade|outdated)/i,\n  /^pnpm\\s+(install|i|add|remove|run|test|build|init|create|link|unlink|update|outdated)/i,\n  /^pip\\s+(install|list|show|freeze|check)/i,\n  /^pip3\\s+(install|list|show|freeze|check)/i,\n  /^poetry\\s+(install|add|remove|run|build|init|check|show)/i,\n  /^cargo\\s+(build|run|test|check|clippy|fmt|doc|bench|new|init|add|remove)/i,\n  /^go\\s+(build|run|test|get|mod|fmt|vet|generate)/i,\n  /^composer\\s+(install|require|remove|update|dump-autoload)/i,\n  /^gem\\s+(install|list|update)/i,\n  /^bundle\\s+(install|exec|update)/i,\n\n  // Version queries\n  /^(node|npm|bun|yarn|pnpm|python|python3|pip|pip3|cargo|rustc|go|java|ruby|php)\\s+(--version|-v|-V)$/i,\n  /^(node|npm|bun|yarn|pnpm|python|python3|pip|pip3|cargo|rustc|go|java|ruby|php)\\s+-version$/i,\n\n  // Build and test tools\n  /^make(\\s|$)/i,\n  /^cmake\\s/i,\n  /^ninja(\\s|$)/i,\n  /^pytest(\\s|$)/i,\n  /^jest(\\s|$)/i,\n  /^vitest(\\s|$)/i,\n  /^mocha(\\s|$)/i,\n  /^ava(\\s|$)/i,\n  /^tape(\\s|$)/i,\n  /^tap(\\s|$)/i,\n  /^tsc(\\s|$)/i,\n  /^eslint(\\s|$)/i,\n  /^prettier(\\s|$)/i,\n  /^biome(\\s|$)/i,\n\n  // Docker (read-only and common operations)\n  /^docker\\s+(ps|images|logs|inspect|version|info|stats|top|port|diff)/i,\n  /^docker\\s+(build|run|exec|pull|push|start|stop|restart)/i,\n  /^docker-compose\\s+(ps|logs|config|up|down|build|pull|restart)/i,\n\n  // Kubernetes (read-only)\n  /^kubectl\\s+(get|describe|logs|explain|version|config|cluster-info)/i,\n\n  // Environment and shell\n  /^env$/i,\n  /^printenv/i,\n  /^export\\s/i,\n  /^source\\s/i,\n  /^\\.\\s/i,\n\n  // Process viewing\n  /^ps(\\s|$)/i,\n  /^top$/i,\n  /^htop$/i,\n\n  // Network diagnostics (read-only)\n  /^ping\\s/i,\n  /^traceroute\\s/i,\n  /^dig\\s/i,\n  /^nslookup\\s/i,\n  /^host\\s/i,\n  /^ifconfig$/i,\n  /^ip\\s+(addr|link|route)/i,\n\n  // Archive viewing\n  /^tar\\s+(-t|--list)/i,\n  /^unzip\\s+-l/i,\n  /^zipinfo\\s/i,\n\n  // Text processing\n  /^sort(\\s|$)/i,\n  /^uniq(\\s|$)/i,\n  /^cut(\\s|$)/i,\n  /^awk\\s/i,\n  /^sed\\s/i,\n  /^tr\\s/i,\n  /^diff\\s/i,\n  /^md5sum\\s/i,\n  /^sha256sum\\s/i,\n\n  // Directory operations (safe)\n  /^mkdir\\s/i,\n  /^touch\\s/i,\n  /^cp\\s/i,\n  /^mv\\s/i,\n]\n\n/**\n * Dangerous Bash command patterns - always require confirmation\n * These patterns match potentially destructive commands\n */\nexport const DANGEROUS_BASH_PATTERNS: RegExp[] = [\n  // File deletion\n  /\\brm\\s/i,\n  /\\brmdir\\s/i,\n  /\\bunlink\\s/i,\n\n  // Privilege escalation\n  /\\bsudo\\s/i,\n  /\\bsu\\s/i,\n  /\\bdoas\\s/i,\n  /\\bpkexec\\s/i,\n\n  // Permission changes\n  /\\bchmod\\s/i,\n  /\\bchown\\s/i,\n  /\\bchgrp\\s/i,\n\n  // Disk operations\n  /\\bmkfs\\b/i,\n  /\\bfdisk\\s/i,\n  /\\bparted\\s/i,\n  /\\bdd\\s+if=/i,\n  /\\bshred\\s/i,\n\n  // System control\n  /\\bsystemctl\\s/i,\n  /\\bservice\\s/i,\n  /\\breboot\\b/i,\n  /\\bshutdown\\s/i,\n  /\\bhalt\\b/i,\n  /\\bpoweroff\\b/i,\n\n  // Dangerous redirections\n  />\\s*\\/(?!tmp|dev\\/null)/i, // Redirect to root paths (except /tmp and /dev/null)\n  />\\s*~\\//i, // Redirect to home directory paths\n\n  // Shell execution from network\n  /\\|\\s*(bash|sh|zsh|fish)/i,\n  /curl.*\\|\\s*(bash|sh)/i,\n  /wget.*\\|\\s*(bash|sh)/i,\n\n  // Environment destruction\n  /\\bkillall\\s/i,\n  /\\bpkill\\s/i,\n  /kill\\s+-9/i,\n\n  // Network dangerous\n  /\\bnc\\s+-l/i, // netcat listen mode\n  /\\biptables\\s/i,\n  /\\bufw\\s/i,\n\n  // Crontab\n  /\\bcrontab\\s+-r/i,\n\n  // Git destructive\n  /\\bgit\\s+(reset\\s+--hard|clean\\s+-f|push\\s+--force|push\\s+-f)/i,\n]\n\n/**\n * Classify a Bash command into a risk level\n *\n * @param command The bash command to classify\n * @returns The risk level of the command\n */\nexport function classifyBashCommand(command: string): RiskLevel {\n  // Trim and normalize whitespace\n  const normalizedCommand = command.trim().replace(/\\s+/g, ' ')\n\n  // Check dangerous patterns first (higher priority)\n  if (DANGEROUS_BASH_PATTERNS.some(p => p.test(normalizedCommand))) {\n    return 'dangerous'\n  }\n\n  // Check safe patterns\n  if (SAFE_BASH_PATTERNS.some(p => p.test(normalizedCommand))) {\n    return 'safe'\n  }\n\n  // Default to monitored (allows in Smart mode, asks in Strict mode)\n  return 'monitored'\n}\n\n/**\n * Get the risk level for a tool\n *\n * @param toolName The name of the tool\n * @param input Optional tool input for command-specific classification\n * @returns The risk level of the tool\n */\nexport function getToolRiskLevel(\n  toolName: string,\n  input?: { command?: string },\n): RiskLevel {\n  // Special handling for Bash commands\n  if (toolName === 'Bash' && input?.command) {\n    return classifyBashCommand(input.command)\n  }\n\n  // Look up in the static table\n  return TOOL_RISK_LEVELS[toolName] ?? 'dangerous'\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/utils/toolTimeout.js

@@ -0,0 +1,136 @@
+const TOOL_TIMEOUTS = {
+  /** Quick read-only operations (file read, grep, glob) */
+  FAST: 3e4,
+  // 30 seconds
+  /** Standard operations (most tools) */
+  STANDARD: 12e4,
+  // 2 minutes
+  /** Long-running operations (bash commands, web fetch) */
+  LONG: 6e5,
+  // 10 minutes
+  /** Extended operations (task agents, complex builds) */
+  EXTENDED: 18e5,
+  // 30 minutes
+  /** No timeout (special cases only) */
+  NONE: 0
+};
+const TOOL_TIMEOUT_CONFIG = {
+  // Fast operations (30s)
+  Read: TOOL_TIMEOUTS.FAST,
+  View: TOOL_TIMEOUTS.FAST,
+  Grep: TOOL_TIMEOUTS.FAST,
+  Glob: TOOL_TIMEOUTS.FAST,
+  LS: TOOL_TIMEOUTS.FAST,
+  LSP: TOOL_TIMEOUTS.FAST,
+  // Standard operations (2min)
+  Write: TOOL_TIMEOUTS.STANDARD,
+  Edit: TOOL_TIMEOUTS.STANDARD,
+  MultiEdit: TOOL_TIMEOUTS.STANDARD,
+  NotebookEdit: TOOL_TIMEOUTS.STANDARD,
+  TodoWrite: TOOL_TIMEOUTS.STANDARD,
+  TodoRead: TOOL_TIMEOUTS.STANDARD,
+  MemoryRead: TOOL_TIMEOUTS.STANDARD,
+  MemoryWrite: TOOL_TIMEOUTS.STANDARD,
+  AskUser: TOOL_TIMEOUTS.STANDARD,
+  Think: TOOL_TIMEOUTS.STANDARD,
+  // Long operations (10min)
+  Bash: TOOL_TIMEOUTS.LONG,
+  WebFetch: TOOL_TIMEOUTS.LONG,
+  WebSearch: TOOL_TIMEOUTS.LONG,
+  mcp__: TOOL_TIMEOUTS.LONG,
+  // MCP tools prefix
+  // Extended operations (30min)
+  Task: TOOL_TIMEOUTS.EXTENDED
+};
+function getToolTimeout(toolName) {
+  if (toolName in TOOL_TIMEOUT_CONFIG) {
+    return TOOL_TIMEOUT_CONFIG[toolName];
+  }
+  for (const [prefix, timeout] of Object.entries(TOOL_TIMEOUT_CONFIG)) {
+    if (prefix.endsWith("__") && toolName.startsWith(prefix)) {
+      return timeout;
+    }
+  }
+  return TOOL_TIMEOUTS.STANDARD;
+}
+class ToolTimeoutError extends Error {
+  toolName;
+  timeoutMs;
+  constructor(toolName, timeoutMs) {
+    super(
+      `Tool '${toolName}' execution timed out after ${Math.round(timeoutMs / 1e3)} seconds`
+    );
+    this.name = "ToolTimeoutError";
+    this.toolName = toolName;
+    this.timeoutMs = timeoutMs;
+  }
+}
+async function* withTimeout(generator, toolName, timeoutMs) {
+  const actualTimeout = timeoutMs ?? getToolTimeout(toolName);
+  if (actualTimeout === 0) {
+    yield* generator;
+    return;
+  }
+  let timeoutId = null;
+  let hasTimedOut = false;
+  const timeoutPromise = new Promise((_, reject) => {
+    timeoutId = setTimeout(() => {
+      hasTimedOut = true;
+      reject(new ToolTimeoutError(toolName, actualTimeout));
+    }, actualTimeout);
+  });
+  try {
+    while (true) {
+      const result = await Promise.race([generator.next(), timeoutPromise]);
+      if (result.done) {
+        return;
+      }
+      yield result.value;
+    }
+  } finally {
+    if (timeoutId !== null) {
+      clearTimeout(timeoutId);
+    }
+    if (hasTimedOut) {
+      try {
+        await generator.return(void 0);
+      } catch {
+      }
+    }
+  }
+}
+async function withPromiseTimeout(promise, toolName, timeoutMs) {
+  const actualTimeout = timeoutMs ?? getToolTimeout(toolName);
+  if (actualTimeout === 0) {
+    return promise;
+  }
+  let timeoutId = null;
+  const timeoutPromise = new Promise((_, reject) => {
+    timeoutId = setTimeout(() => {
+      reject(new ToolTimeoutError(toolName, actualTimeout));
+    }, actualTimeout);
+  });
+  try {
+    return await Promise.race([promise, timeoutPromise]);
+  } finally {
+    if (timeoutId !== null) {
+      clearTimeout(timeoutId);
+    }
+  }
+}
+function formatTimeout(timeoutMs) {
+  if (timeoutMs === 0) return "no limit";
+  if (timeoutMs < 6e4) return `${Math.round(timeoutMs / 1e3)}s`;
+  if (timeoutMs < 36e5) return `${Math.round(timeoutMs / 6e4)}min`;
+  return `${Math.round(timeoutMs / 36e5)}hr`;
+}
+export {
+  TOOL_TIMEOUTS,
+  TOOL_TIMEOUT_CONFIG,
+  ToolTimeoutError,
+  formatTimeout,
+  getToolTimeout,
+  withPromiseTimeout,
+  withTimeout
+};
+//# sourceMappingURL=toolTimeout.js.map

package/dist/utils/toolTimeout.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/utils/toolTimeout.ts"],
+  "sourcesContent": ["/**\n * Tool Execution Timeout Utility\n *\n * Provides timeout handling for tool execution to prevent infinite hangs.\n * Each tool can have a different timeout based on its nature.\n */\n\n/**\n * Default timeout values for different tool categories (in milliseconds)\n */\nexport const TOOL_TIMEOUTS = {\n  /** Quick read-only operations (file read, grep, glob) */\n  FAST: 30_000, // 30 seconds\n\n  /** Standard operations (most tools) */\n  STANDARD: 120_000, // 2 minutes\n\n  /** Long-running operations (bash commands, web fetch) */\n  LONG: 600_000, // 10 minutes\n\n  /** Extended operations (task agents, complex builds) */\n  EXTENDED: 1_800_000, // 30 minutes\n\n  /** No timeout (special cases only) */\n  NONE: 0,\n} as const\n\n/**\n * Tool-specific timeout configurations\n * Maps tool names to their timeout duration\n */\nexport const TOOL_TIMEOUT_CONFIG: Record<string, number> = {\n  // Fast operations (30s)\n  Read: TOOL_TIMEOUTS.FAST,\n  View: TOOL_TIMEOUTS.FAST,\n  Grep: TOOL_TIMEOUTS.FAST,\n  Glob: TOOL_TIMEOUTS.FAST,\n  LS: TOOL_TIMEOUTS.FAST,\n  LSP: TOOL_TIMEOUTS.FAST,\n\n  // Standard operations (2min)\n  Write: TOOL_TIMEOUTS.STANDARD,\n  Edit: TOOL_TIMEOUTS.STANDARD,\n  MultiEdit: TOOL_TIMEOUTS.STANDARD,\n  NotebookEdit: TOOL_TIMEOUTS.STANDARD,\n  TodoWrite: TOOL_TIMEOUTS.STANDARD,\n  TodoRead: TOOL_TIMEOUTS.STANDARD,\n  MemoryRead: TOOL_TIMEOUTS.STANDARD,\n  MemoryWrite: TOOL_TIMEOUTS.STANDARD,\n  AskUser: TOOL_TIMEOUTS.STANDARD,\n  Think: TOOL_TIMEOUTS.STANDARD,\n\n  // Long operations (10min)\n  Bash: TOOL_TIMEOUTS.LONG,\n  WebFetch: TOOL_TIMEOUTS.LONG,\n  WebSearch: TOOL_TIMEOUTS.LONG,\n  mcp__: TOOL_TIMEOUTS.LONG, // MCP tools prefix\n\n  // Extended operations (30min)\n  Task: TOOL_TIMEOUTS.EXTENDED,\n}\n\n/**\n * Get timeout duration for a specific tool\n */\nexport function getToolTimeout(toolName: string): number {\n  // Check for exact match first\n  if (toolName in TOOL_TIMEOUT_CONFIG) {\n    return TOOL_TIMEOUT_CONFIG[toolName]\n  }\n\n  // Check for prefix matches (e.g., mcp__ tools)\n  for (const [prefix, timeout] of Object.entries(TOOL_TIMEOUT_CONFIG)) {\n    if (prefix.endsWith('__') && toolName.startsWith(prefix)) {\n      return timeout\n    }\n  }\n\n  // Default to standard timeout\n  return TOOL_TIMEOUTS.STANDARD\n}\n\n/**\n * Error thrown when tool execution times out\n */\nexport class ToolTimeoutError extends Error {\n  public readonly toolName: string\n  public readonly timeoutMs: number\n\n  constructor(toolName: string, timeoutMs: number) {\n    super(\n      `Tool '${toolName}' execution timed out after ${Math.round(timeoutMs / 1000)} seconds`,\n    )\n    this.name = 'ToolTimeoutError'\n    this.toolName = toolName\n    this.timeoutMs = timeoutMs\n  }\n}\n\n/**\n * Wraps an async generator with a timeout\n * Yields values as they come, but throws ToolTimeoutError if the overall\n * execution exceeds the timeout.\n */\nexport async function* withTimeout<T>(\n  generator: AsyncGenerator<T, void>,\n  toolName: string,\n  timeoutMs?: number,\n): AsyncGenerator<T, void> {\n  const actualTimeout = timeoutMs ?? getToolTimeout(toolName)\n\n  // No timeout\n  if (actualTimeout === 0) {\n    yield* generator\n    return\n  }\n\n  // Create a timeout promise\n  let timeoutId: ReturnType<typeof setTimeout> | null = null\n  let hasTimedOut = false\n\n  const timeoutPromise = new Promise<never>((_, reject) => {\n    timeoutId = setTimeout(() => {\n      hasTimedOut = true\n      reject(new ToolTimeoutError(toolName, actualTimeout))\n    }, actualTimeout)\n  })\n\n  try {\n    while (true) {\n      // Race between the next value and timeout\n      const result = await Promise.race([generator.next(), timeoutPromise])\n\n      if (result.done) {\n        return\n      }\n\n      yield result.value as T\n    }\n  } finally {\n    // Clean up timeout\n    if (timeoutId !== null) {\n      clearTimeout(timeoutId)\n    }\n\n    // If we timed out, try to return/cleanup the generator\n    if (hasTimedOut) {\n      try {\n        await generator.return(undefined)\n      } catch {\n        // Ignore cleanup errors\n      }\n    }\n  }\n}\n\n/**\n * Wraps a promise with a timeout\n * Useful for non-generator async operations\n */\nexport async function withPromiseTimeout<T>(\n  promise: Promise<T>,\n  toolName: string,\n  timeoutMs?: number,\n): Promise<T> {\n  const actualTimeout = timeoutMs ?? getToolTimeout(toolName)\n\n  // No timeout\n  if (actualTimeout === 0) {\n    return promise\n  }\n\n  let timeoutId: ReturnType<typeof setTimeout> | null = null\n\n  const timeoutPromise = new Promise<never>((_, reject) => {\n    timeoutId = setTimeout(() => {\n      reject(new ToolTimeoutError(toolName, actualTimeout))\n    }, actualTimeout)\n  })\n\n  try {\n    return await Promise.race([promise, timeoutPromise])\n  } finally {\n    if (timeoutId !== null) {\n      clearTimeout(timeoutId)\n    }\n  }\n}\n\n/**\n * Format timeout for display\n */\nexport function formatTimeout(timeoutMs: number): string {\n  if (timeoutMs === 0) return 'no limit'\n  if (timeoutMs < 60_000) return `${Math.round(timeoutMs / 1000)}s`\n  if (timeoutMs < 3_600_000) return `${Math.round(timeoutMs / 60_000)}min`\n  return `${Math.round(timeoutMs / 3_600_000)}hr`\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/utils/tooling/safeRender.js

@@ -0,0 +1,116 @@
+import * as React from "react";
+import { Box, Text } from "ink";
+import { SEMANTIC_COLORS } from "../../constants/colors.js";
+function DefaultToolResult({
+  output
+}) {
+  let displayContent;
+  if (output === null || output === void 0) {
+    displayContent = "(no output)";
+  } else if (typeof output === "string") {
+    displayContent = output.length > 500 ? output.slice(0, 500) + "..." : output;
+  } else if (typeof output === "object") {
+    try {
+      const json = JSON.stringify(output, null, 2);
+      displayContent = json.length > 500 ? json.slice(0, 500) + "..." : json;
+    } catch {
+      displayContent = "[Object - cannot stringify]";
+    }
+  } else {
+    displayContent = String(output);
+  }
+  return /* @__PURE__ */ React.createElement(Box, { flexDirection: "column" }, /* @__PURE__ */ React.createElement(Text, { color: SEMANTIC_COLORS.dim }, displayContent));
+}
+function ErrorToolResult({
+  error,
+  toolName
+}) {
+  const errorMessage = error instanceof Error ? error.message : String(error || "Unknown error");
+  return /* @__PURE__ */ React.createElement(Box, { flexDirection: "column" }, /* @__PURE__ */ React.createElement(Text, { color: "red" }, toolName ? `[${toolName}] ` : "", "Error rendering result:"), /* @__PURE__ */ React.createElement(Text, { color: SEMANTIC_COLORS.dim }, errorMessage));
+}
+function safeRenderToolResult(tool, output, options) {
+  if (!tool) {
+    return /* @__PURE__ */ React.createElement(DefaultToolResult, { output });
+  }
+  if (!tool.renderToolResultMessage) {
+    return /* @__PURE__ */ React.createElement(DefaultToolResult, { output });
+  }
+  try {
+    const rendered = tool.renderToolResultMessage(output, options);
+    if (rendered === null || rendered === void 0) {
+      return /* @__PURE__ */ React.createElement(DefaultToolResult, { output });
+    }
+    return rendered;
+  } catch (error) {
+    return /* @__PURE__ */ React.createElement(ErrorToolResult, { error, toolName: tool.name });
+  }
+}
+function safeRenderToolUseMessage(tool, input, options) {
+  if (!tool) {
+    return /* @__PURE__ */ React.createElement(Box, null, /* @__PURE__ */ React.createElement(Text, { color: SEMANTIC_COLORS.dim }, "Unknown tool call"));
+  }
+  if (!tool.renderToolUseMessage) {
+    return /* @__PURE__ */ React.createElement(Box, null, /* @__PURE__ */ React.createElement(Text, null, /* @__PURE__ */ React.createElement(Text, { color: "cyan" }, tool.name), options.verbose && /* @__PURE__ */ React.createElement(Text, { color: SEMANTIC_COLORS.dim }, " ", JSON.stringify(input).slice(0, 100))));
+  }
+  try {
+    const rendered = tool.renderToolUseMessage(input, options);
+    if (rendered === null || rendered === void 0) {
+      return /* @__PURE__ */ React.createElement(Box, null, /* @__PURE__ */ React.createElement(Text, { color: "cyan" }, tool.name));
+    }
+    return rendered;
+  } catch (error) {
+    return /* @__PURE__ */ React.createElement(ErrorToolResult, { error, toolName: tool.name });
+  }
+}
+function safeRenderToolRejectedMessage(tool, ...args) {
+  if (!tool || !tool.renderToolUseRejectedMessage) {
+    return /* @__PURE__ */ React.createElement(Box, null, /* @__PURE__ */ React.createElement(Text, { color: "yellow" }, "Tool use rejected"));
+  }
+  try {
+    const rendered = tool.renderToolUseRejectedMessage(...args);
+    if (rendered === null || rendered === void 0) {
+      return /* @__PURE__ */ React.createElement(Box, null, /* @__PURE__ */ React.createElement(Text, { color: "yellow" }, tool.name, " rejected"));
+    }
+    return rendered;
+  } catch (error) {
+    return /* @__PURE__ */ React.createElement(ErrorToolResult, { error, toolName: tool.name });
+  }
+}
+function isValidReactNode(value) {
+  if (value === null || value === void 0) {
+    return true;
+  }
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return true;
+  }
+  if (Array.isArray(value)) {
+    return value.every(isValidReactNode);
+  }
+  if (typeof value === "object" && value !== null) {
+    return "$$typeof" in value || React.isValidElement(value);
+  }
+  return false;
+}
+function wrapRenderFunction(renderFn, fallback) {
+  return (...args) => {
+    try {
+      const result = renderFn(...args);
+      if (result === null || result === void 0) {
+        return fallback;
+      }
+      return result;
+    } catch {
+      return fallback;
+    }
+  };
+}
+export {
+  DefaultToolResult,
+  ErrorToolResult,
+  isValidReactNode,
+  safeRenderToolRejectedMessage,
+  safeRenderToolResult,
+  safeRenderToolUseMessage,
+  wrapRenderFunction
+};
+//# sourceMappingURL=safeRender.js.map

package/dist/utils/tooling/safeRender.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/utils/tooling/safeRender.tsx"],
+  "sourcesContent": ["/**\n * Safe Rendering Utilities for Tool Results\n *\n * Provides null-safe wrappers for tool rendering methods to prevent\n * crashes from undefined returns or exceptions.\n *\n * Part of Phase 1.3: Null Guards Completion\n */\n\nimport * as React from 'react'\nimport { Box, Text } from 'ink'\nimport { Tool } from '@tool'\nimport { SEMANTIC_COLORS } from '@constants/colors'\n\n/**\n * Default tool result component when tool doesn't provide a renderer.\n */\nexport function DefaultToolResult({\n  output,\n}: {\n  output: unknown\n}): React.ReactElement {\n  let displayContent: string\n\n  if (output === null || output === undefined) {\n    displayContent = '(no output)'\n  } else if (typeof output === 'string') {\n    displayContent = output.length > 500 ? output.slice(0, 500) + '...' : output\n  } else if (typeof output === 'object') {\n    try {\n      const json = JSON.stringify(output, null, 2)\n      displayContent = json.length > 500 ? json.slice(0, 500) + '...' : json\n    } catch {\n      displayContent = '[Object - cannot stringify]'\n    }\n  } else {\n    displayContent = String(output)\n  }\n\n  return (\n    <Box flexDirection=\"column\">\n      <Text color={SEMANTIC_COLORS.dim}>{displayContent}</Text>\n    </Box>\n  )\n}\n\n/**\n * Error display component for tool rendering failures.\n */\nexport function ErrorToolResult({\n  error,\n  toolName,\n}: {\n  error: unknown\n  toolName?: string\n}): React.ReactElement {\n  const errorMessage =\n    error instanceof Error ? error.message : String(error || 'Unknown error')\n\n  return (\n    <Box flexDirection=\"column\">\n      <Text color=\"red\">\n        {toolName ? `[${toolName}] ` : ''}Error rendering result:\n      </Text>\n      <Text color={SEMANTIC_COLORS.dim}>{errorMessage}</Text>\n    </Box>\n  )\n}\n\n/**\n * Safely render a tool result with comprehensive error handling.\n *\n * @param tool - The tool that produced the result\n * @param output - The tool's output data\n * @param options - Rendering options\n * @returns A React node that is guaranteed to be renderable\n */\nexport function safeRenderToolResult(\n  tool: Tool | undefined | null,\n  output: unknown,\n  options: { verbose: boolean },\n): React.ReactNode {\n  // No tool provided\n  if (!tool) {\n    return <DefaultToolResult output={output} />\n  }\n\n  // Tool doesn't have a renderer\n  if (!tool.renderToolResultMessage) {\n    return <DefaultToolResult output={output} />\n  }\n\n  try {\n    const rendered = tool.renderToolResultMessage(output, options)\n\n    // Handle null/undefined returns\n    if (rendered === null || rendered === undefined) {\n      return <DefaultToolResult output={output} />\n    }\n\n    return rendered\n  } catch (error) {\n    // Catch any rendering errors\n    return <ErrorToolResult error={error} toolName={tool.name} />\n  }\n}\n\n/**\n * Safely render a tool use message with comprehensive error handling.\n *\n * @param tool - The tool being used\n * @param input - The tool's input parameters\n * @param options - Rendering options\n * @returns A React node that is guaranteed to be renderable\n */\nexport function safeRenderToolUseMessage(\n  tool: Tool | undefined | null,\n  input: unknown,\n  options: { verbose: boolean },\n): React.ReactNode {\n  // No tool provided\n  if (!tool) {\n    return (\n      <Box>\n        <Text color={SEMANTIC_COLORS.dim}>Unknown tool call</Text>\n      </Box>\n    )\n  }\n\n  // Tool doesn't have a renderer\n  if (!tool.renderToolUseMessage) {\n    return (\n      <Box>\n        <Text>\n          <Text color=\"cyan\">{tool.name}</Text>\n          {options.verbose && (\n            <Text color={SEMANTIC_COLORS.dim}>\n              {' '}\n              {JSON.stringify(input).slice(0, 100)}\n            </Text>\n          )}\n        </Text>\n      </Box>\n    )\n  }\n\n  try {\n    const rendered = tool.renderToolUseMessage(input, options)\n\n    // Handle null/undefined returns\n    if (rendered === null || rendered === undefined) {\n      return (\n        <Box>\n          <Text color=\"cyan\">{tool.name}</Text>\n        </Box>\n      )\n    }\n\n    return rendered\n  } catch (error) {\n    return <ErrorToolResult error={error} toolName={tool.name} />\n  }\n}\n\n/**\n * Safely render a tool rejection message with comprehensive error handling.\n *\n * @param tool - The tool that was rejected\n * @param args - Arguments to pass to the rejection renderer\n * @returns A React node that is guaranteed to be renderable\n */\nexport function safeRenderToolRejectedMessage(\n  tool: Tool | undefined | null,\n  ...args: unknown[]\n): React.ReactNode {\n  // No tool or no renderer\n  if (!tool || !tool.renderToolUseRejectedMessage) {\n    return (\n      <Box>\n        <Text color=\"yellow\">Tool use rejected</Text>\n      </Box>\n    )\n  }\n\n  try {\n    const rendered = tool.renderToolUseRejectedMessage(...args)\n\n    // Handle null/undefined returns\n    if (rendered === null || rendered === undefined) {\n      return (\n        <Box>\n          <Text color=\"yellow\">{tool.name} rejected</Text>\n        </Box>\n      )\n    }\n\n    return rendered\n  } catch (error) {\n    return <ErrorToolResult error={error} toolName={tool.name} />\n  }\n}\n\n/**\n * Type guard to check if a value is a valid React node.\n */\nexport function isValidReactNode(value: unknown): value is React.ReactNode {\n  if (value === null || value === undefined) {\n    return true // React accepts null/undefined\n  }\n\n  if (\n    typeof value === 'string' ||\n    typeof value === 'number' ||\n    typeof value === 'boolean'\n  ) {\n    return true\n  }\n\n  if (Array.isArray(value)) {\n    return value.every(isValidReactNode)\n  }\n\n  // Check for React element\n  if (typeof value === 'object' && value !== null) {\n    return '$$typeof' in value || React.isValidElement(value)\n  }\n\n  return false\n}\n\n/**\n * Wrap a potentially unsafe render function with error boundaries.\n *\n * @param renderFn - The render function to wrap\n * @param fallback - Fallback content on error\n * @returns A safe render function\n */\nexport function wrapRenderFunction<TArgs extends unknown[]>(\n  renderFn: (...args: TArgs) => React.ReactNode,\n  fallback: React.ReactNode,\n): (...args: TArgs) => React.ReactNode {\n  return (...args: TArgs) => {\n    try {\n      const result = renderFn(...args)\n      if (result === null || result === undefined) {\n        return fallback\n      }\n      return result\n    } catch {\n      return fallback\n    }\n  }\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/utils/userFriendlyError.js

@@ -0,0 +1,346 @@
+import { randomUUID } from "crypto";
+import * as fs from "fs";
+import * as path from "path";
+import { t, tSafe } from "../i18n/index.js";
+var ErrorCategory = /* @__PURE__ */ ((ErrorCategory2) => {
+  ErrorCategory2["NETWORK_CONNECTION"] = "network_connection";
+  ErrorCategory2["NETWORK_TIMEOUT"] = "network_timeout";
+  ErrorCategory2["NETWORK_DNS"] = "network_dns";
+  ErrorCategory2["API_RATE_LIMIT"] = "api_rate_limit";
+  ErrorCategory2["API_AUTH"] = "api_auth";
+  ErrorCategory2["API_QUOTA"] = "api_quota";
+  ErrorCategory2["API_SERVER_ERROR"] = "api_server_error";
+  ErrorCategory2["API_INVALID_RESPONSE"] = "api_invalid_response";
+  ErrorCategory2["FILE_NOT_FOUND"] = "file_not_found";
+  ErrorCategory2["FILE_PERMISSION"] = "file_permission";
+  ErrorCategory2["FILE_TOO_LARGE"] = "file_too_large";
+  ErrorCategory2["FILE_ENCODING"] = "file_encoding";
+  ErrorCategory2["CONFIG_MISSING"] = "config_missing";
+  ErrorCategory2["CONFIG_INVALID"] = "config_invalid";
+  ErrorCategory2["CONFIG_API_KEY"] = "config_api_key";
+  ErrorCategory2["MODEL_UNAVAILABLE"] = "model_unavailable";
+  ErrorCategory2["MODEL_CONTEXT_LENGTH"] = "model_context_length";
+  ErrorCategory2["MODEL_CONTENT_FILTER"] = "model_content_filter";
+  ErrorCategory2["SYSTEM_MEMORY"] = "system_memory";
+  ErrorCategory2["SYSTEM_PROCESS"] = "system_process";
+  ErrorCategory2["UNKNOWN"] = "unknown";
+  return ErrorCategory2;
+})(ErrorCategory || {});
+const CATEGORY_TO_I18N_PREFIX = {
+  ["network_connection" /* NETWORK_CONNECTION */]: "friendlyError.networkConnection",
+  ["network_timeout" /* NETWORK_TIMEOUT */]: "friendlyError.networkTimeout",
+  ["network_dns" /* NETWORK_DNS */]: "friendlyError.networkDns",
+  ["api_rate_limit" /* API_RATE_LIMIT */]: "friendlyError.apiRateLimit",
+  ["api_auth" /* API_AUTH */]: "friendlyError.apiAuth",
+  ["api_quota" /* API_QUOTA */]: "friendlyError.apiQuota",
+  ["api_server_error" /* API_SERVER_ERROR */]: "friendlyError.apiServerError",
+  ["api_invalid_response" /* API_INVALID_RESPONSE */]: "friendlyError.apiInvalidResponse",
+  ["file_not_found" /* FILE_NOT_FOUND */]: "friendlyError.fileNotFound",
+  ["file_permission" /* FILE_PERMISSION */]: "friendlyError.filePermission",
+  ["file_too_large" /* FILE_TOO_LARGE */]: "friendlyError.fileTooLarge",
+  ["file_encoding" /* FILE_ENCODING */]: "friendlyError.fileEncoding",
+  ["config_missing" /* CONFIG_MISSING */]: "friendlyError.configMissing",
+  ["config_invalid" /* CONFIG_INVALID */]: "friendlyError.configInvalid",
+  ["config_api_key" /* CONFIG_API_KEY */]: "friendlyError.configApiKey",
+  ["model_unavailable" /* MODEL_UNAVAILABLE */]: "friendlyError.modelUnavailable",
+  ["model_context_length" /* MODEL_CONTEXT_LENGTH */]: "friendlyError.modelContextLength",
+  ["model_content_filter" /* MODEL_CONTENT_FILTER */]: "friendlyError.modelContentFilter",
+  ["system_memory" /* SYSTEM_MEMORY */]: "friendlyError.systemMemory",
+  ["system_process" /* SYSTEM_PROCESS */]: "friendlyError.systemProcess",
+  ["unknown" /* UNKNOWN */]: "friendlyError.unknown"
+};
+function getFriendlyMessage(category) {
+  const prefix = CATEGORY_TO_I18N_PREFIX[category];
+  const suggestions = [];
+  for (let i = 1; i <= 3; i++) {
+    const suggestion = tSafe(`${prefix}.suggestion${i}`);
+    if (suggestion) {
+      suggestions.push(suggestion);
+    }
+  }
+  return {
+    title: tSafe(`${prefix}.title`) || category,
+    description: tSafe(`${prefix}.description`) || "",
+    suggestions
+  };
+}
+const FRIENDLY_MESSAGES = Object.fromEntries(
+  Object.values(ErrorCategory).map((category) => [
+    category,
+    getFriendlyMessage(category)
+  ])
+);
+const ERROR_PATTERNS = [
+  // Network errors
+  {
+    category: "network_connection" /* NETWORK_CONNECTION */,
+    patterns: [
+      "socket.*closed",
+      "ECONNREFUSED",
+      "ECONNRESET",
+      "ENOTFOUND",
+      "connection.*refused",
+      "connection.*closed",
+      "network.*error",
+      "fetch failed"
+    ]
+  },
+  {
+    category: "network_timeout" /* NETWORK_TIMEOUT */,
+    patterns: [
+      "timeout",
+      "ETIMEDOUT",
+      "timed out",
+      "deadline exceeded",
+      "request.*timeout"
+    ]
+  },
+  {
+    category: "network_dns" /* NETWORK_DNS */,
+    patterns: ["ENOTFOUND", "getaddrinfo", "DNS", "resolve.*failed"]
+  },
+  // API errors
+  {
+    category: "api_rate_limit" /* API_RATE_LIMIT */,
+    patterns: ["rate.*limit", "429", "too many requests", "quota.*exceeded"]
+  },
+  {
+    category: "api_auth" /* API_AUTH */,
+    patterns: [
+      "401",
+      "unauthorized",
+      "authentication.*failed",
+      "invalid.*key",
+      "api.*key.*invalid"
+    ]
+  },
+  {
+    category: "api_quota" /* API_QUOTA */,
+    patterns: [
+      "insufficient.*quota",
+      "billing",
+      "credit",
+      "exceeded.*quota",
+      "402"
+    ]
+  },
+  {
+    category: "api_server_error" /* API_SERVER_ERROR */,
+    patterns: ["500", "502", "503", "504", "internal.*error", "server.*error"]
+  },
+  // File errors
+  {
+    category: "file_not_found" /* FILE_NOT_FOUND */,
+    patterns: ["ENOENT", "no such file", "file.*not.*found", "does not exist"]
+  },
+  {
+    category: "file_permission" /* FILE_PERMISSION */,
+    patterns: ["EACCES", "EPERM", "permission.*denied", "access.*denied"]
+  },
+  {
+    category: "file_too_large" /* FILE_TOO_LARGE */,
+    patterns: ["file.*too.*large", "EFBIG", "size.*limit"]
+  },
+  // Model errors
+  {
+    category: "model_context_length" /* MODEL_CONTEXT_LENGTH */,
+    patterns: [
+      "context.*length",
+      "token.*limit",
+      "max.*tokens",
+      "too.*long",
+      "exceeds.*maximum"
+    ]
+  },
+  {
+    category: "model_content_filter" /* MODEL_CONTENT_FILTER */,
+    patterns: ["content.*filter", "safety", "blocked", "moderation"]
+  },
+  {
+    category: "model_unavailable" /* MODEL_UNAVAILABLE */,
+    patterns: ["model.*not.*found", "model.*unavailable", "does not exist"]
+  },
+  // Config errors
+  {
+    category: "config_api_key" /* CONFIG_API_KEY */,
+    patterns: [
+      "api.*key.*not.*set",
+      "missing.*api.*key",
+      "ANTHROPIC_API_KEY",
+      "OPENAI_API_KEY"
+    ]
+  },
+  // System errors
+  {
+    category: "system_memory" /* SYSTEM_MEMORY */,
+    patterns: ["ENOMEM", "out of memory", "heap", "memory.*limit"]
+  }
+];
+function classifyError(error) {
+  const errorString = getErrorString(error).toLowerCase();
+  for (const { category, patterns } of ERROR_PATTERNS) {
+    for (const pattern of patterns) {
+      if (typeof pattern === "string") {
+        if (errorString.includes(pattern.toLowerCase())) {
+          return category;
+        }
+      } else if (pattern.test(errorString)) {
+        return category;
+      }
+    }
+  }
+  return "unknown" /* UNKNOWN */;
+}
+function getErrorString(error) {
+  if (error instanceof Error) {
+    return `${error.name}: ${error.message} ${error.stack || ""}`;
+  }
+  return String(error);
+}
+class UserFriendlyError extends Error {
+  id;
+  category;
+  friendlyMessage;
+  originalError;
+  context;
+  timestamp;
+  constructor(originalError, context = {}, categoryOverride) {
+    const category = categoryOverride || classifyError(originalError);
+    const friendly = FRIENDLY_MESSAGES[category];
+    super(friendly.title);
+    this.name = "UserFriendlyError";
+    this.id = randomUUID().slice(0, 8);
+    this.category = category;
+    this.friendlyMessage = friendly;
+    this.originalError = originalError;
+    this.context = context;
+    this.timestamp = /* @__PURE__ */ new Date();
+    if (originalError instanceof Error && originalError.stack) {
+      this.stack = originalError.stack;
+    }
+  }
+  /**
+   * Get user-facing display message
+   */
+  getUserMessage() {
+    const message = getFriendlyMessage(this.category);
+    const suggestionLabel = t("friendlyError.suggestionLabel");
+    const errorIdLabel = t("friendlyError.errorIdLabel");
+    const lines = [
+      `\u26A0\uFE0F ${message.title}`,
+      "",
+      message.description,
+      "",
+      `\u{1F4A1} ${suggestionLabel}:`,
+      ...message.suggestions.map((s) => `  \u2022 ${s}`),
+      "",
+      `\u{1F4CB} ${errorIdLabel}: ${this.id}`
+    ];
+    return lines.join("\n");
+  }
+  /**
+   * Get technical message for developers
+   */
+  getTechnicalMessage() {
+    const original = this.originalError instanceof Error ? this.originalError.message : String(this.originalError);
+    return `[${this.category}] ${original}`;
+  }
+  /**
+   * Create structured log entry
+   */
+  toLogEntry() {
+    return {
+      id: this.id,
+      timestamp: this.timestamp.toISOString(),
+      category: this.category,
+      friendlyTitle: this.friendlyMessage.title,
+      technicalMessage: this.getTechnicalMessage(),
+      stack: this.stack,
+      context: this.context,
+      systemInfo: {
+        platform: process.platform,
+        nodeVersion: process.version,
+        mintoVersion: getMintoVersion()
+      }
+    };
+  }
+}
+let errorLogPath = null;
+function getErrorLogPath() {
+  if (!errorLogPath) {
+    const logDir = path.join(process.env.HOME || "", ".minto", "logs");
+    errorLogPath = path.join(logDir, "errors.jsonl");
+  }
+  return errorLogPath;
+}
+function logUserFriendlyError(error) {
+  try {
+    const logPath = getErrorLogPath();
+    const logDir = path.dirname(logPath);
+    if (!fs.existsSync(logDir)) {
+      fs.mkdirSync(logDir, { recursive: true });
+    }
+    const entry = error.toLogEntry();
+    fs.appendFileSync(logPath, JSON.stringify(entry) + "\n");
+  } catch {
+  }
+}
+function getRecentErrors(limit = 10) {
+  try {
+    const logPath = getErrorLogPath();
+    if (!fs.existsSync(logPath)) {
+      return [];
+    }
+    const content = fs.readFileSync(logPath, "utf-8");
+    const lines = content.trim().split("\n").filter(Boolean);
+    const entries = lines.slice(-limit).map((line) => {
+      try {
+        return JSON.parse(line);
+      } catch {
+        return null;
+      }
+    }).filter((e) => e !== null);
+    return entries.reverse();
+  } catch {
+    return [];
+  }
+}
+function getMintoVersion() {
+  try {
+    const packageJsonPath = path.join(__dirname, "../../package.json");
+    const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
+    return packageJson.version || "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+function toUserFriendlyError(error, context) {
+  if (error instanceof UserFriendlyError) {
+    return error;
+  }
+  return new UserFriendlyError(error, context);
+}
+function formatErrorForUser(error, options = {}) {
+  const friendly = toUserFriendlyError(error, options.context);
+  logUserFriendlyError(friendly);
+  let message = friendly.getUserMessage();
+  if (options.showTechnical) {
+    const technicalLabel = t("friendlyError.technicalDetailsLabel");
+    message += `
+
+\u{1F527} ${technicalLabel}: ${friendly.getTechnicalMessage()}`;
+  }
+  return message;
+}
+export {
+  ERROR_PATTERNS,
+  ErrorCategory,
+  FRIENDLY_MESSAGES,
+  UserFriendlyError,
+  classifyError,
+  formatErrorForUser,
+  getRecentErrors,
+  logUserFriendlyError,
+  toUserFriendlyError
+};
+//# sourceMappingURL=userFriendlyError.js.map