@armadra/agent 0.4.0 → 0.5.0

package/dist/agent/session.js

@@ -1,16 +1,13 @@
 /**
  * AgentSessionImpl（设计 §4.2–§4.3、§9、§11.1 第 16 步、§13.1）。[B2]
  *
- * 会话 = SessionManager（JSONL 树，事实来源）+ Agent（上下文消息、队列、run）+ 压缩 / 重试 / Hook 调度。
- * - 每条 message_end 落盘为条目；Agent 的上下文 = 活动分支的投影（压缩 / context_edit 后重建）。
- * - 首次模型请求前把系统提示 + 工具表作为首条 `system` 消息落盘并 `flush()`（此时才创建文件）；
- *   之后节或工具表变化落 system 补丁。
- * - `prompt()`：运行中且无 streamingBehavior → `AmaError{code:"busy"}`；否则展开（expandPrompt）→
- *   UserPromptSubmit Hook → 阈值压缩检查 → 会话周期（session-run.ts）；周期结束后 resolve。
- * - `steer()` / `followUp()`：运行中入队（返回 "queued"）；空闲时直接以该消息开始一个周期（"handled"）。
- * - `abort()`：中断供应商流、工具、重试等待与压缩；回到 idle 后 resolve；不清队列。
+ * 会话 = SessionManager（JSONL 树，事实来源）+ Agent（上下文、队列、run）+ 压缩 / 重试 / Hook / 回滚调度。
+ * 每条 message_end 落盘；首次请求前落 system + 工具表并 flush。`prompt()` 运行中且无
+ * streamingBehavior → busy；`steer / followUp` 运行中入队、空闲时直接开周期；`abort()` 不清队列。
+ * [W5-C0] 设置类方法在 session-settings.ts；扩展点（session-extensions.ts）的调用点：构造时
+ * wrapStream、emit 后 onEvent、runPrompt 的 beforePrompts、agent_settled 后 onAgentSettled、
+ * getStats 末尾 contributeStats、dispose。
  */
-import { modelRefOf } from "../ai/providers/channels.js";
 import { join } from "node:path";
 import { AmaError } from "../errors.js";
 import { createSessionClassifier } from "./session-classifier.js";
@@ -20,16 +17,15 @@ import { queuedText } from "./queue.js";
 import { resolveRetrySettings } from "./retry.js";
 import { SessionCacheController, resolveCacheSettings } from "./session-cache.js";
 import { CompactionController } from "./session-compaction.js";
-import { makeUserMessage, runPrompt } from "./session-run.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 { persistMessage, runHookWithEvents, syncSystemMessage } from "./session-sync.js";
+import { SessionExtensions } from "./session-extensions.js";
+import { SessionSettings, providerStream } from "./session-settings.js";
 import { createToolRunnerOptions } from "./session-tools.js";
+import { RewindController } from "./session-rewind.js";
 import { convertToLlm } from "./transform.js";
-/** `"user"` = 普通用户输入，不写 origin。 */
-function normalizeOrigin(origin) {
-    return origin === undefined || origin === "user" ? undefined : origin;
-}
 export class AgentSessionImpl {
     options;
     manager;
@@ -39,10 +35,8 @@ export class AgentSessionImpl {
     readFiles = new Set();
     stream;
     cache;
-    currentModel;
-    currentThinking;
-    allTools = new Map();
-    activeNames;
+    settings;
+    extensions;
     listeners = new Set();
     compaction;
     retrySettings;
@@ -51,40 +45,35 @@ export class AgentSessionImpl {
     stopReason;
     stopFlag = false;
     turns = 0;
-    systemInput;
     subagentPool;
     disposed = false;
     classifier;
     /** 已入队、尚未投递的消息（投递时发 queue_update）。 */
     queuedMessages = new WeakSet();
+    rewinder;
     constructor(options) {
         this.options = options;
         this.manager = options.sessionManager;
         this.cwd = this.manager.cwd;
         this.depth = options.depth ?? 0;
-        this.currentModel = options.model;
-        this.currentThinking = options.thinkingLevel ?? "off";
-        for (const tool of options.tools ?? [])
-            this.allTools.set(tool.name, tool);
-        this.activeNames = [...(options.activeTools ?? this.allTools.keys())].filter((name) => this.allTools.has(name));
-        this.systemInput = { ...(options.system ?? {}) };
+        this.settings = new SessionSettings(options, {
+            core: this,
+            assertUsable: () => this.assertUsable(),
+            onModelChanged: () => this.compaction.refresh(),
+        });
+        this.extensions = new SessionExtensions(this, options.extensions);
         this.retrySettings = resolveRetrySettings(options.retry);
         this.cache = new SessionCacheController(this, resolveCacheSettings(options.cache), {
             decider: () => options.warmingDecider?.(),
         });
-        this.stream = this.cache.wrapStream((model, context, streamOptions) => {
-            const api = options.providers.getApi(model.api);
-            if (api === undefined) {
-                throw new AmaError("provider_not_found", `no implementation registered for api ${model.api}`);
-            }
-            return api.stream(model, context, streamOptions);
-        });
+        // 缓存控制器在最外层（看到扩展改写后的最终请求）
+        this.stream = this.cache.wrapStream(this.extensions.wrapStream(providerStream(options.providers)));
         const runner = createToolRunnerOptions(this);
         const agentOptions = {
             hooks: {
                 convertToLlm: (messages) => convertToLlm(messages, {
-                    provider: this.currentModel.provider,
-                    model: this.currentModel.id,
+                    provider: this.settings.model.provider,
+                    model: this.settings.model.id,
                 }),
                 beforeToolCall: runner.beforeToolCall,
                 prepareNextTurn: async () => {
@@ -101,8 +90,8 @@ export class AgentSessionImpl {
                 },
             },
             stream: this.stream,
-            getModel: () => this.currentModel,
-            getThinkingLevel: () => this.currentThinking,
+            getModel: () => this.settings.model,
+            getThinkingLevel: () => this.settings.thinking,
             streamOptions: async () => {
                 const apiKey = await this.resolveApiKey();
                 const idle = options.idleTimeoutMs;
@@ -115,6 +104,7 @@ export class AgentSessionImpl {
             beforeRequest: async () => {
                 this.syncSystem();
                 this.manager.flush();
+                await this.rewinder.ready();
             },
             tools: runner,
             messages: buildProjection(this.manager.branch()).messages,
@@ -129,15 +119,24 @@ export class AgentSessionImpl {
         this.compaction = new CompactionController(this, options.compaction);
         const subagents = options.subagents === false ? undefined : options.subagents;
         this.subagentPool = new SubagentPool(subagents?.maxConcurrent ?? DEFAULT_SUBAGENT_CONCURRENCY);
+        this.rewinder = new RewindController({
+            core: this,
+            running: () => {
+                this.assertUsable();
+                return this.cycle !== undefined;
+            },
+            navigate: (targetId, navigateOptions) => this.navigate(targetId, navigateOptions),
+            compactAt: (entryId, instructions) => this.compact(instructions, entryId),
+        });
     }
     // -------------------------------------------------------------------------
     // SessionCore
     // -------------------------------------------------------------------------
     model() {
-        return this.currentModel;
+        return this.settings.model;
     }
     thinkingLevel() {
-        return this.currentThinking;
+        return this.settings.thinking;
     }
     outputDir() {
         if (this.options.outputDir !== undefined)
@@ -147,7 +146,7 @@ export class AgentSessionImpl {
     }
     async resolveApiKey() {
         try {
-            const { provider, channel } = this.currentModel;
+            const { provider, channel } = this.settings.model;
             return (await this.options.providers.resolveApiKey(provider, channel)).apiKey;
         }
         catch {
@@ -164,6 +163,7 @@ export class AgentSessionImpl {
                 this.log("warn", `session listener failed on ${event.type}: ${String(error)}`);
             }
         }
+        this.extensions.onEvent(event);
     }
     appendEntry(input) {
         const entry = this.manager.append(input);
@@ -174,13 +174,13 @@ export class AgentSessionImpl {
         this.agent.messages = buildProjection(this.manager.branch()).messages;
     }
     activeTool(name) {
-        return this.activeNames.includes(name) ? this.allTools.get(name) : undefined;
+        return this.settings.activeTool(name);
     }
     tool(name) {
-        return this.allTools.get(name);
+        return this.settings.tool(name);
     }
     activeToolNames() {
-        return [...this.activeNames];
+        return this.settings.activeToolNames();
     }
     runHook(event, payload, signal) {
         return runHookWithEvents(this, event, payload, signal);
@@ -197,7 +197,7 @@ export class AgentSessionImpl {
     // -------------------------------------------------------------------------
     onAgentEvent(event) {
         if (event.type === "message_end")
-            persistMessage(this, event.message);
+            this.rewinder.onPersisted(persistMessage(this, event.message));
         else if (event.type === "agent_start")
             this.compaction.breaker.startRun();
         this.emit(event);
@@ -215,7 +215,7 @@ export class AgentSessionImpl {
         });
     }
     syncSystem() {
-        syncSystemMessage(this, this.systemInput, this.getTools());
+        syncSystemMessage(this, this.settings.systemInput, this.getTools());
     }
     // -------------------------------------------------------------------------
     // 周期
@@ -256,6 +256,9 @@ export class AgentSessionImpl {
                 this.retrying = value;
             },
             lastAssistantText: () => this.getLastAssistantText(),
+            beginTurn: (message) => this.rewinder.beginTurn(message),
+            beforePrompts: (prompts) => this.extensions.beforePrompts(prompts),
+            afterSettled: () => this.extensions.onAgentSettled(),
         };
     }
     // -------------------------------------------------------------------------
@@ -321,13 +324,21 @@ export class AgentSessionImpl {
         this.listeners.add(listener);
         return () => this.listeners.delete(listener);
     }
-    /** 手动压缩；运行中 → busy。 */
-    compact(instructions) {
+    /** 手动压缩；运行中 → busy。`cutAt`：以该条目为切点（「摘要到这里」）。 */
+    compact(instructions, cutAt) {
         this.assertUsable();
         if (this.cycle !== undefined)
             return Promise.reject(new AmaError("busy", "cannot compact while running"));
-        return this.startCycle((signal) => this.compaction.compactManual(instructions, signal));
-    }
+        return this.startCycle((signal) => this.compaction.compactManual(instructions, signal, cutAt));
+    }
+    // [RW-B] 回滚（docs/rewind-plan.md §3；编排与校验在 session-rewind.ts）
+    rewindPoints = () => this.rewinder.points();
+    rewind = (request) => this.rewinder.rewind(request);
+    summarizeFrom = (entryId, instructions) => this.rewinder.summarizeFrom(entryId, instructions);
+    summarizeUpTo = (entryId, instructions) => this.rewinder.summarizeUpTo(entryId, instructions);
+    canUndoAbortedTurn = () => this.rewinder.canUndoAbortedTurn();
+    undoAbortedTurn = () => this.rewinder.undoAbortedTurn();
+    checkpointHooks = () => this.rewinder.hooks();
     async fork(entryId) {
         this.assertUsable();
         if (this.cycle !== undefined)
@@ -338,9 +349,7 @@ export class AgentSessionImpl {
             sessionManager: this.manager.fork(entryId),
         });
     }
-    /**
-     * `/tree`：同文件换叶子；`summarize` 时为离开的分支写 branch_summary（挂在新叶子下）。
-     */
+    /** `/tree`：同文件换叶子；`summarize` 时为离开的分支写 branch_summary（挂在新叶子下）。 */
     async navigate(targetId, options = {}) {
         this.assertUsable();
         if (this.cycle !== undefined)
@@ -355,83 +364,28 @@ export class AgentSessionImpl {
         this.cache.onContextChanged();
         return entry;
     }
-    async setModel(ref) {
-        this.assertUsable();
-        const lookup = this.options.providers.findModel(ref);
-        if (!lookup.ok) {
-            throw new AmaError("model_not_found", `model ${ref} not found`, {
-                detail: lookup.candidates,
-            });
-        }
-        this.currentModel = lookup.model;
-        this.compaction.refresh();
-        const next = modelRefOf(lookup.model);
-        this.appendEntry({
-            type: "model_change",
-            provider: next.provider,
-            modelId: next.id,
-            ...(next.channel !== undefined ? { channel: next.channel } : {}),
-        });
-        this.emit({ type: "model_changed", model: next });
-    }
-    setThinkingLevel(level) {
-        this.currentThinking = level;
-        this.appendEntry({ type: "thinking_level_change", thinkingLevel: level });
-        this.emit({ type: "thinking_level_changed", level });
-    }
-    setPermissionMode(mode) {
-        this.options.permission?.setMode(mode);
-        this.emit({ type: "permission_mode_changed", mode });
-    }
-    setActiveTools(names) {
-        const unknown = names.filter((name) => !this.allTools.has(name));
-        if (unknown.length > 0)
-            throw new AmaError("tool_not_found", `unknown tools: ${unknown.join(", ")}`);
-        this.activeNames = [...new Set(names)];
-    }
+    // [W5-C0] 设置类（session-settings.ts）
+    setModel = (ref) => this.settings.setModel(ref);
+    setThinkingLevel = (level) => this.settings.setThinkingLevel(level);
+    setPermissionMode = (mode) => this.settings.setPermissionMode(mode);
+    setActiveTools = (names) => this.settings.setActiveTools(names);
     /** 宿主 / SDK 在会话创建后追加工具（下次请求前以 system 补丁声明）。 */
-    addTool(tool, active = true) {
-        if (this.allTools.has(tool.name))
-            throw new AmaError("tool_exists", `tool ${tool.name} already exists`);
-        this.allTools.set(tool.name, tool);
-        if (active)
-            this.activeNames.push(tool.name);
-    }
-    /** 更新系统提示的静态部分（SessionStart Hook 的 hookContext、宿主 instructions 等）。 */
-    updateSystem(patch) {
-        this.systemInput = { ...this.systemInput, ...patch };
-    }
+    addTool = (tool, active = true) => this.settings.addTool(tool, active);
+    updateSystem = (patch) => this.settings.updateSystem(patch);
+    getTools = () => this.settings.getTools();
+    announceStart = (reason) => this.settings.announceStart(reason);
     setAutoCompaction(enabled) {
         this.compaction.setAuto(enabled);
     }
     setAutoRetry(enabled) {
         this.retrySettings = { ...this.retrySettings, enabled };
     }
-    getTools() {
-        return this.activeNames
-            .map((name) => this.allTools.get(name))
-            .filter((tool) => tool !== undefined)
-            .sort((a, b) => a.name.localeCompare(b.name));
-    }
-    /** 发 session_start（bootstrap / SDK 在会话就绪后调用一次）。 */
-    announceStart(reason) {
-        const event = {
-            type: "session_start",
-            sessionId: this.manager.id,
-            cwd: this.cwd,
-            reason,
-        };
-        const file = this.manager.file();
-        if (file !== undefined)
-            event.sessionFile = file;
-        this.emit(event);
-    }
     get state() {
         return buildSessionState({
             agent: this.agent,
             manager: this.manager,
-            model: this.currentModel,
-            thinkingLevel: this.currentThinking,
+            model: this.settings.model,
+            thinkingLevel: this.settings.thinking,
             permissionMode: this.options.permission?.mode ?? "default",
             isCompacting: this.compaction.isCompacting,
             isRetrying: this.retrying,
@@ -454,8 +408,8 @@ export class AgentSessionImpl {
     }
     getStats() {
         const contextTokens = this.compaction.estimate().tokens;
-        const contextWindow = this.currentModel.contextWindow;
-        return computeStats({
+        const contextWindow = this.settings.model.contextWindow;
+        const stats = computeStats({
             sessionId: this.manager.id,
             sessionFile: this.manager.file(),
             branch: this.manager.branch(),
@@ -463,12 +417,14 @@ export class AgentSessionImpl {
             contextWindow,
             cache: this.cache.stats({ tokens: contextTokens, window: contextWindow }),
         });
+        return this.extensions.contributeStats(stats);
     }
     async dispose() {
         if (this.disposed)
             return;
         await this.abort();
         this.cache.dispose();
+        this.extensions.dispose();
         this.disposed = true;
         this.manager.close();
         this.listeners.clear();
@@ -478,10 +434,10 @@ export class AgentSessionImpl {
     // -------------------------------------------------------------------------
     childBase() {
         return {
-            model: this.currentModel,
-            thinkingLevel: this.currentThinking,
-            activeTools: this.activeNames,
-            system: this.systemInput,
+            model: this.settings.model,
+            thinkingLevel: this.settings.thinking,
+            activeTools: this.settings.activeNamesRef(),
+            system: this.settings.systemInput,
         };
     }
     autoClassifier() {

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

@@ -0,0 +1,91 @@
+/**
+ * 子 Agent 任务注册表（docs/wave5-plan.md §7.3–§7.6，D13、D23–D24）。[W5-G]
+ *
+ * 每个根会话一份（按会话 id 登记；compose-agents.ts 的扩展在会话构造时建，SDK / 测试直接构造的
+ * 会话在首次 task 时以缺省环境懒建）。职责：
+ * - 解析类型（catalog）→ 选 runner：ama 子会话（session-subagent.ts 的工厂）或外部 runner（W5-E /
+ *   宿主，经 `env.runners`）；同一 `task(agent=…)` 入口；
+ * - 并发池（`subagents.maxConcurrent`，缺省 4）+ 排队上限（`maxPending`，缺省 16，超出报错不要重试）；
+ * - 前台（等结果）/ 后台（立即返回 taskId，完成后 `<task-notification>` 走父会话 followUp 队列）；
+ * - `taskId` 续聊：句柄保留 16 个（LRU，释放的只是内存，JSONL 永在），被释放或 resume 后按会话
+ *   文件 / 外部会话 id 重新接上；
+ * - 结果 > 50 KB 保留头尾并全文落 `outputs/`；轮数耗尽加说明；worktree 隔离；
+ * - 事件 `subagent_start / update / end`；父会话 `custom{ama.task}` 记任务快照（带 `status`），
+ *   resume 时据此重建（未完成标 `interrupted`）。
+ */
+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 { 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";
+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 AmaRunnerFactory = (spec: AmaRunnerSpec) => SubagentRunner;
+export interface SubagentEnvironment {
+    catalog: AgentCatalog;
+    maxConcurrent?: number;
+    maxPending?: number;
+    retain?: number;
+    modelConfig?: AgentModelConfig;
+    /** 外部 / 宿主 runner（W5-E `ProcessRunner`、HostApi.runners）；没有返回 undefined。 */
+    runners?(agent: AgentDefinition): SubagentRunner | undefined;
+    now?(): number;
+}
+/** 注册表需要的父会话能力（`SessionCore`；followUp 为 AgentSessionImpl 的公开方法）。 */
+export type RegistryHost = Pick<SessionCore, "manager" | "cwd" | "emit" | "appendEntry" | "outputDir" | "log" | "options"> & {
+    followUp?(text: string, options?: {
+        origin?: string;
+    }): Promise<unknown>;
+    waitForIdle?(): Promise<void>;
+};
+/** RPC `get_tasks` / `/tasks`：会话 id → 注册表视图（没有任务时 undefined）。 */
+export declare function taskRegistryView(sessionId: string): TaskRegistryView | undefined;
+/** RPC `get_agents` / `/agents`：会话可用的类型（没有 task 工具、注册表未装配时为空）。 */
+export declare function sessionAgents(sessionId: string): AgentInfo[];
+export declare function registryOf(sessionId: string): SubagentRegistry | undefined;
+/** 取会话的注册表；没有就以 `env`（缺省只有内置类型）新建并登记。 */
+export declare function subagentRegistryFor(host: RegistryHost, env?: SubagentEnvironment): SubagentRegistry;
+export declare class SubagentRegistry implements TaskControl {
+    private readonly host;
+    private readonly env;
+    readonly catalog: AgentCatalog;
+    private readonly pool;
+    private readonly tasks;
+    private readonly retained;
+    private seq;
+    private disposed;
+    private delivery;
+    constructor(host: RegistryHost, env: SubagentEnvironment);
+    private now;
+    list(): readonly TaskInfo[];
+    get(taskId: string): TaskInfo | undefined;
+    stats(): SessionTaskStats | undefined;
+    /** 运行中任务的已有输出（`task_ctl output`）；结束后为最终文本。 */
+    output(taskId: string): string | undefined;
+    /** 等任务结束或超时；超时返回 undefined。 */
+    wait(taskId: string, timeoutMs: number): Promise<SubagentResult | undefined>;
+    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;
+    private persist;
+    private touch;
+    /** 句柄 LRU：超出上限时释放最久未用、空闲的子会话（JSONL 仍在，续聊时重开）。 */
+    private retain;
+    /** 会话关闭：停止运行中的任务、释放保留的子会话。 */
+    dispose(): void;
+}