minimal-agent 0.12.0 → 0.14.0

package/src/infra/verification.ts

@@ -16,16 +16,35 @@
  *  设计原则：
  *    - 纯工具函数，无全局状态，无副作用（除了 shell 子进程）
  *    - 不依赖任何插件代码，可被 src/ 和 plugins/ 同时导入
- *    - 工作目录隔离：所有相对路径以 getWorkingDir() 为锚
+ *    - 工作目录隔离：相对路径以调用方给的 cwd 为锚，缺省 getWorkingDir()
+ *
+ *  ⚠️ cwd 参数不是可有可无的修饰：**验收必须和写入锚在同一个目录**。
+ *  会话进入 session worktree 后（EnterWorktree），写文件的工具跟着 worktree 走
+ *  （loop.ts 按 sessionState.activeWorktree 重定向 cwd），验收若仍锚原 workspace，
+ *  就会在空目录里找产物 —— file_exists 恒 false，工作流被判失败并反复重试，
+ *  而产物其实好好躺在 worktree 里。调用方拿得到有效 cwd 时务必传进来。
  * ============================================================
  */
 
 import { existsSync, readFileSync } from 'node:fs';
 import { spawn } from 'node:child_process';
 import { sanitizeCredentialEnv } from '../config/configService.js';
+import { CONFIG_LIMITS, normalizeLimited } from '../config/numericLimits.js';
 
 import { getWorkingDir } from '../bootstrap/workingDir.js';
 
+/**
+ * `shell:` 检查的默认超时——**唯一真值**。
+ *
+ * ⚠️ 这个数字此前在本文件里写了两份（`parseCheckString` 的构造处 + `runVerification`
+ * 的 `?? 30_000` 兜底），改一处漏一处就会出现「解析时 30s、执行时 60s」这种谁都看不出
+ * 的分裂。边界见 `config/numericLimits.ts::CONFIG_LIMITS.verifyShellTimeoutMs`。
+ *
+ * 为什么默认值不能太大：`verify()` 是工作流硬门，跑不完就阻塞整条流水线。
+ * 需要跑全量测试套件的场景应当缩到具体文件，或由调用方显式传 `defaultShellTimeoutMs`。
+ */
+export const DEFAULT_SHELL_CHECK_TIMEOUT_MS = 30_000;
+
 export interface Check {
   type: 'shell' | 'file_contains' | 'file_exists' | 'test_count';
   command?: string;
@@ -57,7 +76,10 @@ function parseVerifyArg(arg: string): Check | null {
 
   switch (type) {
     case 'shell':
-      return { type: 'shell', command: value, timeout: 30_000 };
+      // ⚠️ 这里**不填** timeout：解析层只管语法，超时是策略、由 runVerification 决定。
+      // 曾经在这里写死 30_000，于是 `check.timeout ?? 默认值` 里的默认值永远走不到 ——
+      // 调用方传的超时被一个「解析时顺手填上的」值静默盖掉。
+      return { type: 'shell', command: value };
     case 'file_exists':
       return { type: 'file_exists', file: value };
     case 'file_contains': {
@@ -128,12 +150,27 @@ interface ShellRunResult {
   errored: boolean;
 }
 
-function runShell(command: string, timeout: number): Promise<ShellRunResult> {
+function runShell(
+  command: string,
+  timeout: number,
+  cwd: string,
+): Promise<ShellRunResult> {
   return new Promise((resolve) => {
     const isWin = process.platform === 'win32';
+    const opts = { timeout, cwd, env: sanitizeCredentialEnv() };
+    // ⚠️ windowsVerbatimArguments: true 是必须的，不是可选优化：Node 给 cmd.exe/
+    // .bat 目标默认加一层它自己的参数转义（CVE-2024-27980 之后的安全加固），
+    // 会把 command 字符串里模型自己写好的转义（比如内嵌 PowerShell 单行脚本里的
+    // `\"..."`）再转义一遍，导致 cmd.exe 转交给子进程的字符串被改写、PowerShell
+    // 解析报 UnexpectedToken——文件内容明明字节级正确，check 却稳定失败。
+    // 已实测：一段合法的 `powershell -Command "...; Write-Host \"x\"; ..."`
+    // 不加这个选项必挂，加了立刻 exitCode 0；简单命令（echo/dir/bun --version）
+    // 行为不受影响。verify() 的 shell: 检查类型专供工作流的 hard_checks 使用，
+    // 命令来自可信的 LLM 契约草稿或用户输入，不是不可信的外部数据，
+    // 关掉这层转义不引入新的注入面。
     const child = isWin
-      ? spawn('cmd', ['/c', command], { timeout, env: sanitizeCredentialEnv() })
-      : spawn('bash', ['-c', command], { timeout, env: sanitizeCredentialEnv() });
+      ? spawn('cmd', ['/c', command], { ...opts, windowsVerbatimArguments: true })
+      : spawn('bash', ['-c', command], opts);
 
     let stdout = '';
     let stderr = '';
@@ -155,8 +192,12 @@ function runShell(command: string, timeout: number): Promise<ShellRunResult> {
   });
 }
 
-export async function verifyShell(command: string, timeout: number): Promise<CheckResult> {
-  const r = await runShell(command, timeout);
+export async function verifyShell(
+  command: string,
+  timeout: number,
+  cwd: string = getWorkingDir(),
+): Promise<CheckResult> {
+  const r = await runShell(command, timeout, cwd);
   if (r.errored) {
     return {
       check: { type: 'shell', command },
@@ -171,9 +212,12 @@ export async function verifyShell(command: string, timeout: number): Promise<Che
   };
 }
 
-export function verifyFileExists(file: string): CheckResult {
-  // 相对路径以 workingDir 为锚（绝对路径识别含 UNC）
-  const resolved = isAbsolutePath(file) ? file : `${getWorkingDir()}/${file}`;
+export function verifyFileExists(
+  file: string,
+  cwd: string = getWorkingDir(),
+): CheckResult {
+  // 相对路径以调用方给的 cwd 为锚（绝对路径识别含 UNC）
+  const resolved = isAbsolutePath(file) ? file : `${cwd}/${file}`;
   const exists = existsSync(resolved);
   return {
     check: { type: 'file_exists', file },
@@ -182,8 +226,12 @@ export function verifyFileExists(file: string): CheckResult {
   };
 }
 
-export function verifyFileContains(file: string, pattern: string): CheckResult {
-  const resolved = isAbsolutePath(file) ? file : `${getWorkingDir()}/${file}`;
+export function verifyFileContains(
+  file: string,
+  pattern: string,
+  cwd: string = getWorkingDir(),
+): CheckResult {
+  const resolved = isAbsolutePath(file) ? file : `${cwd}/${file}`;
   try {
     const content = readFileSync(resolved, 'utf8');
     const regex = new RegExp(pattern);
@@ -203,11 +251,14 @@ export function verifyFileContains(file: string, pattern: string): CheckResult {
   }
 }
 
-async function verifyTestCount(minCount: number): Promise<CheckResult> {
+async function verifyTestCount(
+  minCount: number,
+  cwd: string = getWorkingDir(),
+): Promise<CheckResult> {
   // 跨运行时：开发用 bun → bun test；npm 全局安装用 Node → npm test --silent
   // 用 process.versions.bun 探测比 typeof Bun !== 'undefined' 更稳（不依赖全局类型）
   const cmd = process.versions.bun ? 'bun test' : 'npm test --silent';
-  const r = await runShell(cmd, 60_000);
+  const r = await runShell(cmd, 60_000, cwd);
   const combined = `${r.stdout}\n${r.stderr}`;
   if (r.errored) {
     return {
@@ -232,7 +283,16 @@ async function verifyTestCount(minCount: number): Promise<CheckResult> {
  * 执行一组检查，返回聚合结果。
  * 全部通过 → passed=true；任一失败 → passed=false + summary 列出失败项。
  */
-export async function runVerification(checks: Check[]): Promise<VerifyResult> {
+export async function runVerification(
+  checks: Check[],
+  cwd: string = getWorkingDir(),
+  options: { defaultShellTimeoutMs?: number } = {},
+): Promise<VerifyResult> {
+  const shellTimeout = normalizeLimited(
+    options.defaultShellTimeoutMs,
+    CONFIG_LIMITS.verifyShellTimeoutMs,
+    DEFAULT_SHELL_CHECK_TIMEOUT_MS,
+  );
   if (checks.length === 0) {
     return { passed: true, details: [], summary: '无验证项' };
   }
@@ -244,16 +304,20 @@ export async function runVerification(checks: Check[]): Promise<VerifyResult> {
 
     switch (check.type) {
       case 'shell':
-        result = await verifyShell(check.command ?? '', check.timeout ?? 30_000);
+        result = await verifyShell(
+          check.command ?? '',
+          check.timeout ?? shellTimeout,
+          cwd,
+        );
         break;
       case 'file_exists':
-        result = verifyFileExists(check.file ?? '');
+        result = verifyFileExists(check.file ?? '', cwd);
         break;
       case 'file_contains':
-        result = verifyFileContains(check.file ?? '', check.pattern ?? '');
+        result = verifyFileContains(check.file ?? '', check.pattern ?? '', cwd);
         break;
       case 'test_count':
-        result = await verifyTestCount(check.minCount ?? 0);
+        result = await verifyTestCount(check.minCount ?? 0, cwd);
         break;
       default:
         result = {
@@ -263,7 +327,10 @@ export async function runVerification(checks: Check[]): Promise<VerifyResult> {
         };
     }
 
-    results.push(result);
+    // 回填**原始** check：各 verifier 只收散参（command/file/pattern），返回时会
+    // 自己重建一个残缺的 check 对象，把 timeout 这类字段丢掉。details 是给人排障和
+    // 给工作流做卡死指纹用的，它必须如实反映「这一条到底是按什么跑的」。
+    results.push({ ...result, check });
   }
 
   const allPassed = results.every((r) => r.passed);

package/src/llm/client.js

@@ -26,7 +26,9 @@
 import { dlog } from '../utils/debugLog.js';
 import { buildOpenAIRequest, createOpenAISSEParser, isImageInputRejected, isMaxTokensRejected, isPromptCacheKeyRejected, isResponseFormatUnsupported, } from './providers/openaiFormat.js';
 import { promptMaterialHash, shortCacheScope } from './promptCache.js';
-import { buildAnthropicRequest, createAnthropicSSEParser } from './providers/anthropicFormat.js';
+import { buildAnthropicRequest, createAnthropicSSEParser, } from './providers/anthropicFormat.js';
+import { chatGateway } from './gatewayClient.js';
+import { prepareMessagesForProvider } from './messageProvenance.js';
 /**
  * 记住"这个 baseURL::model 不支持 response_format.json_schema"，避免每次都先撞 400。
  * 单进程内有效；每个 -p 子进程是全新进程 → 首个结构化调用吃一次 400 再退化，可接受。
@@ -133,7 +135,10 @@ export function _nextRetryDelayMs(retryAfterMs) {
 }
 /** 可重试的 HTTP 状态码。4xx 除 408/425/429 外不重试（重试无意义）。 */
 function isRetryableStatus(status) {
-    return status === 408 || status === 425 || status === 429 || (status >= 500 && status < 600);
+    return (status === 408 ||
+        status === 425 ||
+        status === 429 ||
+        (status >= 500 && status < 600));
 }
 /** 鉴权类错误：明确告诉用户"key 失效/过期/无权访问"，避免重试无意义。 */
 function isClientAuthError(status) {
@@ -212,7 +217,9 @@ export function createIdleWatchdog(userSignal, timeoutMs = IDLE_TIMEOUT_MS) {
     };
     arm();
     return {
-        signal: userSignal ? AbortSignal.any([userSignal, ctrl.signal]) : ctrl.signal,
+        signal: userSignal
+            ? AbortSignal.any([userSignal, ctrl.signal])
+            : ctrl.signal,
         kick: arm,
         dispose: () => {
             if (timer)
@@ -240,8 +247,34 @@ export function createIdleWatchdog(userSignal, timeoutMs = IDLE_TIMEOUT_MS) {
  * }
  * ```
  */
+export function createModelProvider(provider) {
+    return {
+        source: provider.source === 'gateway' ? 'gateway' : 'local',
+        descriptor: provider,
+        stream: (request) => {
+            if (provider.source === 'gateway') {
+                if (request.responseFormat &&
+                    provider.gatewayCapabilities?.structuredOutput === false) {
+                    throw new Error('当前在线模型不支持结构化输出');
+                }
+                return chatGateway({
+                    provider: provider,
+                    messages: request.messages,
+                    tools: request.tools,
+                    signal: request.signal,
+                    conversationMode: request.conversationMode,
+                    responseFormat: request.responseFormat,
+                });
+            }
+            return streamLocal({ ...request, provider: provider });
+        },
+    };
+}
 export async function* chat(args) {
-    const { provider, messages, tools, signal, responseFormat, promptCache } = args;
+    yield* createModelProvider(args.provider).stream(args);
+}
+async function* streamLocal(args) {
+    const { provider, messages, tools, signal, responseFormat, promptCache, conversationMode, cacheEdits, } = args;
     const format = provider.apiFormat === 'anthropic' ? 'anthropic' : 'openai';
     if (format === 'anthropic' && responseFormat) {
         throw new Error('output_schema 结构化输出目前不支持 Anthropic Messages 格式的 provider' +
@@ -251,17 +284,14 @@ export async function* chat(args) {
     // 过滤并清洁 messages 数组，剥离 timestamp, id, _ephemeral 等本地渲染元数据。
     // 两种格式共用同一份清洗后的内部形状——Anthropic 分支的翻译（system 摘除/
     // tool_calls→tool_use 等）在 buildAnthropicRequest 内部做，不在这里做。
-    let cleanedMessages = messages
-        .filter((m) => !(m.role === 'system' && m._ephemeral === true))
-        .map((m) => {
-        const { id, timestamp, attachments, browserReferences, display_metadata, ...rest } = m;
-        return rest;
-    });
+    let cleanedMessages = prepareMessagesForProvider(messages, conversationMode ?? 'private');
     const includeUsage = process.env.MINIMAL_AGENT_DISABLE_USAGE !== '1';
     const rfKey = `${provider.baseURL}::${provider.model}`;
     // OpenAI 分支专属的「就地退化」状态；Anthropic 无此概念，两个 flag 恒为 false，
     // 下面的退化 if 分支天然不会进入（不需要额外的 format 判断散落各处）。
-    let wantResponseFormat = format === 'openai' && responseFormat !== undefined && !rfUnsupported.has(rfKey);
+    let wantResponseFormat = format === 'openai' &&
+        responseFormat !== undefined &&
+        !rfUnsupported.has(rfKey);
     let wantMaxTokens = format === 'openai' &&
         typeof provider.maxTokens === 'number' &&
         provider.maxTokens > 0 &&
@@ -278,7 +308,12 @@ export async function* chat(args) {
         const textOnly = c.filter((p) => p.type === 'text');
         const newContent = textOnly.length > 0
             ? textOnly.map((p) => ({ type: 'text', text: p.text }))
-            : [{ type: 'text', text: '[图片内容未发送：当前模型不支持图片输入]' }];
+            : [
+                {
+                    type: 'text',
+                    text: '[图片内容未发送：当前模型不支持图片输入]',
+                },
+            ];
         return { ...m, content: newContent };
     });
     // 空闲 watchdog：每个 attempt 一只（重试前换新）；fetch 等待期自动计时，
@@ -286,7 +321,12 @@ export async function* chat(args) {
     let watchdog = createIdleWatchdog(signal);
     const postChat = () => {
         const req = format === 'anthropic'
-            ? buildAnthropicRequest({ provider, cleanedMessages, tools })
+            ? buildAnthropicRequest({
+                provider,
+                cleanedMessages,
+                tools,
+                ...(cacheEdits ? { cacheEdits } : {}),
+            })
             : buildOpenAIRequest({
                 provider,
                 cleanedMessages,
@@ -298,7 +338,12 @@ export async function* chat(args) {
                 withPromptCacheKey: wantPromptCacheKey,
                 responseFormat,
             });
-        return fetch(req.url, { method: 'POST', headers: req.headers, body: req.body, signal: watchdog.signal });
+        return fetch(req.url, {
+            method: 'POST',
+            headers: req.headers,
+            body: req.body,
+            signal: watchdog.signal,
+        });
     };
     const reqId = ++reqCounter;
     dlog('llm', `req#${reqId} POST →`, {
@@ -315,7 +360,9 @@ export async function* chat(args) {
             .map((message) => message.content)),
         toolSchemaHash: promptMaterialHash(tools.map((tool) => ({
             name: tool.name,
-            description: typeof tool.description === 'function' ? tool.description() : tool.description,
+            description: typeof tool.description === 'function'
+                ? tool.description()
+                : tool.description,
             parameters: tool.parameters,
         }))),
     });
@@ -386,7 +433,8 @@ export async function* chat(args) {
             errText = await resp.text().catch(() => '');
         }
         // 退化①：response_format.json_schema 不支持
-        if (wantResponseFormat && isResponseFormatUnsupported(resp.status, errText)) {
+        if (wantResponseFormat &&
+            isResponseFormatUnsupported(resp.status, errText)) {
             // 记住该 model 不支持，单进程内后续结构化调用直接跳过 response_format（不再撞 400）。
             rfUnsupported.add(rfKey);
             console.warn(`[minimal-agent] provider model "${provider.model}" 不支持 response_format.json_schema，` +
@@ -399,7 +447,8 @@ export async function* chat(args) {
             }
             catch (e) {
                 // 退化二次 fetch 也网络错：把错误外提到外层重试循环
-                if ((await handleNetworkError(e, attempt, 'fallback fetch failed')) === 'break')
+                if ((await handleNetworkError(e, attempt, 'fallback fetch failed')) ===
+                    'break')
                     break;
                 continue;
             }
@@ -419,7 +468,8 @@ export async function* chat(args) {
                 watchdog.kick();
             }
             catch (e) {
-                if ((await handleNetworkError(e, attempt, 'fallback fetch failed')) === 'break')
+                if ((await handleNetworkError(e, attempt, 'fallback fetch failed')) ===
+                    'break')
                     break;
                 continue;
             }
@@ -432,9 +482,14 @@ export async function* chat(args) {
         if (!imagesStripped && isImageInputRejected(resp.status, errText)) {
             const hasImages = cleanedMessages.some((m) => {
                 const c = m.content;
-                return Array.isArray(c) && c.some((p) => p.type === 'image_url' || p.type === 'video_url');
+                return (Array.isArray(c) &&
+                    c.some((p) => p.type === 'image_url' || p.type === 'video_url'));
             });
             if (hasImages) {
+                if (args.visionPolicy === 'required') {
+                    throw new Error(`当前模型拒绝了本轮必需的图片输入，已停止而未删除图片重试。` +
+                        `请改用支持视觉的模型或检查模型配置。Provider 返回：${errText.slice(0, 500)}`);
+                }
                 console.warn(`[minimal-agent] provider model "${provider.model}" 不支持图片输入，` +
                     `已剥离图片重发（仅保留文本内容）。如该模型实际支持视觉，请在模型设置中确认。`);
                 cleanedMessages = stripImagesFromMessages(cleanedMessages);
@@ -444,7 +499,8 @@ export async function* chat(args) {
                     watchdog.kick();
                 }
                 catch (e) {
-                    if ((await handleNetworkError(e, attempt, 'fallback fetch failed')) === 'break')
+                    if ((await handleNetworkError(e, attempt, 'fallback fetch failed')) ===
+                        'break')
                         break;
                     continue;
                 }
@@ -486,7 +542,9 @@ export async function* chat(args) {
     const decoder = new TextDecoder();
     /** 临时缓冲：HTTP chunk 不一定按行切，要自己拼 */
     let buffer = '';
-    const parser = format === 'anthropic' ? createAnthropicSSEParser() : createOpenAISSEParser();
+    const parser = format === 'anthropic'
+        ? createAnthropicSSEParser()
+        : createOpenAISSEParser();
     try {
         while (true) {
             // 每次 read 前检查 abort：用户按 ESC/Ctrl+C 时 signal.aborted 为 true。