@armadra/agent 0.5.0 → 0.6.0

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

@@ -0,0 +1,20 @@
+/**
+ * 子 Agent 视图的直接对话与实时数据（docs/wave6-plan.md §1.2–§1.3、D3）。[W6-A]
+ *
+ * 从 subagent-registry.ts 拆出（保持 ≤ 600 行）：
+ * - `liveOf`：视图读的快照、是否在并发池排队、ama 子会话的观察钩子与外部 Agent 的环形缓冲；
+ * - `directMessage`：人在视图里发的消息——ama 运行中 → 子会话 followUp（回合结束投递，返回 `steered`）；
+ *   外部 Agent 运行中 / 还在排队 → 等本次运行结束后续聊（`queued`）；已结束 → 同 `task_ctl send` 的后台续聊
+ *   （`resumed`，完成后父会话照常收 `<task-notification>`）。子会话 user 消息记 `origin: "direct"`；
+ * - `drainDirect`：运行结束时把排着的消息合成一条续聊；任务被停止时丢弃（停止的一方不想它再跑）。
+ */
+import type { TaskLive, TaskRecord } from "../agents/task-record.js";
+import type { SubagentRequest, SubagentResult } from "../tools/types.js";
+export type DirectReply = "steered" | "queued" | "resumed";
+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 drainDirect(record: TaskRecord, host: DirectHost): void;

package/dist/agent/subagent-direct.js

@@ -0,0 +1,76 @@
+/**
+ * 子 Agent 视图的直接对话与实时数据（docs/wave6-plan.md §1.2–§1.3、D3）。[W6-A]
+ *
+ * 从 subagent-registry.ts 拆出（保持 ≤ 600 行）：
+ * - `liveOf`：视图读的快照、是否在并发池排队、ama 子会话的观察钩子与外部 Agent 的环形缓冲；
+ * - `directMessage`：人在视图里发的消息——ama 运行中 → 子会话 followUp（回合结束投递，返回 `steered`）；
+ *   外部 Agent 运行中 / 还在排队 → 等本次运行结束后续聊（`queued`）；已结束 → 同 `task_ctl send` 的后台续聊
+ *   （`resumed`，完成后父会话照常收 `<task-notification>`）。子会话 user 消息记 `origin: "direct"`；
+ * - `drainDirect`：运行结束时把排着的消息合成一条续聊；任务被停止时丢弃（停止的一方不想它再跑）。
+ */
+import { AmaError } from "../errors.js";
+export function liveOf(record) {
+    const handle = record.handle;
+    const live = {
+        info: { ...record.info },
+        queued: record.queued === true,
+        recent: handle?.recent?.() ?? record.ring?.items() ?? [],
+        pending: record.direct?.length ?? 0,
+    };
+    const observe = handle?.observe;
+    const entries = handle?.entries;
+    if (observe !== undefined)
+        live.observe = (listener) => observe.call(handle, listener);
+    if (entries !== undefined)
+        live.entries = () => entries.call(handle);
+    return live;
+}
+export async function directMessage(record, text, host) {
+    if (text.trim() === "")
+        throw new AmaError("invalid_arguments", "empty message");
+    if (record.running !== undefined) {
+        const handle = record.handle;
+        if (handle?.message !== undefined && record.queued !== true) {
+            try {
+                await handle.message(text, "followUp");
+                return "steered";
+            }
+            catch (error) {
+                // 子会话这一轮刚结束、注册表还没收尾：排到运行结束后续聊
+                if (!(error instanceof AmaError) || error.code !== "task_idle")
+                    throw error;
+            }
+        }
+        (record.direct ??= []).push(text);
+        return "queued";
+    }
+    await resumeDirect(record, text, host);
+    return "resumed";
+}
+async function resumeDirect(record, text, host) {
+    const spawn = host.spawnSubagent;
+    if (spawn === undefined)
+        throw new AmaError("unsupported", "this session cannot continue sub-agent tasks");
+    record.directNext = true;
+    const result = await spawn.call(host, {
+        prompt: text,
+        taskId: record.info.taskId,
+        background: true,
+        parentToolCallId: record.parentToolCallId,
+        signal: new AbortController().signal,
+    });
+    if (result.isError) {
+        delete record.directNext;
+        throw new AmaError("task_not_resumable", result.text);
+    }
+}
+export function drainDirect(record, host) {
+    const queued = record.direct?.splice(0) ?? [];
+    if (queued.length === 0)
+        return;
+    if (record.info.status === "aborted") {
+        host.log("info", `task ${record.info.taskId} was stopped; ${queued.length} queued message(s) dropped`);
+        return;
+    }
+    void resumeDirect(record, queued.join("\n\n"), host).catch((error) => host.log("warn", `task ${record.info.taskId}: queued message failed: ${String(error)}`));
+}

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

@@ -12,10 +12,11 @@
  * - 结果 > 50 KB 保留头尾并全文落 `outputs/`；轮数耗尽加说明；worktree 隔离；
  * - 事件 `subagent_start / update / end`；父会话 `custom{ama.task}` 记任务快照（带 `status`），
  *   resume 时据此重建（未完成标 `interrupted`）。
+ * - [W6-A] 子 Agent 视图的 `live()` / `message()`（实现在 subagent-direct.ts）。
  */
 import type { SubagentRequest, SubagentResult, SubagentRunner, TaskInfo, TaskRegistryView } from "../tools/types.js";
 import { AgentCatalog, type AgentModelConfig } from "../agents/catalog.js";
-import { SubagentPool, TASK_CUSTOM_TYPE, type AmaRunnerSpec, type TaskHandle } from "../agents/task-record.js";
+import { SubagentPool, TASK_CUSTOM_TYPE, type AmaRunnerSpec, type TaskHandle, type TaskLive } from "../agents/task-record.js";
 import { type TaskControl } from "../agents/task-control.js";
 import type { AgentDefinition, AgentInfo } from "../agents/types.js";
 import type { SessionCore } from "./session-core.js";
@@ -41,6 +42,8 @@ export type RegistryHost = Pick<SessionCore, "manager" | "cwd" | "emit" | "appen
         origin?: string;
     }): Promise<unknown>;
     waitForIdle?(): Promise<void>;
+    /** [W6-A] 视图里续聊已结束的任务（AgentSessionImpl 的方法，经 runSubagent 拿到 ama runner 工厂）。 */
+    spawnSubagent?(request: SubagentRequest): Promise<SubagentResult>;
 };
 /** RPC `get_tasks` / `/tasks`：会话 id → 注册表视图（没有任务时 undefined）。 */
 export declare function taskRegistryView(sessionId: string): TaskRegistryView | undefined;
@@ -68,6 +71,10 @@ export declare class SubagentRegistry implements TaskControl {
     output(taskId: string): string | undefined;
     /** 等任务结束或超时；超时返回 undefined。 */
     wait(taskId: string, timeoutMs: number): Promise<SubagentResult | undefined>;
+    /** [W6-A] 子 Agent 视图读的实时数据；未知任务 undefined。 */
+    live(taskId: string): TaskLive | undefined;
+    /** [W6-A] 人在子 Agent 视图里发的消息（subagent-direct.ts）。 */
+    message(taskId: string, text: string): Promise<"steered" | "queued" | "resumed">;
     stop(taskId: string): Promise<SubagentResult | undefined>;
     run(request: SubagentRequest, ama: AmaRunnerFactory): Promise<SubagentResult>;
     private continueTask;

package/dist/agent/subagent-registry.js

@@ -12,6 +12,7 @@
  * - 结果 > 50 KB 保留头尾并全文落 `outputs/`；轮数耗尽加说明；worktree 隔离；
  * - 事件 `subagent_start / update / end`；父会话 `custom{ama.task}` 记任务快照（带 `status`），
  *   resume 时据此重建（未完成标 `interrupted`）。
+ * - [W6-A] 子 Agent 视图的 `live()` / `message()`（实现在 subagent-direct.ts）。
  */
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -23,6 +24,8 @@ import { SubagentPool, TASK_CUSTOM_TYPE, applyRunnerEvent, flushText, newRecord,
 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";
 export const DEFAULT_SUBAGENT_CONCURRENCY = 4;
 export const DEFAULT_MAX_PENDING = 16;
 export const DEFAULT_RETAINED = 16;
@@ -126,6 +129,18 @@ export class SubagentRegistry {
             clearTimeout(timer);
         }
     }
+    /** [W6-A] 子 Agent 视图读的实时数据；未知任务 undefined。 */
+    live(taskId) {
+        const record = this.tasks.get(taskId);
+        return record === undefined ? undefined : liveOf(record);
+    }
+    /** [W6-A] 人在子 Agent 视图里发的消息（subagent-direct.ts）。 */
+    async message(taskId, text) {
+        const record = this.tasks.get(taskId);
+        if (record === undefined)
+            throw new AmaError("task_not_found", `unknown task ${taskId}`);
+        return directMessage(record, text, this.host);
+    }
     async stop(taskId) {
         const record = this.tasks.get(taskId);
         if (record === undefined)
@@ -206,6 +221,8 @@ export class SubagentRegistry {
             parentSignal?.removeEventListener("abort", onParentAbort);
             delete record.running;
             delete record.controller;
+            if (!this.disposed)
+                drainDirect(record, this.host);
         });
         record.running = running;
         if (!background)
@@ -229,12 +246,15 @@ export class SubagentRegistry {
         return result;
     }
     async execute(record, request, ama, signal) {
+        record.queued = true;
         try {
             await this.pool.acquire(signal);
         }
         catch {
+            delete record.queued;
             return this.finish(record, { ...failed("aborted by user"), status: "aborted" });
         }
+        delete record.queued;
         try {
             if (record.isolation === "worktree" && record.worktree === undefined) {
                 // 名字带会话 id 前缀：不同会话的 t1 不会撞到同一个 worktree / 分支
@@ -265,10 +285,15 @@ export class SubagentRegistry {
     }
     async handleFor(record, request, ama, signal) {
         const live = record.handle;
+        const direct = record.directNext === true;
+        delete record.directNext;
         if (live !== undefined) {
             this.touch(record.info.taskId);
             this.emitStart(record, live);
-            await live.send(request.prompt);
+            if (direct && live.message !== undefined)
+                await live.message(request.prompt, "send");
+            else
+                await live.send(request.prompt);
             return live;
         }
         const ref = record.info.sessionRef;
@@ -281,6 +306,7 @@ export class SubagentRegistry {
                 cwd: record.cwd,
                 ...(ref?.sessionFile === undefined ? {} : { resumeFile: ref.sessionFile }),
                 isolated: record.worktree !== undefined,
+                ...(direct ? { origin: "direct" } : {}),
             })
             : this.env.runners?.(record.agent);
         if (runner === undefined)
@@ -327,6 +353,7 @@ export class SubagentRegistry {
             emit: (event) => this.host.emit(event),
             log: (level, message) => this.host.log(level, message),
             now: () => this.now(),
+            appendTrace: (data) => appendTraceEntry(this.host, data), // [W6-C0]
         };
     }
     async finish(record, result, aborted = false) {

package/dist/agent/system-prompt.d.ts

@@ -13,7 +13,7 @@ import type { SystemMessage, ToolDecl } from "../ai/types.js";
 import { type SystemState } from "../session/projection.js";
 import type { AgentMessage } from "../session/types.js";
 import type { ToolDefinition } from "../tools/types.js";
-export declare const SECTION_ORDER: readonly ["preamble", "tools", "rules", "project_context", "skills", "hooks", "cwd", "host", "role"];
+export declare const SECTION_ORDER: readonly ["preamble", "tools", "rules", "project_context", "skills", "memory", "hooks", "cwd", "host", "role"];
 export type SectionName = (typeof SECTION_ORDER)[number];
 export declare const DEFAULT_PREAMBLE: string;
 export interface SystemPromptInput {
@@ -38,6 +38,8 @@ export interface SystemPromptInput {
     hostInstructions?: readonly string[];
     /** [W5-G] task 子会话的角色说明（子 Agent 通用说明 + 类型正文）；主会话没有。 */
     role?: string;
+    /** [W6-C0] 预渲染的 `<memory_index>` 节（W6-M 的 memory/section.ts）；未开启记忆时不给。 */
+    memory?: string;
 }
 export declare function toolDecl(tool: ToolDefinition): ToolDecl;
 /** 按名排序的工具声明（与 ToolRegistry.active() 的顺序一致）。 */

package/dist/agent/system-prompt.js

@@ -18,6 +18,8 @@ export const SECTION_ORDER = [
     "rules",
     "project_context",
     "skills",
+    // [W6-C0] 记忆索引（W6-M，docs/wave6-plan.md §3.4）；未开启时为 undefined，字节不变
+    "memory",
     "hooks",
     "cwd",
     "host",
@@ -66,6 +68,7 @@ export function assembleSections(input) {
         rules: rules.length > 0 ? `Rules:\n${rules.map((rule) => `- ${rule}`).join("\n")}` : undefined,
         project_context: nonEmpty(projectContext),
         skills: nonEmpty(skills),
+        memory: nonEmpty(input.memory),
         hooks: nonEmpty(input.hookContext),
         cwd: `Current working directory: ${input.cwd}`,
         host: host.length > 0 ? host.join("\n\n") : undefined,

package/dist/agent/tool-runner.d.ts

@@ -8,7 +8,8 @@
  * `terminate` 要整批都为真才提前结束。`stopReason: "length"` 且有工具调用 → 整批判失败不执行。
  * abort：未开始的调用直接给 `aborted by user` 错误结果；执行中的工具收到 signal，超过宽限期仍未结束
  * 则不再等待、记 `aborted by user`。结果超 `maxToolResultChars` 截断并把全文写到 `outputDir`：
- * [W5-H2] 保留头 70% + 尾 30%，中间 `[… N 字符已省略，全文 <path>]`（tools/truncate.ts）。
+ * [W5-H2] 保留头 70% + 尾 30%，中间 `[… N chars omitted (…; full output at <path>)]`（tools/truncate.ts；
+ * [W6-C0] 进模型的标记固定英文，与界面语言无关）。
  *
  * 嵌套调用（`ToolContext.tools.executeTool`，codemode 脚本里的 `tools.*`）走 `runSingleToolCall`：
  * 同一套校验与门禁，按**全部未禁用工具**查找（codemode only 模式下活动集只有 codemode），

package/dist/agent/tool-runner.js

@@ -8,7 +8,8 @@
  * `terminate` 要整批都为真才提前结束。`stopReason: "length"` 且有工具调用 → 整批判失败不执行。
  * abort：未开始的调用直接给 `aborted by user` 错误结果；执行中的工具收到 signal，超过宽限期仍未结束
  * 则不再等待、记 `aborted by user`。结果超 `maxToolResultChars` 截断并把全文写到 `outputDir`：
- * [W5-H2] 保留头 70% + 尾 30%，中间 `[… N 字符已省略，全文 <path>]`（tools/truncate.ts）。
+ * [W5-H2] 保留头 70% + 尾 30%，中间 `[… N chars omitted (…; full output at <path>)]`（tools/truncate.ts；
+ * [W6-C0] 进模型的标记固定英文，与界面语言无关）。
  *
  * 嵌套调用（`ToolContext.tools.executeTool`，codemode 脚本里的 `tools.*`）走 `runSingleToolCall`：
  * 同一套校验与门禁，按**全部未禁用工具**查找（codemode only 模式下活动集只有 codemode），
@@ -130,13 +131,13 @@ function truncateResult(call, result, options, nested = false) {
     const text = resultText(result.content);
     if (text.length <= limit)
         return result;
-    let where = "全文未保存";
+    let where = "full output not saved";
     if (options.outputDir !== undefined) {
         try {
             mkdirSync(options.outputDir, { recursive: true });
             const file = join(options.outputDir, `${call.id.replace(/[^A-Za-z0-9_-]/g, "_")}.txt`);
             writeFileSync(file, text, "utf8");
-            where = `全文 ${file}`;
+            where = `full output at ${file}`;
         }
         catch {
             // 落盘失败只影响提示文字
@@ -145,7 +146,7 @@ function truncateResult(call, result, options, nested = false) {
     const images = typeof result.content === "string"
         ? []
         : result.content.filter((block) => block.type === "image");
-    const { content } = truncateMiddle(text, limit, (omitted) => `[… ${omitted} 字符已省略（输出过长已截断：共 ${text.length} 字符，${where}）]`);
+    const { content } = truncateMiddle(text, limit, (omitted) => `[… ${omitted} chars omitted (truncated from ${text.length} chars; ${where})]`);
     return {
         ...result,
         content: images.length > 0 ? [{ type: "text", text: content }, ...images] : content,

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

@@ -0,0 +1,39 @@
+/**
+ * 第六波会话事件与统计（docs/wave6-plan.md §4.4、D17）。[W6-C0] 契约文件：形状在这里，行为由 W6-O 实现。
+ */
+/** 一档配额窗口的用量。 */
+export interface QuotaWindow {
+    /** 0–100。 */
+    usedPercent: number;
+    /** epoch ms。 */
+    resetsAt?: number;
+    windowMinutes?: number;
+}
+/**
+ * [W6-O] 订阅配额更新：codex flavor 来自 `x-codex-*` 响应头与 `codex.rate_limits` 事件；SIWC 只在 429 时给出。
+ * 宿主只消费它与错误码 `auth_expired` / `quota_exceeded`。
+ */
+export interface QuotaUpdateEvent {
+    type: "quota_update";
+    provider: string;
+    planType?: string;
+    primary?: QuotaWindow;
+    secondary?: QuotaWindow;
+}
+export type SessionEventW6 = QuotaUpdateEvent;
+/** [W6-O] 订阅计费的请求（`Usage.billing: "subscription"`）：单列，不折算美元。 */
+export interface SubscriptionStats {
+    requests: number;
+    byProvider: Record<string, {
+        requests: number;
+        input: number;
+        output: number;
+        cacheRead: number;
+    }>;
+    /** [W6-O] 本会话最近一次 `quota_update`（没有收到过时缺省）。 */
+    quota?: QuotaUpdateEvent;
+}
+export interface SessionStatsW6 {
+    /** [W6-O] 订阅用量；没有订阅请求时缺省。 */
+    subscription?: SubscriptionStats;
+}

package/dist/agent/types-w6.js

@@ -0,0 +1,4 @@
+/**
+ * 第六波会话事件与统计（docs/wave6-plan.md §4.4、D17）。[W6-C0] 契约文件：形状在这里，行为由 W6-O 实现。
+ */
+export {};

package/dist/agent/types.d.ts

@@ -28,6 +28,7 @@ import type { AgentMessage, BranchSummaryEntry, SessionEntry } from "../session/
 import type { RewindMode, RewindPoint, RewindRequest, RewindResult, RewindSkipReason } from "../checkpoints/types.js";
 import type { ToolDefinition, ToolResult } from "../tools/types.js";
 import type { SessionEventW5, SessionStatsW5 } from "./types-w5.js";
+import type { SessionEventW6, SessionStatsW6 } from "./types-w6.js";
 export type * from "./types-w5.js";
 export type { AssistantContentBlock, AssistantMessage, ContentBlock, ImageBlock, Message, StopReason, SystemMessage, TextBlock, ThinkingBlock, ToolCallBlock, ToolResultMessage, Usage, UserMessage, } from "../ai/types.js";
 export type { AgentMessage, BranchSummaryMessage, CompactionSummaryMessage, CustomMessage, } from "../session/types.js";
@@ -292,7 +293,9 @@ export type SessionEvent = {
     estimatedTurnsLeft?: number;
 }
 /** [W5-C0] 第五波事件（agent/types-w5.ts）。 */
- | SessionEventW5;
+ | SessionEventW5
+/** [W6-C0] 第六波事件（agent/types-w6.ts）。 */
+ | SessionEventW6;
 export type SessionEventType = SessionEvent["type"];
 export type PromptDisposition = "started" | "queued" | "handled";
 export interface PromptOptions {
@@ -325,7 +328,7 @@ export interface SessionState {
     autoRetry: boolean;
 }
 /** [W5-C0] `telemetry? / external? / tasks?` 见 `SessionStatsW5`。 */
-export interface SessionStats extends SessionStatsW5 {
+export interface SessionStats extends SessionStatsW5, SessionStatsW6 {
     sessionId: string;
     sessionFile: string | undefined;
     userMessages: number;

package/dist/agents/external.js

@@ -106,7 +106,7 @@ class ExternalTaskHandle {
             }
         }
         if (this.inner.id === "")
-            throw new AmaError("agent_closed", "外部 Agent 会话没有建立，不能续聊");
+            throw new AmaError("agent_closed", "the external agent session was never established; cannot continue it");
         this.inner = await this.reopen(this.inner.id, text);
         this.stopped = false;
     }

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

@@ -4,6 +4,9 @@
  * 编排在 agent/subagent-registry.ts。
  */
 import type { 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";
 import type { Worktree, WorktreeOutcome } from "../agent/worktree.js";
 import type { SessionEntry } from "../session/types.js";
 import type { RunnerHandle, SubagentEvent, SubagentRequest, SubagentResult, TaskInfo } from "../tools/types.js";
@@ -34,13 +37,73 @@ export interface AmaRunnerSpec {
     resumeFile?: string;
     /** worktree 里运行：不记父会话检查点。 */
     isolated: boolean;
+    /** [W6-A] 首条 prompt 的 origin（子 Agent 视图里续聊已释放的子会话 = `"direct"`）。 */
+    origin?: MessageOrigin;
 }
-/** runner 句柄的可选扩展（ama 子会话提供）。 */
+/**
+ * [W6-C0] 外部 Agent 的展示事件（`DriverEvent` 派生，子 Agent 视图用）：只在内存环形缓冲里（≤ 2000 条 /
+ * 1 MB），不落盘（docs/wave6-plan.md §1.2、D2）。
+ */
+export interface ExternalDisplayEvent {
+    at: number;
+    kind: "text" | "thought" | "tool" | "notice" | "turn";
+    text?: string;
+    toolName?: string;
+    toolId?: string;
+    status?: "started" | "completed" | "failed";
+    level?: "info" | "warn";
+    turn?: number;
+}
+/** runner 句柄的可选扩展（ama 子会话提供；[W6-C0] 视图钩子由 W6-A 实现）。 */
 export type TaskHandle = RunnerHandle & {
     readonly sessionFile?: string;
     readonly model?: string;
     dispose?(): Promise<void>;
+    /** [W6-C0] ama 子会话的实时事件（子 Agent 视图跟随）；返回取消订阅。 */
+    observe?(listener: (event: SessionEvent) => void): () => void;
+    /** [W6-C0] ama 子会话当前分支的条目（视图全量渲染）。 */
+    entries?(): readonly SessionEntry[];
+    /** [W6-C0] 外部 Agent 的环形缓冲（W6-A）。 */
+    recent?(): readonly ExternalDisplayEvent[];
+    /**
+     * [W6-A] 人在子 Agent 视图里直接发的消息（子会话 user 消息 `origin: "direct"`）：`followUp` = 本轮运行中
+     * 排到回合结束（不在运行中抛 `task_idle`，由注册表排队到运行结束后续聊）；`send` = 空闲时开新一轮（同 `send`）。
+     * ama 子会话提供。
+     */
+    message?(text: string, when: "followUp" | "send"): Promise<void>;
 };
+/** [W6-A] 外部 Agent 环形缓冲的上限（docs/wave6-plan.md D2）。 */
+export declare const RING_MAX_EVENTS = 2000;
+export declare const RING_MAX_BYTES: number;
+/**
+ * [W6-A] 外部 Agent 展示事件的内存环形缓冲：相邻的同类文本（text / thought）合并成一条；超过条数或字节
+ * 上限从最旧的丢。只在内存，不落盘（第五波 §5.4：外部 Agent 原始事件不进 JSONL）。
+ */
+export declare class DisplayRing {
+    private readonly maxEvents;
+    private readonly maxBytes;
+    private readonly events;
+    private bytes;
+    constructor(maxEvents?: number, maxBytes?: number);
+    get size(): number;
+    items(): readonly ExternalDisplayEvent[];
+    push(event: ExternalDisplayEvent): void;
+    private trim;
+    private drop;
+}
+/** [W6-A] 子 Agent 视图读的一条任务的实时数据（`SubagentRegistry.live`）。 */
+export interface TaskLive {
+    info: TaskInfo;
+    /** 还在并发池里排队（尚未开跑）。 */
+    queued: boolean;
+    /** ama 子会话的观察钩子（句柄在内存时）。 */
+    observe?(listener: (event: SessionEvent) => void): () => void;
+    entries?(): readonly SessionEntry[];
+    /** 外部 Agent 的环形缓冲（本进程里跑过才有）。 */
+    recent: readonly ExternalDisplayEvent[];
+    /** 人在视图里发、等运行结束再续聊的消息数。 */
+    pending: number;
+}
 export interface TaskRecord {
     info: TaskInfo;
     agent: AgentDefinition;
@@ -59,12 +122,22 @@ export interface TaskRecord {
     worktreeOutcome?: WorktreeOutcome;
     last?: SubagentResult;
     onUpdate?: (partial: string) => void;
+    /** [W6-A] 在并发池里排队（acquire 之前）。 */
+    queued?: boolean;
+    /** [W6-A] 外部 Agent 的展示事件（内存环形缓冲）。 */
+    ring?: DisplayRing;
+    /** [W6-A] 视图里发来、等本次运行结束再续聊的消息。 */
+    direct?: string[];
+    /** [W6-A] 下一次续聊是人在视图里发的（子会话 user 消息记 `origin: "direct"`）。 */
+    directNext?: boolean;
 }
 export declare function newRecord(info: TaskInfo, agent: AgentDefinition, parentToolCallId: string, cwd: string, isolation?: "none" | "worktree"): TaskRecord;
 export interface ProgressSink {
     emit(event: SubagentUpdateEvent): void;
     log(level: "info" | "warn", message: string): void;
     now(): number;
+    /** [W6-C0] 写父会话的 `ama.trace`（外部 Agent 回合骨架）。 */
+    appendTrace?(data: TraceExternalTurnData): void;
 }
 export declare function flushText(record: TaskRecord, sink: ProgressSink): void;
 /** runner 进度 → 记录与 `subagent_update`（文本 ≥ 250 ms 合并，轮次与结束时冲刷）。 */

package/dist/agents/task-record.js

@@ -44,6 +44,66 @@ export class SubagentPool {
         this.waiters[0]?.();
     }
 }
+/** [W6-A] 外部 Agent 环形缓冲的上限（docs/wave6-plan.md D2）。 */
+export const RING_MAX_EVENTS = 2000;
+export const RING_MAX_BYTES = 1024 * 1024;
+/**
+ * [W6-A] 外部 Agent 展示事件的内存环形缓冲：相邻的同类文本（text / thought）合并成一条；超过条数或字节
+ * 上限从最旧的丢。只在内存，不落盘（第五波 §5.4：外部 Agent 原始事件不进 JSONL）。
+ */
+export class DisplayRing {
+    maxEvents;
+    maxBytes;
+    events = [];
+    bytes = 0;
+    constructor(maxEvents = RING_MAX_EVENTS, maxBytes = RING_MAX_BYTES) {
+        this.maxEvents = maxEvents;
+        this.maxBytes = maxBytes;
+    }
+    get size() {
+        return this.bytes;
+    }
+    items() {
+        return this.events;
+    }
+    push(event) {
+        const last = this.events.at(-1);
+        const add = sizeOf(event);
+        if (last !== undefined &&
+            (event.kind === "text" || event.kind === "thought") &&
+            last.kind === event.kind &&
+            last.turn === event.turn) {
+            last.text = (last.text ?? "") + (event.text ?? "");
+            this.bytes += add;
+        }
+        else {
+            this.events.push({ ...event });
+            this.bytes += add;
+        }
+        this.trim();
+    }
+    trim() {
+        while (this.events.length > this.maxEvents)
+            this.drop();
+        while (this.bytes > this.maxBytes && this.events.length > 1)
+            this.drop();
+        const only = this.events[0];
+        if (this.bytes > this.maxBytes && only?.text !== undefined) {
+            // 单条超过上限：保留尾部
+            const keep = only.text.slice(only.text.length - Math.floor(this.maxBytes / 4));
+            this.bytes = this.bytes - Buffer.byteLength(only.text) + Buffer.byteLength(keep);
+            only.text = keep;
+        }
+    }
+    drop() {
+        const first = this.events.shift();
+        if (first !== undefined)
+            this.bytes -= sizeOf(first);
+    }
+}
+function sizeOf(event) {
+    return Buffer.byteLength(event.text ?? "") + Buffer.byteLength(event.toolName ?? "") + 32;
+}
 export function newRecord(info, agent, parentToolCallId, cwd, isolation = "none") {
     return { info, agent, parentToolCallId, isolation, cwd, text: "", pendingText: "", lastFlush: 0 };
 }
@@ -63,6 +123,8 @@ export function flushText(record, sink) {
 /** runner 进度 → 记录与 `subagent_update`（文本 ≥ 250 ms 合并，轮次与结束时冲刷）。 */
 export function applyRunnerEvent(record, event, sink) {
     const taskId = record.info.taskId;
+    if (record.info.runner !== "ama")
+        recordDisplay(record, event, sink.now());
     switch (event.type) {
         case "text":
             record.text += event.delta;
@@ -105,6 +167,44 @@ export function applyRunnerEvent(record, event, sink) {
         case "notice":
             sink.log(event.level, `[task ${taskId}] ${event.text}`);
             return;
+        case "turn_trace":
+            sink.appendTrace?.({
+                kind: "external_turn",
+                taskId,
+                agent: record.info.agent,
+                ...event.trace,
+            });
+            return;
+        default:
+            return;
+    }
+}
+/** [W6-A] 外部 Agent 的进度 → 环形缓冲（ama 子会话由视图直接订阅子会话，不进这里）。 */
+function recordDisplay(record, event, now) {
+    const turn = record.info.turns ?? 0;
+    const ring = (record.ring ??= new DisplayRing());
+    switch (event.type) {
+        case "text":
+        case "thought":
+            if (event.delta !== "")
+                ring.push({ at: now, kind: event.type, text: event.delta, turn });
+            return;
+        case "tool":
+            ring.push({
+                at: event.at ?? now,
+                kind: "tool",
+                toolName: event.toolName,
+                status: event.status,
+                ...(event.id === undefined ? {} : { toolId: event.id }),
+                turn,
+            });
+            return;
+        case "turn":
+            ring.push({ at: now, kind: "turn", turn: event.turn });
+            return;
+        case "notice":
+            ring.push({ at: now, kind: "notice", text: event.text, level: event.level, turn });
+            return;
         default:
             return;
     }

package/dist/ai/apis/cache-params.js

@@ -14,6 +14,7 @@
  * 并提示一次（实测：某中转的 Responses 对 DeepSeek 拒收 prompt_cache_retention / _options）。
  */
 import { HttpError, postJson } from "../http.js";
+import { msg } from "../../i18n/index.js";
 const DEFAULT_BASE_URLS = {
     "anthropic-messages": "https://api.anthropic.com",
     "openai-completions": "https://api.openai.com/v1",
@@ -176,7 +177,7 @@ export async function postWithCacheFallback(model, url, options) {
         if (!field || !stripped || stripped.removed === 0)
             throw error;
         strippedCacheParams.add(key);
-        warn(`${key}：该端点不支持 ${field}，已自动去掉缓存参数重发；可在 config 里设 ${SUGGESTION[field] ?? "相应的 compat 开关"}`);
+        warn(msg().errors.cacheParamsStripped(key, field, SUGGESTION[field]));
         return postJson(url, { ...options, body: stripped.body });
     }
 }