minimal-agent 0.18.10 → 0.18.11

package/src/loop/toolPresentation.js

@@ -0,0 +1,135 @@
+/** 给 UI 展示用的参数预览（只取前 60 字符） */
+export function previewArgs(rawJson) {
+    const oneLine = rawJson.replace(/\s+/g, ' ').trim();
+    if (oneLine.length <= 60)
+        return oneLine;
+    return oneLine.slice(0, 60) + '...';
+}
+/**
+ * 把工具名 + raw arguments JSON 转换成人话描述。
+ * UI 优先用这个显示在 spinner 行（如 "Reading src/foo.ts"）。
+ * 已知工具走 switch；未知工具或 JSON parse 失败 fallback 到 `${toolName}(...)`。
+ */
+export function friendlyToolDescription(toolName, rawArgsJson, fileLabel) {
+    let args = {};
+    try {
+        args = JSON.parse(rawArgsJson) ?? {};
+    }
+    catch {
+        return `${toolName}(...)`;
+    }
+    const truncate = (s, n) => {
+        if (typeof s !== 'string')
+            return '';
+        return s.length > n ? s.slice(0, n) + '…' : s;
+    };
+    const file = (value) => {
+        if (typeof value !== 'string')
+            return '';
+        if (fileLabel)
+            return fileLabel(value);
+        return value.length > 64 ? `…${value.slice(-63)}` : value;
+    };
+    switch (toolName) {
+        case 'Skill':
+            return `技能 · ${truncate(args.name, 60)}`;
+        case 'SearchSkills':
+            return `查找技能 · ${truncate(args.query, 60)}`;
+        case 'Advisor': {
+            const reasons = {
+                plan_review: '执行前评审',
+                delivery_review: '交付前核验',
+                stalled: '分析重复失败',
+                uncertainty: '核查不确定问题',
+                user_dissatisfaction: '复核用户反馈',
+                evidence_conflict: '核查证据冲突',
+            };
+            return `咨询顾问 · ${reasons[String(args.reason)] ?? '独立第二意见'}`;
+        }
+        case 'AdvisorDecision':
+            return `顾问建议 · ${truncate(args.decision ?? args.action, 40) || '记录核验与采纳结论'}`;
+        case 'AskUserQuestion':
+            return '询问关键决策';
+        case 'PresentResult':
+            return '提交成果与验证结果';
+        case 'PowerShell':
+            return `运行 PowerShell · ${truncate(args.description ?? args.command, 60)}`;
+        case 'OptimizeConversation':
+            return '优化对话';
+        case 'Read':
+            return `Reading ${file(args.file_path)}`;
+        case 'Edit':
+            return `Editing ${file(args.file_path)}`;
+        case 'MultiEdit': {
+            const n = Array.isArray(args.edits) ? args.edits.length : 0;
+            return `Editing ${file(args.file_path)}${n ? ` (${n} 处)` : ''}`;
+        }
+        case 'Write':
+            return `Writing ${file(args.file_path)}`;
+        case 'Trash':
+            return `Moving to Trash ${file(args.file_path ?? args.path)}`;
+        case 'ApplyPatch': {
+            const patch = typeof args.patch === 'string' ? args.patch : typeof args.input === 'string' ? args.input : '';
+            const files = [...patch.matchAll(/^\*\*\* (Add|Update|Delete) File: (.+)$/gm)].map((m) => `${file(m[2])}（${{ Add: '新增', Update: '修改', Delete: '删除' }[m[1]]}）`);
+            if (!files.length)
+                files.push(...[...patch.matchAll(/^\+\+\+ [ab]\/([^\n]+)$/gm)].map((m) => file(m[1])));
+            return files.length > 0 ? `Editing ${files.join(', ')}` : 'Editing patch';
+        }
+        case 'NotebookEdit':
+            return `Editing ${file(args.notebook_path ?? args.file_path)}`;
+        case 'Bash':
+            return typeof args.description === 'string' && args.description.trim()
+                ? `运行 ${truncate(args.description, 70)}`
+                : `Running \`${truncate(args.command, 40)}\``;
+        case 'Grep': {
+            const p = truncate(args.pattern, 30);
+            const g = typeof args.glob === 'string' && args.glob.length > 0 ? ` in ${truncate(args.glob, 25)}` : '';
+            return `Searching \`${p}\`${g}`;
+        }
+        case 'Glob':
+            return `Globbing \`${truncate(args.pattern, 50)}\``;
+        case 'WebBrowser': {
+            const actions = {
+                start: '启动',
+                navigate: '打开页面',
+                screenshot: '截图',
+                snapshot: '读取页面',
+                click: '点击',
+                fill: '填写',
+                evaluate: '执行页面脚本',
+                close: '关闭',
+                stop: '停止',
+                console: '查看控制台',
+                network: '查看网络请求',
+            };
+            let target = '';
+            try {
+                target = new URL(String(args.url)).host;
+            }
+            catch {
+                /* no URL for local actions */
+            }
+            return `浏览器 · ${actions[String(args.action)] ?? (truncate(args.action, 32) || '操作页面')}${target ? ` · ${target}` : ''}`;
+        }
+        case 'WebFetch': {
+            try {
+                return `Fetching ${new URL(String(args.url)).host}`;
+            }
+            catch {
+                return `Fetching ...`;
+            }
+        }
+        case 'BrowserBatch':
+            return `浏览器 · ${truncate(args.action, 30) || '批量操作'}（${Array.isArray(args.steps) ? args.steps.length : 0} 步）`;
+        case 'BrowserCDP':
+            return `浏览器调试 · ${truncate(String(args.method ?? args.operation ?? ''), 45)}`;
+        case 'WebSearch':
+            return `Searching \`${truncate(args.query, 50)}\``;
+        case 'Agent': {
+            const t = typeof args.agent_type === 'string' ? args.agent_type : 'explore';
+            return `子任务[${t}] ${truncate(args.description, 50)}`;
+        }
+        default:
+            return `${toolName} · ${truncate(args.description ?? args.action ?? args.operation, 60) || '执行工具操作'}`;
+    }
+}

package/src/loop/toolPresentation.ts

@@ -0,0 +1,134 @@
+/** 给 UI 展示用的参数预览（只取前 60 字符） */
+export function previewArgs(rawJson: string): string {
+  const oneLine = rawJson.replace(/\s+/g, ' ').trim();
+  if (oneLine.length <= 60) return oneLine;
+  return oneLine.slice(0, 60) + '...';
+}
+
+/**
+ * 把工具名 + raw arguments JSON 转换成人话描述。
+ * UI 优先用这个显示在 spinner 行（如 "Reading src/foo.ts"）。
+ * 已知工具走 switch；未知工具或 JSON parse 失败 fallback 到 `${toolName}(...)`。
+ */
+export function friendlyToolDescription(
+  toolName: string,
+  rawArgsJson: string,
+  fileLabel?: (path: string) => string,
+): string {
+  let args: Record<string, unknown> = {};
+  try {
+    args = JSON.parse(rawArgsJson) ?? {};
+  } catch {
+    return `${toolName}(...)`;
+  }
+  const truncate = (s: unknown, n: number): string => {
+    if (typeof s !== 'string') return '';
+    return s.length > n ? s.slice(0, n) + '…' : s;
+  };
+  const file = (value: unknown): string => {
+    if (typeof value !== 'string') return '';
+    if (fileLabel) return fileLabel(value);
+    return value.length > 64 ? `…${value.slice(-63)}` : value;
+  };
+  switch (toolName) {
+    case 'Skill':
+      return `技能 · ${truncate(args.name, 60)}`;
+    case 'SearchSkills':
+      return `查找技能 · ${truncate(args.query, 60)}`;
+    case 'Advisor': {
+      const reasons: Record<string, string> = {
+        plan_review: '执行前评审',
+        delivery_review: '交付前核验',
+        stalled: '分析重复失败',
+        uncertainty: '核查不确定问题',
+        user_dissatisfaction: '复核用户反馈',
+        evidence_conflict: '核查证据冲突',
+      };
+      return `咨询顾问 · ${reasons[String(args.reason)] ?? '独立第二意见'}`;
+    }
+    case 'AdvisorDecision':
+      return `顾问建议 · ${truncate(args.decision ?? args.action, 40) || '记录核验与采纳结论'}`;
+    case 'AskUserQuestion':
+      return '询问关键决策';
+    case 'PresentResult':
+      return '提交成果与验证结果';
+    case 'PowerShell':
+      return `运行 PowerShell · ${truncate(args.description ?? args.command, 60)}`;
+    case 'OptimizeConversation':
+      return '优化对话';
+    case 'Read':
+      return `Reading ${file(args.file_path)}`;
+    case 'Edit':
+      return `Editing ${file(args.file_path)}`;
+    case 'MultiEdit': {
+      const n = Array.isArray(args.edits) ? args.edits.length : 0;
+      return `Editing ${file(args.file_path)}${n ? ` (${n} 处)` : ''}`;
+    }
+    case 'Write':
+      return `Writing ${file(args.file_path)}`;
+    case 'Trash':
+      return `Moving to Trash ${file(args.file_path ?? args.path)}`;
+    case 'ApplyPatch': {
+      const patch = typeof args.patch === 'string' ? args.patch : typeof args.input === 'string' ? args.input : '';
+      const files = [...patch.matchAll(/^\*\*\* (Add|Update|Delete) File: (.+)$/gm)].map(
+        (m) => `${file(m[2])}（${({ Add: '新增', Update: '修改', Delete: '删除' } as Record<string, string>)[m[1]]}）`,
+      );
+      if (!files.length) files.push(...[...patch.matchAll(/^\+\+\+ [ab]\/([^\n]+)$/gm)].map((m) => file(m[1])));
+      return files.length > 0 ? `Editing ${files.join(', ')}` : 'Editing patch';
+    }
+    case 'NotebookEdit':
+      return `Editing ${file(args.notebook_path ?? args.file_path)}`;
+    case 'Bash':
+      return typeof args.description === 'string' && args.description.trim()
+        ? `运行 ${truncate(args.description, 70)}`
+        : `Running \`${truncate(args.command, 40)}\``;
+    case 'Grep': {
+      const p = truncate(args.pattern, 30);
+      const g = typeof args.glob === 'string' && args.glob.length > 0 ? ` in ${truncate(args.glob, 25)}` : '';
+      return `Searching \`${p}\`${g}`;
+    }
+    case 'Glob':
+      return `Globbing \`${truncate(args.pattern, 50)}\``;
+    case 'WebBrowser': {
+      const actions: Record<string, string> = {
+        start: '启动',
+        navigate: '打开页面',
+        screenshot: '截图',
+        snapshot: '读取页面',
+        click: '点击',
+        fill: '填写',
+        evaluate: '执行页面脚本',
+        close: '关闭',
+        stop: '停止',
+        console: '查看控制台',
+        network: '查看网络请求',
+      };
+      let target = '';
+      try {
+        target = new URL(String(args.url)).host;
+      } catch {
+        /* no URL for local actions */
+      }
+      return `浏览器 · ${actions[String(args.action)] ?? (truncate(args.action, 32) || '操作页面')}${target ? ` · ${target}` : ''}`;
+    }
+    case 'WebFetch': {
+      try {
+        return `Fetching ${new URL(String(args.url)).host}`;
+      } catch {
+        return `Fetching ...`;
+      }
+    }
+    case 'BrowserBatch':
+      return `浏览器 · ${truncate(args.action, 30) || '批量操作'}（${Array.isArray(args.steps) ? args.steps.length : 0} 步）`;
+    case 'BrowserCDP':
+      return `浏览器调试 · ${truncate(String(args.method ?? args.operation ?? ''), 45)}`;
+    case 'WebSearch':
+      return `Searching \`${truncate(args.query, 50)}\``;
+    case 'Agent': {
+      const t = typeof args.agent_type === 'string' ? args.agent_type : 'explore';
+      return `子任务[${t}] ${truncate(args.description, 50)}`;
+    }
+    default:
+      return `${toolName} · ${truncate(args.description ?? args.action ?? args.operation, 60) || '执行工具操作'}`;
+  }
+}

package/src/loop/toolSemantics.js

@@ -0,0 +1,45 @@
+import { isReadOnlyShellCommand, isVerificationShellCommand, isAdvisorInspectionCommand } from '../tools/bash/semantics.js';
+import { toolEffectFor } from '../tools/capabilities.js';
+import { getToolByName, getToolGateDetails } from '../tools/index.js';
+export function advisorSemanticsFor(call, context, tool, 
+// 默认 false：只有 advisor 检查点/记账（beforeTool、observeToolResult、
+// 持久化的 advisorMutatesWorkspace 标注）才传 true。工作区租约判定
+// （needsWorkspaceLease）必须保持严格定义不受影响——验证类命令仍可能写
+// 构建产物/缓存，并发场景下让它绕开租约会重新引入竞态。
+opts) {
+    const definition = tool ?? getToolByName(call.function.name);
+    const gate = context ? getToolGateDetails(call.function.name, call.function.arguments, context) : undefined;
+    // Reuse the tool's side-effect contract, including shell/scripts, Trash and
+    // generation tools. Shell tools refine their generic writable declaration
+    // using the actual command; the same result is also used by the host gate.
+    let isReadOnly = gate?.isReadOnly ?? definition?.isReadOnly ?? false;
+    if (call.function.name === 'Agent') {
+        try {
+            const args = JSON.parse(call.function.arguments || '{}');
+            isReadOnly = !args.resume_agent_id && (args.agent_type ?? 'explore') === 'explore';
+        }
+        catch {
+            isReadOnly = false;
+        }
+    }
+    if (call.function.name === 'Bash' || call.function.name === 'PowerShell') {
+        try {
+            const input = JSON.parse(call.function.arguments || '{}');
+            if (typeof input.command === 'string') {
+                // 跑测试/构建/lint 只是核对现状，不该被当成"开始实施改动"而白白烧掉
+                // pre-execution 检查点——即使它们可能写构建产物/缓存，不满足
+                // isReadOnlyShellCommand 的并发安全定义（见 opts 注释，那个场景仍要严格）。
+                isReadOnly =
+                    isReadOnlyShellCommand(input.command) ||
+                        (opts?.treatVerificationAsReadOnly === true &&
+                            (isAdvisorInspectionCommand(input.command) || isVerificationShellCommand(input.command)));
+            }
+        }
+        catch {
+            // Malformed input is left writable; normal tool validation reports it.
+            isReadOnly = false;
+        }
+    }
+    const mutatesWorkspace = toolEffectFor(call.function.name, isReadOnly) === 'execution';
+    return { mutatesWorkspace };
+}

package/src/loop/toolSemantics.ts

@@ -0,0 +1,51 @@
+import type { AdvisorToolSemantics } from '../advisor/advisorCoordinator.js';
+import { isReadOnlyShellCommand, isVerificationShellCommand, isAdvisorInspectionCommand } from '../tools/bash/semantics.js';
+import { toolEffectFor } from '../tools/capabilities.js';
+import { getToolByName, getToolGateDetails } from '../tools/index.js';
+import type { Tool, ToolCall, ToolCallContext } from '../types.js';
+export function advisorSemanticsFor(
+  call: ToolCall,
+  context?: ToolCallContext,
+  tool?: Tool,
+  // 默认 false：只有 advisor 检查点/记账（beforeTool、observeToolResult、
+  // 持久化的 advisorMutatesWorkspace 标注）才传 true。工作区租约判定
+  // （needsWorkspaceLease）必须保持严格定义不受影响——验证类命令仍可能写
+  // 构建产物/缓存，并发场景下让它绕开租约会重新引入竞态。
+  opts?: { treatVerificationAsReadOnly?: boolean },
+): AdvisorToolSemantics {
+  const definition = tool ?? getToolByName(call.function.name);
+  const gate = context ? getToolGateDetails(call.function.name, call.function.arguments, context) : undefined;
+  // Reuse the tool's side-effect contract, including shell/scripts, Trash and
+  // generation tools. Shell tools refine their generic writable declaration
+  // using the actual command; the same result is also used by the host gate.
+  let isReadOnly = gate?.isReadOnly ?? definition?.isReadOnly ?? false;
+  if (call.function.name === 'Agent') {
+    try {
+      const args = JSON.parse(call.function.arguments || '{}');
+      isReadOnly = !args.resume_agent_id && (args.agent_type ?? 'explore') === 'explore';
+    } catch {
+      isReadOnly = false;
+    }
+  }
+  if (call.function.name === 'Bash' || call.function.name === 'PowerShell') {
+    try {
+      const input = JSON.parse(call.function.arguments || '{}') as {
+        command?: unknown;
+      };
+      if (typeof input.command === 'string') {
+        // 跑测试/构建/lint 只是核对现状，不该被当成"开始实施改动"而白白烧掉
+        // pre-execution 检查点——即使它们可能写构建产物/缓存，不满足
+        // isReadOnlyShellCommand 的并发安全定义（见 opts 注释，那个场景仍要严格）。
+        isReadOnly =
+          isReadOnlyShellCommand(input.command) ||
+          (opts?.treatVerificationAsReadOnly === true &&
+            (isAdvisorInspectionCommand(input.command) || isVerificationShellCommand(input.command)));
+      }
+    } catch {
+      // Malformed input is left writable; normal tool validation reports it.
+      isReadOnly = false;
+    }
+  }
+  const mutatesWorkspace = toolEffectFor(call.function.name, isReadOnly) === 'execution';
+  return { mutatesWorkspace };
+}