minimal-agent 0.12.0 → 0.14.0

package/plugins/workflow-runner/src/util.js

@@ -0,0 +1,47 @@
+/**
+ * ============================================================
+ *  plugins/workflow-runner/src/util.ts —— 引擎内共用小件
+ * ------------------------------------------------------------
+ *  只放「多处要用、又不值得单开文件」的纯函数。有任何状态或 IO 的都不该进这里。
+ * ============================================================
+ */
+import { resolve, sep } from 'node:path';
+/** 截断到 n 个字符，超出补省略号。 */
+export function truncate(s, n) {
+    return s.length > n ? `${s.slice(0, n)}…` : s;
+}
+/**
+ * 把一个声明产物路径收敛成「相对 workingDir 的安全相对路径」；越界返回 null。
+ *
+ * 自 legacy `types.ts` 原样移植，两处判据都是踩出来的，改之前先读：
+ *
+ *  ① **前缀匹配必须带路径分隔符边界**。裸 `startsWith(base)` 会让 `/repo` 匹配上
+ *    `/repo-hack/evil` —— 一个只差几个字符的兄弟目录就能骗过越界检查。
+ *
+ *  ② **Windows 上比较前要统一大小写**。NTFS 不区分大小写，`D:\Code` 与 `D:\code`
+ *    是同一个目录，逐字节比较会把合法路径判成越界。（相关教训见记忆
+ *    `project_windows_path_separator_gotcha`：同一类判据写死 `/` 分隔符时，
+ *    Windows 上条件恒为 false，缓存清理曾因此静默失效。）
+ */
+export function safeArtifactPath(workingDir, rawPath) {
+    if (!rawPath || typeof rawPath !== 'string')
+        return null;
+    const base = resolve(workingDir);
+    const baseWithSep = base.endsWith(sep) ? base : base + sep;
+    let abs;
+    try {
+        abs = resolve(workingDir, rawPath);
+    }
+    catch {
+        return null;
+    }
+    const sameCase = (p) => process.platform === 'win32' ? p.toLowerCase() : p;
+    const nAbs = sameCase(abs);
+    const nBase = sameCase(base);
+    const nBaseSep = sameCase(baseWithSep);
+    // 恰好等于 base 本身（rawPath='.' 这种极端情形）也算合法。
+    if (nAbs !== nBase && !nAbs.startsWith(nBaseSep))
+        return null;
+    const rel = abs.slice(base.length).replace(/^[/\\]/, '');
+    return rel.length === 0 ? '.' : rel;
+}

package/plugins/workflow-runner/src/util.ts

@@ -0,0 +1,51 @@
+/**
+ * ============================================================
+ *  plugins/workflow-runner/src/util.ts —— 引擎内共用小件
+ * ------------------------------------------------------------
+ *  只放「多处要用、又不值得单开文件」的纯函数。有任何状态或 IO 的都不该进这里。
+ * ============================================================
+ */
+
+import { resolve, sep } from 'node:path';
+
+/** 截断到 n 个字符，超出补省略号。 */
+export function truncate(s: string, n: number): string {
+  return s.length > n ? `${s.slice(0, n)}…` : s;
+}
+
+/**
+ * 把一个声明产物路径收敛成「相对 workingDir 的安全相对路径」；越界返回 null。
+ *
+ * 自 legacy `types.ts` 原样移植，两处判据都是踩出来的，改之前先读：
+ *
+ *  ① **前缀匹配必须带路径分隔符边界**。裸 `startsWith(base)` 会让 `/repo` 匹配上
+ *    `/repo-hack/evil` —— 一个只差几个字符的兄弟目录就能骗过越界检查。
+ *
+ *  ② **Windows 上比较前要统一大小写**。NTFS 不区分大小写，`D:\Code` 与 `D:\code`
+ *    是同一个目录，逐字节比较会把合法路径判成越界。（相关教训见记忆
+ *    `project_windows_path_separator_gotcha`：同一类判据写死 `/` 分隔符时，
+ *    Windows 上条件恒为 false，缓存清理曾因此静默失效。）
+ */
+export function safeArtifactPath(
+  workingDir: string,
+  rawPath: string,
+): string | null {
+  if (!rawPath || typeof rawPath !== 'string') return null;
+  const base = resolve(workingDir);
+  const baseWithSep = base.endsWith(sep) ? base : base + sep;
+  let abs: string;
+  try {
+    abs = resolve(workingDir, rawPath);
+  } catch {
+    return null;
+  }
+  const sameCase = (p: string): string =>
+    process.platform === 'win32' ? p.toLowerCase() : p;
+  const nAbs = sameCase(abs);
+  const nBase = sameCase(base);
+  const nBaseSep = sameCase(baseWithSep);
+  // 恰好等于 base 本身（rawPath='.' 这种极端情形）也算合法。
+  if (nAbs !== nBase && !nAbs.startsWith(nBaseSep)) return null;
+  const rel = abs.slice(base.length).replace(/^[/\\]/, '');
+  return rel.length === 0 ? '.' : rel;
+}

package/plugins/workflow-runner/src/workflowContext.js

@@ -0,0 +1,20 @@
+import capabilities from './workflowContextCapabilities.json' with { type: 'json' };
+export const WORKFLOW_CONTEXT_CAPABILITIES = capabilities;
+export function assertWorkflowContextShape(value) {
+    const context = value;
+    for (const [group, names] of Object.entries(WORKFLOW_CONTEXT_CAPABILITIES)) {
+        const actual = context[group];
+        if (!actual || typeof actual !== 'object') {
+            throw new Error(`WorkflowContext 缺少能力组 wf.${group}`);
+        }
+        const keys = Object.keys(actual).sort();
+        const expected = [...names].sort();
+        const missing = expected.filter((name) => !keys.includes(name));
+        const extra = keys.filter((name) => !expected.includes(name));
+        if (missing.length || extra.length) {
+            throw new Error(`WorkflowContext wf.${group} 与能力注册表不同步` +
+                `${missing.length ? `；缺少 ${missing.join(', ')}` : ''}` +
+                `${extra.length ? `；多出 ${extra.join(', ')}` : ''}`);
+        }
+    }
+}

package/plugins/workflow-runner/src/workflowContext.ts

@@ -0,0 +1,58 @@
+import capabilities from './workflowContextCapabilities.json' with { type: 'json' };
+
+export const WORKFLOW_CONTEXT_CAPABILITIES = capabilities as Readonly<
+  Record<string, readonly string[]>
+>;
+
+export interface WorkflowPipelineSuccess<T = unknown> {
+  ok: true;
+  index: number;
+  value: T;
+}
+
+export interface WorkflowPipelineFailure {
+  ok: false;
+  index: number;
+  error: { name: string; message: string; code?: string };
+}
+
+export interface WorkflowPipelineResult<T = unknown> {
+  results: (WorkflowPipelineSuccess<T> | WorkflowPipelineFailure)[];
+  succeeded: number;
+  failed: number;
+}
+
+/** Public V2 contract. Function signatures remain structural so the registry is the key truth. */
+export interface WorkflowContext {
+  input: { values: Record<string, unknown>; resources: Record<string, unknown> };
+  runtime: Record<string, unknown>;
+  model: Record<string, (...args: any[]) => any>;
+  tools: Record<string, (...args: any[]) => any>;
+  exec: Record<string, (...args: any[]) => any>;
+  fs: Record<string, (...args: any[]) => any>;
+  flow: Record<string, (...args: any[]) => any>;
+  check: Record<string, (...args: any[]) => any>;
+  state: Record<string, (...args: any[]) => any>;
+  output: Record<string, (...args: any[]) => any>;
+}
+
+export function assertWorkflowContextShape(value: object): void {
+  const context = value as Record<string, unknown>;
+  for (const [group, names] of Object.entries(WORKFLOW_CONTEXT_CAPABILITIES)) {
+    const actual = context[group];
+    if (!actual || typeof actual !== 'object') {
+      throw new Error(`WorkflowContext 缺少能力组 wf.${group}`);
+    }
+    const keys = Object.keys(actual).sort();
+    const expected = [...names].sort();
+    const missing = expected.filter((name) => !keys.includes(name));
+    const extra = keys.filter((name) => !expected.includes(name));
+    if (missing.length || extra.length) {
+      throw new Error(
+        `WorkflowContext wf.${group} 与能力注册表不同步` +
+          `${missing.length ? `；缺少 ${missing.join(', ')}` : ''}` +
+          `${extra.length ? `；多出 ${extra.join(', ')}` : ''}`,
+      );
+    }
+  }
+}

package/plugins/workflow-runner/src/workflowDependencies.js

@@ -0,0 +1,36 @@
+import { discoverWorkflows } from './discovery.js';
+import { fingerprint } from './journal.js';
+import { workflowFingerprint } from './workflowFingerprint.js';
+/** Resolve once per root execution using the same override precedence as /workflow. */
+export async function resolveWorkflowBundle(root, cwd) {
+    const discovered = root.meta.dependencies?.length
+        ? await discoverWorkflows(cwd)
+        : { workflows: [], failures: [] };
+    const scripts = new Map(discovered.workflows.map((s) => [s.name, s]));
+    scripts.set(root.name, root);
+    async function visit(script, ancestors) {
+        if (ancestors.includes(script.name))
+            throw new Error(`工作流依赖环：${[...ancestors, script.name].join(' → ')}`);
+        if (ancestors.length >= 8)
+            throw new Error('子工作流嵌套超过8层');
+        if (ancestors.length && script.meta.managedRuntime)
+            throw new Error(`不能把 managedRuntime 工作流 ${script.name} 作为子流程调用`);
+        const children = new Map();
+        for (const name of script.meta.dependencies ?? []) {
+            const child = scripts.get(name);
+            if (!child)
+                throw new Error(`依赖工作流 ${name} 不可用：${discovered.failures.find((f) => f.name === name)?.errors.join('; ') ?? '未找到'}`);
+            children.set(name, await visit(child, [...ancestors, script.name]));
+        }
+        const own = await workflowFingerprint(script.source, script.dir, script.meta.packages ?? []);
+        // Keep legacy leaf fingerprints, avoiding unrelated invalidations.
+        const hash = children.size
+            ? fingerprint('workflow-tree-v1', {
+                own,
+                children: [...children].map(([name, b]) => [name, b.hash]),
+            })
+            : own;
+        return { script, hash, children };
+    }
+    return visit(root, []);
+}

package/plugins/workflow-runner/src/workflowDependencies.ts

@@ -0,0 +1,59 @@
+import { discoverWorkflows } from './discovery.js';
+import { fingerprint } from './journal.js';
+import type { WorkflowScript } from './types.js';
+import { workflowFingerprint } from './workflowFingerprint.js';
+
+export interface WorkflowBundle {
+  script: WorkflowScript;
+  hash: string;
+  children: Map<string, WorkflowBundle>;
+}
+
+/** Resolve once per root execution using the same override precedence as /workflow. */
+export async function resolveWorkflowBundle(
+  root: WorkflowScript,
+  cwd: string,
+): Promise<WorkflowBundle> {
+  const discovered = root.meta.dependencies?.length
+    ? await discoverWorkflows(cwd)
+    : { workflows: [], failures: [] };
+  const scripts = new Map(discovered.workflows.map((s) => [s.name, s]));
+  scripts.set(root.name, root);
+  async function visit(
+    script: WorkflowScript,
+    ancestors: string[],
+  ): Promise<WorkflowBundle> {
+    if (ancestors.includes(script.name))
+      throw new Error(
+        `工作流依赖环：${[...ancestors, script.name].join(' → ')}`,
+      );
+    if (ancestors.length >= 8) throw new Error('子工作流嵌套超过8层');
+    if (ancestors.length && script.meta.managedRuntime)
+      throw new Error(
+        `不能把 managedRuntime 工作流 ${script.name} 作为子流程调用`,
+      );
+    const children = new Map<string, WorkflowBundle>();
+    for (const name of script.meta.dependencies ?? []) {
+      const child = scripts.get(name);
+      if (!child)
+        throw new Error(
+          `依赖工作流 ${name} 不可用：${discovered.failures.find((f) => f.name === name)?.errors.join('; ') ?? '未找到'}`,
+        );
+      children.set(name, await visit(child, [...ancestors, script.name]));
+    }
+    const own = await workflowFingerprint(
+      script.source,
+      script.dir,
+      script.meta.packages ?? [],
+    );
+    // Keep legacy leaf fingerprints, avoiding unrelated invalidations.
+    const hash = children.size
+      ? fingerprint('workflow-tree-v1', {
+          own,
+          children: [...children].map(([name, b]) => [name, b.hash]),
+        })
+      : own;
+    return { script, hash, children };
+  }
+  return visit(root, []);
+}

package/plugins/workflow-runner/src/workflowFingerprint.js

@@ -0,0 +1,118 @@
+import { createHash } from 'node:crypto';
+import { createRequire } from 'node:module';
+import { readFile, readdir, lstat } from 'node:fs/promises';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import { pathContains } from '../../../src/plugin-sdk.js';
+import { moduleImports, packageName, resolveRelativeModule } from './moduleResolution.js';
+/**
+ * 宿主引擎自身的 npm 包名（`package.json::name`）。硬编码、人工同步，**不**在
+ * 这里动态读 `package.json`：这个文件会被绿色版 `bun --compile` 编译进单文件
+ * exe，届时 `import.meta.url` 变成虚拟路径——用相对路径去定位磁盘上的
+ * `package.json` 会复现 CLAUDE.md 反复警告过的那类绿色版地雷。改包名时要与
+ * `scriptGuard.mjs::HOST_PACKAGE_NAME` 一起改。
+ */
+const HOST_PACKAGE_NAME = 'minimal-agent';
+async function packageVersion(entry, name) {
+    let cursor = dirname(entry);
+    for (;;) {
+        const manifest = join(cursor, 'package.json');
+        try {
+            const value = JSON.parse(await readFile(manifest, 'utf8'));
+            if (value.name === name && value.version)
+                return value.version;
+        }
+        catch {
+            // continue upwards
+        }
+        const parent = dirname(cursor);
+        if (parent === cursor)
+            break;
+        cursor = parent;
+    }
+    return 'unknown';
+}
+/** Fingerprint executable ESM graph, prompts/assets, and declared package versions. */
+export async function workflowFingerprint(source, dir, packages = []) {
+    const hash = createHash('sha256').update('workflow-bundle-v2\0');
+    const entry = join(dir, 'workflow.mjs');
+    const seen = new Set();
+    const importedPackages = new Set();
+    async function addModule(path, knownSource) {
+        const absolute = resolve(path);
+        if (!pathContains(dir, absolute)) {
+            throw new Error(`工作流相对模块越出工作流目录：${absolute}`);
+        }
+        if (seen.has(absolute))
+            return;
+        seen.add(absolute);
+        const text = knownSource ?? (await readFile(absolute, 'utf8'));
+        const name = relative(dir, absolute).split(sep).join('/');
+        hash.update(JSON.stringify(['module', name, Buffer.byteLength(text)])).update(text);
+        for (const specifier of moduleImports(text)) {
+            if (specifier.startsWith('.')) {
+                await addModule(await resolveRelativeModule(absolute, specifier));
+            }
+            else if (specifier.startsWith('node:')) {
+                continue;
+            }
+            else if (specifier.startsWith('/') || specifier.startsWith('file:')) {
+                throw new Error(`工作流 ESM import 不得使用绝对路径：${specifier}`);
+            }
+            else if (packageName(specifier) === HOST_PACKAGE_NAME) {
+                // 第二道闸，对齐 scriptGuard.mjs 的同名检查：包自引用 +
+                // package.json::exports 的 "./src/*"/"./plugins/*" 通配符会让
+                // `minimal-agent/src/xxx` 解析到真实内核文件，完全绕开 wf 分组能力
+                // 对象。声明进 meta.packages 也无法绕过这条——即使调用顺序以后变了、
+                // discovery.ts 没能先跑 scriptGuard 校验，这里仍然拦得住。
+                throw new Error(`工作流禁止 import 宿主引擎自身（${specifier}）：一切对内核的访问必须经 wf 分组能力对象。`);
+            }
+            else {
+                importedPackages.add(packageName(specifier));
+            }
+        }
+    }
+    await addModule(entry, source);
+    async function visit(relativeDir) {
+        let entries;
+        try {
+            if ((await lstat(join(dir, relativeDir))).isSymbolicLink())
+                throw new Error(`工作流随包资源不能是符号链接：${relativeDir}`);
+            entries = await readdir(join(dir, relativeDir), { withFileTypes: true });
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return;
+            throw error;
+        }
+        for (const item of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+            const name = `${relativeDir}/${item.name}`;
+            if (item.isSymbolicLink())
+                throw new Error(`工作流随包资源不能是符号链接：${name}`);
+            if (item.isDirectory())
+                await visit(name);
+            else if (item.isFile() && !seen.has(resolve(dir, name))) {
+                const bytes = await readFile(join(dir, name));
+                hash.update(JSON.stringify(['resource', name, bytes.length])).update(bytes);
+            }
+        }
+    }
+    for (const folder of ['prompts', 'scripts', 'assets'])
+        await visit(folder);
+    const require = createRequire(entry);
+    for (const name of importedPackages) {
+        if (!packages.includes(name)) {
+            throw new Error(`运行时包 ${name} 必须声明在 meta.packages 中。`);
+        }
+    }
+    for (const name of [...packages].sort()) {
+        let resolved;
+        try {
+            resolved = require.resolve(name);
+        }
+        catch (error) {
+            throw new Error(`无法解析 meta.packages 中的 ${name}：${error instanceof Error ? error.message : String(error)}`);
+        }
+        hash.update(JSON.stringify(['package', name, await packageVersion(resolved, name)]));
+    }
+    return hash.digest('hex').slice(0, 16);
+}

package/plugins/workflow-runner/src/workflowFingerprint.ts

@@ -0,0 +1,122 @@
+import { createHash } from 'node:crypto';
+import { createRequire } from 'node:module';
+import { readFile, readdir, lstat } from 'node:fs/promises';
+import type { Dirent } from 'node:fs';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+
+import { pathContains } from '../../../src/plugin-sdk.js';
+import { moduleImports, packageName, resolveRelativeModule } from './moduleResolution.js';
+
+/**
+ * 宿主引擎自身的 npm 包名（`package.json::name`）。硬编码、人工同步，**不**在
+ * 这里动态读 `package.json`：这个文件会被绿色版 `bun --compile` 编译进单文件
+ * exe，届时 `import.meta.url` 变成虚拟路径——用相对路径去定位磁盘上的
+ * `package.json` 会复现 CLAUDE.md 反复警告过的那类绿色版地雷。改包名时要与
+ * `scriptGuard.mjs::HOST_PACKAGE_NAME` 一起改。
+ */
+const HOST_PACKAGE_NAME = 'minimal-agent';
+
+async function packageVersion(entry: string, name: string): Promise<string> {
+  let cursor = dirname(entry);
+  for (;;) {
+    const manifest = join(cursor, 'package.json');
+    try {
+      const value = JSON.parse(await readFile(manifest, 'utf8')) as {
+        name?: string;
+        version?: string;
+      };
+      if (value.name === name && value.version) return value.version;
+    } catch {
+      // continue upwards
+    }
+    const parent = dirname(cursor);
+    if (parent === cursor) break;
+    cursor = parent;
+  }
+  return 'unknown';
+}
+
+/** Fingerprint executable ESM graph, prompts/assets, and declared package versions. */
+export async function workflowFingerprint(
+  source: string,
+  dir: string,
+  packages: string[] = [],
+): Promise<string> {
+  const hash = createHash('sha256').update('workflow-bundle-v2\0');
+  const entry = join(dir, 'workflow.mjs');
+  const seen = new Set<string>();
+  const importedPackages = new Set<string>();
+
+  async function addModule(path: string, knownSource?: string): Promise<void> {
+    const absolute = resolve(path);
+    if (!pathContains(dir, absolute)) {
+      throw new Error(`工作流相对模块越出工作流目录：${absolute}`);
+    }
+    if (seen.has(absolute)) return;
+    seen.add(absolute);
+    const text = knownSource ?? (await readFile(absolute, 'utf8'));
+    const name = relative(dir, absolute).split(sep).join('/');
+    hash.update(JSON.stringify(['module', name, Buffer.byteLength(text)])).update(text);
+    for (const specifier of moduleImports(text)) {
+      if (specifier.startsWith('.')) {
+        await addModule(await resolveRelativeModule(absolute, specifier));
+      } else if (specifier.startsWith('node:')) {
+        continue;
+      } else if (specifier.startsWith('/') || specifier.startsWith('file:')) {
+        throw new Error(`工作流 ESM import 不得使用绝对路径：${specifier}`);
+      } else if (packageName(specifier) === HOST_PACKAGE_NAME) {
+        // 第二道闸，对齐 scriptGuard.mjs 的同名检查：包自引用 +
+        // package.json::exports 的 "./src/*"/"./plugins/*" 通配符会让
+        // `minimal-agent/src/xxx` 解析到真实内核文件，完全绕开 wf 分组能力
+        // 对象。声明进 meta.packages 也无法绕过这条——即使调用顺序以后变了、
+        // discovery.ts 没能先跑 scriptGuard 校验，这里仍然拦得住。
+        throw new Error(
+          `工作流禁止 import 宿主引擎自身（${specifier}）：一切对内核的访问必须经 wf 分组能力对象。`,
+        );
+      } else {
+        importedPackages.add(packageName(specifier));
+      }
+    }
+  }
+
+  await addModule(entry, source);
+
+  async function visit(relativeDir: string): Promise<void> {
+    let entries: Dirent[];
+    try {
+      if ((await lstat(join(dir, relativeDir))).isSymbolicLink())
+        throw new Error(`工作流随包资源不能是符号链接：${relativeDir}`);
+      entries = await readdir(join(dir, relativeDir), { withFileTypes: true });
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return;
+      throw error;
+    }
+    for (const item of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+      const name = `${relativeDir}/${item.name}`;
+      if (item.isSymbolicLink()) throw new Error(`工作流随包资源不能是符号链接：${name}`);
+      if (item.isDirectory()) await visit(name);
+      else if (item.isFile() && !seen.has(resolve(dir, name))) {
+        const bytes = await readFile(join(dir, name));
+        hash.update(JSON.stringify(['resource', name, bytes.length])).update(bytes);
+      }
+    }
+  }
+  for (const folder of ['prompts', 'scripts', 'assets']) await visit(folder);
+
+  const require = createRequire(entry);
+  for (const name of importedPackages) {
+    if (!packages.includes(name)) {
+      throw new Error(`运行时包 ${name} 必须声明在 meta.packages 中。`);
+    }
+  }
+  for (const name of [...packages].sort()) {
+    let resolved: string;
+    try {
+      resolved = require.resolve(name);
+    } catch (error) {
+      throw new Error(`无法解析 meta.packages 中的 ${name}：${error instanceof Error ? error.message : String(error)}`);
+    }
+    hash.update(JSON.stringify(['package', name, await packageVersion(resolved, name)]));
+  }
+  return hash.digest('hex').slice(0, 16);
+}