@armadra/agent 0.6.1 → 0.6.3

package/dist/agent/subagent-registry.js

@@ -13,19 +13,21 @@
  * - 事件 `subagent_start / update / end`；父会话 `custom{ama.task}` 记任务快照（带 `status`），
  *   resume 时据此重建（未完成标 `interrupted`）。
  * - [W6-A] 子 Agent 视图的 `live()` / `message()`（实现在 subagent-direct.ts）。
+ * - [W7-B1] 缺省后台、前台转后台 `background()`、通知投递与 `settled()`（subagent-background.ts）。
  */
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { AmaError } from "../errors.js";
 import { DEFAULT_AGENT } from "../agents/builtin.js";
 import { AgentCatalog, resolveAgentModel } from "../agents/catalog.js";
-import { MAX_TURNS_NOTE, capTaskText, taskNotification, writeTaskOutput, } from "../agents/result.js";
-import { SubagentPool, TASK_CUSTOM_TYPE, applyRunnerEvent, flushText, newRecord, rebuildRecords, recordData, } from "../agents/task-record.js";
+import { MAX_TURNS_NOTE, capTaskText, writeTaskOutput } from "../agents/result.js";
+import { SubagentPool, TASK_CUSTOM_TYPE, applyRunnerEvent, flushText, newRecord, rebuildRecords, recordData, startEvent, taskStats, } from "../agents/task-record.js";
 import { registerTaskControl, unregisterTaskControl, } from "../agents/task-control.js";
 import { ZERO_USAGE } from "./loop.js";
 import { createWorktree, finishWorktree } from "./worktree.js";
 import { appendTraceEntry } from "./session-trace-writer.js";
 import { directMessage, drainDirect, liveOf } from "./subagent-direct.js";
+import { TaskNotifier, WaitDetach, backgroundRecords, blockingTasks, foregroundWaiter, settleTasks, startedResult, waitForTask, } from "./subagent-background.js";
 export const DEFAULT_SUBAGENT_CONCURRENCY = 4;
 export const DEFAULT_MAX_PENDING = 16;
 export const DEFAULT_RETAINED = 16;
@@ -71,7 +73,8 @@ export class SubagentRegistry {
     retained = [];
     seq = 0;
     disposed = false;
-    delivery = Promise.resolve();
+    notifier;
+    waits = new WaitDetach();
     constructor(host, env) {
         this.host = host;
         this.env = env;
@@ -80,6 +83,7 @@ export class SubagentRegistry {
         const rebuilt = rebuildRecords(host.manager.branch(), this.catalog, host.cwd);
         this.tasks = rebuilt.records;
         this.seq = rebuilt.seq;
+        this.notifier = new TaskNotifier(host, () => this.disposed);
     }
     now() {
         return this.env.now?.() ?? Date.now();
@@ -95,39 +99,48 @@ export class SubagentRegistry {
         return record === undefined ? undefined : { ...record.info };
     }
     stats() {
-        if (this.tasks.size === 0)
-            return undefined;
-        const byStatus = {};
-        let running = 0;
-        for (const { info } of this.tasks.values()) {
-            if (info.status === "running")
-                running++;
-            else
-                byStatus[info.status] = (byStatus[info.status] ?? 0) + 1;
-        }
-        return { total: this.tasks.size, running, byStatus };
+        return taskStats(this.tasks.values());
     }
     /** 运行中任务的已有输出（`task_ctl output`）；结束后为最终文本。 */
     output(taskId) {
         return this.tasks.get(taskId)?.text;
     }
-    /** 等任务结束或超时；超时返回 undefined。 */
-    async wait(taskId, timeoutMs) {
+    /** 等结束；超时或 signal（缺省本任务的转后台信号，`background()` 触发）返回 undefined。[W7-B1] */
+    async wait(taskId, timeoutMs, options = {}) {
         const record = this.tasks.get(taskId);
         if (record === undefined)
             throw new AmaError("task_not_found", `unknown task ${taskId}`);
-        if (record.running === undefined)
-            return record.last;
-        let timer;
-        const timeout = new Promise((resolve) => {
-            timer = setTimeout(() => resolve(undefined), timeoutMs);
+        return waitForTask(record, timeoutMs, options.signal ?? this.waits.signal(taskId), this.waits);
+    }
+    /** [W7-B1] `task_ctl wait` 用的打断信号（`background()` 触发后换新）。 */
+    detachSignal(taskId) {
+        return this.waits.signal(taskId);
+    }
+    /** [W7-B1] 正在阻塞父回合的任务：运行中的前台任务与有 `task_ctl wait` 在等的任务。 */
+    blocking() {
+        return blockingTasks(this.tasks.values(), this.waits);
+    }
+    /**
+     * [W7-B1] 前台任务转后台（§2.5，subagent-background.ts），并打断等它的 `task_ctl wait`；不给 taskId =
+     * 全部。返回被转后台或被打断等待的 taskId（不在运行时为空）。
+     */
+    background(taskId, reason = "user") {
+        if (this.disposed)
+            return [];
+        const one = taskId === undefined ? undefined : this.tasks.get(taskId);
+        const records = taskId === undefined ? [...this.tasks.values()] : one === undefined ? [] : [one];
+        const moved = backgroundRecords(records, reason, {
+            emit: (event) => this.host.emit(event),
+            persist: (record) => this.persist(record),
+            notify: (record, result) => this.notifier.notify(record, result),
+            afterMs: this.env.autoBackgroundAfterMs ?? 0,
+            outputFile: (id) => this.outputFileFor(id),
         });
-        try {
-            return await Promise.race([record.running, timeout]);
-        }
-        finally {
-            clearTimeout(timer);
-        }
+        return [...new Set([...moved, ...this.waits.detach(taskId)])];
+    }
+    /** [W7-B1] `-p` 收尾：等到没有运行中的任务、通知回合也已跑完；会话关闭立即返回。 */
+    settled() {
+        return settleTasks(this.tasks, this.notifier, () => this.disposed);
     }
     /** [W6-A] 子 Agent 视图读的实时数据；未知任务 undefined。 */
     live(taskId) {
@@ -170,7 +183,7 @@ export class SubagentRegistry {
         const model = resolveAgentModel(agent, request.model, this.env.modelConfig ?? {});
         if (model.warning !== undefined)
             this.host.log("warn", `agent ${name}: ${model.warning}`);
-        const background = request.background ?? agent.background;
+        const background = request.background ?? agent.background ?? this.env.background ?? false;
         const taskId = `t${++this.seq}`;
         const record = newRecord({
             taskId,
@@ -197,7 +210,8 @@ export class SubagentRegistry {
         const resumable = record.agent.runner === "ama" ? ref?.sessionFile !== undefined : ref !== undefined;
         if (record.handle === undefined && !resumable)
             return Promise.resolve(failed(`Task ${taskId} cannot be continued (its session was not saved).`));
-        return this.launch(record, request, ama, request.background ?? false);
+        const background = request.background ?? record.agent.background ?? this.env.background;
+        return this.launch(record, request, ama, background ?? false);
     }
     launch(record, request, ama, background) {
         const controller = new AbortController();
@@ -217,33 +231,35 @@ export class SubagentRegistry {
         else
             parentSignal?.addEventListener("abort", onParentAbort, { once: true });
         this.persist(record);
+        let timer;
         const running = this.execute(record, request, ama, controller.signal).finally(() => {
+            clearTimeout(timer);
             parentSignal?.removeEventListener("abort", onParentAbort);
+            delete record.foregroundWaiter;
             delete record.running;
             delete record.controller;
             if (!this.disposed)
                 drainDirect(record, this.host);
         });
         record.running = running;
-        if (!background)
-            return running;
-        void running.then((result) => this.notify(record, result));
-        return Promise.resolve(this.startedResult(record));
-    }
-    startedResult(record) {
-        const result = {
-            text: `Started background task ${record.info.taskId} (agent ${record.agent.name}). ` +
-                "A <task-notification> arrives when it finishes; use task_ctl to wait, stop or read output.",
-            usage: { ...ZERO_USAGE },
-            stopReason: "stop",
-            isError: false,
-            taskId: record.info.taskId,
-            status: "running",
-        };
         const file = this.outputFileFor(record.info.taskId);
-        if (file !== undefined)
-            result.outputFile = file;
-        return result;
+        if (background) {
+            void running.then((result) => this.notifier.notify(record, result));
+            return Promise.resolve(startedResult(record, file));
+        }
+        // [W7-B1] 前台：转后台（background()）时等待者先行 resolve，工具调用立即返回
+        const { waiter, promise } = foregroundWaiter(() => {
+            clearTimeout(timer);
+            parentSignal?.removeEventListener("abort", onParentAbort);
+            delete record.onUpdate;
+        });
+        record.foregroundWaiter = waiter;
+        const after = this.env.autoBackgroundAfterMs ?? 0;
+        if (after > 0) {
+            timer = setTimeout(() => this.background(record.info.taskId, "timeout"), after);
+            timer.unref?.();
+        }
+        return Promise.race([running, promise]);
     }
     async execute(record, request, ama, signal) {
         record.queued = true;
@@ -332,21 +348,7 @@ export class SubagentRegistry {
         return handle;
     }
     emitStart(record, handle) {
-        const event = {
-            type: "subagent_start",
-            taskId: record.info.taskId,
-            parentToolCallId: record.parentToolCallId,
-            agent: record.agent.name,
-            runner: record.agent.runner,
-            description: record.info.description,
-            background: record.info.background,
-            cwd: record.cwd,
-        };
-        if (handle.model !== undefined)
-            event.model = handle.model;
-        if (handle.sessionFile !== undefined)
-            event.sessionFile = handle.sessionFile;
-        this.host.emit(event);
+        this.host.emit(startEvent(record, handle));
     }
     sink() {
         return {
@@ -425,36 +427,6 @@ export class SubagentRegistry {
         this.retain(info.taskId);
         return final;
     }
-    notify(record, result) {
-        // 被停止的任务（task_ctl stop、会话关闭）不再通知：发起停止的一方已经知道
-        if (this.disposed || result.status === "aborted")
-            return;
-        const info = record.info;
-        const text = taskNotification({
-            taskId: info.taskId,
-            agent: info.agent,
-            status: (result.status ?? "completed"),
-            ...(info.turns === undefined ? {} : { turns: info.turns }),
-            ...(info.usage === undefined ? {} : { usage: info.usage }),
-            ...(info.outputFile === undefined ? {} : { outputFile: info.outputFile }),
-            report: result.text,
-        });
-        const host = this.host;
-        const followUp = host.followUp;
-        if (followUp === undefined) {
-            host.log("warn", `task ${info.taskId} finished but the session cannot be notified`);
-            return;
-        }
-        // 父空闲时投递（开新回合）；父正忙则等这一周期结束再投——周期收尾阶段入队的 followUp 会滞留到
-        // 下一次提示。串行投递保证按完成顺序到达。
-        this.delivery = this.delivery
-            .then(async () => {
-            await host.waitForIdle?.();
-            if (!this.disposed)
-                await followUp.call(host, text, { origin: "task" });
-        })
-            .catch((error) => host.log("warn", `task notification failed: ${String(error)}`));
-    }
     // -------------------------------------------------------------------------
     // 落盘、保留与重建
     // -------------------------------------------------------------------------

package/dist/agent/types-w5.d.ts

@@ -80,6 +80,16 @@ export interface SubagentEndEvent {
         changed: boolean;
     };
 }
+/**
+ * [W7-B1] 前台任务转后台（docs/agents-concurrency-plan.md §2.5）：`user` = 人（TUI `Ctrl+B` 等），
+ * `timeout` = `subagents.autoBackgroundAfterMs` 到时，`host` = 宿主 / SDK（`session.backgroundTask`）。
+ */
+export interface SubagentBackgroundEvent {
+    type: "subagent_background";
+    taskId: string;
+    parentToolCallId: string;
+    reason: "user" | "timeout" | "host";
+}
 export interface PlanStep {
     /** `S1`、`S2` …；编号列表时按序号生成。 */
     id: string;
@@ -161,7 +171,7 @@ export type SessionEventW5 =
 /** 流式中 ≤ 2 Hz（`ui.animation: false` 时不发）；数据从 `getStats().telemetry` 取。 */
 {
     type: "telemetry_tick";
-} | SubagentStartEvent | SubagentUpdateEvent | SubagentEndEvent | PlanProposedEvent | PlanResolvedEvent | TodoUpdatedEvent | LimitReachedEvent | ModelFallbackEvent | BackgroundJobEvent;
+} | SubagentStartEvent | SubagentUpdateEvent | SubagentEndEvent | SubagentBackgroundEvent | PlanProposedEvent | PlanResolvedEvent | TodoUpdatedEvent | LimitReachedEvent | ModelFallbackEvent | BackgroundJobEvent;
 /** 外部 Agent 记账（`custom{ama.agent-usage}` 汇总，§5.4）。 */
 export interface ExternalAgentStats {
     byAgent: Record<string, {

package/dist/agent/types.d.ts

@@ -397,6 +397,11 @@ export interface AgentSession {
         steering: string[];
         followUp: string[];
     };
+    /**
+     * [W7-B1] 阻塞中的前台子 Agent 任务转后台（不给 taskId = 全部；docs/agents-concurrency-plan.md §2.5）。
+     * `reason` 缺省 `"host"`（宿主 / SDK）；TUI 的人工操作传 `"user"`。返回被转后台或被打断等待的 taskId。
+     */
+    backgroundTask(taskId?: string, reason?: "user" | "timeout" | "host"): string[];
     subscribe(listener: (event: SessionEvent) => void): () => void;
     compact(instructions?: string): Promise<CompactionResult>;
     fork(entryId: string): Promise<AgentSession>;

package/dist/agents/builtin.js

@@ -17,7 +17,6 @@ function builtin(name, description, prompt, permissionMode) {
         model: "inherit",
         maxTurns: 30,
         isolation: "none",
-        background: false,
         runner: "ama",
         prompt,
         source: "builtin",

package/dist/agents/external.js

@@ -48,7 +48,6 @@ function definition(name, runner, description, source) {
         model: "inherit",
         maxTurns: 30,
         isolation: "none",
-        background: false,
         // 驱动表 id（gemini 等）与宿主 id 不在 AgentRunnerSpec 的字面量里，线上照样是字符串
         runner: runner,
         prompt: "",

package/dist/agents/parse.js

@@ -85,8 +85,8 @@ export function parseAgentDefinition(text, filePath, source) {
     const isolation = data["isolation"] ?? "none";
     if (isolation !== "none" && isolation !== "worktree")
         return fail("isolation must be none or worktree");
-    const background = data["background"] ?? false;
-    if (typeof background !== "boolean")
+    const background = data["background"];
+    if (background !== undefined && typeof background !== "boolean")
         return fail("background must be true or false");
     if (runner !== "ama") {
         const ignored = ["tools", "disallowed-tools", "permission-mode"].filter((key) => data[key] !== undefined);
@@ -100,12 +100,13 @@ export function parseAgentDefinition(text, filePath, source) {
         model: model.trim(),
         maxTurns,
         isolation,
-        background,
         runner,
         prompt: fm.body.trim(),
         source,
         filePath,
     };
+    if (background !== undefined)
+        agent.background = background;
     if (tools !== undefined)
         agent.tools = tools;
     if (disallowedTools !== undefined)

package/dist/agents/result.d.ts

@@ -28,5 +28,11 @@ export interface NotificationInput {
     report: string;
 }
 export declare function taskNotification(input: NotificationInput): string;
+export declare const NOTIFY_HINT = "A <task-notification> arrives when it finishes; use task_ctl to wait, stop or read output.";
+export declare function startedText(taskId: string, agent: string): string;
+/** 前台转后台的工具结果（§2.5.3）：固定英文；task 工具在前面加 `[task tN] `。 */
+export declare function backgroundedText(reason: "user" | "timeout" | "host", afterMs: number): string;
+/** `task_ctl wait` 被转后台打断时的文案（§2.5.4）。 */
+export declare function waitDetachedText(taskId: string): string;
 /** 系统提示 rules 节的一句（task 工具的 promptGuidelines；会话开始即固定）。 */
-export declare const TASK_NOTIFICATION_RULE = "A <task-notification> message is a background task's report, not the user speaking.";
+export declare const TASK_NOTIFICATION_RULE: string;

package/dist/agents/result.js

@@ -63,5 +63,24 @@ export function taskNotification(input) {
         attrs.push(`outputFile="${attr(input.outputFile)}"`);
     return `<task-notification ${attrs.join(" ")}>\n${input.report}\n</task-notification>`;
 }
+// [W7-B1] 后台任务的固定英文文案（docs/agents-concurrency-plan.md §2.5；工具结果不进缓存前缀，但要
+// 稳定，便于测试与模型学习）。
+export const NOTIFY_HINT = "A <task-notification> arrives when it finishes; use task_ctl to wait, stop or read output.";
+export function startedText(taskId, agent) {
+    return `Started background task ${taskId} (agent ${agent}). ${NOTIFY_HINT}`;
+}
+/** 前台转后台的工具结果（§2.5.3）：固定英文；task 工具在前面加 `[task tN] `。 */
+export function backgroundedText(reason, afterMs) {
+    const head = reason === "timeout"
+        ? `Still running after ${Math.round(afterMs / 1000)}s and moved to the background`
+        : "Moved to the background by the user";
+    return `${head}; it was not interrupted. ${NOTIFY_HINT} Do not wait for it unless the user asks.`;
+}
+/** `task_ctl wait` 被转后台打断时的文案（§2.5.4）。 */
+export function waitDetachedText(taskId) {
+    return (`Task ${taskId} is still running and was moved to the background by the user; do not wait ` +
+        "again — a <task-notification> arrives when it finishes.");
+}
 /** 系统提示 rules 节的一句（task 工具的 promptGuidelines；会话开始即固定）。 */
-export const TASK_NOTIFICATION_RULE = "A <task-notification> message is a background task's report, not the user speaking.";
+export const TASK_NOTIFICATION_RULE = "A <task-notification> is a background task's report, not the user speaking; never sleep or " +
+    "poll for it.";

package/dist/agents/task-control.d.ts

@@ -8,9 +8,20 @@ import type { SubagentResult, TaskRegistryView } from "../tools/types.js";
 export interface TaskControl extends TaskRegistryView {
     /** 运行中是已有输出，结束后是最终文本。 */
     output(taskId: string): string | undefined;
-    /** 等结束或超时（超时返回 undefined）；未知 taskId 抛 `task_not_found`。 */
-    wait(taskId: string, timeoutMs: number): Promise<SubagentResult | undefined>;
+    /**
+     * 等结束、超时或 `signal` 触发（后两者返回 undefined）；未知 taskId 抛 `task_not_found`。
+     * [W7-B1] 不给 signal 时由 `background()` 打断（见 `detachSignal`）。
+     */
+    wait(taskId: string, timeoutMs: number, options?: {
+        signal?: AbortSignal;
+    }): Promise<SubagentResult | undefined>;
     stop(taskId: string): Promise<SubagentResult | undefined>;
+    /** [W7-B1] 前台任务转后台（不给 taskId = 全部）；返回被转后台或被打断等待的 taskId。 */
+    background(taskId?: string): string[];
+    /** [W7-B1] 该任务的转后台信号：`background()` 触发后 abort（下次取到新的）。 */
+    detachSignal(taskId: string): AbortSignal;
+    /** [W7-B1] 正在阻塞父回合的任务（前台运行中、或有 `task_ctl wait` 在等）。 */
+    blocking(): string[];
 }
 export declare function registerTaskControl(sessionId: string, control: TaskControl): void;
 export declare function unregisterTaskControl(sessionId: string, control: TaskControl): void;

package/dist/agents/task-record.d.ts

@@ -3,7 +3,7 @@
  * `custom{ama.task}` 快照的写入形状与 resume 重建（docs/wave5-plan.md §7.4–§7.5）。[W5-G]
  * 编排在 agent/subagent-registry.ts。
  */
-import type { SubagentUpdateEvent } from "../agent/types-w5.js";
+import type { SessionTaskStats, SubagentStartEvent, SubagentUpdateEvent } from "../agent/types-w5.js";
 import type { MessageOrigin } from "../ai/types.js";
 import type { SessionEvent } from "../agent/types.js";
 import type { TraceExternalTurnData } from "../trace/types.js";
@@ -130,6 +130,14 @@ export interface TaskRecord {
     direct?: string[];
     /** [W6-A] 下一次续聊是人在视图里发的（子会话 user 消息记 `origin: "direct"`）。 */
     directNext?: boolean;
+    /**
+     * [W7-B1] 前台等待者：launch 时建，转后台时 resolve（工具调用先返回）；结束时删掉。
+     * `detachParent` 解绑父 signal 与进度回调（父回合 Esc 不再连带停止它）。
+     */
+    foregroundWaiter?: {
+        resolve(result: SubagentResult): void;
+        detachParent(): void;
+    };
 }
 export declare function newRecord(info: TaskInfo, agent: AgentDefinition, parentToolCallId: string, cwd: string, isolation?: "none" | "worktree"): TaskRecord;
 export interface ProgressSink {
@@ -142,6 +150,10 @@ export interface ProgressSink {
 export declare function flushText(record: TaskRecord, sink: ProgressSink): void;
 /** runner 进度 → 记录与 `subagent_update`（文本 ≥ 250 ms 合并，轮次与结束时冲刷）。 */
 export declare function applyRunnerEvent(record: TaskRecord, event: SubagentEvent, sink: ProgressSink): void;
+/** `subagent_start` 事件（新开或续聊都发）。 */
+export declare function startEvent(record: TaskRecord, handle: TaskHandle): SubagentStartEvent;
+/** `getStats().tasks`：没有任务时 undefined。 */
+export declare function taskStats(records: Iterable<TaskRecord>): SessionTaskStats | undefined;
 /** 父会话 `custom{ama.task}` 的 data：TaskInfo + 父 toolCallId + 运行目录（带 `status`）。 */
 export declare function recordData(record: TaskRecord): Record<string, unknown>;
 /** 从父会话分支重建（同一 taskId 取最后一条；未结束的标 interrupted）；返回最大序号。 */

package/dist/agents/task-record.js

@@ -209,6 +209,38 @@ function recordDisplay(record, event, now) {
             return;
     }
 }
+/** `subagent_start` 事件（新开或续聊都发）。 */
+export function startEvent(record, handle) {
+    const event = {
+        type: "subagent_start",
+        taskId: record.info.taskId,
+        parentToolCallId: record.parentToolCallId,
+        agent: record.agent.name,
+        runner: record.agent.runner,
+        description: record.info.description,
+        background: record.info.background,
+        cwd: record.cwd,
+    };
+    if (handle.model !== undefined)
+        event.model = handle.model;
+    if (handle.sessionFile !== undefined)
+        event.sessionFile = handle.sessionFile;
+    return event;
+}
+/** `getStats().tasks`：没有任务时 undefined。 */
+export function taskStats(records) {
+    const byStatus = {};
+    let total = 0;
+    let running = 0;
+    for (const { info } of records) {
+        total++;
+        if (info.status === "running")
+            running++;
+        else
+            byStatus[info.status] = (byStatus[info.status] ?? 0) + 1;
+    }
+    return total === 0 ? undefined : { total, running, byStatus };
+}
 /** 父会话 `custom{ama.task}` 的 data：TaskInfo + 父 toolCallId + 运行目录（带 `status`）。 */
 export function recordData(record) {
     return { ...record.info, parentToolCallId: record.parentToolCallId, cwd: record.cwd };

package/dist/agents/types.d.ts

@@ -25,7 +25,11 @@ export interface AgentDefinition {
     /** 缺省 30。 */
     maxTurns: number;
     isolation: "none" | "worktree";
-    background: boolean;
+    /**
+     * 显式覆盖缺省前台 / 后台；不设由 `subagents.background` 决定（[W7-B1]，优先级：调用参数 > 类型
+     * 定义 > 配置）。
+     */
+    background?: boolean;
     runner: AgentRunnerSpec;
     /** 正文：追加到子会话系统提示末尾的角色说明。 */
     prompt: string;

package/dist/ai/apis/chatgpt-backend.d.ts

@@ -10,7 +10,9 @@
  * - 出错恢复（每种至多一次）：401 → 强制刷新重试；SIWC 400 `subscription_sharing_unsupported_capability` → 删去
  *   `error.param` 重试；codex 400 `Instructions are not valid` → 本会话切 developer-message 重试；
  * - 错误映射（文案带码前缀，宿主按码判断）：429 配额 → `quota_exceeded`（不重试）；失效 → `auth_expired`；
- *   SIWC 403 `subscription_sharing_user_not_eligible` → `not_eligible`；503 留给会话层现有重试；
+ *   SIWC 403 `subscription_sharing_user_not_eligible` → `not_eligible`（i18n 文案列出原因）；503 留给会话层现有重试；
+ * - 渠道跟随登录方式由会话层做（auth/chatgpt/follow.ts）；到这里仍不符说明用户显式写了 `@渠道`，报
+ *   `chatgpt_flavor_mismatch`（i18n）；
  * - 用量：`cost = 0`、`billing: "subscription"`。
  */
 import { type LiveToken } from "../../auth/oauth/live.js";
@@ -25,7 +27,10 @@ export declare function sessionKeyOf(model: Model, options: StreamOptions): stri
 export declare function resetChatGptState(): void;
 export declare function instructionsModeOf(model: Model, compat: OpenAIResponsesCompat, options: StreamOptions): "native" | "developer-message";
 export declare function transformChatGptBody(body: Json, model: Model, compat: OpenAIResponsesCompat, options: StreamOptions): Json;
-/** 发请求前：needsLogin 直接报 auth_expired；登录 flavor 与渠道不符报错。 */
+/**
+ * 发请求前：needsLogin 直接报 auth_expired；登录 flavor 与渠道不符报错（没写 `@渠道` 的模型会话层已改到登录的
+ * 渠道，走到这里的是显式指定了另一渠道）。
+ */
 export declare function chatgptPrecheck(model: Model, compat: OpenAIResponsesCompat, apiKey?: string): void;
 export declare function chatgptHeaders(compat: OpenAIResponsesCompat, options: StreamOptions, apiKey: string | undefined): Record<string, string>;
 /** 包一层 onResponse：解析响应头里的配额。 */

package/dist/ai/apis/chatgpt-backend.js

@@ -10,11 +10,14 @@
  * - 出错恢复（每种至多一次）：401 → 强制刷新重试；SIWC 400 `subscription_sharing_unsupported_capability` → 删去
  *   `error.param` 重试；codex 400 `Instructions are not valid` → 本会话切 developer-message 重试；
  * - 错误映射（文案带码前缀，宿主按码判断）：429 配额 → `quota_exceeded`（不重试）；失效 → `auth_expired`；
- *   SIWC 403 `subscription_sharing_user_not_eligible` → `not_eligible`；503 留给会话层现有重试；
+ *   SIWC 403 `subscription_sharing_user_not_eligible` → `not_eligible`（i18n 文案列出原因）；503 留给会话层现有重试；
+ * - 渠道跟随登录方式由会话层做（auth/chatgpt/follow.ts）；到这里仍不符说明用户显式写了 `@渠道`，报
+ *   `chatgpt_flavor_mismatch`（i18n）；
  * - 用量：`cost = 0`、`billing: "subscription"`。
  */
 import { liveToken } from "../../auth/oauth/live.js";
 import { authExpiredError } from "../../auth/oauth/refresh.js";
+import { msg } from "../../i18n/index.js";
 import { parseQuotaHeaders, parseRateLimitEvent, quotaFromLimitError, } from "./chatgpt-rate-limits.js";
 export const SIWC_FORBIDDEN_FIELDS = [
     "background",
@@ -81,7 +84,10 @@ export function transformChatGptBody(body, model, compat, options) {
     out["input"] = input;
     return out;
 }
-/** 发请求前：needsLogin 直接报 auth_expired；登录 flavor 与渠道不符报错。 */
+/**
+ * 发请求前：needsLogin 直接报 auth_expired；登录 flavor 与渠道不符报错（没写 `@渠道` 的模型会话层已改到登录的
+ * 渠道，走到这里的是显式指定了另一渠道）。
+ */
 export function chatgptPrecheck(model, compat, apiKey) {
     const live = liveToken(apiKey);
     if (live === undefined)
@@ -89,7 +95,9 @@ export function chatgptPrecheck(model, compat, apiKey) {
     if (live.needsLogin === true)
         throw authExpiredError(live.provider);
     if (live.flavor !== compat.chatgptBackend) {
-        throw new Error(`chatgpt_flavor_mismatch: logged in with ${live.flavor} but ${model.provider}/${model.id} uses the ${String(compat.chatgptBackend)} channel; run \`ama auth login ${live.provider} --flavor ${String(compat.chatgptBackend)}\` or switch channel`);
+        const pinned = String(compat.chatgptBackend);
+        const ref = `${model.provider}/${model.id}@${pinned}`;
+        throw new Error(`chatgpt_flavor_mismatch: ${msg().auth.request.flavorMismatch(live.flavor, ref, pinned)}`);
     }
 }
 export function chatgptHeaders(compat, options, apiKey) {
@@ -196,7 +204,7 @@ export function recoverChatGptError(error, model, compat, options, apiKey, tried
         code === "subscription_sharing_user_not_eligible")
         return {
             kind: "fail",
-            error: new Error("not_eligible: this ChatGPT account cannot share plan usage with ama (403 subscription_sharing_user_not_eligible)"),
+            error: new Error(`not_eligible: ${msg().auth.request.notEligible}`),
         };
     if (backend === "siwc" &&
         error.status === 400 &&

package/dist/ai/providers/discovered-cache.d.ts

@@ -3,10 +3,17 @@
  *
  * 模型表为空、接受任意 slug 的供应商（`chatgpt` 的订阅后端）在选择器里原本一个模型都看不到。
  * `ama auth login chatgpt` 成功后与 `ama models discover chatgpt` 把账户可用的 slug 写进这里；组装注册表时
- * （`mergeDiscoveredModels`）并入**模型表仍为空**的供应商，元数据用 models.dev（快照 ⊕ 用户刷新）补全。
- * `ama auth logout chatgpt` 删掉它。只存 slug、显示名、flavor 与时间戳——没有 token、账户 id。
+ * （`mergeDiscoveredModels`）并入**模型表仍为空**的供应商。`ama auth logout chatgpt` 删掉它。只存 slug、显示名、
+ * 后端给的元数据（上下文窗口、输入模态、推理强度）、flavor 与时间戳——没有 token、账户 id。
+ *
+ * 元数据优先级：后端明确给的 > models.dev（快照 ⊕ 用户刷新）> 自定义缺省。上下文窗口尤其如此：订阅后端的生效
+ * 窗口（如 codex 的 272k）可能远小于 models.dev 记的 API 版窗口（1.1M），按后者算压缩阈值会让请求超窗被拒。
+ * 旧版本写的缓存（siwc 不含上下文窗口）照旧用 models.dev；`chatgpt` 两边都没有时用保守缺省
+ * `SUBSCRIPTION_FALLBACK_CONTEXT_WINDOW`，不让自动压缩关闭。
+ *
+ * ChatGPT 的缓存带登录 flavor；组装时与当前登录的 flavor 不符视为过期、不并入（选择器提示重新发现）。
  */
-import type { Model, ProviderData } from "../types.js";
+import type { Model, ModelThinkingLevel, ProviderData } from "../types.js";
 import type { ModelsDevIndex } from "./models-dev.js";
 export declare const DISCOVERED_CACHE_VERSION = 1;
 export interface DiscoveredCacheFile {
@@ -16,10 +23,15 @@ export interface DiscoveredCacheFile {
     fetchedAt: string;
     /** ChatGPT 登录的 flavor（siwc / codex）；其它供应商不写。 */
     flavor?: string;
-    models: {
-        id: string;
-        name?: string;
-    }[];
+    models: DiscoveredCacheModel[];
+}
+/** 缓存里的一个模型：slug、显示名与后端给的元数据（都可缺）。 */
+export interface DiscoveredCacheModel {
+    id: string;
+    name?: string;
+    contextWindow?: number;
+    input?: ("text" | "image")[];
+    reasoningLevels?: string[];
 }
 /** 缓存文件位置。 */
 export declare function discoveredCachePath(dataDir: string, provider: string): string;
@@ -27,15 +39,18 @@ export declare function discoveredCachePath(dataDir: string, provider: string):
 export declare function readDiscoveredCache(dataDir: string, provider: string): DiscoveredCacheFile | undefined;
 /** 写缓存（先写临时文件再改名）；返回路径。 */
 export declare function writeDiscoveredCache(dataDir: string, provider: string, input: {
-    models: readonly {
-        id: string;
+    models: readonly (Omit<DiscoveredCacheModel, "name"> & {
         name?: string | undefined;
-    }[];
+    })[];
     flavor?: string | undefined;
 }, now?: number): string;
 /** 删缓存；删了返回 true。 */
 export declare function clearDiscoveredCache(dataDir: string, provider: string): boolean;
-/** 缓存里的模型 → 注册表模型（models.dev 补元数据，补不到用自定义缺省）。 */
+/** 后端给的推理强度 → 思考级别映射（`none` 对应 off；没列出的级别不支持）。 */
+export declare function thinkingMapOf(levels: readonly string[]): Partial<Record<ModelThinkingLevel, string | null>>;
+/** 订阅后端：models.dev 与后端都没给上下文窗口时的保守缺省。 */
+export declare const SUBSCRIPTION_FALLBACK_CONTEXT_WINDOW = 128000;
+/** 缓存里的模型 → 注册表模型（后端给的元数据优先，其次 models.dev，再次自定义缺省）。 */
 export declare function discoveredModels(file: DiscoveredCacheFile, provider: ProviderData, modelsDev: () => ModelsDevIndex | undefined): Model[];
 /** 注册表里能追加模型的最小接口（`ProviderRegistry.addModels`）。 */
 export interface DiscoveredTarget {
@@ -45,4 +60,6 @@ export interface DiscoveredTarget {
 /**
  * 把缓存并入模型表为空的供应商（本地服务除外：它们每次启动现场探测）。返回并入了的供应商 id。
  */
-export declare function mergeDiscoveredModels(registry: DiscoveredTarget, dataDir: string, modelsDev: () => ModelsDevIndex | undefined): string[];
+export declare function mergeDiscoveredModels(registry: DiscoveredTarget, dataDir: string, modelsDev: () => ModelsDevIndex | undefined, 
+/** 当前登录的 flavor（只有 OAuth 供应商有）：缓存的 flavor 与之不符视为过期，不并入。 */
+loginFlavor?: (providerId: string) => string | undefined): string[];