minimal-agent 0.10.0 → 0.12.0

package/src/humanIntervention.ts

@@ -0,0 +1,216 @@
+import { randomUUID } from 'node:crypto';
+
+// 这里曾 re-export `tools/computeruse/humanBoundary.js` 的
+// `detectComputerHumanBoundary` —— 一个**通用**的人机接管模块
+// （surface: 'browser' | 'computer'）顶头挂一个具体工具的符号，
+// 是最容易被后人当成"通用能力"到处引的形状。已移除：需要它的消费方
+// 直接从 `tools/computeruse/humanBoundary.js` 取，谁用谁依赖，路径如实。
+
+export type HumanInterventionReason =
+  | 'password'
+  | 'otp'
+  | 'captcha'
+  | 'qr_login'
+  | 'login'
+  | 'permission'
+  | 'security_warning'
+  | 'blocked'
+  | 'manual';
+
+export type HumanInterventionSurface = 'browser' | 'computer';
+
+export interface HumanInterventionIdentity {
+  ownerId: string;
+  conversationKey: string;
+  runId: string;
+}
+
+export interface HumanInterventionTarget {
+  tabId?: string;
+  origin?: string;
+  appId?: string;
+  windowId?: string;
+}
+
+export interface HumanInterventionRequest extends HumanInterventionIdentity {
+  surface: HumanInterventionSurface;
+  reason: HumanInterventionReason;
+  sanitizedSummary: string;
+  target?: HumanInterventionTarget;
+  expiresAt?: number;
+}
+
+export interface PendingHumanIntervention extends HumanInterventionRequest {
+  id: string;
+  resumeToken: string;
+  requestedAt: number;
+}
+
+export type HumanInterventionResolutionStatus = 'resumed' | 'cancelled' | 'expired' | 'aborted';
+
+export interface HumanInterventionResolution {
+  status: HumanInterventionResolutionStatus;
+  intervention: PendingHumanIntervention;
+  resolvedAt: number;
+  waitedMs: number;
+}
+
+export type HumanInterventionEvent =
+  | { type: 'started'; intervention: PendingHumanIntervention }
+  | { type: 'resolved'; resolution: HumanInterventionResolution };
+
+export interface HumanInterventionCredential extends HumanInterventionIdentity {
+  id: string;
+  resumeToken: string;
+}
+
+type Waiter = {
+  resolve: (resolution: HumanInterventionResolution) => void;
+  reject: (error: unknown) => void;
+  cleanup: () => void;
+};
+
+type ActiveIntervention = {
+  pending: PendingHumanIntervention;
+  waiters: Set<Waiter>;
+  expiryTimer?: ReturnType<typeof setTimeout>;
+};
+
+function interventionKey(identity: HumanInterventionIdentity): string {
+  return `${identity.ownerId}\u0000${identity.conversationKey}\u0000${identity.runId}`;
+}
+
+function sameIdentity(
+  pending: PendingHumanIntervention,
+  credential: HumanInterventionCredential,
+): boolean {
+  return pending.id === credential.id
+    && pending.resumeToken === credential.resumeToken
+    && pending.ownerId === credential.ownerId
+    && pending.conversationKey === credential.conversationKey
+    && pending.runId === credential.runId;
+}
+
+/**
+ * Process-local coordination for sensitive handoffs. It deliberately stores no
+ * secret input: only a sanitized reason and the run identity cross this boundary.
+ */
+export class HumanInterventionCoordinator {
+  private readonly active = new Map<string, ActiveIntervention>();
+  private readonly byId = new Map<string, ActiveIntervention>();
+  private readonly listeners = new Set<(event: HumanInterventionEvent) => void>();
+
+  request(input: HumanInterventionRequest): PendingHumanIntervention {
+    const key = interventionKey(input);
+    const current = this.active.get(key);
+    if (current) return current.pending;
+
+    const requestedAt = Date.now();
+    const pending: PendingHumanIntervention = {
+      ...input,
+      id: randomUUID(),
+      resumeToken: randomUUID(),
+      requestedAt,
+    };
+    const entry: ActiveIntervention = { pending, waiters: new Set() };
+    if (pending.expiresAt !== undefined) {
+      const delay = Math.max(0, pending.expiresAt - requestedAt);
+      entry.expiryTimer = setTimeout(() => {
+        this.resolveEntry(entry, 'expired');
+      }, delay);
+      entry.expiryTimer.unref?.();
+    }
+    this.active.set(key, entry);
+    this.byId.set(pending.id, entry);
+    this.emit({ type: 'started', intervention: pending });
+    return pending;
+  }
+
+  get(identity: HumanInterventionIdentity): PendingHumanIntervention | undefined {
+    return this.active.get(interventionKey(identity))?.pending;
+  }
+
+  subscribe(listener: (event: HumanInterventionEvent) => void): () => void {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+
+  wait(id: string, signal?: AbortSignal): Promise<HumanInterventionResolution> {
+    const entry = this.byId.get(id);
+    if (!entry) return Promise.reject(new Error('人工介入请求不存在或已结束'));
+
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      const waiter: Waiter = {
+        resolve: (resolution) => {
+          if (settled) return;
+          settled = true;
+          waiter.cleanup();
+          resolve(resolution);
+        },
+        reject: (error) => {
+          if (settled) return;
+          settled = true;
+          waiter.cleanup();
+          reject(error);
+        },
+        cleanup: () => signal?.removeEventListener('abort', onAbort),
+      };
+      const onAbort = () => {
+        entry.waiters.delete(waiter);
+        waiter.reject(new DOMException('aborted', 'AbortError'));
+      };
+      entry.waiters.add(waiter);
+      signal?.addEventListener('abort', onAbort, { once: true });
+      if (signal?.aborted) onAbort();
+    });
+  }
+
+  resume(credential: HumanInterventionCredential): boolean {
+    return this.resolveCredential(credential, 'resumed');
+  }
+
+  cancel(credential: HumanInterventionCredential): boolean {
+    return this.resolveCredential(credential, 'cancelled');
+  }
+
+  abort(identity: HumanInterventionIdentity): boolean {
+    const entry = this.active.get(interventionKey(identity));
+    if (!entry) return false;
+    this.resolveEntry(entry, 'aborted');
+    return true;
+  }
+
+  private resolveCredential(
+    credential: HumanInterventionCredential,
+    status: Extract<HumanInterventionResolutionStatus, 'resumed' | 'cancelled'>,
+  ): boolean {
+    const entry = this.byId.get(credential.id);
+    if (!entry || !sameIdentity(entry.pending, credential)) return false;
+    this.resolveEntry(entry, status);
+    return true;
+  }
+
+  private resolveEntry(entry: ActiveIntervention, status: HumanInterventionResolutionStatus): void {
+    const key = interventionKey(entry.pending);
+    if (this.active.get(key) !== entry || this.byId.get(entry.pending.id) !== entry) return;
+
+    this.active.delete(key);
+    this.byId.delete(entry.pending.id);
+    if (entry.expiryTimer) clearTimeout(entry.expiryTimer);
+    const resolvedAt = Date.now();
+    const resolution: HumanInterventionResolution = {
+      status,
+      intervention: entry.pending,
+      resolvedAt,
+      waitedMs: Math.max(0, resolvedAt - entry.pending.requestedAt),
+    };
+    for (const waiter of [...entry.waiters]) waiter.resolve(resolution);
+    entry.waiters.clear();
+    this.emit({ type: 'resolved', resolution });
+  }
+
+  private emit(event: HumanInterventionEvent): void {
+    for (const listener of this.listeners) listener(event);
+  }
+}

package/src/infra/verification.ts

@@ -0,0 +1,295 @@
+/**
+ * ============================================================
+ *  src/infra/verification.ts —— 共享验证基础设施
+ * ------------------------------------------------------------
+ *  支持四种检查器（跨平台）：
+ *    - shell:<cmd>                跨平台 spawn（Windows 走 cmd /c, 其余 bash -c）
+ *    - file_exists:<path>         fs.existsSync
+ *    - file_contains:<file>:<re>  正则匹配文件内容
+ *    - test_count:<min>           跑 `bun test`，从 stdout 解析 "N pass"
+ *
+ *  消费者：
+ *    - workflow-runner 插件（verify 步骤类型）
+ *    - 工作流 YAML 的 type: verify 步骤
+ *    - 未来任何需要声明式验证的插件或模块
+ *
+ *  设计原则：
+ *    - 纯工具函数，无全局状态，无副作用（除了 shell 子进程）
+ *    - 不依赖任何插件代码，可被 src/ 和 plugins/ 同时导入
+ *    - 工作目录隔离：所有相对路径以 getWorkingDir() 为锚
+ * ============================================================
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+import { sanitizeCredentialEnv } from '../config/configService.js';
+
+import { getWorkingDir } from '../bootstrap/workingDir.js';
+
+export interface Check {
+  type: 'shell' | 'file_contains' | 'file_exists' | 'test_count';
+  command?: string;
+  file?: string;
+  pattern?: string;
+  minCount?: number;
+  timeout?: number;
+}
+
+export interface CheckResult {
+  check: Check;
+  passed: boolean;
+  output: string;
+}
+
+export interface VerifyResult {
+  passed: boolean;
+  details: CheckResult[];
+  summary: string;
+}
+
+/** 从 "type:value" 字符串解析为 Check 对象。 */
+function parseVerifyArg(arg: string): Check | null {
+  const colonIdx = arg.indexOf(':');
+  if (colonIdx < 0) return null;
+
+  const type = arg.slice(0, colonIdx).trim().toLowerCase();
+  const value = arg.slice(colonIdx + 1).trim();
+
+  switch (type) {
+    case 'shell':
+      return { type: 'shell', command: value, timeout: 30_000 };
+    case 'file_exists':
+      return { type: 'file_exists', file: value };
+    case 'file_contains': {
+      const sep = value.indexOf(':');
+      if (sep < 0) return null;
+      return {
+        type: 'file_contains',
+        file: value.slice(0, sep),
+        pattern: value.slice(sep + 1),
+      };
+    }
+    case 'test_count': {
+      const count = parseInt(value, 10);
+      if (isNaN(count) || count < 0) return null;
+      return { type: 'test_count', minCount: count };
+    }
+    default:
+      return null;
+  }
+}
+
+/**
+ * 从命令行参数字符串中提取所有 --verify 项。
+ * 兼容两种调用方式：
+ *   - 工作流 / 命令的 args 字符串：`"goal --verify 'shell:bun test'"`
+ *   - workflow verify 步骤的 checks 数组元素：`"shell:bun test"`
+ */
+export function parseVerifyArgs(args: string): Check[] {
+  const checks: Check[] = [];
+  const regex = /--verify\s+("[^"]*"|\S+)/gi;
+  let match;
+
+  while ((match = regex.exec(args)) !== null) {
+    const raw = match[1].replace(/^"|"$/g, '');
+    const check = parseVerifyArg(raw);
+    if (check) checks.push(check);
+  }
+
+  return checks;
+}
+
+/** 从单个 check 字符串解析（workflow verify 步骤用）。
+ *  parseVerifyArg 是底层解析器；本函数保留独立名字是因为 verify.ts:14 直接 import 它。
+ *  parseVerifyArgs 用于从命令行参数字符串抓 --verify 项——两者职责不重叠。 */
+export function parseCheckString(raw: string): Check | null {
+  return parseVerifyArg(raw);
+}
+
+/**
+ * 判断路径是否为绝对路径（POSIX / Windows drive / Windows UNC）。
+ *  - POSIX:    /usr/local/...
+ *  - Win drive: C:\Users\... 或 C:/foo
+ *  - UNC:       \\server\share\...
+ * 之前漏识别 UNC → 会被错误地拼上 workingDir 前缀，file_exists 永远查不到。
+ */
+function isAbsolutePath(file: string): boolean {
+  return (
+    file.startsWith('/') ||
+    file.startsWith('\\') || // 同时覆盖 \foo 和 \\server（前者非常规但兼容）
+    /^[A-Za-z]:[\\/]/.test(file) // C:\ 或 C:/
+  );
+}
+
+interface ShellRunResult {
+  exitCode: number | null;
+  stdout: string;
+  stderr: string;
+  errored: boolean;
+}
+
+function runShell(command: string, timeout: number): Promise<ShellRunResult> {
+  return new Promise((resolve) => {
+    const isWin = process.platform === 'win32';
+    const child = isWin
+      ? spawn('cmd', ['/c', command], { timeout, env: sanitizeCredentialEnv() })
+      : spawn('bash', ['-c', command], { timeout, env: sanitizeCredentialEnv() });
+
+    let stdout = '';
+    let stderr = '';
+
+    child.stdout.on('data', (d: Buffer) => {
+      stdout += d.toString();
+    });
+    child.stderr.on('data', (d: Buffer) => {
+      stderr += d.toString();
+    });
+
+    child.on('error', () => {
+      resolve({ exitCode: null, stdout, stderr, errored: true });
+    });
+
+    child.on('close', (code) => {
+      resolve({ exitCode: code, stdout, stderr, errored: false });
+    });
+  });
+}
+
+export async function verifyShell(command: string, timeout: number): Promise<CheckResult> {
+  const r = await runShell(command, timeout);
+  if (r.errored) {
+    return {
+      check: { type: 'shell', command },
+      passed: false,
+      output: `执行失败`,
+    };
+  }
+  return {
+    check: { type: 'shell', command },
+    passed: r.exitCode === 0,
+    output: r.stdout.trim() || r.stderr.trim() || `exit code ${r.exitCode}`,
+  };
+}
+
+export function verifyFileExists(file: string): CheckResult {
+  // 相对路径以 workingDir 为锚（绝对路径识别含 UNC）
+  const resolved = isAbsolutePath(file) ? file : `${getWorkingDir()}/${file}`;
+  const exists = existsSync(resolved);
+  return {
+    check: { type: 'file_exists', file },
+    passed: exists,
+    output: exists ? '文件存在' : `文件不存在: ${resolved}`,
+  };
+}
+
+export function verifyFileContains(file: string, pattern: string): CheckResult {
+  const resolved = isAbsolutePath(file) ? file : `${getWorkingDir()}/${file}`;
+  try {
+    const content = readFileSync(resolved, 'utf8');
+    const regex = new RegExp(pattern);
+    const matched = regex.test(content);
+
+    return {
+      check: { type: 'file_contains', file, pattern },
+      passed: matched,
+      output: matched ? `文件包含 "${pattern}"` : `文件不包含 "${pattern}"`,
+    };
+  } catch {
+    return {
+      check: { type: 'file_contains', file, pattern },
+      passed: false,
+      output: `无法读取文件: ${resolved}`,
+    };
+  }
+}
+
+async function verifyTestCount(minCount: number): 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 combined = `${r.stdout}\n${r.stderr}`;
+  if (r.errored) {
+    return {
+      check: { type: 'test_count', minCount },
+      passed: false,
+      output: '无法执行 bun test',
+    };
+  }
+
+  const matches = [...combined.matchAll(/(\d+)\s+pass/gi)];
+  const count = matches.length > 0 ? parseInt(matches[matches.length - 1][1], 10) : 0;
+  const passed = count >= minCount;
+
+  return {
+    check: { type: 'test_count', minCount },
+    passed,
+    output: `${count} pass (需要 >=${minCount})`,
+  };
+}
+
+/**
+ * 执行一组检查，返回聚合结果。
+ * 全部通过 → passed=true；任一失败 → passed=false + summary 列出失败项。
+ */
+export async function runVerification(checks: Check[]): Promise<VerifyResult> {
+  if (checks.length === 0) {
+    return { passed: true, details: [], summary: '无验证项' };
+  }
+
+  const results: CheckResult[] = [];
+
+  for (const check of checks) {
+    let result: CheckResult;
+
+    switch (check.type) {
+      case 'shell':
+        result = await verifyShell(check.command ?? '', check.timeout ?? 30_000);
+        break;
+      case 'file_exists':
+        result = verifyFileExists(check.file ?? '');
+        break;
+      case 'file_contains':
+        result = verifyFileContains(check.file ?? '', check.pattern ?? '');
+        break;
+      case 'test_count':
+        result = await verifyTestCount(check.minCount ?? 0);
+        break;
+      default:
+        result = {
+          check,
+          passed: false,
+          output: `未知验证类型: ${(check as { type: string }).type}`,
+        };
+    }
+
+    results.push(result);
+  }
+
+  const allPassed = results.every((r) => r.passed);
+  const failedNames = results.filter((r) => !r.passed).map((r) => formatCheckName(r.check));
+
+  let summary: string;
+  if (allPassed) {
+    summary = `✅ 全部通过 (${results.length}/${results.length})`;
+  } else {
+    summary = `❌ 验证未通过: ${failedNames.join(', ')}`;
+  }
+
+  return { passed: allPassed, details: results, summary };
+}
+
+function formatCheckName(check: Check): string {
+  switch (check.type) {
+    case 'shell':
+      return `shell(${(check.command ?? '').slice(0, 40)})`;
+    case 'file_exists':
+      return `exists(${check.file})`;
+    case 'file_contains':
+      return `contains(${check.file}:${check.pattern})`;
+    case 'test_count':
+      return `tests(>=${check.minCount})`;
+    default:
+      return check.type;
+  }
+}