@aipack-ai/multi-agent 1.1.7 → 1.1.8

package/dist/index.js

@@ -78,7 +78,50 @@ function createEmptyUsage() {
   return { input: 0, output: 0, total: 0 };
 }
 
+// ../agent/core/tokens.ts
+function estimateTextTokens(text) {
+  if (!text) return 0;
+  return Math.ceil(text.length / 4);
+}
+function estimateMessageTokens(message) {
+  const content = message.content;
+  if (typeof content === "string") return estimateTextTokens(content);
+  try {
+    return Math.ceil(JSON.stringify(content ?? []).length / 4);
+  } catch {
+    return 0;
+  }
+}
+
+// ../agent/core/errors.ts
+var AgentErrorCategory = {
+  RETRYABLE: "retryable",
+  TIMEOUT: "timeout",
+  AUTH: "auth",
+  CONTEXT_OVERFLOW: "context-overflow",
+  RATE_LIMIT: "rate-limit",
+  INVALID_REQUEST: "invalid-request",
+  UNKNOWN: "unknown"
+};
+
 // ../agent/core/tapable.ts
+var tapFailurePolicy = "log";
+var tapErrorHandler;
+function setTapErrorHandler(handler) {
+  tapErrorHandler = handler;
+}
+function handleTapError(hook, tap, err) {
+  if (tapErrorHandler) {
+    try {
+      tapErrorHandler({ hook, tap: tap.name, error: err });
+    } catch {
+    }
+  }
+  if (tapFailurePolicy === "throw") throw err;
+  if (tapFailurePolicy === "log") {
+    console.warn(`[aipack] extension tap "${tap.name}" on hook "${hook}" \u5931\u8D25:`, err);
+  }
+}
 var AsyncSeriesHook = class {
   constructor(name) {
     this.name = name;
@@ -94,6 +137,7 @@ var AsyncSeriesHook = class {
       try {
         await tap.fn(...args);
       } catch (err) {
+        handleTapError(this.name, tap, err);
       }
     }
   }
@@ -120,6 +164,7 @@ var AsyncSeriesWaterfallHook = class {
       try {
         current = await tap.fn(current, ...rest);
       } catch (err) {
+        handleTapError(this.name, tap, err);
       }
     }
     return current;
@@ -606,15 +651,6 @@ function resourcesToMessages(resources) {
 import { Type } from "@sinclair/typebox";
 
 // ../agent/ai/errors.ts
-var AgentErrorCategory = {
-  RETRYABLE: "retryable",
-  TIMEOUT: "timeout",
-  AUTH: "auth",
-  CONTEXT_OVERFLOW: "context-overflow",
-  RATE_LIMIT: "rate-limit",
-  INVALID_REQUEST: "invalid-request",
-  UNKNOWN: "unknown"
-};
 var RETRYABLE_CATEGORIES = /* @__PURE__ */ new Set([
   AgentErrorCategory.RETRYABLE,
   AgentErrorCategory.RATE_LIMIT
@@ -802,62 +838,7 @@ function isContextOverflow(message, contextWindow) {
   return false;
 }
 
-// ../agent/transformer/index.ts
-function ensureToolPairing(messages) {
-  const toolCallIds = /* @__PURE__ */ new Set();
-  const toolResultIds = /* @__PURE__ */ new Set();
-  for (const msg of messages) {
-    if (msg.role === "assistant") {
-      const content = msg.content;
-      if (Array.isArray(content)) {
-        for (const tc of extractToolCalls(content)) {
-          toolCallIds.add(tc.id);
-        }
-      }
-    }
-    if (msg.role === "toolResult") {
-      toolResultIds.add(msg.toolCallId);
-    }
-  }
-  const orphanedCalls = /* @__PURE__ */ new Set();
-  const orphanedResults = /* @__PURE__ */ new Set();
-  for (const id of toolCallIds) {
-    if (!toolResultIds.has(id)) orphanedCalls.add(id);
-  }
-  for (const id of toolResultIds) {
-    if (!toolCallIds.has(id)) orphanedResults.add(id);
-  }
-  if (orphanedCalls.size === 0 && orphanedResults.size === 0) {
-    return messages;
-  }
-  const result = [];
-  for (const msg of messages) {
-    if (msg.role === "assistant") {
-      const content = msg.content;
-      if (Array.isArray(content)) {
-        const filteredContent = content.filter((block) => {
-          if (block.type === "toolCall") {
-            return !orphanedCalls.has(block.id);
-          }
-          return true;
-        });
-        if (filteredContent.length === 0 && content.length > 0) continue;
-        result.push({ ...msg, content: filteredContent });
-      } else {
-        result.push(msg);
-      }
-    } else if (msg.role === "toolResult") {
-      if (!orphanedResults.has(msg.toolCallId)) {
-        result.push(msg);
-      }
-    } else {
-      result.push(msg);
-    }
-  }
-  return result;
-}
-
-// ../agent/runtime/index.ts
+// ../agent/runtime/shared.ts
 import { randomUUID } from "crypto";
 function newTraceId() {
   return `${Date.now().toString(36)}-${randomUUID()}`;
@@ -929,19 +910,25 @@ function buildImageContent(media) {
   }
   return { type: "image", mimeType: "image/url", data: media };
 }
-var OVERFLOW_RECOVERY_LIMIT = 2;
-function estimateMessageTokens(message) {
-  const content = message.content;
-  if (typeof content === "string") return Math.ceil(content.length / 4);
-  try {
-    return Math.ceil(JSON.stringify(content ?? []).length / 4);
-  } catch {
-    return 0;
+function buildUserMessage(request) {
+  if (request.media && request.media.length > 0) {
+    const blocks = [
+      createTextContent(request.message),
+      ...request.media.filter(Boolean).map(buildImageContent)
+    ];
+    return {
+      role: "user",
+      content: blocks,
+      timestamp: Date.now()
+    };
   }
+  return {
+    role: "user",
+    content: request.message,
+    timestamp: Date.now()
+  };
 }
-function estimateTextTokens(text) {
-  return Math.ceil(text.length / 4);
-}
+var OVERFLOW_RECOVERY_LIMIT = 2;
 var COMPACTION_SUMMARY_BUDGET_RATIO = 0.6;
 var COMPACTION_LINE_CLAMP = 4e3;
 var DEFAULT_COMPACTION_PROMPT = [
@@ -992,150 +979,146 @@ function messageToSummaryLine(msg) {
     }
   }
 }
-var AgentRuntime = class _AgentRuntime {
-  _config;
-  _extensions;
-  _hooks;
-  /** 上下文转换器列表，按数组顺序链式执行（上一个输出作为下一个输入） */
-  _transformers;
-  _model;
-  _streamFn;
-  _systemPrompt;
-  _thinkingLevel;
-  _globalTools = /* @__PURE__ */ new Map();
-  /** 多会话状态表：key = sessionKey。模型/工具/扩展/转换器等资源跨会话共享 */
-  _sessions;
-  /** 默认会话 key（常量 'default'；请求未指定 sessionKey 时路由到此会话） */
-  _sessionKey;
-  /** 内存会话状态表 LRU 上限 */
-  _maxSessions;
-  _sessionStorage;
-  /** Extension 应用时的上下文（shared Map 供 ToolCallContext 引用） */
-  _extensionContext;
-  _maxTurns;
-  _toolTimeoutMs;
-  _parallelToolCalls;
-  _contextBudgetRatio;
-  /** 内置摘要压缩配置（未配置 = 保持旧行为，仅硬截断兜底） */
-  _compaction;
-  _telemetry;
-  /** 框架级工具权限策略（未配置 → 放行，向后兼容） */
-  _permissionPolicy;
-  /** 审批管理器（pending 决策挂起等待外部批准；未配置 → pending 视为 deny） */
-  _approvals;
-  /** 审批等待超时（毫秒） */
-  _approvalTimeoutMs;
-  /** traceId 生成器（测试可注入确定性 id） */
-  _traceIdGenerator;
-  constructor(options) {
-    this._config = options.config ?? {};
-    this._extensions = new ExtensionManager();
-    this._hooks = this._extensions.getHooks();
-    this._transformers = [...options.transformers ?? []];
-    this._model = options.model ?? {
-      id: "unknown",
-      name: "unknown",
-      provider: "unknown",
-      contextWindow: 128e3,
-      maxTokens: 8192,
-      reasoning: false
-    };
-    this._streamFn = options.streamFn ?? (async function* () {
-      throw new Error("streamFn \u672A\u8BBE\u7F6E\uFF0C\u8BF7\u901A\u8FC7 setStreamFn() \u6216 RuntimeOptions.streamFn \u63D0\u4F9B");
-    });
-    this._systemPrompt = options.systemPrompt ?? "";
-    this._thinkingLevel = options.thinkingLevel ?? "off";
-    this._sessionStorage = options.sessionStorage;
-    this._maxTurns = options.maxTurns ?? 50;
-    this._toolTimeoutMs = options.toolTimeoutMs ?? 12e4;
-    this._parallelToolCalls = options.parallelToolCalls ?? true;
-    this._contextBudgetRatio = options.contextBudgetRatio ?? 0.8;
-    this._compaction = options.compaction;
-    this._telemetry = options.telemetry;
-    this._permissionPolicy = options.permissionPolicy;
-    this._approvals = options.approvals;
-    this._approvalTimeoutMs = options.approvalTimeoutMs ?? 3e5;
-    this._traceIdGenerator = options.traceIdGenerator;
-    if (options.tools) {
-      for (const tool of options.tools) {
-        this._globalTools.set(tool.name, tool);
+function buildResult(compilation) {
+  const messages = compilation.messages;
+  let content = "";
+  let stopReason = "completed";
+  let error;
+  const toolsUsed = [];
+  const usage = {};
+  for (const msg of messages) {
+    if (msg.role === "assistant") {
+      const assistant = msg;
+      content = extractText(assistant.content);
+      stopReason = assistant.stopReason ?? "completed";
+      error = assistant.errorMessage;
+      if (assistant.usage) {
+        usage.input = (usage.input ?? 0) + assistant.usage.input;
+        usage.output = (usage.output ?? 0) + assistant.usage.output;
+        usage.total = (usage.total ?? 0) + assistant.usage.total;
+        if (assistant.usage.cacheRead) usage.cacheRead = (usage.cacheRead ?? 0) + assistant.usage.cacheRead;
+        if (assistant.usage.cacheWrite) usage.cacheWrite = (usage.cacheWrite ?? 0) + assistant.usage.cacheWrite;
       }
     }
-    this._sessionKey = "default";
-    this._maxSessions = options.maxSessions ?? DEFAULT_MAX_SESSIONS;
-    this._sessions = /* @__PURE__ */ new Map([[this._sessionKey, createSessionState()]]);
-  }
-  // ─── 静态工厂 ───────────────────────────────────────────────────
-  static create(options = {}) {
-    const runtime = new _AgentRuntime(options);
-    if (options.extensions) {
-      runtime._extensions.registerAll(options.extensions);
+    if (msg.role === "toolResult") {
+      const toolMsg = msg;
+      if (!toolsUsed.includes(toolMsg.toolName)) {
+        toolsUsed.push(toolMsg.toolName);
+      }
     }
-    const ctx = {
-      config: runtime._config,
-      workspace: options.workspace ?? process.cwd(),
-      sessionKey: runtime._sessionKey,
-      shared: /* @__PURE__ */ new Map(),
-      runtime
-    };
-    runtime._extensionContext = ctx;
-    runtime._extensions.applyAll(ctx);
-    return runtime;
   }
-  // ─── Runtime 接口实现 ───────────────────────────────────────────
-  get config() {
-    return this._config;
+  const resources = messagesToResources(messages);
+  const builder = new ResultBuilder().content(content).toolsUsed(toolsUsed).usage(usage).stopReason(stopReason).error(error).resources(resources).metadata("traceId", compilation.traceId);
+  if (compilation.terminateReason) {
+    builder.stopReason("terminated").metadata("terminateReason", compilation.terminateReason);
   }
-  get extensions() {
-    return this._extensions;
+  if (compilation.maxTurnsExhausted) {
+    builder.stopReason("max_turns").metadata("maxTurns", true);
   }
-  get hooks() {
-    return this._hooks;
+  return builder.build();
+}
+function streamEventToChunk(event) {
+  switch (event.type) {
+    case "text_delta":
+      return { type: "text", content: event.delta };
+    case "thinking_delta":
+      return { type: "thinking", content: event.delta };
+    case "error":
+      return {
+        type: "error",
+        content: event.message.errorMessage || "\u6A21\u578B\u8C03\u7528\u51FA\u9519"
+      };
+    default:
+      return null;
   }
-  // ─── 工具/模型/流管理 ───────────────────────────────────────────
-  registerTool(tool) {
-    if (this._globalTools.has(tool.name)) {
-      console.warn(`[Runtime] \u5DE5\u5177 "${tool.name}" \u5DF2\u5B58\u5728\uFF0C\u5C06\u88AB\u8986\u76D6`);
-    }
-    this._globalTools.set(tool.name, tool);
-    return this;
+}
+
+// ../agent/runtime/session-store.ts
+var SessionStore = class {
+  /** 多会话状态表：key = sessionKey。模型/工具/扩展/转换器等资源跨会话共享 */
+  _sessions;
+  /** 内存会话状态表 LRU 上限 */
+  _maxSessions;
+  /** 默认会话 key（常量 'default'；请求未指定 sessionKey 时路由到此会话） */
+  defaultKey;
+  constructor(defaultKey, maxSessions = DEFAULT_MAX_SESSIONS) {
+    this.defaultKey = defaultKey;
+    this._maxSessions = maxSessions;
+    this._sessions = /* @__PURE__ */ new Map();
+    this._sessions.set(defaultKey, createSessionState());
   }
-  registerTools(tools) {
-    for (const tool of tools) {
-      this.registerTool(tool);
+  /**
+   * 获取（懒创建）会话状态。同一 Runtime 下不同 sessionKey 的消息历史、
+   * 串行队列、abort 控制相互独立；共享模型/工具/扩展/转换器。
+   * 超过 maxSessions 时淘汰最久未用的非活动会话（仅清内存态，不删存储）。
+   */
+  ensure(key) {
+    let session = this._sessions.get(key);
+    if (session) {
+      this._sessions.delete(key);
+      this._sessions.set(key, session);
+      return session;
     }
-    return this;
-  }
-  unregisterTool(name) {
-    return this._globalTools.delete(name);
-  }
-  setModel(model) {
-    this._model = model;
-    return this;
+    session = createSessionState();
+    this._sessions.set(key, session);
+    this.evictIdleSessions();
+    return session;
   }
-  setSystemPrompt(prompt) {
-    this._systemPrompt = prompt;
-    return this;
+  /** 只读访问（不创建、不刷新 LRU；会话不存在返回 undefined） */
+  peek(key) {
+    return this._sessions.get(key);
   }
-  setThinkingLevel(level) {
-    this._thinkingLevel = level;
-    return this;
+  /** LRU 淘汰：仅淘汰非活动（未运行、未排队）的最久未用会话 */
+  evictIdleSessions() {
+    if (this._sessions.size <= this._maxSessions) return;
+    for (const [key, session] of this._sessions) {
+      if (this._sessions.size <= this._maxSessions) break;
+      if (session.isStreaming || session.lockHeld) continue;
+      if (session.idleResolvers.length > 0) {
+        const resolvers = session.idleResolvers.splice(0);
+        for (const resolve of resolvers) resolve();
+      }
+      this._sessions.delete(key);
+    }
   }
-  setStreamFn(fn) {
-    this._streamFn = fn;
-    return this;
+  /** 当前活跃的会话 key 列表（含默认会话） */
+  keys() {
+    return Array.from(this._sessions.keys());
   }
-  registerExtension(extension) {
-    this._extensions.register(extension);
-    return this;
+  /** 某会话是否存在（内存中） */
+  has(key) {
+    return this._sessions.has(key);
   }
-  useTransformer(transformer) {
-    this._transformers.push(transformer);
-    return this;
+  /**
+   * 获取同一会话的执行锁：返回 release 函数，调用后释放。
+   * 同一 sessionKey 的 run/stream 会串行执行，避免消息数组交错、
+   * abortController 互相覆盖、hydrate 竞态。
+   */
+  async acquire(session) {
+    let release;
+    const prev = session.queue;
+    session.queue = new Promise((resolve) => {
+      release = () => resolve();
+    });
+    await prev;
+    session.lockHeld = true;
+    return () => {
+      session.lockHeld = false;
+      release();
+    };
   }
-  /** 获取指定会话的消息列表（默认会话；会话不存在返回空数组） */
-  getMessages(sessionKey) {
-    const session = this._sessions.get(sessionKey ?? this._sessionKey);
+  /** 标记会话空闲并唤醒所有 waitForIdle 等待者 */
+  markIdle(session) {
+    session.isStreaming = false;
+    session.abortController = null;
+    if (session.idleResolvers.length > 0) {
+      const resolvers = session.idleResolvers.splice(0);
+      for (const resolve of resolvers) resolve();
+    }
+  }
+  /** 指定会话的消息列表深拷贝（避免外部直接修改会话内部状态；不存在返回空数组） */
+  getMessagesCopy(key) {
+    const session = this._sessions.get(key);
     if (!session) return [];
     const messages = session.messages;
     try {
@@ -1144,372 +1127,253 @@ var AgentRuntime = class _AgentRuntime {
       return JSON.parse(JSON.stringify(messages));
     }
   }
-  // ─── 核心运行逻辑 ───────────────────────────────────────────────
-  /** 解析请求路由的会话 key：request.sessionKey ?? 默认会话 key */
-  resolveSessionKey(request) {
-    return request.sessionKey ?? this._sessionKey;
+  /**
+   * 指定会话消息的只读视图（高频轮询用）：仅浅拷贝数组（O(n) 引用，
+   * 不做 structuredClone 深拷贝），消息对象与内部共享——调用方不得修改，
+   * 需要可变副本时用 getMessagesCopy。
+   */
+  peekMessages(key) {
+    return this._sessions.get(key)?.messages.slice() ?? [];
+  }
+  /** 等待指定会话空闲（基于 promise，无轮询；会话不存在或非运行中直接返回） */
+  async waitForIdle(key, timeoutMs) {
+    const session = this._sessions.get(key);
+    if (!session || !session.isStreaming) return;
+    if (timeoutMs === void 0) {
+      await new Promise((resolve) => {
+        session.idleResolvers.push(resolve);
+      });
+      return;
+    }
+    await new Promise((resolve, reject) => {
+      const resolver = () => {
+        clearTimeout(timer);
+        resolve();
+      };
+      const timer = setTimeout(() => {
+        const i = session.idleResolvers.indexOf(resolver);
+        if (i >= 0) session.idleResolvers.splice(i, 1);
+        reject(new Error(
+          `[Runtime] waitForIdle \u8D85\u65F6\uFF08${timeoutMs}ms\uFF09: ${key}`
+        ));
+      }, timeoutMs);
+      session.idleResolvers.push(resolver);
+    });
+  }
+  /** 清除指定会话消息（仅内存；下次 run 会从存储恢复） */
+  clearMessages(key) {
+    const session = this._sessions.get(key);
+    if (!session) return;
+    session.messages = [];
+    session.hydrated = false;
   }
   /**
-   * 获取（懒创建）会话状态。同一 Runtime 下不同 sessionKey 的消息历史、
-   * 串行队列、abort 控制相互独立；共享模型/工具/扩展/转换器。
-   * 超过 _maxSessions 时淘汰最久未用的非活动会话（仅清内存态，不删存储）。
+   * 删除指定会话（仅内存态）：等待在途任务完成后移除，返回被移除的会话。
    */
-  getSession(key) {
-    let session = this._sessions.get(key);
+  async remove(key) {
+    const session = this._sessions.get(key);
     if (session) {
+      await session.queue;
       this._sessions.delete(key);
-      this._sessions.set(key, session);
-      return session;
     }
-    session = createSessionState();
-    this._sessions.set(key, session);
-    this.evictIdleSessions();
     return session;
   }
-  /** LRU 淘汰：仅淘汰非活动（未运行、未排队）的最久未用会话 */
-  evictIdleSessions() {
-    if (this._sessions.size <= this._maxSessions) return;
-    for (const [key, session] of this._sessions) {
-      if (this._sessions.size <= this._maxSessions) break;
-      if (session.isStreaming || session.lockHeld) continue;
-      this._sessions.delete(key);
+  /** 关闭用：等待所有会话的在途任务完成后清空状态表 */
+  async drainAndClear() {
+    await Promise.allSettled(Array.from(this._sessions.values(), (s) => s.queue));
+    for (const session of this._sessions.values()) {
+      session.messages = [];
+      session.hydrated = false;
     }
+    this._sessions.clear();
   }
-  /** 当前活跃的会话 key 列表（含默认会话） */
-  getSessionKeys() {
-    return Array.from(this._sessions.keys());
+};
+
+// ../agent/runtime/session-persistence.ts
+var SessionPersistence = class {
+  constructor(_storage, _defaultModel, _store) {
+    this._storage = _storage;
+    this._defaultModel = _defaultModel;
+    this._store = _store;
+  }
+  _storage;
+  _defaultModel;
+  _store;
+  get storage() {
+    return this._storage;
   }
-  /** 某会话是否存在（内存中） */
-  hasSession(sessionKey) {
-    return this._sessions.has(sessionKey);
+  /** 从存储懒加载会话（串行化后无竞态，每个会话仅恢复一次） */
+  async hydrate(sessionKey, session) {
+    if (!this._storage) return;
+    if (session.hydrated) return;
+    session.hydrated = true;
+    const stored = await this._storage.load(sessionKey);
+    if (!stored) return;
+    session.messages = stored.messages;
+    session.createdAt = stored.createdAt;
   }
-  async run(request) {
-    const validation = validateRequest(request);
-    if (!validation.valid) {
-      const invalidResult = new ResultBuilder().error(`\u8BF7\u6C42\u6821\u9A8C\u5931\u8D25: ${validation.errors.join("; ")}`).build();
-      await this.emitTelemetry("onRunEnd", {
-        traceId: this.newTraceId(),
-        sessionKey: this.resolveSessionKey(request),
-        request,
-        durationMs: 0,
-        activeMs: 0,
-        queuedMs: 0,
-        turnCount: 0,
-        result: invalidResult,
-        success: false,
-        errorClass: "validation",
-        tokens: { input: 0, output: 0 }
-      });
-      return invalidResult;
-    }
-    const finalRequest = normalizeRequest(request);
-    const sessionKey = this.resolveSessionKey(finalRequest);
-    const traceId = this.newTraceId();
-    const queuedAt = Date.now();
-    await this.emitTelemetry("onRunStart", {
-      traceId,
-      sessionKey,
-      request: finalRequest,
-      queuedAt
-    });
-    const session = this.getSession(sessionKey);
-    const release = await this.acquire(session);
-    const queuedMs = Date.now() - queuedAt;
+  /** 整体保存指定会话（ephemeral 跳过；失败不影响运行结果） */
+  async persist(sessionKey, session) {
+    if (!this._storage) return;
+    const stored = {
+      key: sessionKey,
+      version: SESSION_VERSION,
+      messages: session.messages,
+      model: this.deriveModel(session.messages),
+      usage: this.sumUsage(session.messages),
+      createdAt: session.createdAt,
+      updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    await this._storage.save(sessionKey, stored);
+  }
+  /**
+   * 实时持久化指定会话：每轮 assistant 回复/工具结果完成后调用，
+   * 让运行中的会话随时可被持久化数据观测到。ephemeral 跳过；
+   * 存储失败仅告警，不影响对话循环继续。
+   */
+  async persistSafe(request, sessionKey) {
+    if (request.ephemeral || !this._storage) return;
     try {
-      return await this.runWithStorageLock(
-        finalRequest,
-        sessionKey,
-        () => this._run(finalRequest, sessionKey, session, traceId, queuedMs)
-      );
-    } finally {
-      release();
+      const session = this._store.peek(sessionKey);
+      if (!session) return;
+      await this.persist(sessionKey, session);
+    } catch (err) {
+      console.warn("[Runtime] \u4F1A\u8BDD\u6301\u4E45\u5316\u5931\u8D25:", err?.message);
     }
   }
-  async *stream(request) {
-    const validation = validateRequest(request);
-    if (!validation.valid) {
-      const message = `\u8BF7\u6C42\u6821\u9A8C\u5931\u8D25: ${validation.errors.join("; ")}`;
-      await this.emitTelemetry("onRunEnd", {
-        traceId: this.newTraceId(),
-        sessionKey: this.resolveSessionKey(request),
-        request,
-        durationMs: 0,
-        activeMs: 0,
-        queuedMs: 0,
-        turnCount: 0,
-        result: new ResultBuilder().error(message).build(),
-        success: false,
-        errorClass: "validation",
-        tokens: { input: 0, output: 0 }
-      });
-      yield { type: "error", content: message };
-      yield { type: "done" };
-      return;
+  /** 从消息中推导最后使用的模型 */
+  deriveModel(messages) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+      const msg = messages[i];
+      if (msg.role === "assistant" && msg.model) {
+        return {
+          provider: msg.provider ?? this._defaultModel().provider,
+          modelId: msg.model
+        };
+      }
     }
-    const finalRequest = normalizeRequest(request);
-    const sessionKey = this.resolveSessionKey(finalRequest);
-    const traceId = this.newTraceId();
-    const queuedAt = Date.now();
-    await this.emitTelemetry("onRunStart", {
-      traceId,
-      sessionKey,
-      request: finalRequest,
-      queuedAt
-    });
-    const session = this.getSession(sessionKey);
-    const release = await this.acquire(session);
-    const queuedMs = Date.now() - queuedAt;
-    try {
-      yield* this.streamWithStorageLock(
-        finalRequest,
-        sessionKey,
-        () => this._stream(finalRequest, sessionKey, session, traceId, queuedMs)
-      );
-    } finally {
-      release();
+    return null;
+  }
+  /** 汇总所有 assistant 消息的 token 用量（含 cache） */
+  sumUsage(messages) {
+    const usage = createEmptyUsage();
+    for (const msg of messages) {
+      if (msg.role === "assistant") {
+        const u = msg.usage;
+        if (u) {
+          usage.input += u.input;
+          usage.output += u.output;
+          usage.total += u.total;
+          usage.cacheRead = (usage.cacheRead ?? 0) + (u.cacheRead ?? 0);
+          usage.cacheWrite = (usage.cacheWrite ?? 0) + (u.cacheWrite ?? 0);
+          usage.reasoning = (usage.reasoning ?? 0) + (u.reasoning ?? 0);
+        }
+      }
     }
+    return usage;
   }
   /**
    * 非 ephemeral 请求在"读(load)-改(run)-写(save)"全程持有存储级锁，
    * 防止多进程并发写同一会话导致 last-write-wins 丢消息。
    * ephemeral / 无锁支持 / 无存储时直接执行。
    */
-  async runWithStorageLock(request, sessionKey, fn) {
-    const storage = this._sessionStorage;
-    if (request.ephemeral || !storage?.withLock) return fn();
-    return storage.withLock(sessionKey, fn);
+  async withStorageLock(request, sessionKey, fn) {
+    if (request.ephemeral || !this._storage?.withLock) return fn();
+    return this._storage.withLock(sessionKey, fn);
   }
   /** 流式版本：无法用回调包住生成器，改用手动锁（acquire/release） */
   async *streamWithStorageLock(request, sessionKey, gen) {
-    const storage = this._sessionStorage;
-    if (request.ephemeral || !storage?.acquireLock) {
+    if (request.ephemeral || !this._storage?.acquireLock) {
       yield* gen();
       return;
     }
-    const lock = await storage.acquireLock(sessionKey);
+    const lock = await this._storage.acquireLock(sessionKey);
     try {
       yield* gen();
     } finally {
       await lock.release();
     }
   }
-  async _run(request, sessionKey, session, traceId, queuedMs) {
-    const activeStartedAt = Date.now();
-    await this._hooks.beforeInitialize.promise(request);
-    await this._hooks.afterInitialize.promise(request);
-    const finalRequest = await this._hooks.beforeRun.promise(request);
-    if (!finalRequest.ephemeral) {
-      await this.hydrateSession(sessionKey, session);
-    }
-    const compilation = this.createCompilation(finalRequest, sessionKey, session, traceId);
-    compilation.messages.push(this.buildUserMessage(finalRequest));
+};
+
+// ../agent/runtime/telemetry.ts
+var RuntimeTelemetry = class {
+  constructor(_telemetry, _traceIdGenerator) {
+    this._telemetry = _telemetry;
+    this._traceIdGenerator = _traceIdGenerator;
+  }
+  _telemetry;
+  _traceIdGenerator;
+  /** traceId 生成：优先用注入的生成器（测试可确定性） */
+  newTraceId() {
+    return this._traceIdGenerator ? this._traceIdGenerator() : newTraceId();
+  }
+  /**
+   * 触发遥测回调。全可选、失败不阻断主流程。
+   */
+  async emit(event, info) {
+    const fn = this._telemetry?.[event];
+    if (!fn) return;
     try {
-      await this.runLoop(compilation, finalRequest, session);
-      const result = this.buildResult(compilation);
-      await this._hooks.beforeEmit.promise(result);
-      await this._hooks.afterEmit.promise(result);
-      await this._hooks.done.promise(result, finalRequest);
-      compilation.completed = true;
-      await this.emitRunEnd(finalRequest, sessionKey, compilation, result, queuedMs, activeStartedAt);
-      return result;
+      await Promise.resolve(fn(info));
     } catch (err) {
-      const error = err;
-      if (error?.name !== "AbortError") {
-        console.error("[Runtime] \u8FD0\u884C\u5931\u8D25:", error?.stack ?? error);
-      }
-      await this._hooks.failed.promise(error, finalRequest);
-      const result = new ResultBuilder().error(error.message).build();
-      await this.emitRunEnd(finalRequest, sessionKey, compilation, result, queuedMs, activeStartedAt);
-      return result;
-    } finally {
-      await this.persistSessionSafe(finalRequest, sessionKey);
-    }
-  }
-  async *_stream(request, sessionKey, session, traceId, queuedMs) {
-    const activeStartedAt = Date.now();
-    await this._hooks.beforeInitialize.promise(request);
-    await this._hooks.afterInitialize.promise(request);
-    const finalRequest = await this._hooks.beforeRun.promise(request);
-    if (!finalRequest.ephemeral) {
-      await this.hydrateSession(sessionKey, session);
-    }
-    const compilation = this.createCompilation(finalRequest, sessionKey, session, traceId);
-    compilation.messages.push(this.buildUserMessage(finalRequest));
-    try {
-      for await (const chunk of this.runLoopStream(compilation, finalRequest, session)) {
-        yield chunk;
-      }
-      const result = this.buildResult(compilation);
-      await this._hooks.beforeEmit.promise(result);
-      await this._hooks.afterEmit.promise(result);
-      await this._hooks.done.promise(result, finalRequest);
-      yield { type: "done", result };
-      await this.emitRunEnd(finalRequest, sessionKey, compilation, result, queuedMs, activeStartedAt);
-    } catch (err) {
-      const error = err;
-      if (error?.name !== "AbortError") {
-        console.error("[Runtime] \u6D41\u5F0F\u8FD0\u884C\u5931\u8D25:", error?.stack ?? error);
-      }
-      await this._hooks.failed.promise(error, finalRequest);
-      const result = new ResultBuilder().error(error.message).build();
-      yield { type: "error", content: error.message };
-      yield { type: "done", result };
-      await this.emitRunEnd(finalRequest, sessionKey, compilation, result, queuedMs, activeStartedAt);
-    } finally {
-      await this.persistSessionSafe(finalRequest, sessionKey);
-    }
-  }
-  createCompilation(request, sessionKey, session, traceId) {
-    return {
-      request,
-      graph: createTaskGraph(),
-      resources: [],
-      messages: (session ?? this.getSession(sessionKey ?? this._sessionKey)).messages,
-      completed: false,
-      traceId: traceId ?? this.newTraceId()
-    };
-  }
-  async close() {
-    await Promise.allSettled(Array.from(this._sessions.values(), (s) => s.queue));
-    for (const session of this._sessions.values()) {
-      session.messages = [];
-      session.hydrated = false;
+      console.warn(`[aipack] telemetry "${String(event)}" \u4E0A\u62A5\u5931\u8D25:`, err);
     }
-    this._sessions.clear();
-    this._extensions.clear();
-    this._transformers = [];
   }
-  // ─── 对话循环（同步） ───────────────────────────────────────────
-  async runLoop(compilation, request, session) {
-    session.isStreaming = true;
-    session.abortController = new AbortController();
-    const sessionKey = this.resolveSessionKey(request);
-    try {
-      let maxTurns = this._maxTurns;
-      let turnCount = 0;
-      while (maxTurns-- > 0) {
-        turnCount += 1;
-        await this.transformMessages(compilation, sessionKey);
-        await this.maybeCompactByThreshold(
-          compilation,
-          sessionKey,
-          session.abortController.signal
-        );
-        const assistantMessage = await this.streamModel(
-          compilation,
-          session.abortController.signal,
-          sessionKey
-        );
-        compilation.messages.push(assistantMessage);
-        await this.persistSessionSafe(request, sessionKey);
-        const toolCalls = extractToolCalls(assistantMessage.content);
-        if (toolCalls.length === 0) {
-          break;
-        }
-        const outcome = await this.executeToolCalls(
-          compilation,
-          toolCalls,
-          session.abortController.signal
-        );
-        await this.persistSessionSafe(request, sessionKey);
-        if (outcome.terminate) {
-          compilation.terminateReason = outcome.terminateReason ?? "terminated";
-          break;
-        }
-      }
-      if (maxTurns < 0) compilation.maxTurnsExhausted = true;
-      compilation.turnCount = turnCount;
-    } finally {
-      this.markIdle(session);
-    }
+  /** 组装并上报 run 级完成事件（run/stream 内部统一调用） */
+  async emitRunEnd(request, sessionKey, compilation, result, queuedMs, activeStartedAt, defaultModelId) {
+    const activeMs = Date.now() - activeStartedAt;
+    await this.emit("onRunEnd", {
+      traceId: compilation.traceId,
+      sessionKey,
+      // 请求未显式指定 model 时补实际模型（模型排行按 run 级 requests 统计，缺省会落入 'unknown'）
+      request: request.model ? request : { ...request, model: defaultModelId },
+      durationMs: activeMs + queuedMs,
+      activeMs,
+      queuedMs,
+      turnCount: compilation.turnCount ?? 0,
+      result,
+      success: result.success,
+      errorClass: this.runErrorClass(compilation),
+      tokens: {
+        input: result.usage.input ?? 0,
+        output: result.usage.output ?? 0,
+        cacheRead: result.usage.cacheRead,
+        cacheWrite: result.usage.cacheWrite
+      },
+      ttftMs: compilation.ttftMs
+    });
   }
-  // ─── 对话循环（流式） ───────────────────────────────────────────
-  async *runLoopStream(compilation, request, session) {
-    session.isStreaming = true;
-    session.abortController = new AbortController();
-    const sessionKey = this.resolveSessionKey(request);
-    try {
-      let maxTurns = this._maxTurns;
-      let turnCount = 0;
-      while (maxTurns-- > 0) {
-        turnCount += 1;
-        await this.transformMessages(compilation, sessionKey);
-        await this.maybeCompactByThreshold(
-          compilation,
-          sessionKey,
-          session.abortController.signal
-        );
-        const turn = this.modelTurnWithRecovery(
-          compilation,
-          session.abortController.signal,
-          sessionKey,
-          true
-          // stream 模式：同时统计首 token 延迟
-        );
-        let turnResult = await turn.next();
-        while (!turnResult.done) {
-          yield turnResult.value;
-          turnResult = await turn.next();
-        }
-        const assistantMessage = turnResult.value;
-        if (!assistantMessage) break;
-        compilation.messages.push(assistantMessage);
-        await this.persistSessionSafe(request, sessionKey);
-        const toolCalls = extractToolCalls(assistantMessage.content);
-        if (toolCalls.length === 0) {
-          break;
-        }
-        for (const toolCall of toolCalls) {
-          yield {
-            type: "tool_start",
-            toolName: toolCall.name,
-            toolCallId: toolCall.id
-          };
-        }
-        const outcome = await this.executeToolCalls(
-          compilation,
-          toolCalls,
-          session.abortController.signal
-        );
-        await this.persistSessionSafe(request, sessionKey);
-        for (let i = 0; i < toolCalls.length; i++) {
-          yield {
-            type: "tool_end",
-            toolName: toolCalls[i].name,
-            toolCallId: toolCalls[i].id,
-            isError: this.isErrorResult(outcome.results[i])
-          };
-        }
-        if (outcome.terminate) {
-          compilation.terminateReason = outcome.terminateReason ?? "terminated";
-          break;
-        }
+  /** run 级错误分类：terminate → 'terminated'；否则只看最后一条 assistant 消息（与 buildResult 的 result.success 同口径） */
+  runErrorClass(compilation) {
+    if (compilation.terminateReason) return "terminated";
+    const messages = compilation.messages;
+    for (let i = messages.length - 1; i >= 0; i--) {
+      const m = messages[i];
+      if (m.role === "assistant") {
+        if (!m.errorMessage) return void 0;
+        const cls = errorClassFromMessage(m.errorMessage);
+        return cls ?? "unknown";
       }
-      if (maxTurns < 0) compilation.maxTurnsExhausted = true;
-      compilation.turnCount = turnCount;
-    } finally {
-      this.markIdle(session);
     }
+    return void 0;
   }
-  // ─── 工具执行 ───────────────────────────────────────────────────
-  /** 同步循环：执行工具调用并将结果消息按原顺序追加 */
-  async executeToolCalls(compilation, toolCalls, signal) {
-    const outcome = await this.runTools(toolCalls, signal, compilation.request, compilation.traceId);
-    for (let i = 0; i < toolCalls.length; i++) {
-      compilation.messages.push(
-        this.buildToolResultMessage(toolCalls[i], outcome.results[i])
-      );
-    }
-    return outcome;
+};
+
+// ../agent/runtime/tool-executor.ts
+var ToolExecutor = class {
+  constructor(_d) {
+    this._d = _d;
   }
+  _d;
   /**
    * 执行一组工具调用：parallelToolCalls 为 true 时并行，否则串行。
    * 返回 ToolExecutionOutcome：任一工具请求 terminate 即终止整个 run；
    * 串行模式下 terminate 后剩余工具生成 skipped 结果以保持配对完整。
    */
-  async runTools(toolCalls, signal, request, traceId) {
-    const execute = (tc) => this.executeTool(tc, signal, request, traceId);
-    if (this._parallelToolCalls && toolCalls.length > 1) {
+  async run(toolCalls, signal, request, traceId) {
+    const execute = (tc) => this.execute(tc, signal, request, traceId);
+    if (this._d.parallelToolCalls && toolCalls.length > 1) {
       const outcomes = await Promise.all(toolCalls.map(execute));
       const terminated = outcomes.find((o) => o.terminate);
       return {
@@ -1535,8 +1399,8 @@ var AgentRuntime = class _AgentRuntime {
     }
     return { results, terminate, terminateReason };
   }
-  async executeTool(toolCall, signal, request, traceId) {
-    const tool = this._globalTools.get(toolCall.name);
+  async execute(toolCall, signal, request, traceId) {
+    const tool = this._d.getTools().get(toolCall.name);
     if (!tool) {
       return {
         result: {
@@ -1550,27 +1414,43 @@ var AgentRuntime = class _AgentRuntime {
     if (tool.prepareArguments) {
       args = tool.prepareArguments(toolCall.arguments);
     }
-    if (this._permissionPolicy) {
+    if (!this._d.permissionPolicy) {
+      if (!this._d.permissionFailOpen) {
+        const reason = `no permissionPolicy configured (fail-closed by default). Configure RuntimeOptions.permissionPolicy (e.g. createAllowAllPolicy()) or explicitly set permissionFailOpen: true to allow unrestricted tool execution`;
+        await this._d.telemetry.emit("onPermissionDenied", {
+          traceId,
+          sessionKey: request.sessionKey ?? this._d.defaultSessionKey,
+          toolName: toolCall.name,
+          permissions: tool.permissions ?? [],
+          args,
+          reason: `permission denied for tool "${toolCall.name}": ${reason}`
+        });
+        return {
+          result: this.makeBlockedResult(`permission denied for tool "${toolCall.name}": ${reason}`),
+          terminate: false
+        };
+      }
+    } else {
       const permissionReq = {
         toolName: toolCall.name,
         permissions: tool.permissions ?? [],
         args,
-        sessionKey: request.sessionKey ?? this._sessionKey,
+        sessionKey: request.sessionKey ?? this._d.defaultSessionKey,
         request,
-        shared: this._extensionContext?.shared ?? /* @__PURE__ */ new Map()
+        shared: this._d.getShared() ?? /* @__PURE__ */ new Map()
       };
-      const decision = await this._permissionPolicy.check(permissionReq);
+      const decision = await this._d.permissionPolicy.check(permissionReq);
       let allowed = decision === "allow";
       if (decision === "confirm") {
-        allowed = this._permissionPolicy.confirm ? await this._permissionPolicy.confirm(permissionReq) : false;
+        allowed = this._d.permissionPolicy.confirm ? await this._d.permissionPolicy.confirm(permissionReq) : false;
       }
       if (decision === "pending") {
-        if (this._approvals) {
-          const approval = this._approvals.create(permissionReq, {
-            timeoutMs: this._approvalTimeoutMs,
+        if (this._d.approvals) {
+          const approval = this._d.approvals.create(permissionReq, {
+            timeoutMs: this._d.approvalTimeoutMs,
             signal
           });
-          await this.emitTelemetry("onApprovalPending", {
+          await this._d.telemetry.emit("onApprovalPending", {
             traceId,
             sessionKey: permissionReq.sessionKey,
             approvalId: approval.id,
@@ -1579,9 +1459,9 @@ var AgentRuntime = class _AgentRuntime {
             args,
             expiresAt: approval.expiresAt
           });
-          const outcome = await this._approvals.wait(approval);
+          const outcome = await this._d.approvals.wait(approval);
           allowed = outcome.status === "approved";
-          await this.emitTelemetry("onApprovalResolved", {
+          await this._d.telemetry.emit("onApprovalResolved", {
             traceId,
             sessionKey: permissionReq.sessionKey,
             approvalId: approval.id,
@@ -1595,7 +1475,7 @@ var AgentRuntime = class _AgentRuntime {
       }
       if (!allowed) {
         const reason = `permission denied by policy for tool "${toolCall.name}"`;
-        await this.emitTelemetry("onPermissionDenied", {
+        await this._d.telemetry.emit("onPermissionDenied", {
           traceId,
           sessionKey: permissionReq.sessionKey,
           toolName: toolCall.name,
@@ -1609,10 +1489,10 @@ var AgentRuntime = class _AgentRuntime {
         };
       }
     }
-    const { signal: timedSignal, clear } = withTimeoutSignal(signal, this._toolTimeoutMs);
+    const { signal: timedSignal, clear } = withTimeoutSignal(signal, this._d.toolTimeoutMs);
     try {
       const beforeCtx = this.buildToolCallContext(toolCall, tool, args, request, timedSignal);
-      const before = await this._hooks.beforeToolCall.promise(
+      const before = await this._d.hooks.beforeToolCall.promise(
         { block: false, terminate: false, args },
         beforeCtx
       );
@@ -1644,10 +1524,10 @@ var AgentRuntime = class _AgentRuntime {
         };
       }
       const status = toolResultStatus(result);
-      await this.emitTelemetry("onToolCall", {
+      await this._d.telemetry.emit("onToolCall", {
         traceId,
         spanId: newSpanId(),
-        sessionKey: request.sessionKey ?? this._sessionKey,
+        sessionKey: request.sessionKey ?? this._d.defaultSessionKey,
         toolName: toolCall.name,
         args,
         durationMs: Date.now() - toolStartedAt,
@@ -1657,7 +1537,7 @@ var AgentRuntime = class _AgentRuntime {
         errorClass: status === "error" ? errorClassFromMessage(String(result.details?.error ?? "")) ?? "tool_error" : void 0
       });
       const afterCtx = this.buildToolCallContext(toolCall, tool, args, request, timedSignal);
-      const after = await this._hooks.afterToolCall.promise(
+      const after = await this._d.hooks.afterToolCall.promise(
         { result, terminate: false },
         afterCtx
       );
@@ -1693,13 +1573,14 @@ var AgentRuntime = class _AgentRuntime {
       toolCall,
       tool,
       args,
-      sessionKey: request.sessionKey ?? this._sessionKey,
+      sessionKey: request.sessionKey ?? this._d.defaultSessionKey,
       request,
-      shared: this._extensionContext?.shared ?? /* @__PURE__ */ new Map(),
+      shared: this._d.getShared() ?? /* @__PURE__ */ new Map(),
       signal
     };
   }
-  buildToolResultMessage(toolCall, result) {
+  /** 工具结果 → toolResult 消息（写入会话历史） */
+  buildResultMessage(toolCall, result) {
     return {
       role: "toolResult",
       content: result.content,
@@ -1709,294 +1590,69 @@ var AgentRuntime = class _AgentRuntime {
       timestamp: Date.now()
     };
   }
-  buildUserMessage(request) {
-    if (request.media && request.media.length > 0) {
-      const blocks = [
-        createTextContent(request.message),
-        ...request.media.filter(Boolean).map(buildImageContent)
-      ];
-      return {
-        role: "user",
-        content: blocks,
-        timestamp: Date.now()
-      };
+};
+
+// ../agent/transformer/index.ts
+function ensureToolPairing(messages) {
+  const toolCallIds = /* @__PURE__ */ new Set();
+  const toolResultIds = /* @__PURE__ */ new Set();
+  for (const msg of messages) {
+    if (msg.role === "assistant") {
+      const content = msg.content;
+      if (Array.isArray(content)) {
+        for (const tc of extractToolCalls(content)) {
+          toolCallIds.add(tc.id);
+        }
+      }
     }
-    return {
-      role: "user",
-      content: request.message,
-      timestamp: Date.now()
-    };
-  }
-  // ─── 内部方法 ───────────────────────────────────────────────────
-  /**
-   * 获取同一会话的执行锁：返回 release 函数，调用后释放。
-   * 同一 sessionKey 的 run/stream 会串行执行，避免消息数组交错、
-   * abortController 互相覆盖、hydrate 竞态。
-   */
-  async acquire(session) {
-    let release;
-    const prev = session.queue;
-    session.queue = new Promise((resolve) => {
-      release = () => resolve();
-    });
-    await prev;
-    session.lockHeld = true;
-    return () => {
-      session.lockHeld = false;
-      release();
-    };
-  }
-  /** 标记会话空闲并唤醒所有 waitForIdle 等待者 */
-  markIdle(session) {
-    session.isStreaming = false;
-    session.abortController = null;
-    if (session.idleResolvers.length > 0) {
-      const resolvers = session.idleResolvers.splice(0);
-      for (const resolve of resolvers) resolve();
+    if (msg.role === "toolResult") {
+      toolResultIds.add(msg.toolCallId);
     }
   }
-  // ─── 会话持久化 ─────────────────────────────────────────────────
-  /** 从存储懒加载会话（串行化后无竞态，每个会话仅恢复一次） */
-  async hydrateSession(sessionKey, session) {
-    if (!this._sessionStorage) return;
-    if (session.hydrated) return;
-    session.hydrated = true;
-    const stored = await this._sessionStorage.load(sessionKey);
-    if (!stored) return;
-    session.messages = stored.messages;
-    session.createdAt = stored.createdAt;
+  const orphanedCalls = /* @__PURE__ */ new Set();
+  const orphanedResults = /* @__PURE__ */ new Set();
+  for (const id of toolCallIds) {
+    if (!toolResultIds.has(id)) orphanedCalls.add(id);
   }
-  /** 整体保存指定会话（ephemeral 跳过；失败不影响运行结果） */
-  async persistSession(sessionKey, session) {
-    if (!this._sessionStorage) return;
-    const stored = {
-      key: sessionKey,
-      version: SESSION_VERSION,
-      messages: session.messages,
-      model: this.deriveModel(session.messages),
-      usage: this.sumUsage(session.messages),
-      createdAt: session.createdAt,
-      updatedAt: (/* @__PURE__ */ new Date()).toISOString()
-    };
-    await this._sessionStorage.save(sessionKey, stored);
+  for (const id of toolResultIds) {
+    if (!toolCallIds.has(id)) orphanedResults.add(id);
   }
-  /**
-   * 实时持久化指定会话：每轮 assistant 回复/工具结果完成后调用，
-   * 让运行中的会话随时可被持久化数据观测到。ephemeral 跳过；
-   * 存储失败仅告警，不影响对话循环继续。
-   */
-  async persistSessionSafe(request, sessionKey) {
-    if (request.ephemeral || !this._sessionStorage) return;
-    try {
-      const session = this._sessions.get(sessionKey);
-      if (!session) return;
-      await this.persistSession(sessionKey, session);
-    } catch (err) {
-      console.warn("[Runtime] \u4F1A\u8BDD\u6301\u4E45\u5316\u5931\u8D25:", err?.message);
-    }
-  }
-  /** 从消息中推导最后使用的模型 */
-  deriveModel(messages) {
-    for (let i = messages.length - 1; i >= 0; i--) {
-      const msg = messages[i];
-      if (msg.role === "assistant" && msg.model) {
-        return {
-          provider: msg.provider ?? this._model.provider,
-          modelId: msg.model
-        };
-      }
-    }
-    return null;
-  }
-  /** 汇总所有 assistant 消息的 token 用量（含 cache） */
-  sumUsage(messages) {
-    const usage = createEmptyUsage();
-    for (const msg of messages) {
-      if (msg.role === "assistant") {
-        const u = msg.usage;
-        if (u) {
-          usage.input += u.input;
-          usage.output += u.output;
-          usage.total += u.total;
-          usage.cacheRead = (usage.cacheRead ?? 0) + (u.cacheRead ?? 0);
-          usage.cacheWrite = (usage.cacheWrite ?? 0) + (u.cacheWrite ?? 0);
-          usage.reasoning = (usage.reasoning ?? 0) + (u.reasoning ?? 0);
-        }
-      }
-    }
-    return usage;
-  }
-  /** 链式执行上下文转换器（按数组顺序，上一个输出作为下一个输入） */
-  async transformMessages(compilation, sessionKey) {
-    if (this._transformers.length === 0) {
-      return;
-    }
-    let resources = messagesToResources(compilation.messages);
-    const context = {
-      graph: compilation.graph,
-      runtime: {
-        sessionKey,
-        turn: compilation.messages.length,
-        contextWindow: this._model.contextWindow,
-        maxTokens: this._model.maxTokens,
-        contextBudgetRatio: this._contextBudgetRatio
-      }
-    };
-    for (const transformer of this._transformers) {
-      try {
-        resources = await transformer.transform(resources, context);
-      } catch (err) {
-        console.warn(
-          `[Runtime] \u8F6C\u6362\u5668 "${transformer.name}" \u5931\u8D25\uFF0C\u5DF2\u8DF3\u8FC7:`,
-          err?.message ?? err
-        );
-      }
-    }
-    const messages = resourcesToMessages(resources);
-    compilation.messages.splice(0, compilation.messages.length, ...messages);
-  }
-  buildContext(messages) {
-    const tools = Array.from(this._globalTools.values());
-    return {
-      systemPrompt: this._systemPrompt,
-      // compactionSummary / stateSnapshot 为内部扩展 role，provider 适配层
-      // 仅支持 user/assistant/toolResult，发出前统一转为带标注的 user 消息
-      messages: messages.filter((m) => m.role !== "system").map((m) => {
-        const role = m.role;
-        if (role === "compactionSummary") return this.compactionSummaryToUser(m);
-        if (role === "stateSnapshot") return this.stateSnapshotToUser(m);
-        return m;
-      }),
-      tools: tools.length > 0 ? tools : void 0
-    };
-  }
-  /** compactionSummary 消息 → user 消息（所有 provider 均兼容 user role） */
-  compactionSummaryToUser(msg) {
-    const text = typeof msg.content === "string" ? msg.content : extractText(msg.content);
-    return {
-      role: "user",
-      content: `${COMPACTION_USER_PREFIX}
-${text}`,
-      timestamp: msg.timestamp
-    };
-  }
-  /** stateSnapshot 消息 → user 消息（所有 provider 均兼容 user role） */
-  stateSnapshotToUser(msg) {
-    const text = typeof msg.content === "string" ? msg.content : extractText(msg.content);
-    return {
-      role: "user",
-      content: `${STATE_SNAPSHOT_USER_PREFIX}
-${text}`,
-      timestamp: msg.timestamp
-    };
-  }
-  async streamModel(compilation, signal, sessionKey) {
-    const turn = this.modelTurnWithRecovery(compilation, signal, sessionKey, false);
-    let r = await turn.next();
-    while (!r.done) r = await turn.next();
-    return r.value ?? this.emptyAssistantMessage();
-  }
-  /** 空的 assistant 消息（流异常中断无 done/error 事件时的兜底，与旧 streamModel 行为一致） */
-  emptyAssistantMessage() {
-    return {
-      role: "assistant",
-      content: [],
-      stopReason: "stop",
-      usage: createEmptyUsage(),
-      model: this._model.id,
-      provider: this._model.provider,
-      timestamp: Date.now()
-    };
+  if (orphanedCalls.size === 0 && orphanedResults.size === 0) {
+    return messages;
   }
-  /**
-   * 单回合模型调用 + 上下文溢出自动恢复闭环。
-   *
-   * 检测（isContextOverflow，统一传入 model.contextWindow / content / maxTokens，
-   * 覆盖显式错误 / 静默溢出 / 输入截断溢出 / 输出 thinking 耗尽 / 输出打满 五模式）
-   * → 丢弃失败的 assistant 消息 → 截断会话历史 → 同回合重试（不消耗回合数，
-   * 上限 OVERFLOW_RECOVERY_LIMIT）：
-   *
-   * - 显式错误 / 零产出截断溢出 / thinking 耗尽溢出 / 输出打满溢出：丢弃失败
-   *   消息后重试；流式路径吞掉可恢复的 error chunk（消费者看不到瞬态错误），
-   *   不可恢复时补发。
-   * - 静默溢出（stop + 有完整产出）：保留回复，仅压缩旧上下文供后续轮次。
-   * - 恢复耗尽或单请求超窗（无可丢弃）：返回最后一次错误消息，维持旧行为。
-   *
-   * 流式路径 yield 模型事件 chunk；非流式路径由 streamModel 消费（chunk 丢弃）。
-   * 返回最终 assistant 消息；无 done/error 事件时返回 null。
-   */
-  async *modelTurnWithRecovery(compilation, signal, sessionKey, stream) {
-    const contextWindow = this._model.contextWindow;
-    const maxTokens = this._model.maxTokens;
-    let recoveries = 0;
-    const toProbe = (m) => ({
-      stopReason: m.stopReason,
-      errorMessage: m.errorMessage,
-      usage: m.usage,
-      content: m.content,
-      maxTokens
-    });
-    while (true) {
-      let assistant = null;
-      let suppressed = null;
-      for await (const event of this.streamModelEvents(compilation, signal, stream)) {
-        if (event.type === "error") {
-          const msg = event.message;
-          if (recoveries < OVERFLOW_RECOVERY_LIMIT && isContextOverflow(toProbe(msg), contextWindow)) {
-            suppressed = msg;
-            continue;
+  const result = [];
+  for (const msg of messages) {
+    if (msg.role === "assistant") {
+      const content = msg.content;
+      if (Array.isArray(content)) {
+        const filteredContent = content.filter((block) => {
+          if (block.type === "toolCall") {
+            return !orphanedCalls.has(block.id);
           }
-          const chunk = this.streamEventToChunk(event);
-          if (chunk) yield chunk;
-          assistant = msg;
-        } else {
-          const chunk = this.streamEventToChunk(event);
-          if (chunk) yield chunk;
-          if (event.type === "done") assistant = event.message;
-        }
+          return true;
+        });
+        if (filteredContent.length === 0 && content.length > 0) continue;
+        result.push({ ...msg, content: filteredContent });
+      } else {
+        result.push(msg);
       }
-      const final = assistant ?? suppressed;
-      if (!final) return null;
-      if (isContextOverflow(toProbe(final), contextWindow)) {
-        const output = final.usage?.output ?? 0;
-        const blocks = Array.isArray(final.content) ? final.content : null;
-        const hasMeaningfulText = blocks?.some(
-          (b) => b.type === "text" && "text" in b && typeof b.text === "string" && b.text.trim().length > 0
-        );
-        const hasToolCall = blocks?.some((b) => b.type === "toolCall");
-        const thinkingOnly = blocks ? !hasMeaningfulText && !hasToolCall && blocks.some((b) => b.type === "thinking") : false;
-        const outputFull = maxTokens > 0 && output >= Math.floor(maxTokens * 0.95);
-        const failed = final.stopReason === "error" || output === 0 || thinkingOnly || outputFull;
-        if (failed && recoveries < OVERFLOW_RECOVERY_LIMIT) {
-          recoveries += 1;
-          if (await this.recoverFromOverflow(compilation, recoveries, sessionKey, signal)) {
-            const reason = thinkingOnly ? "thinking \u8017\u5C3D" : outputFull ? "output \u6253\u6EE1" : final.stopReason;
-            console.warn(
-              `[Runtime] \u4E0A\u4E0B\u6587\u6EA2\u51FA\uFF08${reason}\uFF09\uFF0C\u5DF2\u538B\u7F29\u5386\u53F2\u5E76\u540C\u56DE\u5408\u91CD\u8BD5\uFF08${recoveries}/${OVERFLOW_RECOVERY_LIMIT}\uFF09`
-            );
-            await this.emitTelemetry("onRetry", {
-              traceId: compilation.traceId,
-              provider: this._model.provider,
-              modelId: this._model.id,
-              attempt: recoveries,
-              errorClass: "context-overflow",
-              delayMs: 0,
-              willRetry: true
-            });
-            continue;
-          }
-          if (suppressed) {
-            yield { type: "error", content: final.errorMessage || "\u6A21\u578B\u8C03\u7528\u51FA\u9519" };
-          }
-          return final;
-        }
-        if (failed) return final;
-        await this.recoverFromOverflow(compilation, 1, sessionKey, signal);
-        console.warn("[Runtime] \u68C0\u6D4B\u5230\u9759\u9ED8\u4E0A\u4E0B\u6587\u6EA2\u51FA\uFF08usage \u8D85\u7A97\uFF09\uFF0C\u5DF2\u538B\u7F29\u5386\u53F2\u6D88\u606F");
+    } else if (msg.role === "toolResult") {
+      if (!orphanedResults.has(msg.toolCallId)) {
+        result.push(msg);
       }
-      return final;
+    } else {
+      result.push(msg);
     }
   }
+  return result;
+}
+
+// ../agent/runtime/compactor.ts
+var ContextCompactor = class {
+  constructor(_d) {
+    this._d = _d;
+  }
+  _d;
   /**
    * 计算溢出恢复的截断点：按 token 预算从最旧消息开始丢弃。
    *
@@ -2007,10 +1663,10 @@ ${text}`,
    * 最小集，单条请求即超窗，无法恢复。
    */
   computeOverflowSplit(messages, recovery) {
-    const contextWindow = this._model.contextWindow;
+    const contextWindow = this._d.getModel().contextWindow;
     if (!contextWindow || contextWindow <= 0) return 0;
     const target = Math.max(
-      Math.floor(contextWindow * this._contextBudgetRatio * 0.5 ** recovery),
+      Math.floor(contextWindow * this._d.contextBudgetRatio * 0.5 ** recovery),
       1
     );
     let total = 0;
@@ -2038,7 +1694,7 @@ ${text}`,
     const messages = compilation.messages;
     const split = this.computeOverflowSplit(messages, recovery);
     if (split <= 0) return false;
-    const useCompaction = !!this._compaction && this._compaction.enabled !== false && this._compaction.onOverflow !== false;
+    const useCompaction = !!this._d.compaction && this._d.compaction.enabled !== false && this._d.compaction.onOverflow !== false;
     if (useCompaction) {
       await this.compactOrTruncate(
         messages,
@@ -2061,30 +1717,17 @@ ${text}`,
    * 其余部分摘要替换；摘要失败降级硬截断。
    */
   async maybeCompactByThreshold(compilation, sessionKey, signal) {
-    if (!this._compaction || this._compaction.enabled === false) return;
-    const contextWindow = this._model.contextWindow;
+    if (!this._d.compaction || this._d.compaction.enabled === false) return;
+    const contextWindow = this._d.getModel().contextWindow;
     if (!contextWindow || contextWindow <= 0) return;
     const messages = compilation.messages;
     const triggerTokens = Math.floor(
-      contextWindow * (this._compaction?.triggerRatio ?? this._contextBudgetRatio)
+      contextWindow * (this._d.compaction?.triggerRatio ?? this._d.contextBudgetRatio)
     );
     let total = 0;
     for (const m of messages) total += estimateMessageTokens(m);
     if (total <= triggerTokens) return;
-    const targetTokens = Math.floor(
-      contextWindow * (this._compaction?.targetRatio ?? 0.5)
-    );
-    const keepTokens = Math.max(Math.floor(targetTokens / 2), 1);
-    let kept = 0;
-    let split = messages.length;
-    for (let i = messages.length - 1; i >= 0; i--) {
-      if (kept >= keepTokens) {
-        split = i + 1;
-        break;
-      }
-      kept += estimateMessageTokens(messages[i]);
-      split = i;
-    }
+    const split = this.computeKeepSplit(messages, contextWindow);
     if (split <= 0 || split >= messages.length) return;
     const mode = await this.compactOrTruncate(
       messages,
@@ -2099,20 +1742,12 @@ ${text}`,
     );
   }
   /**
-   * 手动压缩指定会话（交互命令 /compact 等）：跳过阈值判断，
-   * 直接将历史压缩至 targetRatio 保留量（复用 maybeCompactByThreshold
-   * 的保留段计算与 compactOrTruncate 执行路径），压缩后持久化。
+   * 保留段计算：从尾部累计保留最新消息，保留量为压缩目标（contextWindow ×
+   * targetRatio）的一半。返回被压缩段的结束下标；messages[0..split) 为被压缩段。
    */
-  async compact(sessionKey) {
-    if (!this._compaction || this._compaction.enabled === false) return null;
-    const key = sessionKey ?? this._sessionKey;
-    const session = this.getSession(key);
-    const messages = session.messages;
-    if (messages.length === 0) return null;
-    const contextWindow = this._model.contextWindow;
-    if (!contextWindow || contextWindow <= 0) return null;
+  computeKeepSplit(messages, contextWindow) {
     const targetTokens = Math.floor(
-      contextWindow * (this._compaction.targetRatio ?? 0.5)
+      contextWindow * (this._d.compaction?.targetRatio ?? 0.5)
     );
     const keepTokens = Math.max(Math.floor(targetTokens / 2), 1);
     let kept = 0;
@@ -2125,21 +1760,7 @@ ${text}`,
       kept += estimateMessageTokens(messages[i]);
       split = i;
     }
-    if (split <= 0 || split >= messages.length) return null;
-    const mode = await this.compactOrTruncate(
-      messages,
-      split,
-      key,
-      `manual-${Date.now().toString(36)}`,
-      new AbortController().signal,
-      "threshold"
-    );
-    try {
-      await this.persistSession(key, session);
-    } catch (err) {
-      console.warn("[Runtime] \u624B\u52A8\u538B\u7F29\u540E\u6301\u4E45\u5316\u5931\u8D25:", err?.message);
-    }
-    return mode;
+    return split;
   }
   /**
    * 执行压缩：messages[0..split) 为被压缩段，原地替换。
@@ -2154,10 +1775,10 @@ ${text}`,
     const tokensBefore = messages.reduce((sum, m) => sum + estimateMessageTokens(m), 0);
     let mode = "truncate";
     let summaryText = "";
-    const summaryEnabled = !!this._compaction && this._compaction.enabled !== false;
+    const summaryEnabled = !!this._d.compaction && this._d.compaction.enabled !== false;
     if (summaryEnabled && compacted.length > 0) {
       const summaryBudget = Math.floor(
-        this._model.contextWindow * COMPACTION_SUMMARY_BUDGET_RATIO
+        this._d.getModel().contextWindow * COMPACTION_SUMMARY_BUDGET_RATIO
       );
       const inputText = compacted.map((m) => messageToSummaryLine(m)).filter((line) => line.length > 0).join("\n");
       if (inputText && estimateTextTokens(inputText) <= summaryBudget) {
@@ -2184,7 +1805,7 @@ ${text}`,
       messages.splice(0, messages.length, ...kept);
       tokensAfter = kept.reduce((sum, m) => sum + estimateMessageTokens(m), 0);
     }
-    await this.emitTelemetry("onCompaction", {
+    await this._d.telemetry.emit("onCompaction", {
       traceId,
       sessionKey,
       mode,
@@ -2201,7 +1822,7 @@ ${text}`,
    * 由调用方降级硬截断——摘要失败不影响主流程。
    */
   async summarizeMessages(inputText, sessionKey, traceId, signal) {
-    const prompt = this._compaction?.prompt ?? DEFAULT_COMPACTION_PROMPT;
+    const prompt = this._d.compaction?.prompt ?? DEFAULT_COMPACTION_PROMPT;
     const context = {
       systemPrompt: prompt,
       messages: [{ role: "user", content: inputText, timestamp: Date.now() }]
@@ -2211,7 +1832,7 @@ ${text}`,
     let usage;
     let failed = false;
     try {
-      for await (const event of this._streamFn(this._model, context, { signal })) {
+      for await (const event of this._d.getStreamFn()(this._d.getModel(), context, { signal })) {
         if (event.type === "text_delta") {
           text += event.delta;
         } else if (event.type === "error") {
@@ -2229,11 +1850,11 @@ ${text}`,
       return null;
     }
     if (failed || !text.trim()) return null;
-    await this.emitTelemetry("onModelCall", {
+    await this._d.telemetry.emit("onModelCall", {
       traceId,
       spanId: newSpanId(),
       sessionKey,
-      modelId: this._model.id,
+      modelId: this._d.getModel().id,
       attempts: 1,
       inputTokens: usage?.input ?? estimateTextTokens(inputText),
       outputTokens: usage?.output ?? estimateTextTokens(text),
@@ -2250,30 +1871,148 @@ ${text}`,
       timestamp: Date.now()
     };
   }
-  /**
-   * 统一模型调用埋点生成器：run()（streamModel）与 stream()（runLoopStream）两路径共用。
-   * 职责：模型调用计时、spanId、attempts 累计、onRetry 转发、onModelCall 上报
-   * （含 tokens / cost / errorClass / ttft）。
-   */
-  async *streamModelEvents(compilation, signal, stream) {
-    const sessionKey = this.resolveSessionKey(compilation.request);
-    const modelStartedAt = Date.now();
-    const spanId = newSpanId();
+};
+
+// ../agent/runtime/model-turn.ts
+var ModelTurnRunner = class {
+  constructor(_d) {
+    this._d = _d;
+  }
+  _d;
+  async streamModel(compilation, signal, sessionKey) {
+    const turn = this.modelTurnWithRecovery(compilation, signal, sessionKey, false);
+    let r = await turn.next();
+    while (!r.done) r = await turn.next();
+    return r.value ?? this.emptyAssistantMessage();
+  }
+  /** 空的 assistant 消息（流异常中断无 done/error 事件时的兜底） */
+  emptyAssistantMessage() {
+    const model = this._d.getModel();
+    return {
+      role: "assistant",
+      content: [],
+      stopReason: "stop",
+      usage: createEmptyUsage(),
+      model: model.id,
+      provider: model.provider,
+      timestamp: Date.now()
+    };
+  }
+  /**
+   * 单回合模型调用 + 上下文溢出自动恢复闭环。
+   *
+   * 检测（isContextOverflow，统一传入 model.contextWindow / content / maxTokens，
+   * 覆盖显式错误 / 静默溢出 / 输入截断溢出 / 输出 thinking 耗尽 / 输出打满 五模式）
+   * → 丢弃失败的 assistant 消息 → 截断会话历史 → 同回合重试（不消耗回合数，
+   * 上限 OVERFLOW_RECOVERY_LIMIT）：
+   *
+   * - 显式错误 / 零产出截断溢出 / thinking 耗尽溢出 / 输出打满溢出：丢弃失败
+   *   消息后重试；流式路径吞掉可恢复的 error chunk（消费者看不到瞬态错误），
+   *   不可恢复时补发。
+   * - 静默溢出（stop + 有完整产出）：保留回复，仅压缩旧上下文供后续轮次。
+   * - 恢复耗尽或单请求超窗（无可丢弃）：返回最后一次错误消息，维持旧行为。
+   *
+   * 流式路径 yield 模型事件 chunk；非流式路径由 streamModel 消费（chunk 丢弃）。
+   * 返回最终 assistant 消息；无 done/error 事件时返回 null。
+   */
+  async *modelTurnWithRecovery(compilation, signal, sessionKey, stream) {
+    const model = this._d.getModel();
+    const contextWindow = model.contextWindow;
+    const maxTokens = model.maxTokens;
+    let recoveries = 0;
+    const toProbe = (m) => ({
+      stopReason: m.stopReason,
+      errorMessage: m.errorMessage,
+      usage: m.usage,
+      content: m.content,
+      maxTokens
+    });
+    while (true) {
+      let assistant = null;
+      let suppressed = null;
+      for await (const event of this.streamModelEvents(compilation, signal, stream)) {
+        if (event.type === "error") {
+          const msg = event.message;
+          if (recoveries < OVERFLOW_RECOVERY_LIMIT && isContextOverflow(toProbe(msg), contextWindow)) {
+            suppressed = msg;
+            continue;
+          }
+          const chunk = streamEventToChunk(event);
+          if (chunk) yield chunk;
+          assistant = msg;
+        } else {
+          const chunk = streamEventToChunk(event);
+          if (chunk) yield chunk;
+          if (event.type === "done") assistant = event.message;
+        }
+      }
+      const final = assistant ?? suppressed;
+      if (!final) return null;
+      if (isContextOverflow(toProbe(final), contextWindow)) {
+        const output = final.usage?.output ?? 0;
+        const blocks = Array.isArray(final.content) ? final.content : null;
+        const hasMeaningfulText = blocks?.some(
+          (b) => b.type === "text" && "text" in b && typeof b.text === "string" && b.text.trim().length > 0
+        );
+        const hasToolCall = blocks?.some((b) => b.type === "toolCall");
+        const thinkingOnly = blocks ? !hasMeaningfulText && !hasToolCall && blocks.some((b) => b.type === "thinking") : false;
+        const outputFull = maxTokens > 0 && output >= Math.floor(maxTokens * 0.95);
+        const failed = final.stopReason === "error" || output === 0 || thinkingOnly || outputFull;
+        if (failed && recoveries < OVERFLOW_RECOVERY_LIMIT) {
+          recoveries += 1;
+          if (await this._d.compactor.recoverFromOverflow(compilation, recoveries, sessionKey, signal)) {
+            const reason = thinkingOnly ? "thinking \u8017\u5C3D" : outputFull ? "output \u6253\u6EE1" : final.stopReason;
+            console.warn(
+              `[Runtime] \u4E0A\u4E0B\u6587\u6EA2\u51FA\uFF08${reason}\uFF09\uFF0C\u5DF2\u538B\u7F29\u5386\u53F2\u5E76\u540C\u56DE\u5408\u91CD\u8BD5\uFF08${recoveries}/${OVERFLOW_RECOVERY_LIMIT}\uFF09`
+            );
+            await this._d.telemetry.emit("onRetry", {
+              traceId: compilation.traceId,
+              provider: model.provider,
+              modelId: model.id,
+              attempt: recoveries,
+              errorClass: "context-overflow",
+              delayMs: 0,
+              willRetry: true
+            });
+            continue;
+          }
+          if (suppressed) {
+            yield { type: "error", content: final.errorMessage || "\u6A21\u578B\u8C03\u7528\u51FA\u9519" };
+          }
+          return final;
+        }
+        if (failed) return final;
+        await this._d.compactor.recoverFromOverflow(compilation, 1, sessionKey, signal);
+        console.warn("[Runtime] \u68C0\u6D4B\u5230\u9759\u9ED8\u4E0A\u4E0B\u6587\u6EA2\u51FA\uFF08usage \u8D85\u7A97\uFF09\uFF0C\u5DF2\u538B\u7F29\u5386\u53F2\u6D88\u606F");
+      }
+      return final;
+    }
+  }
+  /**
+   * 统一模型调用埋点生成器：run()（streamModel）与 stream()（runLoopStream）两路径共用。
+   * 职责：模型调用计时、spanId、attempts 累计、onRetry 转发、onModelCall 上报
+   * （含 tokens / cost / errorClass / ttft）。
+   */
+  async *streamModelEvents(compilation, signal, stream) {
+    const model = this._d.getModel();
+    const sessionKey = this._d.resolveSessionKey(compilation.request);
+    const modelStartedAt = Date.now();
+    const spanId = newSpanId();
     let attempts = 1;
     let ttftAt;
     let lastAssistant;
     const options = { signal };
-    if (this._thinkingLevel !== "off" && this._model.reasoning) {
-      options.reasoning = this._thinkingLevel;
+    if (this._d.getThinkingLevel() !== "off" && model.reasoning) {
+      options.reasoning = this._d.getThinkingLevel();
     }
     options.onRetryAttempt = (info) => {
       attempts += 1;
-      void this.emitTelemetry("onRetry", {
+      void this._d.telemetry.emit("onRetry", {
         traceId: compilation.traceId,
         spanId,
         // P2：重试明细关联到本模型调用 span
-        provider: this._model.provider,
-        modelId: this._model.id,
+        provider: model.provider,
+        modelId: model.id,
         attempt: info.attempt,
         errorClass: classifyError(info.error),
         status: statusOfRetryError(info.error),
@@ -2282,10 +2021,10 @@ ${text}`,
       });
     };
     try {
-      const context = await this._hooks.beforeModelCall.promise(
+      const context = await this._d.hooks.beforeModelCall.promise(
         this.buildContext(compilation.messages)
       );
-      for await (const event of this._streamFn(this._model, context, options)) {
+      for await (const event of this._d.getStreamFn()(model, context, options)) {
         if (stream && event.type === "text_delta" && ttftAt === void 0) {
           ttftAt = Date.now();
         }
@@ -2297,11 +2036,11 @@ ${text}`,
     } finally {
       const assistant = lastAssistant;
       const errorClass = assistant?.errorMessage ? errorClassFromMessage(assistant.errorMessage) ?? "unknown" : void 0;
-      await this.emitTelemetry("onModelCall", {
+      await this._d.telemetry.emit("onModelCall", {
         traceId: compilation.traceId,
         spanId,
         sessionKey,
-        modelId: this._model.id,
+        modelId: model.id,
         attempts,
         inputTokens: assistant?.usage?.input ?? 0,
         outputTokens: assistant?.usage?.output ?? 0,
@@ -2316,164 +2055,718 @@ ${text}`,
       }
     }
   }
-  /**
-   * 触发遥测回调。全可选、失败不阻断主流程。
-   */
-  async emitTelemetry(event, info) {
-    const fn = this._telemetry?.[event];
-    if (!fn) return;
-    try {
-      await Promise.resolve(fn(info));
-    } catch (err) {
-      console.warn(`[aipack] telemetry "${String(event)}" \u4E0A\u62A5\u5931\u8D25:`, err);
-    }
+  buildContext(messages) {
+    const tools = Array.from(this._d.getTools().values());
+    return {
+      systemPrompt: this._d.getSystemPrompt(),
+      // compactionSummary / stateSnapshot 为内部扩展 role，provider 适配层
+      // 仅支持 user/assistant/toolResult，发出前统一转为带标注的 user 消息
+      messages: messages.filter((m) => m.role !== "system").map((m) => {
+        const role = m.role;
+        if (role === "compactionSummary") return this.compactionSummaryToUser(m);
+        if (role === "stateSnapshot") return this.stateSnapshotToUser(m);
+        return m;
+      }),
+      tools: tools.length > 0 ? tools : void 0
+    };
   }
-  /** traceId 生成：优先用注入的生成器（测试可确定性） */
-  newTraceId() {
-    return this._traceIdGenerator ? this._traceIdGenerator() : newTraceId();
+  /** compactionSummary 消息 → user 消息（所有 provider 均兼容 user role） */
+  compactionSummaryToUser(msg) {
+    const text = typeof msg.content === "string" ? msg.content : extractText(msg.content);
+    return {
+      role: "user",
+      content: `${COMPACTION_USER_PREFIX}
+${text}`,
+      timestamp: msg.timestamp
+    };
   }
-  /** 组装并上报 run 级完成事件（_run/_stream 内部统一调用） */
-  async emitRunEnd(request, sessionKey, compilation, result, queuedMs, activeStartedAt) {
-    const activeMs = Date.now() - activeStartedAt;
-    await this.emitTelemetry("onRunEnd", {
-      traceId: compilation.traceId,
-      sessionKey,
-      // 请求未显式指定 model 时补实际模型（模型排行按 run 级 requests 统计，缺省会落入 'unknown'）
-      request: request.model ? request : { ...request, model: this._model.id },
-      durationMs: activeMs + queuedMs,
-      activeMs,
-      queuedMs,
-      turnCount: compilation.turnCount ?? 0,
-      result,
-      success: result.success,
-      errorClass: this.runErrorClass(compilation),
-      tokens: {
-        input: result.usage.input ?? 0,
-        output: result.usage.output ?? 0,
-        cacheRead: result.usage.cacheRead,
-        cacheWrite: result.usage.cacheWrite
-      },
-      ttftMs: compilation.ttftMs
-    });
+  /** stateSnapshot 消息 → user 消息（所有 provider 均兼容 user role） */
+  stateSnapshotToUser(msg) {
+    const text = typeof msg.content === "string" ? msg.content : extractText(msg.content);
+    return {
+      role: "user",
+      content: `${STATE_SNAPSHOT_USER_PREFIX}
+${text}`,
+      timestamp: msg.timestamp
+    };
   }
-  /** run 级错误分类：terminate → 'terminated'；否则只看最后一条 assistant 消息（与 buildResult 的 result.success 同口径） */
-  runErrorClass(compilation) {
-    if (compilation.terminateReason) return "terminated";
-    const messages = compilation.messages;
-    for (let i = messages.length - 1; i >= 0; i--) {
-      const m = messages[i];
-      if (m.role === "assistant") {
-        if (!m.errorMessage) return void 0;
-        const cls = errorClassFromMessage(m.errorMessage);
-        return cls ?? "unknown";
+};
+
+// ../agent/runtime/loops.ts
+var RunLoops = class {
+  constructor(_d) {
+    this._d = _d;
+  }
+  _d;
+  async run(request, sessionKey, session, traceId, queuedMs) {
+    const activeStartedAt = Date.now();
+    this._d.onSessionActivated(sessionKey);
+    await this._d.hooks.beforeInitialize.promise(request);
+    await this._d.hooks.afterInitialize.promise(request);
+    const finalRequest = await this._d.hooks.beforeRun.promise(request);
+    if (!finalRequest.ephemeral) {
+      await this._d.persistence.hydrate(sessionKey, session);
+    }
+    const compilation = this._d.createCompilation(finalRequest, sessionKey, session, traceId);
+    compilation.messages.push(this._d.buildUserMessage(finalRequest));
+    try {
+      await this.runLoop(compilation, finalRequest, session);
+      const result = this._d.buildResult(compilation);
+      await this._d.hooks.beforeEmit.promise(result);
+      await this._d.hooks.afterEmit.promise(result);
+      await this._d.hooks.done.promise(result, finalRequest);
+      compilation.completed = true;
+      await this.emitRunEnd(finalRequest, sessionKey, compilation, result, queuedMs, activeStartedAt);
+      return result;
+    } catch (err) {
+      const error = err;
+      const message = error?.message ?? String(err);
+      if (error?.name !== "AbortError") {
+        console.error("[Runtime] \u8FD0\u884C\u5931\u8D25:", error?.stack ?? message);
       }
+      await this._d.hooks.failed.promise(error, finalRequest);
+      const result = new ResultBuilder().error(message).build();
+      await this.emitRunEnd(finalRequest, sessionKey, compilation, result, queuedMs, activeStartedAt);
+      return result;
+    } finally {
+      await this._d.persistence.persistSafe(finalRequest, sessionKey);
     }
-    return void 0;
   }
-  buildResult(compilation) {
-    const messages = compilation.messages;
-    let content = "";
-    let stopReason = "completed";
-    let error;
-    const toolsUsed = [];
-    const usage = {};
-    for (const msg of messages) {
-      if (msg.role === "assistant") {
-        const assistant = msg;
-        content = extractText(assistant.content);
-        stopReason = assistant.stopReason ?? "completed";
-        error = assistant.errorMessage;
-        if (assistant.usage) {
-          usage.input = (usage.input ?? 0) + assistant.usage.input;
-          usage.output = (usage.output ?? 0) + assistant.usage.output;
-          usage.total = (usage.total ?? 0) + assistant.usage.total;
-          if (assistant.usage.cacheRead) usage.cacheRead = (usage.cacheRead ?? 0) + assistant.usage.cacheRead;
-          if (assistant.usage.cacheWrite) usage.cacheWrite = (usage.cacheWrite ?? 0) + assistant.usage.cacheWrite;
-        }
+  async *stream(request, sessionKey, session, traceId, queuedMs) {
+    const activeStartedAt = Date.now();
+    this._d.onSessionActivated(sessionKey);
+    await this._d.hooks.beforeInitialize.promise(request);
+    await this._d.hooks.afterInitialize.promise(request);
+    const finalRequest = await this._d.hooks.beforeRun.promise(request);
+    if (!finalRequest.ephemeral) {
+      await this._d.persistence.hydrate(sessionKey, session);
+    }
+    const compilation = this._d.createCompilation(finalRequest, sessionKey, session, traceId);
+    compilation.messages.push(this._d.buildUserMessage(finalRequest));
+    try {
+      for await (const chunk of this.runLoopStream(compilation, finalRequest, session)) {
+        yield chunk;
       }
-      if (msg.role === "toolResult") {
-        const toolMsg = msg;
-        if (!toolsUsed.includes(toolMsg.toolName)) {
-          toolsUsed.push(toolMsg.toolName);
-        }
+      const result = this._d.buildResult(compilation);
+      await this._d.hooks.beforeEmit.promise(result);
+      await this._d.hooks.afterEmit.promise(result);
+      await this._d.hooks.done.promise(result, finalRequest);
+      yield { type: "done", result };
+      await this.emitRunEnd(finalRequest, sessionKey, compilation, result, queuedMs, activeStartedAt);
+    } catch (err) {
+      const error = err;
+      const message = error?.message ?? String(err);
+      if (error?.name !== "AbortError") {
+        console.error("[Runtime] \u6D41\u5F0F\u8FD0\u884C\u5931\u8D25:", error?.stack ?? message);
       }
+      await this._d.hooks.failed.promise(error, finalRequest);
+      const result = new ResultBuilder().error(message).build();
+      yield { type: "error", content: message };
+      yield { type: "done", result };
+      await this.emitRunEnd(finalRequest, sessionKey, compilation, result, queuedMs, activeStartedAt);
+    } finally {
+      await this._d.persistence.persistSafe(finalRequest, sessionKey);
     }
-    const resources = messagesToResources(messages);
-    const builder = new ResultBuilder().content(content).toolsUsed(toolsUsed).usage(usage).stopReason(stopReason).error(error).resources(resources).metadata("traceId", compilation.traceId);
-    if (compilation.terminateReason) {
-      builder.stopReason("terminated").metadata("terminateReason", compilation.terminateReason);
-    }
-    if (compilation.maxTurnsExhausted) {
-      builder.stopReason("max_turns").metadata("maxTurns", true);
-    }
-    return builder.build();
   }
-  streamEventToChunk(event) {
-    switch (event.type) {
-      case "text_delta":
-        return { type: "text", content: event.delta };
-      case "thinking_delta":
-        return { type: "thinking", content: event.delta };
-      case "error":
-        return {
-          type: "error",
-          content: event.message.errorMessage || "\u6A21\u578B\u8C03\u7528\u51FA\u9519"
-        };
-      default:
-        return null;
+  // ─── 对话循环（同步） ───────────────────────────────────────────
+  async runLoop(compilation, request, session) {
+    session.isStreaming = true;
+    session.abortController = new AbortController();
+    const sessionKey = this._d.resolveSessionKey(request);
+    try {
+      let maxTurns = this._d.getMaxTurns();
+      let turnCount = 0;
+      while (maxTurns-- > 0) {
+        turnCount += 1;
+        await this._d.transformMessages(compilation, sessionKey);
+        await this._d.compactor.maybeCompactByThreshold(
+          compilation,
+          sessionKey,
+          session.abortController.signal
+        );
+        const assistantMessage = await this._d.modelTurn.streamModel(
+          compilation,
+          session.abortController.signal,
+          sessionKey
+        );
+        compilation.messages.push(assistantMessage);
+        await this._d.persistence.persistSafe(request, sessionKey);
+        const toolCalls = extractToolCalls(assistantMessage.content);
+        if (toolCalls.length === 0) {
+          break;
+        }
+        const outcome = await this.executeToolCalls(
+          compilation,
+          toolCalls,
+          session.abortController.signal
+        );
+        await this._d.persistence.persistSafe(request, sessionKey);
+        if (outcome.terminate) {
+          compilation.terminateReason = outcome.terminateReason ?? "terminated";
+          break;
+        }
+      }
+      if (maxTurns < 0) compilation.maxTurnsExhausted = true;
+      compilation.turnCount = turnCount;
+    } finally {
+      this._d.store.markIdle(session);
     }
   }
+  // ─── 对话循环（流式） ───────────────────────────────────────────
+  async *runLoopStream(compilation, request, session) {
+    session.isStreaming = true;
+    session.abortController = new AbortController();
+    const sessionKey = this._d.resolveSessionKey(request);
+    try {
+      let maxTurns = this._d.getMaxTurns();
+      let turnCount = 0;
+      while (maxTurns-- > 0) {
+        turnCount += 1;
+        await this._d.transformMessages(compilation, sessionKey);
+        await this._d.compactor.maybeCompactByThreshold(
+          compilation,
+          sessionKey,
+          session.abortController.signal
+        );
+        const turn = this._d.modelTurn.modelTurnWithRecovery(
+          compilation,
+          session.abortController.signal,
+          sessionKey,
+          true
+          // stream 模式：同时统计首 token 延迟
+        );
+        let turnResult = await turn.next();
+        while (!turnResult.done) {
+          yield turnResult.value;
+          turnResult = await turn.next();
+        }
+        const assistantMessage = turnResult.value;
+        if (!assistantMessage) break;
+        compilation.messages.push(assistantMessage);
+        await this._d.persistence.persistSafe(request, sessionKey);
+        const toolCalls = extractToolCalls(assistantMessage.content);
+        if (toolCalls.length === 0) {
+          break;
+        }
+        for (const toolCall of toolCalls) {
+          yield {
+            type: "tool_start",
+            toolName: toolCall.name,
+            toolCallId: toolCall.id
+          };
+        }
+        const outcome = await this.executeToolCalls(
+          compilation,
+          toolCalls,
+          session.abortController.signal
+        );
+        await this._d.persistence.persistSafe(request, sessionKey);
+        for (let i = 0; i < toolCalls.length; i++) {
+          yield {
+            type: "tool_end",
+            toolName: toolCalls[i].name,
+            toolCallId: toolCalls[i].id,
+            isError: this._d.tools.isErrorResult(outcome.results[i])
+          };
+        }
+        if (outcome.terminate) {
+          compilation.terminateReason = outcome.terminateReason ?? "terminated";
+          break;
+        }
+      }
+      if (maxTurns < 0) compilation.maxTurnsExhausted = true;
+      compilation.turnCount = turnCount;
+    } finally {
+      this._d.store.markIdle(session);
+    }
+  }
+  /** 同步循环：执行工具调用并将结果消息按原顺序追加 */
+  async executeToolCalls(compilation, toolCalls, signal) {
+    const outcome = await this._d.tools.run(
+      toolCalls,
+      signal,
+      compilation.request,
+      compilation.traceId
+    );
+    for (let i = 0; i < toolCalls.length; i++) {
+      compilation.messages.push(
+        this._d.tools.buildResultMessage(toolCalls[i], outcome.results[i])
+      );
+    }
+    return outcome;
+  }
+  /** run 级完成事件上报（补充默认模型 id） */
+  async emitRunEnd(request, sessionKey, compilation, result, queuedMs, activeStartedAt) {
+    await this._d.telemetry.emitRunEnd(
+      request,
+      sessionKey,
+      compilation,
+      result,
+      queuedMs,
+      activeStartedAt,
+      this._d.getModel().id
+    );
+  }
+};
+
+// ../agent/runtime/index.ts
+var AgentRuntime = class _AgentRuntime {
+  _config;
+  _extensions;
+  _hooks;
+  /** 上下文转换器列表，按数组顺序链式执行（上一个输出作为下一个输入） */
+  _transformers;
+  _model;
+  _streamFn;
+  _systemPrompt;
+  _thinkingLevel;
+  _globalTools = /* @__PURE__ */ new Map();
+  /** 默认会话 key（常量 'default'；请求未指定 sessionKey 时路由到此会话） */
+  _sessionKey;
+  _sessionStorage;
+  /** Extension 应用时的上下文（shared Map 供 ToolCallContext 引用） */
+  _extensionContext;
+  _maxTurns;
+  _toolTimeoutMs;
+  _parallelToolCalls;
+  _contextBudgetRatio;
+  /** 内置摘要压缩配置（未配置 = 保持旧行为，仅硬截断兜底） */
+  _compaction;
+  _telemetry;
+  /** 框架级工具权限策略（未配置 → 默认 fail-closed，见 permissionFailOpen） */
+  _permissionPolicy;
+  /** 未配置策略时是否显式放行工具执行（默认 false = 拒绝，安全姿态） */
+  _permissionFailOpen;
+  /** 审批管理器（pending 决策挂起等待外部批准；未配置 → pending 视为 deny） */
+  _approvals;
+  /** 审批等待超时（毫秒） */
+  _approvalTimeoutMs;
+  /** traceId 生成器（测试可注入确定性 id） */
+  _traceIdGenerator;
+  // ─── 协作模块（构造时组装，职责见文件头注释） ───────────────────
+  _store;
+  _persistence;
+  _emitter;
+  _tools;
+  _compactor;
+  _modelTurn;
+  _loops;
+  constructor(options) {
+    this._config = options.config ?? {};
+    this._extensions = new ExtensionManager();
+    this._hooks = this._extensions.getHooks();
+    this._transformers = [...options.transformers ?? []];
+    this._model = options.model ?? {
+      id: "unknown",
+      name: "unknown",
+      provider: "unknown",
+      contextWindow: 128e3,
+      maxTokens: 8192,
+      reasoning: false
+    };
+    this._streamFn = options.streamFn ?? (async function* () {
+      throw new Error("streamFn \u672A\u8BBE\u7F6E\uFF0C\u8BF7\u901A\u8FC7 setStreamFn() \u6216 RuntimeOptions.streamFn \u63D0\u4F9B");
+    });
+    this._systemPrompt = options.systemPrompt ?? "";
+    this._thinkingLevel = options.thinkingLevel ?? "off";
+    this._sessionStorage = options.sessionStorage;
+    this._maxTurns = options.maxTurns ?? 50;
+    this._toolTimeoutMs = options.toolTimeoutMs ?? 12e4;
+    this._parallelToolCalls = options.parallelToolCalls ?? true;
+    this._contextBudgetRatio = options.contextBudgetRatio ?? 0.8;
+    this._compaction = options.compaction;
+    this._telemetry = options.telemetry;
+    this._permissionPolicy = options.permissionPolicy;
+    this._permissionFailOpen = options.permissionFailOpen ?? false;
+    this._approvals = options.approvals;
+    this._approvalTimeoutMs = options.approvalTimeoutMs ?? 3e5;
+    this._traceIdGenerator = options.traceIdGenerator;
+    if (options.tools) {
+      for (const tool of options.tools) {
+        this._globalTools.set(tool.name, tool);
+      }
+    }
+    this._sessionKey = "default";
+    this._emitter = new RuntimeTelemetry(options.telemetry, options.traceIdGenerator);
+    setTapErrorHandler((info) => {
+      void this._emitter.emit("onHookError", {
+        sessionKey: this._sessionKey,
+        hook: info.hook,
+        tap: info.tap,
+        error: info.error
+      });
+    });
+    this._store = new SessionStore(this._sessionKey, options.maxSessions);
+    this._persistence = new SessionPersistence(
+      this._sessionStorage,
+      () => this._model,
+      this._store
+    );
+    this._tools = new ToolExecutor({
+      hooks: this._hooks,
+      telemetry: this._emitter,
+      permissionPolicy: this._permissionPolicy,
+      permissionFailOpen: this._permissionFailOpen,
+      approvals: this._approvals,
+      approvalTimeoutMs: this._approvalTimeoutMs,
+      toolTimeoutMs: this._toolTimeoutMs,
+      parallelToolCalls: this._parallelToolCalls,
+      defaultSessionKey: this._sessionKey,
+      getTools: () => this._globalTools,
+      getShared: () => this._extensionContext?.shared
+    });
+    this._compactor = new ContextCompactor({
+      telemetry: this._emitter,
+      getModel: () => this._model,
+      getStreamFn: () => this._streamFn,
+      contextBudgetRatio: this._contextBudgetRatio,
+      compaction: this._compaction
+    });
+    this._modelTurn = new ModelTurnRunner({
+      telemetry: this._emitter,
+      compactor: this._compactor,
+      hooks: this._hooks,
+      getModel: () => this._model,
+      getStreamFn: () => this._streamFn,
+      getSystemPrompt: () => this._systemPrompt,
+      getThinkingLevel: () => this._thinkingLevel,
+      getTools: () => this._globalTools,
+      resolveSessionKey: (request) => this.resolveSessionKey(request)
+    });
+    this._loops = new RunLoops({
+      hooks: this._hooks,
+      telemetry: this._emitter,
+      store: this._store,
+      persistence: this._persistence,
+      tools: this._tools,
+      compactor: this._compactor,
+      modelTurn: this._modelTurn,
+      getModel: () => this._model,
+      getMaxTurns: () => this._maxTurns,
+      resolveSessionKey: (request) => this.resolveSessionKey(request),
+      onSessionActivated: (key) => this.syncExtensionSessionKey(key),
+      createCompilation: (request, sessionKey, session, traceId) => this.createCompilation(request, sessionKey, session, traceId),
+      buildUserMessage: (request) => buildUserMessage(request),
+      buildResult: (compilation) => buildResult(compilation),
+      transformMessages: (compilation, sessionKey) => this.transformMessages(compilation, sessionKey)
+    });
+  }
+  // ─── 静态工厂 ───────────────────────────────────────────────────
+  static create(options = {}) {
+    const runtime = new _AgentRuntime(options);
+    if (options.extensions) {
+      runtime._extensions.registerAll(options.extensions);
+    }
+    const ctx = {
+      config: runtime._config,
+      workspace: options.workspace ?? process.cwd(),
+      sessionKey: runtime._sessionKey,
+      shared: /* @__PURE__ */ new Map(),
+      runtime
+    };
+    runtime._extensionContext = ctx;
+    runtime._extensions.applyAll(ctx);
+    return runtime;
+  }
+  // ─── Runtime 接口实现 ───────────────────────────────────────────
+  get config() {
+    return this._config;
+  }
+  get extensions() {
+    return this._extensions;
+  }
+  get hooks() {
+    return this._hooks;
+  }
+  // ─── 工具/模型/流管理 ───────────────────────────────────────────
+  registerTool(tool) {
+    if (this._globalTools.has(tool.name)) {
+      console.warn(`[Runtime] \u5DE5\u5177 "${tool.name}" \u5DF2\u5B58\u5728\uFF0C\u5C06\u88AB\u8986\u76D6`);
+    }
+    this._globalTools.set(tool.name, tool);
+    return this;
+  }
+  registerTools(tools) {
+    for (const tool of tools) {
+      this.registerTool(tool);
+    }
+    return this;
+  }
+  unregisterTool(name) {
+    return this._globalTools.delete(name);
+  }
+  setModel(model) {
+    this._model = model;
+    return this;
+  }
+  setSystemPrompt(prompt) {
+    this._systemPrompt = prompt;
+    return this;
+  }
+  setThinkingLevel(level) {
+    this._thinkingLevel = level;
+    return this;
+  }
+  setStreamFn(fn) {
+    this._streamFn = fn;
+    return this;
+  }
+  registerExtension(extension) {
+    this._extensions.register(extension);
+    return this;
+  }
+  useTransformer(transformer) {
+    this._transformers.push(transformer);
+    return this;
+  }
+  /**
+   * 获取指定会话的消息列表（默认会话；会话不存在返回空数组）。
+   * 同步方法：会话被 LRU 淘汰且配置了存储时，后台异步恢复（下次调用可读到），
+   * 需确定性读取（如断言/导出）请用 loadMessages()。
+   */
+  getMessages(sessionKey) {
+    const key = sessionKey ?? this._sessionKey;
+    if (this._store.has(key)) {
+      return this._store.getMessagesCopy(key);
+    }
+    if (this._sessionStorage) {
+      const session = this._store.ensure(key);
+      void this._persistence.hydrate(key, session).catch(() => {
+      });
+    }
+    return [];
+  }
+  /** 异步读取指定会话的消息列表：内存未命中（LRU 淘汰）时等待存储恢复后返回 */
+  async loadMessages(sessionKey) {
+    const key = sessionKey ?? this._sessionKey;
+    const existing = this._store.peek(key);
+    if (existing && existing.hydrated) {
+      return this._store.getMessagesCopy(key);
+    }
+    const session = existing ?? this._store.ensure(key);
+    await this._persistence.hydrate(key, session);
+    return this._store.getMessagesCopy(key);
+  }
+  /**
+   * 指定会话消息的只读视图（高频轮询用）：浅拷贝数组、共享消息对象，
+   * 避免每次 structuredClone 深拷贝整个会话历史；调用方不得修改内容。
+   */
+  peekMessages(sessionKey) {
+    return this._store.peekMessages(sessionKey ?? this._sessionKey);
+  }
+  /**
+   * 同步共享扩展上下文的会话键为本次 run/stream 的真实会话。
+   * 注意：ExtensionContext 为跨会话共享单例，多会话并发时该值为最近激活的
+   * 会话；需精确会话请用 ToolCallContext.sessionKey / Request.sessionKey。
+   */
+  syncExtensionSessionKey(sessionKey) {
+    if (this._extensionContext && this._extensionContext.sessionKey !== sessionKey) {
+      this._extensionContext.sessionKey = sessionKey;
+    }
+  }
+  // ─── 核心运行逻辑 ───────────────────────────────────────────────
+  /** 解析请求路由的会话 key：request.sessionKey ?? 默认会话 key */
+  resolveSessionKey(request) {
+    return request.sessionKey ?? this._sessionKey;
+  }
+  /** 当前活跃的会话 key 列表（含默认会话） */
+  getSessionKeys() {
+    return this._store.keys();
+  }
+  /** 某会话是否存在（内存中） */
+  hasSession(sessionKey) {
+    return this._store.has(sessionKey);
+  }
+  async run(request) {
+    const validation = validateRequest(request);
+    if (!validation.valid) {
+      const invalidResult = new ResultBuilder().error(`\u8BF7\u6C42\u6821\u9A8C\u5931\u8D25: ${validation.errors.join("; ")}`).build();
+      await this._emitter.emit("onRunEnd", {
+        traceId: this._emitter.newTraceId(),
+        sessionKey: this.resolveSessionKey(request),
+        request,
+        durationMs: 0,
+        activeMs: 0,
+        queuedMs: 0,
+        turnCount: 0,
+        result: invalidResult,
+        success: false,
+        errorClass: "validation",
+        tokens: { input: 0, output: 0 }
+      });
+      return invalidResult;
+    }
+    const finalRequest = normalizeRequest(request);
+    const sessionKey = this.resolveSessionKey(finalRequest);
+    const traceId = this._emitter.newTraceId();
+    const queuedAt = Date.now();
+    await this._emitter.emit("onRunStart", {
+      traceId,
+      sessionKey,
+      request: finalRequest,
+      queuedAt
+    });
+    const session = this._store.ensure(sessionKey);
+    const release = await this._store.acquire(session);
+    const queuedMs = Date.now() - queuedAt;
+    try {
+      return await this._persistence.withStorageLock(
+        finalRequest,
+        sessionKey,
+        () => this._loops.run(finalRequest, sessionKey, session, traceId, queuedMs)
+      );
+    } finally {
+      release();
+    }
+  }
+  async *stream(request) {
+    const validation = validateRequest(request);
+    if (!validation.valid) {
+      const message = `\u8BF7\u6C42\u6821\u9A8C\u5931\u8D25: ${validation.errors.join("; ")}`;
+      await this._emitter.emit("onRunEnd", {
+        traceId: this._emitter.newTraceId(),
+        sessionKey: this.resolveSessionKey(request),
+        request,
+        durationMs: 0,
+        activeMs: 0,
+        queuedMs: 0,
+        turnCount: 0,
+        result: new ResultBuilder().error(message).build(),
+        success: false,
+        errorClass: "validation",
+        tokens: { input: 0, output: 0 }
+      });
+      yield { type: "error", content: message };
+      yield { type: "done" };
+      return;
+    }
+    const finalRequest = normalizeRequest(request);
+    const sessionKey = this.resolveSessionKey(finalRequest);
+    const traceId = this._emitter.newTraceId();
+    const queuedAt = Date.now();
+    await this._emitter.emit("onRunStart", {
+      traceId,
+      sessionKey,
+      request: finalRequest,
+      queuedAt
+    });
+    const session = this._store.ensure(sessionKey);
+    const release = await this._store.acquire(session);
+    const queuedMs = Date.now() - queuedAt;
+    try {
+      yield* this._persistence.streamWithStorageLock(
+        finalRequest,
+        sessionKey,
+        () => this._loops.stream(finalRequest, sessionKey, session, traceId, queuedMs)
+      );
+    } finally {
+      release();
+    }
+  }
+  createCompilation(request, sessionKey, session, traceId) {
+    return {
+      request,
+      graph: createTaskGraph(),
+      resources: [],
+      messages: (session ?? this._store.ensure(sessionKey ?? this._sessionKey)).messages,
+      completed: false,
+      traceId: traceId ?? this._emitter.newTraceId()
+    };
+  }
+  async close() {
+    await this._store.drainAndClear();
+    this._extensions.clear();
+    this._transformers = [];
+  }
+  // ─── 上下文转换（链式执行，原地替换保持 session 引用） ──────────
+  /** 链式执行上下文转换器（按数组顺序，上一个输出作为下一个输入） */
+  async transformMessages(compilation, sessionKey) {
+    if (this._transformers.length === 0) {
+      return;
+    }
+    let resources = messagesToResources(compilation.messages);
+    const originalResources = resources;
+    const context = {
+      graph: compilation.graph,
+      runtime: {
+        sessionKey,
+        turn: compilation.messages.length,
+        contextWindow: this._model.contextWindow,
+        maxTokens: this._model.maxTokens,
+        contextBudgetRatio: this._contextBudgetRatio
+      }
+    };
+    for (const transformer of this._transformers) {
+      try {
+        const next = await transformer.transform(resources, context);
+        if (next !== resources) resources = next;
+      } catch (err) {
+        console.warn(
+          `[Runtime] \u8F6C\u6362\u5668 "${transformer.name}" \u5931\u8D25\uFF0C\u5DF2\u8DF3\u8FC7:`,
+          err?.message ?? err
+        );
+      }
+    }
+    if (resources === originalResources) {
+      return;
+    }
+    const messages = resourcesToMessages(resources);
+    compilation.messages.splice(0, compilation.messages.length, ...messages);
+  }
+  // ─── 手动压缩（交互命令 /compact 等） ───────────────────────────
+  /**
+   * 手动压缩指定会话：跳过阈值判断，直接将历史压缩至 targetRatio
+   * 保留量（复用 compactor 的保留段计算与 compactOrTruncate 执行路径），
+   * 压缩后持久化。返回压缩模式；compaction 未启用或无可压缩段时返回 null。
+   */
+  async compact(sessionKey) {
+    if (!this._compaction || this._compaction.enabled === false) return null;
+    const key = sessionKey ?? this._sessionKey;
+    const session = this._store.ensure(key);
+    const messages = session.messages;
+    if (messages.length === 0) return null;
+    const contextWindow = this._model.contextWindow;
+    if (!contextWindow || contextWindow <= 0) return null;
+    const split = this._compactor.computeKeepSplit(messages, contextWindow);
+    if (split <= 0 || split >= messages.length) return null;
+    const mode = await this._compactor.compactOrTruncate(
+      messages,
+      split,
+      key,
+      `manual-${Date.now().toString(36)}`,
+      new AbortController().signal,
+      "threshold"
+    );
+    try {
+      await this._persistence.persist(key, session);
+    } catch (err) {
+      console.warn("[Runtime] \u624B\u52A8\u538B\u7F29\u540E\u6301\u4E45\u5316\u5931\u8D25:", err?.message);
+    }
+    return mode;
+  }
   // ─── 便捷方法 ───────────────────────────────────────────────────
   /** 终止指定会话的运行（默认会话；会话不存在为 no-op） */
   abort(sessionKey) {
-    this._sessions.get(sessionKey ?? this._sessionKey)?.abortController?.abort();
+    this._store.peek(sessionKey ?? this._sessionKey)?.abortController?.abort();
   }
   /** 检查指定会话是否正在运行（默认会话；会话不存在返回 false） */
   isBusy(sessionKey) {
-    return this._sessions.get(sessionKey ?? this._sessionKey)?.isStreaming ?? false;
+    return this._store.peek(sessionKey ?? this._sessionKey)?.isStreaming ?? false;
   }
   /** 等待指定会话空闲（默认会话；基于 promise，无轮询） */
   async waitForIdle(sessionKey, timeoutMs) {
-    const session = this._sessions.get(sessionKey ?? this._sessionKey);
-    if (!session || !session.isStreaming) return;
-    if (timeoutMs === void 0) {
-      await new Promise((resolve) => {
-        session.idleResolvers.push(resolve);
-      });
-      return;
-    }
-    await new Promise((resolve, reject) => {
-      const resolver = () => {
-        clearTimeout(timer);
-        resolve();
-      };
-      const timer = setTimeout(() => {
-        const i = session.idleResolvers.indexOf(resolver);
-        if (i >= 0) session.idleResolvers.splice(i, 1);
-        reject(new Error(
-          `[Runtime] waitForIdle \u8D85\u65F6\uFF08${timeoutMs}ms\uFF09: ${sessionKey ?? "default"}`
-        ));
-      }, timeoutMs);
-      session.idleResolvers.push(resolver);
-    });
+    await this._store.waitForIdle(sessionKey ?? this._sessionKey, timeoutMs);
   }
   /** 清除指定会话消息（仅内存；下次 run 会从存储恢复） */
   clearSession(sessionKey) {
-    const session = this._sessions.get(sessionKey ?? this._sessionKey);
-    if (!session) return;
-    session.messages = [];
-    session.hydrated = false;
+    this._store.clearMessages(sessionKey ?? this._sessionKey);
   }
   /** 删除指定会话（内存 + 存储），返回是否删除成功 */
   async deleteSession(sessionKey) {
     const key = sessionKey ?? this._sessionKey;
-    const session = this._sessions.get(key);
-    if (session) {
-      await session.queue;
-      this._sessions.delete(key);
-    }
-    if (!this._sessionStorage) return true;
+    await this._store.remove(key);
     const storage = this._sessionStorage;
+    if (!storage) return true;
     if (!storage.withLock) return storage.delete(key);
     return storage.withLock(key, () => storage.delete(key));
   }