@armadra/agent 0.0.0-stage → 0.3.0

package/dist/cli/subcommands/sessions.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `ama sessions list|show|prune`（设计 §1.2、§8）。[B5]
+ *
+ * 会话存储是 B2 的实现，经 RuntimeDeps.sessions 注入；这里只做参数、目录解析与输出格式。
+ * - list [--all]：缺省只列当前目录的会话；`--all` 列全部。
+ * - show <id>：头信息 + 条目类型统计 + 首条提示。
+ * - prune [--older-than <天>] [--dry-run]：缺省 30 天，移到 trash（不删除）。
+ */
+import type { CliIo, RuntimeDeps } from "../deps.js";
+export declare const SESSIONS_USAGE = "\u7528\u6CD5\uFF1Aama sessions list [--all] [--session-dir <\u76EE\u5F55>]\n      ama sessions show <id> [--session-dir <\u76EE\u5F55>]\n      ama sessions prune [--older-than <\u5929>] [--dry-run] [--all] [--session-dir <\u76EE\u5F55>]\n";
+export declare function runSessions(argv: readonly string[], io: CliIo, deps: Pick<RuntimeDeps, "sessions"> | undefined): Promise<number>;

package/dist/cli/subcommands/sessions.js

@@ -0,0 +1,100 @@
+/**
+ * `ama sessions list|show|prune`（设计 §1.2、§8）。[B5]
+ *
+ * 会话存储是 B2 的实现，经 RuntimeDeps.sessions 注入；这里只做参数、目录解析与输出格式。
+ * - list [--all]：缺省只列当前目录的会话；`--all` 列全部。
+ * - show <id>：头信息 + 条目类型统计 + 首条提示。
+ * - prune [--older-than <天>] [--dry-run]：缺省 30 天，移到 trash（不删除）。
+ */
+import { resolve } from "node:path";
+import { expandHome, resolveDataDir } from "../../config/paths.js";
+import { parseSubArgs, UsageError } from "../args.js";
+import { ExitCode } from "../exit-codes.js";
+export const SESSIONS_USAGE = `用法：ama sessions list [--all] [--session-dir <目录>]
+      ama sessions show <id> [--session-dir <目录>]
+      ama sessions prune [--older-than <天>] [--dry-run] [--all] [--session-dir <目录>]
+`;
+function shortTime(iso) {
+    return iso.replace("T", " ").replace(/\.\d+Z$|Z$/, "");
+}
+function oneLine(text, max = 60) {
+    if (text === undefined)
+        return "";
+    const flat = text.replace(/\s+/g, " ").trim();
+    return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+}
+export async function runSessions(argv, io, deps) {
+    const { positionals, values, flags } = parseSubArgs(argv, ["session-dir", "older-than"], ["all", "dry-run"]);
+    const action = positionals[0];
+    if (flags.has("help") || action === undefined) {
+        io.stdout(SESSIONS_USAGE);
+        return flags.has("help") ? ExitCode.Ok : ExitCode.Usage;
+    }
+    const dirFlag = values.get("session-dir");
+    const sessionDir = dirFlag !== undefined
+        ? resolve(io.cwd, expandHome(dirFlag, { env: io.env }))
+        : resolve(resolveDataDir({ env: io.env }), "sessions");
+    const sessions = deps?.sessions;
+    const scope = flags.has("all") ? {} : { cwd: io.cwd };
+    switch (action) {
+        case "list": {
+            if (sessions?.list === undefined)
+                return notWired(io, "sessions list");
+            const items = await sessions.list({ sessionDir, ...scope });
+            if (items.length === 0) {
+                io.stdout("没有会话\n");
+                return ExitCode.Ok;
+            }
+            for (const item of items) {
+                const name = item.name ?? oneLine(item.firstPrompt);
+                io.stdout(`${item.id.slice(0, 8)}  ${shortTime(item.modifiedAt)}  ${String(item.messageCount).padStart(4)} 条  ${name}\n`);
+            }
+            return ExitCode.Ok;
+        }
+        case "show": {
+            const id = positionals[1];
+            if (id === undefined)
+                throw new UsageError("ama sessions show 需要 <id>");
+            if (sessions?.show === undefined)
+                return notWired(io, "sessions show");
+            const { item, entries } = await sessions.show(id, { sessionDir });
+            const counts = new Map();
+            for (const entry of entries)
+                counts.set(entry.type, (counts.get(entry.type) ?? 0) + 1);
+            io.stdout([
+                `id：${item.id}`,
+                `文件：${item.file}`,
+                `目录：${item.cwd}`,
+                ...(item.name !== undefined ? [`名称：${item.name}`] : []),
+                `创建：${shortTime(item.createdAt)} · 修改：${shortTime(item.modifiedAt)}`,
+                `消息：${item.messageCount}`,
+                `条目：${[...counts].map(([type, n]) => `${type} ${n}`).join(" · ")}`,
+                ...(item.firstPrompt !== undefined
+                    ? [`首条提示：${oneLine(item.firstPrompt, 200)}`]
+                    : []),
+            ].join("\n") + "\n");
+            return ExitCode.Ok;
+        }
+        case "prune": {
+            const raw = values.get("older-than") ?? "30";
+            const olderThanDays = Number(raw);
+            if (!Number.isFinite(olderThanDays) || olderThanDays < 0) {
+                throw new UsageError(`--older-than 应为非负天数（收到 ${raw}）`);
+            }
+            if (sessions?.prune === undefined)
+                return notWired(io, "sessions prune");
+            const dryRun = flags.has("dry-run");
+            const { moved } = await sessions.prune({ sessionDir, olderThanDays, dryRun, ...scope });
+            for (const file of moved)
+                io.stdout(`${dryRun ? "将移到 trash" : "已移到 trash"}：${file}\n`);
+            io.stdout(`${moved.length} 个会话${dryRun ? "（演练，未改动）" : ""}\n`);
+            return ExitCode.Ok;
+        }
+        default:
+            throw new UsageError(`未知的 sessions 子命令：${action}`);
+    }
+}
+function notWired(io, what) {
+    io.stderr(`ama: ${what} 尚未装配（会话存储由集成批次注入）\n`);
+    return ExitCode.RuntimeError;
+}

package/dist/codemode/capability.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 沙箱能力探测（设计 §5.5 沙箱第 4 条）。[B10]
+ *
+ * Node 的权限模型（`--permission`）在 Node ≥ 25 同时拒绝网络；Node 22 / 24 只管文件、子进程、
+ * worker 与 addon，不管网络——脚本若逃出 `vm` 就能联网。所以：
+ * - Node ≥ 25 → `strict`；
+ * - Node 22 / 24 → 仍可用，但工具描述与状态栏标注「网络未隔离」；`codemode.requireStrict: true`
+ *   时直接禁用 codemode 工具并 warning（`codemodeAvailability`）。
+ *
+ * 状态栏由 B7 直接调用 `detectSandboxCapability()` 判断（不经宿主 status）。
+ */
+export interface SandboxCapability {
+    /** 权限模型同时隔离文件、子进程与网络。 */
+    strict: boolean;
+    /** 运行时 Node 的主版本。 */
+    nodeMajor: number;
+    /** 人读说明（英文，进工具描述；不含完整版本号以保证同一主版本下字节稳定）。 */
+    reason: string;
+    /** 运行时支持的权限开关：Node ≥ 22.13 / 23.5 为 `--permission`，更早为 `--experimental-permission`。 */
+    permissionFlag: "--permission" | "--experimental-permission";
+}
+export declare const NETWORK_NOT_ISOLATED = "network not isolated";
+export declare function parseNodeMajor(version: string): number;
+/** `--permission` 在 Node 22.13 / 23.5 之后才是稳定名字；之前只有 `--experimental-permission`。 */
+export declare function permissionFlagFor(allowedFlags?: ReadonlySet<string>): SandboxCapability["permissionFlag"];
+export declare function detectSandboxCapability(nodeVersion?: string, allowedFlags?: ReadonlySet<string>): SandboxCapability;
+export type CodemodeAvailability = {
+    available: true;
+    capability: SandboxCapability;
+    warning?: string;
+} | {
+    available: false;
+    capability: SandboxCapability;
+    warning: string;
+};
+/** `requireStrict` 且运行时不是 strict → 禁用并给出 warning；非 strict 但允许 → 可用并提示。 */
+export declare function codemodeAvailability(requireStrict: boolean | undefined, capability?: SandboxCapability): CodemodeAvailability;

package/dist/codemode/capability.js

@@ -0,0 +1,55 @@
+/**
+ * 沙箱能力探测（设计 §5.5 沙箱第 4 条）。[B10]
+ *
+ * Node 的权限模型（`--permission`）在 Node ≥ 25 同时拒绝网络；Node 22 / 24 只管文件、子进程、
+ * worker 与 addon，不管网络——脚本若逃出 `vm` 就能联网。所以：
+ * - Node ≥ 25 → `strict`；
+ * - Node 22 / 24 → 仍可用，但工具描述与状态栏标注「网络未隔离」；`codemode.requireStrict: true`
+ *   时直接禁用 codemode 工具并 warning（`codemodeAvailability`）。
+ *
+ * 状态栏由 B7 直接调用 `detectSandboxCapability()` 判断（不经宿主 status）。
+ */
+export const NETWORK_NOT_ISOLATED = "network not isolated";
+export function parseNodeMajor(version) {
+    const major = Number.parseInt(version.replace(/^v/, "").split(".")[0] ?? "", 10);
+    return Number.isFinite(major) ? major : 0;
+}
+/** `--permission` 在 Node 22.13 / 23.5 之后才是稳定名字；之前只有 `--experimental-permission`。 */
+export function permissionFlagFor(allowedFlags = process.allowedNodeEnvironmentFlags) {
+    return allowedFlags.has("--permission") ? "--permission" : "--experimental-permission";
+}
+export function detectSandboxCapability(nodeVersion = process.versions.node, allowedFlags) {
+    const nodeMajor = parseNodeMajor(nodeVersion);
+    const permissionFlag = permissionFlagFor(allowedFlags);
+    if (nodeMajor >= 25) {
+        return {
+            strict: true,
+            nodeMajor,
+            reason: `Node ${nodeMajor}: the permission model blocks file access, child processes and network`,
+            permissionFlag,
+        };
+    }
+    return {
+        strict: false,
+        nodeMajor,
+        reason: `Node ${nodeMajor}: ${NETWORK_NOT_ISOLATED} (the permission model blocks file access and child processes only)`,
+        permissionFlag,
+    };
+}
+/** `requireStrict` 且运行时不是 strict → 禁用并给出 warning；非 strict 但允许 → 可用并提示。 */
+export function codemodeAvailability(requireStrict, capability = detectSandboxCapability()) {
+    if (capability.strict)
+        return { available: true, capability };
+    if (requireStrict === true) {
+        return {
+            available: false,
+            capability,
+            warning: `codemode 已禁用：Node ${capability.nodeMajor} 的权限模型不隔离网络（codemode.requireStrict 为 true；Node ≥ 25 才隔离）`,
+        };
+    }
+    return {
+        available: true,
+        capability,
+        warning: `codemode：Node ${capability.nodeMajor} 下网络未隔离（Node ≥ 25 才隔离；要求隔离可设 codemode.requireStrict）`,
+    };
+}

package/dist/codemode/declarations.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 工具声明：JSON Schema 子集（`ai/types.ts` 的 JsonSchema）→ TypeScript 声明字符串（设计 §5.5）。[B10]
+ *
+ * - 每个工具一段：JSDoc 描述 + `name(args: {...}): Promise<R>;`，属性按 schema 原序，必填无 `?`，
+ *   属性的 description 作为行内 JSDoc；`items` → `T[]`，`enum` → 字面量联合，空 object → `Record`。
+ * - 返回类型：`bash` 解析为 `BashResult`（脚本里不受 50 KB 截断的结构化值），其余内置工具为文本，
+ *   宿主 / SDK 工具可能返回结构化值，声明为 `unknown`。
+ * - `inlineBudget`（估算 token = 字符 / 4）：按名排序依次内联，放不下的工具只列名字，脚本用
+ *   `describeTool(name)` 取完整声明。输出只依赖输入，字节稳定（设计 §9.1）。
+ */
+import type { JsonSchema } from "../ai/types.js";
+export declare const DEFAULT_INLINE_BUDGET = 3000;
+/** 脚本里 `tools.bash()` 的解析值（设计 §5.5）。 */
+export declare const BASH_RESULT_DECLARATION = "interface BashResult { output: string; truncated: boolean; fullOutputPath?: string; exitCode: number; wallTimeMs: number }";
+export interface DeclarableTool {
+    name: string;
+    description: string;
+    parameters: JsonSchema;
+}
+export interface DeclarationOptions {
+    /** 内置工具（非 bash）返回文本；其它来源返回 unknown。缺省 true。 */
+    textResult?: boolean;
+}
+export declare function estimateTokens(text: string): number;
+/** 单个 schema → TypeScript 类型表达式。 */
+export declare function schemaToType(schema: JsonSchema | undefined, indent?: string): string;
+/** 单个工具的声明（describeTool 返回它）。 */
+export declare function toolDeclaration(tool: DeclarableTool, options?: DeclarationOptions): string;
+export interface DeclarationBlock {
+    /** 内联进 codemode 描述的声明（按名排序）。 */
+    inline: string[];
+    /** 超出预算、只列名字的工具。 */
+    namesOnly: string[];
+    /** 拼好的文本。 */
+    text: string;
+}
+/**
+ * 按预算拼工具声明。工具按名排序；预算按估算 token 累计，第一个放不下的之后全部只列名字
+ * （保持按名顺序、不跳着塞小的，便于模型理解「后面的去 describeTool 查」）。
+ */
+export declare function buildDeclarationBlock(tools: readonly {
+    tool: DeclarableTool;
+    textResult?: boolean;
+}[], inlineBudget?: number): DeclarationBlock;

package/dist/codemode/declarations.js

@@ -0,0 +1,111 @@
+/**
+ * 工具声明：JSON Schema 子集（`ai/types.ts` 的 JsonSchema）→ TypeScript 声明字符串（设计 §5.5）。[B10]
+ *
+ * - 每个工具一段：JSDoc 描述 + `name(args: {...}): Promise<R>;`，属性按 schema 原序，必填无 `?`，
+ *   属性的 description 作为行内 JSDoc；`items` → `T[]`，`enum` → 字面量联合，空 object → `Record`。
+ * - 返回类型：`bash` 解析为 `BashResult`（脚本里不受 50 KB 截断的结构化值），其余内置工具为文本，
+ *   宿主 / SDK 工具可能返回结构化值，声明为 `unknown`。
+ * - `inlineBudget`（估算 token = 字符 / 4）：按名排序依次内联，放不下的工具只列名字，脚本用
+ *   `describeTool(name)` 取完整声明。输出只依赖输入，字节稳定（设计 §9.1）。
+ */
+export const DEFAULT_INLINE_BUDGET = 3000;
+/** 脚本里 `tools.bash()` 的解析值（设计 §5.5）。 */
+export const BASH_RESULT_DECLARATION = "interface BashResult { output: string; truncated: boolean; fullOutputPath?: string; exitCode: number; wallTimeMs: number }";
+export function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+const IDENT_RE = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+function propertyKey(name) {
+    return IDENT_RE.test(name) ? name : JSON.stringify(name);
+}
+function jsdoc(text, indent) {
+    if (text === undefined || text.trim() === "")
+        return "";
+    const clean = text.replace(/\*\//g, "*\\/").trim();
+    if (!clean.includes("\n"))
+        return `${indent}/** ${clean} */\n`;
+    const body = clean
+        .split("\n")
+        .map((line) => `${indent} * ${line}`.trimEnd())
+        .join("\n");
+    return `${indent}/**\n${body}\n${indent} */\n`;
+}
+/** 单个 schema → TypeScript 类型表达式。 */
+export function schemaToType(schema, indent = "") {
+    if (schema === undefined)
+        return "unknown";
+    if (schema.enum !== undefined && schema.enum.length > 0) {
+        return schema.enum.map((value) => JSON.stringify(value)).join(" | ");
+    }
+    switch (schema.type) {
+        case "string":
+            return "string";
+        case "number":
+        case "integer":
+            return "number";
+        case "boolean":
+            return "boolean";
+        case "array": {
+            const item = schemaToType(schema.items, indent);
+            return /[|&]/.test(item) && !item.startsWith("{") ? `(${item})[]` : `${item}[]`;
+        }
+        case "object":
+            return objectType(schema, indent);
+        default:
+            return schema.properties !== undefined ? objectType(schema, indent) : "unknown";
+    }
+}
+function objectType(schema, indent) {
+    const properties = Object.entries(schema.properties ?? {});
+    if (properties.length === 0)
+        return "Record<string, unknown>";
+    const required = new Set(schema.required ?? []);
+    const inner = `${indent}  `;
+    const lines = properties.map(([name, prop]) => {
+        const optional = required.has(name) ? "" : "?";
+        return `${jsdoc(prop.description, inner)}${inner}${propertyKey(name)}${optional}: ${schemaToType(prop, inner)};`;
+    });
+    return `{\n${lines.join("\n")}\n${indent}}`;
+}
+/** 单个工具的声明（describeTool 返回它）。 */
+export function toolDeclaration(tool, options = {}) {
+    const returns = tool.name === "bash" ? "BashResult" : options.textResult === false ? "unknown" : "string";
+    const args = schemaToType(tool.parameters);
+    return `${jsdoc(tool.description, "")}${tool.name}(args: ${args}): Promise<${returns}>;`;
+}
+/**
+ * 按预算拼工具声明。工具按名排序；预算按估算 token 累计，第一个放不下的之后全部只列名字
+ * （保持按名顺序、不跳着塞小的，便于模型理解「后面的去 describeTool 查」）。
+ */
+export function buildDeclarationBlock(tools, inlineBudget = DEFAULT_INLINE_BUDGET) {
+    const sorted = [...tools].sort((a, b) => (a.tool.name < b.tool.name ? -1 : 1));
+    const inline = [];
+    const namesOnly = [];
+    let used = 0;
+    for (const { tool, textResult } of sorted) {
+        const decl = toolDeclaration(tool, textResult === false ? { textResult } : {});
+        const cost = estimateTokens(decl);
+        if (namesOnly.length === 0 && used + cost <= inlineBudget) {
+            inline.push(decl);
+            used += cost;
+        }
+        else
+            namesOnly.push(tool.name);
+    }
+    const parts = [];
+    if (sorted.some(({ tool }) => tool.name === "bash"))
+        parts.push(BASH_RESULT_DECLARATION);
+    if (inline.length > 0) {
+        parts.push(`declare const tools: {\n${indent(inline.join("\n"))}\n};`);
+    }
+    if (namesOnly.length > 0) {
+        parts.push(`// Also callable (use describeTool(name) for the signature): ${namesOnly.join(", ")}`);
+    }
+    return { inline, namesOnly, text: parts.join("\n") };
+}
+function indent(text) {
+    return text
+        .split("\n")
+        .map((line) => (line === "" ? line : `  ${line}`))
+        .join("\n");
+}

package/dist/codemode/host-side.d.ts

@@ -0,0 +1,59 @@
+/**
+ * codemode 父进程侧：起子进程、转发工具调用、超时杀树（设计 §5.5 沙箱第 1–4 条）。[B10]
+ *
+ * - 命令行：`<node> --permission --allow-fs-read=<入口> --disallow-code-generation-from-strings
+ *   <入口> --ama-codemode-sandbox`；Node 22.0–22.12 用 `--experimental-permission`。不授予文件写、
+ *   子进程、worker、addon、inspector 权限；以空环境启动（拿不到密钥与会话路径）；嵌入 Electron
+ *   时设 `ELECTRON_RUN_AS_NODE=1` 运行同一可执行文件。
+ * - 入口：bundle 里是 ama.cjs 同目录的 `ama-sandbox.cjs`（构建脚本定义 `__AMA_SANDBOX_ENTRY__`）；
+ *   tsc 产物里是同目录的 `sandbox-entry.js`；源码树里是 `sandbox-entry.ts`；取 realpath（权限模型
+ *   按真实路径比对，macOS 的 /tmp、/var 是符号链接）。
+ * - `tool_call` → `callTool(name, input, signal)`：由 tool.ts 接到 `ToolContext.tools.executeTool`
+ *   （完整门禁）；名字是 `codemode` 直接拒绝。脚本结束时 abort 仍在跑的调用。
+ * - 超时：父进程计时，到点杀子进程树（POSIX 进程组 / Windows taskkill）；外层 abort：先发
+ *   `abort`，宽限后杀树。
+ */
+import { type SandboxCapability } from "./capability.js";
+import { type ScriptOptions, type StoreSnapshot, type ToolDecl } from "./protocol.js";
+/** 父进程累积的输出上限（字符）；超出后丢弃中段（给模型的再按 max_output_tokens 截）。 */
+export declare const MAX_COLLECTED_OUTPUT_CHARS: number;
+/** 外层 abort 后等子进程自行结束的宽限。 */
+export declare const ABORT_GRACE_MS = 500;
+/** 子进程入口的绝对路径（realpath）；找不到 → undefined。 */
+export declare function resolveSandboxEntry(moduleUrl?: string): string | undefined;
+/** 子进程参数（不含可执行文件）。 */
+export declare function sandboxArgs(entry: string, capability?: Pick<SandboxCapability, "permissionFlag">): string[];
+/** 子进程环境：空；Electron 下以 Node 方式运行同一可执行文件；Windows 保留 SystemRoot。 */
+export declare function sandboxEnv(versions?: NodeJS.ProcessVersions, platform?: NodeJS.Platform, parentEnv?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export interface SandboxRunRequest {
+    script: string;
+    options: ScriptOptions;
+    tools: ToolDecl[];
+    store: StoreSnapshot;
+    /** 执行一次内层工具调用：解析为脚本拿到的值，失败抛 Error（消息给脚本）。 */
+    callTool(name: string, input: unknown, signal: AbortSignal): Promise<unknown>;
+    onOutput?(text: string): void;
+    signal: AbortSignal;
+    /** 缺省 resolveSandboxEntry()。 */
+    entry?: string;
+    /** 缺省 process.execPath。 */
+    nodePath?: string;
+    capability?: Pick<SandboxCapability, "permissionFlag">;
+}
+export interface SandboxRunResult {
+    ok: boolean;
+    error?: string;
+    outputs: string[];
+    /** 脚本成功且写过 store 时的完整快照。 */
+    store?: StoreSnapshot;
+    elapsedMs: number;
+    timedOut: boolean;
+    aborted: boolean;
+    /** 内层调用次数。 */
+    toolCalls: number;
+    /** 输出超过 MAX_COLLECTED_OUTPUT_CHARS 被丢弃的字符数。 */
+    droppedChars: number;
+    /** 子进程 pid（POSIX 下也是进程组 id）。 */
+    pid?: number;
+}
+export declare function runSandbox(request: SandboxRunRequest): Promise<SandboxRunResult>;

package/dist/codemode/host-side.js

@@ -0,0 +1,253 @@
+/**
+ * codemode 父进程侧：起子进程、转发工具调用、超时杀树（设计 §5.5 沙箱第 1–4 条）。[B10]
+ *
+ * - 命令行：`<node> --permission --allow-fs-read=<入口> --disallow-code-generation-from-strings
+ *   <入口> --ama-codemode-sandbox`；Node 22.0–22.12 用 `--experimental-permission`。不授予文件写、
+ *   子进程、worker、addon、inspector 权限；以空环境启动（拿不到密钥与会话路径）；嵌入 Electron
+ *   时设 `ELECTRON_RUN_AS_NODE=1` 运行同一可执行文件。
+ * - 入口：bundle 里是 ama.cjs 同目录的 `ama-sandbox.cjs`（构建脚本定义 `__AMA_SANDBOX_ENTRY__`）；
+ *   tsc 产物里是同目录的 `sandbox-entry.js`；源码树里是 `sandbox-entry.ts`；取 realpath（权限模型
+ *   按真实路径比对，macOS 的 /tmp、/var 是符号链接）。
+ * - `tool_call` → `callTool(name, input, signal)`：由 tool.ts 接到 `ToolContext.tools.executeTool`
+ *   （完整门禁）；名字是 `codemode` 直接拒绝。脚本结束时 abort 仍在跑的调用。
+ * - 超时：父进程计时，到点杀子进程树（POSIX 进程组 / Windows taskkill）；外层 abort：先发
+ *   `abort`，宽限后杀树。
+ */
+import { spawn } from "node:child_process";
+import { existsSync, realpathSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { killProcessTree, trackProcessGroup, untrackProcessGroup } from "../tools/process-tree.js";
+import { detectSandboxCapability } from "./capability.js";
+import { LineSplitter, SANDBOX_MAIN_FLAG, decodeChildLine, encodeLine, } from "./protocol.js";
+/** 父进程累积的输出上限（字符）；超出后丢弃中段（给模型的再按 max_output_tokens 截）。 */
+export const MAX_COLLECTED_OUTPUT_CHARS = 16 * 1024 * 1024;
+/** 外层 abort 后等子进程自行结束的宽限。 */
+export const ABORT_GRACE_MS = 500;
+/** 子进程入口的绝对路径（realpath）；找不到 → undefined。 */
+export function resolveSandboxEntry(moduleUrl = import.meta.url) {
+    const here = dirname(fileURLToPath(moduleUrl));
+    const candidates = [];
+    if (typeof __AMA_SANDBOX_ENTRY__ !== "undefined")
+        candidates.push(join(here, __AMA_SANDBOX_ENTRY__));
+    candidates.push(join(here, "sandbox-entry.js"));
+    // 源码树（vitest / 开发）：Node ≥ 22.18 直接剥离类型运行 .ts（入口只 import node: 与类型）。
+    candidates.push(join(here, "sandbox-entry.ts"));
+    for (const candidate of candidates) {
+        if (existsSync(candidate))
+            return realpathSync(candidate);
+    }
+    return undefined;
+}
+/** 子进程参数（不含可执行文件）。 */
+export function sandboxArgs(entry, capability = detectSandboxCapability()) {
+    return [
+        capability.permissionFlag,
+        `--allow-fs-read=${entry}`,
+        "--disallow-code-generation-from-strings",
+        entry,
+        SANDBOX_MAIN_FLAG,
+    ];
+}
+/** 子进程环境：空；Electron 下以 Node 方式运行同一可执行文件；Windows 保留 SystemRoot。 */
+export function sandboxEnv(versions = process.versions, platform = process.platform, parentEnv = process.env) {
+    const env = {};
+    if (versions.electron !== undefined)
+        env["ELECTRON_RUN_AS_NODE"] = "1";
+    if (platform === "win32") {
+        const root = parentEnv["SystemRoot"] ?? parentEnv["SYSTEMROOT"];
+        if (root !== undefined)
+            env["SystemRoot"] = root;
+    }
+    return env;
+}
+export async function runSandbox(request) {
+    const started = Date.now();
+    const entry = request.entry ?? resolveSandboxEntry();
+    const base = {
+        outputs: [],
+        timedOut: false,
+        aborted: false,
+        toolCalls: 0,
+        droppedChars: 0,
+    };
+    if (entry === undefined) {
+        return {
+            ...base,
+            ok: false,
+            error: "codemode sandbox entry not found (build the package first)",
+            elapsedMs: 0,
+        };
+    }
+    if (request.signal.aborted) {
+        return { ...base, ok: false, error: "Script aborted", aborted: true, elapsedMs: 0 };
+    }
+    const isWindows = process.platform === "win32";
+    const child = spawn(request.nodePath ?? process.execPath, sandboxArgs(entry, request.capability), {
+        env: sandboxEnv(),
+        stdio: ["pipe", "pipe", "pipe"],
+        detached: !isWindows,
+        windowsHide: true,
+    });
+    const pid = child.pid;
+    if (pid !== undefined && !isWindows)
+        trackProcessGroup(pid);
+    const calls = new AbortController();
+    const result = { ...base, ok: false, elapsedMs: 0 };
+    if (pid !== undefined)
+        result.pid = pid;
+    let collected = 0;
+    let stderr = "";
+    let settled = false;
+    let finish;
+    const finished = new Promise((resolve) => (finish = resolve));
+    const write = (message) => {
+        if (child.stdin.destroyed || !child.stdin.writable)
+            return;
+        child.stdin.write(encodeLine(message));
+    };
+    const kill = () => {
+        if (pid === undefined)
+            return;
+        void killProcessTree(pid, { graceMs: 200 }).finally(() => {
+            if (!isWindows)
+                untrackProcessGroup(pid);
+        });
+    };
+    const settle = (patch) => {
+        if (settled)
+            return;
+        settled = true;
+        Object.assign(result, patch);
+        result.elapsedMs = patch.elapsedMs ?? Date.now() - started;
+        calls.abort();
+        finish();
+    };
+    const timer = setTimeout(() => {
+        settle({
+            ok: false,
+            timedOut: true,
+            error: `Script timed out after ${request.options.timeoutMs} ms`,
+        });
+        kill();
+    }, request.options.timeoutMs);
+    let graceTimer;
+    const onAbort = () => {
+        write({ type: "abort" });
+        graceTimer = setTimeout(() => {
+            settle({ ok: false, aborted: true, error: "Script aborted" });
+            kill();
+        }, ABORT_GRACE_MS);
+    };
+    request.signal.addEventListener("abort", onAbort, { once: true });
+    child.stdin.on("error", () => { });
+    child.stderr.setEncoding("utf8");
+    child.stderr.on("data", (chunk) => {
+        stderr = (stderr + chunk).slice(-4000);
+    });
+    const splitter = new LineSplitter();
+    const onLine = (line) => {
+        if (settled)
+            return;
+        let message;
+        try {
+            message = decodeChildLine(line);
+        }
+        catch {
+            return;
+        }
+        switch (message.type) {
+            case "output": {
+                const text = message.text;
+                if (collected + text.length > MAX_COLLECTED_OUTPUT_CHARS) {
+                    result.droppedChars += text.length;
+                    return;
+                }
+                collected += text.length;
+                result.outputs.push(text);
+                request.onOutput?.(text);
+                return;
+            }
+            case "tool_call": {
+                const { id, name, input } = message;
+                result.toolCalls++;
+                if (name === "codemode") {
+                    write({
+                        type: "tool_result",
+                        id,
+                        ok: false,
+                        error: "codemode cannot be called from a codemode script",
+                    });
+                    return;
+                }
+                request.callTool(name, input, calls.signal).then((value) => {
+                    if (!settled)
+                        write({ type: "tool_result", id, ok: true, value: value ?? null });
+                }, (error) => {
+                    if (!settled) {
+                        write({
+                            type: "tool_result",
+                            id,
+                            ok: false,
+                            error: error instanceof Error ? error.message : String(error),
+                        });
+                    }
+                });
+                return;
+            }
+            case "store":
+                result.store = message.entries;
+                return;
+            case "done": {
+                const patch = { ok: message.ok, elapsedMs: message.elapsedMs };
+                if (message.error !== undefined)
+                    patch.error = message.error;
+                if (request.signal.aborted) {
+                    patch.ok = false;
+                    patch.aborted = true;
+                }
+                if (patch.ok !== true)
+                    delete result.store;
+                settle(patch);
+                return;
+            }
+        }
+    };
+    child.stdout.setEncoding("utf8");
+    child.stdout.on("data", (chunk) => {
+        for (const line of splitter.push(chunk))
+            onLine(line);
+    });
+    child.on("error", (error) => settle({ ok: false, error: `Failed to start codemode sandbox: ${error.message}` }));
+    child.on("close", (code, signal) => {
+        for (const line of splitter.flush())
+            onLine(line);
+        if (pid !== undefined && !isWindows)
+            untrackProcessGroup(pid);
+        const detail = stderr.trim().split("\n").slice(-3).join(" | ");
+        settle({
+            ok: false,
+            error: `codemode sandbox exited unexpectedly (${signal ?? `code ${code}`})${detail === "" ? "" : `: ${detail}`}`,
+        });
+    });
+    write({
+        type: "run",
+        script: request.script,
+        options: request.options,
+        tools: request.tools,
+        store: request.store,
+    });
+    await finished;
+    clearTimeout(timer);
+    if (graceTimer !== undefined)
+        clearTimeout(graceTimer);
+    request.signal.removeEventListener("abort", onAbort);
+    if (child.exitCode === null && child.signalCode === null) {
+        // 正常结束时子进程会自行退出；兜底：稍后仍在就杀掉。
+        const reaper = setTimeout(kill, 1000);
+        reaper.unref();
+        child.once("close", () => clearTimeout(reaper));
+    }
+    child.stdin.end();
+    return result;
+}