@armadra/agent 0.0.0-stage → 0.3.0

package/dist/cli/main.js

@@ -0,0 +1,177 @@
+#!/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 { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { AMA_VERSION } from "../version.js";
+import { parseArgs } from "./args.js";
+import { reportError, runCli } from "./bootstrap.js";
+import { ExitCode } from "./exit-codes.js";
+import { runAuth } from "./subcommands/auth.js";
+import { runConfig } from "./subcommands/config.js";
+import { runDoctor } from "./subcommands/doctor.js";
+import { runModels } from "./subcommands/models.js";
+import { runProviders } from "./subcommands/providers.js";
+import { runInit } from "./subcommands/init.js";
+import { autoInitConfigDir } from "../config/init.js";
+import { resolveConfigDir } from "../config/paths.js";
+import { runSessions } from "./subcommands/sessions.js";
+let registeredDeps;
+/** 集成批次注入运行时实现（B1 / B2 / B3 / B6 / B7）。 */
+export function registerRuntimeDeps(deps) {
+    registeredDeps = deps;
+}
+/** 读 stdin 全部内容；TTY 下只读一行且不回显（auth set）。 */
+export function readStdinDefault() {
+    const stdin = process.stdin;
+    if (!stdin.isTTY) {
+        return new Promise((resolve, reject) => {
+            const chunks = [];
+            stdin.on("data", (chunk) => chunks.push(chunk));
+            stdin.once("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+            stdin.once("error", reject);
+        });
+    }
+    return new Promise((resolve) => {
+        let line = "";
+        stdin.setRawMode(true);
+        stdin.resume();
+        const onData = (chunk) => {
+            for (const ch of chunk.toString("utf8")) {
+                if (ch === "\r" || ch === "\n" || ch === "\u0004") {
+                    stdin.off("data", onData);
+                    stdin.setRawMode(false);
+                    stdin.pause();
+                    resolve(line);
+                    return;
+                }
+                if (ch === "\u0003") {
+                    stdin.off("data", onData);
+                    stdin.setRawMode(false);
+                    stdin.pause();
+                    resolve("");
+                    return;
+                }
+                if (ch === "\u007f" || ch === "\b")
+                    line = line.slice(0, -1);
+                else
+                    line += ch;
+            }
+        };
+        stdin.on("data", onData);
+    });
+}
+export function defaultIo() {
+    return {
+        stdout: (text) => void process.stdout.write(text),
+        stderr: (text) => void process.stderr.write(text),
+        stdinIsTTY: process.stdin.isTTY === true,
+        stdoutIsTTY: process.stdout.isTTY === true,
+        env: process.env,
+        cwd: process.cwd(),
+        readStdin: readStdinDefault,
+    };
+}
+let hooksInstalled = false;
+function installProcessHooks(io) {
+    if (hooksInstalled)
+        return;
+    hooksInstalled = true;
+    const fatal = (error) => {
+        const message = error instanceof Error ? (error.stack ?? error.message) : String(error);
+        io.stderr(`ama: 未捕获的异常：${message.split("\n")[0] ?? ""}\n`);
+        process.exit(ExitCode.RuntimeError);
+    };
+    process.on("uncaughtException", fatal);
+    process.on("unhandledRejection", fatal);
+}
+export async function main(argv, options = {}) {
+    const io = { ...defaultIo(), ...options.io };
+    process.env["AMA"] = "1";
+    process.env["AI_AGENT"] = "ama";
+    const [first] = argv;
+    if (argv.length === 1 && (first === "--version" || first === "-v")) {
+        io.stdout(`${AMA_VERSION}\n`);
+        return ExitCode.Ok;
+    }
+    if (options.processHooks !== false)
+        installProcessHooks(io);
+    // 缺省装配走动态 import：--version / auth 不加载运行时实现（bundle 里同样内联）。
+    // io 交给组装根决定启动期问答（迷你 TUI / 文本 / 不问）；--no-tui 在解析后才知道。
+    let noTui = false;
+    const resolveDeps = async () => options.deps ??
+        registeredDeps ??
+        (await import("./compose.js")).createRuntimeDeps({
+            env: io.env,
+            io,
+            noTui,
+        });
+    try {
+        const parsed = parseArgs(argv);
+        if (parsed.kind !== "subcommand")
+            noTui = parsed.args.noTui;
+        const informational = parsed.kind === "run" ? parsed.args.help || parsed.args.version : parsed.name === "init";
+        if (!informational)
+            autoInitConfigDir(resolveConfigDir({ env: io.env }), io.env);
+        if (parsed.kind === "subcommand") {
+            switch (parsed.name) {
+                case "auth":
+                    return await runAuth(parsed.argv, io);
+                case "sessions":
+                    return await runSessions(parsed.argv, io, await resolveDeps());
+                case "models":
+                    return await runModels(parsed.argv, io, await resolveDeps());
+                case "providers":
+                    return await runProviders(parsed.argv, io, await resolveDeps());
+                case "doctor":
+                    return await runDoctor(parsed.argv, io, await resolveDeps());
+                case "config":
+                    return await runConfig(parsed.argv, io, await resolveDeps());
+                case "init":
+                    return runInit(parsed.argv, io);
+            }
+        }
+        if (parsed.args.version) {
+            io.stdout(`${AMA_VERSION}\n`);
+            return ExitCode.Ok;
+        }
+        if (parsed.args.help)
+            return runCli(argv, undefined, io);
+    }
+    catch (error) {
+        return reportError(error, io);
+    }
+    return runCli(argv, await resolveDeps(), io);
+}
+function isDirectRun() {
+    if (typeof __AMA_BUNDLED__ !== "undefined" && __AMA_BUNDLED__)
+        return false;
+    const entry = process.argv[1];
+    if (entry === undefined)
+        return false;
+    try {
+        return realpathSync(entry) === realpathSync(fileURLToPath(import.meta.url));
+    }
+    catch {
+        return false;
+    }
+}
+if (isDirectRun()) {
+    main(process.argv.slice(2)).then((code) => {
+        process.exitCode = code;
+    }, (error) => {
+        process.stderr.write(`ama: ${error instanceof Error ? error.message : String(error)}\n`);
+        process.exitCode = ExitCode.RuntimeError;
+    });
+}

package/dist/cli/runtime.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Runtime：bootstrap（§11.1 第 5–14 步）的产物，各模式与 SDK `createRuntime()` 共用。
+ * [B0] 契约文件，组装归 B5（cli/bootstrap.ts），消费者是 B6 / B7。
+ *
+ * 补全说明：设计只列了字段名（config、providers、session、hooks、host、permission、tools），
+ * 这里补全为各批次的最小接口类型（`*Api`），不依赖任何实现文件。
+ */
+import type { Model, ModelThinkingLevel, ProviderRegistryApi } from "../ai/types.js";
+import type { AgentSession } from "../agent/types.js";
+import type { AmaConfig } from "../config/types.js";
+import type { HookDispatcherApi } from "../hooks/types.js";
+import type { ApprovalBroker, HostAdapterHandle, HostMode, InstructionSource } from "../host/types.js";
+import type { PermissionPipelineApi } from "../permissions/types.js";
+import type { SessionManagerApi } from "../session/types.js";
+import type { ToolRegistryApi } from "../tools/types.js";
+export type RuntimeMode = HostMode;
+export interface ResolvedPaths {
+    /** 用户级配置目录（`AMA_CONFIG_DIR` / XDG / `%APPDATA%\ama`）。 */
+    configDir: string;
+    /** 数据目录（`AMA_DATA_DIR` / `~/.local/share/ama`）。 */
+    dataDir: string;
+    /** `--session-dir` > profile > `<dataDir>/sessions`。 */
+    sessionDir: string;
+    /** 会话 cwd。 */
+    cwd: string;
+}
+export interface TrustState {
+    trusted: boolean;
+    /** 决策来源。 */
+    source: "flag" | "trust-file" | "prompt" | "profile" | "default";
+    /** 命中 trust.json 的祖先目录。 */
+    matchedPath?: string;
+}
+export interface LoadedResources {
+    /** AGENTS.md 等，外层在前。 */
+    contextFiles: readonly {
+        path: string;
+        content: string;
+    }[];
+    /** 发现的 Skill（name → SKILL.md 绝对路径）。 */
+    skills: readonly {
+        name: string;
+        description: string;
+        location: string;
+    }[];
+    /** 提示模板（命令名 → 文件）。 */
+    prompts: readonly {
+        name: string;
+        path: string;
+    }[];
+    instructions: readonly InstructionSource[];
+}
+/** UI 通知：交互模式显示在 TUI，rpc 模式转成事件。 */
+export type UiNotify = (message: string, level: "info" | "warn" | "error") => void;
+/** 模式层晚绑定的审批 UI（B6 / B7 在界面就绪后设置）。 */
+export interface RuntimeApprovals {
+    /**
+     * 设置 UI broker：排在宿主 broker 之后，宿主不作答（返回 undefined）时由它询问用户；
+     * undefined = 撤下（回到无人值守处理）。组装出的会话每次审批现取，设置立即生效。
+     */
+    setUiBroker(broker: ApprovalBroker | undefined): void;
+}
+/** 模式层晚绑定的通知出口：宿主 `ui.notify` 转到这里；undefined 恢复为写 stderr。 */
+export interface RuntimeNotifier {
+    set(fn?: UiNotify): void;
+}
+export interface Runtime {
+    readonly mode: RuntimeMode;
+    readonly paths: ResolvedPaths;
+    /** 合并后的有效配置。 */
+    readonly config: AmaConfig;
+    readonly trust: TrustState;
+    readonly resources: LoadedResources;
+    readonly providers: ProviderRegistryApi;
+    readonly model: Model;
+    readonly thinkingLevel: ModelThinkingLevel;
+    readonly sessionManager: SessionManagerApi;
+    readonly session: AgentSession;
+    readonly hooks: HookDispatcherApi;
+    /** 未激活宿主适配器时为 undefined。 */
+    readonly host: HostAdapterHandle | undefined;
+    readonly permission: PermissionPipelineApi;
+    readonly tools: ToolRegistryApi;
+    readonly approvals: RuntimeApprovals;
+    readonly notifier: RuntimeNotifier;
+    /** 启动期收集的 warning（被忽略的放宽项、文件读错等）。 */
+    readonly warnings: readonly string[];
+    /** 发 session_shutdown、SessionEnd Hook、适配器 dispose；幂等。 */
+    dispose(reason?: "exit" | "new" | "switch"): Promise<void>;
+}

package/dist/cli/runtime.js

@@ -0,0 +1,8 @@
+/**
+ * Runtime：bootstrap（§11.1 第 5–14 步）的产物，各模式与 SDK `createRuntime()` 共用。
+ * [B0] 契约文件，组装归 B5（cli/bootstrap.ts），消费者是 B6 / B7。
+ *
+ * 补全说明：设计只列了字段名（config、providers、session、hooks、host、permission、tools），
+ * 这里补全为各批次的最小接口类型（`*Api`），不依赖任何实现文件。
+ */
+export {};

package/dist/cli/startup-screen.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 启动画面参数与内容（设计 §12.10）。[B5]
+ *
+ * 档位来源：`--quiet-startup` > 项目 / profile / 用户 config 的 `ui.quietStartup`（合并后）>
+ * 有 profile 时缺省 `header` > `normal`。这里只产出纯文本行，着色与布局由界面（B7 / B6 line）负责。
+ * - normal：标题行 + 模型 / 信任 / 已加载资源清单 / 警告数
+ * - header：只有标题行（版本与按键提示）
+ * - silent：不输出
+ */
+import type { Runtime } from "./runtime.js";
+export type StartupScreenLevel = "normal" | "header" | "silent";
+export declare function startupScreenLevel(runtime: Pick<Runtime, "config">): StartupScreenLevel;
+export declare function headerLine(): string;
+export type StartupScreenRuntime = Pick<Runtime, "config" | "trust" | "resources" | "model" | "thinkingLevel" | "hooks" | "host" | "paths" | "warnings">;
+export declare function buildStartupScreen(runtime: StartupScreenRuntime, level?: StartupScreenLevel): string[];

package/dist/cli/startup-screen.js

@@ -0,0 +1,56 @@
+/**
+ * 启动画面参数与内容（设计 §12.10）。[B5]
+ *
+ * 档位来源：`--quiet-startup` > 项目 / profile / 用户 config 的 `ui.quietStartup`（合并后）>
+ * 有 profile 时缺省 `header` > `normal`。这里只产出纯文本行，着色与布局由界面（B7 / B6 line）负责。
+ * - normal：标题行 + 模型 / 信任 / 已加载资源清单 / 警告数
+ * - header：只有标题行（版本与按键提示）
+ * - silent：不输出
+ */
+import { AMA_VERSION } from "../version.js";
+export function startupScreenLevel(runtime) {
+    return runtime.config.ui?.quietStartup ?? "normal";
+}
+export function headerLine() {
+    return `ama ${AMA_VERSION} · Enter 发送 · Esc 中断 · Ctrl+C 两次退出 · /help 命令`;
+}
+function trustText(runtime) {
+    const { trusted, source, matchedPath } = runtime.trust;
+    const from = source === "flag"
+        ? "命令行"
+        : source === "trust-file"
+            ? `trust.json${matchedPath === undefined ? "" : ` ${matchedPath}`}`
+            : source === "prompt"
+                ? "本次确认"
+                : source === "profile"
+                    ? "profile"
+                    : "缺省";
+    return `${trusted ? "已信任" : "未信任"}（${from}）`;
+}
+export function buildStartupScreen(runtime, level = startupScreenLevel(runtime)) {
+    if (level === "silent")
+        return [];
+    const lines = [headerLine()];
+    if (level === "header")
+        return lines;
+    const { resources } = runtime;
+    lines.push(`模型：${runtime.model.provider}/${runtime.model.id} · 思考 ${runtime.thinkingLevel}`);
+    lines.push(`目录：${runtime.paths.cwd} · ${trustText(runtime)}`);
+    if (resources.contextFiles.length > 0) {
+        lines.push(`上下文：${resources.contextFiles.map((f) => f.path).join(", ")}`);
+    }
+    if (resources.skills.length > 0) {
+        lines.push(`Skill：${resources.skills.map((s) => s.name).join(", ")}`);
+    }
+    if (resources.prompts.length > 0) {
+        lines.push(`提示模板：${resources.prompts.map((p) => `/${p.name}`).join(" ")}`);
+    }
+    const hooks = runtime.hooks.list();
+    if (hooks.length > 0)
+        lines.push(`Hook：${hooks.length} 条`);
+    if (runtime.host !== undefined)
+        lines.push(`宿主：${runtime.host.adapter.id}`);
+    if (runtime.warnings.length > 0)
+        lines.push(`警告：${runtime.warnings.length} 条（ama doctor 查看）`);
+    return lines;
+}

package/dist/cli/startup-steps.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 启动序列的单步辅助（设计 §11.1）：错误映射、模式判定、profile 合并、会话请求、
+ * 模型与思考级别解析、工具过滤、指令文件。[B5] 由 cli/bootstrap.ts 编排。
+ */
+import type { Model, ModelThinkingLevel, ProviderData, ProviderRegistryApi } from "../ai/types.js";
+import type { AgentSession } from "../agent/types.js";
+import type { ProfileOptions } from "../config/profile.js";
+import { AmaError } from "../errors.js";
+import type { InstructionSource } from "../host/types.js";
+import type { SessionEntry, SessionManagerApi } from "../session/types.js";
+import { type ParsedArgs } from "./args.js";
+import type { CliIo, RuntimeDeps, SessionAssembly, SessionRequest } from "./deps.js";
+import type { Runtime, RuntimeMode } from "./runtime.js";
+/** 把非 StartupError 包成指定退出码；StartupError / UsageError 原样透传。 */
+export declare function step<T>(exitCode: number, label: string, fn: () => T | Promise<T>): Promise<T>;
+export declare function toStartupError(error: unknown, exitCode: number, label: string): AmaError;
+/** 第 4 步。 */
+export declare function decideMode(args: ParsedArgs, io: Pick<CliIo, "stdinIsTTY" | "stdoutIsTTY" | "env">): RuntimeMode;
+/** 第 3 步：profile 字段等价于参数，命令行显式参数优先。 */
+export declare function applyProfile(args: ParsedArgs, profile: ProfileOptions): ParsedArgs;
+export declare function sessionRequestOf(args: ParsedArgs): SessionRequest | "pick";
+export declare function sourceOf(request: SessionRequest, manager: SessionManagerApi): SessionAssembly["source"];
+export declare function lastEntry(manager: SessionManagerApi, predicate: (entry: SessionEntry) => boolean): SessionEntry | undefined;
+export interface ModelChoice {
+    model: Model;
+    provider: ProviderData;
+}
+/** 第 11 步：解析模型与 key。 */
+export declare function resolveModel(args: ParsedArgs, registry: ProviderRegistryApi, manager: SessionManagerApi, defaultModel: string | undefined, deps: RuntimeDeps, interactive: boolean): Promise<ModelChoice>;
+export declare function thinkingOf(args: ParsedArgs, manager: SessionManagerApi, fallback: ModelThinkingLevel | undefined): ModelThinkingLevel;
+/** 第 12 步之后：`--tools` / `--exclude-tools`（宿主工具注册后再校验，宿主工具名也可用）。 */
+export declare function applyToolFilters(args: ParsedArgs, runtimeTools: Runtime["tools"]): void;
+export declare function instructionSources(paths: readonly string[], cwd: string): InstructionSource[];
+/** 宿主 `messages.sendUser` 的缺省实现：运行中 steer，空闲时 prompt；origin 原样落盘到 user 消息。 */
+export declare function defaultSendUser(session: AgentSession, text: string, origin?: string): Promise<"started" | "queued">;

package/dist/cli/startup-steps.js

@@ -0,0 +1,202 @@
+/**
+ * 启动序列的单步辅助（设计 §11.1）：错误映射、模式判定、profile 合并、会话请求、
+ * 模型与思考级别解析、工具过滤、指令文件。[B5] 由 cli/bootstrap.ts 编排。
+ */
+import { formatModelRef } from "../ai/providers/channels.js";
+import { statSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+import { AmaError, StartupError, isAmaError } from "../errors.js";
+import { UsageError } from "./args.js";
+import { pickDefaultModel } from "./default-model.js";
+import { ExitCode } from "./exit-codes.js";
+/** 把非 StartupError 包成指定退出码；StartupError / UsageError 原样透传。 */
+export async function step(exitCode, label, fn) {
+    try {
+        return await fn();
+    }
+    catch (error) {
+        throw toStartupError(error, exitCode, label);
+    }
+}
+const CODE_EXIT = {
+    session_not_found: ExitCode.Session,
+    session_corrupt: ExitCode.Session,
+    model_not_found: ExitCode.NoModel,
+    provider_not_found: ExitCode.NoModel,
+    no_api_key: ExitCode.NoModel,
+    config_invalid: ExitCode.Config,
+    profile_invalid: ExitCode.Config,
+    tool_not_found: ExitCode.Usage,
+    host_load_failed: ExitCode.HostOrHook,
+    host_version_mismatch: ExitCode.HostVersion,
+    hook_failed: ExitCode.HostOrHook,
+};
+export function toStartupError(error, exitCode, label) {
+    if (error instanceof StartupError || error instanceof UsageError)
+        return error;
+    if (isAmaError(error)) {
+        const mapped = error.exitCode ?? CODE_EXIT[error.code] ?? exitCode;
+        return new StartupError(error.code, error.message, mapped, { cause: error });
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    return new StartupError("startup_failed", `${label}：${message}`, exitCode, { cause: error });
+}
+/** 第 4 步。 */
+export function decideMode(args, io) {
+    if (args.mode === "rpc")
+        return "rpc";
+    if (args.print)
+        return "print";
+    if (args.noTui || !io.stdinIsTTY || !io.stdoutIsTTY || io.env["TERM"] === "dumb")
+        return "line";
+    return "interactive";
+}
+/** 第 3 步：profile 字段等价于参数，命令行显式参数优先。 */
+export function applyProfile(args, profile) {
+    const merged = { ...args };
+    if (merged.host === undefined && profile.host !== undefined)
+        merged.host = profile.host;
+    if (merged.authFile === undefined && profile.authFile !== undefined)
+        merged.authFile = profile.authFile;
+    if (merged.sessionDir === undefined && profile.sessionDir !== undefined)
+        merged.sessionDir = profile.sessionDir;
+    if (merged.trust === undefined && profile.trustProject)
+        merged.trust = true;
+    merged.instructions = [...profile.instructions, ...args.instructions];
+    merged.skillDirs = [...args.skillDirs, ...profile.skillDirs];
+    return merged;
+}
+export function sessionRequestOf(args) {
+    if (args.continue)
+        return { kind: "continue" };
+    if (args.resume)
+        return args.resumeId === undefined ? "pick" : { kind: "resume", id: args.resumeId };
+    if (args.sessionId !== undefined)
+        return { kind: "session-id", id: args.sessionId };
+    if (args.fork !== undefined)
+        return { kind: "fork", id: args.fork };
+    return { kind: "new" };
+}
+export function sourceOf(request, manager) {
+    if (request.kind === "fork")
+        return "fork";
+    if (request.kind === "new")
+        return "startup";
+    return manager.entries().length > 0 ? "resume" : "startup";
+}
+export function lastEntry(manager, predicate) {
+    const branch = manager.branch();
+    for (let i = branch.length - 1; i >= 0; i--) {
+        const entry = branch[i];
+        if (entry !== undefined && predicate(entry))
+            return entry;
+    }
+    return undefined;
+}
+/** 第 11 步：解析模型与 key。 */
+export async function resolveModel(args, registry, manager, defaultModel, deps, interactive) {
+    if (args.provider !== undefined && args.model === undefined) {
+        throw new UsageError(`--provider ${args.provider} 需要同时给出 --model（不回退到该供应商的缺省模型）`);
+    }
+    const lookup = (ref, label) => {
+        const found = registry.findModel(ref);
+        if (found.ok)
+            return { model: found.model, provider: found.provider };
+        const hint = found.candidates.length > 0 ? `；候选：${found.candidates.slice(0, 20).join(", ")}` : "";
+        const what = found.reason === "provider_not_found"
+            ? "供应商不存在"
+            : found.reason === "ambiguous"
+                ? "模型名有歧义"
+                : "模型不存在";
+        throw new StartupError("model_not_found", `${label}${what}：${ref}${hint}`, ExitCode.NoModel);
+    };
+    let choice;
+    if (args.model !== undefined) {
+        const ref = args.provider !== undefined && !args.model.includes("/")
+            ? `${args.provider}/${args.model}`
+            : args.model;
+        choice = lookup(ref, "");
+    }
+    else {
+        const change = lastEntry(manager, (e) => e.type === "model_change");
+        if (change?.type === "model_change") {
+            const found = registry.findModel(formatModelRef({
+                provider: change.provider,
+                id: change.modelId,
+                ...(change.channel !== undefined ? { channel: change.channel } : {}),
+            }));
+            if (found.ok)
+                choice = { model: found.model, provider: found.provider };
+        }
+        if (choice === undefined && defaultModel !== undefined)
+            choice = lookup(defaultModel, "config.defaultModel ");
+        if (choice === undefined) {
+            const picked = await pickDefaultModel(registry);
+            if (picked !== undefined)
+                choice = { model: picked.model, provider: picked.provider };
+        }
+    }
+    const pick = async (reason) => {
+        const picked = interactive ? await deps.ui?.pickModel?.(registry, reason) : undefined;
+        if (picked === undefined)
+            throw new StartupError("no_api_key", reason, ExitCode.NoModel);
+        return lookup(picked, "");
+    };
+    if (choice === undefined) {
+        return pick("没有可用模型：用 `ama auth set <provider>` 保存 key，或设置对应环境变量，或 --model 指定");
+    }
+    if (choice.provider.requiresApiKey) {
+        const key = await registry.resolveApiKey(choice.provider.id);
+        if (key.apiKey === undefined) {
+            const envs = choice.provider.envKeys.length > 0
+                ? `，或设置环境变量 ${choice.provider.envKeys.join(" / ")}`
+                : "";
+            return pick(`供应商 ${choice.provider.id} 没有 API key：运行 \`ama auth set ${choice.provider.id}\`${envs}`);
+        }
+    }
+    return choice;
+}
+export function thinkingOf(args, manager, fallback) {
+    if (args.thinking !== undefined)
+        return args.thinking;
+    const change = lastEntry(manager, (e) => e.type === "thinking_level_change");
+    if (change?.type === "thinking_level_change")
+        return change.thinkingLevel;
+    return fallback ?? "medium";
+}
+/** 第 12 步之后：`--tools` / `--exclude-tools`（宿主工具注册后再校验，宿主工具名也可用）。 */
+export function applyToolFilters(args, runtimeTools) {
+    const unknown = [...(args.tools ?? []), ...(args.excludeTools ?? [])].filter((n) => runtimeTools.get(n) === undefined);
+    if (unknown.length > 0) {
+        throw new UsageError(`未知工具：${unknown.join(", ")}（可用：${runtimeTools.list().join(", ")}）`);
+    }
+    if (args.tools !== undefined)
+        runtimeTools.setActive(args.tools);
+    for (const name of args.excludeTools ?? [])
+        runtimeTools.disable(name);
+}
+export function instructionSources(paths, cwd) {
+    return paths.map((p) => {
+        const abs = isAbsolute(p) ? p : resolve(cwd, p);
+        let ok = false;
+        try {
+            ok = statSync(abs).isFile();
+        }
+        catch {
+            ok = false;
+        }
+        if (!ok)
+            throw new StartupError("config_invalid", `--instructions 文件不存在：${abs}`, ExitCode.Config);
+        return { kind: "file", path: abs };
+    });
+}
+/** 宿主 `messages.sendUser` 的缺省实现：运行中 steer，空闲时 prompt；origin 原样落盘到 user 消息。 */
+export async function defaultSendUser(session, text, origin) {
+    const tagged = origin !== undefined ? { origin } : {};
+    if (session.state.isStreaming) {
+        await session.steer(text, tagged);
+        return "queued";
+    }
+    void session.prompt(text, { streamingBehavior: "steer", ...tagged }).catch(() => undefined);
+    return "started";
+}

package/dist/cli/subcommands/auth.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `ama auth set|list|remove <provider>`（设计 §3.5、§16.2 B5 验收）。[B5]
+ *
+ * - set：key 从 stdin 读取（TTY 下不回显），不经命令行参数，避免进 shell 历史；写 auth.json 0600。
+ * - list：只列供应商与 key 形态（字面量 / `!command` / `$ENV` 引用），从不输出 key。
+ * - `--auth-file <path>` 改变目标文件（缺省 `<configDir>/auth.json`）。
+ */
+import type { CliIo } from "../deps.js";
+export declare const AUTH_USAGE = "\u7528\u6CD5\uFF1Aama auth set <provider> [--auth-file <\u6587\u4EF6>]   \u4ECE stdin \u8BFB\u53D6 key\n      ama auth list [--auth-file <\u6587\u4EF6>]\n      ama auth remove <provider> [--auth-file <\u6587\u4EF6>]\n";
+/** 取第一行并去掉首尾空白；stdin 为空返回 ""。 */
+export declare function extractKey(raw: string): string;
+export declare function runAuth(argv: readonly string[], io: CliIo): Promise<number>;