@armadra/agent 0.3.0 → 0.5.0

package/dist/modes/print/print-mode.d.ts

@@ -1,17 +1,53 @@
 /**
  * print 模式（`ama -p`，设计 §11.1 第 15–16 步）。[B6]
  *
- * - 提示 = 位置参数 + stdin 管道（stdin 非 TTY 时读到 EOF），两者都有时空一行拼接；都没有 → 用法错误 2。
+ * - 提示 = 位置参数 + stdin，两者都有时空一行拼接；都没有 → 用法错误 2。stdin 的读法：
+ *   - 没有提示参数，或显式写了位置参数 `-`：读到 EOF（超过 3 s 时 stderr 提示一次正在等待）；
+ *   - 有提示参数且 stdin 是管道（shell 管道或父进程留的管道）：等首字节，`AMA_STDIN_WAIT_MS`
+ *     （缺省 2000，0 = 不等）内一个字节都没有 → 忽略 stdin 并在 stderr 提示；收到首字节后读到 EOF；
+ *   - stdin 是普通文件 / 空设备：直接读（不会卡）；TTY 或 `--no-stdin`：不读。
  * - 图片：`--image`（可重复）与提示里的 `@图片路径` / 图片文件路径作为附件（modes/image-input.ts）；
  *   显式附件遇到当前模型不收图片、文件不存在或超限 → 用法错误 2，不发请求。
  * - `--output-format text`（缺省）：运行结束后输出最后一条助手文本；`json`：一个结果对象（文本、
  *   停止原因、用量、缓存命中率、[W3-C2] `cache` 统计（同 `get_session_stats.cache`）、全部条目）；
  *   `stream-json`：每个会话事件一行（线上形状同 RPC，含 `cache_miss` / `cache_warm` /
  *   `context_pressure`）。
- * - 无人值守：ask → deny（bootstrap 已按 print 设 unattended）。
- * - 退出码：最终助手消息 `error / aborted` 或提示被拒 → 1；SIGINT 130、SIGTERM 143（先 abort）。
+ * - 重试：text / json 格式在 stderr 打一行 `↻ 重试 n/m`（stream-json 里本来就有事件），等待期间不再无声。
+ * - 无人值守：ask → deny（bootstrap 已按 print 设 unattended）。被拒的调用（`tool_execution_end`
+ *   带 `denied`）在 stderr 汇总一行（工具 ×次数、首个原因、放行办法），json 结果带 `deniedTools`。
+ * - [W5-H2] 预算（`--max-turns N` / `--max-cost USD` / config `limits.*`，agent/limits.ts）：到限
+ *   （会话发 `limit_reached`）→ stderr 一行、json 带 `limitReached{kind, value, limit}`（回合到限另带
+ *   `maxTurnsReached: true`）、退出码 8。
+ * - [W5-H2] plan 模式产出计划、`plan.unattended: stop`（缺省）没人审批：stderr 一行（计划文件与审批办法）、
+ *   json 带 `planPending{planId, version, filePath}`、退出码 9。
+ * - [W5-H2] `--image` / `@图片` 超限时按 config `images.resize` 缩放（缺省 auto）。
+ * - 退出码：最终助手消息 `error / aborted` 或提示被拒 → 1；有工具调用被拒 → 7；到达预算 → 8；
+ *   计划待审批 → 9；SIGINT 130、SIGTERM 143（先 abort）。
  */
-import type { ModeContext } from "../../cli/deps.js";
+import type { CliIo, ModeContext } from "../../cli/deps.js";
 import type { Runtime } from "../../cli/runtime.js";
+import type { LimitReachedEvent, PlanProposedEvent } from "../../agent/types.js";
 export declare function joinPrompt(argument: string | undefined, piped: string): string;
+/** 等 stdin 多久后提示一次「正在等待」。 */
+export declare const STDIN_WAIT_HINT_MS = 3000;
+/** 有提示参数时等管道首字节的缺省上限；`AMA_STDIN_WAIT_MS` 覆盖，0 = 不等待。 */
+export declare const STDIN_FIRST_BYTE_MS = 2000;
+export declare function stdinWaitMs(env: Readonly<Record<string, string | undefined>>): number;
+/**
+ * 决定读不读 stdin（规则见文件头）。`mode`：`auto` 按提示参数与 stdin 类型决定，`explicit`
+ * （位置参数 `-`）一直等到 EOF，`off`（`--no-stdin`）不读。
+ */
+export declare function readPromptStdin(io: CliIo, prompt: string | undefined, mode: "auto" | "explicit" | "off", hintMs?: number): Promise<string>;
 export declare function runPrintMode(runtime: Runtime, context: ModeContext): Promise<number>;
+/** stderr 一行：计划已落盘待审批（-p 不替人批准）。 */
+export declare function describePlanPending(plan: PlanProposedEvent): string;
+/** stderr 一行：哪个预算到限。 */
+export declare function describeLimit(event: LimitReachedEvent): string;
+/** 被拒的一次工具调用（json 结果的 `deniedTools` 元素）。 */
+export interface DeniedTool {
+    toolCallId: string;
+    toolName: string;
+    reason: string;
+}
+/** stderr 一行：被拒的工具 ×次数、首个原因、放行办法。 */
+export declare function describeDenied(denied: readonly DeniedTool[]): string;

package/dist/modes/print/print-mode.js

@@ -1,29 +1,103 @@
 /**
  * print 模式（`ama -p`，设计 §11.1 第 15–16 步）。[B6]
  *
- * - 提示 = 位置参数 + stdin 管道（stdin 非 TTY 时读到 EOF），两者都有时空一行拼接；都没有 → 用法错误 2。
+ * - 提示 = 位置参数 + stdin，两者都有时空一行拼接；都没有 → 用法错误 2。stdin 的读法：
+ *   - 没有提示参数，或显式写了位置参数 `-`：读到 EOF（超过 3 s 时 stderr 提示一次正在等待）；
+ *   - 有提示参数且 stdin 是管道（shell 管道或父进程留的管道）：等首字节，`AMA_STDIN_WAIT_MS`
+ *     （缺省 2000，0 = 不等）内一个字节都没有 → 忽略 stdin 并在 stderr 提示；收到首字节后读到 EOF；
+ *   - stdin 是普通文件 / 空设备：直接读（不会卡）；TTY 或 `--no-stdin`：不读。
  * - 图片：`--image`（可重复）与提示里的 `@图片路径` / 图片文件路径作为附件（modes/image-input.ts）；
  *   显式附件遇到当前模型不收图片、文件不存在或超限 → 用法错误 2，不发请求。
  * - `--output-format text`（缺省）：运行结束后输出最后一条助手文本；`json`：一个结果对象（文本、
  *   停止原因、用量、缓存命中率、[W3-C2] `cache` 统计（同 `get_session_stats.cache`）、全部条目）；
  *   `stream-json`：每个会话事件一行（线上形状同 RPC，含 `cache_miss` / `cache_warm` /
  *   `context_pressure`）。
- * - 无人值守：ask → deny（bootstrap 已按 print 设 unattended）。
- * - 退出码：最终助手消息 `error / aborted` 或提示被拒 → 1；SIGINT 130、SIGTERM 143（先 abort）。
+ * - 重试：text / json 格式在 stderr 打一行 `↻ 重试 n/m`（stream-json 里本来就有事件），等待期间不再无声。
+ * - 无人值守：ask → deny（bootstrap 已按 print 设 unattended）。被拒的调用（`tool_execution_end`
+ *   带 `denied`）在 stderr 汇总一行（工具 ×次数、首个原因、放行办法），json 结果带 `deniedTools`。
+ * - [W5-H2] 预算（`--max-turns N` / `--max-cost USD` / config `limits.*`，agent/limits.ts）：到限
+ *   （会话发 `limit_reached`）→ stderr 一行、json 带 `limitReached{kind, value, limit}`（回合到限另带
+ *   `maxTurnsReached: true`）、退出码 8。
+ * - [W5-H2] plan 模式产出计划、`plan.unattended: stop`（缺省）没人审批：stderr 一行（计划文件与审批办法）、
+ *   json 带 `planPending{planId, version, filePath}`、退出码 9。
+ * - [W5-H2] `--image` / `@图片` 超限时按 config `images.resize` 缩放（缺省 auto）。
+ * - 退出码：最终助手消息 `error / aborted` 或提示被拒 → 1；有工具调用被拒 → 7；到达预算 → 8；
+ *   计划待审批 → 9；SIGINT 130、SIGTERM 143（先 abort）。
  */
 import { currentSession } from "../../cli/compose-session.js";
 import { ExitCode } from "../../cli/exit-codes.js";
 import { errorText, lastAssistant, onStdoutClosed, onTerminationSignals } from "../shared.js";
 import { toJsonLine, toWireEvent } from "./json-event.js";
+import { formatUsd } from "../../agent/limits.js";
 import { promptImages, sessionModel } from "../image-input.js";
 export function joinPrompt(argument, piped) {
     const parts = [argument ?? "", piped.replace(/\s+$/, "")].filter((p) => p.trim() !== "");
     return parts.join("\n\n");
 }
+/** 等 stdin 多久后提示一次「正在等待」。 */
+export const STDIN_WAIT_HINT_MS = 3_000;
+/** 有提示参数时等管道首字节的缺省上限；`AMA_STDIN_WAIT_MS` 覆盖，0 = 不等待。 */
+export const STDIN_FIRST_BYTE_MS = 2_000;
+export function stdinWaitMs(env) {
+    const raw = env["AMA_STDIN_WAIT_MS"];
+    if (raw === undefined || raw.trim() === "")
+        return STDIN_FIRST_BYTE_MS;
+    const value = Number(raw);
+    return Number.isFinite(value) && value >= 0 ? value : STDIN_FIRST_BYTE_MS;
+}
+/** io 没有首字节读取时的退化：整段读取与超时赛跑。 */
+function readWithin(io, ms) {
+    if (io.readStdinFirstByte !== undefined)
+        return io.readStdinFirstByte(ms);
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => resolve(undefined), ms);
+        io.readStdin().then((text) => {
+            clearTimeout(timer);
+            resolve(text);
+        }, (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+    });
+}
+/**
+ * 决定读不读 stdin（规则见文件头）。`mode`：`auto` 按提示参数与 stdin 类型决定，`explicit`
+ * （位置参数 `-`）一直等到 EOF，`off`（`--no-stdin`）不读。
+ */
+export async function readPromptStdin(io, prompt, mode, hintMs = STDIN_WAIT_HINT_MS) {
+    if (io.stdinIsTTY || mode === "off")
+        return "";
+    const kind = io.stdinKind?.() ?? "other";
+    const safe = kind === "file" || kind === "null";
+    if (prompt !== undefined && prompt !== "" && mode === "auto" && !safe) {
+        const waitMs = stdinWaitMs(io.env);
+        if (waitMs === 0)
+            return "";
+        const text = await readWithin(io, waitMs);
+        if (text === undefined) {
+            io.stderr(`ama: 未在 ${formatSeconds(waitMs)}内收到管道输入，已忽略；需要等待请在末尾加 -\n`);
+            return "";
+        }
+        return text;
+    }
+    const timer = safe
+        ? undefined
+        : setTimeout(() => io.stderr("ama: 正在等待 stdin 输入结束（Ctrl+D 结束；提示也可以直接写成参数）…\n"), hintMs);
+    try {
+        return await io.readStdin();
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function formatSeconds(ms) {
+    return ms % 1000 === 0 ? `${ms / 1000} 秒` : `${ms} 毫秒`;
+}
 export async function runPrintMode(runtime, context) {
     const { io } = context;
     const format = context.args.outputFormat ?? "text";
-    const piped = io.stdinIsTTY ? "" : await io.readStdin();
+    const stdinMode = context.args.noStdin ? "off" : context.args.stdin ? "explicit" : "auto";
+    const piped = await readPromptStdin(io, context.prompt, stdinMode);
     const prompt = joinPrompt(context.prompt, piped);
     if (prompt === "") {
         io.stderr("ama: -p 需要提示（位置参数或 stdin 管道）\n");
@@ -31,16 +105,35 @@ export async function runPrintMode(runtime, context) {
     }
     const session = currentSession(runtime);
     let images;
+    const resize = runtime.config.images?.resize;
     try {
-        images = await promptImages(prompt, context.args.images, io.cwd, sessionModel(runtime.providers, session));
+        images = await promptImages(prompt, context.args.images, io.cwd, sessionModel(runtime.providers, session), resize === undefined ? {} : { resize });
     }
     catch (error) {
         io.stderr(`ama: ${errorText(error)}\n`);
         return ExitCode.Usage;
     }
-    const unsubscribe = format === "stream-json"
-        ? session.subscribe((event) => io.stdout(`${toJsonLine(toWireEvent(event))}\n`))
-        : () => undefined;
+    const denied = [];
+    let limit;
+    let plan;
+    const unsubscribe = session.subscribe((event) => {
+        if (event.type === "limit_reached")
+            limit ??= event;
+        else if (event.type === "plan_proposed")
+            plan = event;
+        else if (event.type === "plan_resolved" && event.planId === plan?.planId)
+            plan = undefined;
+        if (event.type === "tool_execution_end" && event.denied === true)
+            denied.push({
+                toolCallId: event.toolCallId,
+                toolName: event.toolName,
+                reason: textOf(event),
+            });
+        if (format === "stream-json")
+            io.stdout(`${toJsonLine(toWireEvent(event))}\n`);
+        else if (event.type === "auto_retry_start")
+            io.stderr(`ama: ↻ 重试 ${event.attempt}/${event.maxAttempts}（${Math.round(event.delayMs / 1000)}s 后）：${event.errorMessage}\n`);
+    });
     let signalled;
     const offSignals = onTerminationSignals((code) => {
         signalled ??= code;
@@ -88,6 +181,22 @@ export async function runPrintMode(runtime, context) {
             cost: stats.cost,
             cacheHitRate: stats.cacheHitRate,
             ...(stats.cache !== undefined ? { cache: stats.cache } : {}),
+            ...(denied.length > 0 ? { deniedTools: denied } : {}),
+            ...(plan !== undefined
+                ? {
+                    planPending: {
+                        planId: plan.planId,
+                        version: plan.version,
+                        ...(plan.filePath === undefined ? {} : { filePath: plan.filePath }),
+                    },
+                }
+                : {}),
+            ...(limit !== undefined
+                ? {
+                    limitReached: { kind: limit.kind, value: limit.value, limit: limit.limit },
+                    ...(limit.kind === "turns" ? { maxTurnsReached: true } : {}),
+                }
+                : {}),
             entries: session.entries,
         })}\n`);
     }
@@ -99,9 +208,53 @@ export async function runPrintMode(runtime, context) {
         io.stderr(`ama: ${failure}\n`);
         return ExitCode.RuntimeError;
     }
+    if (limit !== undefined) {
+        if (denied.length > 0)
+            io.stderr(`${describeDenied(denied)}\n`);
+        io.stderr(`${describeLimit(limit)}\n`);
+        return ExitCode.LimitReached;
+    }
     if (last?.stopReason === "error" || last?.stopReason === "aborted") {
         io.stderr(`ama: ${last.errorMessage ?? "模型调用失败"}\n`);
         return ExitCode.RuntimeError;
     }
+    if (denied.length > 0)
+        io.stderr(`${describeDenied(denied)}\n`);
+    if (plan !== undefined) {
+        io.stderr(`${describePlanPending(plan)}\n`);
+        return ExitCode.PlanPending;
+    }
+    if (denied.length > 0)
+        return ExitCode.ToolDenied;
     return ExitCode.Ok;
 }
+/** stderr 一行：计划已落盘待审批（-p 不替人批准）。 */
+export function describePlanPending(plan) {
+    const where = plan.filePath ?? plan.planId;
+    return (`ama: 计划 v${plan.version} 已落盘、待审批（未执行）：${where}；-p 不替人批准——` +
+        "在交互界面或 RPC plan_response 里审批，或设 plan.unattended: approve 让 -p 批准后接着执行");
+}
+/** stderr 一行：哪个预算到限。 */
+export function describeLimit(event) {
+    return event.kind === "turns"
+        ? `ama: 已达到回合上限 ${event.limit}（--max-turns / limits.maxTurns），运行在完成前结束`
+        : `ama: 已达到费用上限 ${formatUsd(event.limit)}（累计 ${formatUsd(event.value)}；` +
+            "--max-cost / limits.maxCostUsd），运行在完成前结束";
+}
+function textOf(event) {
+    const content = event.result.content;
+    const text = typeof content === "string"
+        ? content
+        : content.map((b) => (b.type === "text" ? b.text : "")).join("");
+    return text.split("\n")[0]?.trim().slice(0, 200) ?? "";
+}
+/** stderr 一行：被拒的工具 ×次数、首个原因、放行办法。 */
+export function describeDenied(denied) {
+    const counts = new Map();
+    for (const item of denied)
+        counts.set(item.toolName, (counts.get(item.toolName) ?? 0) + 1);
+    const tools = [...counts].map(([name, n]) => `${name} ×${n}`).join("、");
+    const reason = denied[0]?.reason ?? "";
+    return (`ama: ${denied.length} 次工具调用被拒：${tools}${reason !== "" ? `（${reason}）` : ""}；` +
+        "-p 没有人审批，需要放行时用 --permission-mode auto-edit|auto 或 --allow <规则>");
+}

package/dist/modes/rpc/commands.d.ts

@@ -8,7 +8,12 @@
  * - 审批：`RpcApprovals` 是 UI broker（`set_client_capabilities` 声明 approvals 后挂上），
  *   `permission_response` 按 requestId 作答；先到的回答暂存，等 broker 被问到时取用。
  * - 密钥不离开进程：`get_available_models` 只回 `hasKey` 与 `keySource`。
+ * - [W5-F] 计划：声明 `plans` 能力后计划审批交客户端（`plan_proposed` → `plan_response`），未声明按
+ *   `plan.unattended`；`approve_fresh` 在这里新建会话并以计划全文开新回合。`get_tasks / get_agents`
+ *   读 `RpcContext.tasks / agents`（W5-G 的注册表与发现结果；未装配时回空表）。
  */
+import type { AgentInfo } from "../../agents/types.js";
+import type { TaskRegistryView } from "../../tools/types.js";
 import type { AgentSession } from "../../agent/types.js";
 import type { Runtime } from "../../cli/runtime.js";
 import type { ApprovalBroker, ApprovalDecision, ApprovalRequest } from "../../permissions/types.js";
@@ -32,6 +37,10 @@ export interface RpcContext {
     onSessionChanged(next: AgentSession): void;
     /** 运行开始后提示命令自身的失败（应答已发出）。 */
     onBackgroundError(error: unknown): void;
+    /** [W5-F] `get_tasks`：子 Agent 任务注册表的只读视图（W5-G 装配；缺省回空表）。 */
+    tasks?(): TaskRegistryView | undefined;
+    /** [W5-F] `get_agents`：可用的子 Agent 类型与外部 Agent（W5-G / W5-E 装配；缺省回空表）。 */
+    agents?(): readonly AgentInfo[];
 }
 export type RpcHandlers = {
     [K in RpcCommandType]: (params: RpcCommandMap[K], ctx: RpcContext) => Promise<unknown>;

package/dist/modes/rpc/commands.js

@@ -8,12 +8,19 @@
  * - 审批：`RpcApprovals` 是 UI broker（`set_client_capabilities` 声明 approvals 后挂上），
  *   `permission_response` 按 requestId 作答；先到的回答暂存，等 broker 被问到时取用。
  * - 密钥不离开进程：`get_available_models` 只回 `hasKey` 与 `keySource`。
+ * - [W5-F] 计划：声明 `plans` 能力后计划审批交客户端（`plan_proposed` → `plan_response`），未声明按
+ *   `plan.unattended`；`approve_fresh` 在这里新建会话并以计划全文开新回合。`get_tasks / get_agents`
+ *   读 `RpcContext.tasks / agents`（W5-G 的注册表与发现结果；未装配时回空表）。
  */
 import { formatModelRef } from "../../ai/providers/channels.js";
 import { AgentSessionImpl } from "../../agent/session.js";
+import { planController } from "../../agent/session-plan.js";
+import { currentTodos } from "../../plan/store.js";
 import { getSupportedLevels } from "../../ai/thinking.js";
 import { switchSession } from "../../cli/compose-session.js";
 import { AmaError } from "../../errors.js";
+import { isPermissionMode } from "../../permissions/modes.js";
+import { PERMISSION_MODES_STRICT_FIRST } from "../../permissions/types.js";
 import { BUILTIN_COMMANDS } from "../commands-core.js";
 /** 审批 broker：等客户端 `permission_response`。 */
 export class RpcApprovals {
@@ -60,6 +67,17 @@ function impl(session) {
         return session;
     throw new AmaError("not_implemented", "该会话不支持此命令");
 }
+/** [W5-F] 当前会话的计划控制面；会话没有装配 plan 扩展时报 not_implemented。 */
+function plans(ctx) {
+    const controller = planController(ctx.session());
+    if (controller === undefined)
+        throw new AmaError("not_implemented", "该会话没有装配 plan 扩展");
+    return controller;
+}
+/** 声明了 `plans` 能力 → 客户端作答；否则按 `plan.unattended`。换会话后重新应用。 */
+function applyPlanAttendance(ctx) {
+    planController(ctx.session())?.setAttendance(ctx.capabilities.has("plans") ? "client" : "unattended");
+}
 /** 开始一次运行：开始 / 入队 / 被处理后即返回，不等运行结束。 */
 async function startRun(ctx, run) {
     const session = ctx.session();
@@ -87,6 +105,7 @@ async function startRun(ctx, run) {
 async function switched(ctx, next, reason) {
     const session = await next;
     ctx.onSessionChanged(session);
+    applyPlanAttendance(ctx);
     if (session instanceof AgentSessionImpl)
         session.announceStart(reason);
     return { sessionId: session.state.sessionId, sessionFile: session.state.sessionFile };
@@ -211,12 +230,24 @@ export const handlers = {
             ]
             : []),
     }),
+    get_rewind_points: async (_p, ctx) => ({ points: ctx.session().rewindPoints() }),
+    rewind: async (p, ctx) => {
+        const request = { entryId: p.entryId, mode: p.mode };
+        if (p.dryRun !== undefined)
+            request.dryRun = p.dryRun;
+        if (p.onConflict !== undefined)
+            request.onConflict = p.onConflict;
+        return ctx.session().rewind(request);
+    },
+    summarize_from: async (p, ctx) => ctx.session().summarizeFrom(p.entryId, p.instructions),
+    summarize_up_to: async (p, ctx) => ctx.session().summarizeUpTo(p.entryId, p.instructions),
     set_client_capabilities: async (p, ctx) => {
         ctx.capabilities = new Set(p.capabilities);
         const approvals = ctx.capabilities.has("approvals");
         ctx.runtime.approvals.setUiBroker(approvals ? ctx.approvals : undefined);
         if (!approvals)
             ctx.approvals.cancelAll();
+        applyPlanAttendance(ctx);
         return { capabilities: [...ctx.capabilities] };
     },
     permission_response: async (p, ctx) => ({
@@ -254,10 +285,28 @@ export const handlers = {
         };
     },
     set_permission_mode: async (p, ctx) => {
+        if (!isPermissionMode(p.mode)) {
+            throw new AmaError("invalid_arguments", `mode 应为 ${PERMISSION_MODES_STRICT_FIRST.join(" | ")}`);
+        }
         ctx.session().setPermissionMode(p.mode);
         return { mode: p.mode };
     },
     get_commands: async (_p, ctx) => ({ commands: commands(ctx.runtime) }),
     get_skills: async (_p, ctx) => ({ skills: ctx.runtime.resources.skills }),
+    // [W5-F] 计划 / 任务命令（docs/wave5-plan.md §6.5、§7.5）
+    plan_response: async (p, ctx) => {
+        const result = await plans(ctx).respond(p);
+        if (result.freshPrompt !== undefined) {
+            const prompt = result.freshPrompt;
+            await switched(ctx, switchSession(ctx.runtime, { kind: "new" }), "new");
+            planController(ctx.session())?.adopt(result.plan);
+            await startRun(ctx, () => ctx.session().prompt(prompt, { origin: "plan" }));
+        }
+        return { planId: result.planId, decision: result.decision };
+    },
+    get_plan: async (p, ctx) => plans(ctx).get(p.planId),
+    get_todos: async (_p, ctx) => ({ items: currentTodos(impl(ctx.session()).manager.branch()) }),
+    get_tasks: async (_p, ctx) => ({ tasks: [...(ctx.tasks?.()?.list() ?? [])] }),
+    get_agents: async (_p, ctx) => ({ agents: [...(ctx.agents?.() ?? [])] }),
 };
 export const RPC_COMMAND_TYPES = Object.keys(handlers);

package/dist/modes/rpc/rpc-mode.js

@@ -19,9 +19,11 @@ import { RPC_PROTOCOL_VERSION } from "../../rpc.js";
 import { AMA_VERSION } from "../../version.js";
 import { toJsonLine, toWireEvent } from "../print/json-event.js";
 import { errorText, onTerminationSignals } from "../shared.js";
+import { sessionAgents, taskRegistryView } from "../../agent/subagent-registry.js";
+import { cachedAgentInfos } from "../../agents/external.js";
 import { RpcApprovals, handlers } from "./commands.js";
 import { createLineReader, writeChunked } from "./jsonl.js";
-export const RPC_CAPABILITIES = ["approvals", "images", "hooks"];
+export const RPC_CAPABILITIES = ["approvals", "images", "hooks", "plans"];
 export async function runRpcMode(runtime, context, options = {}) {
     const stdin = options.stdin ?? process.stdin;
     const stdout = options.stdout ?? process.stdout;
@@ -48,6 +50,10 @@ export async function runRpcMode(runtime, context, options = {}) {
         onBackgroundError(error) {
             void write({ type: "notification", level: "error", message: errorText(error) });
         },
+        // [W5-G] get_tasks / get_agents：当前会话的任务注册表与可用类型
+        tasks: () => taskRegistryView(session.state.sessionId),
+        // [W5-EG] 外部 Agent 的安装 / 版本要异步探测：会话建立时缓存、变化时刷新，未就绪时只列类型目录
+        agents: () => cachedAgentInfos(session.state.sessionId) ?? sessionAgents(session.state.sessionId),
     };
     runtime.notifier.set((message, level) => {
         void write({ type: "notification", level, message });

package/dist/modes/session-report.d.ts

@@ -47,6 +47,17 @@ export declare function warmStopText(reason: string | undefined): string;
 export declare function warmingText(status: WarmerStatus, now: number, minSavingsUsd: number | undefined): string;
 /** 缓存段的键值行（`/session` 与 `/cache` 共用）。 */
 export declare function cacheRows(session: AgentSession, now?: number): KeyValueRow[];
+/** [W5-U] 外部 Agent 用量一项：美元 / token / 请求数按各自单位，不换算。 */
+export declare function externalUsageText(usage: {
+    runs: number;
+    unit: "usd" | "tokens" | "requests";
+    amount: number;
+    tokens?: number;
+}): string;
+/** [W5-U] 「外部 Agent」段（`getStats().external.byAgent`）；没有外部运行时为空。 */
+export declare function externalRows(session: AgentSession): KeyValueRow[];
+/** [W5-U] 子 Agent 任务汇总（`getStats().tasks`）；没有任务时 undefined。 */
+export declare function taskStatsText(session: AgentSession): string | undefined;
 /** 键值行 → 纯文本（键列对齐、去行尾空白）。 */
 export declare function renderRows(rows: readonly KeyValueRow[], indent?: string): string[];
 export declare function describeCache(session: AgentSession, now?: number): string;

package/dist/modes/session-report.js

@@ -219,6 +219,45 @@ export function cacheRows(session, now = Date.now()) {
     }
     return rows;
 }
+/** [W5-U] 外部 Agent 用量一项：美元 / token / 请求数按各自单位，不换算。 */
+export function externalUsageText(usage) {
+    const amount = usage.unit === "usd"
+        ? formatUsd(usage.amount)
+        : usage.unit === "tokens"
+            ? `${formatTokenCount(usage.amount)} token`
+            : `${usage.amount} 次请求`;
+    const tokens = usage.unit !== "tokens" && usage.tokens !== undefined && usage.tokens > 0
+        ? ` · ${formatTokenCount(usage.tokens)} token`
+        : "";
+    return `${usage.runs} 次运行 · ${amount}${tokens}`;
+}
+/** [W5-U] 「外部 Agent」段（`getStats().external.byAgent`）；没有外部运行时为空。 */
+export function externalRows(session) {
+    const byAgent = session.getStats().external?.byAgent ?? {};
+    return Object.entries(byAgent)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([agent, usage]) => ({ key: agent, value: externalUsageText(usage) }));
+}
+/** [W5-U] 子 Agent 任务汇总（`getStats().tasks`）；没有任务时 undefined。 */
+export function taskStatsText(session) {
+    const tasks = session.getStats().tasks;
+    if (tasks === undefined || tasks.total === 0)
+        return undefined;
+    const parts = [`${tasks.total} 个任务`];
+    if (tasks.running > 0)
+        parts.push(`运行中 ${tasks.running}`);
+    const labels = {
+        completed: "完成",
+        failed: "失败",
+        aborted: "已停止",
+        max_turns: "轮数耗尽",
+        interrupted: "已中断",
+    };
+    for (const [status, count] of Object.entries(tasks.byStatus))
+        if (count !== undefined && count > 0)
+            parts.push(`${labels[status] ?? status} ${count}`);
+    return `${parts.join(" · ")}（/tasks）`;
+}
 /** 键值行 → 纯文本（键列对齐、去行尾空白）。 */
 export function renderRows(rows, indent = "") {
     return new KeyValue(rows)
@@ -257,7 +296,15 @@ export function describeSession(session, now = Date.now()) {
             value: `${stats.contextTokens ?? "?"} / ${stats.contextWindow ?? "?"}（${percent}%）`,
         },
     ];
-    return [...renderRows(rows), describeCache(session, now)].join("\n");
+    const tasks = taskStatsText(session);
+    if (tasks !== undefined)
+        rows.push({ key: "子 Agent", value: tasks });
+    const external = externalRows(session);
+    return [
+        ...renderRows(rows),
+        describeCache(session, now),
+        ...(external.length > 0 ? ["外部 Agent", ...renderRows(external, "  ")] : []),
+    ].join("\n");
 }
 /** `/cache fingerprint`：最近一次真实请求的前缀指纹（system / tools 哈希与模型）。 */
 export function describeFingerprint(session) {

package/dist/permissions/auto-safe.d.ts

@@ -0,0 +1,65 @@
+/**
+ * auto 模式下 bash 的规则层与静态判定（§7.4，docs/permissions.md）。
+ *
+ * 规则层（命中即询问，不调模型）——外层与每层嵌套命令（`sh -c`、`eval`、`xargs`、`find -exec`，
+ * 见 dangerous.ts）的每一段都查：
+ * - 网络命令（{@link networkReason}）：curl / wget / ssh / git push|pull|fetch|clone / npm install / npx …
+ * - 删除与回退（{@link destructiveReason}）：rm -r|-f、find -delete、git clean / restore / checkout -- …
+ * - 写入目标：重定向（`>`、`>>`、`&>`）、tee、cp / mv / mkdir / touch / ln / chmod 等的目标在项目外或受保护；
+ * - 参数里出现机密路径（`cat .env`、`< ~/.ssh/id_rsa`、`--env-file=.env`）。
+ *
+ * 静态判定（全部满足即放行）：每一段都命中安全名单（{@link AUTO_SAFE_COMMANDS} + 用户追加），整条命令
+ * 没有命令替换、参数没有变量展开 `$X`、没有可能匹配点文件的通配、没有超深嵌套。
+ *
+ * 分段与分词复用 rules.ts / dangerous.ts（引号内不切、剥环境赋值与 env / nohup / time 等前缀）。
+ */
+export interface SafeCommandSpec {
+    /** 词前缀：`["git", "status"]` 命中 `git status -s`。git 的全局选项只允许 `-C <dir>` 与 `--no-pager`。 */
+    words: readonly string[];
+    /** 前缀之后任一参数命中即不安全。 */
+    forbid?: RegExp;
+    /** 前缀之后必须出现的参数。 */
+    require?: string;
+}
+/** 初始安全名单（每条在 auto-safe.test.ts 有正反例）。 */
+export declare const AUTO_SAFE_COMMANDS: readonly SafeCommandSpec[];
+/**
+ * 用户追加的安全命令（`permission.autoSafeCommands`）：不含 `*` 按词前缀；含 `*` 按通配匹配整段
+ * （剥过前缀、重定向之后的命令文本）。
+ */
+export declare function extraSafeMatches(argv: readonly string[], entry: string): boolean;
+/** 网络命令：返回说明；不是返回 undefined。 */
+export declare function networkReason(argv: readonly string[]): string | undefined;
+/** 删除与丢弃改动的命令：返回说明；不是返回 undefined。 */
+export declare function destructiveReason(argv: readonly string[]): string | undefined;
+export interface Redirects {
+    /** 输出重定向目标（`>`、`>>`、`>|`、`&>`）。 */
+    outputs: string[];
+    /** 输入重定向来源（`<`）。 */
+    inputs: string[];
+    /** 去掉重定向之后的段文本。 */
+    rest: string;
+}
+/** 从一段命令里取出重定向（引号内不算）；`2>&1`、`>&2` 是复制描述符，没有目标。 */
+export declare function extractRedirects(segment: string): Redirects;
+export interface BashAutoOptions {
+    cwd: string;
+    projectRoot: string;
+    /** `permission.autoSafeCommands`。 */
+    extraSafe?: readonly string[];
+}
+export interface BashAutoAnalysis {
+    /** 规则层要询问的原因；undefined = 规则层不管。 */
+    ask?: string;
+    /** 静态判定放行。 */
+    safe: boolean;
+    /** 不安全（交给分类器）的原因，审计用。 */
+    reason: string;
+}
+/** auto 模式下一条 bash 命令的规则层与静态判定结论。 */
+export declare function analyzeBashForAuto(command: string, options: BashAutoOptions): BashAutoAnalysis;
+/**
+ * [S2] 命令文本里出现的机密路径（读写都算，含嵌套命令）；没有返回 undefined。default 模式「沙箱内免审批」
+ * 用它把 `cat .env` 之类留给正常审批：OS 沙箱挡不住读工作区里的机密文件，输出会进模型上下文。
+ */
+export declare function secretReferenceReason(command: string, cwd: string): string | undefined;