@armadra/agent 0.0.0-stage → 0.2.1

package/dist/codemode/modes.d.ts

@@ -0,0 +1,23 @@
+/**
+ * codemode 三种模式（设计 §5.5 模式表、§5.6；实施计划 §9 修正）。[B10]
+ *
+ * | 模式   | 模型看到的工具                                                             |
+ * | ------ | -------------------------------------------------------------------------- |
+ * | `off`  | 不注册 codemode（工厂返回 undefined）                                       |
+ * | `on`   | 预设的工具 + codemode；其它工具描述末尾加一行「也可在 codemode 脚本里调用」 |
+ * | `only` | 只有 codemode（宿主 / SDK 工具也不直接暴露）；其它工具的声明列在它的描述里 |
+ *
+ * 活动集由 B6 的 `resolvePreset` 决定（`only` → `["codemode"]`）；这里补两件事：`on` 模式下的描述
+ * 追加（在注册前包一层，描述在会话开始时就确定、字节稳定）与 `only` 模式的独占活动集
+ * （`PresetToolRegistry.setPresetTools(names, { exclusive: true })`）。
+ */
+import type { CodemodeMode } from "../config/types.js";
+import { type PresetResolution, type PresetToolRegistry } from "../tools/presets.js";
+import type { ToolDefinition } from "../tools/types.js";
+export declare function codemodeHint(name: string): string;
+/** 复制工具（保留 getter 与方法），描述末尾追加一行 codemode 提示。 */
+export declare function withCodemodeHint<I>(tool: ToolDefinition<I>): ToolDefinition<I>;
+/** 注册前的包装：`on` 模式给 codemode 以外的工具加提示，其它模式原样返回。 */
+export declare function decorateForMode(mode: CodemodeMode): <I>(tool: ToolDefinition<I>) => ToolDefinition<I>;
+/** 把预设结果落到注册表：`only` 时活动集独占（宿主 / SDK 工具也只能在脚本里调用）。 */
+export declare function applyCodemodeMode(registry: PresetToolRegistry, resolution: Pick<PresetResolution, "builtin" | "codemode">): void;

package/dist/codemode/modes.js

@@ -0,0 +1,40 @@
+/**
+ * codemode 三种模式（设计 §5.5 模式表、§5.6；实施计划 §9 修正）。[B10]
+ *
+ * | 模式   | 模型看到的工具                                                             |
+ * | ------ | -------------------------------------------------------------------------- |
+ * | `off`  | 不注册 codemode（工厂返回 undefined）                                       |
+ * | `on`   | 预设的工具 + codemode；其它工具描述末尾加一行「也可在 codemode 脚本里调用」 |
+ * | `only` | 只有 codemode（宿主 / SDK 工具也不直接暴露）；其它工具的声明列在它的描述里 |
+ *
+ * 活动集由 B6 的 `resolvePreset` 决定（`only` → `["codemode"]`）；这里补两件事：`on` 模式下的描述
+ * 追加（在注册前包一层，描述在会话开始时就确定、字节稳定）与 `only` 模式的独占活动集
+ * （`PresetToolRegistry.setPresetTools(names, { exclusive: true })`）。
+ */
+import { CODEMODE_TOOL } from "../tools/presets.js";
+export function codemodeHint(name) {
+    return `Also callable inside codemode scripts as tools.${name}(args).`;
+}
+/** 复制工具（保留 getter 与方法），描述末尾追加一行 codemode 提示。 */
+export function withCodemodeHint(tool) {
+    const copy = Object.create(Object.getPrototypeOf(tool), {
+        ...Object.getOwnPropertyDescriptors(tool),
+    });
+    Object.defineProperty(copy, "description", {
+        value: `${tool.description}\n${codemodeHint(tool.name)}`,
+        enumerable: true,
+        writable: false,
+        configurable: true,
+    });
+    return copy;
+}
+/** 注册前的包装：`on` 模式给 codemode 以外的工具加提示，其它模式原样返回。 */
+export function decorateForMode(mode) {
+    if (mode !== "on")
+        return (tool) => tool;
+    return (tool) => (tool.name === CODEMODE_TOOL ? tool : withCodemodeHint(tool));
+}
+/** 把预设结果落到注册表：`only` 时活动集独占（宿主 / SDK 工具也只能在脚本里调用）。 */
+export function applyCodemodeMode(registry, resolution) {
+    registry.setPresetTools(resolution.builtin, { exclusive: resolution.codemode === "only" });
+}

package/dist/codemode/protocol.d.ts

@@ -0,0 +1,91 @@
+/**
+ * codemode 父子进程的 JSON 行协议（设计 §5.5、实施计划 §5.1）。[B10]
+ *
+ * 父 → 子（子进程 stdin，一行一个 JSON）：
+ * - `run`：脚本、选项、可调用工具的声明、当前 store 快照；每个子进程只收一次；
+ * - `tool_result`：对某次 `tool_call` 的应答（`ok` 时带 `value`，否则带 `error` 文本）；
+ * - `abort`：父进程要求结束（子进程拒绝所有未完成调用并以失败结束）。
+ *
+ * 子 → 父（子进程 stdout）：
+ * - `tool_call`：脚本里的 `tools.<name>(input)`；
+ * - `output`：`text()` / `console.log()` / `return` 产出的一段输出；
+ * - `store`：脚本成功结束且写过 store 时的完整快照，父进程只在 `done.ok` 时提交；
+ * - `done`：脚本结束（成功或失败），带用时。
+ *
+ * 本文件只有纯函数与类型；子进程入口（sandbox-entry.ts）不 import 它的运行时代码（子进程只被
+ * 允许读自己的入口文件），只 import 类型。
+ */
+/** 脚本首行 `// @options: {...}` 可设的选项。 */
+export interface ScriptOptions {
+    /** 输出上限（估算 token，字符 / 4）；超出保留首尾，全文落盘。缺省 10 000。 */
+    maxOutputTokens: number;
+    /** 整个脚本的硬期限（毫秒）；到时父进程杀掉子进程树。缺省 300 000。 */
+    timeoutMs: number;
+}
+export declare const DEFAULT_MAX_OUTPUT_TOKENS = 10000;
+export declare const DEFAULT_SCRIPT_TIMEOUT_MS = 300000;
+export declare const MAX_SCRIPT_TIMEOUT_MS = 3600000;
+/** 父进程启动子进程时附加的参数（sandbox-entry.ts 见到它才启动）。 */
+export declare const SANDBOX_MAIN_FLAG = "--ama-codemode-sandbox";
+/** 同一脚本内并发工具调用上限。 */
+export declare const MAX_CONCURRENT_TOOL_CALLS = 8;
+export declare const DEFAULT_SCRIPT_OPTIONS: Readonly<ScriptOptions>;
+/** 传给子进程的工具声明：名字 + TypeScript 声明（describeTool 返回它）。 */
+export interface ToolDecl {
+    name: string;
+    declaration: string;
+}
+export type StoreSnapshot = Record<string, unknown>;
+export type ParentMessage = {
+    type: "run";
+    script: string;
+    options: ScriptOptions;
+    tools: ToolDecl[];
+    store: StoreSnapshot;
+} | {
+    type: "tool_result";
+    id: number;
+    ok: true;
+    value: unknown;
+} | {
+    type: "tool_result";
+    id: number;
+    ok: false;
+    error: string;
+} | {
+    type: "abort";
+};
+export type ChildMessage = {
+    type: "tool_call";
+    id: number;
+    name: string;
+    input: unknown;
+} | {
+    type: "output";
+    text: string;
+}
+/** 脚本成功结束且写过 store 时发：结束时的完整快照（父进程整体替换）。 */
+ | {
+    type: "store";
+    entries: Record<string, unknown>;
+} | {
+    type: "done";
+    ok: boolean;
+    error?: string;
+    elapsedMs: number;
+};
+/**
+ * 解析脚本首行的 `// @options: {...}`。没有选项行 → 缺省值；JSON 非法、键未知或取值越界 →
+ * AmaError{code:"invalid_arguments"}（模型能从报错里改正）。
+ */
+export declare function parseOptionsLine(script: string): ScriptOptions;
+/** 编码一行（含结尾 \n）；U+2028 / U+2029 转义，保证按 \n 切行安全。 */
+export declare function encodeLine(message: ParentMessage | ChildMessage): string;
+export declare function decodeChildLine(line: string): ChildMessage;
+export declare function decodeParentLine(line: string): ParentMessage;
+/** 按 \n 切行的累加器（多字节 UTF-8 由调用方 setEncoding 处理）。 */
+export declare class LineSplitter {
+    private buffer;
+    push(chunk: string): string[];
+    flush(): string[];
+}

package/dist/codemode/protocol.js

@@ -0,0 +1,114 @@
+/**
+ * codemode 父子进程的 JSON 行协议（设计 §5.5、实施计划 §5.1）。[B10]
+ *
+ * 父 → 子（子进程 stdin，一行一个 JSON）：
+ * - `run`：脚本、选项、可调用工具的声明、当前 store 快照；每个子进程只收一次；
+ * - `tool_result`：对某次 `tool_call` 的应答（`ok` 时带 `value`，否则带 `error` 文本）；
+ * - `abort`：父进程要求结束（子进程拒绝所有未完成调用并以失败结束）。
+ *
+ * 子 → 父（子进程 stdout）：
+ * - `tool_call`：脚本里的 `tools.<name>(input)`；
+ * - `output`：`text()` / `console.log()` / `return` 产出的一段输出；
+ * - `store`：脚本成功结束且写过 store 时的完整快照，父进程只在 `done.ok` 时提交；
+ * - `done`：脚本结束（成功或失败），带用时。
+ *
+ * 本文件只有纯函数与类型；子进程入口（sandbox-entry.ts）不 import 它的运行时代码（子进程只被
+ * 允许读自己的入口文件），只 import 类型。
+ */
+import { AmaError } from "../errors.js";
+export const DEFAULT_MAX_OUTPUT_TOKENS = 10_000;
+export const DEFAULT_SCRIPT_TIMEOUT_MS = 300_000;
+export const MAX_SCRIPT_TIMEOUT_MS = 3_600_000;
+/** 父进程启动子进程时附加的参数（sandbox-entry.ts 见到它才启动）。 */
+export const SANDBOX_MAIN_FLAG = "--ama-codemode-sandbox";
+/** 同一脚本内并发工具调用上限。 */
+export const MAX_CONCURRENT_TOOL_CALLS = 8;
+export const DEFAULT_SCRIPT_OPTIONS = Object.freeze({
+    maxOutputTokens: DEFAULT_MAX_OUTPUT_TOKENS,
+    timeoutMs: DEFAULT_SCRIPT_TIMEOUT_MS,
+});
+const OPTIONS_RE = /^\s*\/\/\s*@options:\s*(.*)$/;
+/**
+ * 解析脚本首行的 `// @options: {...}`。没有选项行 → 缺省值；JSON 非法、键未知或取值越界 →
+ * AmaError{code:"invalid_arguments"}（模型能从报错里改正）。
+ */
+export function parseOptionsLine(script) {
+    const firstLine = script.split("\n", 1)[0] ?? "";
+    const match = OPTIONS_RE.exec(firstLine);
+    const options = { ...DEFAULT_SCRIPT_OPTIONS };
+    if (match === null)
+        return options;
+    let raw;
+    try {
+        raw = JSON.parse((match[1] ?? "").trim());
+    }
+    catch (error) {
+        throw new AmaError("invalid_arguments", `Invalid // @options line: ${error.message}`);
+    }
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        throw new AmaError("invalid_arguments", "Invalid // @options line: expected a JSON object");
+    }
+    for (const [key, value] of Object.entries(raw)) {
+        if (key === "max_output_tokens") {
+            options.maxOutputTokens = positiveInt(key, value, 1_000_000);
+        }
+        else if (key === "timeout_ms") {
+            options.timeoutMs = positiveInt(key, value, MAX_SCRIPT_TIMEOUT_MS);
+        }
+        else {
+            throw new AmaError("invalid_arguments", `Invalid // @options line: unknown option "${key}" (use max_output_tokens, timeout_ms)`);
+        }
+    }
+    return options;
+}
+function positiveInt(key, value, max) {
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 1 || value > max) {
+        throw new AmaError("invalid_arguments", `Invalid // @options line: ${key} must be an integer between 1 and ${max}`);
+    }
+    return value;
+}
+/** 编码一行（含结尾 \n）；U+2028 / U+2029 转义，保证按 \n 切行安全。 */
+export function encodeLine(message) {
+    return `${JSON.stringify(message)
+        .replace(/\u2028/g, "\\u2028")
+        .replace(/\u2029/g, "\\u2029")}\n`;
+}
+const CHILD_TYPES = new Set(["tool_call", "output", "store", "done"]);
+const PARENT_TYPES = new Set(["run", "tool_result", "abort"]);
+function decode(line, types) {
+    let value;
+    try {
+        value = JSON.parse(line);
+    }
+    catch (error) {
+        throw new AmaError("invalid_arguments", `codemode protocol: ${error.message}`);
+    }
+    if (typeof value !== "object" ||
+        value === null ||
+        typeof value.type !== "string" ||
+        !types.has(value.type)) {
+        throw new AmaError("invalid_arguments", "codemode protocol: unknown message");
+    }
+    return value;
+}
+export function decodeChildLine(line) {
+    return decode(line, CHILD_TYPES);
+}
+export function decodeParentLine(line) {
+    return decode(line, PARENT_TYPES);
+}
+/** 按 \n 切行的累加器（多字节 UTF-8 由调用方 setEncoding 处理）。 */
+export class LineSplitter {
+    buffer = "";
+    push(chunk) {
+        this.buffer += chunk;
+        const lines = this.buffer.split("\n");
+        this.buffer = lines.pop() ?? "";
+        return lines.filter((line) => line.trim() !== "");
+    }
+    flush() {
+        const rest = this.buffer;
+        this.buffer = "";
+        return rest.trim() === "" ? [] : [rest];
+    }
+}

package/dist/codemode/sandbox-entry.d.ts

@@ -0,0 +1,25 @@
+/**
+ * codemode 子进程入口（设计 §5.5 沙箱第 1–3 条；第二个 bundle 入口 dist/bundle/ama-sandbox.cjs）。[B10]
+ *
+ * 父进程以 `<node> --permission --allow-fs-read=<本文件> --disallow-code-generation-from-strings
+ * <本文件>`、空环境启动本文件。本文件**只能 import node: 内置模块与类型**：权限模型只允许读入口
+ * 文件本身，其它源文件读不到。
+ *
+ * - 用 `node:vm` 建一个只含 ECMAScript 内建对象的上下文（`codeGeneration: { strings: false,
+ *   wasm: false }`），没有 require / process / fetch / console / 定时器；
+ * - 注入 `tools`（Proxy：已知工具 → 调用，`codemode` → 拒绝，其它名字 → 拒绝并列出可用工具）、
+ *   `text / console.* / store / load / ALL_TOOLS / describeTool`；
+ * - 上下文里的函数都在上下文内定义（引导脚本），只经一个宿主函数 `host(kind, json)` 与本进程
+ *   交换 JSON 字符串；本进程主 realm 也禁止字符串生成代码，拿到宿主函数的 `constructor` 也无法
+ *   `Function("return process")`；
+ * - 脚本包成 `(async () => { ... })()`，`return v` 等同 `text(v)`；并发工具调用 ≤ 8（引导脚本
+ *   内的信号量）；结束（成功 / 失败 / abort）时拒绝未完成调用，发 `store`（仅成功）与 `done` 后退出。
+ *
+ * 行协议见 protocol.ts（这里只 import 类型）。
+ */
+/** 与 protocol.ts 的 MAX_CONCURRENT_TOOL_CALLS、store.ts 的上限一致（本文件不能 import 运行时代码）。 */
+export declare const MAX_CONCURRENT = 8;
+export declare const MAX_STORE_VALUE_CHARS = 262144;
+export declare const MAX_STORE_TOTAL_CHARS = 1048576;
+/** 错误 → 一行说明；带上脚本里的行号（若能从栈里找到）。 */
+export declare function describeError(error: unknown): string;

package/dist/codemode/sandbox-entry.js

@@ -0,0 +1,323 @@
+/**
+ * codemode 子进程入口（设计 §5.5 沙箱第 1–3 条；第二个 bundle 入口 dist/bundle/ama-sandbox.cjs）。[B10]
+ *
+ * 父进程以 `<node> --permission --allow-fs-read=<本文件> --disallow-code-generation-from-strings
+ * <本文件>`、空环境启动本文件。本文件**只能 import node: 内置模块与类型**：权限模型只允许读入口
+ * 文件本身，其它源文件读不到。
+ *
+ * - 用 `node:vm` 建一个只含 ECMAScript 内建对象的上下文（`codeGeneration: { strings: false,
+ *   wasm: false }`），没有 require / process / fetch / console / 定时器；
+ * - 注入 `tools`（Proxy：已知工具 → 调用，`codemode` → 拒绝，其它名字 → 拒绝并列出可用工具）、
+ *   `text / console.* / store / load / ALL_TOOLS / describeTool`；
+ * - 上下文里的函数都在上下文内定义（引导脚本），只经一个宿主函数 `host(kind, json)` 与本进程
+ *   交换 JSON 字符串；本进程主 realm 也禁止字符串生成代码，拿到宿主函数的 `constructor` 也无法
+ *   `Function("return process")`；
+ * - 脚本包成 `(async () => { ... })()`，`return v` 等同 `text(v)`；并发工具调用 ≤ 8（引导脚本
+ *   内的信号量）；结束（成功 / 失败 / abort）时拒绝未完成调用，发 `store`（仅成功）与 `done` 后退出。
+ *
+ * 行协议见 protocol.ts（这里只 import 类型）。
+ */
+import { Script, createContext } from "node:vm";
+/** 与 protocol.ts 的 MAX_CONCURRENT_TOOL_CALLS、store.ts 的上限一致（本文件不能 import 运行时代码）。 */
+export const MAX_CONCURRENT = 8;
+export const MAX_STORE_VALUE_CHARS = 262_144;
+export const MAX_STORE_TOTAL_CHARS = 1_048_576;
+const SCRIPT_FILENAME = "codemode-script.js";
+/** 在 vm 上下文里执行的引导脚本：返回 `{ deliver, finish, run }`，全部是上下文 realm 的函数。 */
+const BOOTSTRAP = String.raw `(function (host, config) {
+  "use strict";
+  const MAX = config.maxConcurrent;
+  const stringify = JSON.stringify;
+  const parse = JSON.parse;
+  const pending = new Map();
+  const waiting = [];
+  let nextId = 0;
+  let active = 0;
+  let closed = false;
+  const decls = parse(config.tools);
+  const declByName = new Map();
+  const callName = new Map();
+  for (const decl of decls) {
+    declByName.set(decl.name, decl.declaration);
+    callName.set(decl.name.replace(/[^A-Za-z0-9_$]/g, "_"), decl.name);
+  }
+  const names = Object.freeze(decls.map((d) => d.name));
+
+  function format(value) {
+    if (typeof value === "string") return value;
+    if (value === undefined) return "undefined";
+    if (value instanceof Error) return value.name + ": " + value.message;
+    try {
+      const json = stringify(value, null, 2);
+      return json === undefined ? String(value) : json;
+    } catch (error) {
+      return String(value);
+    }
+  }
+  function text(...values) {
+    host("output", values.map(format).join(" "));
+  }
+
+  function callTool(name, input) {
+    if (closed) return Promise.reject(new Error("The script has already finished"));
+    let payload;
+    try {
+      payload = stringify({ name: name, input: input === undefined ? {} : input });
+    } catch (error) {
+      return Promise.reject(new Error("tools." + name + ": arguments must be JSON-serializable"));
+    }
+    return new Promise((resolve, reject) => {
+      const start = () => {
+        if (closed) return reject(new Error("The script has already finished"));
+        const id = ++nextId;
+        active++;
+        pending.set(id, { resolve: resolve, reject: reject });
+        host("tool_call", stringify(id) + "\n" + payload);
+      };
+      if (active < MAX) start();
+      else waiting.push(start);
+    });
+  }
+
+  function deliver(id, ok, json) {
+    const entry = pending.get(id);
+    if (entry === undefined) return;
+    pending.delete(id);
+    active--;
+    const next = waiting.shift();
+    if (next !== undefined) next();
+    if (ok) entry.resolve(json === undefined ? undefined : parse(json));
+    else entry.reject(new Error(json));
+  }
+
+  const toolsTarget = Object.create(null);
+  const tools = new Proxy(toolsTarget, {
+    get(target, prop) {
+      if (typeof prop !== "string" || prop === "then") return undefined;
+      const real = callName.get(prop);
+      if (real !== undefined) return (args) => callTool(real, args);
+      if (prop === "codemode") {
+        return () => Promise.reject(new Error("codemode cannot be called from a codemode script"));
+      }
+      return () =>
+        Promise.reject(new Error("Unknown tool " + prop + ". Callable tools: " + names.join(", ")));
+    },
+    has(target, prop) {
+      return typeof prop === "string" && callName.has(prop);
+    },
+    ownKeys() {
+      return [...callName.keys()];
+    },
+    getOwnPropertyDescriptor(target, prop) {
+      if (typeof prop !== "string" || !callName.has(prop)) return undefined;
+      return { configurable: true, enumerable: true, writable: false, value: tools[prop] };
+    },
+    set() {
+      return false;
+    },
+    defineProperty() {
+      return false;
+    },
+    deleteProperty() {
+      return false;
+    },
+  });
+
+  const storeMap = new Map(Object.entries(parse(config.store)).map(([k, v]) => [k, stringify(v)]));
+  let storeChanged = false;
+  function store(key, value) {
+    if (typeof key !== "string" || key === "") throw new TypeError("store(key, value): key must be a non-empty string");
+    if (value === undefined) {
+      storeChanged = storeMap.delete(key) || storeChanged;
+      return;
+    }
+    let json;
+    try {
+      json = stringify(value);
+    } catch (error) {
+      throw new TypeError("store(" + stringify(key) + "): value must be JSON-serializable");
+    }
+    if (json === undefined) throw new TypeError("store(" + stringify(key) + "): value must be JSON-serializable");
+    if (json.length > config.maxValueChars) {
+      throw new RangeError("store(" + stringify(key) + "): value is " + json.length + " characters of JSON (limit " + config.maxValueChars + ")");
+    }
+    let total = json.length;
+    for (const [k, v] of storeMap) if (k !== key) total += v.length;
+    if (total > config.maxTotalChars) {
+      throw new RangeError("store(" + stringify(key) + "): store would hold " + total + " characters of JSON (limit " + config.maxTotalChars + ")");
+    }
+    storeMap.set(key, json);
+    storeChanged = true;
+  }
+  function load(key) {
+    const json = storeMap.get(key);
+    return json === undefined ? undefined : parse(json);
+  }
+  function describeTool(name) {
+    return declByName.get(callName.get(name) ?? name);
+  }
+
+  const consoleObject = Object.freeze({
+    log: text, info: text, warn: text, error: text, debug: text,
+  });
+  const globals = {
+    tools: tools,
+    text: (value) => text(value),
+    console: consoleObject,
+    store: store,
+    load: load,
+    ALL_TOOLS: names,
+    describeTool: describeTool,
+  };
+  for (const [key, value] of Object.entries(globals)) {
+    Object.defineProperty(globalThis, key, { value: value, writable: false, enumerable: false, configurable: false });
+  }
+
+  function finish() {
+    closed = true;
+    waiting.length = 0;
+    for (const entry of pending.values()) entry.reject(new Error("The script has finished"));
+    pending.clear();
+    if (!storeChanged) return undefined;
+    const out = {};
+    for (const [k, v] of storeMap) out[k] = parse(v);
+    return stringify(out);
+  }
+
+  async function run(main) {
+    const value = await main;
+    if (value !== undefined) text(value);
+  }
+
+  return { deliver: deliver, finish: finish, run: run };
+})`;
+function send(message) {
+    process.stdout.write(`${JSON.stringify(message)
+        .replace(/\u2028/g, "\\u2028")
+        .replace(/\u2029/g, "\\u2029")}\n`);
+}
+/** 错误 → 一行说明；带上脚本里的行号（若能从栈里找到）。 */
+export function describeError(error) {
+    if (typeof error !== "object" || error === null)
+        return String(error);
+    const e = error;
+    const base = typeof e.message === "string"
+        ? `${typeof e.name === "string" ? e.name : "Error"}: ${e.message}`
+        : String(error);
+    const stack = typeof e.stack === "string" ? e.stack : "";
+    const at = new RegExp(`${SCRIPT_FILENAME.replace(".", "\\.")}:(\\d+)(?::(\\d+))?`).exec(stack);
+    return at === null ? base : `${base} (line ${at[1]})`;
+}
+let started = false;
+let finished = false;
+let bridge;
+let startedAt = 0;
+function done(ok, error) {
+    if (finished)
+        return;
+    finished = true;
+    if (bridge !== undefined) {
+        const snapshot = bridge.finish();
+        if (ok && snapshot !== undefined) {
+            send({ type: "store", entries: JSON.parse(snapshot) });
+        }
+    }
+    const message = { type: "done", ok, elapsedMs: Date.now() - startedAt };
+    if (error !== undefined)
+        message.error = error;
+    send(message);
+    // 等 stdout 冲完再退出（macOS 上管道写是异步的）。
+    process.stdout.write("", () => process.exit(0));
+}
+function host(kind, payload) {
+    if (finished)
+        return;
+    if (kind === "output") {
+        send({ type: "output", text: payload });
+        return;
+    }
+    if (kind === "tool_call") {
+        const newline = payload.indexOf("\n");
+        const id = Number(payload.slice(0, newline));
+        const call = JSON.parse(payload.slice(newline + 1));
+        send({ type: "tool_call", id, name: call.name, input: call.input });
+    }
+}
+function start(run) {
+    started = true;
+    startedAt = Date.now();
+    // 沙箱对象用空原型：上下文的全局属性查找不会落到本进程 realm 的 Object.prototype 上。
+    const context = createContext(Object.create(null), {
+        name: "codemode",
+        codeGeneration: { strings: false, wasm: false },
+    });
+    const config = {
+        maxConcurrent: MAX_CONCURRENT,
+        maxValueChars: MAX_STORE_VALUE_CHARS,
+        maxTotalChars: MAX_STORE_TOTAL_CHARS,
+        tools: JSON.stringify(run.tools),
+        store: JSON.stringify(run.store ?? {}),
+    };
+    let main;
+    try {
+        const factory = new Script(BOOTSTRAP, { filename: "codemode-bootstrap.js" }).runInContext(context);
+        bridge = factory(host, config);
+        main = new Script(`(async () => {\n${run.script}\n})()`, {
+            filename: SCRIPT_FILENAME,
+            lineOffset: -1,
+        }).runInContext(context);
+    }
+    catch (error) {
+        done(false, describeError(error));
+        return;
+    }
+    bridge.run(main).then(() => done(true), (error) => done(false, describeError(error)));
+}
+function handle(line) {
+    let message;
+    try {
+        message = JSON.parse(line);
+    }
+    catch {
+        return;
+    }
+    if (message.type === "run") {
+        if (!started)
+            start(message);
+    }
+    else if (message.type === "tool_result") {
+        if (message.ok) {
+            const json = message.value === undefined ? undefined : JSON.stringify(message.value);
+            bridge?.deliver(message.id, true, json);
+        }
+        else
+            bridge?.deliver(message.id, false, message.error);
+    }
+    else if (message.type === "abort") {
+        done(false, "Script aborted");
+    }
+}
+function main() {
+    // 脚本里未 await 的 Promise 被拒绝不应让子进程崩溃。
+    process.on("unhandledRejection", () => { });
+    process.on("uncaughtException", (error) => done(false, describeError(error)));
+    let buffer = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => {
+        buffer += chunk;
+        const lines = buffer.split("\n");
+        buffer = lines.pop() ?? "";
+        for (const line of lines)
+            if (line.trim() !== "")
+                handle(line);
+    });
+    process.stdin.on("end", () => {
+        if (buffer.trim() !== "")
+            handle(buffer);
+        buffer = "";
+        done(false, "Script aborted: parent closed the channel");
+    });
+}
+// 父进程启动时附加该参数（protocol.ts 的 SANDBOX_MAIN_FLAG）；没有它（例如被测试 import）就不启动。
+if (process.argv.includes("--ama-codemode-sandbox"))
+    main();

package/dist/codemode/store.d.ts

@@ -0,0 +1,26 @@
+/**
+ * codemode 的跨次存储（设计 §5.5 `store / load`）。[B10]
+ *
+ * - 存成 `custom{customType:"ama.codemode-store", data:{ entries }}` 条目（不进上下文）；每次成功
+ *   的脚本写过 store 就追加一条**完整快照**，读取取活动分支上最近一条——随会话分支走，fork /
+ *   切分支后只看本分支写过的值；
+ * - 单值 JSON ≤ 262 144 字符、合计 ≤ 1 048 576 字符（子进程里 store() 先检查一次，这里提交前
+ *   再检查一次，防止子进程被绕过）；
+ * - 脚本失败不提交（由 tool.ts 保证：只在 `done.ok` 时调用 commitStore）。
+ */
+import type { ToolContext } from "../tools/types.js";
+import type { StoreSnapshot } from "./protocol.js";
+export declare const STORE_CUSTOM_TYPE = "ama.codemode-store";
+export declare const MAX_STORE_VALUE_CHARS = 262144;
+export declare const MAX_STORE_TOTAL_CHARS = 1048576;
+export interface StoreEntryData {
+    entries: StoreSnapshot;
+}
+type SessionAccess = ToolContext["session"];
+/** 活动分支上最近一次提交的快照；没有或形状不对 → 空。 */
+export declare function readStore(session: SessionAccess): StoreSnapshot;
+/** 超限 / 非法 → 说明文字；合法 → undefined。 */
+export declare function validateStore(entries: StoreSnapshot): string | undefined;
+/** 校验并追加快照条目；超限不写，返回说明。 */
+export declare function commitStore(session: SessionAccess, entries: StoreSnapshot): string | undefined;
+export {};