@armadra/agent 0.6.2 → 0.6.4

package/dist/agent/queue.d.ts

@@ -4,6 +4,7 @@
  * `one-at-a-time`：每个投递点只取一条；`all`：一次取空。abort 不清队列。
  */
 import type { QueueMode } from "./types.js";
+import type { ImageBlock } from "../ai/types.js";
 import type { AgentMessage } from "../session/types.js";
 export declare class PendingMessageQueue {
     private items;
@@ -23,3 +24,11 @@ export declare class PendingMessageQueue {
 }
 /** 队列消息的显示文本（queue_update 事件用）。 */
 export declare function queuedText(message: AgentMessage): string;
+/**
+ * 打断并立即发送的新回合输入：排队的 steer（按入队顺序）在前、本条在后，文字以空行拼接，图片依次保留。
+ * 全部为空时 undefined（不打断）。
+ */
+export declare function mergeForInterrupt(queued: readonly AgentMessage[], text: string, images?: readonly ImageBlock[]): {
+    text: string;
+    images: ImageBlock[];
+} | undefined;

package/dist/agent/queue.js

@@ -53,3 +53,30 @@ export function queuedText(message) {
         return content;
     return content.map((block) => (block.type === "text" ? block.text : "[image]")).join("");
 }
+/**
+ * 打断并立即发送的新回合输入：排队的 steer（按入队顺序）在前、本条在后，文字以空行拼接，图片依次保留。
+ * 全部为空时 undefined（不打断）。
+ */
+export function mergeForInterrupt(queued, text, images = []) {
+    const texts = [];
+    const merged = [];
+    for (const message of queued) {
+        if (message.role !== "user")
+            continue;
+        const { content } = message;
+        if (typeof content === "string")
+            texts.push(content);
+        else {
+            texts.push(content.map((block) => (block.type === "text" ? block.text : "")).join(""));
+            for (const block of content)
+                if (block.type === "image")
+                    merged.push(block);
+        }
+    }
+    texts.push(text);
+    merged.push(...images);
+    const parts = texts.filter((part) => part.trim() !== "");
+    if (parts.length === 0 && merged.length === 0)
+        return undefined;
+    return { text: parts.join("\n\n"), images: merged };
+}

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

@@ -54,6 +54,7 @@ export interface ChildSession {
     readonly messages: readonly AgentMessage[];
     prompt(text: string, options?: {
         origin?: MessageOrigin;
+        interrupt?: boolean;
     }): Promise<unknown>;
     /** [W6-A] 视图里直接发的消息（运行中排到回合结束）。 */
     followUp?(text: string, options?: {

package/dist/agent/session-subagent.js

@@ -186,6 +186,8 @@ async function startAmaChild(parent, spec, createChild, run) {
     run.signal.addEventListener("abort", onAbort, { once: true });
     let billed = { cacheRead: 0, prompt: 0, reBilled: 0 };
     let active = false;
+    /** 视图里「打断并发送」开的回合（runOnce 等它们跑完再收尾）。 */
+    const forced = [];
     const runOnce = async (prompt, origin) => {
         const startTurns = turns;
         let error;
@@ -196,6 +198,8 @@ async function startAmaChild(parent, spec, createChild, run) {
             await child.prompt(prompt, origin === undefined ? {} : { origin });
             // [W6-A] 收尾阶段才入队的 followUp（只可能来自视图）留在队列里：接着再跑一轮
             for (;;) {
+                while (forced.length > 0)
+                    await forced.shift();
                 const left = child.clearQueue?.().followUp ?? [];
                 if (left.length === 0 || run.signal.aborted)
                     break;
@@ -245,6 +249,11 @@ async function startAmaChild(parent, spec, createChild, run) {
             }
             if (!active || child.followUp === undefined)
                 throw new AmaError("task_idle", "the sub-agent is not running");
+            if (when === "interrupt") {
+                // 同步登记：被中止的那一轮一结束，runOnce 就接着等这一轮
+                forced.push(child.prompt(text, { origin: "direct", interrupt: true }));
+                return;
+            }
             await child.followUp(text, { origin: "direct" });
         },
         wait: () => current,

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";
@@ -76,8 +77,18 @@ export declare class AgentSessionImpl implements AgentSession, SessionCore {
     private enqueueOrRun;
     steer(text: string, options?: EnqueueOptions): Promise<"queued" | "handled">;
     followUp(text: string, options?: EnqueueOptions): Promise<"queued" | "handled">;
+    /**
+     * 打断并立即发送：取走排队的 steer、中止当前周期（工具按 abort 收尾），以「steer… + 本条」开新回合；
+     * followUp 留在队列。没有可发的内容 → invalid_arguments（不打断）。
+     */
+    private interruptWith;
     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

@@ -13,13 +13,14 @@ import { AmaError } from "../errors.js";
 import { createSessionClassifier } from "./session-classifier.js";
 import { buildProjection } from "../session/projection.js";
 import { Agent } from "./agent.js";
-import { queuedText } from "./queue.js";
+import { mergeForInterrupt, queuedText } from "./queue.js";
 import { resolveRetrySettings } from "./retry.js";
 import { SessionCacheController, resolveCacheSettings } from "./session-cache.js";
 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";
@@ -277,6 +278,8 @@ export class AgentSessionImpl {
     // -------------------------------------------------------------------------
     async prompt(text, options = {}) {
         this.assertUsable();
+        if (options.interrupt === true && this.cycle !== undefined)
+            return this.interruptWith(text, options.images, options.origin);
         if (this.cycle !== undefined) {
             const behavior = options.streamingBehavior;
             if (behavior === undefined) {
@@ -298,7 +301,9 @@ export class AgentSessionImpl {
     }
     async enqueueOrRun(text, queue, options) {
         this.assertUsable();
-        const origin = normalizeOrigin(options.origin ?? queue);
+        if (options.interrupt === true && this.cycle !== undefined)
+            return this.interruptWith(text, undefined, options.origin).then(() => "handled");
+        const origin = normalizeOrigin(options.origin ?? (options.interrupt === true ? "user" : queue));
         if (this.cycle === undefined) {
             await this.startCycle((signal) => runPrompt(this.runDeps(), text, undefined, origin, signal));
             return "handled";
@@ -312,6 +317,21 @@ export class AgentSessionImpl {
     followUp(text, options = {}) {
         return this.enqueueOrRun(text, "followUp", options);
     }
+    /**
+     * 打断并立即发送：取走排队的 steer、中止当前周期（工具按 abort 收尾），以「steer… + 本条」开新回合；
+     * followUp 留在队列。没有可发的内容 → invalid_arguments（不打断）。
+     */
+    async interruptWith(text, images, origin) {
+        const merged = mergeForInterrupt(this.agent.steeringQueue.snapshot(), text, images);
+        if (merged === undefined)
+            throw new AmaError("invalid_arguments", "nothing to send");
+        this.agent.steeringQueue.clear();
+        this.emitQueue();
+        while (this.cycle !== undefined)
+            await this.abort();
+        const kind = normalizeOrigin(origin ?? "interrupt");
+        return this.startCycle((s) => runPrompt(this.runDeps(), merged.text, merged.images, kind, s));
+    }
     async abort() {
         const cycle = this.cycle;
         if (cycle === undefined)
@@ -323,6 +343,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-direct.d.ts

@@ -7,14 +7,17 @@
  *   外部 Agent 运行中 / 还在排队 → 等本次运行结束后续聊（`queued`）；已结束 → 同 `task_ctl send` 的后台续聊
  *   （`resumed`，完成后父会话照常收 `<task-notification>`）。子会话 user 消息记 `origin: "direct"`；
  * - `drainDirect`：运行结束时把排着的消息合成一条续聊；任务被停止时丢弃（停止的一方不想它再跑）。
+ * - 打断并发送（`interrupt`）：ama 运行中 → 子会话 `prompt{interrupt}`（中止本轮、立即开新回合，`interrupted`）；
+ *   外部 Agent 运行中且驱动能中断回合 → 连同排着的消息一起 `handle.interrupt`（`interrupted`）；驱动不能中断
+ *   或任务还在并发池排队 → 照常排到运行结束（`queuedNoInterrupt`，视图提示）；已结束 → 同上的后台续聊。
  */
 import type { TaskLive, TaskRecord } from "../agents/task-record.js";
 import type { SubagentRequest, SubagentResult } from "../tools/types.js";
-export type DirectReply = "steered" | "queued" | "resumed";
+export type DirectReply = "steered" | "queued" | "resumed" | "interrupted" | "queuedNoInterrupt";
 export interface DirectHost {
     spawnSubagent?(request: SubagentRequest): Promise<SubagentResult>;
     log(level: "debug" | "info" | "warn" | "error", message: string): void;
 }
 export declare function liveOf(record: TaskRecord): TaskLive;
-export declare function directMessage(record: TaskRecord, text: string, host: DirectHost): Promise<DirectReply>;
+export declare function directMessage(record: TaskRecord, text: string, host: DirectHost, interrupt?: boolean): Promise<DirectReply>;
 export declare function drainDirect(record: TaskRecord, host: DirectHost): void;

package/dist/agent/subagent-direct.js

@@ -7,6 +7,9 @@
  *   外部 Agent 运行中 / 还在排队 → 等本次运行结束后续聊（`queued`）；已结束 → 同 `task_ctl send` 的后台续聊
  *   （`resumed`，完成后父会话照常收 `<task-notification>`）。子会话 user 消息记 `origin: "direct"`；
  * - `drainDirect`：运行结束时把排着的消息合成一条续聊；任务被停止时丢弃（停止的一方不想它再跑）。
+ * - 打断并发送（`interrupt`）：ama 运行中 → 子会话 `prompt{interrupt}`（中止本轮、立即开新回合，`interrupted`）；
+ *   外部 Agent 运行中且驱动能中断回合 → 连同排着的消息一起 `handle.interrupt`（`interrupted`）；驱动不能中断
+ *   或任务还在并发池排队 → 照常排到运行结束（`queuedNoInterrupt`，视图提示）；已结束 → 同上的后台续聊。
  */
 import { AmaError } from "../errors.js";
 export function liveOf(record) {
@@ -25,11 +28,17 @@ export function liveOf(record) {
         live.entries = () => entries.call(handle);
     return live;
 }
-export async function directMessage(record, text, host) {
+export async function directMessage(record, text, host, interrupt = false) {
     if (text.trim() === "")
         throw new AmaError("invalid_arguments", "empty message");
     if (record.running !== undefined) {
         const handle = record.handle;
+        if (interrupt && record.queued !== true && (await interruptRun(record, text)))
+            return "interrupted";
+        if (interrupt) {
+            (record.direct ??= []).push(text);
+            return "queuedNoInterrupt";
+        }
         if (handle?.message !== undefined && record.queued !== true) {
             try {
                 await handle.message(text, "followUp");
@@ -47,6 +56,30 @@ export async function directMessage(record, text, host) {
     await resumeDirect(record, text, host);
     return "resumed";
 }
+/** 打断运行中的任务并立即发送；做不到返回 false（不改动排队）。 */
+async function interruptRun(record, text) {
+    const handle = record.handle;
+    if (handle?.message !== undefined) {
+        try {
+            await handle.message(text, "interrupt");
+            return true;
+        }
+        catch (error) {
+            if (error instanceof AmaError && error.code === "task_idle")
+                return false;
+            throw error;
+        }
+    }
+    if (handle?.interrupt === undefined)
+        return false;
+    // 外部 Agent：排着的消息（运行中在视图里发的）在前，一起作为新回合
+    const queued = record.direct ?? [];
+    const merged = [...queued, text].join("\n\n");
+    if (!(await handle.interrupt(merged)))
+        return false;
+    queued.splice(0);
+    return true;
+}
 async function resumeDirect(record, text, host) {
     const spawn = host.spawnSubagent;
     if (spawn === undefined)

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,13 @@ 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 DirectReply } from "./subagent-direct.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 +39,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 +69,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,23 +78,34 @@ 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）。 */
-    message(taskId: string, text: string): Promise<"steered" | "queued" | "resumed">;
+    message(taskId: string, text: string, interrupt?: boolean): Promise<DirectReply>;
     stop(taskId: string): Promise<SubagentResult | undefined>;
     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;