@downcity/agent 1.1.437 → 1.1.445

package/src/tools/ask/AskQuestionsTool.ts

@@ -4,22 +4,28 @@
  * 该 Tool 只负责把模型的结构化 Tool Call 映射到当前 Session 的 Question
  * Interaction。Session 是交互状态和生命周期的唯一拥有者；Tool 等待 Session 返回终态，
  * 再把用户答案作为 Tool Result 交回同一 Turn 的后续模型 Step。
+ *
+ * Interaction 的 `payload` 由生产者解释，所以问题与回答的校验都在这里：入参先过
+ * Schema，回答再过 {@link resolve_ask_question_answers}，核心不参与业务字段。
  */
 
 import {
-  define_runtime_tool,
-  type RuntimeToolExecutionOptions as ToolExecutionOptions,
+  define_agent_tool,
+  type ToolCallContext,
 } from "@downcity/type";
 import { ask_questions_input_schema } from "./AskQuestionsToolSchemas.js";
+import {
+  read_ask_question_note,
+  resolve_ask_question_answers,
+} from "./AskQuestionAnswers.js";
 import type {
   AskQuestionsToolInput,
   AskQuestionsToolOutput,
 } from "@/types/tools/ask/AskQuestionsTool.js";
-import type { SessionToolExecutionContext } from "@/types/executor/SessionToolExecutionContext.js";
+import type { ActionResult } from "@downcity/type";
 import { generate_id } from "@/utils/Id.js";
-import type { ActionResult } from "@/types/action/ActionResult.js";
 import type { JsonValue } from "@downcity/type";
-import type { SessionInteractionAnswer } from "@downcity/type";
+import type { SessionInteractionQuestion } from "@downcity/type";
 
 /**
  * 由调用方显式注册、按当前 Session Turn 上下文执行的提问 Tool。
@@ -33,54 +39,42 @@ import type { SessionInteractionAnswer } from "@downcity/type";
  * });
  * ```
  */
-export const AskQuestionsTool = define_runtime_tool<AskQuestionsToolInput, ActionResult<AskQuestionsToolOutput>>({
+export const AskQuestionsTool = define_agent_tool<AskQuestionsToolInput, ActionResult<AskQuestionsToolOutput>>({
   description:
     "Ask the user one or more questions when missing information would materially change the outcome. The call waits for every answer, then returns them so you can continue the same task. Do not use it for information that can be inferred safely. For single_select and multi_select questions, every option MUST contain both a machine-readable value and a user-visible label; never omit value or use label as value. Example: { value: 'cn', label: '中国' }.",
   input_schema: ask_questions_input_schema,
   execute: async (
     input: AskQuestionsToolInput,
-    execution_options: ToolExecutionOptions,
+    context: ToolCallContext,
   ): Promise<ActionResult<AskQuestionsToolOutput>> => {
-    const execution_context = execution_options.context as
-      | Partial<SessionToolExecutionContext>
-      | undefined;
-    const action_execution = execution_context?.action_execution_context;
-    const interaction_port = action_execution?.session.interactions;
-    const turn_id = String(action_execution?.session.turn_id || "").trim();
-    const tool_call_id = String(action_execution?.call_id || "").trim();
+    const interaction_port = context.interactions;
+    const turn_id = String(context.turn_id || "").trim();
+    const tool_call_id = String(context.tool_call_id || "").trim();
     if (!interaction_port || !turn_id || !tool_call_id) {
       throw new Error(
         "ask_question requires an active Session tool execution context",
       );
     }
 
+    // 入参先过 Schema：模型漏写 type 这类缺陷在发起交互之前就暴露，不会落成待响应卡片。
+    const parsed = ask_questions_input_schema.parse(input);
+    // 问题只在模型输入上补一个 Session 生成的 question_id，其余字段原样落库。
+    const questions: SessionInteractionQuestion[] = parsed.questions.map(
+      (question) => ({ ...question, question_id: `question:${generate_id()}` }),
+    );
+
     const handle = await interaction_port.request({
-      interaction_id: `interaction:${generate_id()}`,
-      turn_id,
       type: "question",
-      source: {
-        type: "tool",
-        tool_call_id,
-        tool_name: "ask_question",
-      },
-      title: input.title,
-      payload: {
-        questions: input.questions.map((question) => ({
-          question_id: `question:${generate_id()}`,
-          prompt: question.question,
-          response_type: question.type,
-          ...(question.options ? { options: question.options } : {}),
-        })),
-      } as unknown as JsonValue,
-      created_at: Date.now(),
+      turn_id,
+      tool_call_id,
+      tool_name: "ask_question",
+      ...(parsed.title ? { title: parsed.title } : {}),
+      payload: { questions } as unknown as JsonValue,
     });
     const result = await handle.result;
     if (result.status === "cancelled") {
       throw new Error(`ask_question was cancelled: ${result.reason}`);
     }
-    if (result.status === "expired") {
-      throw new Error("ask_question expired before the user responded");
-    }
     if (
       result.status !== "resolved" ||
       result.response.type !== "question" ||
@@ -90,12 +84,13 @@ export const AskQuestionsTool = define_runtime_tool<AskQuestionsToolInput, Actio
         "ask_question received an incompatible Interaction response",
       );
     }
-    const response_payload = result.response.payload as unknown as { answers: SessionInteractionAnswer[]; note?: string };
+    const answers = resolve_ask_question_answers(questions, result.response.payload);
+    const note = read_ask_question_note(result.response.payload);
     return {
       output: {
         status: "resolved",
-        answers: response_payload.answers,
-        ...(response_payload.note ? { note: response_payload.note } : {}),
+        answers,
+        ...(note ? { note } : {}),
       },
       messages: [],
     };

package/src/types/agent/AgentOptions.ts

@@ -6,7 +6,7 @@
  * - RemoteAgent 与 Session 数据结构拆到独立类型文件。
  */
 
-import type { ModelClient, RuntimeTool as Tool } from "@downcity/type";
+import type { ModelClient, AgentTool as Tool, ToolHookSet } from "@downcity/type";
 import type {
   AgentManagedSession,
   SessionOptions,
@@ -52,14 +52,23 @@ export interface AgentOptions {
   description?: string;
 
   /**
-   * 当前 agent 默认可用的工具集合。
+   * 当前 agent 自有的工具集合。
    *
    * 关键点（中文）
    * - tools 归属于 agent 级，而不是 session 级。
-   * - session 运行时会直接复用这份工具集合。
+   * - 与 Workspace 工具、容器 Power 工具在 Session 创建时合并；同名冲突立即失败。
    */
   tools?: Record<string, Tool>;
 
+  /**
+   * 当前 agent 自有的检查点处理器集合。
+   *
+   * 关键点（中文）
+   * - 与容器提供的 Power hooks 合并；同名检查点按「容器在前、自有在后」顺序执行。
+   * - 不传入时只使用容器提供的 hooks。
+   */
+  hooks?: ToolHookSet;
+
   /**
    * 调用方显式传入的静态基础指令。
    *
@@ -90,13 +99,13 @@ export interface AgentOptions {
   session_class?: AgentSessionConstructor;
 
   /**
-   * 为每个 Session 创建独立 Composer 的工厂。
+   * 当前 Agent 使用的 Session Composer。
    *
    * 关键点（中文）
-   * - 每次创建、恢复或 fork Session 都会调用一次，禁止返回共享实例。
-   * - 省略时创建默认 `DefaultSessionComposer`。
-   * - Context Policy 应在工厂内部随 Composer 一起创建，避免跨 Session 共享派生状态。
+   * - Composer 描述「这个 Agent 怎么和模型说话」，属于 Agent 级特性，被其所有 Session 共享。
+   * - 实现必须无状态：全部 Session 与上下文都由 `compose(input)` 参数传入，派生数据写入传入的 `derived` 存储。
+   * - 省略时使用默认 `DefaultSessionComposer`。
    */
-  session_composer?: () => SessionComposer;
+  session_composer?: SessionComposer;
 
 }

package/src/types/agent/AgentSessionCollection.ts

@@ -68,4 +68,13 @@ export interface AgentSessionCollection {
 
   /** 清空 Session 消息。 */
   clear_messages(session_id: string, origin_type?: string): Promise<boolean>;
+
+  /**
+   * 释放一个空闲 Session 的运行时实例。
+   *
+   * 只影响内存缓存；消息与元数据仍在 Store 中，下次 `get()` 会重新恢复。
+   * 正在执行的 Session 不会被释放，返回是否真的释放。
+   * 调用方必须先解除对该实例的订阅，否则重新 `get()` 得到的新实例不会再被订阅。
+   */
+  release(session_id: string, origin_type?: string): boolean;
 }

package/src/types/agent/SessionActor.ts

@@ -31,7 +31,7 @@ import type {
 import type {
   RespondSessionInteractionInput,
   SessionInteractionResult,
-  SessionPendingInteraction,
+  SessionInteractionRequest,
 } from "@downcity/type";
 import type {
   ListSessionMessagesInput,
@@ -63,7 +63,6 @@ export interface AgentSessions<TSession extends AgentSessionActor = AgentSession
 
   /** 永久清空已归档 session。 */
   clean_archive(): Promise<AgentCleanArchiveResult>;
-
 }
 
 /**
@@ -99,7 +98,7 @@ export interface AgentSessionActor {
   system(): Promise<AgentSessionSystemSnapshot>;
 
   /** 列出当前 Session 正在等待用户响应的 Interaction。 */
-  interactions(): Promise<SessionPendingInteraction[]>;
+  interactions(): Promise<SessionInteractionRequest[]>;
 
   /** 读取当前 Session 的运行与安全状态。 */
   status(): Promise<AgentSessionStatus>;
@@ -127,7 +126,7 @@ export interface AgentSession extends AgentSessionActor {
   /** 把当前 Session 首次生成后固定的完整 system 显式固化到 instruction.md。 */
   snapshot(): Promise<void>;
 
-  /** 使用 Agent 当前 instruction 与 Plugin 显式重新生成 Session system。 */
+  /** 使用 Agent 当前 instruction 与 Power 显式重新生成 Session system。 */
   syncshot(): Promise<void>;
 
   /** 从当前 session 创建一个分叉会话。 */

package/src/types/group/DispatchStrategy.ts

@@ -12,7 +12,7 @@ import type {
   ModelJsonValue,
   ModelMessage,
 } from "@downcity/type";
-import { generate_model } from "@executor/model/ModelGenerate.js";
+import { generate_model } from "@/model/ModelGenerate.js";
 import { z } from "zod";
 
 /** 本次调度的触发来源。 */

package/src/types/group/GroupSession.ts

@@ -84,6 +84,31 @@ export interface GroupSessionListInput {
   readonly workspace_id?: string;
 }
 
+/**
+ * 归档一个 GroupSession 的结果。
+ *
+ * 归档是一次**目录搬迁**（活动区 → 归档区），不是打标记：
+ * 它让「活动列表」天然只含活动项，不需要在每次查询里过滤。
+ */
+export interface GroupSessionArchiveResult {
+  /** 被归档的 GroupSession 标识。 */
+  readonly session_id: string;
+  /** 归档发生的时间戳。 */
+  readonly archived_at: number;
+}
+
+/** 列出已归档 GroupSession 的过滤条件。 */
+export interface GroupSessionArchiveListInput {
+  /** 只返回绑定到指定 Workspace 的归档群聊。 */
+  readonly workspace_id?: string;
+}
+
+/** 清空归档后的结果。 */
+export interface GroupSessionCleanArchiveResult {
+  /** 被永久删除的归档 GroupSession 标识。 */
+  readonly removed_session_ids: readonly string[];
+}
+
 /** GroupSession 公开能力。 */
 export interface GroupSessionContract {
   /** 当前群聊上下文的稳定标识。 */
@@ -117,10 +142,28 @@ export interface GroupSessions {
   create(input?: GroupSessionCreateInput): Promise<GroupSession>;
   /** 从 Storage 恢复当前 Group 的一个群聊上下文。 */
   get(session_id: string, input?: GroupSessionGetInput): Promise<GroupSession | null>;
-  /** 从 Storage 恢复当前 Group 的全部群聊上下文。 */
+  /** 从 Storage 恢复当前 Group 的全部群聊上下文（不含已归档）。 */
   list(input?: GroupSessionListInput): Promise<readonly GroupSessionSummary[]>;
   /** 释放并移除指定群聊上下文。 */
   remove(session_id: string, input?: GroupSessionGetInput): Promise<GroupSession | null>;
+  /**
+   * 归档指定群聊上下文：从活动区迁入归档区。
+   *
+   * 与 `remove` 的区别是**可逆性**：归档只是收起来，数据仍在归档区；
+   * 而 `remove` 是永久删除。因此正在执行的群聊不能归档（先停再归档）。
+   */
+  archive(session_id: string): Promise<GroupSessionArchiveResult>;
+  /** 列出已归档的群聊上下文摘要。 */
+  archived(input?: GroupSessionArchiveListInput): Promise<readonly GroupSessionSummary[]>;
+  /** 永久清空当前 Group 的全部归档。 */
+  clean_archive(): Promise<GroupSessionCleanArchiveResult>;
+  /**
+   * 永久删除当前 Group 的全部群聊数据（活动区 + 归档区）。
+   *
+   * 它服务于「Group 被删除」：Group 是群聊的**所有者**，所有者消失时它拥有的数据
+   * 不该继续存在。与 `dispose` 的区别：那个只释放运行时实例，数据仍在磁盘上。
+   */
+  purge(): Promise<void>;
 }
 
 /** GroupSession 的内部依赖快照。 */

package/src/types/group/GroupSessionStore.ts

@@ -2,6 +2,7 @@
 
 import type { GroupMessage } from "@/types/group/Group.js";
 import type { GroupDispatchTurnRecord } from "@/types/group/GroupDispatch.js";
+import type { GroupSessionArchiveResult, GroupSessionCleanArchiveResult } from "@/types/group/GroupSession.js";
 import type { FileSystem } from "@downcity/type";
 
 /** GroupSession 的持久化元数据。 */
@@ -70,12 +71,38 @@ export interface GroupSessionDataStore {
 export interface GroupSessionStore {
   /** 返回指定 GroupSession 的持久化视图。 */
   session(session_id: string): GroupSessionDataStore;
-  /** 判断指定 GroupSession 是否存在。 */
+  /** 判断指定 GroupSession 是否存在（活动区）。 */
   has_session(session_id: string): Promise<boolean>;
-  /** 列出当前 Group 的持久化 Session metadata。 */
+  /** 列出当前 Group 活动区的 Session metadata（不含已归档）。 */
   list_session_metadata(): Promise<GroupSessionHistoryMeta[]>;
-  /** 删除指定 GroupSession 的全部数据。 */
+  /** 删除指定 GroupSession 的全部数据（活动区）。 */
   remove_session(session_id: string): Promise<boolean>;
+  /**
+   * 把一个活动 GroupSession 迁入归档区。
+   *
+   * 与 Agent Session 的归档同形（`LocalSessionStore.archive_session`），只有一处差别：
+   * **不接受 `origin_type`**——群聊的来源只有一种，多一个参数只会让人猜该传什么。
+   *
+   * 不变量（两个方向都不允许静默成功）：
+   *
+   * - 源不存在 → 报错；
+   * - 目标已存在 → 报错（覆盖会丢掉一份真实数据）。
+   */
+  archive_session(session_id: string): Promise<GroupSessionArchiveResult>;
+  /** 列出归档区的 Session metadata。 */
+  list_archived_session_metadata(): Promise<GroupSessionHistoryMeta[]>;
+  /** 删除归档区中的指定 Session。 */
+  remove_archived_session(session_id: string): Promise<boolean>;
+  /** 永久清空归档区。 */
+  clean_archive(): Promise<GroupSessionCleanArchiveResult>;
+  /**
+   * 永久删除当前 Group 的**全部** GroupSession 数据（活动区 + 归档区）。
+   *
+   * 与 `clean_archive` 的区别：那个只动归档区，这个连活动区一起删。
+   * 它服务于「Group 被删除」——Group 是群聊的**所有者**，所有者消失时它拥有的数据不该继续存在。
+   * 没有它时删掉一个 Group 会在磁盘上留下无人认领的孤儿目录。
+   */
+  purge(): Promise<void>;
   /** 释放当前 Store 持有的资源。 */
   dispose(): Promise<void>;
 }

package/src/types/sdk/AgentSessionAction.ts

@@ -6,20 +6,7 @@
  * - Action 不进入模型输入。
  */
 
-import type {
-  SessionActionEvent,
-  SessionActionStatus,
-} from "@downcity/type";
-
-/**
- * Session action 当前状态。
- */
-export type AgentSessionActionState = SessionActionStatus;
-
-/**
- * Session action 记录。
- */
-export type AgentSessionActionRecord = SessionActionEvent;
+import type { SessionActionEvent } from "@downcity/type";
 
 /**
  * Session action 订阅事件。

package/src/types/session/{AdaptivePartContextPolicy.ts → ContextCheckpoint.ts}

@@ -1,7 +1,8 @@
 /**
- * AdaptivePartContextPolicy 内部持久化与候选类型。
+ * Composer 上下文 checkpoint 派生类型。
  *
- * 类型集中在 types 目录，策略模块只保留上下文选择行为。
+ * checkpoint 记录「累计摘要已经覆盖到哪个 canonical Part」，属于 Composer 自己的派生
+ * 数据：可以随时删除并从 canonical history 重新累积，不参与 Session Message 语义。
  */
 
 import type {
@@ -11,25 +12,25 @@ import type {
 } from "@downcity/type";
 
 /** Part 级累计摘要 checkpoint。 */
-export interface AdaptivePartCheckpointRow {
+export interface ContextCheckpointRow {
   /** checkpoint 稳定标识。 */
   checkpoint_id: string;
   /** 边界所属 Message 标识。 */
   through_message_id: string;
   /** 边界所属 Message sequence。 */
   through_message_sequence: number;
-  /** 边界 Part sequence。 */
+  /** 边界 Part sequence；边界可以落在单个 Message 内部。 */
   through_part_sequence: number;
-  /** 累计摘要正文。 */
+  /** 截至边界的累计摘要正文。 */
   summary: string;
-  /** 生成派生结果的策略版本。 */
-  policy_version: number;
+  /** 生成派生结果时的 schema 版本；不兼容的旧表会被重建。 */
+  schema_version: number;
   /** 派生记录创建时间。 */
   created_at: number;
 }
 
 /** 可参与摘要的稳定 Part 及其 canonical 位置。 */
-export interface StablePartCandidate {
+export interface StableContextPart {
   /** Part 所属完整 Message。 */
   message: SessionMessage;
   /** 具体 canonical Part。 */

package/src/types/session/SessionAgentMessageState.ts

@@ -1,13 +1,13 @@
 /**
  * Assistant Message 状态转换器的依赖类型。
  *
- * 该类型只暴露 canonical Message 所有者允许使用的最小能力，避免内部协作者
- * 复制 SessionMessages 的消息索引或 Mutation 发布状态。
+ * 该类型只暴露 canonical Message 运行时真正需要的协作能力：持久化边界与
+ * Message 缓存。缓存是 SessionMessages 与本模块共享的唯一边界，两者都单向依赖它，
+ * 不再需要互相回指的闭包。
  */
 
 import type { SessionStorage } from "@/types/store/SessionStorage.js";
-import type { SessionMessage } from "@downcity/type";
-import type { SessionMutation } from "@downcity/type";
+import type { SessionMessageCache } from "@/session/messages/SessionMessageCache.js";
 
 /** Assistant Message 状态转换器的构造参数。 */
 export interface SessionAgentMessageStateOptions {
@@ -15,16 +15,6 @@ export interface SessionAgentMessageStateOptions {
   session_id: string;
   /** 负责持久化 canonical Message 稳定检查点的 Store。 */
   store: SessionStorage;
-  /** 读取 SessionMessages 当前持有的 canonical Message 集合。 */
-  list_messages: () => Iterable<SessionMessage>;
-  /** 接受已持久化的完整 Message 快照，并按需发布 Mutation。 */
-  accept_message: (
-    message: SessionMessage,
-    publish_mutation?: boolean,
-  ) => void;
-  /** 接受未持久化的实时 Mutation，并只更新当前运行投影。 */
-  project_mutation: (
-    mutation: SessionMutation,
-    message: SessionMessage,
-  ) => void;
+  /** Message 运行缓存与 Mutation 发布边界。 */
+  cache: SessionMessageCache;
 }

package/src/types/session/SessionComposer.ts

@@ -1,20 +1,21 @@
 /**
  * Session Composer 类型。
  *
- * Composer 是最终模型输入的唯一生成者：它组合运行快照、canonical history 与内部
- * Context Policy；不拥有 Message、Turn 或数据库连接生命周期。
+ * Composer 是唯一回答「这一步模型看到什么」的组件：它把运行快照、canonical history
+ * 快照与自己的派生状态组装成一次模型 Step 输入，并在上下文压力出现时推进派生状态。
+ *
+ * 关键点（中文）
+ * - canonical history 与派生存储都由调用方传入，Composer 不主动访问 Session 存储。
+ * - 「压缩」不是独立概念，只是 `advance_context()` 的一种实现；不做任何推进也是合法实现。
+ * - Composer 不拥有 Message、Turn 或数据库连接生命周期，也不修改 canonical history。
  */
 
-import type { ModelClient, ModelMessage, RuntimeTool as Tool } from "@downcity/type";
-import type { SessionSystemMessage } from "@/executor/types/SessionPrompts.js";
+import type { ModelClient, ModelMessage, AgentTool } from "@downcity/type";
+import type { SessionSystemMessage } from "@downcity/type";
 import type { AgentSessionSystemBlock } from "@/types/agent/SessionTypes.js";
-import type { SessionHookContextBlock } from "@downcity/type";
-import type { ModelRequestFailureReporter } from "@/types/executor/ModelRequest.js";
-import type { SessionStorage } from "@/types/store/SessionStorage.js";
-import type {
-  SessionContextRecoveryReason,
-  SessionResolvedContextDiagnostics,
-} from "@/types/session/SessionContextPolicy.js";
+import type { SessionHookContextBlock, SessionMessage } from "@downcity/type";
+import type { ModelRequestFailureReporter } from "@/types/model/ModelRequest.js";
+import type { SessionDerivedStore } from "@/types/store/SessionStorage.js";
 
 /** Composer 可读取的 Session 身份快照。 */
 export interface SessionComposeIdentity {
@@ -41,29 +42,27 @@ export interface SessionComposeState {
   /** 当前 Step 生效的 Agent instruction 文本。 */
   systems: readonly string[];
   /** 当前 Step 可使用的工具集合。 */
-  tools: Readonly<Record<string, Tool>>;
+  tools: Readonly<Record<string, AgentTool>>;
   /** 当前 Step 生效的 instruction system blocks。 */
   instruction_system_blocks: readonly AgentSessionSystemBlock[];
-  /** 宿主注入的受托管 Plugin system blocks。 */
-  managed_plugin_system_blocks: readonly AgentSessionSystemBlock[];
-  /** 当前 Step 捕获的 Plugin system blocks。 */
-  plugin_system_blocks: readonly AgentSessionSystemBlock[];
-  /** 当前 Turn 冻结的 Plugin 动态上下文。 */
-  plugin_context_blocks: readonly SessionHookContextBlock[];
+  /** 当前 Step 捕获的扩展 system blocks。 */
+  power_system_blocks: readonly AgentSessionSystemBlock[];
+  /** 当前 Turn 冻结的 Power 动态上下文。 */
+  power_context_blocks: readonly SessionHookContextBlock[];
 }
 
 /** Composer 可读取的当前 Turn 快照。 */
 export interface SessionComposeTurn {
   /** 当前 Turn 标识；只读查询时允许为空。 */
   turn_id?: string;
-  /** 当前执行已进行的上下文恢复次数。 */
-  retry_count: number;
+  /** 当前执行已进行的上下文推进次数。 */
+  advance_count: number;
 }
 
 /** Composer 初始化输入。 */
 export interface SessionComposerInitializeInput {
-  /** 当前 Session 的统一持久化边界。 */
-  storage: SessionStorage;
+  /** 当前 Composer 命名空间内的派生表事务。 */
+  derived: SessionDerivedStore;
 }
 
 /** 单次模型输入组装参数。 */
@@ -72,26 +71,51 @@ export interface SessionComposeInput {
   session: SessionComposeIdentity;
   /** 当前 Step 已生效的运行状态。 */
   state: SessionComposeState;
-  /** 当前 Session 的统一持久化边界。 */
-  storage: SessionStorage;
+  /** 调用方读取的 canonical history 只读快照，按 sequence 升序。 */
+  history: readonly SessionMessage[];
+  /** 当前 Composer 命名空间内的派生表事务。 */
+  derived: SessionDerivedStore;
   /** 当前 Turn 快照。 */
   turn: SessionComposeTurn;
 }
 
-/** 上下文超限后的恢复输入。 */
-export interface SessionContextRecoveryInput {
+/** 触发一次派生上下文推进的稳定领域原因。 */
+export type SessionContextAdvanceTrigger =
+  /** Provider 明确拒绝超出上下文窗口的请求。 */
+  | "provider_context_limit"
+  /** Provider usage 已达到主动推进阈值。 */
+  | "usage_pressure";
+
+/** 上下文推进输入。 */
+export interface SessionContextAdvanceInput {
   /** 当前 Session 身份快照。 */
   session: SessionComposeIdentity;
-  /** 当前 Session 使用的模型。 */
+  /** 调用方读取的 canonical history 只读快照，按 sequence 升序。 */
+  history: readonly SessionMessage[];
+  /** 当前 Composer 命名空间内的派生表事务。 */
+  derived: SessionDerivedStore;
+  /** 触发本次推进的稳定领域原因。 */
+  trigger: SessionContextAdvanceTrigger;
+  /** 用于生成派生摘要的当前模型。 */
   model?: ModelClient;
-  /** 当前 Session 的统一持久化边界。 */
-  storage: SessionStorage;
-  /** 触发当前恢复的稳定领域原因。 */
-  reason: SessionContextRecoveryReason;
   /** 模型请求逐次失败的可选观测入口。 */
   on_model_request_failure?: ModelRequestFailureReporter;
 }
 
+/** Composer 对本次模型上下文的只读诊断。 */
+export interface SessionContextDiagnostics {
+  /** 生成当前上下文的 Composer 名称。 */
+  composer_name: string;
+  /** 当前上下文覆盖到的最新 canonical Message sequence。 */
+  through_sequence?: number;
+  /** 当前派生边界在 Message 内覆盖到的 Part sequence。 */
+  through_part_sequence?: number;
+  /** 当前上下文是否使用了派生摘要。 */
+  derived: boolean;
+  /** 当前使用的可选派生记录标识。 */
+  derivation_id?: string;
+}
+
 /** Composer 为一次模型 Step 生成的完整输入。 */
 export interface SessionStepInput {
   /** 当前 Step 的 system messages。 */
@@ -100,20 +124,24 @@ export interface SessionStepInput {
   system_blocks?: AgentSessionSystemBlock[];
   /** 当前 Step 已转换完成的标准模型消息。 */
   messages: ModelMessage[];
-  /** 当前 Step 可调用的工具集合。 */
-  tools: Record<string, Tool>;
-  /** 本次上下文策略诊断。 */
-  context_diagnostics?: SessionResolvedContextDiagnostics;
+  /** 当前 Step 可调用的工具集合；执行前由 StepInput 绑定调用环境。 */
+  tools: Record<string, AgentTool>;
+  /** 本次上下文组装诊断。 */
+  context_diagnostics?: SessionContextDiagnostics;
 }
 
 /** Session 级可替换 Composer。 */
 export interface SessionComposer {
-  /** Composer 的稳定可读名称。 */
+  /**
+   * Composer 稳定名称。
+   *
+   * 关键点（中文）：该值同时作为派生表命名空间，派生表前缀固定为 `composer_<name>_`。
+   */
   readonly name: string;
-  /** 初始化 Composer 及其内部 Policy。 */
+  /** 初始化当前 Composer 的派生 schema；没有派生状态时可以是空实现。 */
   initialize(input: SessionComposerInitializeInput): Promise<void>;
   /** 组装一次模型 Step 使用的最终输入。 */
   compose(input: SessionComposeInput): Promise<SessionStepInput>;
-  /** 尝试推进上下文派生状态；有效推进时返回 true。 */
-  recover_context(input: SessionContextRecoveryInput): Promise<boolean>;
+  /** 尝试推进派生上下文状态；发生有效推进时返回 true。 */
+  advance_context(input: SessionContextAdvanceInput): Promise<boolean>;
 }