@downcity/agent 1.1.408 → 1.1.437

package/src/types/group/GroupSession.ts

@@ -3,8 +3,8 @@
 import type { AgentSession } from "@/types/agent/SessionActor.js";
 import type { GroupMessage } from "@/types/group/Group.js";
 import type { Agent } from "@/agent/Agent.js";
-import type { WorkspaceBase } from "@downcity/workspace";
-import type { RespondSessionInteractionInput, SessionInteractionRequest } from "@/types/session/SessionInteraction.js";
+import type { WorkspaceRuntime } from "@downcity/type";
+import type { RespondSessionInteractionInput, SessionInteractionRequest } from "@downcity/type";
 
 /** Group 成员运行态。 */
 export interface GroupMemberRuntime {
@@ -20,6 +20,7 @@ export type GroupStatusPhase = "idle" | "dispatching" | "dispatched" | "executin
 /** GroupSession 的统一实时事件。 */
 export type GroupEvent =
   | { /** 事件类型。 */ readonly type: "message"; /** 新增的共享消息。 */ readonly message: GroupMessage }
+  | { /** 事件类型。 */ readonly type: "title"; /** 当前 GroupSession 最新的 canonical 标题。 */ readonly title: string }
   | { /** 事件类型。 */ readonly type: "interaction"; /** 发起交互的成员 Agent。 */ readonly agent_id: string; /** 成员 Session 的交互请求。 */ readonly request: SessionInteractionRequest }
   | { /** 事件类型。 */ readonly type: "status"; /** 当前群聊轮次。 */ readonly turn_id?: string; /** 当前轮次对应的消息标识。 */ readonly message_id?: string; /** 当前运行阶段。 */ readonly phase: GroupStatusPhase; /** Dispatch 完成后实际接受消息的成员标识。 */ readonly dispatched_member_ids?: readonly string[]; /** 成员运行态快照。 */ readonly members: readonly GroupMemberRuntime[] };
 
@@ -59,6 +60,8 @@ export interface GroupSessionSummary {
   readonly message_count: number;
   /** 当前 GroupSession 绑定的 Workspace 标识。 */
   readonly workspace_id?: string;
+  /** 当前 GroupSession 持久化的用户可见标题。 */
+  readonly title?: string;
   /** 最后一条消息的用户可见预览。 */
   readonly preview_text?: string;
 }
@@ -66,13 +69,13 @@ export interface GroupSessionSummary {
 /** GroupSession 的创建输入；第一阶段不允许调用方指定 session_id。 */
 export interface GroupSessionCreateInput {
   /** 当前群聊使用的 Workspace；省略时使用内存执行上下文。 */
-  readonly workspace?: WorkspaceBase;
+  readonly workspace?: WorkspaceRuntime;
 }
 
 /** 恢复 GroupSession 时的上下文输入。 */
 export interface GroupSessionGetInput {
   /** 当前群聊使用的 Workspace；必须与持久化 metadata 一致。 */
-  readonly workspace?: WorkspaceBase;
+  readonly workspace?: WorkspaceRuntime;
 }
 
 /** GroupSession 列表过滤条件。 */
@@ -89,6 +92,8 @@ export interface GroupSessionContract {
   readonly group_id: string;
   /** 当前 GroupSession 绑定的 Workspace ID；未绑定时为空。 */
   readonly workspace_id?: string;
+  /** 修改当前 GroupSession 的 canonical 用户可见标题。 */
+  rename(title: string): Promise<string>;
   /** 立即追加用户消息并开始异步群聊调度。 */
   prompt(input: GroupPromptInput): Promise<GroupPromptResult>;
   /** 读取共享消息事实快照。 */

package/src/types/group/GroupSessionStore.ts

@@ -1,8 +1,8 @@
 /** GroupSession 持久化协议：只描述 GroupSession 所需的底层数据能力。 */
 
 import type { GroupMessage } from "@/types/group/Group.js";
-import type { GroupDispatchSessionDataStore } from "@/types/group/GroupDispatchSession.js";
-import type { FileSystem } from "@downcity/workspace";
+import type { GroupDispatchTurnRecord } from "@/types/group/GroupDispatch.js";
+import type { FileSystem } from "@downcity/type";
 
 /** GroupSession 的持久化元数据。 */
 export interface GroupSessionHistoryMeta {
@@ -14,6 +14,8 @@ export interface GroupSessionHistoryMeta {
   readonly group_id: string;
   /** 当前 GroupSession 绑定的 Workspace 标识；未绑定时为空。 */
   readonly workspace_id?: string;
+  /** 当前 GroupSession 持久化的用户可见标题。 */
+  readonly title?: string;
   /** 首次创建时间戳。 */
   readonly created_at: number;
   /** 最近更新时间戳。 */
@@ -46,8 +48,6 @@ export interface GroupSessionTurnCheckpoint {
 export interface GroupSessionDataStore {
   /** 当前 GroupSession 标识。 */
   readonly session_id: string;
-  /** 当前 GroupSession 独享的 Dispatch Session 持久化视图。 */
-  readonly dispatch_session: GroupDispatchSessionDataStore;
   /** 初始化当前 GroupSession 的存储布局。 */
   initialize(): Promise<void>;
   /** 读取完整共享消息历史。 */
@@ -60,6 +60,10 @@ export interface GroupSessionDataStore {
   write_metadata(metadata: GroupSessionHistoryMeta): Promise<void>;
   /** 在文件锁内合并更新当前 GroupSession metadata。 */
   update_metadata(patch: Partial<GroupSessionHistoryMeta>): Promise<GroupSessionHistoryMeta>;
+  /** 读取当前 GroupSession 中每个 dispatch_id 的最新调度 Turn 快照。 */
+  list_dispatch_turns(): Promise<GroupDispatchTurnRecord[]>;
+  /** 向当前 GroupSession 的调度审计日志追加一个 Turn 状态快照。 */
+  append_dispatch_turn(turn: GroupDispatchTurnRecord): Promise<void>;
 }
 
 /** Group 所拥有的全部 GroupSession 持久化入口。 */

package/src/types/sdk/AgentSessionAction.ts

@@ -2,14 +2,14 @@
  * Agent Session action 公开类型。
  *
  * 关键点（中文）
- * - Action 运行事件由 Session 收口为 canonical `SessionActionMessage`。
+ * - Action 运行事件由 Session 收口为 canonical `SessionAgentActionPart`。
  * - Action 不进入模型输入。
  */
 
 import type {
   SessionActionEvent,
   SessionActionStatus,
-} from "@/types/session/SessionAction.js";
+} from "@downcity/type";
 
 /**
  * Session action 当前状态。

package/src/types/sdk/AgentSessionPrompt.ts

@@ -6,16 +6,16 @@
  * - 首条输入、运行中补充输入、排队到下一轮的输入，调用侧都使用同一结构。
  */
 
-import type { SessionPromptPart } from "@/types/session/SessionContent.js";
+import type { SessionUserContent } from "@downcity/type";
 
 /**
  * Session user message part 类型。
  *
  * 说明（中文）
  * - 这是 Downcity Session 输入边界，不依赖模型协议或第三方 SDK。
- * - 可直接用于 `session.prompt({ query: [...parts] })` 传入 text parts、file parts 等。
+ * - 可直接用于 `session.prompt({ query: [...parts] })` 传入 text、context、file 等 parts。
  */
-export type SessionUserMessagePart = SessionPromptPart;
+export type AgentSessionPromptContent = SessionUserContent;
 
 /**
  * Session prompt 输入。
@@ -24,6 +24,7 @@ export type SessionUserMessagePart = SessionPromptPart;
  * ```ts
  * session.prompt({
  *   query: [
+ *     { type: "context", tag: "reference", context: "此前引用的消息" },
  *     { type: "text", text: "请分析这个附件" },
  *     {
  *       type: "file",
@@ -43,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、file 等内容。
+   *   2. `AgentSessionPromptContent[]`：Downcity Session 内容，可直接携带 text、context、file 等内容。
    * - 调用侧永远只传"新的用户输入"。
    * - 它是否并入当前 turn，还是排到下一 turn，由 Session 内部决定。
    */
-  query: string | SessionUserMessagePart[];
+  query: string | AgentSessionPromptContent[];
 }
 
 /**
@@ -61,7 +72,7 @@ export interface AgentSessionPromptInput {
  *
  * 说明（中文）
  * - `string`：trim 后为空即视为空。
- * - `SessionUserMessagePart[]`：数组为空或仅包含空文本时视为空。
+ * - `AgentSessionPromptContent[]`：数组为空，或仅包含空文本和空 Context 时视为空。
  */
 export function is_agent_session_prompt_input_empty(input: AgentSessionPromptInput): boolean {
   const query = input.query;
@@ -72,9 +83,11 @@ export function is_agent_session_prompt_input_empty(input: AgentSessionPromptInp
     if (query.length === 0) {
       return true;
     }
-    // 如果所有 parts 都是空文本，也视为空
+    // 只有空文本与空 Context 的输入没有可执行语义。
     return query.every((part) => {
-      return part.type === "text" && part.text.trim() === "";
+      if (part.type === "text") return part.text.trim() === "";
+      if (part.type === "context") return part.context.trim() === "";
+      return false;
     });
   }
   return true;

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/SessionAgentMessageState.ts

@@ -0,0 +1,30 @@
+/**
+ * Assistant Message 状态转换器的依赖类型。
+ *
+ * 该类型只暴露 canonical Message 所有者允许使用的最小能力，避免内部协作者
+ * 复制 SessionMessages 的消息索引或 Mutation 发布状态。
+ */
+
+import type { SessionStorage } from "@/types/store/SessionStorage.js";
+import type { SessionMessage } from "@downcity/type";
+import type { SessionMutation } from "@downcity/type";
+
+/** Assistant Message 状态转换器的构造参数。 */
+export interface SessionAgentMessageStateOptions {
+  /** 当前 Assistant Message 所属 Session 的稳定标识。 */
+  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;
+}

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,15 +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 {
@@ -17,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;
@@ -27,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[];
@@ -39,75 +44,76 @@ export interface SessionComposeState {
   tools: Readonly<Record<string, Tool>>;
   /** 当前 Step 生效的 instruction system blocks。 */
   instruction_system_blocks: readonly AgentSessionSystemBlock[];
-  /** 当前 Session 由宿主注入的 system blocks。 */
+  /** 宿主注入的受托管 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[];
 }
 
 /** 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>;
-}
-
-/** 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>;
 }

package/src/types/session/SessionComposition.ts

@@ -0,0 +1,52 @@
+/**
+ * Session system 快照与模型输入组装的依赖类型。
+ *
+ * 这些字段共同描述 composition 领域所需的最小只读资源；SessionComposition 不拥有
+ * Message、Store、Model 或 Plugin 生命周期。
+ */
+
+import type { ModelClient, RuntimeTool as Tool } from "@downcity/type";
+import type { AgentSessionSystemBlock } from "@/types/agent/SessionTypes.js";
+import type { SessionOrigin } from "@downcity/type";
+import type { SessionStorage } from "@/types/store/SessionStorage.js";
+import type { SessionHookRuntime } from "@downcity/type";
+import type { SessionComposer } from "@/types/session/SessionComposer.js";
+import type { Logger } from "@/utils/logger/Logger.js";
+
+/** SessionComposition 构造参数。 */
+export interface SessionCompositionOptions {
+  /** 当前 Session 所属 Agent 的稳定标识。 */
+  agent_id: string;
+  /** 当前 Session 的稳定标识。 */
+  session_id: string;
+  /** 当前 Session 的创建来源。 */
+  session_origin: SessionOrigin;
+  /** 当前 Session 使用的 Workspace 绝对根目录。 */
+  workspace_path: string;
+  /** 当前 Session 的领域持久化视图。 */
+  store: SessionStorage;
+  /** 当前 Session 使用的统一 Composer。 */
+  composer: SessionComposer;
+  /** 在每个 Step 检查点读取当前可用 Tool 集合。 */
+  get_tools: () => Record<string, Tool>;
+  /** 当前 Session 创建时捕获的 instruction system blocks。 */
+  instruction_system_blocks: AgentSessionSystemBlock[];
+  /** 显式 syncshot 时读取 Agent 最新 instruction system blocks。 */
+  get_instruction_system_blocks: () => AgentSessionSystemBlock[];
+  /** 显式 syncshot 时读取当前配置的 Hook 执行视图。 */
+  get_hooks: () => SessionHookRuntime;
+  /** 在每个 Step 检查点读取 Workspace env。 */
+  get_workspace_env: () => Record<string, string>;
+  /** 读取宿主显式注入的受托管 Plugin system blocks。 */
+  get_managed_plugin_system_blocks: () => Promise<AgentSessionSystemBlock[]>;
+  /** 读取当前 Session 实际使用的模型。 */
+  get_model: () => ModelClient | undefined;
+  /** 读取当前模型声明的上下文窗口。 */
+  get_model_context_window: () => number | undefined;
+  /** 读取当前 Session 的创建时间戳。 */
+  get_created_at: () => number;
+  /** 读取当前 Session 的参考时区。 */
+  get_timezone: () => string;
+  /** 记录 Plugin Hook 降级等可观察事件。 */
+  logger: Logger;
+}

package/src/types/session/SessionContextPolicy.ts

@@ -0,0 +1,77 @@
+/**
+ * Session Composer 的上下文策略协议。
+ *
+ * Policy 只读取 canonical Message，并在自己的命名空间维护可删除、可重建的派生数据；
+ * 它不修改 Session Message、State 或 Turn 生命周期。
+ */
+
+import type { ModelClient, ModelMessage, SessionSystemBlock } from "@downcity/type";
+import type { ModelRequestFailureReporter } from "@/types/executor/ModelRequest.js";
+import type { SessionComposerStorage } from "@/types/store/SessionStorage.js";
+
+/** Composer 可以处理的上下文恢复原因。 */
+export type SessionContextRecoveryReason =
+  /** Provider 明确拒绝超出上下文窗口的请求。 */
+  | "provider_context_limit"
+  /** Provider usage 已达到主动压缩阈值。 */
+  | "usage_pressure";
+
+/** Policy 初始化输入。 */
+export interface SessionContextPolicyInitializeInput {
+  /** 当前 Policy 已限定命名空间的派生存储。 */
+  storage: SessionComposerStorage;
+}
+
+/** Policy 正常解析上下文的输入。 */
+export interface SessionContextPolicyInput {
+  /** 当前 Policy 已限定命名空间的派生存储。 */
+  storage: SessionComposerStorage;
+  /** 解析文件 Part 时使用的 Workspace 根目录。 */
+  project_root: string;
+}
+
+/** 上下文恢复输入。 */
+export interface SessionContextPolicyRecoveryInput extends SessionContextPolicyInput {
+  /** 触发当前恢复的稳定领域原因。 */
+  reason: SessionContextRecoveryReason;
+  /** 用于生成派生摘要的当前模型。 */
+  model?: ModelClient;
+  /** 模型请求逐次失败的可选观测入口。 */
+  on_model_request_failure?: ModelRequestFailureReporter;
+}
+
+/** Policy 对本次模型上下文的只读诊断。 */
+export interface SessionResolvedContextDiagnostics {
+  /** 生成当前上下文的 Policy 名称。 */
+  policy_name: string;
+  /** 当前上下文覆盖到的最新 canonical Message sequence。 */
+  through_sequence?: number;
+  /** 当前派生边界在 Message 内覆盖到的 Part sequence。 */
+  through_part_sequence?: number;
+  /** 当前上下文是否使用了派生摘要或检索结果。 */
+  derived: boolean;
+  /** 当前使用的可选派生记录标识。 */
+  derivation_id?: string;
+}
+
+/** Policy 已确定顺序的最终模型历史。 */
+export interface SessionResolvedContext {
+  /** 送入模型的标准历史消息。 */
+  messages: ModelMessage[];
+  /** 由 Policy 生成、且不伪装成普通历史消息的显式 system 上下文。 */
+  system_blocks?: SessionSystemBlock[];
+  /** 不进入 canonical history 的策略诊断。 */
+  diagnostics: SessionResolvedContextDiagnostics;
+}
+
+/** Session Composer 内部可替换的上下文策略。 */
+export interface SessionContextPolicy {
+  /** Policy 稳定名称，同时作为派生表命名空间。 */
+  readonly name: string;
+  /** 初始化当前 Policy 的派生 schema。 */
+  initialize(input: SessionContextPolicyInitializeInput): Promise<void>;
+  /** 从 canonical history 与派生数据生成模型历史。 */
+  resolve(input: SessionContextPolicyInput): Promise<SessionResolvedContext>;
+  /** 模型上下文失败后尝试推进派生状态；发生有效变化时返回 true。 */
+  recover(input: SessionContextPolicyRecoveryInput): Promise<boolean>;
+}