@armadra/agent 0.0.0-stage → 0.3.0

package/dist/cli/compose.js

@@ -0,0 +1,221 @@
+/**
+ * 组装根（composition root，实施计划 §1）：`createRuntimeDeps()` 把各批次的实现装成 bootstrap 要的
+ * `RuntimeDeps`。CLI（main.ts 动态 import）与 SDK（sdk.ts）共用。[B6]
+ *
+ * | 字段                 | 实现                                                                 |
+ * | -------------------- | -------------------------------------------------------------------- |
+ * | providers.create     | compose-providers.ts（ProviderRegistry + auth + 零配置本地探测）     |
+ * | sessions.*           | compose-store.ts（SessionManager 五种请求、list / show / prune）     |
+ * | tools.create         | PresetToolRegistry：内置 + 工具工厂 + extraTools，按预设定活动集     |
+ * | permissions.create   | 内置 deny（按 builtinDeny 过滤）+ 逐条 parseRule → PermissionPipeline |
+ * | resources.discover   | skills / 提示模板发现，完整对象存进闭包状态                          |
+ * | session.create       | compose-session.ts                                                   |
+ * | modes                | line / print / rpc 懒加载；interactive 在 B7 之前回落到 line         |
+ * | ui                   | 传了 io 时：终端 → 迷你 TUI（懒加载），否则文本问答；stdin 非 TTY 不问 |
+ *
+ * **跨步骤状态走闭包（表 B·B13，有意保留）**：`RuntimeDeps.tools.create` 的入参没有 skills / 提示模板，
+ * 第 13 步 `resources.discover` 把完整对象存进 `ComposeState`，组装会话时（compose-session.ts 的技能
+ * 索引与 `/skill:` 展开）再取。不为此扩契约：两步都在同一个 `createRuntimeDeps()` 闭包里，顺序由
+ * bootstrap 固定。
+ *
+ * **工具注册点（给 B10 等）**：`ComposeOptions.toolFactories` 与 `DEFAULT_TOOL_FACTORIES`。工厂在
+ * 第 12 步建注册表时调用，产物以 `builtin` 来源注册（受预设管理）；工厂拿不到会话对象本身，执行期
+ * 需要会话时用 `ctx.session()`，嵌套调用其它工具用 `ToolContext.tools.executeTool`（走完整门禁）。
+ */
+import { formatModelRef } from "../ai/providers/channels.js";
+import { PermissionPipeline } from "../permissions/pipeline.js";
+import { BUILTIN_DENY_RULES, parseRule } from "../permissions/rules.js";
+import { discoverSkills, skillSources } from "../skills/discover.js";
+import { discoverPromptTemplates, promptSources } from "../skills/templates.js";
+import { applyCodemodeMode, decorateForMode } from "../codemode/modes.js";
+import { codemodeToolFactory } from "../codemode/tool.js";
+import { PresetToolRegistry, resolvePreset } from "../tools/presets.js";
+import { builtinTools } from "../tools/registry.js";
+import { buildProviderRegistry } from "./compose-providers.js";
+import { composeSession, emptyComposeState, } from "./compose-session.js";
+import { createSessionStore } from "./compose-store.js";
+import { defaultSendUser } from "./startup-steps.js";
+/** 缺省工具工厂：codemode（`codemode.mode` 生效值为 off 时不注册）。 */
+export const DEFAULT_TOOL_FACTORIES = [codemodeToolFactory()];
+export function lazyMode(load) {
+    return async (runtime, context) => (await load())(runtime, context);
+}
+/** 缺省模式（懒加载：子命令与 --version 不加载模式实现）。 */
+export const DEFAULT_MODES = {
+    print: lazyMode(async () => (await import("../modes/print/print-mode.js")).runPrintMode),
+    rpc: lazyMode(async () => (await import("../modes/rpc/rpc-mode.js")).runRpcMode),
+    line: lazyMode(async () => (await import("../modes/interactive/line/line-mode.js")).runLineMode),
+    interactive: lazyMode(async () => (await import("../modes/interactive/interactive-mode.js")).runInteractiveMode),
+};
+/**
+ * 第 12 步：内置工具 + 工厂 + extraTools，按预设定活动集；warning 留给组装会话时报告。
+ *
+ * 先跑工厂（产物暂不注册）再解析预设：codemode 是否可用决定预设与模式；`on` 模式下注册时给
+ * 其它工具的描述追加 codemode 提示，`only` 模式活动集独占（codemode/modes.ts）。工厂拿到的
+ * `registry` 在执行期才读，此时已登记完全部工具。
+ */
+export function createTools(input, options, state) {
+    const registry = new PresetToolRegistry();
+    const bash = input.config.tools?.bashTimeoutMs !== undefined
+        ? { defaultTimeoutMs: input.config.tools.bashTimeoutMs }
+        : {};
+    const builtins = builtinTools({
+        bash,
+        read: { supportsImages: (ctx) => modelAcceptsImages(state, ctx.model) },
+    });
+    const ctx = {
+        ...input,
+        registry,
+        session: () => state.session,
+        warn: (message) => state.warnings.push(message),
+    };
+    const produced = [];
+    for (const factory of options.toolFactories ?? DEFAULT_TOOL_FACTORIES) {
+        try {
+            const tool = factory(ctx);
+            if (tool !== undefined)
+                produced.push(tool);
+        }
+        catch (error) {
+            state.warnings.push(`工具工厂失败：${error.message}`);
+        }
+    }
+    const extra = options.extraTools ?? [];
+    const names = new Set([...builtins, ...produced, ...extra].map((tool) => tool.name));
+    const preset = resolvePreset({ config: input.config, available: (name) => names.has(name) });
+    const decorate = decorateForMode(preset.codemode);
+    for (const tool of [...builtins, ...produced]) {
+        try {
+            registry.register(decorate(tool), "builtin");
+        }
+        catch (error) {
+            state.warnings.push(`工具 ${tool.name} 注册失败：${error.message}`);
+        }
+    }
+    for (const tool of extra)
+        registry.register(decorate(tool), "sdk");
+    applyCodemodeMode(registry, preset);
+    state.warnings.push(...preset.warnings);
+    return registry;
+}
+/** 当前模型是否收图片（read 工具用）；查不到模型时按收（交给协议层过滤）。 */
+export function modelAcceptsImages(state, model) {
+    if (model === undefined || state.providers === undefined)
+        return true;
+    const found = state.providers.findModel(formatModelRef(model));
+    return found.ok ? found.model.input.includes("image") : true;
+}
+/** 第 14 步前：内置 deny（builtinDeny 过滤）+ 用户规则；非法规则 warning 后跳过。 */
+export function buildRules(specs, builtinDeny, warn) {
+    const rules = [];
+    if (builtinDeny !== false) {
+        for (const raw of BUILTIN_DENY_RULES) {
+            if (Array.isArray(builtinDeny) && builtinDeny.includes(raw))
+                continue;
+            rules.push(parseRule(raw, "deny", "builtin"));
+        }
+    }
+    for (const spec of specs) {
+        try {
+            rules.push(parseRule(spec.raw, spec.effect, spec.source));
+        }
+        catch (error) {
+            warn(`权限规则（${spec.source}）：${error.message}，已忽略`);
+        }
+    }
+    return rules;
+}
+/** 回调先于模式运行；终端界面只在加载时 import，文本回退不加载终端组件库。 */
+function lazyUi(load) {
+    let ui;
+    const get = () => (ui ??= load());
+    return {
+        promptTrust: async (cwd, resources) => (await get()).promptTrust(cwd, resources),
+        pickSession: async (items) => (await get()).pickSession(items),
+        pickModel: async (providers, reason) => (await get()).pickModel(providers, reason),
+        askCwd: async (missing) => (await get()).askCwd(missing),
+    };
+}
+/**
+ * CLI 缺省的启动期问答（第 7 / 8 / 11 步，只在 interactive / line 模式被调用）：
+ * stdin 非 TTY 时不问（管道里的输入留给行式界面，保持非交互分支）；stdout 也是终端、
+ * `TERM` 不是 dumb 且没有 `--no-tui` 时用迷你 TUI，否则写 stderr、从 stdin 读一行。
+ */
+export function defaultStartupUi(io, options = {}) {
+    if (!io.stdinIsTTY)
+        return undefined;
+    if (io.stdoutIsTTY && io.env["TERM"] !== "dumb" && options.noTui !== true) {
+        return lazyUi(async () => (await import("../modes/interactive/startup-ui.js")).createStartupUi(options.tui));
+    }
+    return lazyUi(async () => (await import("../modes/startup-ui-text.js")).createTextStartupUi(options.text ?? { stdin: process.stdin, write: (text) => process.stderr.write(text) }));
+}
+export function createRuntimeDeps(options = {}) {
+    const state = emptyComposeState();
+    const deps = {
+        providers: {
+            create: async (input) => {
+                const registry = await buildProviderRegistry(input, {
+                    providers: options.providers,
+                    apis: options.apis,
+                    env: options.env,
+                    includeFake: options.includeFake,
+                    probeLocal: options.probeLocal,
+                    warn: (message) => state.warnings.push(message),
+                });
+                state.providers = registry;
+                return registry;
+            },
+        },
+        sessions: createSessionStore(),
+        tools: { create: (input) => createTools(input, options, state) },
+        permissions: {
+            create: (input) => new PermissionPipeline({
+                mode: input.mode,
+                rules: buildRules(input.rules, input.builtinDeny, (m) => state.warnings.push(m)),
+                cwd: input.cwd,
+            }),
+        },
+        resources: {
+            async discover(input) {
+                const skills = await discoverSkills(skillSources({
+                    cwd: input.cwd,
+                    configDir: input.configDir,
+                    cliDirs: input.extraSkillDirs,
+                }), { trusted: input.trusted });
+                const prompts = await discoverPromptTemplates(promptSources({
+                    cwd: input.cwd,
+                    configDir: input.configDir,
+                    profileDirs: input.promptDirs,
+                }), { trusted: input.trusted });
+                state.skills = skills.skills;
+                state.templates = prompts.templates;
+                const skipped = [...new Set([...skills.skippedUntrusted, ...prompts.skippedUntrusted])];
+                const warnings = [...skills.warnings, ...prompts.warnings];
+                if (skipped.length > 0)
+                    warnings.push(`${skipped.length} 个项目级目录因未信任被跳过（--trust 加载）`);
+                return {
+                    skills: skills.skills.map((s) => ({
+                        name: s.name,
+                        description: s.description,
+                        location: s.location,
+                    })),
+                    prompts: prompts.templates.map((t) => ({ name: t.name, path: t.path })),
+                    warnings,
+                };
+            },
+        },
+        session: {
+            create: (assembly) => composeSession(assembly, state, {
+                approvalTimeoutMs: options.approvalTimeoutMs,
+                log: options.log,
+            }),
+        },
+        modes: { ...DEFAULT_MODES, ...options.modes },
+        sendUser: defaultSendUser,
+    };
+    const ui = options.ui ??
+        (options.io !== undefined ? defaultStartupUi(options.io, { noTui: options.noTui }) : undefined);
+    if (ui !== undefined)
+        deps.ui = ui;
+    return deps;
+}

package/dist/cli/default-model.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 零配置选模型（设计 §10.0、§11.1 第 11 步）：没有 `--model`、续会话的 model_change 与
+ * `config.defaultModel` 时，按内置供应商顺序（§3.3）选第一个**可用**供应商的缺省模型（目录首条）。
+ *
+ * 可用 = 有 key（`requiresApiKey`）或本地服务已探测到模型（ollama / lmstudio，组装根在
+ * 无 key 时探测）。跳过 `fake`（测试供应商只能显式 `--model fake/…`）与协议尚未实现的供应商。
+ */
+import type { Model, ProviderData, ProviderRegistryApi } from "../ai/types.js";
+export interface DefaultModelChoice {
+    model: Model;
+    provider: ProviderData;
+    /** 选中原因：`key`（有 key，来源见 keySource）或 `local`（本地服务）。 */
+    via: "key" | "local";
+    keySource?: string;
+}
+export declare function pickDefaultModel(registry: ProviderRegistryApi): Promise<DefaultModelChoice | undefined>;

package/dist/cli/default-model.js

@@ -0,0 +1,24 @@
+/**
+ * 零配置选模型（设计 §10.0、§11.1 第 11 步）：没有 `--model`、续会话的 model_change 与
+ * `config.defaultModel` 时，按内置供应商顺序（§3.3）选第一个**可用**供应商的缺省模型（目录首条）。
+ *
+ * 可用 = 有 key（`requiresApiKey`）或本地服务已探测到模型（ollama / lmstudio，组装根在
+ * 无 key 时探测）。跳过 `fake`（测试供应商只能显式 `--model fake/…`）与协议尚未实现的供应商。
+ */
+export async function pickDefaultModel(registry) {
+    for (const provider of registry.list()) {
+        if (provider.id === "fake" && !provider.requiresApiKey)
+            continue;
+        const model = provider.models[0];
+        if (model === undefined)
+            continue;
+        if (registry.getApi(model.api) === undefined)
+            continue;
+        if (!provider.requiresApiKey)
+            return { model, provider, via: "local" };
+        const key = await registry.resolveApiKey(provider.id);
+        if (key.apiKey !== undefined)
+            return { model, provider, via: "key", keySource: key.source };
+    }
+    return undefined;
+}

package/dist/cli/deps.d.ts

@@ -0,0 +1,207 @@
+/**
+ * RuntimeDeps：bootstrap 对其它批次能力的依赖注入接口。[B5]
+ *
+ * 第一波各批次并行实施，B5 不 import B1 / B2 / B3 / B6 / B7 的实现文件；bootstrap 只编排流程、
+ * 失败处理与退出码，具体实现由集成批次在 cli/main.ts 用 `registerRuntimeDeps()` 注入
+ * （SDK 的 `createRuntime()` 直接把 deps 传给 `bootstrap()`）。测试用桩。
+ *
+ * 错误约定：注入实现抛 `StartupError` 时原样透传（用它的退出码）；抛 `AmaError` 时按 code
+ * 映射（`session_not_found / session_corrupt` → 5、`model_not_found / provider_not_found /
+ * no_api_key` → 4、`config_invalid` → 3、`tool_not_found` → 2）；其它异常按所在步骤的缺省退出码。
+ */
+import type { ModelThinkingLevel, Model, ProviderData, ProviderRegistryApi } from "../ai/types.js";
+import type { AgentSession } from "../agent/types.js";
+import type { AmaConfig } from "../config/types.js";
+import type { PermissionRuleSpec } from "../config/merge.js";
+import type { TrustPromptAnswer } from "../config/trust.js";
+import type { HookDispatcherApi } from "../hooks/types.js";
+import type { WarmingDecisionHandler } from "../ai/cache/types.js";
+import type { AgentEventBus } from "../host/api-impl.js";
+import type { ApprovalBroker, HostAdapterHandle, InstructionSource } from "../host/types.js";
+import type { PermissionMode, PermissionPipelineApi } from "../permissions/types.js";
+import type { SessionEntry, SessionListItem, SessionManagerApi } from "../session/types.js";
+import type { ToolRegistryApi } from "../tools/types.js";
+import type { LoadedResources, ResolvedPaths, Runtime, RuntimeMode, TrustState } from "./runtime.js";
+import type { ParsedArgs } from "./args.js";
+/** 第 7 步的会话请求。 */
+export type SessionRequest = {
+    kind: "new";
+} | {
+    kind: "continue";
+} | {
+    kind: "resume";
+    id: string;
+} | {
+    kind: "session-id";
+    id: string;
+} | {
+    kind: "fork";
+    id: string;
+};
+export interface ProviderBuildInput {
+    config: AmaConfig;
+    cwd: string;
+    /** 解析后的 auth.json 路径：`--auth-file` > profile.authFile > `<configDir>/auth.json`。 */
+    authFile: string;
+    /** 是否读环境变量（profile.authEnv=false 时为 false，§11.2）。 */
+    authEnv: boolean;
+    /** `--api-key`：只作用于 `modelRef` 所属的供应商（§3.5 ①）。 */
+    cliApiKey?: {
+        apiKey: string;
+        modelRef: string;
+        provider?: string;
+    };
+    /** 数据目录：读 models.dev 缓存（`<dataDir>/models-dev.json`，只读不联网）；缺省不补元数据。 */
+    dataDir?: string;
+}
+export interface ResourceDiscoveryInput {
+    cwd: string;
+    configDir: string;
+    trusted: boolean;
+    /** 按 §5.3 顺序：`--skill-dir` → profile.skillDirs → config.skills.dirs。 */
+    extraSkillDirs: readonly string[];
+    promptDirs: readonly string[];
+}
+export interface ResourceDiscoveryResult {
+    skills: LoadedResources["skills"];
+    prompts: LoadedResources["prompts"];
+    warnings: string[];
+}
+/** 第 14 步交给 AgentSession 实现（B2）的全部装配材料。 */
+export interface SessionAssembly {
+    mode: RuntimeMode;
+    paths: ResolvedPaths;
+    config: AmaConfig;
+    trust: TrustState;
+    resources: LoadedResources;
+    providers: ProviderRegistryApi;
+    model: Model;
+    provider: ProviderData;
+    thinkingLevel: ModelThinkingLevel;
+    sessionManager: SessionManagerApi;
+    /** session_start 的 reason。 */
+    source: "startup" | "resume" | "new" | "fork";
+    hooks: HookDispatcherApi;
+    permission: PermissionPipelineApi;
+    tools: ToolRegistryApi;
+    /** 宿主事件总线：AgentSession 把 AgentEvents 发到这里（session_start 由 bootstrap 发）。 */
+    events: AgentEventBus;
+    host: {
+        handle: HostAdapterHandle | undefined;
+        /** 宿主 broker（链首）；undefined 交给 UI / 无人值守。 */
+        broker(): ApprovalBroker | undefined;
+        /** 系统提示 host 节。 */
+        instructions: readonly InstructionSource[];
+        /** [W3-C1b] 宿主 `cache.onWarmingDecision` 的当前处理器（每次保温前现取）。 */
+        warmingDecider?(): WarmingDecisionHandler | undefined;
+    };
+    /** `Runtime.approvals.setUiBroker` 设置的 UI broker（链尾）；每次审批现取，未设置为 undefined。 */
+    uiBroker(): ApprovalBroker | undefined;
+    /**
+     * 模式层把当前会话换成另一个（`/new`、`/resume`、`/fork`、RPC `switch_session`）后调用：
+     * bootstrap 让 HostApi.session.*、宿主 sendUser、Hook 公共字段与退出时的 dispose 跟随 `next`。
+     * 旧会话由调用方自行 dispose；`Runtime.session` 仍指初始会话。
+     */
+    onSessionReplaced(next: AgentSession): void;
+    /** SessionStart Hook 的 additionalContext（系统提示 hooks 节）；首次装配系统提示时读取。 */
+    sessionStartContext(): string | undefined;
+    /** print：ask → deny。 */
+    unattended: boolean;
+    warn(message: string): void;
+}
+export interface ModeContext {
+    args: ParsedArgs;
+    /** 位置参数拼成的首条提示。 */
+    prompt: string | undefined;
+    io: CliIo;
+}
+/** 第 15–16 步：模式实现（B6 line / print / rpc，B7 interactive）；返回退出码。 */
+export type ModeRunner = (runtime: Runtime, context: ModeContext) => Promise<number>;
+/** 交互 UI 回调（B7 / B6 line 提供）；全部可选，缺省按非交互处理。 */
+export interface InteractiveUi {
+    promptTrust?(cwd: string, resources: readonly string[]): Promise<TrustPromptAnswer>;
+    /** `--resume` 无 id：返回会话 id，undefined = 用户取消（退出码 5）。 */
+    pickSession?(items: readonly SessionListItem[]): Promise<string | undefined>;
+    /** 无 key / 无模型时选择模型；返回 `provider/id`，undefined = 取消（退出码 4）。 */
+    pickModel?(providers: ProviderRegistryApi, reason: string): Promise<string | undefined>;
+    /** 会话 cwd 不存在：返回新 cwd，undefined = 取消（退出码 5）。 */
+    askCwd?(missing: string): Promise<string | undefined>;
+}
+export interface RuntimeDeps {
+    /** B1：ProviderRegistry.build(builtin, config.providers) + auth。 */
+    providers: {
+        create(input: ProviderBuildInput): ProviderRegistryApi | Promise<ProviderRegistryApi>;
+    };
+    /** B2：SessionManager。 */
+    sessions: {
+        open(request: SessionRequest, context: {
+            sessionDir: string;
+            cwd: string;
+        }): SessionManagerApi | Promise<SessionManagerApi>;
+        /** `--resume` 选择器与 `ama sessions` 用。 */
+        list?(context: {
+            sessionDir: string;
+            cwd?: string;
+        }): Promise<SessionListItem[]>;
+        /** `ama sessions show`：id 可为前缀；找不到抛 AmaError{code:"session_not_found"}。 */
+        show?(id: string, context: {
+            sessionDir: string;
+        }): Promise<{
+            item: SessionListItem;
+            entries: readonly SessionEntry[];
+        }>;
+        /** `ama sessions prune`：把超过 olderThanDays 天未修改的会话移到 trash（§8）。 */
+        prune?(context: {
+            sessionDir: string;
+            cwd?: string;
+            olderThanDays: number;
+            dryRun: boolean;
+        }): Promise<{
+            moved: string[];
+        }>;
+    };
+    /** B3：ToolRegistry（内置工具已注册）。 */
+    tools: {
+        create(input: {
+            config: AmaConfig;
+            cwd: string;
+            mode: RuntimeMode;
+        }): ToolRegistryApi;
+    };
+    /** B3：权限管线。 */
+    permissions: {
+        create(input: {
+            mode: PermissionMode;
+            rules: readonly PermissionRuleSpec[];
+            unattended: boolean;
+            /** 会话 cwd：规则里的相对路径以它为基准。 */
+            cwd: string;
+            /** config `permission.builtinDeny`（只来自用户级 / profile）；缺省 = 启用全部内置 deny。 */
+            builtinDeny?: boolean | string[];
+        }): PermissionPipelineApi;
+    };
+    /** B3：skills / prompts 发现；缺省为空。 */
+    resources?: {
+        discover(input: ResourceDiscoveryInput): ResourceDiscoveryResult | Promise<ResourceDiscoveryResult>;
+    };
+    /** B2：组装 AgentSession。 */
+    session: {
+        create(assembly: SessionAssembly): AgentSession | Promise<AgentSession>;
+    };
+    /** B6 / B7。 */
+    modes: Partial<Record<RuntimeMode, ModeRunner>>;
+    ui?: InteractiveUi;
+    /** 宿主 `messages.sendUser` 的实现；缺省：运行中 steer，空闲时 prompt。 */
+    sendUser?(session: AgentSession, text: string, origin: string): Promise<"started" | "queued">;
+}
+/** 进程 I/O（测试注入）。 */
+export interface CliIo {
+    stdout: (text: string) => void;
+    stderr: (text: string) => void;
+    stdinIsTTY: boolean;
+    stdoutIsTTY: boolean;
+    env: Readonly<Record<string, string | undefined>>;
+    cwd: string;
+    /** 读取 stdin 全部内容（auth set）。 */
+    readStdin(): Promise<string>;
+}

package/dist/cli/deps.js

@@ -0,0 +1,12 @@
+/**
+ * RuntimeDeps：bootstrap 对其它批次能力的依赖注入接口。[B5]
+ *
+ * 第一波各批次并行实施，B5 不 import B1 / B2 / B3 / B6 / B7 的实现文件；bootstrap 只编排流程、
+ * 失败处理与退出码，具体实现由集成批次在 cli/main.ts 用 `registerRuntimeDeps()` 注入
+ * （SDK 的 `createRuntime()` 直接把 deps 传给 `bootstrap()`）。测试用桩。
+ *
+ * 错误约定：注入实现抛 `StartupError` 时原样透传（用它的退出码）；抛 `AmaError` 时按 code
+ * 映射（`session_not_found / session_corrupt` → 5、`model_not_found / provider_not_found /
+ * no_api_key` → 4、`config_invalid` → 3、`tool_not_found` → 2）；其它异常按所在步骤的缺省退出码。
+ */
+export {};

package/dist/cli/exit-codes.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 进程退出码（设计 §11.3）。[B0] 契约文件。
+ */
+export declare const ExitCode: {
+    /** 正常。 */
+    readonly Ok: 0;
+    /** 运行期错误（模型最终失败等）。 */
+    readonly RuntimeError: 1;
+    /** 参数用法错误。 */
+    readonly Usage: 2;
+    /** 配置 / profile / 路径错误。 */
+    readonly Config: 3;
+    /** 无可用模型或密钥。 */
+    readonly NoModel: 4;
+    /** 会话不存在 / 损坏 / cwd 不匹配。 */
+    readonly Session: 5;
+    /** 宿主 / Hook 加载或启动失败。 */
+    readonly HostOrHook: 6;
+    /** HOST_API_VERSION 不匹配。 */
+    readonly HostVersion: 78;
+    /** SIGINT 退出（两次 Ctrl+C）。 */
+    readonly Sigint: 130;
+    /** SIGTERM。 */
+    readonly Sigterm: 143;
+};
+export type ExitCodeName = keyof typeof ExitCode;
+export type ExitCode = (typeof ExitCode)[ExitCodeName];
+export declare const EXIT_CODE_DESCRIPTIONS: Readonly<Record<ExitCode, string>>;
+export declare function describeExitCode(code: number): string;

package/dist/cli/exit-codes.js

@@ -0,0 +1,40 @@
+/**
+ * 进程退出码（设计 §11.3）。[B0] 契约文件。
+ */
+export const ExitCode = {
+    /** 正常。 */
+    Ok: 0,
+    /** 运行期错误（模型最终失败等）。 */
+    RuntimeError: 1,
+    /** 参数用法错误。 */
+    Usage: 2,
+    /** 配置 / profile / 路径错误。 */
+    Config: 3,
+    /** 无可用模型或密钥。 */
+    NoModel: 4,
+    /** 会话不存在 / 损坏 / cwd 不匹配。 */
+    Session: 5,
+    /** 宿主 / Hook 加载或启动失败。 */
+    HostOrHook: 6,
+    /** HOST_API_VERSION 不匹配。 */
+    HostVersion: 78,
+    /** SIGINT 退出（两次 Ctrl+C）。 */
+    Sigint: 130,
+    /** SIGTERM。 */
+    Sigterm: 143,
+};
+export const EXIT_CODE_DESCRIPTIONS = {
+    0: "正常",
+    1: "运行期错误（模型最终失败等）",
+    2: "参数用法错误",
+    3: "配置 / profile / 路径错误",
+    4: "无可用模型或密钥",
+    5: "会话不存在 / 损坏 / cwd 不匹配",
+    6: "宿主 / Hook 加载或启动失败",
+    78: "HOST_API_VERSION 不匹配",
+    130: "SIGINT 退出（两次 Ctrl+C）",
+    143: "SIGTERM",
+};
+export function describeExitCode(code) {
+    return EXIT_CODE_DESCRIPTIONS[code] ?? "未知退出码";
+}

package/dist/cli/main.d.ts

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+/**
+ * bin 入口（设计 §11.1 第 1–2 步）。[B5]
+ *
+ * - 设 `AMA=1`、`AI_AGENT=ama`；直接执行时装 `uncaughtException` / `unhandledRejection` →
+ *   stderr 一行 + 退出码 1；SIGINT / SIGTERM 交给当前模式。
+ * - `--version` / `--help` 短路；子命令 `auth / sessions / models / providers / doctor / config /
+ *   init` 分派后返回；其余命令启动前若配置目录不存在则静默初始化（`AMA_NO_INIT=1` 关闭）；
+ *   其余交给 `runCli()`（bootstrap → 模式）。
+ * - 运行时实现（RuntimeDeps）：`MainOptions.deps` > `registerRuntimeDeps()` > 组装根
+ *   `createRuntimeDeps()`（cli/compose.ts，动态 import）。
+ * - 签名 `main(argv): Promise<number>` 与「直接执行才自动运行」判定保持不变：
+ *   src/bundle.ts 显式调用 `main()`。
+ */
+import type { CliIo, RuntimeDeps } from "./deps.js";
+/** 集成批次注入运行时实现（B1 / B2 / B3 / B6 / B7）。 */
+export declare function registerRuntimeDeps(deps: RuntimeDeps | undefined): void;
+export interface MainOptions {
+    deps?: RuntimeDeps;
+    io?: Partial<CliIo>;
+    /** 装进程级异常处理器（缺省 true；测试传 false）。 */
+    processHooks?: boolean;
+}
+/** 读 stdin 全部内容；TTY 下只读一行且不回显（auth set）。 */
+export declare function readStdinDefault(): Promise<string>;
+export declare function defaultIo(): CliIo;
+export declare function main(argv: readonly string[], options?: MainOptions): Promise<number>;