@downcity/agent 1.1.408 → 1.1.437

package/src/types/session/SessionExecution.ts

@@ -7,8 +7,11 @@
  * - 输出只返回执行结果；Assistant Message 通过显式输出端口写入唯一事实源。
  */
 
-import type { ModelMessage, RuntimeTool as Tool } from "@downcity/type";
-import type { SessionUserMessage } from "@/types/session/SessionMessage.js";
+import type {
+  ModelClient,
+  ModelMessage,
+  RuntimeTool as Tool,
+} from "@downcity/type";
 import type { SessionSystemMessage } from "@/executor/types/SessionPrompts.js";
 import type { SessionTurnContext } from "@/types/executor/SessionTurnContext.js";
 
@@ -29,15 +32,6 @@ export interface SessionTurnExecutionResult {
    */
   error?: string;
 
-  /**
-   * 本轮执行结束后待写入长期历史的 user 消息。
-   *
-   * 关键点（中文）
-   * - 这些消息通常由 tool 运行时在执行过程中动态注入。
-   * - 为保证消息顺序稳定，统一在 assistant 结果落盘后再由外层 Session 持久化。
-   */
-  deferred_persisted_user_messages?: SessionUserMessage[];
-
   /**
    * 本轮结束后是否需要把已完成的 canonical 历史持久化压缩。
    *
@@ -52,11 +46,6 @@ export interface SessionTurnExecutionResult {
  * Session Turn 执行入口输入。
  */
 export interface SessionTurnExecutionInput {
-  /**
-   * 本轮用户输入查询文本。
-   */
-  query: string;
-
   /**
    * 本轮唯一的显式 Turn 上下文。
    *
@@ -71,10 +60,8 @@ export interface SessionTurnExecutionInput {
  * Executor 通过 Composer 装配后的中间运行态。
  */
 export interface SessionStepExecutionInput {
-  /**
-   * 当前轮用户查询文本。
-   */
-  query: string;
+  /** 当前 Step 使用的模型实例。 */
+  model: ModelClient;
 
   /**
    * 当前轮 system messages。
@@ -84,13 +71,14 @@ export interface SessionStepExecutionInput {
   /** 当前轮标准模型消息历史。 */
   messages: ModelMessage[];
 
-  /** 当前模型历史所包含的最新持久化 Summary 标识。 */
-  history_summary_id?: string;
-
   /**
    * 当前轮可用工具集合。
    */
   tools: Record<string, Tool>;
+
+  /** 当前模型支持的上下文窗口长度。 */
+  context_window?: number;
+
 }
 
 /** 单个 Session 的统一 Turn 执行协议。 */
@@ -100,16 +88,3 @@ export interface SessionExecutor {
     input: SessionTurnExecutionInput,
   ): Promise<SessionTurnExecutionResult>;
 }
-
-/** Session 领域执行一次持久化历史压缩的统一回调。 */
-export type SessionCompactHistory = (input: {
-  /** 触发压缩的 Turn 标识；非 Turn 维护操作允许为空。 */
-  turn_id?: string;
-}) => Promise<{
-  /** 是否生成并成功提交了压缩计划。 */
-  compacted: boolean;
-  /** 没有压缩时的稳定原因。 */
-  reason?: string;
-  /** 压缩失败时的具体错误文本。 */
-  error?: string;
-}>;

package/src/types/session/SessionInteractions.ts

@@ -8,7 +8,7 @@
 import type {
   SessionInteractionRequest,
   SessionInteractionResult,
-} from "@/types/session/SessionInteraction.js";
+} from "@downcity/type";
 
 /** 单个等待用户响应的运行时 Interaction。 */
 export interface SessionPendingInteractionRuntime {

package/src/types/session/SessionLocalState.ts

@@ -8,7 +8,7 @@
  */
 
 import type { AgentSessionConfigSnapshot } from "@/types/agent/SessionTypes.js";
-import type { SessionApprovalMode } from "@/types/session/SessionInteraction.js";
+import type { SessionApprovalMode } from "@downcity/type";
 
 /**
  * 本地 Session 内存状态。

package/src/types/session/SessionLoop.ts

@@ -4,7 +4,7 @@
  * 这些类型描述 Turn 编排所依赖的领域对象，不实现任何调度行为。
  */
 
-import type { ShellApprovalGateway } from "@downcity/workspace";
+import type { ShellApprovalGateway } from "@downcity/type";
 import type { SessionEventHub } from "@/session/runtime/SessionEventHub.js";
 import type { SessionMessages } from "@/session/SessionMessages.js";
 import type { SessionState } from "@/session/SessionState.js";
@@ -12,14 +12,12 @@ import type { AgentSessionTurnResult } from "@/types/sdk/AgentSessionTurn.js";
 import type {
   SessionInteractionLifecycle,
   SessionInteractionPort,
-} from "@/types/session/SessionInteraction.js";
-import type {
-  SessionCompactHistory,
-  SessionExecutor,
-} from "@/types/session/SessionExecution.js";
+} from "@downcity/type";
+import type { SessionExecutor } from "@/types/session/SessionExecution.js";
 import type { SessionQueue } from "@/session/SessionQueue.js";
 import type { Logger } from "@/utils/logger/Logger.js";
 import type { SessionTurnContext } from "@/types/executor/SessionTurnContext.js";
+import type { SessionOrigin } from "@downcity/type";
 
 /** Promise 延迟控制器。 */
 export interface SessionDeferred<T> {
@@ -39,8 +37,6 @@ export interface ActiveSessionTurnState {
   deferred_finished: SessionDeferred<AgentSessionTurnResult>;
   /** 当前 Turn 进入执行阶段后拥有的唯一上下文。 */
   turn_context: SessionTurnContext | null;
-  /** 下一 Step 是否需要重新读取 canonical history。 */
-  history_reload_requested: boolean;
   /** 当前 Turn 是否已经接收并持久化首条 Prompt。 */
   prompt_started: boolean;
 }
@@ -49,12 +45,14 @@ export interface ActiveSessionTurnState {
 export interface SessionLoopOptions {
   /** 当前 Session 的稳定标识。 */
   session_id: string;
+  /** 当前 Session 的完整来源元数据。 */
+  session_origin: SessionOrigin;
   /** 当前 Session 所属 Workspace 的绝对根目录。 */
   workspace_path: string;
   /** 当前 Session 的模型执行器。 */
   executor: SessionExecutor;
-  /** 由 Session 领域提供的 canonical 历史压缩入口。 */
-  compact_history: SessionCompactHistory;
+  /** Turn 结束后按需维护 Composer 派生上下文。 */
+  maintain_context: () => Promise<void>;
   /** 当前 Session 的配置与 Metadata 状态。 */
   state: SessionState;
   /** 当前 Session 的 canonical Message 入口。 */

package/src/types/session/SessionMessages.ts

@@ -4,26 +4,26 @@
  * 这些类型只描述 canonical Message 领域入口的参数，不包含持久化行为。
  */
 
-import type { JsonObject } from "@/types/common/Json.js";
-import type { SessionMessageStore } from "@/types/store/SessionDataStore.js";
+import type { JsonObject } from "@downcity/type";
+import type { SessionStorage } from "@/types/store/SessionStorage.js";
 import type { SessionAttachmentStore } from "@/types/store/SessionAttachmentStore.js";
 import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
 import type {
-  SessionAssistantResultPart,
-  SessionPromptPart,
-} from "@/types/session/SessionContent.js";
+  SessionAgentContent,
+  SessionUserContent,
+} from "@downcity/type";
 import type {
-  SessionAssistantMessagePart,
+  SessionAgentMessagePart,
   SessionUserMessagePart,
-} from "@/types/session/SessionMessage.js";
-import type { SessionMutation } from "@/types/session/SessionMutation.js";
+} from "@downcity/type";
+import type { SessionMutation } from "@downcity/type";
 
 /** SessionMessages 构造参数。 */
 export interface SessionMessagesOptions {
   /** 当前 Session 标识。 */
   session_id: string;
   /** Message 快照持久化 Store。 */
-  store: SessionMessageStore;
+  store: SessionStorage;
   /** 当前 Session 的附件持久化能力。 */
   attachment_store: SessionAttachmentStore;
   /** 持久化成功后的实时 Mutation 发布函数。 */
@@ -34,8 +34,6 @@ export interface SessionMessagesOptions {
 export interface AppendSessionUserMessageInput {
   /** 当前输入所属 Turn。 */
   turn_id: string;
-  /** 当前输入是普通 Prompt 还是 Steering 输入。 */
-  input_type: "prompt" | "steer";
   /** User 结构化 Part。 */
   parts: SessionUserMessagePart[];
   /** 可选的稳定 Message 标识。 */
@@ -45,35 +43,27 @@ export interface AppendSessionUserMessageInput {
 }
 
 /** Assistant Message 创建参数。 */
-export interface OpenSessionAssistantMessageInput {
+export interface OpenSessionAgentMessageInput {
   /** 当前 Assistant 所属 Turn。 */
   turn_id: string;
-  /** 当前 Assistant 是普通回复还是压缩 Summary。 */
-  kind?: "normal" | "summary";
   /** 当前 Message 的默认展示范围。 */
   visibility?: "visible" | "internal";
   /** 可选的稳定 Message 标识。 */
   message_id?: string;
-  /** Summary 已覆盖到的来源 Message 标识。 */
-  summary_through_message_id?: string;
 }
 
 /** 已完成 Assistant Message 的直接写入参数。 */
-export interface AppendCompletedAssistantMessageInput {
+export interface AppendCompletedAgentMessageInput {
   /** 当前 Assistant 所属 Turn。 */
   turn_id?: string;
   /** Assistant 完整结构化 Part。 */
-  parts: SessionAssistantMessagePart[];
-  /** 当前 Assistant 是普通回复还是压缩 Summary。 */
-  kind?: "normal" | "summary";
+  parts: SessionAgentMessagePart[];
   /** 当前 Message 的默认展示范围。 */
   visibility?: "visible" | "internal";
-  /** Summary 已覆盖到的来源 Message 标识。 */
-  summary_through_message_id?: string;
 }
 
-/** Action Message 创建参数。 */
-export interface OpenSessionActionMessageInput {
+/** Action Part 及其所属 Agent Message 的创建参数。 */
+export interface OpenSessionAgentActionPartInput {
   /** 可选的稳定 Message 标识，用于更新同一个 Action 生命周期。 */
   message_id?: string;
   /** 当前 Action 所属 Turn。 */
@@ -90,8 +80,18 @@ export interface OpenSessionActionMessageInput {
   publish_mutation?: boolean;
 }
 
-/** Error Message 创建参数。 */
-export interface AppendSessionErrorMessageInput {
+/** 完成 Action Part 时允许覆盖的内容。 */
+export interface CompleteSessionAgentActionPartInput {
+  /** 完成时覆盖的可选标题。 */
+  title?: string;
+  /** 完成时覆盖的可选描述。 */
+  description?: string;
+  /** 完成时写入的可选结构化数据。 */
+  data?: JsonObject;
+}
+
+/** 将 Error Part 归入所属 Turn Agent Message 的参数。 */
+export interface AppendSessionAgentErrorPartInput {
   /** 当前错误影响 Session 还是单个 Turn。 */
   scope: "session" | "turn";
   /** 当前错误所属 Turn。 */
@@ -107,15 +107,15 @@ export interface AppendSessionErrorMessageInput {
 /** 公开 Session API 追加 User Message 的输入。 */
 export interface AppendExternalSessionUserMessageInput {
   /** 可选的结构化 User 内容。 */
-  parts?: SessionPromptPart[];
+  parts?: SessionUserContent[];
   /** 未提供结构化内容时使用的纯文本。 */
   text?: string;
 }
 
 /** 公开 Session API 追加 Assistant Message 的输入。 */
-export interface AppendExternalSessionAssistantMessageInput {
+export interface AppendExternalSessionAgentMessageInput {
   /** 可选的结构化 Assistant 内容。 */
-  parts?: SessionAssistantResultPart[];
+  parts?: SessionAgentContent[];
   /** 未提供结构化内容时使用的纯文本。 */
   text?: string;
 }
@@ -128,6 +128,6 @@ export interface AppendSessionPromptMessageInput {
   prompt: AgentSessionPromptInput;
   /** 当前输入所属 Turn。 */
   turn_id: string;
-  /** 当前输入是普通 Prompt 还是 Steering 输入。 */
-  input_type: "prompt" | "steer";
+  /** 幂等 Prompt 使用的稳定 User Message ID。 */
+  message_id?: string;
 }

package/src/types/session/SessionOptions.ts

@@ -7,16 +7,15 @@
  * - Composer 仍然是 Session 级能力，不向 Agent 的执行策略层泄漏。
  */
 
-import type { RuntimeTool as Tool } from "@downcity/type";
-import type { AgentModel } from "@/agent/AgentModel.js";
+import type { ModelClient, RuntimeTool as Tool } from "@downcity/type";
 import type { AgentSession } from "@/types/agent/SessionActor.js";
 import type { SessionPort } from "@/types/session/SessionPort.js";
 import type { AgentSessionSystemBlock } from "@/types/agent/SessionTypes.js";
-import type { AgentPluginExecutionRuntime } from "@/types/plugin/PluginRuntime.js";
+import type { SessionHookRuntime } from "@downcity/type";
 import type { SessionComposer } from "@/types/session/SessionComposer.js";
 import type { Logger } from "@/utils/logger/Logger.js";
-import type { SessionDataStore } from "@/types/store/SessionDataStore.js";
-import type { SessionOrigin } from "@/types/session/SessionOrigin.js";
+import type { SessionStorage } from "@/types/store/SessionStorage.js";
+import type { SessionOrigin } from "@downcity/type";
 
 /**
  * Agent 可管理的本地 Session 实例。
@@ -28,7 +27,7 @@ export interface AgentManagedSession extends AgentSession {
   initialize(): Promise<this>;
 
   /**
-   * 返回供 plugin/runtime 使用的 session 端口。
+   * 返回供宿主运行时使用的 Session 端口。
    */
   get_runtime_port(): SessionPort;
 
@@ -40,23 +39,6 @@ export interface AgentManagedSession extends AgentSession {
    */
   is_executing(): boolean;
 
-  /** 把 Workspace env 快照加入当前 Session 的有序输入队列。 */
-  enqueue_workspace_env(input: {
-    /** 当前 Workspace env 修改的稳定标识。 */
-    command_id: string;
-    /** 下一 Session Step 使用的完整环境变量快照。 */
-    env: Record<string, string>;
-  }): void;
-
-  /** 把 Agent Plugin 执行视图加入当前 Session 的有序输入队列。 */
-  enqueue_agent_plugins(input: {
-    /** 当前 Plugin 修改的稳定标识。 */
-    command_id: string;
-    /** 当前 Plugin 修改的用户可读标题。 */
-    title: string;
-    /** 下一 Session Step 使用的 Plugin 执行视图。 */
-    plugins: AgentPluginExecutionRuntime;
-  }): void;
 }
 
 /**
@@ -74,24 +56,31 @@ export interface SessionOptions {
   /** 当前 Session 创建时绑定的 Workspace 稳定标识；未传 Workspace 时为空。 */
   workspace_id?: string;
 
-  /** 当前 Session 的创建来源；未填写时视为用户直接创建。 */
-  origin?: SessionOrigin;
+  /** 当前 Session 的创建来源与物理存储分区。 */
+  origin: SessionOrigin;
 
   /** 当前 Session 独享的领域持久化视图。 */
-  store: SessionDataStore;
+  store: SessionStorage;
 
   /** 为 fork 创建另一个 Session 的领域持久化视图。 */
-  get_session_store: (session_id: string) => SessionDataStore;
+  create_session_store: (session_id: string) => SessionStorage;
 
   /**
-   * 当前 session_id。
+   * 将 fork 创建的子 Session 交回 AgentSessions 登记。
+   *
+   * 关键点（中文）
+   * - Session 只负责创建子实例，AgentSessions 仍是运行时实例的唯一所有者。
+   * - 登记后再通过 `sessions.get()` 读取时，必须返回同一实例。
    */
-  session_id: string;
+  register_forked_session: (session: AgentManagedSession) => void;
 
   /**
-   * 当前 agent 默认工具集合。
+   * 当前 session_id。
    */
-  tools: Record<string, Tool>;
+  session_id: string;
+
+  /** 在每个 Step 检查点读取当前可用 Tool 集合。 */
+  get_tools: () => Record<string, Tool>;
 
   /**
    * 统一日志器。
@@ -120,17 +109,14 @@ export interface SessionOptions {
    * 读取当前 Workspace configured env。
    *
    * 关键点（中文）
-   * - Session 创建时用它建立初始 effective env。
-   * - 后续 Workspace env 修改通过 Session command 在 step 检查点执行。
+   * - 每个 Step 在检查点读取一次并形成不可变快照。
    */
   get_workspace_env: () => Record<string, string>;
 
-  /** 创建当前 Agent configured plugin 的 Session step 执行视图。 */
-  get_agent_plugins: () => AgentPluginExecutionRuntime;
+  /** 创建当前 City configured extension 的 Session Step 执行视图。 */
+  get_hooks: () => SessionHookRuntime;
 
-  /**
-   * 读取当前 agent 显式注入的受托管 plugin system blocks。
-   */
+  /** 读取当前 Agent 显式注入的受托管 Plugin system blocks。 */
   get_managed_plugin_system_blocks: () => Promise<AgentSessionSystemBlock[]>;
 
   /**
@@ -139,8 +125,8 @@ export interface SessionOptions {
   ensure_configured?: (session: AgentManagedSession) => Promise<void>;
 
   /** 读取 Agent 当前持有的运行时模型实例。 */
-  get_agent_model: () => AgentModel | undefined;
+  get_agent_model: () => ModelClient | undefined;
 
-  /** 当前 Session 使用的统一执行策略；省略时使用默认 Composer。 */
-  composer?: SessionComposer;
+  /** 为当前 Session 及其 fork 子 Session 创建独立 Composer 的工厂。 */
+  create_composer?: () => SessionComposer;
 }

package/src/types/session/SessionPort.ts

@@ -2,15 +2,16 @@
  * Session runtime 端口类型。
  *
  * 职责说明（中文）
- * - 定义 Plugin、transport 与 Agent 内部运行时访问单个 Session 的稳定协议。
+ * - 定义宿主 transport 与 Agent 内部运行时访问单个 Session 的稳定协议。
  * - 不暴露具体 Session class，也不包含 Session 集合管理能力。
  */
 
 import type { ModelClient } from "@downcity/type";
 import type {
-  SessionAssistantResultPart,
-  SessionPromptPart,
-} from "@/types/session/SessionContent.js";
+  SessionAgentContent,
+  SessionUserContent,
+  SessionMessage,
+} from "@downcity/type";
 import type { SessionExecutor } from "@/types/session/SessionExecution.js";
 import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
 import type { AgentSessionStopResult } from "@/types/sdk/AgentSessionStop.js";
@@ -18,8 +19,7 @@ import type { AgentSessionTurnHandle } from "@/types/sdk/AgentSessionTurn.js";
 import type {
   SessionMutationSubscriber,
   SessionMutationUnsubscribe,
-} from "@/types/session/SessionMutation.js";
-import type { SessionContextSnapshot } from "@/types/session/SessionSegment.js";
+} from "@downcity/type";
 
 /**
  * 单个 Session 实例端口。
@@ -34,8 +34,8 @@ export interface SessionPort {
   /** 获取当前 Session 的执行端口。 */
   get_executor(): SessionExecutor;
 
-  /** 读取当前 Session 的累计 Summary 与 Active Message 快照。 */
-  context(): Promise<SessionContextSnapshot>;
+  /** 读取全部 canonical Session Message。 */
+  messages(): Promise<SessionMessage[]>;
 
   /** 向当前 Session actor 追加一条新的 prompt。 */
   prompt(input: AgentSessionPromptInput): Promise<AgentSessionTurnHandle>;
@@ -51,17 +51,17 @@ export interface SessionPort {
    */
   append_user_message(params: {
     /** 已构造好的 User 内容。 */
-    parts?: SessionPromptPart[];
+    parts?: SessionUserContent[];
     /** 未传入结构化内容时使用的文本。 */
     text?: string;
   }): Promise<void>;
 
   /**
-   * 追加一条 assistant 消息。
+   * 追加一条 Agent 消息。
    */
-  append_assistant_message(params: {
-    /** 已构造好的 Assistant 内容。 */
-    parts?: SessionAssistantResultPart[];
+  append_agent_message(params: {
+    /** 已构造好的 Agent 内容。 */
+    parts?: SessionAgentContent[];
     /** 未传入结构化内容时使用的文本。 */
     text?: string;
   }): Promise<void>;

package/src/types/session/SessionState.ts

@@ -5,12 +5,11 @@
  */
 
 import type { ModelClient } from "@downcity/type";
-import type { SessionMessages } from "@/session/SessionMessages.js";
 import type { SessionLocalState } from "@/types/session/SessionLocalState.js";
-import type { SessionMutation } from "@/types/session/SessionMutation.js";
+import type { SessionMutation } from "@downcity/type";
 import type { Logger } from "@/utils/logger/Logger.js";
-import type { SessionDataStore } from "@/types/store/SessionDataStore.js";
-import type { SessionOrigin } from "@/types/session/SessionOrigin.js";
+import type { SessionStorage } from "@/types/store/SessionStorage.js";
+import type { SessionOrigin } from "@downcity/type";
 
 /** SessionState 构造参数。 */
 export interface SessionStateOptions {
@@ -19,11 +18,9 @@ export interface SessionStateOptions {
   /** 当前 Session 的稳定标识。 */
   session_id: string;
   /** 当前 Session 的创建来源。 */
-  origin?: SessionOrigin;
+  origin: SessionOrigin;
   /** 当前 Session 独享的领域持久化视图。 */
-  store: SessionDataStore;
-  /** 当前 Session 的 canonical Message 入口。 */
-  messages: SessionMessages;
+  store: SessionStorage;
   /** 当前 Session 的可变内存状态。 */
   state: SessionLocalState;
   /** 当前 Session 的运行日志器。 */

package/src/types/session/SessionSystem.ts

@@ -5,6 +5,11 @@
  */
 
 import type { AgentSessionSystemBlock } from "@/types/agent/SessionTypes.js";
+import type {
+  SessionHookContext,
+  SessionHookRuntime,
+  SessionHookScopeRuntime,
+} from "@downcity/type";
 
 /** 默认 Session System Block 的组装参数。 */
 export interface BuildSessionSystemBlocksInput {
@@ -22,6 +27,20 @@ export interface BuildSessionSystemBlocksInput {
   get_instruction_system_blocks: () => AgentSessionSystemBlock[];
   /** 读取当前显式注入的受托管 Plugin System Block。 */
   get_managed_plugin_system_blocks: () => Promise<AgentSessionSystemBlock[]>;
-  /** 读取当前显式注册 Plugin 的 System Block。 */
+  /** 读取当前 Session Plugin 的 System Block。 */
   get_plugin_system_blocks: () => Promise<AgentSessionSystemBlock[]>;
 }
+
+/** 解析 Plugin system blocks 所需的稳定执行输入。 */
+export interface ResolveSessionPluginSystemBlocksInput {
+  /** 当前 Session 的稳定标识。 */
+  session_id: string;
+  /** 当前 Turn 的稳定标识；控制面预览等非 Turn 调用允许为空。 */
+  turn_id?: string;
+  /** 当前调用捕获的 Hook runtime 或 Step scope。 */
+  hooks: SessionHookRuntime | SessionHookScopeRuntime;
+  /** 向 Plugin 暴露的只读 Session 上下文。 */
+  context: SessionHookContext;
+  /** Plugin system 解析失败后的可选降级观测入口。 */
+  on_error?: (error: unknown) => void | Promise<void>;
+}

package/src/types/session/SessionTool.ts

@@ -4,14 +4,14 @@
  * 这些类型描述 Tool 生命周期协调器与 Recorder 之间的稳定边界。
  */
 
-import type { SessionAssistantToolPart } from "@/types/session/SessionMessage.js";
+import type { SessionAgentToolPart } from "@downcity/type";
 
 /** 当前流式 Assistant 中的 Tool Part 定位结果。 */
 export interface SessionStreamingToolLocation {
   /** Tool Part 所属 Assistant Message。 */
   message_id: string;
   /** 当前 Tool Part 完整快照。 */
-  part: SessionAssistantToolPart;
+  part: SessionAgentToolPart;
 }
 
 /** Executor 在调用 Tool 实现前提交的完整输入。 */

package/src/types/session/SessionTurnCompletion.ts

@@ -0,0 +1,24 @@
+/**
+ * Session Turn 收口领域函数的依赖类型。
+ *
+ * 这些依赖只覆盖 canonical Message、Mutation、Hook 与资源释放，不包含 Queue 或
+ * Executor，避免 Turn 结果提交反向理解调度过程。
+ */
+
+import type { SessionEventHub } from "@/session/runtime/SessionEventHub.js";
+import type { SessionMessages } from "@/session/SessionMessages.js";
+import type { Logger } from "@/utils/logger/Logger.js";
+
+/** Turn 收口函数的稳定依赖。 */
+export interface SessionTurnCompletionOptions {
+  /** 当前 Session 的稳定标识。 */
+  session_id: string;
+  /** 当前 Session 的 canonical Message 入口。 */
+  messages: SessionMessages;
+  /** 当前 Session 的 Mutation 发布入口。 */
+  events: SessionEventHub;
+  /** 当前 Session 的统一日志器。 */
+  logger: Logger;
+  /** Turn 停止时对外使用的稳定错误文本。 */
+  stopped_message: string;
+}

package/src/types/session/SessionTurnFileDiff.ts

@@ -0,0 +1,44 @@
+/**
+ * Session Turn 文件修改观测函数的依赖类型。
+ *
+ * 文件 Diff 是辅助观测结果，不参与模型或 Tool 的成功判定；这些类型显式限制它只能
+ * 读取 Turn effects、写入 Assistant 输出并发布摘要 Mutation。
+ */
+
+import type { RuntimeToolEffect } from "@downcity/type";
+import type { SessionAssistantOutput } from "@/types/executor/SessionAssistantOutput.js";
+import type { SessionTurnContext } from "@/types/executor/SessionTurnContext.js";
+import type { SessionMutation } from "@downcity/type";
+import type { Logger } from "@/utils/logger/Logger.js";
+
+/** 持久化 Turn 最终文件 Diff 的输入。 */
+export interface AppendSessionTurnFileDiffInput {
+  /** 当前 Session 的稳定标识。 */
+  session_id: string;
+  /** 当前 Turn 的稳定标识。 */
+  turn_id: string;
+  /** 当前 Workspace 的绝对根路径。 */
+  workspace_path: string;
+  /** 当前 Turn 持有的 effects 与生命周期上下文。 */
+  turn_context: SessionTurnContext;
+  /** 当前 Turn 的 canonical Assistant 输出端口。 */
+  assistant_output: SessionAssistantOutput;
+  /** 当前 Session 的统一日志器。 */
+  logger: Logger;
+}
+
+/** 发布 Turn 实时文件 Diff 摘要的输入。 */
+export interface PublishSessionTurnFileDiffInput {
+  /** 当前 Session 的稳定标识。 */
+  session_id: string;
+  /** 当前 Turn 的稳定标识。 */
+  turn_id: string;
+  /** 当前 Workspace 的绝对根路径。 */
+  workspace_path: string;
+  /** 当前检查点已经发生的 Tool effects。 */
+  effects: readonly RuntimeToolEffect[];
+  /** 发布公开 Session Mutation 的函数。 */
+  publish: (mutation: SessionMutation) => void;
+  /** 当前 Session 的统一日志器。 */
+  logger: Logger;
+}