@armadra/agent 0.6.8 → 0.7.0

package/dist/i18n/messages/print.js

@@ -1,9 +1,10 @@
 /**
- * 消息目录：print（键名规范见 docs/i18n.md）。[W6-C0 建空壳，W6-I3 迁入 `src/modes/{print,rpc,acp}/**`]
+ * 消息目录：print（键名规范见 docs/i18n.md）。[W6-C0 建空壳，W6-I3 迁入 `src/modes/{print,rpc}/**`；
+ * ACP 的文案在 [ACP-C0] 迁到 acp.ts]
  *
  * en 是形状源；zh 用 `satisfies Messages<typeof en>`，缺键 / 多键 / 参数不符在 tsc 期报错。
  * 整句一个键、禁止片段拼接；插值写成函数，条件分支写进函数体。
- * RPC / ACP 的 `error` / `message` 是人读文本，宿主按 `code` 判断（docs/rpc.md）；JSON 字段名不在这里。
+ * RPC 的 `error` / `message` 是人读文本，宿主按 `code` 判断（docs/rpc.md）；JSON 字段名不在这里。
  */
 import { plural } from "../format.js";
 export const en = {
@@ -36,22 +37,6 @@ export const en = {
         noPlan: "this session has no plan extension",
         badMode: (modes) => `mode must be ${modes.join(" | ")}`,
     },
-    /** ACP 服务端（`ama --mode acp`）。 */
-    acp: {
-        missingParam: (key) => `missing ${key}`,
-        promptNotArray: "prompt must be an array of content blocks",
-        unparsable: (reason) => `ACP: unparsable input (${reason})`,
-        missingProtocolVersion: "missing protocolVersion",
-        fixedCwd: (cwd, got) => `the session directory of ama --mode acp is fixed to the start directory ${cwd} (got ${got})`,
-        sessionNotFound: (id, error) => `session ${id} not found: ${error}`,
-        busy: "the current session is running; send session/cancel first",
-        modelFailed: "model request failed",
-        unknownMode: (mode) => `unknown mode: ${mode}`,
-        allowOnce: "Allow",
-        allowAlways: "Allow for this session",
-        rejectOnce: "Deny",
-        truncated: (length) => `…(truncated, ${plural(length, "character")} in total)`,
-    },
 };
 export const zh = {
     print: {
@@ -81,19 +66,4 @@ export const zh = {
         noPlan: "该会话没有装配 plan 扩展",
         badMode: (modes) => `mode 应为 ${modes.join(" | ")}`,
     },
-    acp: {
-        missingParam: (key) => `缺少 ${key}`,
-        promptNotArray: "prompt 应为内容块数组",
-        unparsable: (reason) => `ACP：无法解析的输入（${reason}）`,
-        missingProtocolVersion: "缺少 protocolVersion",
-        fixedCwd: (cwd, got) => `ama --mode acp 的会话目录固定为启动目录 ${cwd}（收到 ${got}）`,
-        sessionNotFound: (id, error) => `找不到会话 ${id}：${error}`,
-        busy: "当前会话正在运行，先 session/cancel",
-        modelFailed: "模型请求失败",
-        unknownMode: (mode) => `未知模式：${mode}`,
-        allowOnce: "允许",
-        allowAlways: "本会话允许",
-        rejectOnce: "拒绝",
-        truncated: (length) => `…（已截断，共 ${length} 字符）`,
-    },
 };

package/dist/modes/acp/acp-auth-gate.d.ts

@@ -0,0 +1,40 @@
+/**
+ * `ama --mode acp` 的认证门（docs/acp-plan.md §2.2、D3、D4）。[ACP-A]
+ *
+ * bootstrap 因没有可用模型（退出码 4）失败时不退出，改为在同一条 stdio 上应答 ACP：
+ * - `initialize` → 正常握手；客户端声明 `clientCapabilities.auth.terminal` 时给两条 terminal 型
+ *   认证方法（`ama auth login chatgpt` / `ama auth set`，启动时的 `--auth-file` / profile 的
+ *   `authFile` 一并带上，R4），否则 `authMethods: []`。
+ * - `authenticate` → -32602（terminal 方法规定不经 authenticate）。
+ * - 会话方法 → 距上次失败 ≥ 1 s 则重试整段 bootstrap（并发请求共用同一次重试）：成功则把同一条
+ *   连接交给 `runAcpMode`（服务端处理本次与之后的全部请求，客户端不必重新 initialize）；仍无模型
+ *   → -32000（message = 无模型引导，`data.authMethods` = 已给方法的 id）；其它启动错误 → -32603。
+ * - 其它方法 → -32601；交接前的通知忽略。
+ * - stdin 关闭：已交接则走 ACP 模式的退出（0）；否则直接退出 0。SIGINT / SIGTERM → 130 / 143。
+ *
+ * stdout 由 runCli 在第一次 bootstrap 之前接管（宿主 / Hook 的 console.log 改写到 stderr）。
+ */
+import { type ParsedArgs } from "../../cli/args.js";
+import type { CliIo, RuntimeDeps } from "../../cli/deps.js";
+import { type AcpAuthMethod } from "../../drivers/acp/types.js";
+/** 两次 bootstrap 重试的最小间隔。 */
+export declare const AUTH_RETRY_INTERVAL_MS = 1000;
+/**
+ * terminal 型认证方法（D4）：客户端把 `args` **追加**到启动 Agent 的那条命令后面、在终端里起子进程
+ * （规范：append to the configured agent invocation），所以 args 是 `--acp-terminal-auth <id>`，
+ * 由 `parseArgs` 认出后转成 `auth login chatgpt` / `auth set`，原有的 `--mode acp` 等参数不再生效。
+ * `authFile`：启动时的 `--auth-file` 或 profile 的 `authFile`（绝对路径），让登录写到同一个文件。
+ */
+export declare function terminalAuthMethods(authFile?: string): AcpAuthMethod[];
+/** 登录应写入的 auth 文件：`--auth-file`（相对启动目录）> profile 的 `authFile`；都没有 → 缺省位置。 */
+export declare function gateAuthFile(args: ParsedArgs, cwd: string): string | undefined;
+export interface AcpAuthGateOptions {
+    stdin?: NodeJS.ReadableStream;
+    stdout?: NodeJS.WritableStream;
+    /** 重试间隔（测试缩短）；缺省 {@link AUTH_RETRY_INTERVAL_MS}。 */
+    retryIntervalMs?: number;
+    now?: () => number;
+}
+export declare function runAcpAuthGate(args: ParsedArgs, deps: RuntimeDeps, io: CliIo, 
+/** bootstrap 第一次失败的错误（NoModel）。 */
+cause: unknown, options?: AcpAuthGateOptions): Promise<number>;

package/dist/modes/acp/acp-auth-gate.js

@@ -0,0 +1,201 @@
+/**
+ * `ama --mode acp` 的认证门（docs/acp-plan.md §2.2、D3、D4）。[ACP-A]
+ *
+ * bootstrap 因没有可用模型（退出码 4）失败时不退出，改为在同一条 stdio 上应答 ACP：
+ * - `initialize` → 正常握手；客户端声明 `clientCapabilities.auth.terminal` 时给两条 terminal 型
+ *   认证方法（`ama auth login chatgpt` / `ama auth set`，启动时的 `--auth-file` / profile 的
+ *   `authFile` 一并带上，R4），否则 `authMethods: []`。
+ * - `authenticate` → -32602（terminal 方法规定不经 authenticate）。
+ * - 会话方法 → 距上次失败 ≥ 1 s 则重试整段 bootstrap（并发请求共用同一次重试）：成功则把同一条
+ *   连接交给 `runAcpMode`（服务端处理本次与之后的全部请求，客户端不必重新 initialize）；仍无模型
+ *   → -32000（message = 无模型引导，`data.authMethods` = 已给方法的 id）；其它启动错误 → -32603。
+ * - 其它方法 → -32601；交接前的通知忽略。
+ * - stdin 关闭：已交接则走 ACP 模式的退出（0）；否则直接退出 0。SIGINT / SIGTERM → 130 / 143。
+ *
+ * stdout 由 runCli 在第一次 bootstrap 之前接管（宿主 / Hook 的 console.log 改写到 stderr）。
+ */
+import { resolve } from "node:path";
+import { ACP_TERMINAL_AUTH_FLAG } from "../../cli/args.js";
+import { bootstrap } from "../../cli/bootstrap.js";
+import { ExitCode } from "../../cli/exit-codes.js";
+import { loadProfile } from "../../config/profile.js";
+import { StartupError } from "../../errors.js";
+import { RpcError } from "../../drivers/jsonrpc.js";
+import { ACP_METHODS, ACP_PROTOCOL_VERSION, RPC_ERRORS, } from "../../drivers/acp/types.js";
+import { formatModelRef } from "../../ai/providers/channels.js";
+import { msg } from "../../i18n/index.js";
+import { AMA_VERSION } from "../../version.js";
+import { onTerminationSignals } from "../shared.js";
+import { clientCapabilitiesOf, createAcpConnection } from "./acp-connection.js";
+import { runAcpMode } from "./acp-mode.js";
+import { ACP_AGENT_CAPABILITIES } from "./acp-server.js";
+/** 两次 bootstrap 重试的最小间隔。 */
+export const AUTH_RETRY_INTERVAL_MS = 1000;
+/** 会触发重试的方法（交接后由服务端处理）。 */
+const SESSION_METHODS = new Set([
+    ACP_METHODS.sessionNew,
+    ACP_METHODS.sessionLoad,
+    ACP_METHODS.sessionResume,
+    ACP_METHODS.sessionList,
+    ACP_METHODS.sessionClose,
+    ACP_METHODS.sessionPrompt,
+    ACP_METHODS.sessionSetMode,
+    ACP_METHODS.sessionSetConfigOption,
+]);
+/**
+ * terminal 型认证方法（D4）：客户端把 `args` **追加**到启动 Agent 的那条命令后面、在终端里起子进程
+ * （规范：append to the configured agent invocation），所以 args 是 `--acp-terminal-auth <id>`，
+ * 由 `parseArgs` 认出后转成 `auth login chatgpt` / `auth set`，原有的 `--mode acp` 等参数不再生效。
+ * `authFile`：启动时的 `--auth-file` 或 profile 的 `authFile`（绝对路径），让登录写到同一个文件。
+ */
+export function terminalAuthMethods(authFile) {
+    const m = msg().acp.auth;
+    const extra = authFile !== undefined ? ["--auth-file", authFile] : [];
+    return [
+        {
+            type: "terminal",
+            id: "chatgpt",
+            name: m.chatgptName,
+            description: m.chatgptDescription,
+            args: [ACP_TERMINAL_AUTH_FLAG, "chatgpt", ...extra],
+        },
+        {
+            type: "terminal",
+            id: "api-key",
+            name: m.apiKeyName,
+            description: m.apiKeyDescription,
+            args: [ACP_TERMINAL_AUTH_FLAG, "api-key", ...extra],
+        },
+    ];
+}
+/** 登录应写入的 auth 文件：`--auth-file`（相对启动目录）> profile 的 `authFile`；都没有 → 缺省位置。 */
+export function gateAuthFile(args, cwd) {
+    if (args.authFile !== undefined)
+        return resolve(cwd, args.authFile);
+    if (args.profile === undefined)
+        return undefined;
+    try {
+        return loadProfile(args.profile, cwd).authFile;
+    }
+    catch {
+        return undefined; // bootstrap 已读过 profile；这里失败只是不带 --auth-file
+    }
+}
+function isNoModel(error) {
+    return error instanceof StartupError && error.exitCode === ExitCode.NoModel;
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export async function runAcpAuthGate(args, deps, io, 
+/** bootstrap 第一次失败的错误（NoModel）。 */
+cause, options = {}) {
+    const stdin = options.stdin ?? process.stdin;
+    const stdout = options.stdout ?? process.stdout;
+    const now = options.now ?? Date.now;
+    const interval = options.retryIntervalMs ?? AUTH_RETRY_INTERVAL_MS;
+    const log = (message) => io.stderr(`ama: ${message}\n`);
+    const authFile = gateAuthFile(args, io.cwd);
+    log(msg().acp.auth.waiting(messageOf(cause)));
+    let lastError = cause;
+    let lastFailure = now();
+    let attempt;
+    /** 交接后的服务端（attach 时同步填入）。 */
+    const target = {};
+    const serverOf = () => target.server;
+    let served;
+    let runtime;
+    const offeredMethods = (caps) => caps.auth?.terminal === true ? terminalAuthMethods(authFile) : [];
+    /** 重试 bootstrap（节流；并发请求共用一次）；成功返回 Runtime 并已交接。 */
+    const retry = () => {
+        if (attempt !== undefined)
+            return attempt;
+        if (now() - lastFailure < interval)
+            return Promise.resolve(undefined);
+        attempt = bootstrap(args, deps, io).then((ready) => {
+            handover(ready);
+            return ready;
+        }, (error) => {
+            lastError = error;
+            lastFailure = now();
+            attempt = undefined;
+            if (!isNoModel(error))
+                log(messageOf(error));
+            return undefined;
+        });
+        return attempt;
+    };
+    const connection = createAcpConnection({ input: stdin, output: stdout }, log, {
+        onRequest: async (method, raw, ctx) => {
+            const params = (raw ?? {});
+            if (target.server !== undefined)
+                return target.server.handle(method, params, ctx);
+            if (method === ACP_METHODS.initialize)
+                return initialize(params);
+            if (method === ACP_METHODS.authenticate)
+                throw new RpcError(RPC_ERRORS.invalidParams, msg().acp.auth.notAgentMethod);
+            if (!SESSION_METHODS.has(method))
+                throw new RpcError(RPC_ERRORS.methodNotFound, `method not found: ${method}`);
+            const handed = (await retry()) !== undefined ? serverOf() : undefined;
+            if (handed !== undefined)
+                return handed.handle(method, params, ctx);
+            if (!isNoModel(lastError))
+                throw new RpcError(RPC_ERRORS.internalError, messageOf(lastError));
+            throw new RpcError(RPC_ERRORS.authRequired, messageOf(lastError), {
+                authMethods: offeredMethods(connection.clientCapabilities).map((m) => m.id),
+            });
+        },
+        onNotification: (method, params) => target.server?.handleNotification(method, params),
+    });
+    function initialize(params) {
+        if (typeof params["protocolVersion"] !== "number")
+            throw new RpcError(RPC_ERRORS.invalidParams, msg().acp.core.missingProtocolVersion);
+        const caps = clientCapabilitiesOf(params);
+        connection.markInitialized(caps);
+        return {
+            protocolVersion: ACP_PROTOCOL_VERSION,
+            agentCapabilities: ACP_AGENT_CAPABILITIES,
+            authMethods: offeredMethods(caps),
+            agentInfo: { name: "ama", title: "ama", version: AMA_VERSION },
+        };
+    }
+    // 退出：交接前 stdin 关闭 → 0、信号 → 130 / 143；交接后等 ACP 模式退出
+    let settled = false;
+    let finish = () => undefined;
+    const exit = new Promise((done) => (finish = done));
+    const offSignals = onTerminationSignals((code) => {
+        if (target.server === undefined) {
+            settled = true;
+            finish(code);
+        }
+    });
+    void connection.peer.closed.then(async () => {
+        await attempt; // 收尾中的重试：落定后交接了就交给 ACP 模式退出
+        if (served === undefined) {
+            settled = true;
+            finish(ExitCode.Ok);
+        }
+    });
+    function handover(ready) {
+        if (settled) {
+            void ready.dispose("exit").catch(() => undefined);
+            return;
+        }
+        runtime = ready;
+        offSignals();
+        for (const w of ready.warnings)
+            io.stderr(msg().cli.bootstrap.warning(w));
+        log(msg().acp.auth.ready(formatModelRef({ provider: ready.model.provider, id: ready.model.id })));
+        served = runAcpMode(ready, { args, prompt: undefined, io }, { stdin, stdout, handover: { connection, attach: (s) => void (target.server = s) } });
+        void served.then(finish, () => finish(ExitCode.RuntimeError));
+    }
+    const code = await exit;
+    offSignals();
+    if (served === undefined) {
+        stdin.pause?.();
+        await connection.peer.flush();
+        connection.peer.close();
+    }
+    await runtime?.dispose("exit").catch(() => undefined);
+    return code;
+}

package/dist/modes/acp/acp-config.d.ts

@@ -0,0 +1,43 @@
+/**
+ * `ama --mode acp` 的会话配置项与命令表（docs/acp-plan.md §1.6、D8、D9）。[ACP-C0 建壳，ACP-D 实现]
+ *
+ * - `buildConfigOptions`：`mode`（select，category `mode`，值是 ama 的权限模式，与 `modes` 同一状态）、
+ *   `model`（select，category `model`，按供应商分组，值 `provider/model-id`）与 `thinking`（select，
+ *   category `thought_level`，只列当前模型支持的级别）；没有 boolean 项。规范：Agent 给了 `configOptions`，
+ *   客户端 SHOULD 用它代替 `modes`（Zed 给了就不再看 `modes`），所以模式也必须在这里；`modes` 照给，留给
+ *   只认 `modes` 的客户端。`mode` 的设置由服务端处理（按会话记、只对前台会话生效），不经 `applyConfigOption`。
+ *   模型清单与 TUI `/model` 的「已配置」视图同一口径（`catalogItems`）：只列有 key、OAuth 已登录或本地的
+ *   供应商，`models.enabled` 设置时只列清单内的；`fake` 按 `hideFakeProvider` 规则藏起；当前模型总在列。
+ *   判断有没有 key 要异步解析，所以先 `await prepareConfigOptions(providers)` 缓存各供应商的可用状态，
+ *   之后 `buildConfigOptions` 同步取（映射器的 `extras()` 是同步的）。没准备过时只列本地供应商与当前模型。
+ * - `applyConfigOption`：`session/set_config_option` → `setModel()` / `setThinkingLevel()`；未知 id、
+ *   非字符串值、找不到的模型、不认识的级别回 invalid params。
+ * - `availableCommands`：skills → `skill:<name>`，提示模板 → `<name>`（`argumentHint` → `input.hint`）。
+ *   内置斜杠命令（`/new`、`/compact`…）在 ACP 下不执行，不列。
+ */
+import type { AgentSession } from "../../agent/types.js";
+import type { ProviderRegistryApi } from "../../ai/types.js";
+import type { LoadedResources } from "../../cli/runtime.js";
+import { type AcpAvailableCommand, type AcpSessionConfigOption, type AcpSetConfigOptionParams } from "../../drivers/acp/types.js";
+import type { PermissionMode } from "../../permissions/types.js";
+/** 配置项 id（机器字段，不翻译）。 */
+export declare const CONFIG_IDS: {
+    readonly mode: "mode";
+    readonly model: "model";
+    readonly thinking: "thinking";
+};
+/**
+ * 解析各供应商的可用状态并缓存（读 key / OAuth，毫秒级）；开会话前调一次，登录后再调一次可刷新。
+ * 缓存挂在传入的注册表上，`buildConfigOptions` 须传同一个对象。
+ */
+export declare function prepareConfigOptions(providers: ProviderRegistryApi): Promise<void>;
+export interface ConfigOptionsExtras {
+    /** `models.enabled`（用户级清单）；不给或空表示不限。 */
+    enabled?: readonly string[] | undefined;
+    /** 这个会话的权限模式（服务端按会话记）；不给时取 `session.state.permissionMode`。 */
+    mode?: PermissionMode | undefined;
+}
+export declare function buildConfigOptions(session: AgentSession, providers: ProviderRegistryApi, env: NodeJS.ProcessEnv, extras?: ConfigOptionsExtras): AcpSessionConfigOption[];
+/** 未知 id / value → RpcError invalidParams。 */
+export declare function applyConfigOption(session: AgentSession, params: AcpSetConfigOptionParams): Promise<void>;
+export declare function availableCommands(resources: LoadedResources): AcpAvailableCommand[];

package/dist/modes/acp/acp-config.js

@@ -0,0 +1,151 @@
+/**
+ * `ama --mode acp` 的会话配置项与命令表（docs/acp-plan.md §1.6、D8、D9）。[ACP-C0 建壳，ACP-D 实现]
+ *
+ * - `buildConfigOptions`：`mode`（select，category `mode`，值是 ama 的权限模式，与 `modes` 同一状态）、
+ *   `model`（select，category `model`，按供应商分组，值 `provider/model-id`）与 `thinking`（select，
+ *   category `thought_level`，只列当前模型支持的级别）；没有 boolean 项。规范：Agent 给了 `configOptions`，
+ *   客户端 SHOULD 用它代替 `modes`（Zed 给了就不再看 `modes`），所以模式也必须在这里；`modes` 照给，留给
+ *   只认 `modes` 的客户端。`mode` 的设置由服务端处理（按会话记、只对前台会话生效），不经 `applyConfigOption`。
+ *   模型清单与 TUI `/model` 的「已配置」视图同一口径（`catalogItems`）：只列有 key、OAuth 已登录或本地的
+ *   供应商，`models.enabled` 设置时只列清单内的；`fake` 按 `hideFakeProvider` 规则藏起；当前模型总在列。
+ *   判断有没有 key 要异步解析，所以先 `await prepareConfigOptions(providers)` 缓存各供应商的可用状态，
+ *   之后 `buildConfigOptions` 同步取（映射器的 `extras()` 是同步的）。没准备过时只列本地供应商与当前模型。
+ * - `applyConfigOption`：`session/set_config_option` → `setModel()` / `setThinkingLevel()`；未知 id、
+ *   非字符串值、找不到的模型、不认识的级别回 invalid params。
+ * - `availableCommands`：skills → `skill:<name>`，提示模板 → `<name>`（`argumentHint` → `input.hint`）。
+ *   内置斜杠命令（`/new`、`/compact`…）在 ACP 下不执行，不列。
+ */
+import { formatModelRef } from "../../ai/providers/channels.js";
+import { providerAccess } from "../../ai/providers/model-visibility.js";
+import { clampThinkingLevel, getSupportedLevels, isThinkingLevel, THINKING_LEVELS, } from "../../ai/thinking.js";
+import { hideFakeProvider } from "../../cli/fake-visibility.js";
+import { RPC_ERRORS, } from "../../drivers/acp/types.js";
+import { RpcError } from "../../drivers/jsonrpc.js";
+import { AmaError } from "../../errors.js";
+import { msg } from "../../i18n/index.js";
+import { catalogItems } from "../interactive/model-items.js";
+import { permissionModes } from "./acp-events.js";
+/** 配置项 id（机器字段，不翻译）。 */
+export const CONFIG_IDS = { mode: "mode", model: "model", thinking: "thinking" };
+/** 各注册表上次解析出的供应商可用状态（providerId → access）。 */
+const accessCache = new WeakMap();
+/**
+ * 解析各供应商的可用状态并缓存（读 key / OAuth，毫秒级）；开会话前调一次，登录后再调一次可刷新。
+ * 缓存挂在传入的注册表上，`buildConfigOptions` 须传同一个对象。
+ */
+export async function prepareConfigOptions(providers) {
+    const access = new Map();
+    for (const provider of providers.list())
+        access.set(provider.id, await providerAccess(providers, provider));
+    accessCache.set(providers, access);
+}
+export function buildConfigOptions(session, providers, env, extras = {}) {
+    const m = msg().acp.config;
+    const current = session.state.model === undefined ? undefined : formatModelRef(session.state.model);
+    const known = accessCache.get(providers);
+    const catalog = hideFakeProvider(providers, env)
+        .list()
+        .map((provider) => ({
+        provider,
+        access: known?.get(provider.id) ?? (provider.requiresApiKey ? "none" : "local"),
+    }));
+    const items = catalogItems({ providers: catalog }, { view: "configured", enabled: extras.enabled, current, hints: false });
+    // 按供应商重新分组（`catalogItems` 的组标题带可用状态，当前模型另成一组）
+    const groups = new Map();
+    for (const item of items) {
+        const providerId = item.value.slice(0, item.value.indexOf("/"));
+        let group = groups.get(providerId);
+        if (group === undefined) {
+            group = {
+                group: providerId,
+                name: providers.get(providerId)?.name ?? providerId,
+                options: [],
+            };
+            groups.set(providerId, group);
+        }
+        if (group.options.some((o) => o.value === item.value))
+            continue;
+        group.options.push({
+            value: item.value,
+            name: item.label,
+            ...(item.description !== undefined ? { description: item.description } : {}),
+        });
+    }
+    const modes = permissionModes(extras.mode ?? session.state.permissionMode);
+    const options = [
+        {
+            id: CONFIG_IDS.mode,
+            name: m.mode,
+            category: "mode",
+            type: "select",
+            currentValue: modes.currentModeId,
+            options: modes.availableModes.map(({ id, name, description }) => ({
+                value: id,
+                name,
+                description,
+            })),
+        },
+    ];
+    if (current !== undefined)
+        options.push({
+            id: CONFIG_IDS.model,
+            name: m.model,
+            category: "model",
+            type: "select",
+            currentValue: current,
+            options: [...groups.values()],
+        });
+    const lookup = current === undefined ? undefined : providers.findModel(current);
+    const model = lookup?.ok === true ? lookup.model : undefined;
+    const levels = model === undefined ? [...THINKING_LEVELS] : getSupportedLevels(model);
+    const level = session.state.thinkingLevel;
+    options.push({
+        id: CONFIG_IDS.thinking,
+        name: m.thinking,
+        category: "thought_level",
+        type: "select",
+        currentValue: model === undefined || levels.includes(level) ? level : clampThinkingLevel(model, level),
+        options: levels.map((value) => ({ value, name: m.levels[value] })),
+    });
+    return options;
+}
+/** 未知 id / value → RpcError invalidParams。 */
+export async function applyConfigOption(session, params) {
+    const m = msg().acp.config;
+    const value = params.value;
+    switch (params.configId) {
+        case CONFIG_IDS.model:
+            if (typeof value !== "string" || value === "")
+                throw new RpcError(RPC_ERRORS.invalidParams, m.invalidValue(params.configId, String(value)));
+            try {
+                await session.setModel(value);
+            }
+            catch (error) {
+                if (error instanceof AmaError && error.code === "model_not_found")
+                    throw new RpcError(RPC_ERRORS.invalidParams, m.unknownModel(value));
+                throw error;
+            }
+            return;
+        case CONFIG_IDS.thinking:
+            if (!isThinkingLevel(value))
+                throw new RpcError(RPC_ERRORS.invalidParams, m.invalidValue(params.configId, String(value)));
+            if (value !== session.state.thinkingLevel)
+                session.setThinkingLevel(value);
+            return;
+        default:
+            throw new RpcError(RPC_ERRORS.invalidParams, msg().acp.core.unknownConfigOption(String(params.configId)));
+    }
+}
+export function availableCommands(resources) {
+    const commands = resources.skills.map((skill) => ({
+        name: `skill:${skill.name}`,
+        description: skill.description,
+    }));
+    for (const prompt of resources.prompts)
+        commands.push({
+            name: prompt.name,
+            description: prompt.description ?? "",
+            ...(prompt.argumentHint !== undefined ? { input: { hint: prompt.argumentHint } } : {}),
+        });
+    return commands;
+}

package/dist/modes/acp/acp-connection.d.ts

@@ -0,0 +1,29 @@
+/**
+ * `ama --mode acp` 的连接：JSON-RPC 对等端 + `initialize` 协商结果（docs/acp-plan.md §1.6）。[ACP-C0]
+ *
+ * 认证门（无模型时的握手，acp-auth-gate.ts）与服务端（acp-server.ts）共用同一条连接：门控在
+ * bootstrap 成功后把它交给 `AcpServer`，客户端不必重新 `initialize`。对等端开着协议级取消
+ * （`$/cancel_request`）：本端撤回挂起的请求会通知客户端，客户端撤回的请求 abort `ctx.signal`。
+ */
+import { JsonRpcPeer, type IncomingRequestContext } from "../../drivers/jsonrpc.js";
+import type { AcpClientCapabilities } from "../../drivers/acp/types.js";
+export interface AcpConnectionHandlers {
+    onRequest(method: string, params: unknown, ctx: IncomingRequestContext): Promise<unknown>;
+    onNotification(method: string, params: unknown): void;
+}
+export interface AcpConnection {
+    /** `cancelRequests: true`。 */
+    readonly peer: JsonRpcPeer;
+    /** 客户端在 `initialize` 里声明的能力；之前为空对象。 */
+    clientCapabilities: AcpClientCapabilities;
+    /** 已处理过 `initialize`。 */
+    readonly initialized: boolean;
+    /** 记录 `initialize` 的协商结果（门控与服务端谁先处理谁记）。 */
+    markInitialized(capabilities: AcpClientCapabilities): void;
+}
+export declare function createAcpConnection(streams: {
+    input: NodeJS.ReadableStream;
+    output: NodeJS.WritableStream;
+}, log: (message: string) => void, handlers: AcpConnectionHandlers): AcpConnection;
+/** `initialize` 参数里的客户端能力（缺省或不是对象 → 空对象；不校验子字段）。 */
+export declare function clientCapabilitiesOf(params: Record<string, unknown>): AcpClientCapabilities;

package/dist/modes/acp/acp-connection.js

@@ -0,0 +1,37 @@
+/**
+ * `ama --mode acp` 的连接：JSON-RPC 对等端 + `initialize` 协商结果（docs/acp-plan.md §1.6）。[ACP-C0]
+ *
+ * 认证门（无模型时的握手，acp-auth-gate.ts）与服务端（acp-server.ts）共用同一条连接：门控在
+ * bootstrap 成功后把它交给 `AcpServer`，客户端不必重新 `initialize`。对等端开着协议级取消
+ * （`$/cancel_request`）：本端撤回挂起的请求会通知客户端，客户端撤回的请求 abort `ctx.signal`。
+ */
+import { JsonRpcPeer, } from "../../drivers/jsonrpc.js";
+import { msg } from "../../i18n/index.js";
+export function createAcpConnection(streams, log, handlers) {
+    let initialized = false;
+    const options = {
+        input: streams.input,
+        output: streams.output,
+        cancelRequests: true,
+        onRequest: (method, params, ctx) => handlers.onRequest(method, params, ctx),
+        onNotification: (method, params) => handlers.onNotification(method, params),
+        onProtocolError: (_line, reason) => log(msg().acp.core.unparsable(reason)),
+    };
+    const connection = {
+        peer: new JsonRpcPeer(options),
+        clientCapabilities: {},
+        get initialized() {
+            return initialized;
+        },
+        markInitialized(capabilities) {
+            connection.clientCapabilities = capabilities;
+            initialized = true;
+        },
+    };
+    return connection;
+}
+/** `initialize` 参数里的客户端能力（缺省或不是对象 → 空对象；不校验子字段）。 */
+export function clientCapabilitiesOf(params) {
+    const value = params["clientCapabilities"];
+    return value !== null && typeof value === "object" ? value : {};
+}