@armadra/agent 0.4.0 → 0.5.0

package/dist/agent/limits.js

@@ -0,0 +1,127 @@
+/**
+ * 会话预算（docs/wave5-plan.md §8.3 H2，D29）：`--max-turns` / `--max-cost` / config `limits.*`。[W5-H2]
+ *
+ * 以 `SessionExtension` 实现（只装主会话；task 子会话有自己的 maxTurns）：
+ * - **回合**：每个会话周期（`before_agent_start` 起）累计助手回复（error / aborted 不算）；第 N 次回复
+ *   带工具调用时 `requestStop`——本轮工具照常执行，之后结束 run（与原 `--max-turns` 语义一致：
+ *   「一次模型请求加其工具执行算一轮」；第 N 次回复不再调用工具时自然结束，不算到限）。
+ * - **费用**：同样按会话周期累计助手回复的 `usage.cost.total` 与子 Agent `subagent_end` 的用量
+ *   （模型无价格时为 0，不会到限）；某次回复后累计 ≥ 上限且还要调用工具 → 同样结束 run。本周期内
+ *   之后的 turn 请求（重试、Stop Hook 续跑等）在发出前被拦下（`wrapStream`，返回 `limit_reached:`
+ *   开头的错误回复，不重试、不计费）。两项都是「一次运行」（config 说明与 `--max-cost` 的口径）。
+ * - 到限：发 `limit_reached{kind, value, limit}`（每周期每类一次），`agent_settled{warning:"limit_reached"}`，
+ *   `-p` 以退出码 8 结束（print-mode.ts）。交互与 RPC 同样生效。
+ * - `budgetOf(core)` 给提醒通道（reminders.ts）读当前用量（预算剩余 < 20% 提醒）。
+ */
+import { runEventStream } from "../ai/event-stream.js";
+import { ZERO_USAGE } from "./loop.js";
+import { LIMIT_ERROR_PREFIX, noteSettleWarning } from "./session-run.js";
+export const LIMIT_REACHED = "limit_reached";
+export { LIMIT_ERROR_PREFIX };
+const budgets = new WeakMap();
+/** 当前会话的预算状态（未设上限 / 未装扩展时 undefined）。 */
+export function budgetOf(core) {
+    return budgets.get(core);
+}
+/** 合并：`--max-turns` / `--max-cost` 覆盖 config `limits.*`；全空返回 undefined。 */
+export function resolveLimits(config, overrides = {}) {
+    const limits = { ...config };
+    if (overrides.maxTurns !== undefined)
+        limits.maxTurns = overrides.maxTurns;
+    if (overrides.maxCostUsd !== undefined)
+        limits.maxCostUsd = overrides.maxCostUsd;
+    if (limits.maxTurns === undefined)
+        delete limits.maxTurns;
+    if (limits.maxCostUsd === undefined)
+        delete limits.maxCostUsd;
+    return Object.keys(limits).length > 0 ? limits : undefined;
+}
+export function formatUsd(value) {
+    return `$${value < 1 ? value.toFixed(4) : value.toFixed(2)}`;
+}
+function hasToolCalls(message) {
+    return message.content.some((block) => block.type === "toolCall");
+}
+function blockedReply(model, text) {
+    return {
+        role: "assistant",
+        content: [],
+        api: model.api,
+        provider: model.provider,
+        model: model.id,
+        usage: { ...ZERO_USAGE },
+        stopReason: "error",
+        errorMessage: text,
+        timestamp: Date.now(),
+    };
+}
+export function createLimitsExtension(core, limits) {
+    if (limits === undefined || (limits.maxTurns === undefined && limits.maxCostUsd === undefined))
+        return undefined;
+    const state = { turns: 0, spentUsd: 0 };
+    if (limits.maxTurns !== undefined)
+        state.maxTurns = limits.maxTurns;
+    if (limits.maxCostUsd !== undefined)
+        state.maxCostUsd = limits.maxCostUsd;
+    budgets.set(core, state);
+    /** 本周期已报过的类别（每周期每类只报一次）。 */
+    const reported = new Set();
+    const reach = (kind, value, limit) => {
+        if (reported.has(kind))
+            return;
+        reported.add(kind);
+        core.emit({ type: "limit_reached", kind, value, limit });
+        noteSettleWarning(core, LIMIT_REACHED);
+    };
+    const overCost = () => state.maxCostUsd !== undefined && state.spentUsd >= state.maxCostUsd;
+    const onAssistant = (message) => {
+        state.spentUsd += message.usage.cost?.total ?? 0;
+        if (message.stopReason === "error" || message.stopReason === "aborted")
+            return;
+        state.turns++;
+        if (!hasToolCalls(message))
+            return;
+        if (state.maxTurns !== undefined && state.turns >= state.maxTurns) {
+            reach("turns", state.turns, state.maxTurns);
+            core.requestStop(undefined);
+        }
+        if (overCost()) {
+            reach("cost", state.spentUsd, state.maxCostUsd);
+            core.requestStop(undefined);
+        }
+    };
+    return {
+        id: "limits",
+        onEvent(event) {
+            if (event.type === "before_agent_start") {
+                state.turns = 0;
+                state.spentUsd = 0;
+                reported.clear();
+            }
+            else if (event.type === "message_end" && event.message.role === "assistant") {
+                onAssistant(event.message);
+            }
+            else if (event.type === "subagent_end") {
+                state.spentUsd += event.usage?.cost?.total ?? 0;
+            }
+        },
+        wrapStream(stream) {
+            return (model, context, options) => {
+                if ((options.purpose ?? "turn") !== "turn" || !overCost()) {
+                    return stream(model, context, options);
+                }
+                const limit = state.maxCostUsd;
+                reach("cost", state.spentUsd, limit);
+                const text = `${LIMIT_ERROR_PREFIX} session cost ${formatUsd(state.spentUsd)} has reached the ` +
+                    `${formatUsd(limit)} budget (limits.maxCostUsd / --max-cost); no request was sent`;
+                const reply = blockedReply(model, text);
+                return runEventStream(() => reply, async (out) => {
+                    out.push({ type: "error", reason: "error", message: reply });
+                });
+            };
+        },
+        dispose() {
+            budgets.delete(core);
+        },
+    };
+}

package/dist/agent/loop-guard.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 重复调用检测（docs/wave5-plan.md §8.3 H1，D29）。[W5-H2]
+ *
+ * - 指纹 = `sha256(工具名 + 规范化 JSON 参数)`（对象键排序，数组保持顺序）；同一 run 内**累计**计数。
+ * - 第 `LOOP_REMIND_AT`（3）次起：照常执行，在该次 toolResult 末尾追加提醒（只改这条结果，缓存安全）。
+ * - 第 `LOOP_STOP_AT`（5）次：不执行，给错误结果并结束本 run，`agent_settled{warning:"repeated_tool_call"}`。
+ * - 豁免：`annotations.pollable` 的工具（`task_ctl`），以及后台 bash 的查询（`bash{job, action:"wait"|"output"}`）。
+ *
+ * 每个 run 一个实例：tool-runner 以 run 的 AbortSignal 为键取（`guardFor`），run 结束随之回收。
+ */
+import type { ToolCallBlock } from "../ai/types.js";
+import type { ToolDefinition } from "../tools/types.js";
+export declare const LOOP_REMIND_AT = 3;
+export declare const LOOP_STOP_AT = 5;
+/** 结束 run 时 `agent_settled.warning` 的值。 */
+export declare const REPEATED_TOOL_CALL = "repeated_tool_call";
+export type LoopVerdict = "ok" | "remind" | "stop";
+/** 规范化 JSON：对象键按字典序，`undefined` 字段省略。 */
+export declare function canonicalJson(value: unknown): string;
+export declare function callFingerprint(call: Pick<ToolCallBlock, "name" | "arguments">): string;
+/** 轮询类调用：工具声明 `pollable`，或后台 bash 的 wait / output。 */
+export declare function isPollableCall(call: ToolCallBlock, tool: ToolDefinition | undefined): boolean;
+export declare class LoopGuard {
+    private readonly remindAt;
+    private readonly stopAt;
+    private readonly counts;
+    constructor(remindAt?: number, stopAt?: number);
+    /** 记一次调用并给出判定（轮询类恒为 ok，不计数）。 */
+    observe(call: ToolCallBlock, tool: ToolDefinition | undefined): LoopVerdict;
+    /** 该调用到目前为止的次数。 */
+    count(call: ToolCallBlock): number;
+}
+/** 追加在第 3、4 次结果末尾的提醒（给模型看）。 */
+export declare function loopReminderText(name: string, count: number): string;
+/** 第 5 次：不执行，给这条错误结果并结束 run。 */
+export declare function loopStopText(name: string, count: number): string;
+/** 本 run 的检测器（以 run 的 AbortSignal 为键，run 结束随 signal 回收）。 */
+export declare function guardFor(signal: AbortSignal): LoopGuard;

package/dist/agent/loop-guard.js

@@ -0,0 +1,95 @@
+/**
+ * 重复调用检测（docs/wave5-plan.md §8.3 H1，D29）。[W5-H2]
+ *
+ * - 指纹 = `sha256(工具名 + 规范化 JSON 参数)`（对象键排序，数组保持顺序）；同一 run 内**累计**计数。
+ * - 第 `LOOP_REMIND_AT`（3）次起：照常执行，在该次 toolResult 末尾追加提醒（只改这条结果，缓存安全）。
+ * - 第 `LOOP_STOP_AT`（5）次：不执行，给错误结果并结束本 run，`agent_settled{warning:"repeated_tool_call"}`。
+ * - 豁免：`annotations.pollable` 的工具（`task_ctl`），以及后台 bash 的查询（`bash{job, action:"wait"|"output"}`）。
+ *
+ * 每个 run 一个实例：tool-runner 以 run 的 AbortSignal 为键取（`guardFor`），run 结束随之回收。
+ */
+import { createHash } from "node:crypto";
+export const LOOP_REMIND_AT = 3;
+export const LOOP_STOP_AT = 5;
+/** 结束 run 时 `agent_settled.warning` 的值。 */
+export const REPEATED_TOOL_CALL = "repeated_tool_call";
+/** 规范化 JSON：对象键按字典序，`undefined` 字段省略。 */
+export function canonicalJson(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value) ?? "null";
+    if (Array.isArray(value))
+        return `[${value.map((item) => canonicalJson(item)).join(",")}]`;
+    const record = value;
+    const parts = Object.keys(record)
+        .filter((key) => record[key] !== undefined)
+        .sort()
+        .map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`);
+    return `{${parts.join(",")}}`;
+}
+export function callFingerprint(call) {
+    return createHash("sha256")
+        .update(call.name)
+        .update("\u0000")
+        .update(canonicalJson(call.arguments))
+        .digest("hex");
+}
+/** 轮询类调用：工具声明 `pollable`，或后台 bash 的 wait / output。 */
+export function isPollableCall(call, tool) {
+    if (tool?.annotations?.pollable === true)
+        return true;
+    if (call.name !== "bash")
+        return false;
+    const args = call.arguments;
+    return (typeof args === "object" &&
+        args !== null &&
+        typeof args.job === "string" &&
+        (args.action === "wait" || args.action === "output"));
+}
+export class LoopGuard {
+    remindAt;
+    stopAt;
+    counts = new Map();
+    constructor(remindAt = LOOP_REMIND_AT, stopAt = LOOP_STOP_AT) {
+        this.remindAt = remindAt;
+        this.stopAt = stopAt;
+    }
+    /** 记一次调用并给出判定（轮询类恒为 ok，不计数）。 */
+    observe(call, tool) {
+        if (isPollableCall(call, tool))
+            return "ok";
+        const key = callFingerprint(call);
+        const count = (this.counts.get(key) ?? 0) + 1;
+        this.counts.set(key, count);
+        if (count >= this.stopAt)
+            return "stop";
+        if (count >= this.remindAt)
+            return "remind";
+        return "ok";
+    }
+    /** 该调用到目前为止的次数。 */
+    count(call) {
+        return this.counts.get(callFingerprint(call)) ?? 0;
+    }
+}
+/** 追加在第 3、4 次结果末尾的提醒（给模型看）。 */
+export function loopReminderText(name, count) {
+    return (`<system-reminder>You have now called ${name} ${count} times in this run with exactly the ` +
+        `same arguments. Repeating it will not change the result; use what you already have, try a ` +
+        `different approach, or stop and report. A ${LOOP_STOP_AT}th identical call ends the run.` +
+        `</system-reminder>`);
+}
+/** 第 5 次：不执行，给这条错误结果并结束 run。 */
+export function loopStopText(name, count) {
+    return (`Not executed: ${name} was called ${count} times in this run with identical arguments. ` +
+        `The run was stopped to avoid a loop.`);
+}
+const guards = new WeakMap();
+/** 本 run 的检测器（以 run 的 AbortSignal 为键，run 结束随 signal 回收）。 */
+export function guardFor(signal) {
+    let guard = guards.get(signal);
+    if (guard === undefined) {
+        guard = new LoopGuard();
+        guards.set(signal, guard);
+    }
+    return guard;
+}

package/dist/agent/loop.d.ts

@@ -10,6 +10,8 @@
  * 内层结束（无 tool_call 且 steer 空）→ 收 followUp（有则继续外层）→ 返回
  * ```
  *
+ * [W5-H2] 工具批次带 `stop`（重复调用检测）时本轮结束即返回，`RunOutcome.warning` 交给会话层。
+ *
  * 循环不发 agent_start / agent_end（由 Agent 发，以便带上 willRetry）；上下文每次请求前从
  * `getMessages()` 现取（压缩 / context_edit 会替换 Agent 的消息数组）。
  */
@@ -41,6 +43,8 @@ export interface RunOutcome {
     /** 最后一条助手消息的 stopReason；工具执行中被中断为 "aborted"。 */
     stopReason: string;
     newMessages: AgentMessage[];
+    /** [W5-H2] run 被 harness 提前结束的原因（重复调用检测：`repeated_tool_call`）。 */
+    warning?: string;
 }
 export declare const ZERO_USAGE: Usage;
 export declare function failureMessage(model: Model, stopReason: "error" | "aborted", errorMessage: string): AssistantMessage;

package/dist/agent/loop.js

@@ -10,6 +10,8 @@
  * 内层结束（无 tool_call 且 steer 空）→ 收 followUp（有则继续外层）→ 返回
  * ```
  *
+ * [W5-H2] 工具批次带 `stop`（重复调用检测）时本轮结束即返回，`RunOutcome.warning` 交给会话层。
+ *
  * 循环不发 agent_start / agent_end（由 Agent 发，以便带上 willRetry）；上下文每次请求前从
  * `getMessages()` 现取（压缩 / context_edit 会替换 Agent 的消息数组）。
  */
@@ -129,6 +131,7 @@ export async function runLoop(prompts, config, signal, options = {}) {
             const calls = toolCallsOf(assistant);
             hasMoreToolCalls = false;
             let toolResults = [];
+            let stop;
             if (calls.length > 0) {
                 const batch = assistant.stopReason === "length"
                     ? await failTruncatedBatch(assistant, emit)
@@ -136,12 +139,16 @@ export async function runLoop(prompts, config, signal, options = {}) {
                 toolResults = batch.messages;
                 newMessages.push(...toolResults);
                 hasMoreToolCalls = !batch.terminate;
+                stop = batch.stop;
             }
             lastTurn = { assistant, toolResults };
             const decision = await hooks.finishTurn?.(lastTurn);
             await emit({ type: "turn_end", message: assistant, toolResults });
             if (signal.aborted)
                 return outcome("aborted");
+            // [W5-H2] 重复调用检测要求结束：不再投递 steer / followUp（留在队列）
+            if (stop !== undefined)
+                return { ...outcome(assistant.stopReason), warning: stop };
             // length 且无工具调用：输出被截断，交给会话层的溢出恢复，不投递 steer / followUp。
             if (assistant.stopReason === "length" && calls.length === 0)
                 return outcome("length");

package/dist/agent/prompt-rules.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 系统提示 `rules` 节的通用行为规则（在各工具 `promptGuidelines` 之前）。
+ *
+ * 只按工具表决定、会话内不变，所以不影响前缀稳定（设计 §9.1）。每加一条都进每次请求的缓存前缀：
+ * 保持一句、英文、只写模型确实会做错的事；预算见 `src/cli/prompt-budget.test.ts`。
+ * 「edit 的多处修改」写在 edit 工具描述里（只在 edit 可用时出现）；并行批量在 codemode 独占时
+ * 由它自己的说明负责，所以只在 read 直接可用时给。
+ */
+import type { ToolDefinition } from "../tools/types.js";
+export declare const DESTRUCTIVE_RULE = "Ask before destructive commands (rm -rf, git reset --hard, force push, deleting branches) unless the user requested them.";
+export declare const PARALLEL_READS_RULE = "Batch independent read-only tool calls into one turn.";
+export declare function baseRules(tools: readonly Pick<ToolDefinition, "name">[]): string[];

package/dist/agent/prompt-rules.js

@@ -0,0 +1,18 @@
+/**
+ * 系统提示 `rules` 节的通用行为规则（在各工具 `promptGuidelines` 之前）。
+ *
+ * 只按工具表决定、会话内不变，所以不影响前缀稳定（设计 §9.1）。每加一条都进每次请求的缓存前缀：
+ * 保持一句、英文、只写模型确实会做错的事；预算见 `src/cli/prompt-budget.test.ts`。
+ * 「edit 的多处修改」写在 edit 工具描述里（只在 edit 可用时出现）；并行批量在 codemode 独占时
+ * 由它自己的说明负责，所以只在 read 直接可用时给。
+ */
+export const DESTRUCTIVE_RULE = "Ask before destructive commands (rm -rf, git reset --hard, force push, deleting branches) unless the user requested them.";
+export const PARALLEL_READS_RULE = "Batch independent read-only tool calls into one turn.";
+export function baseRules(tools) {
+    if (tools.length === 0)
+        return [];
+    const rules = [DESTRUCTIVE_RULE];
+    if (tools.some((tool) => tool.name === "read"))
+        rules.push(PARALLEL_READS_RULE);
+    return rules;
+}

package/dist/agent/reminders.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 统一提醒通道 `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 type { RemindersConfig } from "../config/types-w5.js";
+import type { AgentMessage } from "../session/types.js";
+import { type Job } from "../tools/background-jobs.js";
+import type { SessionCore } from "./session-core.js";
+import type { SessionExtension } from "./session-extensions.js";
+export declare const REMINDER_CUSTOM_TYPE = "ama.reminder";
+export declare const DEFAULT_TODO_REMINDER_TURNS = 10;
+export declare const CONTEXT_REMINDER_RATIOS: readonly [0.7, 0.85];
+export declare const BUDGET_REMINDER_RATIO = 0.8;
+export declare const MAX_CHANGED_FILES = 10;
+export interface RemindersSettings {
+    reminders?: RemindersConfig;
+    /** `todo.reminder`：连续多少次回复未更新清单就复述；0 关闭。 */
+    todoEvery?: number;
+}
+/** config → 提醒设置（`reminders.*` 与 `todo.reminder`）。 */
+export declare function remindersSettings(config: {
+    reminders?: RemindersConfig | undefined;
+    todo?: {
+        reminder?: number | undefined;
+    } | undefined;
+}): RemindersSettings;
+export interface RemindersDeps {
+    /** `git diff --stat -- <files>`；拿不到返回 undefined。测试注入。 */
+    diffStat?(cwd: string, files: readonly string[]): string | undefined;
+    stat?(path: string): {
+        mtimeMs: number;
+        size: number;
+    } | undefined;
+}
+export declare function jobExitText(job: Job): string;
+export declare function reminderMessage(text: string): AgentMessage;
+/**
+ * 提醒扩展。主会话：全部提醒 + 后台任务生命周期；子会话：只管后台任务（事件与回收）。
+ */
+export declare function createRemindersExtension(core: SessionCore, settings?: RemindersSettings, deps?: RemindersDeps): SessionExtension;