@armadra/agent 0.6.1 → 0.6.3

package/dist/agent/session-settings.d.ts

@@ -11,7 +11,10 @@ import type { ToolDefinition } from "../tools/types.js";
 import type { StreamFn } from "./loop.js";
 import type { AgentSessionOptions, SessionCore } from "./session-core.js";
 import type { SystemPromptInput } from "./system-prompt.js";
-/** 按模型的协议分派到已注册的实现（会话流的最内层）。 */
+/**
+ * 按模型的协议分派到已注册的实现（会话流的最内层）。ChatGPT 订阅模型先按本次 token 的登录方式改渠道
+ * （没写 `@渠道` 时；auth/chatgpt/follow.ts），会话中途换登录方式不用重启。
+ */
 export declare function providerStream(providers: ProviderRegistryApi): StreamFn;
 export type StaticSystemInput = Omit<SystemPromptInput, "tools" | "cwd">;
 export interface SessionSettingsDeps {

package/dist/agent/session-settings.js

@@ -5,11 +5,16 @@
  * 纯搬迁：`setModel / setThinkingLevel / setPermissionMode / setActiveTools / addTool /
  * updateSystem / announceStart / getTools` 的行为与事件顺序不变；`AgentSessionImpl` 以同名成员转发。
  */
+import { followChatGptLogin } from "../auth/chatgpt/follow.js";
 import { AmaError } from "../errors.js";
 import { appendModelChange, findModelOrThrow, sessionStartEvent } from "./session-sync.js";
-/** 按模型的协议分派到已注册的实现（会话流的最内层）。 */
+/**
+ * 按模型的协议分派到已注册的实现（会话流的最内层）。ChatGPT 订阅模型先按本次 token 的登录方式改渠道
+ * （没写 `@渠道` 时；auth/chatgpt/follow.ts），会话中途换登录方式不用重启。
+ */
 export function providerStream(providers) {
-    return (model, context, streamOptions) => {
+    return (requested, context, streamOptions) => {
+        const model = followChatGptLogin(requested, providers.get(requested.provider), streamOptions.apiKey);
         const api = providers.getApi(model.api);
         if (api === undefined) {
             throw new AmaError("provider_not_found", `no implementation registered for api ${model.api}`);

package/dist/agent/session.d.ts

@@ -19,6 +19,7 @@ import { Agent } from "./agent.js";
 import type { StreamFn } from "./loop.js";
 import type { AgentSessionOptions, SessionCore } from "./session-core.js";
 import { SessionCacheController } from "./session-cache.js";
+import { type BackgroundReason } from "./subagent-registry.js";
 import { type StaticSystemInput } from "./session-settings.js";
 import { type RewindDraft, type SummarizeFromResult } from "./session-rewind.js";
 import type * as CP from "../checkpoints/types.js";
@@ -78,6 +79,11 @@ export declare class AgentSessionImpl implements AgentSession, SessionCore {
     followUp(text: string, options?: EnqueueOptions): Promise<"queued" | "handled">;
     abort(): Promise<void>;
     waitForIdle(): Promise<void>;
+    /**
+     * [W7-B1] 把阻塞中的前台子 Agent 任务转后台（不给 taskId = 全部）：工具调用立即返回，任务继续，完成后
+     * 照常 `<task-notification>`。返回被转后台（或被打断等待）的 taskId。
+     */
+    backgroundTask(taskId?: string, reason?: BackgroundReason): string[];
     clearQueue(): {
         steering: string[];
         followUp: string[];

package/dist/agent/session.js

@@ -20,6 +20,7 @@ import { CompactionController } from "./session-compaction.js";
 import { makeUserMessage, normalizeOrigin, runPrompt } from "./session-run.js";
 import { buildSessionState, computeStats, lastAssistantText } from "./session-state.js";
 import { DEFAULT_SUBAGENT_CONCURRENCY, SubagentPool, runSubagent } from "./session-subagent.js";
+import { registryOf } from "./subagent-registry.js";
 import { persistMessage, runHookWithEvents, syncSystemMessage } from "./session-sync.js";
 import { SessionExtensions } from "./session-extensions.js";
 import { SessionSettings, providerStream } from "./session-settings.js";
@@ -323,6 +324,13 @@ export class AgentSessionImpl {
     waitForIdle() {
         return this.cycle?.promise ?? Promise.resolve();
     }
+    /**
+     * [W7-B1] 把阻塞中的前台子 Agent 任务转后台（不给 taskId = 全部）：工具调用立即返回，任务继续，完成后
+     * 照常 `<task-notification>`。返回被转后台（或被打断等待）的 taskId。
+     */
+    backgroundTask(taskId, reason = "host") {
+        return registryOf(this.manager.id)?.background(taskId, reason) ?? [];
+    }
     clearQueue() {
         const cleared = {
             steering: this.agent.steeringQueue.clear().map(queuedText),

package/dist/agent/subagent-background.d.ts

@@ -0,0 +1,75 @@
+/**
+ * 子 Agent 的后台化（docs/agents-concurrency-plan.md §2.3、§2.5–§2.6）。[W7-B1]
+ *
+ * 从 subagent-registry.ts 拆出（保持 ≤ 600 行）：
+ * - `resolveTaskBackground`：`subagents.background`（auto / always / never）→ 本会话 `task` 的缺省；
+ * - 工具结果：`startedResult`（直接后台）、`backgroundedResult`（前台转后台；固定英文文案在
+ *   agents/result.ts）；
+ * - `foregroundWaiter`：前台任务的等待者——转后台时以固定文案先行 resolve 工具调用，并解绑父 signal；
+ * - `WaitDetach`：`task_ctl wait` 的打断信号（`background()` 触发，按 taskId 或全部）；
+ * - `TaskNotifier`：完成通知的串行投递——父会话空闲后以 followUp（origin task）开一轮；用户的 steer /
+ *   followUp 总在通知之前（通知只在空闲时入场），收尾阶段入队的由 W5-H2 的同周期续投接住；每个通知
+ *   各开一轮，不合并。
+ */
+import type { TaskRecord } from "../agents/task-record.js";
+import type { SubagentResult } from "../tools/types.js";
+import type { SubagentBackgroundEvent } from "./types-w5.js";
+export type BackgroundReason = "user" | "timeout" | "host";
+export type BackgroundSetting = "auto" | "always" | "never";
+/** `auto`：交互 / RPC / ACP 缺省后台，`-p`（无人值守）缺省前台。 */
+export declare function resolveTaskBackground(setting: BackgroundSetting | undefined, unattended: boolean): boolean;
+export declare function startedResult(record: TaskRecord, outputFile?: string): SubagentResult;
+export declare function backgroundedResult(record: TaskRecord, reason: BackgroundReason, afterMs: number, outputFile?: string): SubagentResult;
+/** 前台任务的等待者：`resolve` 让工具调用先返回，`detachParent` 解绑父 signal 与进度回调。 */
+export declare function foregroundWaiter(detachParent: () => void): {
+    waiter: NonNullable<TaskRecord["foregroundWaiter"]>;
+    promise: Promise<SubagentResult>;
+};
+/** `task_ctl wait` 的打断信号：每个 taskId 一个，`detach` 后换新。 */
+export declare class WaitDetach {
+    private readonly controllers;
+    private readonly waiting;
+    signal(taskId: string): AbortSignal;
+    /** 登记一次正在进行的 wait；返回注销函数。 */
+    enter(taskId: string): () => void;
+    /** 有 wait 在等的 taskId。 */
+    waited(): string[];
+    /** 打断 `taskId`（缺省全部）上的 wait；返回被打断的 taskId。 */
+    detach(taskId?: string): string[];
+}
+export interface NotifierHost {
+    followUp?(text: string, options?: {
+        origin?: string;
+    }): Promise<unknown>;
+    waitForIdle?(): Promise<void>;
+    log(level: "debug" | "info" | "warn" | "error", message: string): void;
+}
+/** 完成通知的串行投递（按完成顺序；父空闲时投递，每个通知各开一轮）。 */
+export declare class TaskNotifier {
+    private readonly host;
+    private readonly disposed;
+    private delivery;
+    constructor(host: NotifierHost, disposed: () => boolean);
+    /** 当前投递链（含已入链通知的整个回合）。 */
+    pending(): Promise<void>;
+    notify(record: TaskRecord, result: SubagentResult): void;
+}
+/** 等任务结束、超时或 signal 触发（后两者返回 undefined）；登记进 `waits` 供 `blocking()` 查看。 */
+export declare function waitForTask(record: TaskRecord, timeoutMs: number, signal: AbortSignal, waits: WaitDetach): Promise<SubagentResult | undefined>;
+/** 运行中的前台任务与有 `task_ctl wait` 在等的任务。 */
+export declare function blockingTasks(records: Iterable<TaskRecord>, waits: WaitDetach): string[];
+export interface BackgroundContext {
+    emit(event: SubagentBackgroundEvent): void;
+    persist(record: TaskRecord): void;
+    notify(record: TaskRecord, result: SubagentResult): void;
+    /** 超时转后台的阈值（文案里的秒数）。 */
+    afterMs: number;
+    outputFile(taskId: string): string | undefined;
+}
+/**
+ * 前台 → 后台（§2.5.2）：只动运行中、仍在前台的任务；置后台、落快照、解绑父 signal、发事件、完成后通知、
+ * 让工具调用以固定文案返回。以 `info.status` 为准——已收尾的任务不动（与结束竞争时先到者为准）。
+ */
+export declare function backgroundRecords(records: readonly TaskRecord[], reason: BackgroundReason, ctx: BackgroundContext): string[];
+/** 等到没有运行中的任务、投递链也已结束（通知回合里新起的任务继续等）；会话关闭立即返回。 */
+export declare function settleTasks(tasks: ReadonlyMap<string, TaskRecord>, notifier: TaskNotifier, disposed: () => boolean): Promise<void>;

package/dist/agent/subagent-background.js

@@ -0,0 +1,209 @@
+/**
+ * 子 Agent 的后台化（docs/agents-concurrency-plan.md §2.3、§2.5–§2.6）。[W7-B1]
+ *
+ * 从 subagent-registry.ts 拆出（保持 ≤ 600 行）：
+ * - `resolveTaskBackground`：`subagents.background`（auto / always / never）→ 本会话 `task` 的缺省；
+ * - 工具结果：`startedResult`（直接后台）、`backgroundedResult`（前台转后台；固定英文文案在
+ *   agents/result.ts）；
+ * - `foregroundWaiter`：前台任务的等待者——转后台时以固定文案先行 resolve 工具调用，并解绑父 signal；
+ * - `WaitDetach`：`task_ctl wait` 的打断信号（`background()` 触发，按 taskId 或全部）；
+ * - `TaskNotifier`：完成通知的串行投递——父会话空闲后以 followUp（origin task）开一轮；用户的 steer /
+ *   followUp 总在通知之前（通知只在空闲时入场），收尾阶段入队的由 W5-H2 的同周期续投接住；每个通知
+ *   各开一轮，不合并。
+ */
+import { backgroundedText, startedText, taskNotification } from "../agents/result.js";
+import { ZERO_USAGE } from "./loop.js";
+/** `auto`：交互 / RPC / ACP 缺省后台，`-p`（无人值守）缺省前台。 */
+export function resolveTaskBackground(setting, unattended) {
+    if (setting === "always")
+        return true;
+    if (setting === "never")
+        return false;
+    return !unattended;
+}
+function runningResult(record, text, outputFile) {
+    const result = {
+        text,
+        usage: { ...ZERO_USAGE },
+        stopReason: "stop",
+        isError: false,
+        taskId: record.info.taskId,
+        status: "running",
+    };
+    if (outputFile !== undefined)
+        result.outputFile = outputFile;
+    return result;
+}
+export function startedResult(record, outputFile) {
+    return runningResult(record, startedText(record.info.taskId, record.agent.name), outputFile);
+}
+export function backgroundedResult(record, reason, afterMs, outputFile) {
+    return runningResult(record, backgroundedText(reason, afterMs), outputFile);
+}
+/** 前台任务的等待者：`resolve` 让工具调用先返回，`detachParent` 解绑父 signal 与进度回调。 */
+export function foregroundWaiter(detachParent) {
+    let resolve;
+    const promise = new Promise((r) => {
+        resolve = r;
+    });
+    return { waiter: { resolve, detachParent }, promise };
+}
+/** `task_ctl wait` 的打断信号：每个 taskId 一个，`detach` 后换新。 */
+export class WaitDetach {
+    controllers = new Map();
+    waiting = new Map();
+    signal(taskId) {
+        let controller = this.controllers.get(taskId);
+        if (controller === undefined) {
+            controller = new AbortController();
+            this.controllers.set(taskId, controller);
+        }
+        return controller.signal;
+    }
+    /** 登记一次正在进行的 wait；返回注销函数。 */
+    enter(taskId) {
+        this.waiting.set(taskId, (this.waiting.get(taskId) ?? 0) + 1);
+        return () => {
+            const left = (this.waiting.get(taskId) ?? 1) - 1;
+            if (left <= 0)
+                this.waiting.delete(taskId);
+            else
+                this.waiting.set(taskId, left);
+        };
+    }
+    /** 有 wait 在等的 taskId。 */
+    waited() {
+        return [...this.waiting.keys()];
+    }
+    /** 打断 `taskId`（缺省全部）上的 wait；返回被打断的 taskId。 */
+    detach(taskId) {
+        const ids = taskId === undefined ? this.waited() : this.waiting.has(taskId) ? [taskId] : [];
+        for (const id of taskId === undefined ? [...this.controllers.keys()] : [taskId]) {
+            this.controllers.get(id)?.abort();
+            this.controllers.delete(id);
+        }
+        return ids;
+    }
+}
+/** 完成通知的串行投递（按完成顺序；父空闲时投递，每个通知各开一轮）。 */
+export class TaskNotifier {
+    host;
+    disposed;
+    delivery = Promise.resolve();
+    constructor(host, disposed) {
+        this.host = host;
+        this.disposed = disposed;
+    }
+    /** 当前投递链（含已入链通知的整个回合）。 */
+    pending() {
+        return this.delivery;
+    }
+    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 由同周期续投
+        // 接住（W5-H2）。串行投递保证按完成顺序到达、各开一轮。
+        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)}`));
+    }
+}
+/** 等任务结束、超时或 signal 触发（后两者返回 undefined）；登记进 `waits` 供 `blocking()` 查看。 */
+export async function waitForTask(record, timeoutMs, signal, waits) {
+    const running = record.running;
+    if (running === undefined)
+        return record.last;
+    if (signal.aborted)
+        return undefined;
+    const leave = waits.enter(record.info.taskId);
+    let timer;
+    let onAbort;
+    const stop = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(undefined), timeoutMs);
+        onAbort = () => resolve(undefined);
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+    try {
+        return await Promise.race([running, stop]);
+    }
+    finally {
+        clearTimeout(timer);
+        if (onAbort !== undefined)
+            signal.removeEventListener("abort", onAbort);
+        leave();
+    }
+}
+/** 运行中的前台任务与有 `task_ctl wait` 在等的任务。 */
+export function blockingTasks(records, waits) {
+    const ids = [];
+    for (const r of records)
+        if (r.foregroundWaiter !== undefined && r.running !== undefined)
+            ids.push(r.info.taskId);
+    return [...new Set([...ids, ...waits.waited()])];
+}
+/**
+ * 前台 → 后台（§2.5.2）：只动运行中、仍在前台的任务；置后台、落快照、解绑父 signal、发事件、完成后通知、
+ * 让工具调用以固定文案返回。以 `info.status` 为准——已收尾的任务不动（与结束竞争时先到者为准）。
+ */
+export function backgroundRecords(records, reason, ctx) {
+    const moved = [];
+    for (const record of records) {
+        const waiter = record.foregroundWaiter;
+        const running = record.running;
+        if (waiter === undefined || running === undefined || record.info.status !== "running")
+            continue;
+        delete record.foregroundWaiter;
+        record.info.background = true;
+        waiter.detachParent();
+        ctx.persist(record);
+        const taskId = record.info.taskId;
+        ctx.emit({
+            type: "subagent_background",
+            taskId,
+            parentToolCallId: record.parentToolCallId,
+            reason,
+        });
+        void running.then((result) => ctx.notify(record, result));
+        waiter.resolve(backgroundedResult(record, reason, ctx.afterMs, ctx.outputFile(taskId)));
+        moved.push(taskId);
+    }
+    return moved;
+}
+/** 等到没有运行中的任务、投递链也已结束（通知回合里新起的任务继续等）；会话关闭立即返回。 */
+export async function settleTasks(tasks, notifier, disposed) {
+    const running = () => [...tasks.values()].flatMap((r) => (r.running === undefined ? [] : [r.running]));
+    for (;;) {
+        if (disposed())
+            return;
+        const now = running();
+        if (now.length > 0) {
+            await Promise.allSettled(now);
+            continue;
+        }
+        const delivery = notifier.pending();
+        await delivery;
+        if (delivery === notifier.pending() && running().length === 0)
+            return;
+    }
+}

package/dist/agent/subagent-registry.d.ts

@@ -13,6 +13,7 @@
  * - 事件 `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 type { SubagentRequest, SubagentResult, SubagentRunner, TaskInfo, TaskRegistryView } from "../tools/types.js";
 import { AgentCatalog, type AgentModelConfig } from "../agents/catalog.js";
@@ -21,10 +22,12 @@ import { type TaskControl } from "../agents/task-control.js";
 import type { AgentDefinition, AgentInfo } from "../agents/types.js";
 import type { SessionCore } from "./session-core.js";
 import type { SessionTaskStats } from "./types.js";
+import { type BackgroundReason } from "./subagent-background.js";
 export declare const DEFAULT_SUBAGENT_CONCURRENCY = 4;
 export declare const DEFAULT_MAX_PENDING = 16;
 export declare const DEFAULT_RETAINED = 16;
 export { SubagentPool, TASK_CUSTOM_TYPE, type AmaRunnerSpec, type TaskHandle };
+export type { BackgroundReason };
 export type AmaRunnerFactory = (spec: AmaRunnerSpec) => SubagentRunner;
 export interface SubagentEnvironment {
     catalog: AgentCatalog;
@@ -35,6 +38,10 @@ export interface SubagentEnvironment {
     /** 外部 / 宿主 runner（W5-E `ProcessRunner`、HostApi.runners）；没有返回 undefined。 */
     runners?(agent: AgentDefinition): SubagentRunner | undefined;
     now?(): number;
+    /** [W7-B1] `task` 未指定 background 且类型也没指定时的缺省（`subagents.background` 解析后）；缺省前台。 */
+    background?: boolean;
+    /** [W7-B1] 前台任务运行超过该毫秒数自动转后台（`subagents.autoBackgroundAfterMs`）；0 / 不设关闭。 */
+    autoBackgroundAfterMs?: number;
 }
 /** 注册表需要的父会话能力（`SessionCore`；followUp 为 AgentSessionImpl 的公开方法）。 */
 export type RegistryHost = Pick<SessionCore, "manager" | "cwd" | "emit" | "appendEntry" | "outputDir" | "log" | "options"> & {
@@ -61,7 +68,8 @@ export declare class SubagentRegistry implements TaskControl {
     private readonly retained;
     private seq;
     private disposed;
-    private delivery;
+    private readonly notifier;
+    private readonly waits;
     constructor(host: RegistryHost, env: SubagentEnvironment);
     private now;
     list(): readonly TaskInfo[];
@@ -69,8 +77,21 @@ export declare class SubagentRegistry implements TaskControl {
     stats(): SessionTaskStats | undefined;
     /** 运行中任务的已有输出（`task_ctl output`）；结束后为最终文本。 */
     output(taskId: string): string | undefined;
-    /** 等任务结束或超时；超时返回 undefined。 */
-    wait(taskId: string, timeoutMs: number): Promise<SubagentResult | undefined>;
+    /** 等结束；超时或 signal（缺省本任务的转后台信号，`background()` 触发）返回 undefined。[W7-B1] */
+    wait(taskId: string, timeoutMs: number, options?: {
+        signal?: AbortSignal;
+    }): Promise<SubagentResult | undefined>;
+    /** [W7-B1] `task_ctl wait` 用的打断信号（`background()` 触发后换新）。 */
+    detachSignal(taskId: string): AbortSignal;
+    /** [W7-B1] 正在阻塞父回合的任务：运行中的前台任务与有 `task_ctl wait` 在等的任务。 */
+    blocking(): string[];
+    /**
+     * [W7-B1] 前台任务转后台（§2.5，subagent-background.ts），并打断等它的 `task_ctl wait`；不给 taskId =
+     * 全部。返回被转后台或被打断等待的 taskId（不在运行时为空）。
+     */
+    background(taskId?: string, reason?: BackgroundReason): string[];
+    /** [W7-B1] `-p` 收尾：等到没有运行中的任务、通知回合也已跑完；会话关闭立即返回。 */
+    settled(): Promise<void>;
     /** [W6-A] 子 Agent 视图读的实时数据；未知任务 undefined。 */
     live(taskId: string): TaskLive | undefined;
     /** [W6-A] 人在子 Agent 视图里发的消息（subagent-direct.ts）。 */
@@ -79,13 +100,11 @@ export declare class SubagentRegistry implements TaskControl {
     run(request: SubagentRequest, ama: AmaRunnerFactory): Promise<SubagentResult>;
     private continueTask;
     private launch;
-    private startedResult;
     private execute;
     private handleFor;
     private emitStart;
     private sink;
     private finish;
-    private notify;
     private outputDirectory;
     private outputName;
     private outputFileFor;