@armadra/agent 0.0.0-stage → 0.3.0

package/dist/codemode/store.js

@@ -0,0 +1,53 @@
+/**
+ * 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）。
+ */
+export const STORE_CUSTOM_TYPE = "ama.codemode-store";
+export const MAX_STORE_VALUE_CHARS = 262_144;
+export const MAX_STORE_TOTAL_CHARS = 1_048_576;
+/** 活动分支上最近一次提交的快照；没有或形状不对 → 空。 */
+export function readStore(session) {
+    const data = session.lastCustom(STORE_CUSTOM_TYPE);
+    const entries = data?.entries;
+    if (typeof entries !== "object" || entries === null || Array.isArray(entries))
+        return {};
+    return { ...entries };
+}
+/** 超限 / 非法 → 说明文字；合法 → undefined。 */
+export function validateStore(entries) {
+    let total = 0;
+    for (const [key, value] of Object.entries(entries)) {
+        let json;
+        try {
+            json = JSON.stringify(value);
+        }
+        catch {
+            json = undefined;
+        }
+        if (json === undefined)
+            return `store value "${key}" is not JSON-serializable`;
+        if (json.length > MAX_STORE_VALUE_CHARS) {
+            return `store value "${key}" is ${json.length} characters of JSON (limit ${MAX_STORE_VALUE_CHARS})`;
+        }
+        total += json.length;
+    }
+    if (total > MAX_STORE_TOTAL_CHARS) {
+        return `store holds ${total} characters of JSON (limit ${MAX_STORE_TOTAL_CHARS})`;
+    }
+    return undefined;
+}
+/** 校验并追加快照条目；超限不写，返回说明。 */
+export function commitStore(session, entries) {
+    const problem = validateStore(entries);
+    if (problem !== undefined)
+        return problem;
+    const data = { entries };
+    session.appendCustom(STORE_CUSTOM_TYPE, data);
+    return undefined;
+}

package/dist/codemode/tool.d.ts

@@ -0,0 +1,105 @@
+/**
+ * `codemode` 工具（设计 §5.5）：模型写一段 JavaScript，脚本里经 `tools.*` 编排多次工具调用，只有
+ * 脚本输出回到模型。[B10]
+ *
+ * - 权限类：网络隔离时 `read`，否则 `execute`；`sequential`；脚本里的每次 `tools.*` 经 `ToolContext.tools.executeTool`
+ *   走完整门禁（schema → PreToolUse → 权限管线 → 审批 → 执行 → PostToolUse），Hook 输入带
+ *   `viaCodemode: true` 与父 toolCallId，事件带 `parentToolCallId`（agent/tool-runner.ts）；
+ * - 返回值：`bash` 解析为 `{ output, truncated, fullOutputPath?, exitCode, wallTimeMs }`（非零退出码
+ *   也解析），其它工具解析为 `structured` 或文本；失败、被拒、参数非法 → 以 Error reject；
+ * - 结果：`Script completed` / `Script failed` + 用时 + 输出；超过 `max_output_tokens`（以及会话的
+ *   单条结果上限）保留首尾，全文写 `<outputDir>/<toolCallId>.txt`；失败时保留已产出输出；
+ * - store 只在脚本成功时提交（store.ts）；
+ * - 描述（含工具声明）在第一次读取时确定并冻结：同一会话内字节稳定（设计 §9.1），之后注册的宿主
+ *   工具仍可在脚本里调用（`ALL_TOOLS` / `describeTool` 是执行时的清单）。
+ */
+import type { ToolDefinition, ToolResult } from "../tools/types.js";
+import { type SandboxCapability } from "./capability.js";
+import { type DeclarableTool } from "./declarations.js";
+import { type SandboxRunResult } from "./host-side.js";
+export declare const CODEMODE_TOOL_NAME = "codemode";
+export interface CodemodeInput {
+    script: string;
+}
+export interface CallableTool {
+    tool: DeclarableTool;
+    /** 内置工具（非 bash）解析为文本；宿主 / SDK 工具可能返回结构化值。 */
+    textResult: boolean;
+}
+export interface CodemodeToolOptions {
+    /** 脚本里可调用的工具（不含 codemode 本身）；描述冻结时与每次执行时各调用一次。 */
+    listTools(): CallableTool[];
+    /** 描述里内联声明的预算（估算 token），缺省 3000。 */
+    inlineBudget?: number;
+    /** 缺省 detectSandboxCapability()。 */
+    capability?: SandboxCapability;
+    /** 会话的单条工具结果上限（runner 会再截一次；这里先按它收紧，避免二次截断丢掉尾部）。 */
+    maxResultChars?: number;
+    /** `only` 模式：其它工具不直接暴露，系统提示的工具行与规则写明只能在脚本里调用。 */
+    exclusive?: boolean;
+    /** 子进程入口（测试 / 嵌入方覆盖）。 */
+    entry?: string;
+    nodePath?: string;
+}
+export interface CodemodeDetails {
+    ok: boolean;
+    elapsedMs: number;
+    toolCalls: number;
+    timedOut: boolean;
+    aborted: boolean;
+    strict: boolean;
+    fullOutputPath?: string;
+    error?: string;
+}
+/** 脚本里拿到的 bash 结果。 */
+export interface ScriptBashResult {
+    output: string;
+    truncated: boolean;
+    fullOutputPath?: string;
+    exitCode: number;
+    wallTimeMs: number;
+}
+/** 内层工具结果 → 脚本拿到的值；失败抛 Error。 */
+export declare function toScriptValue(name: string, result: ToolResult): unknown;
+/** 描述里的示例脚本（6 行）：并发两个 read、过滤、return。 */
+export declare const CODEMODE_EXAMPLE: readonly string[];
+/**
+ * 脚本失败原因后补一句正确写法：用了 require / import / process 等，或把工具名当函数直接调用
+ * （实测模型常见的两种错误）。其它错误原样返回。
+ */
+export declare function scriptErrorHint(error: string, toolNames: readonly string[]): string;
+export declare function buildCodemodeDescription(tools: readonly CallableTool[], inlineBudget: number, capability: SandboxCapability): string;
+/** 结果文本：状态行 + 输出（超限保留首尾）+ 失败原因。 */
+export declare function formatCodemodeResult(run: Pick<SandboxRunResult, "ok" | "error" | "outputs" | "elapsedMs" | "droppedChars">, limitChars: number, saveFull: (text: string) => string | undefined): {
+    text: string;
+    fullOutputPath?: string;
+};
+/** `only` 模式的系统提示规则（实测模型仍会先直接调用 read / edit / bash）。 */
+export declare const CODEMODE_ONLY_GUIDELINE = "read, edit, write, bash and the other tools are not callable directly here: every tool call goes inside a codemode script as tools.<name>(args); batch related calls in one script.";
+export declare function createCodemodeTool(options: CodemodeToolOptions): ToolDefinition<CodemodeInput>;
+/** 组装根用：从 ToolFactoryContext 的形状取所需（避免 codemode → cli 的依赖）。 */
+export interface CodemodeFactoryContext {
+    config: {
+        codemode?: {
+            mode?: "off" | "on" | "only";
+            inlineBudget?: number;
+            requireStrict?: boolean;
+        };
+        tools?: {
+            preset?: string;
+            maxToolResultChars?: number;
+        };
+    };
+    registry: {
+        list(): readonly string[];
+        get(name: string): ToolDefinition | undefined;
+    } & {
+        sourceOf?(name: string): string | undefined;
+    };
+    warn(message: string): void;
+}
+/**
+ * codemode 工具工厂：`codemode.mode` 生效值为 off → 不注册；`requireStrict` 而运行时不隔离网络
+ * → 不注册并 warning（预设随之回退到 default）。
+ */
+export declare function codemodeToolFactory(overrides?: Partial<Pick<CodemodeToolOptions, "capability" | "entry" | "nodePath">>): (ctx: CodemodeFactoryContext) => ToolDefinition | undefined;

package/dist/codemode/tool.js

@@ -0,0 +1,283 @@
+/**
+ * `codemode` 工具（设计 §5.5）：模型写一段 JavaScript，脚本里经 `tools.*` 编排多次工具调用，只有
+ * 脚本输出回到模型。[B10]
+ *
+ * - 权限类：网络隔离时 `read`，否则 `execute`；`sequential`；脚本里的每次 `tools.*` 经 `ToolContext.tools.executeTool`
+ *   走完整门禁（schema → PreToolUse → 权限管线 → 审批 → 执行 → PostToolUse），Hook 输入带
+ *   `viaCodemode: true` 与父 toolCallId，事件带 `parentToolCallId`（agent/tool-runner.ts）；
+ * - 返回值：`bash` 解析为 `{ output, truncated, fullOutputPath?, exitCode, wallTimeMs }`（非零退出码
+ *   也解析），其它工具解析为 `structured` 或文本；失败、被拒、参数非法 → 以 Error reject；
+ * - 结果：`Script completed` / `Script failed` + 用时 + 输出；超过 `max_output_tokens`（以及会话的
+ *   单条结果上限）保留首尾，全文写 `<outputDir>/<toolCallId>.txt`；失败时保留已产出输出；
+ * - store 只在脚本成功时提交（store.ts）；
+ * - 描述（含工具声明）在第一次读取时确定并冻结：同一会话内字节稳定（设计 §9.1），之后注册的宿主
+ *   工具仍可在脚本里调用（`ALL_TOOLS` / `describeTool` 是执行时的清单）。
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { codemodeAvailability, detectSandboxCapability, } from "./capability.js";
+import { DEFAULT_INLINE_BUDGET, buildDeclarationBlock, toolDeclaration, } from "./declarations.js";
+import { runSandbox } from "./host-side.js";
+import { codemodeHint } from "./modes.js";
+import { parseOptionsLine } from "./protocol.js";
+import { commitStore, readStore } from "./store.js";
+export const CODEMODE_TOOL_NAME = "codemode";
+/** 与 agent/tool-runner.ts 的 DEFAULT_MAX_TOOL_RESULT_CHARS 一致（codemode 与 tools 同层，不 import agent）。 */
+const DEFAULT_MAX_TOOL_RESULT_CHARS = 30_000;
+function textOf(content) {
+    if (typeof content === "string")
+        return content;
+    return content.map((block) => (block.type === "text" ? block.text : "")).join("");
+}
+function isBashStructured(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof value.output === "string" &&
+        typeof value.exit_code === "number");
+}
+/** 内层工具结果 → 脚本拿到的值；失败抛 Error。 */
+export function toScriptValue(name, result) {
+    if (name === "bash" && isBashStructured(result.structured)) {
+        const s = result.structured;
+        const value = {
+            output: s.output,
+            truncated: s.truncated,
+            exitCode: s.exit_code,
+            wallTimeMs: Math.round(s.wall_time_seconds * 1000),
+        };
+        if (s.full_output_path !== undefined)
+            value.fullOutputPath = s.full_output_path;
+        return value;
+    }
+    if (result.isError === true)
+        throw new Error(textOf(result.content) || `Tool ${name} failed`);
+    return result.structured !== undefined ? result.structured : textOf(result.content);
+}
+/** on 模式下其它工具描述末尾的提示不进声明。 */
+function declarable(tool) {
+    const suffix = `\n${codemodeHint(tool.name)}`;
+    if (!tool.description.endsWith(suffix))
+        return tool;
+    return { ...tool, description: tool.description.slice(0, -suffix.length) };
+}
+/** 描述里的示例脚本（6 行）：并发两个 read、过滤、return。 */
+export const CODEMODE_EXAMPLE = [
+    "const [a, b] = await Promise.all([",
+    '  tools.read({ path: "src/a.ts" }),',
+    '  tools.read({ path: "src/b.ts" }),',
+    "]);",
+    'const hits = (a + "\\n" + b).split("\\n").filter((line) => line.includes("TODO"));',
+    'return hits.join("\\n");',
+];
+const SCRIPT_ONLY_GLOBALS = /\b(require|process|fetch|setTimeout|setInterval|setImmediate) is not defined/;
+/**
+ * 脚本失败原因后补一句正确写法：用了 require / import / process 等，或把工具名当函数直接调用
+ * （实测模型常见的两种错误）。其它错误原样返回。
+ */
+export function scriptErrorHint(error, toolNames) {
+    if (/Cannot use import statement|dynamic import callback/.test(error) ||
+        SCRIPT_ONLY_GLOBALS.test(error)) {
+        return `${error}\nOnly tools.<name>(args) is available in codemode scripts (no require, import, process, fetch or timers).`;
+    }
+    const called = /ReferenceError: ([A-Za-z_$][\w$]*) is not defined/.exec(error)?.[1];
+    if (called !== undefined && toolNames.includes(called)) {
+        return `${error}\nCall tools as tools.${called}({...}), not ${called}(...).`;
+    }
+    return error;
+}
+export function buildCodemodeDescription(tools, inlineBudget, capability) {
+    const lines = [
+        "Run a JavaScript script that calls tools; only the script's output comes back to you. Use it to batch many tool calls (Promise.all), filter or summarize large results, or loop, in one step.",
+        "Only tools.<name>(args) is available. There is no require, import, process, fetch or timers; do not call tools directly as functions.",
+        'The input is raw JavaScript (not JSON, no code fence), run as the body of an async function: top-level await and return work. Optional first line: // @options: {"max_output_tokens": 10000, "timeout_ms": 300000}',
+        "Example:",
+        ...CODEMODE_EXAMPLE,
+        "Globals: tools.<name>(args) returns a Promise and rejects with an Error when the call fails or is denied (use Promise.allSettled to keep the rest); text(v) and console.log(...) append output (non-strings as JSON); return v is text(v); store(key, v) / load(key) keep small JSON values across scripts (saved only when the script succeeds); ALL_TOOLS lists callable tools; describeTool(name) returns a declaration. At most 8 tool calls run at once; codemode cannot call itself. Every call goes through the normal hooks, permissions and approvals.",
+    ];
+    if (!capability.strict) {
+        lines.push(`Sandbox: ${capability.reason}.`);
+    }
+    const block = buildDeclarationBlock(tools.map(({ tool, textResult }) => ({ tool: declarable(tool), textResult })), inlineBudget);
+    if (block.text !== "")
+        lines.push(block.text);
+    return lines.join("\n");
+}
+/** 结果文本：状态行 + 输出（超限保留首尾）+ 失败原因。 */
+export function formatCodemodeResult(run, limitChars, saveFull) {
+    const seconds = (run.elapsedMs / 1000).toFixed(2);
+    const header = `${run.ok ? "Script completed" : "Script failed"} in ${seconds}s`;
+    let output = run.outputs.join("\n");
+    if (run.droppedChars > 0) {
+        output += `\n[${run.droppedChars} more characters of output were discarded]`;
+    }
+    let fullOutputPath;
+    if (output.length > limitChars) {
+        fullOutputPath = saveFull(output);
+        const half = Math.max(1, Math.floor(limitChars / 2));
+        const omitted = output.length - half * 2;
+        const where = fullOutputPath === undefined ? "" : `; full output: ${fullOutputPath}`;
+        output = `${output.slice(0, half)}\n[... ${omitted} characters omitted${where} ...]\n${output.slice(-half)}`;
+    }
+    const parts = [header, output === "" ? "(no output)" : output];
+    if (!run.ok && run.error !== undefined)
+        parts.push(`Script error: ${run.error}`);
+    const result = { text: parts.join("\n\n") };
+    if (fullOutputPath !== undefined)
+        result.fullOutputPath = fullOutputPath;
+    return result;
+}
+function saveFullOutput(ctx, text) {
+    try {
+        const dir = ctx.outputDir ?? join(tmpdir(), "ama-codemode");
+        mkdirSync(dir, { recursive: true });
+        const file = join(dir, `${ctx.toolCallId.replace(/[^A-Za-z0-9_-]/g, "_")}.txt`);
+        writeFileSync(file, text, "utf8");
+        return file;
+    }
+    catch {
+        return undefined;
+    }
+}
+const TAIL_CHARS = 4000;
+/** `only` 模式的系统提示规则（实测模型仍会先直接调用 read / edit / bash）。 */
+export const CODEMODE_ONLY_GUIDELINE = "read, edit, write, bash and the other tools are not callable directly here: every tool call goes inside a codemode script as tools.<name>(args); batch related calls in one script.";
+export function createCodemodeTool(options) {
+    const capability = options.capability ?? detectSandboxCapability();
+    const inlineBudget = options.inlineBudget ?? DEFAULT_INLINE_BUDGET;
+    const maxResultChars = options.maxResultChars ?? DEFAULT_MAX_TOOL_RESULT_CHARS;
+    let frozenDescription;
+    const tool = {
+        name: CODEMODE_TOOL_NAME,
+        label: "Codemode",
+        get description() {
+            frozenDescription ??= buildCodemodeDescription(options.listTools(), inlineBudget, capability);
+            return frozenDescription;
+        },
+        parameters: {
+            type: "object",
+            properties: {
+                script: { type: "string", description: "Raw JavaScript (async function body)" },
+            },
+            required: ["script"],
+        },
+        // 网络隔离（Node ≥ 25）时脚本只能经 tools.* 做事，每次内层调用各自过权限：codemode 本身按 read
+        // 类（default 模式免审批）；不隔离网络时脚本逃出 vm 就能联网，仍按 execute。
+        permission: capability.strict ? "read" : "execute",
+        executionMode: "sequential",
+        promptSnippet: options.exclusive === true
+            ? "codemode: your only tool; run a JavaScript script that calls the other tools as tools.<name>(args); only its output returns"
+            : "codemode: run a JavaScript script that calls tools; only its output returns",
+        ...(options.exclusive === true ? { promptGuidelines: [CODEMODE_ONLY_GUIDELINE] } : {}),
+        async execute(input, ctx) {
+            let scriptOptions;
+            try {
+                scriptOptions = parseOptionsLine(input.script);
+            }
+            catch (error) {
+                return { content: error.message, isError: true };
+            }
+            const tools = options.listTools().map(({ tool: t, textResult }) => ({
+                name: t.name,
+                declaration: toolDeclaration(declarable(t), textResult ? {} : { textResult: false }),
+            }));
+            let tail = "";
+            const run = await runSandbox({
+                script: input.script,
+                options: scriptOptions,
+                tools,
+                store: readStore(ctx.session),
+                signal: ctx.signal,
+                ...(options.entry !== undefined ? { entry: options.entry } : {}),
+                ...(options.nodePath !== undefined ? { nodePath: options.nodePath } : {}),
+                callTool: async (name, args, signal) => toScriptValue(name, await ctx.tools.executeTool(name, args, { signal })),
+                onOutput: (text) => {
+                    tail = `${tail}${tail === "" ? "" : "\n"}${text}`.slice(-TAIL_CHARS);
+                    ctx.onUpdate(tail);
+                },
+            });
+            if (run.error !== undefined) {
+                run.error = scriptErrorHint(run.error, tools.map((t) => t.name));
+            }
+            if (run.ok && run.store !== undefined) {
+                const problem = commitStore(ctx.session, run.store);
+                if (problem !== undefined) {
+                    run.ok = false;
+                    run.error = `store was not saved: ${problem}`;
+                }
+            }
+            const limitChars = Math.max(1000, Math.min(scriptOptions.maxOutputTokens * 4, maxResultChars - 500));
+            const formatted = formatCodemodeResult(run, limitChars, (text) => saveFullOutput(ctx, text));
+            const details = {
+                ok: run.ok,
+                elapsedMs: run.elapsedMs,
+                toolCalls: run.toolCalls,
+                timedOut: run.timedOut,
+                aborted: run.aborted,
+                strict: capability.strict,
+            };
+            if (formatted.fullOutputPath !== undefined)
+                details.fullOutputPath = formatted.fullOutputPath;
+            if (run.error !== undefined)
+                details.error = run.error;
+            return { content: formatted.text, isError: !run.ok, details };
+        },
+        renderCall(input, width) {
+            const lines = input.script.split("\n");
+            const shown = lines.slice(0, 6).map((line) => line.slice(0, Math.max(10, width)));
+            if (lines.length > shown.length)
+                shown.push(`… ${lines.length - shown.length} more lines`);
+            return shown;
+        },
+        renderResult(result, width, expanded) {
+            const lines = textOf(result.content).split("\n");
+            const clip = (line) => line.slice(0, Math.max(10, width));
+            if (expanded || lines.length <= 8)
+                return lines.map(clip);
+            return [clip(lines[0] ?? ""), `… ${lines.length - 6} lines`, ...lines.slice(-5).map(clip)];
+        },
+    };
+    return tool;
+}
+/**
+ * codemode 工具工厂：`codemode.mode` 生效值为 off → 不注册；`requireStrict` 而运行时不隔离网络
+ * → 不注册并 warning（预设随之回退到 default）。
+ */
+export function codemodeToolFactory(overrides = {}) {
+    return (ctx) => {
+        const explicit = ctx.config.codemode?.mode;
+        const mode = explicit ?? (ctx.config.tools?.preset === "codemode" ? "only" : "off");
+        if (mode === "off")
+            return undefined;
+        const availability = codemodeAvailability(ctx.config.codemode?.requireStrict, overrides.capability ?? detectSandboxCapability());
+        if (!availability.available) {
+            ctx.warn(availability.warning);
+            return undefined;
+        }
+        const registry = ctx.registry;
+        const options = {
+            capability: availability.capability,
+            exclusive: mode === "only",
+            listTools: () => registry
+                .list()
+                .filter((name) => name !== CODEMODE_TOOL_NAME)
+                .map((name) => registry.get(name))
+                .filter((t) => t !== undefined)
+                .map((t) => ({
+                tool: t,
+                textResult: (registry.sourceOf?.(t.name) ?? "builtin") === "builtin",
+            })),
+        };
+        const budget = ctx.config.codemode?.inlineBudget;
+        if (budget !== undefined)
+            options.inlineBudget = budget;
+        const maxChars = ctx.config.tools?.maxToolResultChars;
+        if (maxChars !== undefined)
+            options.maxResultChars = maxChars;
+        if (overrides.entry !== undefined)
+            options.entry = overrides.entry;
+        if (overrides.nodePath !== undefined)
+            options.nodePath = overrides.nodePath;
+        return createCodemodeTool(options);
+    };
+}

package/dist/compaction/branch-summary.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 分支摘要（设计 §8「branch_summary」、§1.2 branch-summary.ts）：`/tree` 离开分支时总结被离开的那段。[B2]
+ *
+ * 找新旧叶子的最深公共祖先 → 收集旧叶子到祖先之间（不含祖先）的上下文消息 → 从新到旧按预算截取 →
+ * 用同一模板（止于 Next Steps）生成摘要。调用方把结果作为 `branch_summary` 追加在新位置
+ * （parentId = 新叶子，fromId = 旧叶子）。
+ *
+ * [W3-C1b] 调用方给出续写前缀（离开前的完整转录）时同压缩一样走会话前缀续写：「只摘要最后 K 条」，
+ * 失败回落独立请求（第三波 §1.8）。
+ */
+import type { Usage } from "../ai/types.js";
+import { type EntryIndex } from "../session/tree.js";
+import type { AgentMessage, FileOpsDetails } from "../session/types.js";
+import { type SummarizerOptions } from "./summarize-tier.js";
+export declare const BRANCH_SUMMARY_BUDGET_TOKENS = 20000;
+export declare const BRANCH_SUMMARY_TEMPLATE = "The record above is a branch of the session that the user is now leaving to continue from an earlier point. Summarize what was tried on this branch so the agent can benefit from it, using EXACTLY this format:\n\n## Goal\n## Constraints & Preferences\n## Progress\n### Done\n### In Progress\n### Blocked\n## Key Decisions\n## Next Steps\n\nKeep it concise; preserve exact file paths and error messages.";
+export interface BranchSummaryPlan {
+    fromId: string;
+    commonAncestorId: string | null;
+    messages: AgentMessage[];
+}
+export interface BranchSummaryDraft {
+    fromId: string;
+    summary: string;
+    usage: Usage;
+    details: FileOpsDetails;
+}
+/** 旧叶子与新叶子在同一路径上（无被离开的内容）时返回 undefined。 */
+export declare function prepareBranchSummary(index: EntryIndex, oldLeafId: string | null, newLeafId: string | null, budgetTokens?: number): BranchSummaryPlan | undefined;
+export declare function runBranchSummary(plan: BranchSummaryPlan, options: SummarizerOptions): Promise<BranchSummaryDraft>;

package/dist/compaction/branch-summary.js

@@ -0,0 +1,79 @@
+/**
+ * 分支摘要（设计 §8「branch_summary」、§1.2 branch-summary.ts）：`/tree` 离开分支时总结被离开的那段。[B2]
+ *
+ * 找新旧叶子的最深公共祖先 → 收集旧叶子到祖先之间（不含祖先）的上下文消息 → 从新到旧按预算截取 →
+ * 用同一模板（止于 Next Steps）生成摘要。调用方把结果作为 `branch_summary` 追加在新位置
+ * （parentId = 新叶子，fromId = 旧叶子）。
+ *
+ * [W3-C1b] 调用方给出续写前缀（离开前的完整转录）时同压缩一样走会话前缀续写：「只摘要最后 K 条」，
+ * 失败回落独立请求（第三波 §1.8）。
+ */
+import { entryToMessage } from "../session/projection.js";
+import { commonAncestor, entriesBetween } from "../session/tree.js";
+import { estimateMessageTokens } from "./estimate.js";
+import { collectFileOps, createFileOps, fileOpsDetails, formatFileOps, serializeConversation, } from "./serialize.js";
+import { countLlmMessages, summarizeWithFallback, } from "./summarize-tier.js";
+export const BRANCH_SUMMARY_BUDGET_TOKENS = 20_000;
+export const BRANCH_SUMMARY_TEMPLATE = `The record above is a branch of the session that the user is now leaving to continue from an earlier point. Summarize what was tried on this branch so the agent can benefit from it, using EXACTLY this format:
+
+## Goal
+## Constraints & Preferences
+## Progress
+### Done
+### In Progress
+### Blocked
+## Key Decisions
+## Next Steps
+
+Keep it concise; preserve exact file paths and error messages.`;
+/** 旧叶子与新叶子在同一路径上（无被离开的内容）时返回 undefined。 */
+export function prepareBranchSummary(index, oldLeafId, newLeafId, budgetTokens = BRANCH_SUMMARY_BUDGET_TOKENS) {
+    if (oldLeafId === null)
+        return undefined;
+    const ancestor = commonAncestor(index, oldLeafId, newLeafId);
+    const abandoned = entriesBetween(index, ancestor, oldLeafId);
+    const all = [];
+    for (const entry of abandoned) {
+        const message = entryToMessage(entry);
+        if (message !== undefined && message.role !== "system")
+            all.push(message);
+    }
+    if (all.length === 0)
+        return undefined;
+    const picked = [];
+    let used = 0;
+    for (let i = all.length - 1; i >= 0; i--) {
+        const message = all[i];
+        const cost = estimateMessageTokens(message);
+        if (picked.length > 0 && used + cost > budgetTokens)
+            break;
+        picked.unshift(message);
+        used += cost;
+    }
+    return { fromId: oldLeafId, commonAncestorId: ancestor, messages: picked };
+}
+export async function runBranchSummary(plan, options) {
+    const prefix = options.continuation?.prefix;
+    const total = prefix === undefined ? 0 : prefix.messages.filter((m) => m.role !== "system").length;
+    const from = Math.max(0, total - countLlmMessages(plan.messages));
+    const { text, usage } = await summarizeWithFallback(options, {
+        from,
+        keepFrom: { index: total, excerpt: "" },
+        instruction: `Messages ${from + 1}–${total} are the branch being left.\n\n${BRANCH_SUMMARY_TEMPLATE}`,
+    }, () => {
+        const parts = [`<conversation>\n${serializeConversation(plan.messages)}\n</conversation>`];
+        parts.push(BRANCH_SUMMARY_TEMPLATE);
+        if (options.customInstructions !== undefined && options.customInstructions.trim() !== "") {
+            parts.push(`Additional instructions:\n${options.customInstructions.trim()}`);
+        }
+        return parts.join("\n\n");
+    });
+    const details = fileOpsDetails(collectFileOps(plan.messages, createFileOps()));
+    const files = formatFileOps(details);
+    return {
+        fromId: plan.fromId,
+        summary: files === "" ? text : `${text}\n\n${files}`,
+        usage,
+        details,
+    };
+}

package/dist/compaction/breaker.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 压缩熔断（设计 §9「熔断」）。[B2]
+ *
+ * - 无 `contextWindow` 或配置关闭 → 自动压缩关闭（手动 /compact 仍可用）。
+ * - 同一 run 内档二（摘要）≤ 1 次（`startRun()` 重置计数）。
+ * - 连续两次摘要失败 → 跳闸，关闭自动压缩直到 `reset()`（例如用户手动压缩成功）。
+ * - 溢出恢复：压缩后估算仍 > 0.8 × window → 不重试。
+ */
+export declare const MAX_SUMMARIES_PER_RUN = 1;
+export declare const MAX_CONSECUTIVE_FAILURES = 2;
+export declare const RETRY_AFTER_COMPACTION_RATIO = 0.8;
+export type BreakerBlockReason = "disabled" | "no_window" | "tripped" | "run_limit";
+export declare class CompactionBreaker {
+    private summariesThisRun;
+    private consecutiveFailures;
+    private enabled;
+    private contextWindow;
+    constructor(enabled: boolean, contextWindow: number | undefined);
+    configure(enabled: boolean, contextWindow: number | undefined): void;
+    get tripped(): boolean;
+    /** 自动压缩整体是否开启（不看本 run 计数）。 */
+    get autoEnabled(): boolean;
+    startRun(): void;
+    /** 自动档二能否执行；不能则给出原因。 */
+    blockReason(): BreakerBlockReason | undefined;
+    canSummarize(): boolean;
+    recordSummary(success: boolean): void;
+    /** 手动压缩成功等场景：清零失败计数。 */
+    reset(): void;
+    /** 溢出恢复后是否值得重试。 */
+    shouldRetryAfterCompaction(tokensAfter: number): boolean;
+}

package/dist/compaction/breaker.js

@@ -0,0 +1,65 @@
+/**
+ * 压缩熔断（设计 §9「熔断」）。[B2]
+ *
+ * - 无 `contextWindow` 或配置关闭 → 自动压缩关闭（手动 /compact 仍可用）。
+ * - 同一 run 内档二（摘要）≤ 1 次（`startRun()` 重置计数）。
+ * - 连续两次摘要失败 → 跳闸，关闭自动压缩直到 `reset()`（例如用户手动压缩成功）。
+ * - 溢出恢复：压缩后估算仍 > 0.8 × window → 不重试。
+ */
+export const MAX_SUMMARIES_PER_RUN = 1;
+export const MAX_CONSECUTIVE_FAILURES = 2;
+export const RETRY_AFTER_COMPACTION_RATIO = 0.8;
+export class CompactionBreaker {
+    summariesThisRun = 0;
+    consecutiveFailures = 0;
+    enabled;
+    contextWindow;
+    constructor(enabled, contextWindow) {
+        this.enabled = enabled;
+        this.contextWindow = contextWindow;
+    }
+    configure(enabled, contextWindow) {
+        this.enabled = enabled;
+        this.contextWindow = contextWindow;
+    }
+    get tripped() {
+        return this.consecutiveFailures >= MAX_CONSECUTIVE_FAILURES;
+    }
+    /** 自动压缩整体是否开启（不看本 run 计数）。 */
+    get autoEnabled() {
+        return this.enabled && this.contextWindow !== undefined && !this.tripped;
+    }
+    startRun() {
+        this.summariesThisRun = 0;
+    }
+    /** 自动档二能否执行；不能则给出原因。 */
+    blockReason() {
+        if (!this.enabled)
+            return "disabled";
+        if (this.contextWindow === undefined)
+            return "no_window";
+        if (this.tripped)
+            return "tripped";
+        if (this.summariesThisRun >= MAX_SUMMARIES_PER_RUN)
+            return "run_limit";
+        return undefined;
+    }
+    canSummarize() {
+        return this.blockReason() === undefined;
+    }
+    recordSummary(success) {
+        this.summariesThisRun++;
+        this.consecutiveFailures = success ? 0 : this.consecutiveFailures + 1;
+    }
+    /** 手动压缩成功等场景：清零失败计数。 */
+    reset() {
+        this.consecutiveFailures = 0;
+        this.summariesThisRun = 0;
+    }
+    /** 溢出恢复后是否值得重试。 */
+    shouldRetryAfterCompaction(tokensAfter) {
+        if (this.contextWindow === undefined)
+            return false;
+        return tokensAfter <= RETRY_AFTER_COMPACTION_RATIO * this.contextWindow;
+    }
+}