@downcity/agent 1.1.258 → 1.1.260

package/src/agent/AgentModel.ts

@@ -3,51 +3,24 @@
  *
  * 关键点（中文）
  * - Agent 与 Session 对外统一接收 AgentModel，executor 内部只处理 AI SDK LanguageModel。
- * - CityModel 保留模型目录信息；运行时连接信息通过隐藏协议提供。
- * - 这里直接创建 OpenAI-compatible LanguageModel，不再保留旧的 text/stream 反向适配。
+ * - CityModel 自身实现 LanguageModelV3，executor 可以直接调用。
  * - 这里不依赖 @downcity/city，只依赖 @downcity/type 的共享协议。
  */
 
-import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
 import {
-  CITY_MODEL_INVOKER,
   isCityModel,
-  type CityModel,
 } from "@downcity/type";
 import type { LanguageModel } from "ai";
 
-/** 已完成转换的 CityModel 与 LanguageModel 对应关系。 */
-const normalized_models = new WeakMap<object, LanguageModel>();
-
 /**
  * Agent SDK 可接受的模型输入。
  */
-export type AgentModel = LanguageModel | CityModel;
-
-/**
- * 将 CityModel 的 hidden connection 转换为 AI SDK LanguageModel。
- */
-function cityModelToLanguageModel(model: CityModel): LanguageModel {
-  const connection = model[CITY_MODEL_INVOKER].connection();
-  const provider = createOpenAICompatible({
-    name: "downcity",
-    baseURL: connection.base_url,
-    apiKey: connection.api_key,
-  });
-  return provider.languageModel(connection.model_id) as LanguageModel;
-}
+export type AgentModel = LanguageModel;
 
 /**
  * 将 Agent 可接受的模型输入归一为 AI SDK LanguageModel。
  */
 export function normalizeAgentModel(model: AgentModel): LanguageModel {
-  if (isCityModel(model)) {
-    const cached = normalized_models.get(model);
-    if (cached) return cached;
-    const normalized = cityModelToLanguageModel(model);
-    normalized_models.set(model, normalized);
-    return normalized;
-  }
   return model;
 }
 

package/src/executor/README.md

@@ -2,37 +2,73 @@
 
 `executor/` 是 Session 内部的模型与 Tool Loop 执行内核。普通 SDK 用户只通过 `Session` 调用它。
 
+完整 Session Runtime 设计见 [`docs/session-runtime-architecture.md`](../../../../docs/session-runtime-architecture.md)。
+
 ## 边界
 
-- `SessionTurn` 拥有输入队列、Turn Handle、取消信号与 Message 收口。
-- `SessionComposer` 根据只读 Session 快照组装 system、history 和 tools。
-- `Executor` 管理单次模型执行、上下文超限重试和 Step Plugin lease。
-- `CoreEngineRunner` 执行 `streamText()`、Tool Loop、续写与内存上下文折叠。
+- `SessionTurn` 拥有输入队列、Turn Handle、取消信号与 Assistant Message 收口。
+- `SessionComposer` 根据只读 Session 快照组装 system、messages 和 tools。
+- `Executor` 管理单次模型执行、上下文超限重试和 Step Plugin Lease。
+- `CoreEngineRunner` 执行 `streamText()`、Tool Loop、续写和内存上下文折叠。
 - `SessionMessages` 是 Message 唯一事实源；Executor 不写文件、不持有 Store。
 
-## 调用链
+## 执行关系
+
+```mermaid
+flowchart LR
+    Turn["SessionTurn"] --> Executor
+    Executor --> Composer["SessionComposer"]
+    Composer --> Input["system + messages + tools"]
+    Executor --> Engine["CoreEngineRunner"]
+    Input --> Engine
+    Engine --> Model["LanguageModel"]
+    Engine --> Tools["Tools / Plugins"]
+    Engine -->|"Chunk / Callback"| Turn
+    Turn --> Messages["SessionMessages"]
+```
+
+每个模型 Step 前，`SessionTurn` 先消费排队的 Steer 和状态 Command。Executor 随后捕获最新 effective state，并调用 Composer 生成完整 Step 输入。
 
 ```text
 Session.prompt()
-  -> SessionTurn 写入 User Message
-  -> SessionComposer.compose(readonly snapshot)
-  -> Executor.run()
+  -> SessionTurn 持久化 User Message
+  -> Executor 捕获只读 Session 快照
+  -> SessionComposer.compose()
   -> CoreEngineRunner.run()
-  -> SessionTurn 接收 stream chunk
+  -> SessionTurn 接收 Stream Chunk
   -> SessionMessages 完成 Assistant Message
 ```
 
-每个模型 Step 前，`SessionTurn` 消费排队的 steer 和状态命令，Composer 再基于最新 effective state 生成完整 Step 输入。
+## 旧 Composer 去向
+
+过去的四个独立 Composer 不再构成执行管线：
+
+| 旧能力 | 当前归属 |
+| --- | --- |
+| `SystemComposer` | `DefaultSessionComposer.compose()` + `SessionSystem` |
+| `HistoryComposer` | `SessionMessages.context_snapshot()` + `SessionMessageCodec` |
+| `ContextComposer` 的 tools | `Session.create_compose_input()` + `SessionComposer.compose()` |
+| `ContextComposer` 的 Step Callback | `SessionTurn` + `CoreEngineRunner` |
+| `ContextComposer` 的 fallback Assistant | `CoreEngineRunner` + `ExecutorRecoveryPolicy` |
+| `CompactionComposer` | `SessionComposer.compact()` + `should_compact()` |
+
+统一 Composer 只回答两个策略问题：
+
+1. 当前 Step 的 system、messages 和 tools 是什么？
+2. 当前只读 Message 快照应生成什么压缩计划？
+
+Queue 消费、Turn 控制、Message 写入、Mutation 发布和 Segment 提交都不是 Composer 职责。
 
 ## Compaction
 
 ```text
-SessionComposer.compact(snapshot)
+SessionComposer.compact(readonly snapshot)
   -> SessionCompactionPlan
-  -> SessionMessages.compact_active(plan)
+  -> Session.commit_compaction_plan()
+  -> SessionMessages.compact_active()
 ```
 
-Composer 可以调用模型生成 Summary，但不能修改 Message、Metadata 或发布事件。持久化提交始终由 Session 完成。
+Composer 可以调用模型生成 Summary，但不能修改 Message、Metadata 或发布事件。持久化提交始终由 Session 领域完成。
 
 ## 目录
 
@@ -40,7 +76,7 @@ Composer 可以调用模型生成 Summary，但不能修改 Message、Metadata
 executor/
   Executor.ts
   core-engine/       模型与 Tool Loop
-  composer/system/   默认 system prompt 领域实现
+  composer/system/   可复用的默认 system prompt 领域实现
   messages/          AI SDK 消息转换
   services/          执行恢复策略
   tools/             Tool 运行辅助

package/src/session/SessionMessages.ts

@@ -2,6 +2,8 @@
  * SessionMessages：Session Message 的唯一领域入口。
  *
  * 完整 Message 与 Assistant 草稿先持久化，成功后再发布实时 Mutation。
+ * 同一 Assistant Message 的流式、审批与关闭操作共享一条写队列，保证 revision
+ * 从最新快照严格递增。
  */
 
 import type { UIMessage } from "ai";
@@ -65,6 +67,8 @@ export class SessionMessages {
   private readonly store: JsonlSessionMessageStore;
   private readonly publish: SessionMessagesOptions["publish"];
   private readonly messages_by_id = new Map<string, SessionMessage>();
+  /** 按 Assistant Message 隔离的完整写事务链。 */
+  private readonly assistant_write_chains = new Map<string, Promise<void>>();
   private initialized = false;
 
   constructor(options: SessionMessagesOptions) {
@@ -514,6 +518,18 @@ export class SessionMessages {
     delta: string,
   ): Promise<void> {
     if (!delta) return;
+    await this.enqueue_assistant_write(message_id, async () => {
+      await this.append_assistant_delta_serialized(message_id, part_id, type, delta);
+    });
+  }
+
+  /** 在 Assistant 写队列内追加文本 delta。 */
+  private async append_assistant_delta_serialized(
+    message_id: string,
+    part_id: string,
+    type: "text" | "reasoning",
+    delta: string,
+  ): Promise<void> {
     const current = require_message([...this.messages_by_id.values()], message_id, "assistant");
     require_streaming_assistant(current);
     const part = current.parts.find((item) => item.part_id === part_id);
@@ -551,6 +567,16 @@ export class SessionMessages {
   async update_assistant_part(
     message_id: string,
     part: SessionAssistantMessagePart,
+  ): Promise<void> {
+    await this.enqueue_assistant_write(message_id, async () => {
+      await this.update_assistant_part_serialized(message_id, part);
+    });
+  }
+
+  /** 在 Assistant 写队列内提交完整 Part 快照。 */
+  private async update_assistant_part_serialized(
+    message_id: string,
+    part: SessionAssistantMessagePart,
   ): Promise<void> {
     const current = require_message([...this.messages_by_id.values()], message_id, "assistant");
     require_streaming_assistant(current);
@@ -588,6 +614,16 @@ export class SessionMessages {
   async complete_assistant_message(
     message_id: string,
     status: "completed" | "stopped" | "failed",
+  ): Promise<void> {
+    await this.enqueue_assistant_write(message_id, async () => {
+      await this.complete_assistant_message_serialized(message_id, status);
+    });
+  }
+
+  /** 在 Assistant 写队列内关闭草稿并写入 Active。 */
+  private async complete_assistant_message_serialized(
+    message_id: string,
+    status: "completed" | "stopped" | "failed",
   ): Promise<void> {
     const current = require_message([...this.messages_by_id.values()], message_id, "assistant");
     require_streaming_assistant(current);
@@ -645,16 +681,22 @@ export class SessionMessages {
 
   /** 把完整审批请求写入对应的流式 Tool Part。 */
   async request_tool_approval(approval: SessionApproval): Promise<void> {
-    const tool = this.require_streaming_tool(approval.tool_call_id);
-    if (tool.part.state !== "ready") {
-      throw new Error(
-        `Tool approval requires ready input: ${approval.tool_call_id} (${tool.part.state})`,
-      );
-    }
-    await this.update_assistant_part(tool.message_id, {
-      ...tool.part,
-      state: "approval-required",
-      approval,
+    const { message_id } = this.require_streaming_tool(approval.tool_call_id);
+    await this.enqueue_assistant_write(message_id, async () => {
+      const tool = this.require_streaming_tool(approval.tool_call_id);
+      if (tool.message_id !== message_id) {
+        throw new Error(`Tool Assistant Message changed: ${approval.tool_call_id}`);
+      }
+      if (tool.part.state !== "ready") {
+        throw new Error(
+          `Tool approval requires ready input: ${approval.tool_call_id} (${tool.part.state})`,
+        );
+      }
+      await this.update_assistant_part_serialized(message_id, {
+        ...tool.part,
+        state: "approval-required",
+        approval,
+      });
     });
   }
 
@@ -667,24 +709,52 @@ export class SessionMessages {
     /** 当前审批关联的 Tool Call。 */
     tool_call_id: string;
   }): Promise<void> {
-    const tool = this.require_streaming_tool(input.tool_call_id);
-    if (tool.part.approval?.approval_id !== input.approval_id) {
-      throw new Error(`Tool approval identity mismatch: ${input.approval_id}`);
-    }
-    await this.update_assistant_part(tool.message_id, {
-      ...tool.part,
-      state: input.decision === "approved" ? "running" : "failed",
-      ...(input.decision === "approved"
-        ? {}
-        : {
-            error:
-              input.decision === "expired"
-                ? "Approval expired"
-                : "Approval denied",
-          }),
+    const { message_id } = this.require_streaming_tool(input.tool_call_id);
+    await this.enqueue_assistant_write(message_id, async () => {
+      const tool = this.require_streaming_tool(input.tool_call_id);
+      if (tool.message_id !== message_id) {
+        throw new Error(`Tool Assistant Message changed: ${input.tool_call_id}`);
+      }
+      if (tool.part.approval?.approval_id !== input.approval_id) {
+        throw new Error(`Tool approval identity mismatch: ${input.approval_id}`);
+      }
+      await this.update_assistant_part_serialized(message_id, {
+        ...tool.part,
+        state: input.decision === "approved" ? "running" : "failed",
+        ...(input.decision === "approved"
+          ? {}
+          : {
+              error:
+                input.decision === "expired"
+                  ? "Approval expired"
+                  : "Approval denied",
+            }),
+      });
     });
   }
 
+  /**
+   * 串行执行同一 Assistant Message 的完整写事务。
+   *
+   * 失败事务不会阻塞后续写入；链尾仅用于排序，真实错误仍返回给调用方。
+   */
+  private async enqueue_assistant_write<T>(
+    message_id: string,
+    operation: () => Promise<T>,
+  ): Promise<T> {
+    const previous = this.assistant_write_chains.get(message_id) || Promise.resolve();
+    const result = previous.then(operation, operation);
+    const chain = result.then(() => undefined, () => undefined);
+    this.assistant_write_chains.set(message_id, chain);
+    try {
+      return await result;
+    } finally {
+      if (this.assistant_write_chains.get(message_id) === chain) {
+        this.assistant_write_chains.delete(message_id);
+      }
+    }
+  }
+
   /** 查找当前流式 Assistant 中的 Tool Part，否则抛出明确错误。 */
   private require_streaming_tool(tool_call_id: string): SessionStreamingToolLocation {
     const tool = this.find_streaming_tool(tool_call_id);