@armadra/agent 0.6.8 → 0.7.0

package/dist/cli/args.d.ts

@@ -101,6 +101,12 @@ export declare class UsageError extends AmaError {
 }
 export { helpText } from "./help-text.js";
 export declare function emptyArgs(): ParsedArgs;
+/**
+ * ACP terminal 型认证方法的入口（docs/acp.md「无模型时」）：客户端把方法的 `args` **追加**到配置好的
+ * Agent 启动命令后面（规范原文 append），实际得到 `ama --mode acp … --acp-terminal-auth <id>`。
+ * 见到这个标志就不再按启动参数解析，转成对应的 `auth` 子命令；同一条命令里的 `--auth-file`、`--lang` 一并带上。
+ */
+export declare const ACP_TERMINAL_AUTH_FLAG = "--acp-terminal-auth";
 /** 解析 argv（不含 node 与脚本路径）；用法错误抛 UsageError（退出码 2）。 */
 export declare function parseArgs(argv: readonly string[]): ParseResult;
 /** 子命令内部的小解析器：`--name value` / `--name=value` / 位置参数。 */

package/dist/cli/args.js

@@ -311,9 +311,55 @@ function validate(args) {
         throw new UsageError(m.imagePrintOnly);
     }
 }
+/**
+ * ACP terminal 型认证方法的入口（docs/acp.md「无模型时」）：客户端把方法的 `args` **追加**到配置好的
+ * Agent 启动命令后面（规范原文 append），实际得到 `ama --mode acp … --acp-terminal-auth <id>`。
+ * 见到这个标志就不再按启动参数解析，转成对应的 `auth` 子命令；同一条命令里的 `--auth-file`、`--lang` 一并带上。
+ */
+export const ACP_TERMINAL_AUTH_FLAG = "--acp-terminal-auth";
+const ACP_TERMINAL_AUTH_ARGV = {
+    chatgpt: ["login", "chatgpt"],
+    "api-key": ["set"],
+};
+function acpTerminalAuth(argv) {
+    let id;
+    let lang;
+    let authFile;
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i] ?? "";
+        if (token === "--")
+            break;
+        if (token === ACP_TERMINAL_AUTH_FLAG)
+            id = argv[++i] ?? "";
+        else if (token.startsWith(`${ACP_TERMINAL_AUTH_FLAG}=`))
+            id = token.slice(ACP_TERMINAL_AUTH_FLAG.length + 1);
+        else if (token === "--auth-file")
+            authFile = argv[++i];
+        else if (token.startsWith("--auth-file="))
+            authFile = token.slice("--auth-file=".length);
+        else if (token === "--lang" && argv[i + 1] !== undefined)
+            lang = choice("lang", argv[++i], LOCALES);
+        else if (token.startsWith("--lang="))
+            lang = choice("lang", token.slice(7), LOCALES);
+    }
+    if (id === undefined)
+        return undefined;
+    const sub = ACP_TERMINAL_AUTH_ARGV[id];
+    if (sub === undefined)
+        throw new UsageError(msg().cli.args.unknownTerminalAuth(id));
+    return {
+        kind: "subcommand",
+        name: "auth",
+        argv: [...sub, ...(authFile !== undefined ? ["--auth-file", authFile] : [])],
+        ...(lang !== undefined ? { lang } : {}),
+    };
+}
 /** 解析 argv（不含 node 与脚本路径）；用法错误抛 UsageError（退出码 2）。 */
 export function parseArgs(argv) {
     const lead = leadingLang(argv);
+    const terminalAuth = acpTerminalAuth(argv);
+    if (terminalAuth !== undefined)
+        return terminalAuth;
     const first = argv[lead.next];
     if (first !== undefined && SUBCOMMANDS.includes(first)) {
         return {

package/dist/cli/bootstrap.js

@@ -400,14 +400,25 @@ export async function runCli(argv, deps, io) {
         io.stderr(msg().cli.bootstrap.runtimeNotAssembled);
         return ExitCode.RuntimeError;
     }
+    // [ACP-A] ACP 的 stdout 只给协议：bootstrap 之前就接管（宿主 / Hook 加载期的 console.log 也改写到 stderr）
+    const early = acp ? takeOverStdout() : undefined;
     let runtime;
     try {
         runtime = await bootstrap(args, deps, io);
     }
     catch (error) {
-        return reportError(error, io);
+        try {
+            // [ACP-A] --mode acp 没有可用模型：认证门照常握手，会话方法重试 bootstrap（docs/acp-plan.md §2.2）
+            if (acp && error instanceof StartupError && error.exitCode === ExitCode.NoModel)
+                return await (await import("../modes/acp/acp-auth-gate.js")).runAcpAuthGate(args, deps, io, error);
+            return reportError(error, io);
+        }
+        finally {
+            early?.();
+        }
     }
-    const restore = runtime.mode === "print" || runtime.mode === "rpc" ? takeOverStdout() : () => undefined;
+    const restore = early ??
+        (runtime.mode === "print" || runtime.mode === "rpc" ? takeOverStdout() : () => undefined);
     let cleanupFrom = () => undefined;
     try {
         if (runtime.mode !== "interactive")

package/dist/cli/compose-events.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 组装根：会话事件 → 宿主事件总线（实施计划 §1.4 表）。[B6，ACP-C0 从 compose-session.ts 迁出]
+ *
+ * hook_executed、session_start / session_shutdown 由 bootstrap 与会话切换发，不在这里桥接；
+ * 第三波加 `cache_miss` / `context_pressure`，第五波加子 Agent 与计划事件。
+ */
+import type { SessionEvent } from "../agent/types.js";
+import type { AgentEventBus } from "../host/api-impl.js";
+/** §1.4：SessionEvent → AgentEvents。 */
+export declare function bridgeEvent(event: SessionEvent, bus: AgentEventBus): void;

package/dist/cli/compose-events.js

@@ -0,0 +1,97 @@
+/**
+ * 组装根：会话事件 → 宿主事件总线（实施计划 §1.4 表）。[B6，ACP-C0 从 compose-session.ts 迁出]
+ *
+ * hook_executed、session_start / session_shutdown 由 bootstrap 与会话切换发，不在这里桥接；
+ * 第三波加 `cache_miss` / `context_pressure`，第五波加子 Agent 与计划事件。
+ */
+/** §1.4：SessionEvent → AgentEvents。 */
+export function bridgeEvent(event, bus) {
+    switch (event.type) {
+        case "before_agent_start":
+            void bus.emit("before_agent_start", { prompt: event.prompt });
+            return;
+        case "agent_start":
+        case "turn_start":
+        case "turn_end":
+        case "agent_before_settle":
+            void bus.emit(event.type, {});
+            return;
+        case "agent_end":
+            void bus.emit("agent_end", { stopReason: event.stopReason, willRetry: event.willRetry });
+            return;
+        case "agent_settled":
+            void bus.emit("agent_settled", event.warning === undefined ? {} : { warning: event.warning });
+            return;
+        case "tool_execution_start":
+            void bus.emit("tool_call", {
+                toolCallId: event.toolCallId,
+                toolName: event.toolName,
+                input: event.args,
+            });
+            return;
+        case "tool_execution_end":
+            void bus.emit("tool_result", {
+                toolCallId: event.toolCallId,
+                toolName: event.toolName,
+                isError: event.isError,
+            });
+            return;
+        case "permission_request":
+            void bus.emit("tool_approval_requested", {
+                requestId: event.requestId,
+                toolName: event.toolName,
+            });
+            return;
+        case "permission_resolved":
+            void bus.emit("tool_approval_resolved", {
+                requestId: event.requestId,
+                decision: event.decision,
+            });
+            return;
+        case "compaction_end":
+            if (event.result !== undefined)
+                void bus.emit("session_compact", { tokensBefore: event.result.tokensBefore });
+            return;
+        case "model_changed":
+            void bus.emit("model_select", { model: event.model });
+            return;
+        case "cache_miss": {
+            const { type: _type, ...miss } = event;
+            void bus.emit("cache_miss", miss);
+            return;
+        }
+        case "context_pressure": {
+            const { type: _type, ...pressure } = event;
+            void bus.emit("context_pressure", pressure);
+            return;
+        }
+        case "quota_update": {
+            const { type: _type, ...quota } = event;
+            void bus.emit("quota_update", quota);
+            return;
+        }
+        // [W5-C0] 子 Agent 与计划事件
+        case "subagent_start": {
+            const { type: _type, ...payload } = event;
+            void bus.emit("subagent_start", payload);
+            return;
+        }
+        case "subagent_end": {
+            const { type: _type, ...payload } = event;
+            void bus.emit("subagent_end", payload);
+            return;
+        }
+        case "plan_proposed": {
+            const { type: _type, ...payload } = event;
+            void bus.emit("plan_proposed", payload);
+            return;
+        }
+        case "plan_resolved": {
+            const { type: _type, ...payload } = event;
+            void bus.emit("plan_resolved", payload);
+            return;
+        }
+        default:
+            return;
+    }
+}

package/dist/cli/compose-session.d.ts

@@ -14,18 +14,21 @@
  *   `AMA_CACHE_RETENTION` 覆盖 → 会话的 `cache` 设置；宿主 `cache.onWarmingDecision` 每次现取。
  * - 会话切换：`switchSession()` 复用同一份装配材料建新会话，`assembly.onSessionReplaced(next)`
  *   让宿主访问、Hook 公共字段与退出 dispose 跟随新会话。
+ * - [ACP-C0] 多会话：`createSessionAlongside()` 建兄弟会话（不替换前台、不 dispose 旧会话），
+ *   `setForegroundSession()` 把宿主 / Hook / 工具工厂的「当前会话」切过去，`disposeSessionAlongside()`
+ *   释放一个兄弟会话。事件桥接在 compose-events.ts。
  */
 import type { ProviderRegistryApi } from "../ai/types.js";
 import type { BashSandbox } from "../sandbox/bash.js";
 import { AgentSessionImpl } from "../agent/session.js";
-import type { AgentSession, CacheSettings, SessionEvent } from "../agent/types.js";
+import type { AgentSession, CacheSettings } from "../agent/types.js";
 import { type AmaConfig } from "../config/types.js";
-import type { AgentEventBus } from "../host/api-impl.js";
 import type { Skill } from "../skills/discover.js";
 import { type PromptTemplate } from "../skills/templates.js";
 import type { MemoryRuntime } from "../memory/runtime.js";
 import type { SessionAssembly } from "./deps.js";
 import type { Runtime } from "./runtime.js";
+export { bridgeEvent } from "./compose-events.js";
 /** createRuntimeDeps 闭包里跨步骤共享的状态。 */
 export interface ComposeState {
     /** 第 10 步发现的完整 Skill（`/skill:` 展开与索引用）。 */
@@ -60,8 +63,6 @@ export declare function cacheSettingsFrom(config: Pick<AmaConfig, "cache">, env?
  * （协议层取缺省 300 000）。0 关闭；非法的环境变量值忽略并 warning。
  */
 export declare function idleTimeoutFrom(config: Pick<AmaConfig, "request">, env?: NodeJS.ProcessEnv, warn?: (message: string) => void): number | undefined;
-/** §1.4：SessionEvent → AgentEvents。 */
-export declare function bridgeEvent(event: SessionEvent, bus: AgentEventBus): void;
 /** 第 14 步：组装主会话。 */
 export declare function composeSession(assembly: SessionAssembly, state?: ComposeState, options?: SessionComposeOptions): AgentSessionImpl;
 /** 模式层当前应操作的会话（`switchSession` 之后不再是 `Runtime.session`）。 */
@@ -83,3 +84,23 @@ export type SwitchRequest = {
  * dispose，新会话复用装配材料，宿主总线发 session_start，再跑 SessionStart Hook。
  */
 export declare function switchSession(target: Runtime | AgentSession, request: SwitchRequest): Promise<AgentSessionImpl>;
+/**
+ * [ACP-C0] 不替换当前会话、不 dispose、不跑 SessionEnd Hook 地再建一个会话（ACP 多会话）。
+ * 宿主总线发 `session_start`，再以新会话的公共字段跑 SessionStart Hook（additionalContext 只给它）。
+ * 会话自身的 `session_start` 事件由模式在订阅之后调 `announceStart` 发。
+ */
+export declare function createSessionAlongside(target: Runtime | AgentSession, request: Extract<SwitchRequest, {
+    kind: "new" | "resume";
+}>, options?: {
+    createIfMissing?: boolean;
+}): Promise<AgentSessionImpl>;
+/**
+ * [ACP-C0] 把宿主（HostApi `session.*`）、Hook 公共字段与工具工厂的「当前会话」切到 `session`，
+ * 清掉「本会话允许」的记忆。返回是否真的切换了（已是前台时什么都不做）。
+ */
+export declare function setForegroundSession(target: Runtime | AgentSession, session: AgentSessionImpl): boolean;
+/**
+ * [ACP-C0] 释放一个兄弟会话：以它的公共字段跑 SessionEnd Hook（reason `switch`）后 dispose。
+ * 它是前台时先把前台切到 `fallback`。运行中的会话要先 abort 并等空闲。
+ */
+export declare function disposeSessionAlongside(target: Runtime | AgentSession, session: AgentSessionImpl, fallback: AgentSessionImpl): Promise<void>;

package/dist/cli/compose-session.js

@@ -14,6 +14,9 @@
  *   `AMA_CACHE_RETENTION` 覆盖 → 会话的 `cache` 设置；宿主 `cache.onWarmingDecision` 每次现取。
  * - 会话切换：`switchSession()` 复用同一份装配材料建新会话，`assembly.onSessionReplaced(next)`
  *   让宿主访问、Hook 公共字段与退出 dispose 跟随新会话。
+ * - [ACP-C0] 多会话：`createSessionAlongside()` 建兄弟会话（不替换前台、不 dispose 旧会话），
+ *   `setForegroundSession()` 把宿主 / Hook / 工具工厂的「当前会话」切过去，`disposeSessionAlongside()`
+ *   释放一个兄弟会话。事件桥接在 compose-events.ts。
  */
 import { readFileSync } from "node:fs";
 import { resolveLimits } from "../agent/limits.js";
@@ -33,10 +36,12 @@ import { formatSkillIndex } from "../skills/index-prompt.js";
 import { expandPromptCommand } from "../skills/templates.js";
 import { PresetToolRegistry } from "../tools/presets.js";
 import { openSession } from "./compose-store.js";
+import { bridgeEvent } from "./compose-events.js";
 import { composeExtensions } from "./compose-extensions.js";
 import { attachMemory, withMemorySection } from "./compose-memory.js";
 import { ExitCode } from "./exit-codes.js";
 import { msg } from "../i18n/index.js";
+export { bridgeEvent } from "./compose-events.js";
 export function emptyComposeState() {
     return { skills: [], templates: [], warnings: [], session: undefined };
 }
@@ -91,7 +96,7 @@ function contextFiles(record) {
 export function replyLanguageRule(language) {
     return `Reply to the user in ${language}.`;
 }
-function systemInput(record, active) {
+function systemInput(record, active, hookContextOf) {
     const system = { contextFiles: contextFiles(record) };
     const override = record.assembly.overrides?.systemPrompt;
     if (override?.mode === "replace")
@@ -111,7 +116,7 @@ function systemInput(record, active) {
     const host = hostInstructions(record);
     if (host.length > 0)
         system.hostInstructions = host;
-    const hookContext = record.hookContext();
+    const hookContext = hookContextOf();
     if (hookContext !== undefined && hookContext !== "")
         system.hookContext = hookContext;
     return system;
@@ -119,7 +124,7 @@ function systemInput(record, active) {
 /** 提示展开前刷新会晚到的系统提示材料（值不变则不产生补丁）。 */
 function refreshSystem(record, session) {
     const patch = {};
-    const hookContext = record.hookContext();
+    const hookContext = (record.hookContexts.get(session) ?? record.hookContext)();
     if (hookContext !== undefined && hookContext !== "")
         patch.hookContext = hookContext;
     const host = hostInstructions(record);
@@ -177,98 +182,11 @@ export function idleTimeoutFrom(config, env = process.env, warn = () => undefine
     }
     return config.request?.idleTimeoutMs;
 }
-/** §1.4：SessionEvent → AgentEvents。 */
-export function bridgeEvent(event, bus) {
-    switch (event.type) {
-        case "before_agent_start":
-            void bus.emit("before_agent_start", { prompt: event.prompt });
-            return;
-        case "agent_start":
-        case "turn_start":
-        case "turn_end":
-        case "agent_before_settle":
-            void bus.emit(event.type, {});
-            return;
-        case "agent_end":
-            void bus.emit("agent_end", { stopReason: event.stopReason, willRetry: event.willRetry });
-            return;
-        case "agent_settled":
-            void bus.emit("agent_settled", event.warning === undefined ? {} : { warning: event.warning });
-            return;
-        case "tool_execution_start":
-            void bus.emit("tool_call", {
-                toolCallId: event.toolCallId,
-                toolName: event.toolName,
-                input: event.args,
-            });
-            return;
-        case "tool_execution_end":
-            void bus.emit("tool_result", {
-                toolCallId: event.toolCallId,
-                toolName: event.toolName,
-                isError: event.isError,
-            });
-            return;
-        case "permission_request":
-            void bus.emit("tool_approval_requested", {
-                requestId: event.requestId,
-                toolName: event.toolName,
-            });
-            return;
-        case "permission_resolved":
-            void bus.emit("tool_approval_resolved", {
-                requestId: event.requestId,
-                decision: event.decision,
-            });
-            return;
-        case "compaction_end":
-            if (event.result !== undefined)
-                void bus.emit("session_compact", { tokensBefore: event.result.tokensBefore });
-            return;
-        case "model_changed":
-            void bus.emit("model_select", { model: event.model });
-            return;
-        case "cache_miss": {
-            const { type: _type, ...miss } = event;
-            void bus.emit("cache_miss", miss);
-            return;
-        }
-        case "context_pressure": {
-            const { type: _type, ...pressure } = event;
-            void bus.emit("context_pressure", pressure);
-            return;
-        }
-        case "quota_update": {
-            const { type: _type, ...quota } = event;
-            void bus.emit("quota_update", quota);
-            return;
-        }
-        // [W5-C0] 子 Agent 与计划事件
-        case "subagent_start": {
-            const { type: _type, ...payload } = event;
-            void bus.emit("subagent_start", payload);
-            return;
-        }
-        case "subagent_end": {
-            const { type: _type, ...payload } = event;
-            void bus.emit("subagent_end", payload);
-            return;
-        }
-        case "plan_proposed": {
-            const { type: _type, ...payload } = event;
-            void bus.emit("plan_proposed", payload);
-            return;
-        }
-        case "plan_resolved": {
-            const { type: _type, ...payload } = event;
-            void bus.emit("plan_resolved", payload);
-            return;
-        }
-        default:
-            return;
-    }
-}
-function buildSession(record, manager, model, thinkingLevel) {
+function buildSession(record, manager, model, thinkingLevel, 
+/** 这个会话的 SessionStart additionalContext；缺省沿用前台的。 */
+hookContext = record.hookContext, 
+/** false：兄弟会话，不改工具工厂的当前会话。 */
+foreground = true) {
     const { assembly } = record;
     const registry = assembly.tools;
     const all = registry
@@ -290,7 +208,7 @@ function buildSession(record, manager, model, thinkingLevel) {
         unattended: assembly.unattended,
         approvalTimeoutMs: approvalTimeout(record.options),
         hooks: assembly.hooks,
-        system: withMemorySection(systemInput(record, active), record.state.memory, manager),
+        system: withMemorySection(systemInput(record, active, hookContext), record.state.memory, manager),
         compaction: { ...config.compaction },
         retry: { ...config.retry },
         expandPrompt: (text) => expandPrompt(record, session, text),
@@ -337,7 +255,10 @@ function buildSession(record, manager, model, thinkingLevel) {
     attachMemory(session, record.state.memory);
     session.subscribe((event) => bridgeEvent(event, assembly.events));
     records.set(session, record);
-    record.state.session = session;
+    record.hookContexts.set(session, hookContext);
+    record.live.add(session);
+    if (foreground)
+        record.state.session = session;
     return session;
 }
 /** 第 14 步：组装主会话。 */
@@ -366,6 +287,8 @@ export function composeSession(assembly, state = emptyComposeState(), options =
         options,
         chain,
         hookContext: () => assembly.sessionStartContext(),
+        hookContexts: new WeakMap(),
+        live: new Set(),
         hostTexts: new Map(),
         log: options.log ?? stderrLog(),
     };
@@ -376,11 +299,13 @@ export function composeSession(assembly, state = emptyComposeState(), options =
         // 宿主在会话创建之后注册的工具：追加进当前会话，下次请求以 system 补丁声明（只在末尾追加）。
         registry.onRegister((tool) => {
             const active = registry.active().some((t) => t.name === tool.name);
-            try {
-                record.current.addTool(tool, active);
-            }
-            catch (error) {
-                record.log("warn", msg().cli.composeSession.appendToolFailed(tool.name, error.message));
+            for (const live of record.live) {
+                try {
+                    live.addTool(tool, active);
+                }
+                catch (error) {
+                    record.log("warn", msg().cli.composeSession.appendToolFailed(tool.name, error.message));
+                }
             }
         });
     }
@@ -437,11 +362,12 @@ export async function switchSession(target, request) {
         .run("SessionEnd", { reason: request.kind === "new" ? "new" : "switch" })
         .catch(() => undefined);
     await old.dispose();
+    record.live.delete(old);
     if (assembly.permission instanceof PermissionPipeline)
         assembly.permission.clearSessionGrants();
     let hookContext;
     record.hookContext = () => hookContext;
-    const next = buildSession(record, manager, old.model(), old.thinkingLevel());
+    const next = buildSession(record, manager, old.model(), old.thinkingLevel(), record.hookContext);
     record.current = next;
     assembly.onSessionReplaced(next);
     const file = next.state.sessionFile;
@@ -456,3 +382,104 @@ export async function switchSession(target, request) {
     // 会话自身的 session_start 由模式在重新订阅之后调 `announceStart` 发（否则订阅者收不到）。
     return next;
 }
+function requireRecord(target) {
+    const record = recordOf(target);
+    if (record === undefined)
+        throw new AmaError("not_implemented", msg().cli.composeSession.notComposed);
+    return record;
+}
+/** 按某个会话覆盖 Hook 公共字段（兄弟会话的 SessionStart / SessionEnd 不该带前台会话的 id）。 */
+function hookFieldsOf(session) {
+    const file = session.state.sessionFile;
+    return {
+        sessionId: session.state.sessionId,
+        sessionFile: file,
+        transcriptPath: file,
+        cwd: session.state.cwd,
+        model: session.state.model,
+        permissionMode: session.state.permissionMode,
+    };
+}
+/**
+ * [ACP-C0] 不替换当前会话、不 dispose、不跑 SessionEnd Hook 地再建一个会话（ACP 多会话）。
+ * 宿主总线发 `session_start`，再以新会话的公共字段跑 SessionStart Hook（additionalContext 只给它）。
+ * 会话自身的 `session_start` 事件由模式在订阅之后调 `announceStart` 发。
+ */
+export async function createSessionAlongside(target, request, options = {}) {
+    const record = requireRecord(target);
+    const current = record.current;
+    const { assembly } = record;
+    const sessionDir = assembly.paths.sessionDir;
+    const fresh = (id) => assembly.overrides?.noSession === true
+        ? SessionManager.inMemory(current.cwd)
+        : SessionManager.create(sessionDirForCwd(sessionDir, current.cwd), current.cwd, id !== undefined ? { id } : {});
+    let manager;
+    if (request.kind === "new")
+        manager = fresh();
+    else {
+        try {
+            manager = openSession({ kind: "resume", id: request.id }, { sessionDir, cwd: current.cwd });
+        }
+        catch (error) {
+            // [ACP] 空会话不落盘：进程重启后客户端再打开它时按原 id 新建一个空会话（调用方负责校验 id）
+            if (options.createIfMissing !== true ||
+                !(error instanceof AmaError && error.code === "session_not_found"))
+                throw error;
+            manager = fresh(request.id);
+        }
+    }
+    let hookContext;
+    const next = buildSession(record, manager, current.model(), current.thinkingLevel(), () => hookContext, false);
+    const file = next.state.sessionFile;
+    await assembly.events.emit("session_start", {
+        sessionId: next.state.sessionId,
+        ...(file !== undefined ? { sessionFile: file } : {}),
+        cwd: next.cwd,
+        reason: request.kind,
+    });
+    const outcome = await assembly.hooks
+        .run("SessionStart", { source: request.kind }, undefined, hookFieldsOf(next))
+        .catch(() => undefined);
+    hookContext = outcome?.additionalContext;
+    return next;
+}
+/**
+ * [ACP-C0] 把宿主（HostApi `session.*`）、Hook 公共字段与工具工厂的「当前会话」切到 `session`，
+ * 清掉「本会话允许」的记忆。返回是否真的切换了（已是前台时什么都不做）。
+ */
+export function setForegroundSession(target, session) {
+    const record = requireRecord(target);
+    if (records.get(session) !== record || !record.live.has(session))
+        throw new AmaError("invalid_arguments", msg().cli.composeSession.notLiveSession);
+    if (record.current === session)
+        return false;
+    record.current = session;
+    record.state.session = session;
+    record.hookContext = record.hookContexts.get(session) ?? (() => undefined);
+    record.assembly.onSessionReplaced(session);
+    const permission = record.assembly.permission;
+    if (permission instanceof PermissionPipeline)
+        permission.clearSessionGrants();
+    return true;
+}
+/**
+ * [ACP-C0] 释放一个兄弟会话：以它的公共字段跑 SessionEnd Hook（reason `switch`）后 dispose。
+ * 它是前台时先把前台切到 `fallback`。运行中的会话要先 abort 并等空闲。
+ */
+export async function disposeSessionAlongside(target, session, fallback) {
+    const record = requireRecord(target);
+    if (!record.live.has(session))
+        return;
+    if (session.state.isStreaming)
+        throw new AmaError("busy", msg().cli.composeSession.switchWhileStreaming);
+    if (record.current === session) {
+        if (fallback === session)
+            throw new AmaError("invalid_arguments", msg().cli.composeSession.notLiveSession);
+        setForegroundSession(target, fallback);
+    }
+    await record.assembly.hooks
+        .run("SessionEnd", { reason: "switch" }, undefined, hookFieldsOf(session))
+        .catch(() => undefined);
+    await session.dispose();
+    record.live.delete(session);
+}

package/dist/cli/compose.js

@@ -253,7 +253,12 @@ export function createRuntimeDeps(options = {}) {
                         description: s.description,
                         location: s.location,
                     })),
-                    prompts: prompts.templates.map((t) => ({ name: t.name, path: t.path })),
+                    prompts: prompts.templates.map((t) => ({
+                        name: t.name,
+                        path: t.path,
+                        description: t.description,
+                        ...(t.argumentHint !== undefined ? { argumentHint: t.argumentHint } : {}),
+                    })),
                     warnings,
                 };
             },

package/dist/cli/runtime.d.ts

@@ -43,10 +43,12 @@ export interface LoadedResources {
         description: string;
         location: string;
     }[];
-    /** 提示模板（命令名 → 文件）。 */
+    /** 提示模板（命令名 → 文件；`description` / `argumentHint` 取自 frontmatter，ACP 命令表用）。 */
     prompts: readonly {
         name: string;
         path: string;
+        description?: string;
+        argumentHint?: string;
     }[];
     instructions: readonly InstructionSource[];
 }

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

@@ -3,13 +3,25 @@
  * `ama auth login|logout|status chatgpt`（docs/wave6-plan.md §4.2）。[W6-O] 实现在 auth/chatgpt/cli.ts。
  *
  * - set：key 从 stdin 读取（TTY 下不回显），不经命令行参数，避免进 shell 历史；写 auth.json 0600。
+ *   [ACP-A] 不给 provider 且 stdin 是 TTY 时先用方向键选内置的需 key 供应商（ACP 终端登录方法
+ *   `ama auth set` 就这样跑）；非 TTY 仍是用法错误。
  * - list：只列供应商与 key 形态（字面量 / `!command` / `$ENV` 引用 / oauth 的 flavor 与计划），从不输出 key 或 token。
  * - `--auth-file <path>` 改变目标文件（缺省 `<configDir>/auth.json`）。
  */
 import { type AuthCliDeps } from "../../auth/chatgpt/cli.js";
+import { type ChoiceOption } from "../choice-prompt.js";
 import type { CliIo } from "../deps.js";
 /** 用法文本（按当前语言）。 */
 export declare function authUsage(): string;
+/** `auth set` 选择器列的供应商：内置、需要 API key、有 key 环境变量（不含 OAuth 的 chatgpt）。 */
+export declare function keyProviders(): {
+    id: string;
+    name: string;
+}[];
+export interface AuthDeps extends AuthCliDeps {
+    /** `auth set` 不给 provider 时的选择器（测试注入）；返回下标，取消返回 undefined。缺省方向键选择。 */
+    chooseProvider?(question: string, options: readonly ChoiceOption[]): Promise<number | undefined>;
+}
 /** 取第一行并去掉首尾空白；stdin 为空返回 ""。 */
 export declare function extractKey(raw: string): string;
-export declare function runAuth(argv: readonly string[], io: CliIo, deps?: AuthCliDeps): Promise<number>;
+export declare function runAuth(argv: readonly string[], io: CliIo, deps?: AuthDeps): Promise<number>;