@armadra/agent 0.4.0 → 0.5.0

package/dist/agent/reminders.js

@@ -0,0 +1,327 @@
+/**
+ * 统一提醒通道 `ama.reminder`（docs/wave5-plan.md §8.3 H3，D29）。[W5-H2]
+ *
+ * 以 `SessionExtension` 实现，两个投递点，都只追加在尾部（design §9.1，缓存前缀不动）：
+ * - **新提示**：`beforePrompts` 追加一条 `custom_message{customType:"ama.reminder", display:false}`；
+ * - **run 进行中**：在 agent_start 时以本 run 的 signal 登记批次尾部来源（tool-runner.ts
+ *   `setBatchSuffixSource`），每个工具批次结束时把到期提醒追加在本批最后一条结果末尾
+ *   （`<system-reminder>` 包起来）。不用 steer 队列：那会占用户的投递位、Esc 时还会被回填进编辑器。
+ *
+ * 提醒种类（`reminders.*` 逐项可关，缺省全开）：
+ * 1. `todo`：todo 工具在活动集、清单有未完成项、连续 `todo.reminder`（缺省 10，0 关闭）次助手回复
+ *    没更新清单（`ama.todo` 条目）→ 复述清单，计数清零；
+ * 2. `fileChanges`：本会话 read / edit / write 过的文件 mtime 或大小变了（不是本 Agent 的编辑或 bash
+ *    改的：这些之后重新取基线）→ 列出 ≤ 10 个，附 `git diff --stat`（拿得到时）；
+ * 3. `contextPressure`：上下文估算（compaction/estimate.ts 的口径）到窗口 70% / 85% 各一次，
+ *    压缩后回落再重新计；
+ * 4. `budget`：limits 的回合或费用用掉 ≥ 80%（剩余 < 20%）时每次运行各一次；
+ * 5. 后台命令退出（不可关）：`bash{background}` 的任务退出且模型还没经 wait / output 看到 →
+ *    「后台命令 bgN 已退出（码 N）」。
+ *
+ * 后台任务表的生命周期也挂在这里：任务事件转成 `background_job`，会话 dispose 时回收进程树。
+ * task 子会话（depth > 0）只装后台任务部分。
+ */
+import { execFileSync } from "node:child_process";
+import { statSync } from "node:fs";
+import { resolve } from "node:path";
+import { estimateProjectedTokens } from "../compaction/estimate.js";
+import { buildProjection } from "../session/projection.js";
+import { disposeSessionJobs, jobsForSession } from "../tools/background-jobs.js";
+import { TODO_CUSTOM_TYPE, parseTodoState, renderTodoList } from "../tools/todo.js";
+import { budgetOf } from "./limits.js";
+import { setBatchSuffixSource } from "./tool-runner.js";
+export const REMINDER_CUSTOM_TYPE = "ama.reminder";
+export const DEFAULT_TODO_REMINDER_TURNS = 10;
+export const CONTEXT_REMINDER_RATIOS = [0.7, 0.85];
+export const BUDGET_REMINDER_RATIO = 0.8;
+export const MAX_CHANGED_FILES = 10;
+/** config → 提醒设置（`reminders.*` 与 `todo.reminder`）。 */
+export function remindersSettings(config) {
+    const settings = {};
+    if (config.reminders !== undefined)
+        settings.reminders = config.reminders;
+    if (config.todo?.reminder !== undefined)
+        settings.todoEvery = config.todo.reminder;
+    return settings;
+}
+const FILE_TOOLS = new Set(["read", "edit", "write"]);
+function defaultStat(path) {
+    try {
+        const info = statSync(path);
+        return { mtimeMs: info.mtimeMs, size: info.size };
+    }
+    catch {
+        return undefined;
+    }
+}
+function defaultDiffStat(cwd, files) {
+    try {
+        const out = execFileSync("git", ["diff", "--stat", "--", ...files], {
+            cwd,
+            encoding: "utf8",
+            timeout: 2000,
+            stdio: ["ignore", "pipe", "ignore"],
+            windowsHide: true,
+        }).trim();
+        return out === "" ? undefined : out;
+    }
+    catch {
+        return undefined;
+    }
+}
+function lastTodo(branch) {
+    for (let i = branch.length - 1; i >= 0; i--) {
+        const entry = branch[i];
+        if (entry?.type === "custom" && entry.customType === TODO_CUSTOM_TYPE)
+            return parseTodoState(entry.data);
+    }
+    return parseTodoState(undefined);
+}
+function wrap(lines) {
+    return `<system-reminder>\n${lines.join("\n\n")}\n</system-reminder>`;
+}
+function argPath(args) {
+    if (typeof args !== "object" || args === null)
+        return undefined;
+    const path = args.path;
+    return typeof path === "string" && path !== "" ? path : undefined;
+}
+class Reminders {
+    core;
+    on;
+    todoEvery;
+    stat;
+    diffStat;
+    /** 自上次更新 todo 以来的助手回复数。 */
+    sinceTodo = 0;
+    /** 已提醒过的上下文档位（压缩后回落再清）。 */
+    contextFired = new Set();
+    /** 本次运行已提醒的预算类别。 */
+    budgetFired = new Set();
+    /** 文件基线：绝对路径 → mtime / 大小。 */
+    baseline = new Map();
+    /** toolCallId → 文件工具的绝对路径。 */
+    pendingPaths = new Map();
+    constructor(core, settings, deps) {
+        this.core = core;
+        const r = settings.reminders ?? {};
+        this.on = {
+            todo: r.todo ?? true,
+            fileChanges: r.fileChanges ?? true,
+            contextPressure: r.contextPressure ?? true,
+            budget: r.budget ?? true,
+        };
+        this.todoEvery = settings.todoEvery ?? DEFAULT_TODO_REMINDER_TURNS;
+        this.stat = deps.stat ?? defaultStat;
+        this.diffStat = deps.diffStat ?? defaultDiffStat;
+    }
+    onEvent(event) {
+        switch (event.type) {
+            case "before_agent_start":
+                this.budgetFired.clear();
+                return;
+            case "agent_start": {
+                const signal = this.core.agent.signal;
+                if (signal !== undefined)
+                    setBatchSuffixSource(signal, () => this.collect(true));
+                return;
+            }
+            case "message_end":
+                if (event.message.role === "assistant" &&
+                    event.message.stopReason !== "error" &&
+                    event.message.stopReason !== "aborted")
+                    this.sinceTodo++;
+                return;
+            case "entry_appended":
+                if (event.entry.type === "custom" && event.entry.customType === TODO_CUSTOM_TYPE)
+                    this.sinceTodo = 0;
+                return;
+            case "compaction_end":
+                this.rearmContext();
+                return;
+            case "tool_execution_start": {
+                if (event.parentToolCallId !== undefined || !FILE_TOOLS.has(event.toolName))
+                    return;
+                const path = argPath(event.args);
+                if (path !== undefined)
+                    this.pendingPaths.set(event.toolCallId, resolve(this.core.cwd, path));
+                return;
+            }
+            case "tool_execution_end": {
+                const path = this.pendingPaths.get(event.toolCallId);
+                this.pendingPaths.delete(event.toolCallId);
+                if (path !== undefined && !event.isError)
+                    this.baseline.set(path, this.stat(path));
+                // 本 Agent 自己的 bash 改动模型知道：重新取基线，只报其余来源的改动
+                else if (event.toolName === "bash" && event.parentToolCallId === undefined)
+                    this.rebaseline();
+                return;
+            }
+            default:
+                return;
+        }
+    }
+    /** 到期提醒的正文（没有返回 undefined）；`inRun` = 工具批次尾部（预算提醒只在 run 中有意义）。 */
+    collect(inRun) {
+        const lines = [];
+        const jobs = this.jobLines();
+        const todo = this.todoLine();
+        const files = this.fileLine();
+        const context = this.contextLine();
+        const budget = inRun ? this.budgetLine() : undefined;
+        for (const line of [jobs, todo, files, context, budget])
+            if (line !== undefined)
+                lines.push(line);
+        return lines.length === 0 ? undefined : wrap(lines);
+    }
+    jobLines() {
+        const exited = jobsForSession(this.core.manager.id).takeExited();
+        if (exited.length === 0)
+            return undefined;
+        return exited.map((job) => jobExitText(job)).join("\n");
+    }
+    todoLine() {
+        if (!this.on.todo || this.todoEvery <= 0 || this.sinceTodo < this.todoEvery)
+            return undefined;
+        if (this.core.activeTool("todo") === undefined)
+            return undefined;
+        const { items } = lastTodo(this.core.manager.branch());
+        if (!items.some((item) => item.status !== "done"))
+            return undefined;
+        const turns = this.sinceTodo;
+        this.sinceTodo = 0;
+        return (`The todo list has not been updated in the last ${turns} replies and still has open items:\n` +
+            `${renderTodoList(items).join("\n")}\n` +
+            "If you made progress, update it (todo update); otherwise keep going. Do not mention this reminder.");
+    }
+    fileLine() {
+        if (!this.on.fileChanges || this.baseline.size === 0)
+            return undefined;
+        const changed = [];
+        for (const [path, before] of this.baseline) {
+            const now = this.stat(path);
+            if (before?.mtimeMs === now?.mtimeMs && before?.size === now?.size)
+                continue;
+            this.baseline.set(path, now);
+            changed.push(now === undefined ? `${path} (deleted)` : path);
+        }
+        if (changed.length === 0)
+            return undefined;
+        const shown = changed.slice(0, MAX_CHANGED_FILES);
+        const more = changed.length > shown.length ? `\n…and ${changed.length - shown.length} more` : "";
+        const existing = shown.filter((p) => !p.endsWith(" (deleted)"));
+        const stat = existing.length > 0 ? this.diffStat(this.core.cwd, existing) : undefined;
+        return ("These files changed outside your own edits since you last read them; re-read before editing:\n" +
+            `${shown.map((p) => `- ${p}`).join("\n")}${more}` +
+            (stat === undefined ? "" : `\ngit diff --stat:\n${stat}`));
+    }
+    contextLine() {
+        if (!this.on.contextPressure)
+            return undefined;
+        const window = this.core.model().contextWindow;
+        if (window === undefined || window <= 0)
+            return undefined;
+        const ratio = this.usedTokens() / window;
+        let fired;
+        for (const level of CONTEXT_REMINDER_RATIOS)
+            if (ratio >= level && !this.contextFired.has(level))
+                fired = level;
+        if (fired === undefined)
+            return undefined;
+        for (const level of CONTEXT_REMINDER_RATIOS)
+            if (level <= fired)
+                this.contextFired.add(level);
+        const pct = Math.round(ratio * 100);
+        return fired >= 0.85
+            ? `Context is ${pct}% full. Finish the current step soon and write down progress and next steps (todo or a notes file); older history will be compacted.`
+            : `Context is ${pct}% full. Prefer targeted reads and keep notes of key findings; older history will be compacted when it fills up.`;
+    }
+    budgetLine() {
+        if (!this.on.budget)
+            return undefined;
+        const budget = budgetOf(this.core);
+        if (budget === undefined)
+            return undefined;
+        const parts = [];
+        const { maxTurns, maxCostUsd } = budget;
+        if (maxTurns !== undefined &&
+            !this.budgetFired.has("turns") &&
+            budget.turns >= maxTurns * BUDGET_REMINDER_RATIO) {
+            this.budgetFired.add("turns");
+            parts.push(`${budget.turns} of ${maxTurns} turns`);
+        }
+        if (maxCostUsd !== undefined &&
+            !this.budgetFired.has("cost") &&
+            budget.spentUsd >= maxCostUsd * BUDGET_REMINDER_RATIO) {
+            this.budgetFired.add("cost");
+            parts.push(`$${budget.spentUsd.toFixed(2)} of the $${maxCostUsd.toFixed(2)} budget`);
+        }
+        if (parts.length === 0)
+            return undefined;
+        return `This run has used ${parts.join(" and ")}. Wrap up: finish the most important part and report what is left.`;
+    }
+    usedTokens() {
+        const branch = this.core.manager.branch();
+        return estimateProjectedTokens(buildProjection(branch).items, branch).tokens;
+    }
+    rearmContext() {
+        const window = this.core.model().contextWindow;
+        if (window === undefined || window <= 0)
+            return;
+        const ratio = this.usedTokens() / window;
+        for (const level of CONTEXT_REMINDER_RATIOS)
+            if (ratio < level)
+                this.contextFired.delete(level);
+    }
+    rebaseline() {
+        for (const path of this.baseline.keys())
+            this.baseline.set(path, this.stat(path));
+    }
+}
+export function jobExitText(job) {
+    const how = job.status === "stopped" ? "was stopped" : `exited with code ${job.exitCode ?? "unknown"}`;
+    return `Background job ${job.id} (\`${job.command}\`) ${how}; output: ${job.outputPath} (bash {"job":"${job.id}","action":"output"}).`;
+}
+export function reminderMessage(text) {
+    return {
+        role: "custom",
+        customType: REMINDER_CUSTOM_TYPE,
+        content: text,
+        display: false,
+        timestamp: Date.now(),
+    };
+}
+/**
+ * 提醒扩展。主会话：全部提醒 + 后台任务生命周期；子会话：只管后台任务（事件与回收）。
+ */
+export function createRemindersExtension(core, settings = {}, deps = {}) {
+    const sessionId = core.manager.id;
+    const jobs = jobsForSession(sessionId);
+    const offJobs = jobs.onChange(({ phase, job }) => {
+        core.emit({
+            type: "background_job",
+            jobId: job.id,
+            phase,
+            command: job.command,
+            ...(job.pid === undefined ? {} : { pid: job.pid }),
+            outputPath: job.outputPath,
+            ...(phase === "started" ? {} : { exitCode: job.exitCode ?? null }),
+        });
+    });
+    const dispose = () => {
+        offJobs();
+        void disposeSessionJobs(sessionId);
+    };
+    if (core.depth > 0)
+        return { id: "reminders", dispose };
+    const reminders = new Reminders(core, settings, deps);
+    return {
+        id: "reminders",
+        onEvent: (event) => reminders.onEvent(event),
+        beforePrompts() {
+            const text = reminders.collect(false);
+            return text === undefined ? [] : [reminderMessage(text)];
+        },
+        dispose,
+    };
+}

package/dist/agent/session-cache.d.ts

@@ -81,6 +81,11 @@ export declare class SessionCacheController {
         tokens?: number | undefined;
         window?: number | undefined;
     }): SessionCacheStats;
+    /**
+     * [W5-H1] 缓存是否已冷（wave5 §8.2 C3）：上一次请求（含保温）距今超过 TTL（目录无承诺时按隐式
+     * 10 分钟）。只对 `reported` 端点判断；`silent` / `unknown` 返回 false，档一退化为只按阈值。
+     */
+    isCold(): boolean;
     /**
      * 摘要续写的前缀（第三波 §1.8）：当前转录按回合同样的方式转换，且上一次 turn 请求的消息
      * 逐条是它的前缀（缓存必然命中）、加上摘要输出放得进窗口；否则 undefined（走独立请求）。

package/dist/agent/session-cache.js

@@ -14,6 +14,7 @@ import { fingerprintContext } from "../ai/cache/fingerprint.js";
 import { DEFAULT_MIN_CACHE_TOKENS, IMPLICIT_CACHE_TTL_MS, detectMiss } from "../ai/cache/miss.js";
 import { endpointKey, sharedCacheReporting, } from "../ai/cache/reporting.js";
 import { CacheWarmer, replayBlocker } from "../ai/cache/warmer.js";
+import { estimateTextTokens } from "../compaction/estimate.js";
 import { SUMMARY_MAX_TOKENS } from "../compaction/summarize-tier.js";
 import { convertToLlm } from "./transform.js";
 export const DEFAULT_CACHE_SETTINGS = Object.freeze({
@@ -297,6 +298,21 @@ export class SessionCacheController {
         }
         return stats;
     }
+    /**
+     * [W5-H1] 缓存是否已冷（wave5 §8.2 C3）：上一次请求（含保温）距今超过 TTL（目录无承诺时按隐式
+     * 10 分钟）。只对 `reported` 端点判断；`silent` / `unknown` 返回 false，档一退化为只按阈值。
+     */
+    isCold() {
+        const prev = this.prev;
+        if (prev === undefined || this.disposed)
+            return false;
+        const model = this.core.model();
+        const endpoint = endpointKey({ model, baseUrl: model.baseUrl ?? "" });
+        if (this.tracker.get(endpoint, model.compat?.cacheReporting) !== "reported")
+            return false;
+        const ttl = cacheTtlMs(this.modelOf(prev), prev.options.cacheRetention);
+        return this.now() - prev.at > (ttl ?? IMPLICIT_CACHE_TTL_MS);
+    }
     /**
      * 摘要续写的前缀（第三波 §1.8）：当前转录按回合同样的方式转换，且上一次 turn 请求的消息
      * 逐条是它的前缀（缓存必然命中）、加上摘要输出放得进窗口；否则 undefined（走独立请求）。
@@ -320,7 +336,7 @@ export class SessionCacheController {
         for (let i = 0; i < prev.length; i++)
             if (JSON.stringify(prev[i]) !== JSON.stringify(messages[i]))
                 return undefined;
-        const extra = Math.ceil(JSON.stringify(messages.slice(prev.length)).length / 4);
+        const extra = estimateTextTokens(JSON.stringify(messages.slice(prev.length)));
         const window = model.contextWindow;
         if (window !== undefined && record.promptTokens + extra + SUMMARY_MAX_TOKENS + 2048 > window)
             return undefined;

package/dist/agent/session-classifier.d.ts

@@ -15,4 +15,4 @@ export declare const CLASSIFY_USAGE_KIND = "permission_classify";
 export declare function latestUserText(core: SessionCore): string | undefined;
 export declare function createSessionClassifier(core: SessionCore): PermissionClassifier;
 /** gateToolCall 用：组装分类请求。 */
-export declare function classifierRequest(core: SessionCore, toolName: string, input: unknown, projectRoot: string | undefined): ClassifierRequest;
+export declare function classifierRequest(core: SessionCore, toolName: string, input: unknown, projectRoot: string | undefined, sandbox?: ClassifierRequest["sandbox"]): ClassifierRequest;

package/dist/agent/session-classifier.js

@@ -89,13 +89,15 @@ export function createSessionClassifier(core) {
     });
 }
 /** gateToolCall 用：组装分类请求。 */
-export function classifierRequest(core, toolName, input, projectRoot) {
+export function classifierRequest(core, toolName, input, projectRoot, sandbox) {
     const request = {
         toolName,
         input,
         cwd: core.cwd,
         projectRoot: projectRoot ?? core.cwd,
     };
+    if (sandbox !== undefined)
+        request.sandbox = sandbox;
     const user = latestUserText(core);
     if (user !== undefined)
         request.userMessage = user;

package/dist/agent/session-compaction.d.ts

@@ -1,10 +1,17 @@
 /**
  * 会话侧的压缩调度（设计 §9）。[B2]
  *
- * - 阈值检查（新提示前、`prepareNextTurn` 里）：估算 > 0.7 ×（窗口 − 预留）→ 档一裁剪；仍 > 窗口 − 预留
- *   且熔断允许 → 档二摘要（trigger `threshold`）。
+ * - 阈值检查（新提示前、`prepareNextTurn` 里）：估算 > 0.7 ×（窗口 − 预留）→ 档一裁剪（[W5-H1] 按工具
+ *   结果新旧计边界，可省 ≥ clearAtLeast 才动，一次清到 0.5 ×）；仍 > 窗口 − 预留且熔断允许 → 档二摘要
+ *   （trigger `threshold`）。缓存已冷（上次请求距今超过 TTL，只认 reported 端点）时未到 0.7 也裁，
+ *   且一次换掉全部候选。
+ * - 自检（[W5-H1] C8）：摘要缺 `## Goal` 重试一次再回落；自动压缩后估算不比压缩前小判失败，不写条目。
+ * - 回注（[W5-H1] C6 / C13）：摘要末尾接 `<post-compact-state>` 块（todo、计划、已加载 Skill、最近
+ *   文件、转录与 outputs 路径，不含文件正文；理由见 compaction/post-compact.ts），再跑 PostCompact
+ *   Hook，其 additionalContext 以 `ama.hook_context` 追加在末尾。
+ * - 熔断（[W5-H1] C5）：连续 3 次失败或连续 3 次快速回填跳闸；固定前缀超预算不再尝试；都只告警一次。
  * - 溢出恢复（会话 run 结束后，失败尝试已用 context_edit 剔除）：PreCompact Hook → 档二摘要（trigger
- *   `overflow`，不受「每 run 一次」限制但受跳闸限制）→ 压缩后估算 ≤ 0.8 × 窗口才重试。
+ *   `overflow`，受跳闸限制）→ 压缩后估算 ≤ 0.8 × 窗口才重试。
  * - 手动 `/compact`：PreCompact（trigger `manual`）→ 摘要；成功清零熔断。
  * PreCompact 的 `decision: "block"` 取消本次压缩；`customInstructions` 追加到摘要提示。
  * [W3-C1b] 阈值 / 手动压缩与分支摘要优先走会话前缀续写（缓存控制器给前缀），溢出恢复不走
@@ -12,6 +19,7 @@
  */
 import { CompactionBreaker } from "../compaction/breaker.js";
 import { type ContextEstimate } from "../compaction/estimate.js";
+import { type PrunePolicy } from "../compaction/prune-tier.js";
 import type { BranchSummaryEntry } from "../session/types.js";
 import type { SessionCore } from "./session-core.js";
 import type { CompactionResult, CompactionSettings } from "./types.js";
@@ -23,6 +31,9 @@ export declare class CompactionController {
     settings: CompactionSettings;
     private readonly core;
     private compacting;
+    private warnedReason;
+    /** [W5-H1] config `compaction.prune / pruneExclude`（组装根把整段 config.compaction 展开传入）。 */
+    private readonly pruneConfig;
     constructor(core: SessionCore, settings?: Partial<CompactionSettings>);
     get isCompacting(): boolean;
     /** 模型或开关变化后调用。 */
@@ -33,16 +44,34 @@ export declare class CompactionController {
     private keepRecent;
     /** 摘要请求的公共选项；`continuation` 时附上会话前缀续写的材料。 */
     private summarizer;
-    /** 档一；返回是否裁剪了内容。 */
-    prune(): boolean;
+    /** 档一参数；无窗口时 undefined。 */
+    prunePolicy(): PrunePolicy | undefined;
+    /**
+     * 档一；`need` = 清到目标还要省多少（undefined = 全部候选）。返回省下的 token 估算（0 = 未裁）。
+     */
+    prune(policy: PrunePolicy, need: number | undefined): number;
     /** 阈值检查（档一 → 档二）。失败只记录，不打断 run。 */
     checkThreshold(signal: AbortSignal): Promise<void>;
+    /** 回注块（todo、计划、已加载 Skill、最近文件、转录与 outputs 路径；不含文件正文）。 */
+    private postCompactBlock;
+    /**
+     * PostCompact Hook（C13，不可阻止）：`additionalContext` 作为 `ama.hook_context` 追加在末尾。
+     * 返回最终的压缩后估算。
+     */
+    private runPostCompactHook;
+    /** 假设追加了这条 compaction 之后的估算（按投影全量重估）。 */
+    private projectedTokens;
+    /** 固定前缀（system 节 + 工具表）的估算：摘要压不掉这部分。 */
+    private fixedPrefixTokens;
+    /** 熔断挡住自动摘要时告警（同一原因只报一次）。 */
+    private warnBlocked;
     /** 溢出恢复：返回是否应以新 run 重试。 */
     recoverOverflow(signal: AbortSignal): Promise<{
         retry: boolean;
         warning?: string;
     }>;
-    compactManual(instructions: string | undefined, signal: AbortSignal): Promise<CompactionResult>;
+    /** `cutAt`：[RW-B] 以该条目为切点（「摘要到这里」），不按保留预算找切点。 */
+    compactManual(instructions: string | undefined, signal: AbortSignal, cutAt?: string): Promise<CompactionResult>;
     /** `/tree` 离开分支：换叶子，并为离开的那段写 branch_summary（挂在新叶子下）。 */
     leaveBranch(targetId: string | null, instructions: string | undefined, signal: AbortSignal): Promise<BranchSummaryEntry | undefined>;
     private summarize;