@downcity/agent 1.1.430 → 1.1.437

package/src/tools/ask/AskQuestionsTool.ts

@@ -90,10 +90,12 @@ 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 };
     return {
       output: {
         status: "resolved",
-        answers: (result.response.payload as unknown as { answers: SessionInteractionAnswer[] }).answers,
+        answers: response_payload.answers,
+        ...(response_payload.note ? { note: response_payload.note } : {}),
       },
       messages: [],
     };

package/src/types/action/ActionResult.ts

@@ -3,15 +3,15 @@
  *
  * 关键点（中文）
  * - `output` 是标准 Tool Result，原样交给模型执行器和 canonical Tool Part。
- * - `messages` 是执行后写入 Session 的真实 User / Assistant Message 内容。
+ * - `messages` 是执行后产生的运行期 User 输入或 canonical Agent 内容。
  * - `effects` 是当前 Turn 只追加收集、并在收口检查点解释的已发生副作用。
  * - Message Parts 复用 Downcity Session UI 协议，不再建立文件、图片或 Plugin 专用桥接。
  */
 
 import type { RuntimeToolEffect } from "@downcity/type";
 import type {
-  SessionAssistantResultPart,
-  SessionPromptPart,
+  SessionAgentContent,
+  SessionModelUserContent,
 } from "@downcity/type";
 
 /** Action 执行后产生的一条 Session 消息。 */
@@ -19,14 +19,14 @@ export type ActionResultMessage =
   | {
       /** User 内容在下一 Step 生效。 */
       role: "user";
-      /** 等待进入 canonical User Message 的内容。 */
-      parts: SessionPromptPart[];
+      /** 只在当前 Turn 生效、不会伪装成 canonical Message 的模型输入。 */
+      parts: SessionModelUserContent[];
     }
   | {
-      /** Assistant 内容写入当前回复。 */
-      role: "assistant";
-      /** 等待进入 canonical Assistant Message 的内容。 */
-      parts: SessionAssistantResultPart[];
+      /** Agent 内容写入当前 canonical 回复。 */
+      role: "agent";
+      /** 等待追加到 canonical Agent Message 的内容。 */
+      parts: SessionAgentContent[];
     };
 
 /** Action 或 Tool 内部实现返回的统一结果。 */
@@ -34,7 +34,7 @@ export interface ActionResult<TOutput = unknown> {
   /** 返回给调用方、模型执行器与 canonical Tool Part 的标准执行输出。 */
   output: TOutput;
 
-  /** 执行产生的真实 Session 消息；没有附加消息时传入空数组。 */
+  /** 执行产生的运行期 User 输入或 Agent 输出；没有附加内容时传入空数组。 */
   messages: ActionResultMessage[];
 
   /** 已经发生且需要由当前 Turn 收集的副作用；不会发送给模型或直接持久化。 */

package/src/types/agent/AgentOptions.ts

@@ -11,6 +11,7 @@ import type {
   AgentManagedSession,
   SessionOptions,
 } from "@/types/session/SessionOptions.js";
+import type { SessionComposer } from "@/types/session/SessionComposer.js";
 
 /**
  * Agent 可使用的 Session 类。
@@ -88,4 +89,14 @@ export interface AgentOptions {
    */
   session_class?: AgentSessionConstructor;
 
+  /**
+   * 为每个 Session 创建独立 Composer 的工厂。
+   *
+   * 关键点（中文）
+   * - 每次创建、恢复或 fork Session 都会调用一次，禁止返回共享实例。
+   * - 省略时创建默认 `DefaultSessionComposer`。
+   * - Context Policy 应在工厂内部随 Composer 一起创建，避免跨 Session 共享派生状态。
+   */
+  session_composer?: () => SessionComposer;
+
 }

package/src/types/agent/AgentStorage.ts

@@ -6,7 +6,7 @@
  */
 
 import type { SessionStore } from "@/types/store/SessionStore.js";
-import type { FileSystem } from "@downcity/type";
+import type { FileSystem, StorageDatabaseLocation } from "@downcity/type";
 
 /** Agent 持有的 Session、日志与调度共享存储。 */
 export interface AgentStorage {
@@ -14,6 +14,8 @@ export interface AgentStorage {
   root_path: string;
   /** 受当前 Agent 根路径约束的文件能力。 */
   files: FileSystem;
+  /** Agent 私有结构化数据库使用的位置类型。 */
+  database_location: StorageDatabaseLocation;
   /** 当前 Agent 的 Session 集合存储。 */
   sessions: SessionStore;
 }

package/src/types/agent/SessionActor.ts

@@ -39,7 +39,6 @@ import type {
 } from "@downcity/type";
 import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
 import type { AgentSessionStopResult } from "@/types/sdk/AgentSessionStop.js";
-import type { AgentSessionCompactHandle } from "@/types/sdk/AgentSessionCompact.js";
 import type { AgentSessionTurnHandle } from "@/types/sdk/AgentSessionTurn.js";
 import type { SessionOrigin } from "@downcity/type";
 
@@ -88,15 +87,6 @@ export interface AgentSessionActor {
   /** 停止当前 turn，并取消尚未被吸收的排队 prompt。 */
   stop(): Promise<AgentSessionStopResult>;
 
-  /**
-   * 把一次显式历史压缩加入当前 Session 的有序输入队列。
-   *
-   * 关键点（中文）
-   * - 返回句柄表示 Command 已成功入队。
-   * - `handle.finished` 在压缩真正完成或失败后兑现。
-   */
-  compact(): Promise<AgentSessionCompactHandle>;
-
   /** 订阅当前 session 的未来事件。 */
   subscribe(
     subscriber: SessionMutationSubscriber,

package/src/types/agent/SessionTypes.ts

@@ -97,17 +97,17 @@ export interface AgentSessionSetInput {
 /** Session 配置提交后的 Action 可观测性选项。 */
 export interface AgentSessionSetOptions {
   /**
-   * 是否把真实配置变化持久化为 completed Action Message。
+   * 是否把真实配置变化持久化为包含 completed Action Part 的 Agent Message。
    *
    * 关键点（中文）
    * - 默认值为 true。
-   * - 设为 false 只关闭 Action Message，不影响配置写入与检查点提交。
+   * - 设为 false 只关闭 Action Part 历史，不影响配置写入与检查点提交。
    * - 适用于 Session 初始化、恢复与其他不应进入时间线的宿主装配流程。
    */
   persist_action?: boolean;
 
   /**
-   * 是否在 Action Message 持久化成功后发布对应 Session Mutation。
+   * 是否在 Action Part 所属 Agent Message 持久化成功后发布对应 Session Mutation。
    *
    * 关键点（中文）
    * - 默认跟随 `persist_action`。
@@ -181,7 +181,7 @@ export interface AgentSessionTimelineEvent {
    * 说明（中文）
    * - `tool-call` / `tool-result` 用于把 assistant 内部工具过程平铺给 UI。
    */
-  role: "user" | "assistant" | "tool-call" | "tool-result" | "action";
+  role: "user" | "agent" | "tool-call" | "tool-result" | "action";
   /** 事件时间戳（毫秒）。 */
   ts?: number;
   /** 事件所属消息种类。 */
@@ -289,7 +289,7 @@ export interface AgentSessionSummary {
    * 当前 session 可读标题。
    *
    * 说明（中文）
-   * - 标题持久化在 session `meta.json` 顶层。
+   * - 标题持久化在 Session SQLite 的 `session_state` 中。
    * - SDK 只在模型成功生成标题时写入，不再从首条用户消息生成 fallback。
    * - 标题允许为空，调用方需要展示占位文案时可自行回退到 `session_id`。
    */

package/src/types/executor/SessionAssistantOutput.ts

@@ -5,8 +5,8 @@
  */
 
 import type { ModelStreamEvent } from "@downcity/type";
-import type { SessionAssistantResultPart } from "@downcity/type";
-import type { SessionAssistantMessagePart } from "@downcity/type";
+import type { SessionAgentContent } from "@downcity/type";
+import type { SessionAgentMessagePart } from "@downcity/type";
 import type {
   SessionToolExecutionResult,
   SessionToolInputReady,
@@ -23,13 +23,24 @@ export interface SessionAssistantOutput {
   /** 写入 Tool 执行终态。 */
   write_tool_result(result: SessionToolExecutionResult): Promise<void>;
   /** 使用模型流聚合出的 canonical Parts 校验当前 Step。 */
-  finish_step(parts: SessionAssistantMessagePart[]): Promise<void>;
+  finish_step(parts: SessionAgentMessagePart[]): Promise<void>;
   /** 放弃当前未完成 Step 的临时作用域。 */
   abort_step(): Promise<void>;
   /** User steer 插入前关闭当前连续 Assistant Message。 */
   close_current_message(): Promise<void>;
   /** 把 Action 产生的封闭内容追加到当前 Assistant Message。 */
-  append_result_parts(parts: readonly SessionAssistantResultPart[]): Promise<void>;
+  append_result_parts(parts: readonly SessionAgentContent[]): Promise<SessionAgentMessagePart[]>;
+  /** 在 Turn 收口产物之前追加用户可见的 canonical Error Part。 */
+  append_error(input: {
+    /** 错误影响范围。 */
+    scope: "session" | "turn";
+    /** 稳定错误码。 */
+    code: string;
+    /** 用户可见错误信息。 */
+    message: string;
+    /** 当前错误是否允许重试恢复。 */
+    recoverable: boolean;
+  }): Promise<void>;
   /** 按 Turn 最终结果收口 Assistant 输出。 */
   finish(input: {
     /** Assistant 最终状态。 */

package/src/types/executor/SessionTurnContext.ts

@@ -9,8 +9,11 @@
 
 import type { RuntimeToolEffect } from "@downcity/type";
 import type { ShellApprovalGateway } from "@downcity/type";
-import type { SessionUserMessage } from "@downcity/type";
-import type { SessionAssistantResultPart } from "@downcity/type";
+import type {
+  SessionModelUserContent,
+  SessionUserMessage,
+} from "@downcity/type";
+import type { SessionAgentContent } from "@downcity/type";
 import type { SessionAssistantOutput } from "@/types/executor/SessionAssistantOutput.js";
 import type { SessionHookContext } from "@downcity/type";
 import type { SessionHookScopeRuntime } from "@downcity/type";
@@ -45,15 +48,17 @@ export interface SessionTurnContextInit {
   /** 上游取消信号；上下文会把它转发到自身拥有的运行生命周期。 */
   abort_signal?: AbortSignal;
 
-  /** 在 Step 检查点消费 Session 队列，并返回应并入模型上下文的 User 消息。 */
-  merge_step_input?: () => Promise<SessionUserMessage[]>;
+  /** 在 Step 检查点提交 Session 输入队列；持久化消息由 Composer 重新读取。 */
+  commit_step_input?: () => Promise<void>;
+
+  /** 将 Executor 产生的内部模型输入持久化为当前 Turn 的 canonical User Message。 */
+  append_internal_user_message?: (
+    parts: readonly SessionModelUserContent[],
+  ) => Promise<SessionUserMessage>;
 
   /** 判断是否仍有等待下一个 Step 消费的 User prompt。 */
   has_pending_step_input?: () => boolean;
 
-  /** 消费一次 canonical history 重载请求。 */
-  consume_history_reload?: () => boolean;
-
   /** Executor 写入 canonical Assistant Message 使用的唯一输出端口。 */
   assistant_output?: SessionAssistantOutput;
 
@@ -142,25 +147,23 @@ export interface SessionTurnContext {
     hook_context(call_id?: string): SessionHookContext;
   };
 
-  /** 当前运行的动态 User 输入及延迟持久化输入。 */
+  /** 当前运行的动态 User 输入。 */
   readonly input: {
-    /** 在 Step 边界消费运行期注入消息与 Session 队列消息。 */
-    checkpoint(): Promise<SessionUserMessage[]>;
+    /** 登记已经持久化、属于本 Turn 的 canonical User Message。 */
+    observe_user_message(message: SessionUserMessage): void;
 
-    /** 判断是否有等待下一个 Step 消费的 Session prompt。 */
-    has_pending(): boolean;
+    /** 返回本 Turn 已登记 User Message 的不可变快照。 */
+    user_messages(): readonly SessionUserMessage[];
 
-    /** 注入一条只影响当前运行、在下一 Step 生效的 User 消息。 */
-    inject_user_message(message: SessionUserMessage): void;
+    /** 提交输入队列；下一 Step 由 Composer 重新读取 canonical history。 */
+    checkpoint(): Promise<void>;
 
-    /** 延迟到 Assistant 结果落盘后再持久化一条 User 消息。 */
-    defer_user_message(message: SessionUserMessage): void;
+    /** 判断是否有等待下一个 Step 消费的 Session prompt。 */
+    has_pending(): boolean;
 
-    /** 返回延迟持久化 User 消息的不可变快照。 */
-    deferred_user_messages(): readonly SessionUserMessage[];
+    /** 持久化一条只供模型消费的内部 canonical User Message。 */
+    append_internal(parts: readonly SessionModelUserContent[]): Promise<SessionUserMessage>;
 
-    /** 消费一次 canonical history 重载请求。 */
-    consume_history_reload(): boolean;
   };
 
   /** 当前运行的 Assistant Message 与辅助 Action 输出能力。 */
@@ -169,10 +172,10 @@ export interface SessionTurnContext {
     readonly assistant?: SessionAssistantOutput;
 
     /** 把 Action 产生的 Assistant Parts 加入当前 Step 收口队列。 */
-    enqueue_assistant_parts(parts: readonly SessionAssistantResultPart[]): void;
+    enqueue_assistant_parts(parts: readonly SessionAgentContent[]): void;
 
     /** 消费当前 Step 中等待写入 canonical Assistant Message 的 Parts。 */
-    take_assistant_parts(): SessionAssistantResultPart[];
+    take_assistant_parts(): SessionAgentContent[];
 
     /** 发布一条不进入 LLM 输入的 Session Action。 */
     publish_action(event: AgentSessionActionEvent): Promise<void>;

package/src/types/sdk/AgentSessionAction.ts

@@ -2,7 +2,7 @@
  * Agent Session action 公开类型。
  *
  * 关键点（中文）
- * - Action 运行事件由 Session 收口为 canonical `SessionActionMessage`。
+ * - Action 运行事件由 Session 收口为 canonical `SessionAgentActionPart`。
  * - Action 不进入模型输入。
  */
 

package/src/types/sdk/AgentSessionPrompt.ts

@@ -6,7 +6,7 @@
  * - 首条输入、运行中补充输入、排队到下一轮的输入，调用侧都使用同一结构。
  */
 
-import type { SessionPromptPart } from "@downcity/type";
+import type { SessionUserContent } from "@downcity/type";
 
 /**
  * Session user message part 类型。
@@ -15,7 +15,7 @@ import type { SessionPromptPart } from "@downcity/type";
  * - 这是 Downcity Session 输入边界，不依赖模型协议或第三方 SDK。
  * - 可直接用于 `session.prompt({ query: [...parts] })` 传入 text、context、file 等 parts。
  */
-export type SessionUserMessagePart = SessionPromptPart;
+export type AgentSessionPromptContent = SessionUserContent;
 
 /**
  * Session prompt 输入。
@@ -44,17 +44,27 @@ export type SessionUserMessagePart = SessionPromptPart;
  * - 远程 Session 中，Data URL 在服务端落盘；调用方本地路径必须对服务端可访问。
  */
 export interface AgentSessionPromptInput {
+  /**
+   * 调用方为同一业务输入提供的稳定幂等标识。
+   *
+   * 说明（中文）
+   * - 相同 Session 内重复提交同一个 `request_id`，只会创建一条 canonical User Message。
+   * - 已完成的请求直接返回原 Turn 结果；进程重启后未完成的请求会复用原 Turn 恢复执行。
+   * - 不同业务输入不得复用同一个值；不需要跨进程重试的交互式调用可以省略。
+   */
+  request_id?: string;
+
   /**
    * 当前这次要追加到 Session 的用户文本或 parts 数组。
    *
    * 说明（中文）
    * - 支持两种格式：
    *   1. `string`：纯文本用户输入，Session 会将其包装为用户消息。
-   *   2. `SessionUserMessagePart[]`：Downcity Session user parts，可直接携带 text、context、file 等内容。
+   *   2. `AgentSessionPromptContent[]`：Downcity Session 内容，可直接携带 text、context、file 等内容。
    * - 调用侧永远只传"新的用户输入"。
    * - 它是否并入当前 turn，还是排到下一 turn，由 Session 内部决定。
    */
-  query: string | SessionUserMessagePart[];
+  query: string | AgentSessionPromptContent[];
 }
 
 /**
@@ -62,7 +72,7 @@ export interface AgentSessionPromptInput {
  *
  * 说明（中文）
  * - `string`：trim 后为空即视为空。
- * - `SessionUserMessagePart[]`：数组为空，或仅包含空文本和空 Context 时视为空。
+ * - `AgentSessionPromptContent[]`：数组为空，或仅包含空文本和空 Context 时视为空。
  */
 export function is_agent_session_prompt_input_empty(input: AgentSessionPromptInput): boolean {
   const query = input.query;

package/src/types/session/AdaptivePartContextPolicy.ts

@@ -0,0 +1,37 @@
+/**
+ * AdaptivePartContextPolicy 内部持久化与候选类型。
+ *
+ * 类型集中在 types 目录，策略模块只保留上下文选择行为。
+ */
+
+import type {
+  SessionAgentMessagePart,
+  SessionMessage,
+  SessionUserMessagePart,
+} from "@downcity/type";
+
+/** Part 级累计摘要 checkpoint。 */
+export interface AdaptivePartCheckpointRow {
+  /** checkpoint 稳定标识。 */
+  checkpoint_id: string;
+  /** 边界所属 Message 标识。 */
+  through_message_id: string;
+  /** 边界所属 Message sequence。 */
+  through_message_sequence: number;
+  /** 边界 Part sequence。 */
+  through_part_sequence: number;
+  /** 累计摘要正文。 */
+  summary: string;
+  /** 生成派生结果的策略版本。 */
+  policy_version: number;
+  /** 派生记录创建时间。 */
+  created_at: number;
+}
+
+/** 可参与摘要的稳定 Part 及其 canonical 位置。 */
+export interface StablePartCandidate {
+  /** Part 所属完整 Message。 */
+  message: SessionMessage;
+  /** 具体 canonical Part。 */
+  part: SessionUserMessagePart | SessionAgentMessagePart;
+}

package/src/types/session/{SessionAssistantMessageState.ts → SessionAgentMessageState.ts}

@@ -5,16 +5,16 @@
  * 复制 SessionMessages 的消息索引或 Mutation 发布状态。
  */
 
-import type { SessionMessageStore } from "@/types/store/SessionDataStore.js";
+import type { SessionStorage } from "@/types/store/SessionStorage.js";
 import type { SessionMessage } from "@downcity/type";
 import type { SessionMutation } from "@downcity/type";
 
 /** Assistant Message 状态转换器的构造参数。 */
-export interface SessionAssistantMessageStateOptions {
+export interface SessionAgentMessageStateOptions {
   /** 当前 Assistant Message 所属 Session 的稳定标识。 */
   session_id: string;
-  /** 负责持久化 canonical Message 与 Assistant 草稿的 Store。 */
-  store: SessionMessageStore;
+  /** 负责持久化 canonical Message 稳定检查点的 Store。 */
+  store: SessionStorage;
   /** 读取 SessionMessages 当前持有的 canonical Message 集合。 */
   list_messages: () => Iterable<SessionMessage>;
   /** 接受已持久化的完整 Message 快照，并按需发布 Mutation。 */
@@ -22,8 +22,8 @@ export interface SessionAssistantMessageStateOptions {
     message: SessionMessage,
     publish_mutation?: boolean,
   ) => void;
-  /** 接受已持久化的增量 Mutation，并更新 canonical Message 快照。 */
-  accept_mutation: (
+  /** 接受未持久化的实时 Mutation，并只更新当前运行投影。 */
+  project_mutation: (
     mutation: SessionMutation,
     message: SessionMessage,
   ) => void;

package/src/types/session/SessionCommand.ts

@@ -4,8 +4,19 @@
  * Command 只存在于 Session 运行进程内，不属于 Remote Transport 协议，也不持久化。
  */
 
-/** Session Command 构造参数。 */
-export interface SessionCommandOptions {
+/** Session Command 的执行类别。 */
+export type SessionCommandKind =
+  /** Prompt Command 需要创建或加入一个 Turn。 */
+  | "prompt"
+  /** Maintenance Command 可以在 Session 空闲期独立执行。 */
+  | "maintenance";
+
+/** Session 有序输入队列中的 Command。 */
+export interface SessionCommand {
+  /** 当前 Command 的执行类别。 */
+  kind: SessionCommandKind;
+  /** Prompt 恢复执行时要求复用的稳定 Turn ID。 */
+  turn_id?: string;
   /** Command 出队后执行的完整行为。 */
   execute: () => Promise<void>;
   /** Session stop 时取消该 Command 的可选行为；未提供时 Command 继续保留。 */
@@ -14,16 +25,19 @@ export interface SessionCommandOptions {
   completion?: SessionCommandCompletion;
 }
 
+/** Session facade 创建 Command 时使用的输入。 */
+export type SessionCommandOptions = SessionCommand;
+
 /** Session Command 成功执行后的 canonical 持久化信息。 */
 export interface SessionCommandCompletion {
-  /** 完成信息固定持久化为 Action Message。 */
+  /** 完成信息固定持久化为 Agent Message 内的 Action Part。 */
   type: "action";
-  /** Action Message 使用的稳定业务标识。 */
+  /** Action Part 及其所属 Agent Message 共用的稳定业务标识。 */
   id: string;
-  /** Action Message 展示的用户可读标题。 */
+  /** Action Part 展示的用户可读标题。 */
   title: string;
-  /** Action Message 展示的可选结果说明。 */
+  /** Action Part 展示的可选结果说明。 */
   description?: string;
-  /** Action Message 持久化后是否发布对应 Session Mutation。 */
+  /** Action Part 所属 Agent Message 持久化后是否发布对应 Session Mutation。 */
   publish_mutation?: boolean;
 }

package/src/types/session/SessionComposer.ts

@@ -1,17 +1,20 @@
 /**
  * Session Composer 类型。
  *
- * Composer 是自定义 Session 的执行策略边界：它只读取 Session 的只读快照，
- * 负责组装模型输入和生成压缩计划，不持久化 Message、Metadata 或事件。
+ * Composer 是最终模型输入的唯一生成者：它组合运行快照、canonical history 与内部
+ * Context Policy；不拥有 Message、Turn 或数据库连接生命周期。
  */
 
-import type { ModelClient, ModelMessage } from "@downcity/type";
-import type { RuntimeTool as Tool } from "@downcity/type";
+import type { ModelClient, ModelMessage, RuntimeTool as Tool } from "@downcity/type";
 import type { SessionSystemMessage } from "@/executor/types/SessionPrompts.js";
 import type { AgentSessionSystemBlock } from "@/types/agent/SessionTypes.js";
-import type { SessionContextSnapshot, SessionSegmentSummary } from "@/types/session/SessionSegment.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";
 
 /** Composer 可读取的 Session 身份快照。 */
 export interface SessionComposeIdentity {
@@ -19,9 +22,9 @@ export interface SessionComposeIdentity {
   agent_id: string;
   /** 当前 Session 的稳定标识。 */
   session_id: string;
-  /** 当前 Agent 项目的绝对根目录。 */
+  /** 当前 Workspace 的绝对根目录。 */
   project_root: string;
-  /** 当前 Session 的创建时间戳，单位为毫秒。 */
+  /** 当前 Session 的创建时间戳。 */
   created_at: number;
   /** 当前 Session 使用的参考时区。 */
   timezone: string;
@@ -29,11 +32,11 @@ export interface SessionComposeIdentity {
 
 /** Composer 可读取的当前 Step 生效状态。 */
 export interface SessionComposeState {
-  /** 当前 Step 使用的模型实例；只读查询允许为空。 */
+  /** 当前 Step 使用的模型实例。 */
   model?: ModelClient;
-  /** 当前模型声明的上下文窗口，单位为 token。 */
+  /** 当前模型声明的上下文窗口。 */
   model_context_window?: number;
-  /** 当前 Step 生效的 Agent 环境变量快照。 */
+  /** 当前 Step 生效的 Workspace 环境变量。 */
   env: Readonly<Record<string, string>>;
   /** 当前 Step 生效的 Agent instruction 文本。 */
   systems: readonly string[];
@@ -41,79 +44,76 @@ export interface SessionComposeState {
   tools: Readonly<Record<string, Tool>>;
   /** 当前 Step 生效的 instruction system blocks。 */
   instruction_system_blocks: readonly AgentSessionSystemBlock[];
-  /** 当前 Session 由宿主注入的受托管 Plugin system blocks。 */
+  /** 宿主注入的受托管 Plugin system blocks。 */
   managed_plugin_system_blocks: readonly AgentSessionSystemBlock[];
   /** 当前 Step 捕获的 Plugin system blocks。 */
   plugin_system_blocks: readonly AgentSessionSystemBlock[];
-  /** 当前 Turn 首次解析后复用、只进入模型输入副本的 Plugin 动态上下文。 */
+  /** 当前 Turn 冻结的 Plugin 动态上下文。 */
   plugin_context_blocks: readonly SessionHookContextBlock[];
 }
 
 /** Composer 可读取的当前 Turn 快照。 */
 export interface SessionComposeTurn {
-  /** 当前 Turn 标识；只读查询场景允许为空。 */
+  /** 当前 Turn 标识；只读查询时允许为空。 */
   turn_id?: string;
-  /** 当前执行因上下文超限而进行的重试次数。 */
+  /** 当前执行已进行的上下文恢复次数。 */
   retry_count: number;
 }
 
+/** Composer 初始化输入。 */
+export interface SessionComposerInitializeInput {
+  /** 当前 Session 的统一持久化边界。 */
+  storage: SessionStorage;
+}
+
 /** 单次模型输入组装参数。 */
 export interface SessionComposeInput {
   /** 当前 Session 身份快照。 */
   session: SessionComposeIdentity;
   /** 当前 Step 已生效的运行状态。 */
   state: SessionComposeState;
-  /** 当前 Session 的累计 Summary 与 Active Message 快照。 */
-  history: Readonly<SessionContextSnapshot>;
+  /** 当前 Session 的统一持久化边界。 */
+  storage: SessionStorage;
   /** 当前 Turn 快照。 */
   turn: SessionComposeTurn;
 }
 
+/** 上下文超限后的恢复输入。 */
+export interface SessionContextRecoveryInput {
+  /** 当前 Session 身份快照。 */
+  session: SessionComposeIdentity;
+  /** 当前 Session 使用的模型。 */
+  model?: ModelClient;
+  /** 当前 Session 的统一持久化边界。 */
+  storage: SessionStorage;
+  /** 触发当前恢复的稳定领域原因。 */
+  reason: SessionContextRecoveryReason;
+  /** 模型请求逐次失败的可选观测入口。 */
+  on_model_request_failure?: ModelRequestFailureReporter;
+}
+
 /** Composer 为一次模型 Step 生成的完整输入。 */
 export interface SessionStepInput {
   /** 当前 Step 的 system messages。 */
   system: SessionSystemMessage[];
-  /** 当前 Step 的可解释 system block；自定义 Composer 可以省略。 */
+  /** 当前 Step 的可解释 system blocks。 */
   system_blocks?: AgentSessionSystemBlock[];
   /** 当前 Step 已转换完成的标准模型消息。 */
   messages: ModelMessage[];
   /** 当前 Step 可调用的工具集合。 */
   tools: Record<string, Tool>;
+  /** 本次上下文策略诊断。 */
+  context_diagnostics?: SessionResolvedContextDiagnostics;
 }
 
-/** 持久化上下文压缩所需的最小只读输入。 */
-export interface SessionCompactionInput {
-  /** 当前 Session 的稳定身份快照。 */
-  session: SessionComposeIdentity;
-  /** 当前 Session 实际使用的模型；只读或未配置场景允许为空。 */
-  model?: ModelClient;
-  /** 当前 Session 的累计 Summary 与 Active Message 快照。 */
-  history: Readonly<SessionContextSnapshot>;
-  /** 可选的模型请求逐次失败通知入口。 */
-  on_model_request_failure?: ModelRequestFailureReporter;
-}
-
-/** Composer 生成、等待 SessionMessages 提交的压缩计划。 */
-export interface SessionCompactionPlan {
-  /** Active 中最后一条需要移入 Segment 的 Message sequence。 */
-  through_sequence: number;
-  /** 新 Segment 使用的累计 Summary。 */
-  summary: SessionSegmentSummary;
-  /** 当前计划覆盖到的最后一条 Message 标识。 */
-  boundary_message_id: string;
-}
-
-/** Session 级可替换执行策略。 */
+/** Session 级可替换 Composer。 */
 export interface SessionComposer {
   /** Composer 的稳定可读名称。 */
   readonly name: string;
-
-  /** 组装一次模型 Step 使用的 system、history 与 tools。 */
+  /** 初始化 Composer 及其内部 Policy。 */
+  initialize(input: SessionComposerInitializeInput): Promise<void>;
+  /** 组装一次模型 Step 使用的最终输入。 */
   compose(input: SessionComposeInput): Promise<SessionStepInput>;
-
-  /** 根据只读历史生成压缩计划；无需压缩时返回空。 */
-  compact(input: SessionCompactionInput): Promise<SessionCompactionPlan | null>;
-
-  /** 判断给定错误是否应在持久化压缩后重试。 */
-  should_compact(error: unknown): boolean;
+  /** 尝试推进上下文派生状态；有效推进时返回 true。 */
+  recover_context(input: SessionContextRecoveryInput): Promise<boolean>;
 }