@downcity/agent 1.1.437 → 1.1.445

package/src/group/storage/LocalGroupSessionStore.ts

@@ -8,8 +8,30 @@ import type {
   GroupSessionStore,
   GroupSessionStoreOptions,
 } from "@/types/group/GroupSessionStore.js";
+import type { GroupSessionArchiveResult, GroupSessionCleanArchiveResult } from "@/types/group/GroupSession.js";
 import { LocalGroupSessionDataStore } from "@/group/storage/LocalGroupSessionDataStore.js";
 
+/**
+ * GroupSession 的两个存储区。
+ *
+ * ```text
+ * <group-root>/sessions/<session_id>/           活动
+ * <group-root>/archived-sessions/<session_id>/  归档
+ * ```
+ *
+ * 归档是**目录搬迁**而不是打标记：活动列表因此天然只含活动项，
+ * `list_session_metadata()` 不需要加过滤条件，`metadata.v` 也不用升版本。
+ * 这与 Agent Session 的做法一致（`LocalSessionStore.archive_session`），
+ * 两处同类能力不该有两套语义。
+ */
+type SessionArea = "active" | "archived";
+
+/** 各存储区的目录名。 */
+const area_directory_name: Record<SessionArea, string> = {
+  active: "sessions",
+  archived: "archived-sessions",
+};
+
 /** GroupSession 的底层文件 Store。 */
 export class LocalGroupSessionStore implements GroupSessionStore {
   private readonly files: FileSystem;
@@ -23,48 +45,106 @@ export class LocalGroupSessionStore implements GroupSessionStore {
     this.group_id = options.group_id;
   }
 
-  /** 返回指定 GroupSession 的持久化视图。 */
-  session(session_id: string): GroupSessionDataStore {
+  /**
+   * 返回指定 GroupSession 的持久化视图。
+   *
+   * 缓存键带存储区：同一个 session_id 在活动区与归档区各有一份视图，
+   * 不分区的话归档后会拿到活动区的旧视图（路径指向已经不存在的目录）。
+   */
+  session(session_id: string, area: SessionArea = "active"): GroupSessionDataStore {
     const resolved_session_id = String(session_id || "").trim();
     if (!resolved_session_id) throw new Error("GroupSessionStore.session requires a non-empty session_id");
-    const cached = this.sessions_by_id.get(resolved_session_id);
+    const cache_key = `${area}:${resolved_session_id}`;
+    const cached = this.sessions_by_id.get(cache_key);
     if (cached) return cached;
     const created = new LocalGroupSessionDataStore({
       files: this.files,
       storage_root_path: this.storage_root_path,
       session_id: resolved_session_id,
       group_id: this.group_id,
+      area,
     });
-    this.sessions_by_id.set(resolved_session_id, created);
+    this.sessions_by_id.set(cache_key, created);
     return created;
   }
 
-  /** 判断指定 GroupSession 是否存在。 */
+  /** 判断指定 GroupSession 是否存在（活动区）。 */
   async has_session(session_id: string): Promise<boolean> {
-    return await this.files.path_exists(this.session_path(session_id));
+    return await this.files.path_exists(this.session_path(session_id, "active"));
   }
 
-  /** 列出当前 Group 的全部 Session metadata。 */
+  /** 列出当前 Group 活动区的全部 Session metadata（不含已归档）。 */
   async list_session_metadata(): Promise<GroupSessionHistoryMeta[]> {
-    const sessions_path = path.join(path.resolve(this.storage_root_path), "sessions");
-    if (!(await this.files.path_exists(sessions_path))) return [];
-    const entries = await this.files.read_directory(sessions_path);
-    const metadata: GroupSessionHistoryMeta[] = [];
-    for (const entry of entries.filter((item) => item.is_directory)) {
-      const session_id = decode_session_id(entry.name);
-      metadata.push(await this.session(session_id).read_metadata());
-    }
-    return metadata.sort((left, right) => right.updated_at - left.updated_at);
+    return await this.list_area_metadata("active");
+  }
+
+  /** 列出归档区的 Session metadata。 */
+  async list_archived_session_metadata(): Promise<GroupSessionHistoryMeta[]> {
+    return await this.list_area_metadata("archived");
   }
 
-  /** 删除指定 GroupSession 的全部数据。 */
+  /** 删除指定 GroupSession 的全部数据（活动区）。 */
   async remove_session(session_id: string): Promise<boolean> {
+    return await this.remove_area_session(session_id, "active");
+  }
+
+  /** 删除归档区中的指定 Session。 */
+  async remove_archived_session(session_id: string): Promise<boolean> {
+    return await this.remove_area_session(session_id, "archived");
+  }
+
+  /**
+   * 把一个活动 GroupSession 迁入归档区。
+   *
+   * 用 `move_path` 而不是「复制再删除」：它是原子的，且**不覆盖已有目标**——
+   * 后者正是这里要的语义（覆盖会丢掉一份真实数据）。两个方向的失败都必须报错，
+   * 不能静默成功。
+   *
+   * **先查归档区再查活动区**，顺序不能反：重复归档时活动区已经空了，
+   * 先查活动区会报「not found」——而用户明明看得到那条群聊（在归档区），
+   * 那句话只会让他以为数据丢了。报「已归档」才是他需要知道的事。
+   */
+  async archive_session(session_id: string): Promise<GroupSessionArchiveResult> {
     const resolved_session_id = String(session_id || "").trim();
-    const session_path = this.session_path(resolved_session_id);
-    const existed = await this.files.path_exists(session_path);
-    if (existed) await this.files.remove_path(session_path);
-    this.sessions_by_id.delete(resolved_session_id);
-    return existed;
+    if (!resolved_session_id) throw new Error("GroupSessionStore.archive_session requires a non-empty session_id");
+    const target_path = this.session_path(resolved_session_id, "archived");
+    if (await this.files.path_exists(target_path)) {
+      throw new Error(`Archived GroupSession "${resolved_session_id}" already exists`);
+    }
+    const source_path = this.session_path(resolved_session_id, "active");
+    if (!(await this.files.path_exists(source_path))) {
+      throw new Error(`GroupSession "${resolved_session_id}" not found`);
+    }
+    await this.files.ensure_directory(this.area_path("archived"));
+    await this.files.move_path(source_path, target_path);
+    // 运行时缓存指向的是活动区路径；搬迁后必须丢掉它，否则下次 `session()` 会拿到旧视图。
+    this.sessions_by_id.delete(`active:${resolved_session_id}`);
+    return { session_id: resolved_session_id, archived_at: Date.now() };
+  }
+
+  /** 永久清空归档区。 */
+  async clean_archive(): Promise<GroupSessionCleanArchiveResult> {
+    const archived_path = this.area_path("archived");
+    if (!(await this.files.path_exists(archived_path))) return { removed_session_ids: [] };
+    const entries = await this.files.read_directory(archived_path);
+    const removed_session_ids = entries
+      .filter((entry) => entry.is_directory)
+      .map((entry) => decode_session_id(entry.name));
+    await this.files.remove_path(archived_path);
+    return { removed_session_ids };
+  }
+
+  /**
+   * 永久删除当前 Group 的全部 GroupSession 数据。
+   *
+   * 两个区都删：Group 被删时它的活动会话与归档一样无处可访问，留着只是磁盘泄漏。
+   * 只删两个区目录而不是整个作用域根：作用域可能还装着 Group 的其它私有数据，
+   * 那些不归这个 Store 管。
+   */
+  async purge(): Promise<void> {
+    await this.files.remove_path(this.area_path("active"));
+    await this.files.remove_path(this.area_path("archived"));
+    this.sessions_by_id.clear();
   }
 
   /** 释放当前 Store 的运行时缓存。 */
@@ -72,12 +152,42 @@ export class LocalGroupSessionStore implements GroupSessionStore {
     this.sessions_by_id.clear();
   }
 
-  private session_path(session_id: string): string {
-    return path.join(
-      path.resolve(this.storage_root_path),
-      "sessions",
-      encodeURIComponent(String(session_id || "").trim()),
-    );
+  /** 一个存储区的根目录。 */
+  private area_path(area: SessionArea): string {
+    return path.join(path.resolve(this.storage_root_path), area_directory_name[area]);
+  }
+
+  /**
+   * 某个区里单个 Session 的目录。
+   *
+   * 两个区共用同一段拼接：各写一遍必然分叉，而这类路径一旦分叉，
+   * 表现是「归档后找不到了」——极难归因。
+   */
+  private session_path(session_id: string, area: SessionArea): string {
+    return path.join(this.area_path(area), encodeURIComponent(String(session_id || "").trim()));
+  }
+
+  /** 列出某个区的全部 Session metadata，按最近更新倒序。 */
+  private async list_area_metadata(area: SessionArea): Promise<GroupSessionHistoryMeta[]> {
+    const area_path = this.area_path(area);
+    if (!(await this.files.path_exists(area_path))) return [];
+    const entries = await this.files.read_directory(area_path);
+    const metadata: GroupSessionHistoryMeta[] = [];
+    for (const entry of entries.filter((item) => item.is_directory)) {
+      metadata.push(await this.session(decode_session_id(entry.name), area).read_metadata());
+    }
+    return metadata.sort((left, right) => right.updated_at - left.updated_at);
+  }
+
+  /** 删除某个区里的一个 Session。 */
+  private async remove_area_session(session_id: string, area: SessionArea): Promise<boolean> {
+    const resolved_session_id = String(session_id || "").trim();
+    const session_path = this.session_path(resolved_session_id, area);
+    const existed = await this.files.path_exists(session_path);
+    if (existed) await this.files.remove_path(session_path);
+    // 只清这个区的缓存：同一个 id 在另一个区可能仍有视图。
+    this.sessions_by_id.delete(`${area}:${resolved_session_id}`);
+    return existed;
   }
 }
 

package/src/index.ts

@@ -4,7 +4,7 @@
  * 关键点（中文）
  * - 这是 agent 包核心运行时的稳定公开入口；可选 Tool 通过 `@downcity/agent/tools` 导出。
  * - 只导出 Agent SDK 与必要的 Session 协议类型。
- * - HTTP、RPC、Plugin、Workspace 与 Sandbox 实现不从根入口暴露。
+ * - HTTP、RPC、Power、Workspace 与 Sandbox 实现不从根入口暴露。
  */
 
 // Agent 入口
@@ -50,19 +50,19 @@ export type {
 } from "./group/index.js";
 export { AiDispatchStrategy } from "./group/index.js";
 export type { SessionStore } from "./types/store/SessionStore.js";
+export type {
+  SessionDerivedStore,
+  SessionDerivedStoreTransaction,
+} from "./types/store/SessionStorage.js";
 export type { SessionAttachmentStore } from "./types/store/SessionAttachmentStore.js";
 export type { AgentStorage } from "./types/agent/AgentStorage.js";
 export { Session } from "./session/Session.js";
-export { SessionHooks, SessionHookScope } from "./session/SessionHooks.js";
-export type { SessionOptions } from "./types/session/SessionOptions.js";
 export type { SessionOrigin } from "@downcity/type";
-export { SESSION_HOOK_POINTS } from "./session/SessionHookPoints.js";
+export { SESSION_HOOK_POINTS } from "@downcity/type";
 export type {
   SessionCommittedTurnStatus,
   SessionHookContextBlock,
   SessionHookUserMessage,
-  SessionHookContext,
-  SessionHookHandlers,
   SessionSystemContextHookValue,
   SessionTurnCommittedHookValue,
   SessionTurnContextHookValue,
@@ -97,7 +97,7 @@ export type {
   SessionAgentActionPart,
   SessionAgentDataPart,
   SessionAgentFilePart,
-  SessionAgentInteractionPart,
+  SessionAgentInteraction,
   SessionAgentMessage,
   SessionAgentMessagePart,
   SessionAgentReasoningPart,
@@ -124,8 +124,8 @@ export {
   read_session_turn_file_diff_data,
   SESSION_TURN_FILE_DIFF_DATA_TYPE,
 } from "./session/messages/SessionTurnFileDiffData.js";
-export { to_session_message_timeline_events } from "./session/browse/SessionMessageTimeline.js";
-export { SessionAssistantOutputAdapter } from "./session/execution/SessionAssistantOutputAdapter.js";
+export { to_session_message_timeline_events } from "./session/messages/SessionMessageTimeline.js";
+export { SessionAssistantOutputAdapter } from "./session/messages/SessionAssistantOutputAdapter.js";
 export {
   is_session_mutation,
 } from "@downcity/type";
@@ -148,24 +148,27 @@ export type {
 } from "@downcity/type";
 export type {
   RespondSessionInteractionInput,
+  SessionApprovalDecision,
   SessionApprovalMode,
+  SessionApprovalPort,
+  SessionApprovalRequestInput,
   SessionCancelledInteractionResult,
-  SessionExpiredInteractionResult,
   SessionInteractionAnswer,
   SessionInteractionHandle,
   SessionInteractionLifecycle,
   SessionInteractionOption,
   SessionInteractionPort,
   SessionInteractionQuestion,
-  SessionInteractionQuestionResponseType,
+  SessionInteractionQuestionType,
   SessionInteractionRequest,
+  SessionInteractionRequestInput,
   SessionInteractionResponse,
   SessionInteractionResult,
   SessionInteractionSource,
   SessionInteractionStatus,
-  SessionPendingInteraction,
   SessionResolvedInteractionResult,
 } from "@downcity/type";
+export { SESSION_APPROVAL_RESPONSE_SCHEMA } from "@downcity/type";
 export type {
   AgentOptions,
   AgentSessionConstructor,
@@ -184,8 +187,6 @@ export type { AgentManagedSession } from "./types/session/SessionOptions.js";
 export type {
   AgentSessionActionCallback,
   AgentSessionActionEvent,
-  AgentSessionActionRecord,
-  AgentSessionActionState,
 } from "./types/sdk/AgentSessionAction.js";
 export type {
   AgentSessionPromptContent,
@@ -207,25 +208,24 @@ export type {
   AgentSessionTurnResult,
 } from "./types/sdk/AgentSessionTurn.js";
 export type { SessionPort } from "./types/session/SessionPort.js";
-export type {
-  ActionResult,
-  ActionResultMessage,
-} from "./types/action/ActionResult.js";
+export {
+  is_action_result,
+  type ActionResult,
+  type ActionResultMessage,
+  type SessionSystemMessage,
+} from "@downcity/type";
 
 // Session 与即时执行集成
-export { Executor } from "./executor/Executor.js";
-export { DefaultSessionComposer } from "./session/DefaultSessionComposer.js";
-export { FullHistoryContextPolicy } from "./session/composer/policies/FullHistoryContextPolicy.js";
-export { AdaptivePartContextPolicy } from "./session/composer/policies/AdaptivePartContextPolicy.js";
-export { SessionMessages } from "./session/SessionMessages.js";
+export { SessionExecutor } from "./session/runner/SessionExecutor.js";
+export { DefaultSessionComposer } from "./session/input/composer/DefaultSessionComposer.js";
+export { FullHistorySessionComposer } from "./session/input/composer/FullHistorySessionComposer.js";
+export { SessionMessages } from "./session/messages/SessionMessages.js";
 export type {
-  AppendCompletedAgentMessageInput,
   AppendExternalSessionAgentMessageInput,
   AppendExternalSessionUserMessageInput,
   AppendSessionAgentErrorPartInput,
   AppendSessionPromptMessageInput,
   AppendSessionUserMessageInput,
-  OpenSessionAgentActionPartInput,
   OpenSessionAgentMessageInput,
   SessionMessagesOptions,
 } from "./types/session/SessionMessages.js";
@@ -236,38 +236,20 @@ export type {
   SessionComposeState,
   SessionComposeTurn,
   SessionComposerInitializeInput,
-  SessionContextRecoveryInput,
+  SessionContextAdvanceInput,
+  SessionContextAdvanceTrigger,
+  SessionContextDiagnostics,
   SessionStepInput,
 } from "./types/session/SessionComposer.js";
 export type {
-  SessionContextPolicy,
-  SessionContextPolicyInitializeInput,
-  SessionContextPolicyInput,
-  SessionContextPolicyRecoveryInput,
-  SessionContextRecoveryReason,
-  SessionResolvedContext,
-  SessionResolvedContextDiagnostics,
-} from "./types/session/SessionContextPolicy.js";
-export type {
-  SessionExecutor,
   SessionTurnExecutionResult,
 } from "./types/session/SessionExecution.js";
-export { create_session_turn_context } from "./session/runtime/SessionTurnContext.js";
+export { create_session_turn_context } from "./session/loop/SessionTurnContext.js";
 export type {
   SessionTurnContext,
   SessionTurnContextInit,
-} from "./types/executor/SessionTurnContext.js";
-export type { SessionToolExecutionContext } from "./types/executor/SessionToolExecutionContext.js";
-export type {
-  ToolActionExecutionContext,
-  ToolSessionExecutionScope,
-} from "./types/tools/ToolActionExecutionContext.js";
-export type {
-  SessionActionEvent,
-  SessionActionEventInput,
-  SessionActionStatus,
-} from "@downcity/type";
-export type { SessionSystemMessage } from "./executor/types/SessionPrompts.js";
+} from "./types/turn/SessionTurnContext.js";
+export type { SessionActionEvent, SessionActionStatus } from "@downcity/type";
 export {
   extract_session_message_text,
   extract_session_tool_calls,
@@ -278,18 +260,19 @@ export {
   build_chat_message_text,
   parse_chat_message_markup,
   render_chat_message_file_tag,
-} from "./executor/messages/ChatMessageMarkup.js";
+} from "./model/messages/ChatMessageMarkup.js";
 export type {
   ChatMessageFileTag,
   ChatMessageFileType,
   ChatMessageSegment,
   ChatMessageSendOptions,
-} from "./executor/messages/ChatMessageMarkupTypes.js";
+} from "./model/messages/ChatMessageMarkupTypes.js";
 
 // 日志
 export { get_logger, type Logger } from "./utils/logger/Logger.js";
 export { generate_id } from "./utils/Id.js";
 export {
+  format_date_in_timezone,
   format_date_time_in_timezone,
   resolve_runtime_timezone,
 } from "./utils/Time.js";
@@ -297,4 +280,4 @@ export {
 // JSON 基础类型
 export type { JsonObject, JsonPrimitive, JsonValue } from "@downcity/type";
 
-export { resolve_session_id } from "./executor/ids/resolveSessionId.js";
+export { resolve_session_id } from "./utils/ResolveSessionId.js";

package/src/{executor/model → model}/ModelGenerate.ts

@@ -13,11 +13,11 @@ import type {
   ModelToolCallContent,
   ModelUsage,
 } from "@downcity/type";
-import { execute_model_request } from "@executor/model/ModelRequestRunner.js";
-import { consume_model_stream } from "@executor/model/ModelStreamConsumer.js";
+import { execute_model_request } from "@/model/ModelRequestRunner.js";
+import { consume_model_stream } from "@/model/ModelStreamConsumer.js";
 import type {
   ModelRequestFailureReporter,
-} from "@/types/executor/ModelRequest.js";
+} from "@/types/model/ModelRequest.js";
 
 /** 单次非交互模型生成结果。 */
 export interface ModelGenerateResult {

package/src/{executor/model → model}/ModelRequestRunner.ts

@@ -5,11 +5,11 @@
  */
 
 import type { ModelRequestKind } from "@downcity/type";
-import type { ModelRequestFailureReporter } from "@/types/executor/ModelRequest.js";
+import type { ModelRequestFailureReporter } from "@/types/model/ModelRequest.js";
 import {
   ModelStreamFailure,
   is_retryable_empty_model_stream_failure,
-} from "@executor/model/ModelStreamFailure.js";
+} from "@/model/ModelStreamFailure.js";
 
 /** 首次模型调用失败后的最大自动重试次数。 */
 export const MAX_MODEL_REQUEST_RETRIES = 5;

package/src/{executor/model → model}/ModelStepRunner.ts

@@ -14,17 +14,17 @@ import {
   type ModelStreamEvent,
   type ModelTool,
   type ModelUsage,
-  type RuntimeTool as Tool,
-  type RuntimeToolExecutionOptions as ToolExecutionOptions,
 } from "@downcity/type";
+import type { BoundAgentTool, ToolCallSite } from "@/types/tool/BoundAgentTool.js";
 import { z } from "zod";
-import type { SessionSystemMessage } from "@/executor/types/SessionPrompts.js";
-import type { SessionAssistantOutput } from "@/types/executor/SessionAssistantOutput.js";
+import type { SessionSystemMessage } from "@downcity/type";
+import type { SessionAssistantOutput } from "@/types/turn/SessionAssistantOutput.js";
 import type {
   SessionAgentMessagePart,
   SessionAgentToolPart,
 } from "@downcity/type";
-import { consume_model_stream } from "@/executor/model/ModelStreamConsumer.js";
+import { consume_model_stream } from "@/model/ModelStreamConsumer.js";
+import { validate_tool_input } from "@/model/ToolInputValidation.js";
 
 /** 单个工具调用的执行事实。 */
 export interface ModelStepToolCall {
@@ -70,14 +70,12 @@ export interface RunModelStepInput {
   system: SessionSystemMessage[];
   /** 当前模型上下文。 */
   messages: ModelMessage[];
-  /** 当前可用工具运行时。 */
-  tools: Record<string, Tool>;
+  /** 当前可用工具运行时；上下文已在包装层绑定。 */
+  tools: Record<string, BoundAgentTool>;
   /** 当前取消信号。 */
   abort_signal: AbortSignal;
   /** canonical Assistant 输出端口。 */
   assistant_output?: SessionAssistantOutput;
-  /** 工具执行前的审批回调。 */
-  approve_tool?: (call: ModelStepToolCall, tool: Tool) => Promise<boolean>;
 }
 
 /** 执行一个 Downcity 模型 Step 并收敛工具结果。 */
@@ -261,26 +259,31 @@ async function execute_tools(
       });
       continue;
     }
-    const approved = input.approve_tool
-      ? await input.approve_tool(call, tool)
-      : true;
-    if (!approved) {
+    // 关键点（中文）：模型输入先按工具自己的 schema 校验，非法输入在执行之前
+    // 就形成结构化失败，不会带着错误类型进入工具实现。
+    const validated = validate_tool_input({
+      tool,
+      tool_name: call.tool_name,
+      input: call.input,
+    });
+    if ("error" in validated) {
       results.push({
         ...call,
         success: false,
-        output: { error: "Tool execution denied" },
+        output: { error: validated.error },
       });
       continue;
     }
     try {
-      const options: ToolExecutionOptions = {
+      const site: ToolCallSite = {
         tool_call_id: call.tool_call_id,
         messages,
-        abort_signal: input.abort_signal,
+        ...(input.abort_signal ? { abort_signal: input.abort_signal } : {}),
       };
-      const output = await tool.execute(call.input, options);
+      const output = await tool.execute(validated.input, site);
       results.push({
         ...call,
+        input: validated.input,
         success: !is_structured_tool_failure(output),
         output,
       });
@@ -314,8 +317,8 @@ function convert_system_messages(messages: SessionSystemMessage[]): ModelMessage
   }));
 }
 
-/** 把 Agent 工具定义转换为只含 JSON Schema 的模型协议。 */
-function convert_tools(tools: Record<string, Tool>): ModelTool[] {
+/** 把已绑定工具定义转换为只含 JSON Schema 的模型协议。 */
+function convert_tools(tools: Record<string, BoundAgentTool>): ModelTool[] {
   return Object.entries(tools).map(([name, tool]) => ({
     name,
     description: tool.description ?? "",

package/src/{executor/model → model}/ModelStreamConsumer.ts

@@ -17,7 +17,7 @@ import {
   ModelStreamFailure,
   normalize_model_invocation_failure,
   normalize_model_protocol_failure,
-} from "@executor/model/ModelStreamFailure.js";
+} from "@/model/ModelStreamFailure.js";
 
 /** 消费并校验一次完整模型事件流。 */
 export async function consume_model_stream(

package/src/model/README.md

@@ -0,0 +1,117 @@
+# Execution Module
+
+`model/` 是模型请求与 Tool Loop 的低层内核；Session 级编排在 `session/runner/`。普通 SDK 用户只通过 `Session` 调用它。
+
+完整 Session Runtime 设计见 [`docs/session-runtime-architecture.md`](../../../../docs/session-runtime-architecture.md)。
+
+## 边界
+
+- `Session` 拥有输入队列并创建 Command；`SessionLoop` 负责消费、Turn Handle 与 Assistant Message 收口。
+- `SessionTurnContext` 从 Turn 创建起唯一拥有取消信号、Step 快照和执行期资源。
+- `SessionComposer` 根据只读 Session 快照组装 system、messages 和 tools。
+- `StepInput` 是 SessionLoop 的「输入环境」：刷新 Hook、请求 Composer 组装、冻结并套用 system、绑定工具执行上下文。
+- `SessionExecutor` 负责模型请求、Tool Loop、续写恢复、上下文超限重试与真实 usage 观测；它只对外提供 `execute()`，Step 输入由回调提供。
+- `ModelRequestRunner` 唯一拥有普通模型请求的五次重试、退避和逐次失败通知。
+- `SessionMessages` 是 Message 唯一事实源；执行层不写文件、不持有 Store。
+
+## 执行关系
+
+```mermaid
+flowchart LR
+    Loop["SessionLoop"] --> Context["SessionTurnContext"]
+    Loop --> Assembly["StepInput"]
+    Assembly --> Composer["SessionComposer"]
+    Composer --> Input["system + messages + tools"]
+    Context --> Executor["SessionExecutor"]
+    Input --> Executor
+    Executor --> Request["ModelRequestRunner"]
+    Request --> Step["ModelStepRunner"]
+    Step --> Model["ModelClient"]
+    Executor --> Tools["Tools / Plugins"]
+    Model -->|"ModelStreamEvent"| Step
+    Step --> Request
+    Step -->|"ModelStreamEvent / Tool Result"| Context
+    Context --> Messages["SessionMessages"]
+```
+
+每个模型 Step 前，`SessionLoop` 先消费排队的 Steer 和状态 Command。`StepInput` 随后捕获最新 effective state，并调用 Composer 生成完整 Step 输入。
+
+```text
+Session.prompt()
+  -> SessionLoop 持久化 canonical User Message
+  -> StepInput 捕获只读 Session 快照
+  -> SessionComposer.compose()
+  -> SessionModelMessages: SessionMessage -> ModelMessage
+  -> SessionExecutor.execute()
+  -> Federation / Provider 返回 ModelStreamEvent
+  -> SessionAssistantOutput 直接更新 canonical Assistant Message
+  -> SessionMessages 持久化并发布 Mutation
+```
+
+## 旧 Composer 去向
+
+过去的四个独立 Composer 不再构成执行管线：
+
+| 旧能力 | 当前归属 |
+| --- | --- |
+| `SystemComposer` | `DefaultSessionComposer.compose()` + `SessionSystem` |
+| `HistoryComposer` | `SessionComposer.compose()` + `SessionModelMessages` |
+| `ContextComposer` 的 tools | `Session` 装配 + `SessionComposer.compose()` |
+| `ContextComposer` 的 Step Callback | `SessionLoop` + `StepInput` |
+| `ContextComposer` 的 fallback Assistant | `SessionExecutor` + `ContextAdvanceRetry` |
+| `CompactionComposer` | `SessionComposer.advance_context()` + `session/input/composer/` 内的算法与派生表 |
+
+统一 Composer 只回答一个策略问题：
+
+1. 当前 Step 的 system、messages 和 tools 是什么？上下文超限时能否推进派生上下文？
+
+Queue 消费、Turn 控制、Message 写入和 Mutation 发布都不是 Composer 职责。
+
+## Context advance
+
+```text
+SessionLoop / ContextAdvanceRetry
+  -> Session.advance_context(trigger)
+  -> SessionComposer.advance_context()
+  -> 默认实现在自己的 checkpoint 派生表推进边界
+  -> 下一次 compose() 读取最新派生上下文
+```
+
+Composer 只接收调用方读好的 canonical history 快照与命名空间派生存储；它可以调用模型生成摘要，
+但不能修改 canonical Message、Metadata 或发布事件。持久化提交始终由 `SessionStorage` 事务完成。
+
+## 目录
+
+```text
+model/
+  ModelGenerate.ts          共享的一次性模型生成入口
+  ModelRequestRunner.ts     单次模型请求的重试与失败通知
+  ModelStepRunner.ts        单个 Tool Loop Step 的模型调用
+  ModelStreamConsumer.ts    模型流消费
+  ModelStreamFailure.ts     模型流错误分类
+  messages/                 Session 与 Model Protocol 消息转换
+  prompts/                  默认 core system prompt 资产
+
+types/model/
+  ModelRequest.ts           模型请求失败上报契约
+
+types/turn/
+  SessionTurnContext.ts     一个 Turn 的执行上下文
+  SessionAssistantOutput.ts Turn 的 Assistant 输出端口
+
+session/input/
+  StepInput.ts             每步模型输入与冻结 system
+  SessionSystem.ts         默认 system block 组装
+  SessionHooks.ts          Hook 运行类
+  SessionHookPoints.ts     Hook 检查点目录
+  composer/                Composer 实现与压缩算法
+
+session/runner/
+  SessionExecutor.ts               模型请求、Tool Loop 与上下文推进重试
+  ToolLoopLimits.ts                Step 上限与边界提示
+  ToolLoopDecision.ts              是否继续下一轮的纯决策
+  AssistantParts.ts                Assistant 产出读取与诊断
+  ModelFailure.ts                  模型调用错误归一化
+  ContextPressure.ts               usage 压力阈值判断
+  ContextRetry.ts                  推进上下文后重试整轮
+```