@armadra/agent 0.0.0-stage → 0.2.1

package/dist/host/types.d.ts

@@ -0,0 +1,169 @@
+/**
+ * 宿主适配器契约（设计 §6.2，`@armadra/agent/host`）。[B0] 契约文件，实现归 B5。
+ *
+ * 补全与偏差：
+ * - `InstructionSource` 设计未展开，按 v1 §8.5 补全为 file / text 两种。
+ * - `ApprovalBroker / ApprovalRequest / ApprovalDecision` 定义在 permissions/types.ts，此处再导出。
+ * - `HostMode` 抽成具名类型；`AgentEvents` 中空载荷用 `Record<string, never>` 表示
+ *   （设计写 `{}`，在 strict 下 `{}` 意为「任意非空值」，语义不对）。
+ * - `HostAdapterHandle` 是 Runtime 持有的已激活适配器（loader.ts 产出）。
+ * - （W3-C0）第三波 §1.10 / §1.7：`AgentEvents` 加 `cache_miss`、`context_pressure`；
+ *   `HostApi.cache.onWarmingDecision` 为可选面（HOST_API_VERSION 不变，旧宿主不受影响），
+ *   多个处理器时最后注册的生效。
+ */
+import type { CacheMiss, WarmingDecisionHandler } from "../ai/cache/types.js";
+import type { HookEvent } from "../hooks/types.js";
+import type { ApprovalBroker, ApprovalDecision } from "../permissions/types.js";
+import type { ToolDefinition } from "../tools/types.js";
+export type { ActionPreview, ActionPreviewTarget, ApprovalBroker, ApprovalDecision, ApprovalReason, ApprovalRequest, ApprovalRequestContext, } from "../permissions/types.js";
+export type { ToolAnnotations, ToolContext, ToolDefinition, ToolExecutionMode, ToolPermission, ToolResult, } from "../tools/types.js";
+export type { JsonSchema } from "../ai/types.js";
+export type { CacheMiss, WarmDecision, WarmingDecisionHandler } from "../ai/cache/types.js";
+export declare const HOST_API_VERSION: 1;
+export type HostApiVersion = typeof HOST_API_VERSION;
+export type HostMode = "interactive" | "line" | "print" | "rpc";
+export type InstructionSource = {
+    kind: "file";
+    path: string;
+} | {
+    kind: "text";
+    text: string;
+    name?: string;
+};
+export interface HostModule {
+    readonly hostApi: HostApiVersion;
+    create(api: HostApi): HostAdapter | undefined | Promise<HostAdapter | undefined>;
+}
+export interface HostAdapter {
+    readonly id: string;
+    /** session_shutdown 后调用，幂等。 */
+    dispose?(): void | Promise<void>;
+}
+type Empty = Record<string, never>;
+export interface AgentEvents {
+    session_start: {
+        sessionId: string;
+        sessionFile?: string;
+        cwd: string;
+        reason: "startup" | "resume" | "new" | "fork";
+    };
+    before_agent_start: {
+        prompt: string;
+    };
+    agent_start: Empty;
+    turn_start: Empty;
+    turn_end: Empty;
+    tool_call: {
+        toolCallId: string;
+        toolName: string;
+        input: unknown;
+    };
+    tool_result: {
+        toolCallId: string;
+        toolName: string;
+        isError: boolean;
+    };
+    agent_end: {
+        stopReason: string;
+        willRetry: boolean;
+    };
+    agent_before_settle: Empty;
+    agent_settled: {
+        warning?: string;
+    };
+    session_compact: {
+        tokensBefore: number;
+    };
+    model_select: {
+        model: {
+            id: string;
+            provider: string;
+        };
+    };
+    tool_approval_requested: {
+        requestId: string;
+        toolName: string;
+    };
+    tool_approval_resolved: {
+        requestId: string;
+        decision: ApprovalDecision;
+    };
+    hook_executed: {
+        event: HookEvent;
+        command: string;
+        exitCode: number | null;
+        durationMs: number;
+    };
+    session_shutdown: Empty;
+    /** [W3-C0] 一次缓存未命中（重计费 token / 金额与原因）。 */
+    cache_miss: CacheMiss;
+    /** [W3-C0] 上下文占用跨越 70% / 90%。 */
+    context_pressure: {
+        percent: number;
+        threshold: 70 | 90;
+        remainingTokens?: number;
+        estimatedTurnsLeft?: number;
+    };
+}
+export type AgentEventName = keyof AgentEvents;
+export interface HostApi {
+    readonly version: HostApiVersion;
+    readonly agent: {
+        readonly name: "ama";
+        readonly version: string;
+    };
+    readonly env: Readonly<NodeJS.ProcessEnv>;
+    readonly mode: HostMode;
+    readonly session: {
+        id(): string;
+        file(): string | undefined;
+        cwd(): string;
+        model(): {
+            provider: string;
+            id: string;
+        } | undefined;
+    };
+    readonly tools: {
+        /** 同名已存在则抛错。 */
+        register(tool: ToolDefinition): void;
+        /** 隐藏内置工具（如 task）。 */
+        disable(name: string): void;
+        list(): readonly string[];
+    };
+    /** 追加到系统提示 `host` 节（最后）。 */
+    readonly instructions: {
+        add(source: InstructionSource): void;
+    };
+    readonly events: {
+        on<E extends AgentEventName>(name: E, handler: (event: AgentEvents[E]) => void | Promise<void>): () => void;
+    };
+    readonly approvals: {
+        setBroker(broker: ApprovalBroker): void;
+    };
+    /** 以 user 消息注入（运行中按 steer 入队），origin 缺省 "host"。 */
+    readonly messages: {
+        sendUser(text: string, origin?: string): Promise<"started" | "queued">;
+    };
+    /** print / rpc 下 notify → stderr / 事件。 */
+    readonly ui: {
+        notify(message: string, level?: "info" | "warn" | "error"): void;
+        setStatus(key: string, text?: string): void;
+    };
+    readonly log: (level: "debug" | "info" | "warn" | "error", message: string, detail?: unknown) => void;
+    /**
+     * [W3-C0] 缓存保温的否决钩子（第三波 §1.7）：每次保温前以内置决策调用，返回 `"stop"` 即不发；
+     * 处理器出错回落内置决策。返回值用于注销。可选面：旧版本运行时没有它。
+     */
+    readonly cache?: {
+        onWarmingDecision(handler: WarmingDecisionHandler): () => void;
+    };
+}
+/** Runtime 持有的已激活适配器。 */
+export interface HostAdapterHandle {
+    readonly adapter: HostAdapter;
+    readonly api: HostApi;
+    /** 模块来源（路径或 "sdk"）。 */
+    readonly source: string;
+    /** 宿主 setStatus 的当前值（状态栏显示）。 */
+    status(): ReadonlyMap<string, string>;
+}

package/dist/host/types.js

@@ -0,0 +1,14 @@
+/**
+ * 宿主适配器契约（设计 §6.2，`@armadra/agent/host`）。[B0] 契约文件，实现归 B5。
+ *
+ * 补全与偏差：
+ * - `InstructionSource` 设计未展开，按 v1 §8.5 补全为 file / text 两种。
+ * - `ApprovalBroker / ApprovalRequest / ApprovalDecision` 定义在 permissions/types.ts，此处再导出。
+ * - `HostMode` 抽成具名类型；`AgentEvents` 中空载荷用 `Record<string, never>` 表示
+ *   （设计写 `{}`，在 strict 下 `{}` 意为「任意非空值」，语义不对）。
+ * - `HostAdapterHandle` 是 Runtime 持有的已激活适配器（loader.ts 产出）。
+ * - （W3-C0）第三波 §1.10 / §1.7：`AgentEvents` 加 `cache_miss`、`context_pressure`；
+ *   `HostApi.cache.onWarmingDecision` 为可选面（HOST_API_VERSION 不变，旧宿主不受影响），
+ *   多个处理器时最后注册的生效。
+ */
+export const HOST_API_VERSION = 1;

package/dist/host.d.ts

@@ -0,0 +1,5 @@
+/**
+ * `@armadra/agent/host` 子路径：宿主适配器类型 + HOST_API_VERSION（设计 §6.2、D7）。[B0] 所有。
+ */
+export { HOST_API_VERSION } from "./host/types.js";
+export type * from "./host/types.js";

package/dist/host.js

@@ -0,0 +1,4 @@
+/**
+ * `@armadra/agent/host` 子路径：宿主适配器类型 + HOST_API_VERSION（设计 §6.2、D7）。[B0] 所有。
+ */
+export { HOST_API_VERSION } from "./host/types.js";

package/dist/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * `@armadra/agent`：SDK 公开面（设计 §13.1）。[B0] 所有。
+ *
+ * B0 导出契约类型与少量契约内的值（版本、错误、校验器、退出码）；「SDK」段（B6）导出
+ * `createAgentSession`、`createRuntime` 与常用实现类。
+ */
+export { AMA_VERSION } from "./version.js";
+export { AmaError, StartupError, isAmaError } from "./errors.js";
+export { HOST_API_VERSION } from "./host/types.js";
+export { RPC_PROTOCOL_VERSION } from "./rpc.js";
+export { SESSION_FORMAT_VERSION } from "./session/types.js";
+export { HOOK_EVENTS } from "./hooks/types.js";
+export { PERMISSION_MODES_STRICT_FIRST } from "./permissions/types.js";
+export { ExitCode, describeExitCode } from "./cli/exit-codes.js";
+export { defineTool } from "./tools/types.js";
+export { validateSchema, checkSchemaSubset, formatSchemaErrors } from "./agent/schema.js";
+export type { SchemaError, SchemaErrorKeyword } from "./agent/schema.js";
+export type * from "./ai/types.js";
+export type * from "./ai/cache/types.js";
+export type * from "./agent/types.js";
+export type * from "./session/types.js";
+export type * from "./tools/types.js";
+export type * from "./hooks/types.js";
+export type * from "./permissions/types.js";
+export type * from "./host/types.js";
+export type * from "./config/types.js";
+export type { AmaErrorOptions, ErrorCode, KnownErrorCode } from "./errors.js";
+export type { Runtime, RuntimeMode, ResolvedPaths, TrustState, LoadedResources, } from "./cli/runtime.js";
+export { createAgentSession, createRuntime } from "./sdk.js";
+export type { CreateSessionOptions, RuntimeOptions, SessionAuth } from "./sdk.js";
+export { AgentSessionImpl } from "./agent/session.js";
+export { SessionManager } from "./session/manager.js";
+export { ProviderRegistry } from "./ai/providers/registry.js";
+export { FakeProvider } from "./ai/fake/fake-provider.js";
+export { loadConfigFile as loadConfig } from "./config/load.js";
+export { createToolRegistry } from "./tools/registry.js";
+export { PRESET_TOOLS, effectiveCodemodeMode } from "./tools/presets.js";
+export { createRuntimeDeps, DEFAULT_TOOL_FACTORIES } from "./cli/compose.js";
+export type { ComposeOptions, ToolFactory, ToolFactoryContext } from "./cli/compose.js";
+export { currentSession, switchSession } from "./cli/compose-session.js";
+export type { SwitchRequest } from "./cli/compose-session.js";

package/dist/index.js

@@ -0,0 +1,28 @@
+/**
+ * `@armadra/agent`：SDK 公开面（设计 §13.1）。[B0] 所有。
+ *
+ * B0 导出契约类型与少量契约内的值（版本、错误、校验器、退出码）；「SDK」段（B6）导出
+ * `createAgentSession`、`createRuntime` 与常用实现类。
+ */
+// 值
+export { AMA_VERSION } from "./version.js";
+export { AmaError, StartupError, isAmaError } from "./errors.js";
+export { HOST_API_VERSION } from "./host/types.js";
+export { RPC_PROTOCOL_VERSION } from "./rpc.js";
+export { SESSION_FORMAT_VERSION } from "./session/types.js";
+export { HOOK_EVENTS } from "./hooks/types.js";
+export { PERMISSION_MODES_STRICT_FIRST } from "./permissions/types.js";
+export { ExitCode, describeExitCode } from "./cli/exit-codes.js";
+export { defineTool } from "./tools/types.js";
+export { validateSchema, checkSchemaSubset, formatSchemaErrors } from "./agent/schema.js";
+// SDK（B6 追加）
+export { createAgentSession, createRuntime } from "./sdk.js";
+export { AgentSessionImpl } from "./agent/session.js";
+export { SessionManager } from "./session/manager.js";
+export { ProviderRegistry } from "./ai/providers/registry.js";
+export { FakeProvider } from "./ai/fake/fake-provider.js";
+export { loadConfigFile as loadConfig } from "./config/load.js";
+export { createToolRegistry } from "./tools/registry.js";
+export { PRESET_TOOLS, effectiveCodemodeMode } from "./tools/presets.js";
+export { createRuntimeDeps, DEFAULT_TOOL_FACTORIES } from "./cli/compose.js";
+export { currentSession, switchSession } from "./cli/compose-session.js";

package/dist/modes/commands-core.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 斜杠命令语义层（line 模式与 B7 交互模式共用，不含渲染）。[B6]
+ *
+ * `runSlashCommand(line, ctx)`：
+ * - 不是内置命令（含 `/skill:<name>` 与提示模板 `/<模板名>`）→ undefined，调用方把整行当提示发出，
+ *   展开在会话的 expandPrompt 里做；
+ * - 内置命令 → `CommandResult`：`handled`（可带一段给用户看的文本）、`prompt`（改发这段文本）、
+ *   `pick`（需要界面弹选择器，参数缺省时）、`exit`。
+ *
+ * 会话切换（/new /resume /fork）经 `ctx.switchSession`，调用方据返回的新会话重新订阅事件。
+ */
+import type { AgentSession } from "../agent/types.js";
+import type { SwitchRequest } from "../cli/compose-session.js";
+import type { Runtime } from "../cli/runtime.js";
+export { describeSession } from "./session-report.js";
+export type CommandResult = {
+    kind: "handled";
+    message?: string;
+} | {
+    kind: "prompt";
+    text: string;
+} | {
+    kind: "pick";
+    what: "model" | "session" | "tree" | "permission" | "thinking";
+} | {
+    kind: "exit";
+};
+export interface CommandContext {
+    readonly runtime: Runtime;
+    /** 当前会话（切换后是新的那个）。 */
+    session(): AgentSession;
+    switchSession(request: SwitchRequest): Promise<AgentSession>;
+}
+export interface CommandInfo {
+    name: string;
+    args?: string;
+    description: string;
+}
+export declare const BUILTIN_COMMANDS: readonly CommandInfo[];
+export declare function parseSlash(line: string): {
+    name: string;
+    args: string;
+} | undefined;
+export declare function runSlashCommand(line: string, ctx: CommandContext): Promise<CommandResult | undefined>;

package/dist/modes/commands-core.js

@@ -0,0 +1,171 @@
+/**
+ * 斜杠命令语义层（line 模式与 B7 交互模式共用，不含渲染）。[B6]
+ *
+ * `runSlashCommand(line, ctx)`：
+ * - 不是内置命令（含 `/skill:<name>` 与提示模板 `/<模板名>`）→ undefined，调用方把整行当提示发出，
+ *   展开在会话的 expandPrompt 里做；
+ * - 内置命令 → `CommandResult`：`handled`（可带一段给用户看的文本）、`prompt`（改发这段文本）、
+ *   `pick`（需要界面弹选择器，参数缺省时）、`exit`。
+ *
+ * 会话切换（/new /resume /fork）经 `ctx.switchSession`，调用方据返回的新会话重新订阅事件。
+ */
+import { AgentSessionImpl } from "../agent/session.js";
+import { WARMING_MODES } from "../ai/cache/types.js";
+import { THINKING_LEVELS } from "../ai/thinking.js";
+import { AmaError } from "../errors.js";
+import { PERMISSION_MODES_STRICT_FIRST } from "../permissions/types.js";
+import { describeCache, describeFingerprint, describeSession } from "./session-report.js";
+export { describeSession } from "./session-report.js";
+export const BUILTIN_COMMANDS = [
+    { name: "help", description: "列出命令" },
+    { name: "new", description: "新建会话" },
+    { name: "resume", args: "[id]", description: "恢复会话（无 id 时选择）" },
+    { name: "fork", args: "[条目 id]", description: "从某条目分叉出新会话" },
+    { name: "compact", args: "[说明]", description: "压缩上下文" },
+    { name: "model", args: "[provider/id]", description: "切换模型" },
+    {
+        name: "thinking",
+        args: "[级别]",
+        description: "思考级别 off | minimal | low | medium | high | xhigh",
+    },
+    {
+        name: "permission",
+        args: "[模式]",
+        description: "权限模式 plan | default | auto-edit | full-auto",
+    },
+    { name: "tools", args: "[名字…]", description: "列出 / 设置活动工具" },
+    { name: "hooks", description: "列出已加载的 Hook" },
+    { name: "session", description: "会话信息、用量与缓存" },
+    {
+        name: "cache",
+        args: "[warm off|streaming|idle | fingerprint]",
+        description: "缓存统计；切换本会话保温；打印前缀指纹",
+    },
+    { name: "exit", description: "退出" },
+];
+const ALIASES = { quit: "exit", q: "exit", "?": "help" };
+export function parseSlash(line) {
+    const m = /^\/([A-Za-z?][\w-]*)(?:\s+([\s\S]*))?$/.exec(line.trim());
+    if (m === null)
+        return undefined;
+    const raw = m[1].toLowerCase();
+    return { name: ALIASES[raw] ?? raw, args: (m[2] ?? "").trim() };
+}
+function helpText() {
+    const lines = BUILTIN_COMMANDS.map((c) => `/${c.name}${c.args !== undefined ? ` ${c.args}` : ""}  ${c.description}`);
+    return [...lines, "/skill:<名字> [参数]  使用 Skill", "/<模板名> [参数]  展开提示模板"].join("\n");
+}
+function toolNames(args) {
+    return args
+        .split(/[\s,]+/)
+        .map((s) => s.trim())
+        .filter((s) => s !== "");
+}
+/** `/cache`、`/cache warm <模式>`、`/cache fingerprint`。 */
+function cacheCommand(session, args) {
+    const [sub, value, extra] = args.split(/\s+/).filter((s) => s !== "");
+    if (sub === undefined)
+        return describeCache(session);
+    if (sub === "fingerprint" && value === undefined)
+        return describeFingerprint(session);
+    if (sub === "warm" && extra === undefined) {
+        if (!(session instanceof AgentSessionImpl))
+            throw new AmaError("invalid_arguments", "当前会话不支持切换保温");
+        if (value === undefined)
+            return `保温：${session.cache.mode()}`;
+        if (!WARMING_MODES.includes(value))
+            throw new AmaError("invalid_arguments", `保温模式应为 ${WARMING_MODES.join(" | ")}`);
+        session.cache.setWarming(value);
+        return `保温：${session.cache.mode()}（本会话）`;
+    }
+    throw new AmaError("invalid_arguments", "用法：/cache [warm off|streaming|idle | fingerprint]");
+}
+export async function runSlashCommand(line, ctx) {
+    const parsed = parseSlash(line);
+    if (parsed === undefined)
+        return undefined;
+    const { name, args } = parsed;
+    const session = ctx.session();
+    switch (name) {
+        case "help":
+            return { kind: "handled", message: helpText() };
+        case "exit":
+            return { kind: "exit" };
+        case "new": {
+            const next = await ctx.switchSession({ kind: "new" });
+            return { kind: "handled", message: `已新建会话 ${next.state.sessionId.slice(0, 8)}` };
+        }
+        case "resume": {
+            if (args === "")
+                return { kind: "pick", what: "session" };
+            const next = await ctx.switchSession({ kind: "resume", id: args });
+            return {
+                kind: "handled",
+                message: `已恢复会话 ${next.state.sessionId.slice(0, 8)}（${next.messages.length} 条消息）`,
+            };
+        }
+        case "fork": {
+            if (args === "")
+                return { kind: "pick", what: "tree" };
+            const next = await ctx.switchSession({ kind: "fork", entryId: args });
+            return { kind: "handled", message: `已分叉到新会话 ${next.state.sessionId.slice(0, 8)}` };
+        }
+        case "compact": {
+            const result = await session.compact(args === "" ? undefined : args);
+            const after = result.tokensAfter !== undefined ? ` → ${result.tokensAfter}` : "";
+            return { kind: "handled", message: `已压缩：${result.tokensBefore}${after} token` };
+        }
+        case "model": {
+            if (args === "")
+                return { kind: "pick", what: "model" };
+            await session.setModel(args);
+            const model = session.state.model;
+            return { kind: "handled", message: `模型：${model?.provider}/${model?.id}` };
+        }
+        case "thinking": {
+            if (args === "")
+                return { kind: "pick", what: "thinking" };
+            if (!THINKING_LEVELS.includes(args))
+                throw new AmaError("invalid_arguments", `思考级别应为 ${THINKING_LEVELS.join(" | ")}`);
+            session.setThinkingLevel(args);
+            return { kind: "handled", message: `思考级别：${args}` };
+        }
+        case "permission": {
+            if (args === "")
+                return { kind: "pick", what: "permission" };
+            if (!PERMISSION_MODES_STRICT_FIRST.includes(args)) {
+                throw new AmaError("invalid_arguments", `权限模式应为 ${PERMISSION_MODES_STRICT_FIRST.join(" | ")}`);
+            }
+            session.setPermissionMode(args);
+            return { kind: "handled", message: `权限模式：${args}` };
+        }
+        case "tools": {
+            if (args !== "")
+                session.setActiveTools(toolNames(args));
+            const active = session.getTools().map((t) => t.name);
+            const all = ctx.runtime.tools.list();
+            const inactive = all.filter((n) => !active.includes(n));
+            return {
+                kind: "handled",
+                message: `活动：${active.join(", ") || "（无）"}${inactive.length > 0 ? `\n可用：${inactive.join(", ")}` : ""}`,
+            };
+        }
+        case "hooks": {
+            const hooks = ctx.runtime.hooks.list();
+            if (hooks.length === 0)
+                return { kind: "handled", message: "没有已加载的 Hook" };
+            return {
+                kind: "handled",
+                message: hooks
+                    .map((h) => `${h.source} ${h.event}${h.matcher !== undefined ? ` [${h.matcher}]` : ""} → ${h.command}`)
+                    .join("\n"),
+            };
+        }
+        case "session":
+            return { kind: "handled", message: describeSession(session) };
+        case "cache":
+            return { kind: "handled", message: cacheCommand(session, args) };
+        default:
+            return undefined;
+    }
+}

package/dist/modes/interactive/approval-dialog.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 审批对话框（设计 §12.6）：模式层的 UI `ApprovalBroker`，底部覆盖层。[B7]
+ *
+ * - 标题行：`[task]`（`request.context.depth > 0`，子 Agent 发起）+ 工具名 + 原因标签；
+ * - 输入：bash 显示命令全文，write 显示路径与行数，edit 显示路径与每处修改的 −/+ 摘要，其它显示
+ *   一行摘要；`v` 展开 / 收起完整输入（JSON）；
+ * - 执行前预览（W3-B9a-2，`request.preview`）：输入摘要之后列出会碰到的路径与规模，danger 红、
+ *   warn 黄、info 暗色；`other` 类预览与输入摘要重复，不显示；
+ * - 原因：mode（当前权限模式需要确认）/ dangerous / hook + Hook 给的文本；
+ * - 按键：`y` 允许、`n` / Esc / Ctrl+C 拒绝、`a` 本会话允许同类；
+ * - 超时与中断：broker 链在超时（缺省 10 分钟）或运行被中断时 abort `signal`，对话框关闭并返回
+ *   undefined（链按 deny 处理），消息区留一行说明。
+ *
+ * broker 链本身串行化审批，所以同一时刻最多一个对话框。
+ */
+import type { ApprovalBroker, ApprovalDecision, ApprovalRequest } from "../../permissions/types.js";
+import { type Component, type Keybindings, type OverlayHandle, type Theme } from "../../tui.js";
+export interface ApprovalHost {
+    theme: Theme;
+    keybindings?: Keybindings;
+    /** 路径显示的基准。 */
+    cwd?: string;
+    /** 当前权限模式（原因为 mode 时显示）。 */
+    permissionMode(): string;
+    showOverlay(component: Component): OverlayHandle;
+    /** 对话框打开 / 关闭（交互模式据此禁用编辑器提交、重画）。 */
+    onOpen?(): void;
+    onClose?(): void;
+    /** 结果说明（消息区一行）。 */
+    report?(request: ApprovalRequest, outcome: ApprovalDecision | "cancelled"): void;
+}
+/** 对话框正文（不含按键行）。 */
+export declare function describeRequest(request: ApprovalRequest, theme: Theme, options?: {
+    cwd?: string;
+    permissionMode?: string;
+    expanded?: boolean;
+}): string[];
+export declare const APPROVAL_KEYS_HINT = "[y] \u5141\u8BB8  [n] \u62D2\u7EDD  [a] \u672C\u4F1A\u8BDD\u5141\u8BB8\u540C\u7C7B  [v] \u5B8C\u6574\u8F93\u5165";
+/** UI broker：每个请求开一个底部覆盖层，等用户按键或 signal abort。 */
+export declare class ApprovalDialogBroker implements ApprovalBroker {
+    private readonly host;
+    private open;
+    constructor(host: ApprovalHost);
+    get isOpen(): boolean;
+    ask(request: ApprovalRequest, signal: AbortSignal): Promise<ApprovalDecision | undefined>;
+}
+/** 结果的一行说明（消息区）。 */
+export declare function approvalOutcomeText(request: ApprovalRequest, outcome: ApprovalDecision | "cancelled"): string;