minimal-agent 0.10.0 → 0.12.0

package/src/bootstrap/workingDir.ts

@@ -0,0 +1,48 @@
+/**
+ * ============================================================
+ *  src/bootstrap/workingDir.ts —— 工作目录管理
+ * ------------------------------------------------------------
+ *  启动时一次性捕获 process.cwd()，后续所有"操作目录"统一通过
+ *  getWorkingDir() 读取，杜绝多处 process.cwd() 不一致的隐患。
+ *
+ *  设计选择：
+ *    - 模块级 state：单进程单 cwd，不需要 AsyncLocalStorage
+ *    - 锁定时机：main() 最开头，在加载 config / provider / history 之前
+ *    - 环境变量覆盖 MINIMAL_AGENT_CWD：测试 / docker / 显式 cd 场景
+ * ============================================================
+ */
+
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { resolve } from 'node:path';
+
+let _workingDir: string | null = null;
+const workingDirScope = new AsyncLocalStorage<string>();
+
+/** 首次调用锁定 cwd（解析 MINIMAL_AGENT_CWD），重复调用幂等。 */
+export function initWorkingDir(): string {
+  if (_workingDir !== null) return _workingDir;
+  const override = process.env.MINIMAL_AGENT_CWD;
+  _workingDir = resolve(override ?? process.cwd());
+  return _workingDir;
+}
+
+/** 读取已锁定的工作目录；尚未 init 时退到 lazy init（主要给测试）。 */
+export function getWorkingDir(): string {
+  return workingDirScope.getStore() ?? _workingDir ?? initWorkingDir();
+}
+
+/** TUI idle-only workspace switch. Callers must reject switching during a turn. */
+export function setWorkingDir(cwd: string): string {
+  _workingDir = resolve(cwd);
+  return _workingDir;
+}
+
+/** 在同一进程的某个异步调用链里临时覆盖工作目录（HTTP/Gateway 多工作区宿主用）。 */
+export function withWorkingDir<T>(cwd: string, fn: () => T): T {
+  return workingDirScope.run(resolve(cwd), fn);
+}
+
+/** 仅供测试：重置 module-level state */
+export function _resetWorkingDir(): void {
+  _workingDir = null;
+}

package/src/cli/args.js

@@ -13,7 +13,7 @@
  * ============================================================
  */
 /**
- * 从 args 里提取「带值标志」的值：找到 names 中任一标志，取其后**紧跟的下一个元素**当 value。
+ * 从 args 里提取「带值标志」的值，兼容 `--flag value` 与 `--flag=value`。
  *
  *   - 命中多次：取**第一次**出现的值
  *   - 标志在末尾（后面没有元素）：返回 undefined（args[i+1] 天然是 undefined）
@@ -24,20 +24,40 @@
  * 用于 -p 模式提取 --output-format / --max-turns 的值。
  */
 export function extractFlagValue(args, names) {
-    for (let i = 0; i < args.length; i++) {
-        if (names.includes(args[i])) {
-            return args[i + 1]; // 末尾标志时 args[i+1] 为 undefined，符合语义
+    const normalized = normalizeArgs(args); // `--flag=value` → 空格式，见 normalizeArgs
+    for (let i = 0; i < normalized.length; i++) {
+        const arg = normalized[i];
+        if (names.includes(arg)) {
+            return normalized[i + 1]; // 末尾标志时 [i+1] 为 undefined，符合语义
+        }
+        // 两道防线是互补的、不是重复：normalizeArgs 只展开 VALUE_FLAGS 里的**已知**名字
+        // （它面向全局 argv，不能替未知标志猜语义）；而调用方可以传任意别名
+        // （测试里的 `['--output-format','--fmt']` 就是），那些名字 normalizeArgs 认不出，
+        // 由这里按传入的 name 再兜一次 `=` 形式。
+        for (const name of names) {
+            if (arg.startsWith(`${name}=`))
+                return arg.slice(name.length + 1);
         }
     }
     return undefined;
 }
 /** 提取可重复带值标志，例如 `--image a.png --image b.png`。 */
 export function extractFlagValues(args, names) {
+    const normalized = normalizeArgs(args);
     const values = [];
-    for (let i = 0; i < args.length; i++) {
-        if (names.includes(args[i]) && args[i + 1] !== undefined) {
-            values.push(args[i + 1]);
+    for (let i = 0; i < normalized.length; i++) {
+        const arg = normalized[i];
+        if (names.includes(arg) && normalized[i + 1] !== undefined) {
+            values.push(normalized[i + 1]);
             i++;
+            continue;
+        }
+        // 同 extractFlagValue：调用方传入的别名不在 VALUE_FLAGS 里时的兜底。
+        for (const name of names) {
+            if (arg.startsWith(`${name}=`)) {
+                values.push(arg.slice(name.length + 1));
+                break;
+            }
         }
     }
     return values;
@@ -73,4 +93,47 @@ export const VALUE_FLAGS = new Set([
     '--image',
     '--image-detail',
     '--image-max-long-side-pixel',
+    '--memory-access',
+    '--computer-use',
+    '--computer-use-trace',
 ]);
+/**
+ * 把 GNU 风格的 `--flag=value` 展开成 `['--flag', 'value']`，让下游全部按空格式解析。
+ *
+ * **为什么必须有这一步**：本文件的 `extractFlagValue`、`print.ts::extractPromptArgs`、
+ * `bootstrap/cwdArg.ts::extractCwdArg` 都按**精确名字**匹配标志，`=` 形式因此谁都认不出来，
+ * 而且失败是**静默**的——回落默认值，同时那串 token 还被当成 prompt 文本喂给模型：
+ *
+ *   `--cwd=/tmp/job-123`     → 工作目录没切，产物全写在当前目录
+ *   `--session=foo`          → 读写落到 `default` 会话（会话串错）
+ *   `--output-format=json`   → 回落 text，宿主 JSON.parse 直接炸
+ *
+ * 修在解析层而不是逐个标志各自兜底：`memoryAccess.ts` 曾单独认过一次 `=`，那种补丁
+ * 只保住被打补丁的那一个标志，其余照旧静默失败。
+ *
+ * **保守边界（有意为之）**：
+ *  - 只展开 `VALUE_FLAGS` 里**已知**的名字。未知的 `--foo=bar` 原样保留——它极可能是
+ *    prompt 正文（`-p "把 --foo=bar 解释一下"`），盲目展开会把用户的话拆碎。
+ *  - 只认 `--` 长标志。GNU 惯例里 `=` 属于长选项；短选项写法是 `-d val` 或 `-dval`，
+ *    `-d=x` 在多数 CLI 里意思是「值是 `=x`」，不该替用户猜。
+ *  - 按**第一个** `=` 切分（`slice` 而非 `split`）：值本身可以再含 `=`，
+ *    Windows 路径与 base64 padding 都会出现，`--cwd=D:\a=b` 必须得到 `D:\a=b`。
+ *
+ * 幂等：展开后的 `--flag` 不含 `=`、value 不以 `--` 开头，再跑一次原样返回。
+ * 因此可以在最外层入口调一次、又在各消费函数内部防御性再调一次。
+ */
+export function normalizeArgs(args) {
+    const result = [];
+    for (const arg of args) {
+        const eq = arg.indexOf('=');
+        if (eq > 0 && arg.startsWith('--')) {
+            const name = arg.slice(0, eq);
+            if (VALUE_FLAGS.has(name)) {
+                result.push(name, arg.slice(eq + 1));
+                continue;
+            }
+        }
+        result.push(arg);
+    }
+    return result;
+}

package/src/cli/args.ts

@@ -0,0 +1,146 @@
+/**
+ * ============================================================
+ *  src/cli/args.ts —— CLI 参数解析纯函数
+ * ------------------------------------------------------------
+ *  零依赖、零副作用的命令行参数提取工具，供 main.tsx 的 -p 分支使用。
+ *
+ *  为什么单独成文件（而非塞进 main.tsx）：
+ *    main.tsx 顶层有 `main().catch(...)` 自调用，一旦被 import 就会启动整个
+ *    应用。把纯函数抽出来，单测可零副作用地 import 断言。main.tsx re-export
+ *    同名符号，对外仍是「main.tsx 提供 extractFlagValue」的语义。
+ *
+ *  不引 commander：手撸即可，逻辑足够简单且教学清晰。
+ * ============================================================
+ */
+
+/**
+ * 从 args 里提取「带值标志」的值，兼容 `--flag value` 与 `--flag=value`。
+ *
+ *   - 命中多次：取**第一次**出现的值
+ *   - 标志在末尾（后面没有元素）：返回 undefined（args[i+1] 天然是 undefined）
+ *   - 没命中任何 name：返回 undefined
+ *
+ * 例：extractFlagValue(['-p','--output-format','json','x'], ['--output-format']) === 'json'
+ *
+ * 用于 -p 模式提取 --output-format / --max-turns 的值。
+ */
+export function extractFlagValue(
+  args: string[],
+  names: string[],
+): string | undefined {
+  const normalized = normalizeArgs(args); // `--flag=value` → 空格式，见 normalizeArgs
+  for (let i = 0; i < normalized.length; i++) {
+    const arg = normalized[i]!;
+    if (names.includes(arg)) {
+      return normalized[i + 1]; // 末尾标志时 [i+1] 为 undefined，符合语义
+    }
+    // 两道防线是互补的、不是重复：normalizeArgs 只展开 VALUE_FLAGS 里的**已知**名字
+    // （它面向全局 argv，不能替未知标志猜语义）；而调用方可以传任意别名
+    // （测试里的 `['--output-format','--fmt']` 就是），那些名字 normalizeArgs 认不出，
+    // 由这里按传入的 name 再兜一次 `=` 形式。
+    for (const name of names) {
+      if (arg.startsWith(`${name}=`)) return arg.slice(name.length + 1);
+    }
+  }
+  return undefined;
+}
+
+/** 提取可重复带值标志，例如 `--image a.png --image b.png`。 */
+export function extractFlagValues(args: string[], names: string[]): string[] {
+  const normalized = normalizeArgs(args);
+  const values: string[] = [];
+  for (let i = 0; i < normalized.length; i++) {
+    const arg = normalized[i]!;
+    if (names.includes(arg) && normalized[i + 1] !== undefined) {
+      values.push(normalized[i + 1]!);
+      i++;
+      continue;
+    }
+    // 同 extractFlagValue：调用方传入的别名不在 VALUE_FLAGS 里时的兜底。
+    for (const name of names) {
+      if (arg.startsWith(`${name}=`)) {
+        values.push(arg.slice(name.length + 1));
+        break;
+      }
+    }
+  }
+  return values;
+}
+
+/**
+ * CLI 布尔标志（出现即生效、不带值）。集中定义一份，供 print.ts 的 extractPromptArgs
+ * 共用 —— 避免 flag 列表在多处各维护一份、新增 flag 时漏改导致「flag 值被当 prompt 污染」。
+ */
+export const BOOLEAN_FLAGS: ReadonlySet<string> = new Set([
+  '-p',
+  '--print',
+  '--verbose',
+  '-v',
+  '-h',
+  '--help',
+  '-V',
+  '--version',
+  '--clear',
+  '--compact',
+  '--workspace-doctor',
+]);
+
+/**
+ * CLI 带值标志（标志本身 + 紧跟的下一个元素都不是位置参数）。
+ * 新增带值标志务必加到这里，否则它的值会被 extractPromptArgs 当成 prompt 文本。
+ */
+export const VALUE_FLAGS: ReadonlySet<string> = new Set([
+  '-d',
+  '--cwd',
+  '-s',
+  '--session',
+  '--output-format',
+  '--max-turns',
+  '--image',
+  '--image-detail',
+  '--image-max-long-side-pixel',
+  '--memory-access',
+  '--computer-use',
+  '--computer-use-trace',
+]);
+
+/**
+ * 把 GNU 风格的 `--flag=value` 展开成 `['--flag', 'value']`，让下游全部按空格式解析。
+ *
+ * **为什么必须有这一步**：本文件的 `extractFlagValue`、`print.ts::extractPromptArgs`、
+ * `bootstrap/cwdArg.ts::extractCwdArg` 都按**精确名字**匹配标志，`=` 形式因此谁都认不出来，
+ * 而且失败是**静默**的——回落默认值，同时那串 token 还被当成 prompt 文本喂给模型：
+ *
+ *   `--cwd=/tmp/job-123`     → 工作目录没切，产物全写在当前目录
+ *   `--session=foo`          → 读写落到 `default` 会话（会话串错）
+ *   `--output-format=json`   → 回落 text，宿主 JSON.parse 直接炸
+ *
+ * 修在解析层而不是逐个标志各自兜底：`memoryAccess.ts` 曾单独认过一次 `=`，那种补丁
+ * 只保住被打补丁的那一个标志，其余照旧静默失败。
+ *
+ * **保守边界（有意为之）**：
+ *  - 只展开 `VALUE_FLAGS` 里**已知**的名字。未知的 `--foo=bar` 原样保留——它极可能是
+ *    prompt 正文（`-p "把 --foo=bar 解释一下"`），盲目展开会把用户的话拆碎。
+ *  - 只认 `--` 长标志。GNU 惯例里 `=` 属于长选项；短选项写法是 `-d val` 或 `-dval`，
+ *    `-d=x` 在多数 CLI 里意思是「值是 `=x`」，不该替用户猜。
+ *  - 按**第一个** `=` 切分（`slice` 而非 `split`）：值本身可以再含 `=`，
+ *    Windows 路径与 base64 padding 都会出现，`--cwd=D:\a=b` 必须得到 `D:\a=b`。
+ *
+ * 幂等：展开后的 `--flag` 不含 `=`、value 不以 `--` 开头，再跑一次原样返回。
+ * 因此可以在最外层入口调一次、又在各消费函数内部防御性再调一次。
+ */
+export function normalizeArgs(args: string[]): string[] {
+  const result: string[] = [];
+  for (const arg of args) {
+    const eq = arg.indexOf('=');
+    if (eq > 0 && arg.startsWith('--')) {
+      const name = arg.slice(0, eq);
+      if (VALUE_FLAGS.has(name)) {
+        result.push(name, arg.slice(eq + 1));
+        continue;
+      }
+    }
+    result.push(arg);
+  }
+  return result;
+}

package/src/cli/computerUse.js

@@ -0,0 +1,185 @@
+import { randomUUID } from 'node:crypto';
+import { readdir, readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { inferComputerUseCapabilities } from '../tools/computeruse/grants.js';
+import { anonymousOwnerId } from '../tools/computeruse/computerUseService.js';
+import { extractFlagValue } from './args.js';
+export function resolveComputerUseMode(args) {
+    const raw = extractFlagValue(args, ['--computer-use']);
+    if (raw === undefined)
+        return 'disabled';
+    if (raw === 'observe' || raw === 'interactive')
+        return raw;
+    throw new Error('--computer-use 只接受 observe 或 interactive');
+}
+export function resolveComputerUseTraceDir(args) {
+    const raw = extractFlagValue(args, ['--computer-use-trace']);
+    if (raw === undefined)
+        return undefined;
+    if (!raw.trim())
+        throw new Error('--computer-use-trace 需要一个目录路径');
+    return resolve(raw);
+}
+function capabilitiesForMode(mode, userInput) {
+    if (mode === 'observe')
+        return ['observe'];
+    // interactive 只开放基础交互。剪贴板、文件投放和最终提交仍必须由
+    // 当前用户输入明确表达，不能因为一个 CLI 标志获得持续扩权。
+    return inferComputerUseCapabilities(userInput);
+}
+export function createCliComputerRun(input) {
+    return {
+        ownerId: anonymousOwnerId(),
+        conversationKey: input.conversationKey,
+        runId: randomUUID(),
+        surface: input.surface,
+        allowedApps: [],
+        grantId: randomUUID(),
+        capabilities: capabilitiesForMode(input.mode, input.userInput),
+        ...(input.allowedFileRoots
+            ? { allowedFileRoots: input.allowedFileRoots.map((root) => resolve(root)) }
+            : {}),
+        supervised: input.supervised,
+        // 原话只进确认弹窗的说明文字，不参与授权判定（见 ComputerUseRunContext.userInput）。
+        userInput: input.userInput,
+        ...(input.diagnosticTraceDir
+            ? { diagnosticTraceDir: resolve(input.diagnosticTraceDir) }
+            : {}),
+    };
+}
+/**
+ * TUI and interactive CLI do not have the Desktop Runtime's coordinator, but
+ * they must still enforce the same host-owned run identity and capability
+ * boundary before a model reaches the native helper. The tool repeats these
+ * checks as defence in depth; this gate is the host policy boundary.
+ */
+export function createComputerUseHostGate(context, fallback) {
+    return async (request, signal) => {
+        if (request.name !== 'ComputerUse') {
+            return fallback ? fallback(request, signal) : { allow: true };
+        }
+        const scope = request.runContext;
+        if (!scope
+            || scope.ownerId !== context.ownerId
+            || scope.conversationKey !== context.conversationKey
+            || scope.runId !== context.runId) {
+            return { allow: false, reason: 'Computer Use 运行身份与当前本机会话不匹配。' };
+        }
+        const capability = request.action?.capability;
+        // ★ `submit` 是唯一不在这里终局判定的能力，**故意放行到工具层**。
+        //
+        // 它对应「不可逆动作」，而真正的审批需要「这一步要提交什么、目标应用是
+        // 哪个、应用指南怎么说」这些只有工具层才拿得到的上下文 —— gate 这里连
+        // 前台应用是谁都不知道，问不出一个人能一眼判断的问题。
+        //
+        // 更要紧的是：没有任何路径会预先授予 submit（`grants.ts` 有意不再从用户
+        // 措辞里猜它）。所以 gate 在这里拒死等于让人工审批**永远不可达**，
+        // 「发消息/提交表单/关窗」会被永久拒绝，哪怕用户就在旁边点头。这曾是
+        // 真实存在的死路。
+        //
+        // 放行 submit ≠ 放行一切：工具侧 `authorizeIrreversibleAction` 是这条路径
+        // 的终局关卡，且它在 `supervised !== true` 时无条件拒绝 —— 非交互宿主的
+        // 边界由那一层守住，不依赖这里。批准写的是限定到 (应用, 动作类别) 的
+        // grant（`ComputerUseIrreversibleGrant`），不是一张本回合通用的 submit 通行证。
+        if (capability !== 'submit'
+            && (!capability || !context.capabilities.includes(capability))) {
+            // ⚠️ 拒绝也要指路。实测：`type` 直接输入中文失败后，模型自己想到用
+            //    剪贴板绕，去调 `clipboard_write`，只收到一句「未获得授权」——
+            //    它不知道 `type` **内部已经有**剪贴板兜底（写入、粘贴、还原原内容），
+            //    根本不需要这个能力，于是白卡一轮。
+            return {
+                allow: false,
+                reason: `当前回合未获得 Computer Use ${capability ?? 'unknown'} 授权。`
+                    + (capability === 'clipboard-write'
+                        ? ' 如果你只是想输入一段文字（含中文/emoji），不需要这个能力：直接用 `type`。'
+                            + '系统装着输入法时合成按键到不了控件，`type` 会自己整串走剪贴板粘贴'
+                            + '并还原你原来的剪贴板内容 —— 这是它内部的确定性选路，不额外要授权。'
+                        : ''),
+            };
+        }
+        const targetApp = request.action?.targetApp;
+        if (targetApp && context.allowedApps.length > 0 && !context.allowedApps.includes(targetApp)) {
+            return { allow: false, reason: '目标应用不在当前回合的 Computer Use 授权范围内。' };
+        }
+        return { allow: true };
+    };
+}
+function computerUseStateDir() {
+    if (process.env.KAKADEAI_CU_HOME)
+        return resolve(process.env.KAKADEAI_CU_HOME);
+    if (process.platform === 'darwin') {
+        return join(homedir(), 'Library', 'Application Support', 'KakadeAI', 'computer-use');
+    }
+    if (process.platform === 'win32') {
+        return join(process.env.LOCALAPPDATA ?? homedir(), 'KakadeAI', 'computer-use');
+    }
+    return join(process.env.XDG_STATE_HOME ?? join(homedir(), '.local', 'state'), 'kakadeai', 'computer-use');
+}
+/**
+ * 收集所有审计文件：共享根目录下的历史文件 + 每个宿主桶里的当前文件。
+ *
+ * 守护进程的状态按宿主身份分桶之后（见 `computerUseHostStateDir`），审计也跟着分散到
+ * `hosts/<tag>/audit.jsonl`。读取方必须跨桶汇总，否则「分桶」这个内部实现细节会直接
+ * 表现为「审计记录突然全没了」。根目录那份是分桶之前的历史数据，一并读入不丢。
+ */
+async function auditFiles() {
+    const root = computerUseStateDir();
+    const files = [join(root, 'audit.jsonl')];
+    try {
+        const hosts = await readdir(join(root, 'hosts'), { withFileTypes: true });
+        for (const entry of hosts) {
+            if (entry.isDirectory())
+                files.push(join(root, 'hosts', entry.name, 'audit.jsonl'));
+        }
+    }
+    catch {
+        // 还没有任何宿主桶：只读根目录那份。
+    }
+    return files;
+}
+export async function readRecentComputerUseAudit(limit = 10) {
+    const safeLimit = Math.max(1, Math.min(100, Math.floor(limit)));
+    try {
+        const chunks = await Promise.all((await auditFiles()).map((file) => readFile(file, 'utf8').catch(() => '')));
+        // 跨桶汇总要按时间排序，否则「最近 N 条」会变成「桶 A 的全部 + 桶 B 的全部」。
+        // 无时间戳的行排到最前（宁可先被截掉，也不让它挤掉真正最近的记录）。
+        const ordered = chunks
+            .flatMap((content) => content.split(/\r?\n/))
+            .filter(Boolean)
+            .map((line) => {
+            let at = 0;
+            try {
+                const ts = JSON.parse(line).timestampMs;
+                if (typeof ts === 'number')
+                    at = ts;
+            }
+            catch { /* 解析不了的行保留，下面会显示成「无法解析的审计记录」 */ }
+            return { line, at };
+        })
+            .sort((a, b) => a.at - b.at);
+        return ordered
+            .slice(-safeLimit)
+            .map(({ line }) => {
+            try {
+                const record = JSON.parse(line);
+                const timestamp = typeof record.timestampMs === 'number'
+                    ? new Date(record.timestampMs).toLocaleString()
+                    : '未知时间';
+                const operation = typeof record.operation === 'string' ? record.operation : 'unknown';
+                const outcome = typeof record.outcome === 'string' ? record.outcome : 'unknown';
+                const target = typeof record.targetApp === 'string' ? ` · ${record.targetApp}` : '';
+                const error = typeof record.errorCode === 'string' ? ` · ${record.errorCode}` : '';
+                return `${timestamp} · ${operation}${target} · ${outcome}${error}`;
+            }
+            catch {
+                return '无法解析的审计记录';
+            }
+        });
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+}