@armadra/agent 0.0.0-stage → 0.2.1

package/dist/modes/session-report.js

@@ -0,0 +1,278 @@
+/**
+ * 会话报告与缓存提示文本（第三波 §1.10）。[W3-C2]
+ *
+ * line 模式、交互模式与 RPC 共用的纯文本层，不含渲染：
+ * - `/session`：会话、模型、消息、用量、上下文 + 「缓存」段（`describeSession`）；
+ * - `/cache`：只有缓存段（`describeCache`）；`/cache fingerprint`：最近一次真实请求的前缀指纹；
+ * - 消息区 / stderr 的一行提示：缓存未命中（只提示 ≥ 20k token 或 ≥ $0.10 的那次）、
+ *   上下文跨越 70% / 90%（`cache.missNotices` 为 false 时都不提示，统计不受影响）。
+ *
+ * 两列对齐用 B9a-2 的 `KeyValue`（按足够宽的宽度渲染再去行尾空白，结果是纯文本）。
+ */
+import { AgentSessionImpl } from "../agent/session.js";
+import { MISS_NOTICE_TOKENS, MISS_NOTICE_USD } from "../ai/cache/miss.js";
+import { KeyValue } from "../tui/components/key-value.js";
+const REPORT_WIDTH = 240;
+/** `950`、`38.2k`、`150k`、`1.05M`（比状态栏多一位精度，面板与提示用）。 */
+export function formatTokenCount(count) {
+    const trim = (text) => text.replace(/\.?0+$/, "");
+    if (count < 1000)
+        return String(Math.round(count));
+    if (count < 100_000)
+        return `${trim((count / 1000).toFixed(1))}k`;
+    if (count < 1_000_000)
+        return `${Math.round(count / 1000)}k`;
+    return `${trim((count / 1_000_000).toFixed(2))}M`;
+}
+export function formatUsd(cost) {
+    if (cost === undefined)
+        return "$?";
+    return cost >= 0.01 || cost === 0 ? `$${cost.toFixed(2)}` : `$${cost.toFixed(3)}`;
+}
+export function formatPercent(rate) {
+    return rate === undefined ? "—" : `${Math.round(rate * 100)}%`;
+}
+/** `45s`、`2m 10s`、`7 分钟`（≥ 10 分钟只到分钟）。 */
+export function formatDuration(ms) {
+    const seconds = Math.max(0, Math.round(ms / 1000));
+    if (seconds < 60)
+        return `${seconds}s`;
+    const minutes = Math.floor(seconds / 60);
+    if (minutes >= 10)
+        return `${minutes}m`;
+    const rest = seconds % 60;
+    return rest === 0 ? `${minutes}m` : `${minutes}m ${rest}s`;
+}
+export function reportingLabel(reporting) {
+    return reporting === "reported" ? "reported" : reporting === "silent" ? "未报告" : "未知";
+}
+const REASON_LABELS = {
+    prefix_changed: "前缀变化",
+    model_changed: "切换模型",
+    idle: "空闲超时",
+    subtask: "子任务",
+    evicted: "服务端淘汰",
+};
+/** 未命中原因的短语（提示行括号里那段）。 */
+export function missReasonText(miss) {
+    const minutes = Math.max(1, Math.round(miss.idleMs / 60_000));
+    switch (miss.reason) {
+        case "idle":
+            return `空闲 ${minutes} 分钟后`;
+        case "subtask":
+            return `子任务运行 ${minutes} 分钟后`;
+        case "model_changed":
+            return "切换模型后";
+        case "prefix_changed":
+            return miss.detail === "tools"
+                ? "工具表变化"
+                : miss.detail === "system"
+                    ? "系统提示变化"
+                    : "前缀变化";
+        case "evicted":
+            return "服务端已淘汰";
+    }
+}
+export function shouldNotifyMiss(miss) {
+    return (miss.missedTokens >= MISS_NOTICE_TOKENS ||
+        (miss.missedCost !== undefined && miss.missedCost >= MISS_NOTICE_USD));
+}
+/** `缓存未命中（空闲 7 分钟后）：重计费 38.2k token（约 $0.11）`。 */
+export function cacheMissNotice(miss) {
+    const cost = miss.missedCost === undefined ? "" : `（约 ${formatUsd(miss.missedCost)}）`;
+    return `缓存未命中（${missReasonText(miss)}）：重计费 ${formatTokenCount(miss.missedTokens)} token${cost}`;
+}
+/** `上下文已用 72%，约剩 9 回合（按最近 5 回合均值）`；估不出回合时给余量 token。 */
+export function contextPressureNotice(event) {
+    const head = `上下文已用 ${Math.round(event.percent)}%`;
+    if (event.estimatedTurnsLeft !== undefined)
+        return `${head}，约剩 ${event.estimatedTurnsLeft} 回合（按最近 5 回合均值）`;
+    if (event.remainingTokens !== undefined)
+        return `${head}，余量 ${formatTokenCount(event.remainingTokens)} token`;
+    return head;
+}
+/**
+ * 缓存事件 → 消息区 / stderr 的一行提示；不提示时 undefined。`enabled` = `cache.missNotices`。
+ * 未命中只提示超过门槛的那次；70% 为 warn、90% 为 error；保温事件不进消息区（状态栏 ♨）。
+ */
+export function cacheEventNotice(event, enabled) {
+    if (!enabled)
+        return undefined;
+    if (event.type === "cache_miss") {
+        const { type: _type, ...miss } = event;
+        return shouldNotifyMiss(miss) ? { level: "warn", text: cacheMissNotice(miss) } : undefined;
+    }
+    if (event.type === "context_pressure") {
+        return { level: event.threshold >= 90 ? "error" : "warn", text: contextPressureNotice(event) };
+    }
+    return undefined;
+}
+/** 保温请求发出后的一行（line 模式只在 `AMA_LOG=info|debug` 时写 stderr）。 */
+export function warmSentNotice(event) {
+    if (event.phase !== "sent")
+        return undefined;
+    const read = event.usage === undefined ? "" : `读 ${formatTokenCount(event.usage.cacheRead)} token`;
+    const cost = event.cost === undefined ? "" : `${read !== "" ? "，" : ""}${formatUsd(event.cost)}`;
+    return `缓存保温已刷新${read + cost !== "" ? `（${read}${cost}）` : ""}`;
+}
+/** 消息区 / stderr 是否提示未命中与上下文余量（`cache.missNotices`，缺省 true）。 */
+export function cacheNoticesEnabled(session) {
+    return session instanceof AgentSessionImpl ? session.cache.cacheSettings.missNotices : true;
+}
+const STOP_REASONS = {
+    retention_none: "缓存保留为 none",
+    payload_replaced: "请求体被 onPayload 替换",
+    thinking_budget: "思考预算随 max_tokens，不可重放",
+    reporting_unknown: "端点还没报过缓存",
+    reporting_silent: "端点不报缓存",
+    no_ttl: "模型目录没有缓存 TTL",
+    ttl_too_short: "缓存 TTL 太短",
+    max_duration: "已达保温时长上限",
+    late: "计时器迟到",
+    off: "已关闭",
+    stale: "上下文已变",
+    declined: "宿主否决",
+    error: "保温请求失败",
+    no_cache_hits: "连续保温零命中",
+    no_price: "缺价格，经济性不可算",
+    below_min_savings: "期望节省低于门槛",
+};
+export function warmStopText(reason) {
+    if (reason === undefined)
+        return "已停止";
+    return `已停止：${STOP_REASONS[reason] ?? reason}`;
+}
+/** `streaming · 下次 2m 10s · 期望节省 $0.18 ≥ $0.05 · 已发 2 次 $0.01`。 */
+export function warmingText(status, now, minSavingsUsd) {
+    if (status.mode === "off")
+        return "off";
+    const parts = [status.mode];
+    if (status.state === "scheduled") {
+        if (status.nextWarmAt !== undefined)
+            parts.push(`下次 ${formatDuration(status.nextWarmAt - now)}`);
+        if (status.expectedSavingsUsd !== undefined) {
+            const floor = minSavingsUsd === undefined ? "" : ` ≥ ${formatUsd(minSavingsUsd)}`;
+            parts.push(`期望节省 ${formatUsd(status.expectedSavingsUsd)}${floor}`);
+        }
+    }
+    else if (status.state === "stopped")
+        parts.push(warmStopText(status.reason));
+    else
+        parts.push("待下一次请求");
+    if (status.sent !== undefined && status.sent > 0)
+        parts.push(`已发 ${status.sent} 次 ${formatUsd(status.costUsd)}`);
+    return parts.join(" · ");
+}
+function missesText(cache) {
+    if (cache.misses.count === 0)
+        return "0 次";
+    const by = Object.entries(cache.misses.byReason)
+        .filter(([, n]) => n !== undefined && n > 0)
+        .map(([reason, n]) => `${REASON_LABELS[reason] ?? reason} ${n}`)
+        .join(" · ");
+    const cost = cache.reBilledUsd === undefined ? "$?" : formatUsd(cache.reBilledUsd);
+    return `${cache.misses.count} 次，重计费 ${formatTokenCount(cache.reBilledTokens)} token ≈ ${cost}${by !== "" ? `（${by}）` : ""}`;
+}
+/** 缓存段的键值行（`/session` 与 `/cache` 共用）。 */
+export function cacheRows(session, now = Date.now()) {
+    const stats = session.getStats();
+    const t = stats.tokens;
+    const prompt = t.input + t.cacheRead + t.cacheWrite;
+    const uncached = t.input + t.cacheWrite;
+    const readShare = prompt > 0 ? `（${formatPercent(t.cacheRead / prompt)}）` : " ";
+    const write = t.cacheWrite > 0 ? `（其中写入 ${formatTokenCount(t.cacheWrite)}）` : "";
+    const rows = [
+        {
+            key: "输入",
+            value: `${formatTokenCount(prompt)} = 缓存读 ${formatTokenCount(t.cacheRead)}${readShare}+ 未缓存 ${formatTokenCount(uncached)}${write}`,
+        },
+    ];
+    const cache = stats.cache;
+    if (cache === undefined) {
+        rows.push({ key: "命中率", value: `会话 ${formatPercent(stats.cacheHitRate)}` });
+        return rows;
+    }
+    rows.push({ key: "报告状态", value: reportingLabel(cache.reporting) });
+    if (cache.reporting === "reported") {
+        rows.push({
+            key: "命中率",
+            value: `最近 ${formatPercent(cache.lastHitRate)} · 会话 ${formatPercent(cache.hitRate)}`,
+        });
+    }
+    rows.push({ key: "未命中", value: missesText(cache) });
+    const minSavings = session instanceof AgentSessionImpl ? session.cache.cacheSettings.minSavingsUsd : undefined;
+    rows.push({ key: "保温", value: warmingText(cache.warming, now, minSavings) });
+    if (stats.contextPercent !== undefined) {
+        const remaining = cache.contextRemainingTokens === undefined
+            ? ""
+            : `，余量 ≈ ${formatTokenCount(cache.contextRemainingTokens)} token`;
+        const turns = cache.estimatedTurnsLeft === undefined ? "" : ` ≈ ${cache.estimatedTurnsLeft} 回合`;
+        rows.push({ key: "上下文", value: `${Math.round(stats.contextPercent)}%${remaining}${turns}` });
+    }
+    if (cache.subagents !== undefined) {
+        const sub = cache.subagents;
+        const rebill = sub.reBilledTokens > 0 ? `，重计费 ${formatTokenCount(sub.reBilledTokens)} token` : "";
+        rows.push({
+            key: "子任务",
+            value: `${sub.count} 个会话，命中率 ${formatPercent(sub.hitRate)}${rebill}`,
+        });
+    }
+    return rows;
+}
+/** 键值行 → 纯文本（键列对齐、去行尾空白）。 */
+export function renderRows(rows, indent = "") {
+    return new KeyValue(rows)
+        .render(REPORT_WIDTH)
+        .map((line) => (line === "" ? "" : `${indent}${line}`.replace(/\s+$/, "")));
+}
+export function describeCache(session, now = Date.now()) {
+    return ["缓存", ...renderRows(cacheRows(session, now), "  ")].join("\n");
+}
+export function describeSession(session, now = Date.now()) {
+    const state = session.state;
+    const stats = session.getStats();
+    const model = state.model === undefined ? "?" : `${state.model.provider}/${state.model.id}`;
+    const t = stats.tokens;
+    const percent = stats.contextPercent === undefined ? "?" : `${Math.round(stats.contextPercent)}`;
+    const rows = [
+        {
+            key: "会话",
+            value: `${state.sessionId}${state.sessionFile !== undefined ? `（${state.sessionFile}）` : "（未落盘）"}`,
+        },
+        {
+            key: "模型",
+            value: `${model} · 思考 ${state.thinkingLevel} · 权限 ${state.permissionMode}`,
+        },
+        {
+            key: "消息",
+            value: `用户 ${stats.userMessages} · 助手 ${stats.assistantMessages} · 工具调用 ${stats.toolCalls}`,
+        },
+        {
+            key: "用量",
+            value: `输入 ${t.input} · 输出 ${t.output} · 缓存读 ${t.cacheRead} · 缓存写 ${t.cacheWrite}` +
+                (stats.cost !== undefined ? ` · $${stats.cost.toFixed(4)}` : " · $?"),
+        },
+        {
+            key: "上下文",
+            value: `${stats.contextTokens ?? "?"} / ${stats.contextWindow ?? "?"}（${percent}%）`,
+        },
+    ];
+    return [...renderRows(rows), describeCache(session, now)].join("\n");
+}
+/** `/cache fingerprint`：最近一次真实请求的前缀指纹（system / tools 哈希与模型）。 */
+export function describeFingerprint(session) {
+    if (!(session instanceof AgentSessionImpl))
+        return "当前会话不提供前缀指纹";
+    const record = session.cache.lastTurn;
+    if (record === undefined)
+        return "还没有真实请求（指纹在第一次请求后记录）";
+    const f = record.fingerprint;
+    return [
+        "前缀指纹（最近一次请求）",
+        ...renderRows([
+            { key: "system", value: f.system },
+            { key: "tools", value: f.tools },
+            { key: "model", value: f.model },
+        ], "  "),
+    ].join("\n");
+}

package/dist/modes/shared.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 模式层共用的小工具：最后一条助手消息、信号处理、错误文本。[B6]
+ */
+import type { AgentSession } from "../agent/types.js";
+import type { AssistantMessage } from "../ai/types.js";
+export declare function lastAssistant(session: AgentSession): AssistantMessage | undefined;
+export declare function errorText(error: unknown): string;
+/**
+ * 装 SIGINT / SIGTERM：调用 `onSignal(退出码)`；返回卸载函数。只在当前模式运行期间生效
+ * （设计 §11.1 第 1 步：信号交给当前模式）。
+ */
+export declare function onTerminationSignals(onSignal: (exitCode: number) => void): () => void;
+export declare function onStdoutClosed(onClosed: () => void): () => void;

package/dist/modes/shared.js

@@ -0,0 +1,52 @@
+/**
+ * 模式层共用的小工具：最后一条助手消息、信号处理、错误文本。[B6]
+ */
+import { ExitCode } from "../cli/exit-codes.js";
+export function lastAssistant(session) {
+    for (let i = session.messages.length - 1; i >= 0; i--) {
+        const message = session.messages[i];
+        if (message?.role === "assistant")
+            return message;
+    }
+    return undefined;
+}
+export function errorText(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * 装 SIGINT / SIGTERM：调用 `onSignal(退出码)`；返回卸载函数。只在当前模式运行期间生效
+ * （设计 §11.1 第 1 步：信号交给当前模式）。
+ */
+export function onTerminationSignals(onSignal) {
+    const sigint = () => onSignal(ExitCode.Sigint);
+    const sigterm = () => onSignal(ExitCode.Sigterm);
+    process.on("SIGINT", sigint);
+    process.on("SIGTERM", sigterm);
+    return () => {
+        process.off("SIGINT", sigint);
+        process.off("SIGTERM", sigterm);
+    };
+}
+/**
+ * stdout 被下游提前关闭（`| head`）时不当作未捕获异常：调用 onClosed 并吞掉 EPIPE。
+ * 进程内只装一个监听器、留到进程结束（之后的写入也可能再报 EPIPE）；返回的函数只摘掉回调——
+ * 同一进程里多次运行 print 模式（SDK、测试）不会累积监听器。
+ */
+const stdoutClosedHandlers = new Set();
+let stdoutErrorListening = false;
+export function onStdoutClosed(onClosed) {
+    if (!stdoutErrorListening) {
+        stdoutErrorListening = true;
+        process.stdout.on("error", (error) => {
+            if (error.code !== "EPIPE")
+                throw error;
+            for (const handler of [...stdoutClosedHandlers])
+                handler();
+        });
+    }
+    const handler = () => onClosed();
+    stdoutClosedHandlers.add(handler);
+    return () => {
+        stdoutClosedHandlers.delete(handler);
+    };
+}

package/dist/modes/startup-ui-text.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 启动期问答的文本回退（`--no-tui`、stdout 非 TTY、`TERM=dumb`）：问题写 stderr，从 stdin 读一行。
+ * 与 `interactive/startup-ui.ts` 同一组 `InteractiveUi` 回调，但不加载终端组件库。[W3-B9a-1]
+ *
+ * 读一行只消费到换行为止，多读的部分 `unshift` 回流里，留给随后的行式界面；EOF = 取消。
+ */
+import type { InteractiveUi } from "../cli/deps.js";
+export interface TextUiIo {
+    stdin: NodeJS.ReadableStream & {
+        readableEnded?: boolean;
+    };
+    write(text: string): void;
+}
+/** 读一行（不含行尾）；EOF 且无内容返回 undefined。 */
+export declare function readOneLine(stdin: TextUiIo["stdin"]): Promise<string | undefined>;
+export declare function createTextStartupUi(io: TextUiIo): Required<InteractiveUi>;

package/dist/modes/startup-ui-text.js

@@ -0,0 +1,103 @@
+/**
+ * 启动期问答的文本回退（`--no-tui`、stdout 非 TTY、`TERM=dumb`）：问题写 stderr，从 stdin 读一行。
+ * 与 `interactive/startup-ui.ts` 同一组 `InteractiveUi` 回调，但不加载终端组件库。[W3-B9a-1]
+ *
+ * 读一行只消费到换行为止，多读的部分 `unshift` 回流里，留给随后的行式界面；EOF = 取消。
+ */
+import { existsSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+/** 读一行（不含行尾）；EOF 且无内容返回 undefined。 */
+export function readOneLine(stdin) {
+    if (stdin.readableEnded === true)
+        return Promise.resolve(undefined);
+    return new Promise((done) => {
+        let buffer = "";
+        const finish = (line, rest) => {
+            stdin.off("data", onData);
+            stdin.off("end", onEnd);
+            stdin.pause();
+            if (rest !== "")
+                stdin.unshift(Buffer.from(rest));
+            done(line);
+        };
+        const onData = (chunk) => {
+            buffer += chunk.toString();
+            const at = buffer.indexOf("\n");
+            if (at >= 0)
+                finish(buffer.slice(0, at).replace(/\r$/, ""), buffer.slice(at + 1));
+        };
+        const onEnd = () => finish(buffer === "" ? undefined : buffer, "");
+        stdin.on("data", onData);
+        stdin.on("end", onEnd);
+        stdin.resume();
+    });
+}
+/** 按编号或值（前缀唯一）选一项；空行 / 无匹配 / EOF 返回 undefined。 */
+function choose(answer, values) {
+    const text = answer?.trim() ?? "";
+    if (text === "")
+        return undefined;
+    const index = Number(text);
+    if (Number.isInteger(index) && index >= 1 && index <= values.length)
+        return values[index - 1];
+    if (values.includes(text))
+        return text;
+    const matches = values.filter((value) => value.startsWith(text));
+    return matches.length === 1 ? matches[0] : undefined;
+}
+function isDirectory(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+export function createTextStartupUi(io) {
+    const ask = async (lines, question) => {
+        io.write([...lines, question].join("\n"));
+        return readOneLine(io.stdin);
+    };
+    const list = (values, labels) => values.map((_, i) => `  ${i + 1}. ${labels[i]}`);
+    return {
+        async promptTrust(cwd, resources) {
+            const shown = resources.slice(0, 6).map((p) => `  ${p}`);
+            if (resources.length > shown.length)
+                shown.push(`  …另有 ${resources.length - shown.length} 项`);
+            const answer = await ask([`信任这个目录的项目资源？${cwd}`, ...shown], "[y 仅本次 / a 信任并记住 / N 不信任] ");
+            const key = answer?.trim().toLowerCase();
+            if (key === "a")
+                return { trusted: true, remember: true };
+            return { trusted: key === "y" || key === "yes", remember: false };
+        },
+        async pickSession(items) {
+            if (items.length === 0)
+                return undefined;
+            const sorted = [...items].sort((a, b) => b.modifiedAt.localeCompare(a.modifiedAt));
+            const ids = sorted.map((item) => item.id);
+            const labels = sorted.map((item) => `${item.id.slice(0, 8)}  ${(item.name ?? item.firstPrompt ?? "").replace(/\s+/g, " ").slice(0, 60)}`);
+            return choose(await ask(["恢复哪个会话？", ...list(ids, labels)], "编号或 id："), ids);
+        },
+        async pickModel(providers, reason) {
+            const refs = [];
+            for (const provider of providers.list())
+                for (const model of provider.models)
+                    refs.push(`${provider.id}/${model.id}`);
+            if (refs.length === 0)
+                return undefined;
+            const answer = await ask([reason, "选择模型：", ...list(refs, refs)], "编号或 provider/id：");
+            return choose(answer, refs);
+        },
+        async askCwd(missing) {
+            const answer = (await ask([`会话的工作目录不存在：${missing}`], "替代目录（空行取消）："))?.trim();
+            if (answer === undefined || answer === "")
+                return undefined;
+            const abs = resolve(answer);
+            if (!existsSync(abs) || !isDirectory(abs)) {
+                io.write(`不是目录：${abs}\n`);
+                return undefined;
+            }
+            return abs;
+        },
+    };
+}

package/dist/permissions/broker.d.ts

@@ -0,0 +1,47 @@
+/**
+ * ApprovalBroker 链（设计 §6.3 第 4 步、§7.1）。[B3]
+ *
+ * - 回答者顺序：宿主 broker（`HostApi.approvals.setBroker`）→ UI broker（TUI 对话框 / RPC 客户端 /
+ *   SDK 回调）→ 无人值守 deny。回答者返回 undefined 表示交给下一个；抛错按 deny（fail-safe）。
+ * - 超时（缺省 10 min）→ deny；父 signal abort → deny。
+ * - 审批**串行化**：同一时刻只有一个请求在等回答（task 子 Agent 的审批排到父对话框之后）。
+ * - `allow_session` → 调 `pipeline.rememberForSession()` 后放行。
+ * - `authorize()`：管线判定 + 需要时走 broker，给 tool-runner（B2）一个单入口。
+ */
+import type { ApprovalBroker, ApprovalDecision, ApprovalRequest, PermissionCheckInput, PermissionPipelineApi, PermissionVerdict } from "./types.js";
+export declare const DEFAULT_APPROVAL_TIMEOUT_MS: number;
+export interface BrokerChainOptions {
+    timeoutMs?: number;
+    onRequested?(request: ApprovalRequest): void;
+    onResolved?(request: ApprovalRequest, decision: ApprovalDecision, by: AnsweredBy): void;
+    log?(level: "debug" | "info" | "warn", message: string): void;
+}
+export type AnsweredBy = "host" | "ui" | "timeout" | "aborted" | "unattended" | "error";
+export declare class ApprovalBrokerChain {
+    private readonly options;
+    private host;
+    private ui;
+    private queue;
+    constructor(options?: BrokerChainOptions);
+    setHostBroker(broker: ApprovalBroker | undefined): void;
+    setUiBroker(broker: ApprovalBroker | undefined): void;
+    /** 有没有可能回答的人；没有则调用方应按无人值守处理。 */
+    hasResponder(): boolean;
+    /** 串行排队后询问；总会给出决定。 */
+    ask(request: ApprovalRequest, signal: AbortSignal): Promise<ApprovalDecision>;
+    private askNow;
+}
+export interface AuthorizeResult {
+    allowed: boolean;
+    verdict: PermissionVerdict;
+    /** 走了 broker 时的回答。 */
+    decision?: ApprovalDecision;
+    /** 拒绝时给 tool_result 的说明。 */
+    message?: string;
+}
+export interface AuthorizeOptions {
+    signal: AbortSignal;
+    requestId?: string;
+}
+/** 管线 + broker 的单入口。`input.unattended` 由调用方按「是否有回答者」等决定。 */
+export declare function authorize(pipeline: PermissionPipelineApi, chain: ApprovalBrokerChain, input: PermissionCheckInput, options: AuthorizeOptions): Promise<AuthorizeResult>;

package/dist/permissions/broker.js

@@ -0,0 +1,107 @@
+/**
+ * ApprovalBroker 链（设计 §6.3 第 4 步、§7.1）。[B3]
+ *
+ * - 回答者顺序：宿主 broker（`HostApi.approvals.setBroker`）→ UI broker（TUI 对话框 / RPC 客户端 /
+ *   SDK 回调）→ 无人值守 deny。回答者返回 undefined 表示交给下一个；抛错按 deny（fail-safe）。
+ * - 超时（缺省 10 min）→ deny；父 signal abort → deny。
+ * - 审批**串行化**：同一时刻只有一个请求在等回答（task 子 Agent 的审批排到父对话框之后）。
+ * - `allow_session` → 调 `pipeline.rememberForSession()` 后放行。
+ * - `authorize()`：管线判定 + 需要时走 broker，给 tool-runner（B2）一个单入口。
+ */
+import { randomUUID } from "node:crypto";
+export const DEFAULT_APPROVAL_TIMEOUT_MS = 10 * 60 * 1000;
+export class ApprovalBrokerChain {
+    options;
+    host;
+    ui;
+    queue = Promise.resolve();
+    constructor(options = {}) {
+        this.options = options;
+    }
+    setHostBroker(broker) {
+        this.host = broker;
+    }
+    setUiBroker(broker) {
+        this.ui = broker;
+    }
+    /** 有没有可能回答的人；没有则调用方应按无人值守处理。 */
+    hasResponder() {
+        return this.host !== undefined || this.ui !== undefined;
+    }
+    /** 串行排队后询问；总会给出决定。 */
+    ask(request, signal) {
+        const run = this.queue.then(() => this.askNow(request, signal));
+        this.queue = run.catch(() => undefined);
+        return run;
+    }
+    async askNow(request, signal) {
+        this.options.onRequested?.(request);
+        const finish = (decision, by) => {
+            this.options.onResolved?.(request, decision, by);
+            return decision;
+        };
+        if (signal.aborted)
+            return finish("deny", "aborted");
+        const timeout = new AbortController();
+        const timer = setTimeout(() => timeout.abort(), this.options.timeoutMs ?? DEFAULT_APPROVAL_TIMEOUT_MS);
+        const combined = AbortSignal.any([signal, timeout.signal]);
+        const stopped = new Promise((resolve) => {
+            if (combined.aborted)
+                resolve("stopped");
+            combined.addEventListener("abort", () => resolve("stopped"), { once: true });
+        });
+        try {
+            const responders = [
+                ["host", this.host],
+                ["ui", this.ui],
+            ];
+            for (const [by, broker] of responders) {
+                if (!broker)
+                    continue;
+                let answer;
+                try {
+                    answer = await Promise.race([broker.ask(request, combined), stopped]);
+                }
+                catch (err) {
+                    this.options.log?.("warn", `approval broker (${by}) failed: ${err.message}`);
+                    return finish("deny", "error");
+                }
+                if (answer === "stopped")
+                    return finish("deny", signal.aborted ? "aborted" : "timeout");
+                if (answer === "allow" || answer === "deny" || answer === "allow_session") {
+                    return finish(answer, by);
+                }
+            }
+            return finish("deny", "unattended");
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+/** 管线 + broker 的单入口。`input.unattended` 由调用方按「是否有回答者」等决定。 */
+export async function authorize(pipeline, chain, input, options) {
+    const verdict = pipeline.check(input);
+    if (verdict.decision === "allow")
+        return { allowed: true, verdict };
+    if (verdict.decision === "deny") {
+        return { allowed: false, verdict, message: verdict.message ?? "Permission denied" };
+    }
+    const reason = verdict.approvalReason ?? "mode";
+    const request = {
+        requestId: options.requestId ?? randomUUID(),
+        toolName: input.toolName,
+        input: input.input,
+        reason,
+    };
+    const hookReason = reason === "hook" ? (input.hookReason ?? verdict.message) : undefined;
+    if (hookReason !== undefined)
+        request.hookReason = hookReason;
+    const decision = await chain.ask(request, options.signal);
+    if (decision === "allow_session")
+        pipeline.rememberForSession(input.toolName, input.input);
+    if (decision === "deny") {
+        return { allowed: false, verdict, decision, message: "The tool call was not approved." };
+    }
+    return { allowed: true, verdict, decision };
+}

package/dist/permissions/dangerous.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 危险命令表（设计 §7.2；v1 §7.1 的表 + `git branch -D`、`npm publish`、`docker system prune -a`、
+ * `shutdown/reboot`）。[B3]
+ *
+ * 命中 → 管线第 ② 步 ask（无人值守 deny），allow 规则不能越过。识别按段进行：命令先按
+ * `&&`、`||`、`;`、`|`、`&`、换行切段（引号内不切），每段剥掉前导的环境赋值与
+ * `sudo / command / exec / nohup / time / env` 等前缀后看命令名；`sh -c '…'`、`eval …`、`xargs …`、`find -exec … ;` 里的
+ * 命令递归识别，嵌套超过 {@link MAX_NESTING} 层按危险处理。整条命令另外做跨段检查
+ * （`curl … | sh`、fork 炸弹）。每条规则都有正例与反例测试（dangerous.test.ts）。
+ */
+export interface DangerousRule {
+    id: string;
+    description: string;
+    /** 段级检查：`argv` 是剥掉前缀后的词，`segment` 是原段文本。 */
+    segment?(argv: readonly string[], segment: string): boolean;
+    /** 整条命令检查。 */
+    whole?(command: string): boolean;
+}
+export interface DangerousMatch {
+    id: string;
+    description: string;
+}
+/**
+ * 分词：按未加引号的空白切；单引号内原样，双引号内反斜杠只转义 `\`、`"`、`$`、反引号，引号外反斜杠转义下一个字符；
+ * 相邻的引号段与普通字符拼成一个词（`'a'"b"c` → `abc`）。不做变量与通配展开。
+ */
+export declare function shellWords(segment: string): string[];
+/** 剥前缀；`keepSudo` 为假时连 sudo 一并剥掉。 */
+export declare function commandWords(segment: string, keepSudo?: boolean): string[];
+export declare const DANGEROUS_RULES: readonly DangerousRule[];
+/** 嵌套层数上限：`sh -c` / `eval` 等每包一层计一层，超过按危险处理。 */
+export declare const MAX_NESTING = 3;
+/**
+ * 段内嵌套的命令文本（剥过前缀的 argv）：`sh / bash / zsh / dash / ksh -c '…'` 的字符串参数；
+ * `eval` 其余词以空格拼接；`xargs` 要执行的命令；`find -exec … ;` 里的命令。
+ */
+export declare function nestedCommands(argv: readonly string[]): string[];
+export interface NestedCommands {
+    /** 各层嵌套命令文本（不含最外层），按出现顺序。 */
+    commands: string[];
+    /** 是否有超过 {@link MAX_NESTING} 层的嵌套（其内容未展开）。 */
+    tooDeep: boolean;
+}
+/** 整条命令里所有嵌套的命令文本，供 allow / deny 规则与会话记忆逐层核对。 */
+export declare function collectNestedCommands(command: string): NestedCommands;
+/** 第一条命中的危险规则；无则 undefined。嵌套命令（{@link nestedCommands}）递归识别。 */
+export declare function matchDangerous(command: string, depth?: number): DangerousMatch | undefined;