@armadra/agent 0.0.0-stage → 0.3.0

package/dist/modes/rpc/commands.js

@@ -0,0 +1,263 @@
+/**
+ * RPC 命令分派表（设计 §13.2、src/rpc.ts 的 33 条命令）。[B6]
+ *
+ * - 提示类（prompt / steer / follow_up）不等运行结束：会话开始运行（`before_agent_start` /
+ *   `agent_start`）、入队或被处理后立刻应答 `{ disposition }`；运行中的进展走事件。
+ * - 会话类（new_session / switch_session / fork）经组装根 `switchSession`，`ctx.onSessionChanged`
+ *   让模式重新订阅事件。
+ * - 审批：`RpcApprovals` 是 UI broker（`set_client_capabilities` 声明 approvals 后挂上），
+ *   `permission_response` 按 requestId 作答；先到的回答暂存，等 broker 被问到时取用。
+ * - 密钥不离开进程：`get_available_models` 只回 `hasKey` 与 `keySource`。
+ */
+import { formatModelRef } from "../../ai/providers/channels.js";
+import { AgentSessionImpl } from "../../agent/session.js";
+import { getSupportedLevels } from "../../ai/thinking.js";
+import { switchSession } from "../../cli/compose-session.js";
+import { AmaError } from "../../errors.js";
+import { BUILTIN_COMMANDS } from "../commands-core.js";
+/** 审批 broker：等客户端 `permission_response`。 */
+export class RpcApprovals {
+    pending = new Map();
+    early = new Map();
+    ask(request, signal) {
+        const ready = this.early.get(request.requestId);
+        if (ready !== undefined) {
+            this.early.delete(request.requestId);
+            return Promise.resolve(ready);
+        }
+        return new Promise((resolve) => {
+            const done = (decision) => {
+                this.pending.delete(request.requestId);
+                signal.removeEventListener("abort", onAbort);
+                resolve(decision);
+            };
+            const onAbort = () => done(undefined);
+            if (signal.aborted)
+                return done(undefined);
+            signal.addEventListener("abort", onAbort, { once: true });
+            this.pending.set(request.requestId, done);
+        });
+    }
+    /** 返回 false = 当前没有在等这个 requestId（已暂存，稍后被问到时生效）。 */
+    respond(requestId, decision) {
+        const resolve = this.pending.get(requestId);
+        if (resolve !== undefined) {
+            resolve(decision);
+            return true;
+        }
+        this.early.set(requestId, decision);
+        return false;
+    }
+    /** 关 stdin / 撤下时：全部弃权（会话按无人作答 deny）。 */
+    cancelAll() {
+        for (const resolve of [...this.pending.values()])
+            resolve(undefined);
+        this.early.clear();
+    }
+}
+function impl(session) {
+    if (session instanceof AgentSessionImpl)
+        return session;
+    throw new AmaError("not_implemented", "该会话不支持此命令");
+}
+/** 开始一次运行：开始 / 入队 / 被处理后即返回，不等运行结束。 */
+async function startRun(ctx, run) {
+    const session = ctx.session();
+    let settled = false;
+    let off = () => undefined;
+    const started = new Promise((resolve) => {
+        off = session.subscribe((event) => {
+            if (event.type === "before_agent_start" || event.type === "agent_start")
+                resolve("started");
+        });
+    });
+    const running = run().finally(() => {
+        settled = true;
+    });
+    try {
+        const first = await Promise.race([running, started]);
+        if (!settled)
+            running.catch((error) => ctx.onBackgroundError(error));
+        return { disposition: first };
+    }
+    finally {
+        off();
+    }
+}
+async function switched(ctx, next, reason) {
+    const session = await next;
+    ctx.onSessionChanged(session);
+    if (session instanceof AgentSessionImpl)
+        session.announceStart(reason);
+    return { sessionId: session.state.sessionId, sessionFile: session.state.sessionFile };
+}
+async function availableModels(runtime) {
+    const out = [];
+    for (const provider of runtime.providers.list()) {
+        const key = await runtime.providers.resolveApiKey(provider.id);
+        const hasKey = key.apiKey !== undefined || !provider.requiresApiKey;
+        for (const model of provider.models) {
+            const info = {
+                provider: provider.id,
+                id: model.id,
+                name: model.name,
+                hasKey,
+                keySource: key.apiKey !== undefined ? key.source : "none",
+                maxTokens: model.maxTokens,
+                reasoning: model.reasoning,
+                input: [...model.input],
+            };
+            if (model.contextWindow !== undefined)
+                info.contextWindow = model.contextWindow;
+            out.push(info);
+        }
+    }
+    return out;
+}
+function commands(runtime) {
+    return [
+        ...BUILTIN_COMMANDS.map((c) => ({
+            name: c.name,
+            description: c.description,
+            source: "builtin",
+        })),
+        ...runtime.resources.prompts.map((p) => ({ name: p.name, source: "template" })),
+        ...runtime.resources.skills.map((s) => ({
+            name: `skill:${s.name}`,
+            description: s.description,
+            source: "skill",
+        })),
+    ];
+}
+export const handlers = {
+    prompt: (p, ctx) => startRun(ctx, () => ctx.session().prompt(p.message, {
+        ...(p.images !== undefined ? { images: p.images } : {}),
+        ...(p.streamingBehavior !== undefined ? { streamingBehavior: p.streamingBehavior } : {}),
+    })),
+    steer: (p, ctx) => startRun(ctx, () => ctx.session().steer(p.message)),
+    follow_up: (p, ctx) => startRun(ctx, () => ctx.session().followUp(p.message)),
+    abort: async (_p, ctx) => {
+        await ctx.session().abort();
+        return {};
+    },
+    clear_queue: async (_p, ctx) => ctx.session().clearQueue(),
+    get_state: async (_p, ctx) => ctx.session().state,
+    get_messages: async (_p, ctx) => ({ messages: ctx.session().messages }),
+    get_last_assistant_text: async (_p, ctx) => ({ text: ctx.session().getLastAssistantText() }),
+    // [W3-C2] 含 `cache`（三态、最近 / 会话命中率、未命中、保温、余量；第三波 §1.10）。
+    get_session_stats: async (_p, ctx) => ctx.session().getStats(),
+    set_model: async (p, ctx) => {
+        await ctx.session().setModel(formatModelRef({
+            provider: p.provider,
+            id: p.modelId,
+            ...(p.channel !== undefined ? { channel: p.channel } : {}),
+        }));
+        return { model: ctx.session().state.model };
+    },
+    get_available_models: async (_p, ctx) => ({ models: await availableModels(ctx.runtime) }),
+    set_thinking_level: async (p, ctx) => {
+        ctx.session().setThinkingLevel(p.level);
+        return { level: p.level };
+    },
+    get_available_thinking_levels: async (_p, ctx) => {
+        const ref = ctx.session().state.model;
+        const found = ref === undefined ? undefined : ctx.runtime.providers.findModel(formatModelRef(ref));
+        return { levels: found?.ok === true ? getSupportedLevels(found.model) : ["off"] };
+    },
+    set_steering_mode: async (p, ctx) => {
+        impl(ctx.session()).agent.steeringQueue.mode = p.mode;
+        return { mode: p.mode };
+    },
+    set_follow_up_mode: async (p, ctx) => {
+        impl(ctx.session()).agent.followUpQueue.mode = p.mode;
+        return { mode: p.mode };
+    },
+    compact: async (p, ctx) => ctx.session().compact(p.customInstructions),
+    set_auto_compaction: async (p, ctx) => {
+        impl(ctx.session()).setAutoCompaction(p.enabled);
+        return { enabled: p.enabled };
+    },
+    set_auto_retry: async (p, ctx) => {
+        impl(ctx.session()).setAutoRetry(p.enabled);
+        return { enabled: p.enabled };
+    },
+    abort_retry: async (_p, ctx) => {
+        const session = ctx.session();
+        const retrying = session.state.isRetrying;
+        if (retrying)
+            await session.abort();
+        return { aborted: retrying };
+    },
+    new_session: (_p, ctx) => switched(ctx, switchSession(ctx.runtime, { kind: "new" }), "new"),
+    switch_session: (p, ctx) => switched(ctx, switchSession(ctx.runtime, { kind: "open", file: p.sessionPath }), "resume"),
+    fork: (p, ctx) => switched(ctx, switchSession(ctx.runtime, { kind: "fork", entryId: p.entryId }), "fork"),
+    get_entries: async (p, ctx) => impl(ctx.session()).manager.getEntries(p.since),
+    get_tree: async (_p, ctx) => ({ tree: impl(ctx.session()).manager.getTree() }),
+    set_session_name: async (p, ctx) => {
+        impl(ctx.session()).manager.setName(p.name);
+        return { name: p.name };
+    },
+    get_fork_messages: async (_p, ctx) => ({
+        messages: impl(ctx.session())
+            .manager.branch()
+            .flatMap((entry) => entry.type === "message" && entry.message.role === "user"
+            ? [
+                {
+                    entryId: entry.id,
+                    text: typeof entry.message.content === "string"
+                        ? entry.message.content
+                        : entry.message.content.map((b) => (b.type === "text" ? b.text : "")).join(""),
+                },
+            ]
+            : []),
+    }),
+    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();
+        return { capabilities: [...ctx.capabilities] };
+    },
+    permission_response: async (p, ctx) => ({
+        accepted: ctx.approvals.respond(p.requestId, p.decision),
+    }),
+    get_tools: async (_p, ctx) => {
+        const active = new Set(ctx
+            .session()
+            .getTools()
+            .map((t) => t.name));
+        return {
+            tools: ctx.runtime.tools.list().flatMap((name) => {
+                const tool = ctx.runtime.tools.get(name);
+                return tool === undefined
+                    ? []
+                    : [
+                        {
+                            name,
+                            description: tool.description,
+                            parameters: tool.parameters,
+                            permission: tool.permission,
+                            active: active.has(name),
+                        },
+                    ];
+            }),
+        };
+    },
+    set_active_tools: async (p, ctx) => {
+        ctx.session().setActiveTools(p.names);
+        return {
+            names: ctx
+                .session()
+                .getTools()
+                .map((t) => t.name),
+        };
+    },
+    set_permission_mode: async (p, ctx) => {
+        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 }),
+};
+export const RPC_COMMAND_TYPES = Object.keys(handlers);

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

@@ -0,0 +1,16 @@
+/**
+ * JSONL 读写（设计 §13.2）。[B6]
+ *
+ * - 读：只按 `\n` 切行（不用 readline——它会在 U+2028 / U+2029 等处切），去掉行尾 `\r`，空行跳过；
+ *   多字节 UTF-8 跨 chunk 用 StringDecoder 拼接；流结束时把最后一段不带换行的行也交出去。
+ * - 写：一行拆成 ≤ 64 KiB 的片依次写入，遇到背压等 `drain`，保证大行（图片、长输出）不被截断、
+ *   行与行之间不交错（调用方串行 await）。
+ */
+export declare const WRITE_CHUNK_BYTES: number;
+export interface LineReader {
+    /** 停止监听（不关闭流）。 */
+    close(): void;
+}
+export declare function createLineReader(stream: NodeJS.ReadableStream, onLine: (line: string) => void, onEnd?: () => void): LineReader;
+/** 按 64 KiB 分片写入（背压时等 drain）。 */
+export declare function writeChunked(stream: NodeJS.WritableStream, text: string, chunkBytes?: number): Promise<void>;

package/dist/modes/rpc/jsonl.js

@@ -0,0 +1,55 @@
+/**
+ * JSONL 读写（设计 §13.2）。[B6]
+ *
+ * - 读：只按 `\n` 切行（不用 readline——它会在 U+2028 / U+2029 等处切），去掉行尾 `\r`，空行跳过；
+ *   多字节 UTF-8 跨 chunk 用 StringDecoder 拼接；流结束时把最后一段不带换行的行也交出去。
+ * - 写：一行拆成 ≤ 64 KiB 的片依次写入，遇到背压等 `drain`，保证大行（图片、长输出）不被截断、
+ *   行与行之间不交错（调用方串行 await）。
+ */
+import { StringDecoder } from "node:string_decoder";
+export const WRITE_CHUNK_BYTES = 64 * 1024;
+export function createLineReader(stream, onLine, onEnd) {
+    const decoder = new StringDecoder("utf8");
+    let buffer = "";
+    const emit = (raw) => {
+        const line = raw.endsWith("\r") ? raw.slice(0, -1) : raw;
+        if (line.trim() !== "")
+            onLine(line);
+    };
+    const onData = (chunk) => {
+        buffer += typeof chunk === "string" ? chunk : decoder.write(chunk);
+        let at = buffer.indexOf("\n");
+        while (at >= 0) {
+            emit(buffer.slice(0, at));
+            buffer = buffer.slice(at + 1);
+            at = buffer.indexOf("\n");
+        }
+    };
+    const finish = () => {
+        buffer += decoder.end();
+        if (buffer !== "")
+            emit(buffer);
+        buffer = "";
+        detach();
+        onEnd?.();
+    };
+    const detach = () => {
+        stream.off("data", onData);
+        stream.off("end", finish);
+        stream.off("close", finish);
+    };
+    stream.on("data", onData);
+    stream.once("end", finish);
+    stream.once("close", finish);
+    return { close: detach };
+}
+/** 按 64 KiB 分片写入（背压时等 drain）。 */
+export async function writeChunked(stream, text, chunkBytes = WRITE_CHUNK_BYTES) {
+    const bytes = Buffer.from(text, "utf8");
+    for (let offset = 0; offset < bytes.length; offset += chunkBytes) {
+        const piece = bytes.subarray(offset, Math.min(bytes.length, offset + chunkBytes));
+        if (!stream.write(piece)) {
+            await new Promise((resolve) => stream.once("drain", resolve));
+        }
+    }
+}

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

@@ -0,0 +1,22 @@
+/**
+ * RPC 模式（`ama --mode rpc`，设计 §13.2）：stdin 读命令、stdout 写响应与事件，每行一个 JSON。[B6]
+ *
+ * - 启动先发 `hello{protocolVersion, agent, version, capabilities}`，再发当前会话的 session_start。
+ * - 命令并发处理（prompt 不阻塞后续命令），响应带回请求的 `id`；解析失败 → `command: "parse"`。
+ * - 审批：客户端 `set_client_capabilities{capabilities:["approvals"]}` 之后才挂 UI broker；
+ *   之前的 ask 无人作答 → deny。`permission_request` 带 `timeoutMs`，超时由会话 deny 并发
+ *   `permission_resolved`。
+ * - 宿主 `ui.notify` → `{type:"notification", level, message}` 一行（stderr 同时一份）。
+ * - stdin 关闭：撤下审批（之后的 ask 无人作答 → deny）、等在途命令与已开始的运行结束、
+ *   应答写完 → 退出 0（会话由 runCli dispose）。`printf '{…prompt…}' | ama --mode rpc` 因此能拿到
+ *   完整回复；要中断先发 `abort`。SIGINT / SIGTERM：abort 后有序退出，退出码 130 / 143。
+ */
+import type { ModeContext } from "../../cli/deps.js";
+import type { Runtime } from "../../cli/runtime.js";
+import { type RpcHello } from "../../rpc.js";
+export interface RpcModeOptions {
+    stdin?: NodeJS.ReadableStream;
+    stdout?: NodeJS.WritableStream;
+}
+export declare const RPC_CAPABILITIES: RpcHello["capabilities"];
+export declare function runRpcMode(runtime: Runtime, context: ModeContext, options?: RpcModeOptions): Promise<number>;

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

@@ -0,0 +1,153 @@
+/**
+ * RPC 模式（`ama --mode rpc`，设计 §13.2）：stdin 读命令、stdout 写响应与事件，每行一个 JSON。[B6]
+ *
+ * - 启动先发 `hello{protocolVersion, agent, version, capabilities}`，再发当前会话的 session_start。
+ * - 命令并发处理（prompt 不阻塞后续命令），响应带回请求的 `id`；解析失败 → `command: "parse"`。
+ * - 审批：客户端 `set_client_capabilities{capabilities:["approvals"]}` 之后才挂 UI broker；
+ *   之前的 ask 无人作答 → deny。`permission_request` 带 `timeoutMs`，超时由会话 deny 并发
+ *   `permission_resolved`。
+ * - 宿主 `ui.notify` → `{type:"notification", level, message}` 一行（stderr 同时一份）。
+ * - stdin 关闭：撤下审批（之后的 ask 无人作答 → deny）、等在途命令与已开始的运行结束、
+ *   应答写完 → 退出 0（会话由 runCli dispose）。`printf '{…prompt…}' | ama --mode rpc` 因此能拿到
+ *   完整回复；要中断先发 `abort`。SIGINT / SIGTERM：abort 后有序退出，退出码 130 / 143。
+ */
+import { AgentSessionImpl } from "../../agent/session.js";
+import { currentSession } from "../../cli/compose-session.js";
+import { ExitCode } from "../../cli/exit-codes.js";
+import { isAmaError } from "../../errors.js";
+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 { RpcApprovals, handlers } from "./commands.js";
+import { createLineReader, writeChunked } from "./jsonl.js";
+export const RPC_CAPABILITIES = ["approvals", "images", "hooks"];
+export async function runRpcMode(runtime, context, options = {}) {
+    const stdin = options.stdin ?? process.stdin;
+    const stdout = options.stdout ?? process.stdout;
+    let writing = Promise.resolve();
+    const write = (value) => {
+        const line = `${toJsonLine(value)}\n`;
+        writing = writing.then(() => writeChunked(stdout, line)).catch(() => undefined);
+        return writing;
+    };
+    const subscribe = (s) => s.subscribe((event) => void write(toWireEvent(event)));
+    let session = currentSession(runtime);
+    let unsubscribe = subscribe(session);
+    const approvals = new RpcApprovals();
+    const ctx = {
+        runtime,
+        session: () => session,
+        capabilities: new Set(),
+        approvals,
+        onSessionChanged(next) {
+            unsubscribe();
+            session = next;
+            unsubscribe = subscribe(next);
+        },
+        onBackgroundError(error) {
+            void write({ type: "notification", level: "error", message: errorText(error) });
+        },
+    };
+    runtime.notifier.set((message, level) => {
+        void write({ type: "notification", level, message });
+        context.io.stderr(`ama: [${level}] ${message}\n`);
+    });
+    const hello = {
+        type: "hello",
+        protocolVersion: RPC_PROTOCOL_VERSION,
+        agent: "ama",
+        version: AMA_VERSION,
+        capabilities: [...RPC_CAPABILITIES],
+    };
+    void write(hello);
+    if (session instanceof AgentSessionImpl)
+        session.announceStart("startup");
+    const respond = async (command) => {
+        const id = typeof command.id === "string" ? { id: command.id } : {};
+        const type = command.type;
+        const handler = handlers[type];
+        if (handler === undefined) {
+            await write({
+                ...id,
+                type: "response",
+                command: type,
+                success: false,
+                error: `未知命令：${String(type)}`,
+                code: "invalid_arguments",
+            });
+            return;
+        }
+        try {
+            const data = await handler(command, ctx);
+            await write({
+                ...id,
+                type: "response",
+                command: type,
+                success: true,
+                ...(data !== undefined ? { data } : {}),
+            });
+        }
+        catch (error) {
+            await write({
+                ...id,
+                type: "response",
+                command: type,
+                success: false,
+                error: errorText(error),
+                ...(isAmaError(error) ? { code: error.code } : {}),
+            });
+        }
+    };
+    const inflight = new Set();
+    const onLine = (line) => {
+        let command;
+        try {
+            command = JSON.parse(line);
+        }
+        catch (error) {
+            void write({
+                type: "response",
+                command: "parse",
+                success: false,
+                error: `JSON 解析失败：${errorText(error)}`,
+            });
+            return;
+        }
+        if (typeof command !== "object" || command === null || typeof command.type !== "string") {
+            void write({ type: "response", command: "parse", success: false, error: "缺少 type" });
+            return;
+        }
+        const task = respond(command).finally(() => inflight.delete(task));
+        inflight.add(task);
+    };
+    return new Promise((resolve) => {
+        let finished = false;
+        const finish = async (code, abort) => {
+            if (finished)
+                return;
+            finished = true;
+            reader.close();
+            offSignals();
+            stdin.pause?.();
+            runtime.approvals.setUiBroker(undefined);
+            approvals.cancelAll();
+            if (abort)
+                await session.abort().catch(() => undefined);
+            await Promise.allSettled([...inflight]);
+            await session.waitForIdle().catch(() => undefined);
+            unsubscribe();
+            runtime.notifier.set(undefined);
+            await writing;
+            resolve(code);
+        };
+        // stdin 结束：不再有新命令，也没人能回答审批；已开始的运行跑完再退出（要中断先发 abort 或发信号）。
+        const reader = createLineReader(stdin, onLine, () => void finish(ExitCode.Ok, false));
+        const offSignals = onTerminationSignals((code) => {
+            if (finished)
+                void session.abort();
+            else
+                void finish(code, true);
+        });
+    });
+}

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

@@ -0,0 +1,55 @@
+/**
+ * 会话报告与缓存提示文本（第三波 §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 type { AgentSession, SessionEvent } from "../agent/types.js";
+import type { CacheMiss, CacheReporting, WarmerStatus } from "../ai/cache/types.js";
+import { type KeyValueRow } from "../tui/components/key-value.js";
+/** `950`、`38.2k`、`150k`、`1.05M`（比状态栏多一位精度，面板与提示用）。 */
+export declare function formatTokenCount(count: number): string;
+export declare function formatUsd(cost: number | undefined): string;
+export declare function formatPercent(rate: number | undefined): string;
+/** `45s`、`2m 10s`、`7 分钟`（≥ 10 分钟只到分钟）。 */
+export declare function formatDuration(ms: number): string;
+export declare function reportingLabel(reporting: CacheReporting): string;
+/** 未命中原因的短语（提示行括号里那段）。 */
+export declare function missReasonText(miss: Pick<CacheMiss, "reason" | "detail" | "idleMs">): string;
+export declare function shouldNotifyMiss(miss: Pick<CacheMiss, "missedTokens" | "missedCost">): boolean;
+/** `缓存未命中（空闲 7 分钟后）：重计费 38.2k token（约 $0.11）`。 */
+export declare function cacheMissNotice(miss: CacheMiss): string;
+/** `上下文已用 72%，约剩 9 回合（按最近 5 回合均值）`；估不出回合时给余量 token。 */
+export declare function contextPressureNotice(event: Extract<SessionEvent, {
+    type: "context_pressure";
+}>): string;
+/**
+ * 缓存事件 → 消息区 / stderr 的一行提示；不提示时 undefined。`enabled` = `cache.missNotices`。
+ * 未命中只提示超过门槛的那次；70% 为 warn、90% 为 error；保温事件不进消息区（状态栏 ♨）。
+ */
+export declare function cacheEventNotice(event: SessionEvent, enabled: boolean): {
+    level: "warn" | "error";
+    text: string;
+} | undefined;
+/** 保温请求发出后的一行（line 模式只在 `AMA_LOG=info|debug` 时写 stderr）。 */
+export declare function warmSentNotice(event: Extract<SessionEvent, {
+    type: "cache_warm";
+}>): string | undefined;
+/** 消息区 / stderr 是否提示未命中与上下文余量（`cache.missNotices`，缺省 true）。 */
+export declare function cacheNoticesEnabled(session: AgentSession): boolean;
+export declare function warmStopText(reason: string | undefined): string;
+/** `streaming · 下次 2m 10s · 期望节省 $0.18 ≥ $0.05 · 已发 2 次 $0.01`。 */
+export declare function warmingText(status: WarmerStatus, now: number, minSavingsUsd: number | undefined): string;
+/** 缓存段的键值行（`/session` 与 `/cache` 共用）。 */
+export declare function cacheRows(session: AgentSession, now?: number): KeyValueRow[];
+/** 键值行 → 纯文本（键列对齐、去行尾空白）。 */
+export declare function renderRows(rows: readonly KeyValueRow[], indent?: string): string[];
+export declare function describeCache(session: AgentSession, now?: number): string;
+export declare function describeSession(session: AgentSession, now?: number): string;
+/** `/cache fingerprint`：最近一次真实请求的前缀指纹（system / tools 哈希与模型）。 */
+export declare function describeFingerprint(session: AgentSession): string;