@downcity/agent 1.1.408 → 1.1.437

package/src/executor/model/ModelStepRunner.ts

@@ -6,10 +6,8 @@
  */
 
 import {
-  ModelStreamValidator,
   type ModelCall,
   type ModelClient,
-  type ModelContent,
   type ModelFinishReason,
   type ModelJsonValue,
   type ModelMessage,
@@ -23,10 +21,10 @@ import { z } from "zod";
 import type { SessionSystemMessage } from "@/executor/types/SessionPrompts.js";
 import type { SessionAssistantOutput } from "@/types/executor/SessionAssistantOutput.js";
 import type {
-  SessionAssistantMessagePart,
-  SessionAssistantToolPart,
-} from "@/types/session/SessionMessage.js";
-import { ModelStreamFailure } from "@/executor/model/ModelStreamFailure.js";
+  SessionAgentMessagePart,
+  SessionAgentToolPart,
+} from "@downcity/type";
+import { consume_model_stream } from "@/executor/model/ModelStreamConsumer.js";
 
 /** 单个工具调用的执行事实。 */
 export interface ModelStepToolCall {
@@ -60,8 +58,6 @@ export interface ModelStepResult {
   tool_calls: ModelStepToolCall[];
   /** 当前 Step 的工具结果。 */
   tool_results: ModelStepToolResult[];
-  /** 用于后续模型 Step 的消息。 */
-  response: { messages: ModelMessage[] };
   /** 供诊断代码读取的内容事实。 */
   content: Array<Record<string, unknown>>;
 }
@@ -87,7 +83,7 @@ export interface RunModelStepInput {
 /** 执行一个 Downcity 模型 Step 并收敛工具结果。 */
 export async function run_model_step(input: RunModelStepInput): Promise<{
   /** 当前 Step 的 canonical Assistant Parts。 */
-  assistant_parts: SessionAssistantMessagePart[];
+  assistant_parts: SessionAgentMessagePart[];
   /** 当前 Step 的运行结果。 */
   step_result: ModelStepResult;
 }> {
@@ -95,15 +91,17 @@ export async function run_model_step(input: RunModelStepInput): Promise<{
     messages: [...convert_system_messages(input.system), ...input.messages],
     tools: convert_tools(input.tools),
   };
-  const stream = await input.model.stream(call, input.abort_signal);
   const collector = new StepEventCollector();
-  const validator = new ModelStreamValidator();
-  for await (const event of stream) {
-    validator.accept(event);
-    await input.assistant_output?.write_model_event(event);
-    collector.accept(event);
-  }
-  validator.finish();
+  await consume_model_stream(
+    input.model,
+    call,
+    input.abort_signal,
+    () => collector.has_partial_output(),
+    async (event) => {
+      await input.assistant_output?.write_model_event(event);
+      collector.accept(event);
+    },
+  );
   const collected = collector.finish();
   const tool_results = await execute_tools(
     collected.tool_calls,
@@ -122,19 +120,6 @@ export async function run_model_step(input: RunModelStepInput): Promise<{
     collected.assistant_parts,
     tool_results,
   );
-  const response_messages: ModelMessage[] = [collected.assistant_model_message];
-  if (tool_results.length > 0) {
-    response_messages.push({
-      role: "tool",
-      content: tool_results.map((result) => ({
-        type: "tool_result",
-        tool_call_id: result.tool_call_id,
-        tool_name: result.tool_name,
-        outcome: result.success ? "succeeded" : "failed",
-        content: [{ type: "json", value: to_model_json_value(result.output) }],
-      })),
-    });
-  }
   return {
     assistant_parts,
     step_result: {
@@ -143,7 +128,6 @@ export async function run_model_step(input: RunModelStepInput): Promise<{
       ...(collected.usage ? { usage: collected.usage } : {}),
       tool_calls: collected.tool_calls,
       tool_results,
-      response: { messages: response_messages },
       content: collected.tool_calls.map((tool_call) => ({
         type: "tool-call",
         ...tool_call,
@@ -154,8 +138,7 @@ export async function run_model_step(input: RunModelStepInput): Promise<{
 
 /** 模型事件聚合器。 */
 class StepEventCollector {
-  private readonly model_content: ModelContent[] = [];
-  private readonly assistant_parts: SessionAssistantMessagePart[] = [];
+  private readonly assistant_parts: SessionAgentMessagePart[] = [];
   private readonly text_by_id = new Map<string, string>();
   private readonly reasoning_by_id = new Map<string, string>();
   private readonly tool_by_content_id = new Map<string, ModelStepToolCall>();
@@ -163,16 +146,15 @@ class StepEventCollector {
   private finish_reason?: ModelFinishReason;
   private text = "";
 
+  /** 当前调用是否已经产生不可安全重复的模型输出。 */
+  has_partial_output(): boolean {
+    return this.text.length > 0 ||
+      this.reasoning_by_id.size > 0 ||
+      this.tool_by_content_id.size > 0;
+  }
+
   /** 消费单个标准模型事件。 */
   accept(event: ModelStreamEvent): void {
-    if (event.type === "model_error") {
-      throw new ModelStreamFailure(
-        event.error,
-        this.text.length > 0 ||
-          this.reasoning_by_id.size > 0 ||
-          this.tool_by_content_id.size > 0,
-      );
-    }
     if (event.type === "text_start") {
       this.text_by_id.set(event.content_id, "");
     } else if (event.type === "text_delta") {
@@ -183,7 +165,6 @@ class StepEventCollector {
       this.text += event.delta;
     } else if (event.type === "text_finish") {
       const text = this.text_by_id.get(event.content_id) ?? "";
-      this.model_content.push({ type: "text", text });
       this.assistant_parts.push({
         part_id: `text:${event.content_id}`,
         sequence: this.assistant_parts.length + 1,
@@ -200,11 +181,6 @@ class StepEventCollector {
       );
     } else if (event.type === "reasoning_finish") {
       const text = this.reasoning_by_id.get(event.content_id) ?? "";
-      this.model_content.push({
-        type: "reasoning",
-        text,
-        ...(event.signature ? { signature: event.signature } : {}),
-      });
       this.assistant_parts.push({
         part_id: `reasoning:${event.content_id}`,
         sequence: this.assistant_parts.length + 1,
@@ -224,12 +200,6 @@ class StepEventCollector {
       if (tool) {
         tool.input = event.input;
         if (event.input_error) tool.input_error = event.input_error;
-        this.model_content.push({
-          type: "tool_call",
-          tool_call_id: tool.tool_call_id,
-          tool_name: tool.tool_name,
-          input: tool.input,
-        });
         this.assistant_parts.push({
           part_id: `tool:${tool.tool_call_id}`,
           sequence: this.assistant_parts.length + 1,
@@ -249,8 +219,7 @@ class StepEventCollector {
 
   /** 返回完整 Step 聚合结果。 */
   finish(): {
-    assistant_parts: SessionAssistantMessagePart[];
-    assistant_model_message: ModelMessage;
+    assistant_parts: SessionAgentMessagePart[];
     finish_reason: ModelFinishReason;
     usage?: ModelUsage;
     text: string;
@@ -259,7 +228,6 @@ class StepEventCollector {
     if (!this.finish_reason) throw new Error("Model stream ended without model_finish");
     return {
       assistant_parts: this.assistant_parts,
-      assistant_model_message: { role: "assistant", content: this.model_content },
       finish_reason: this.finish_reason,
       ...(this.usage ? { usage: this.usage } : {}),
       text: this.text,
@@ -377,9 +345,9 @@ function to_model_json_value(value: unknown): ModelJsonValue {
 
 /** 把工具结果合并到 canonical Tool Parts。 */
 function append_tool_results(
-  parts: SessionAssistantMessagePart[],
+  parts: SessionAgentMessagePart[],
   results: ModelStepToolResult[],
-): SessionAssistantMessagePart[] {
+): SessionAgentMessagePart[] {
   if (results.length === 0) return parts;
   const result_by_id = new Map(results.map((result) => [result.tool_call_id, result]));
   return parts.map((part) => {
@@ -391,12 +359,12 @@ function append_tool_results(
           ...part,
           state: "completed",
           output: to_model_json_value(result.output),
-        } satisfies SessionAssistantToolPart
+        } satisfies SessionAgentToolPart
       : {
           ...part,
           state: "failed",
           error: read_tool_error(result.output),
-        } satisfies SessionAssistantToolPart;
+        } satisfies SessionAgentToolPart;
   });
 }
 

package/src/executor/model/ModelStreamConsumer.ts

@@ -0,0 +1,76 @@
+/**
+ * 单次模型流消费基础设施。
+ *
+ * 关键点（中文）
+ * - 统一负责模型调用、协议校验、读取失败归一化与 reader 释放。
+ * - 调用方通过事件回调维护自己的领域状态，本模块不理解 Session、Tool 或文本聚合。
+ * - `has_partial_output` 由调用方基于已接收事实判断，保证失败恢复语义准确。
+ */
+
+import {
+  ModelStreamValidator,
+  type ModelCall,
+  type ModelClient,
+  type ModelStreamEvent,
+} from "@downcity/type";
+import {
+  ModelStreamFailure,
+  normalize_model_invocation_failure,
+  normalize_model_protocol_failure,
+} from "@executor/model/ModelStreamFailure.js";
+
+/** 消费并校验一次完整模型事件流。 */
+export async function consume_model_stream(
+  model: ModelClient,
+  call: ModelCall,
+  abort_signal: AbortSignal | undefined,
+  has_partial_output: () => boolean,
+  accept_event: (event: ModelStreamEvent) => void | Promise<void>,
+): Promise<void> {
+  const validator = new ModelStreamValidator();
+  let stream: ReadableStream<ModelStreamEvent>;
+  try {
+    stream = await model.stream(call, abort_signal);
+  } catch (error) {
+    throw normalize_model_invocation_failure(error, false, abort_signal);
+  }
+
+  const reader = stream.getReader();
+  let stream_complete = false;
+  try {
+    while (true) {
+      let result: Awaited<ReturnType<typeof reader.read>>;
+      try {
+        result = await reader.read();
+      } catch (error) {
+        throw normalize_model_invocation_failure(
+          error,
+          has_partial_output(),
+          abort_signal,
+        );
+      }
+      if (result.done) {
+        stream_complete = true;
+        break;
+      }
+      try {
+        validator.accept(result.value);
+      } catch (error) {
+        throw normalize_model_protocol_failure(error, has_partial_output());
+      }
+      await accept_event(result.value);
+      if (result.value.type === "model_error") {
+        throw new ModelStreamFailure(result.value.error, has_partial_output());
+      }
+    }
+  } finally {
+    if (!stream_complete) await reader.cancel().catch(() => undefined);
+    reader.releaseLock();
+  }
+
+  try {
+    validator.finish();
+  } catch (error) {
+    throw normalize_model_protocol_failure(error, has_partial_output());
+  }
+}

package/src/executor/model/ModelStreamFailure.ts

@@ -33,6 +33,34 @@ export class ModelStreamFailure extends Error {
   }
 }
 
+/** 把 ModelClient 直接抛出的调用异常归一为可恢复的模型传输失败。 */
+export function normalize_model_invocation_failure(
+  error: unknown,
+  has_partial_output: boolean,
+  abort_signal?: AbortSignal,
+): ModelStreamFailure {
+  if (error instanceof ModelStreamFailure) return error;
+  const cancelled = abort_signal?.aborted === true;
+  return new ModelStreamFailure({
+    code: cancelled ? "cancelled" : "transport_error",
+    message: error instanceof Error ? error.message : String(error),
+    retryable: !cancelled,
+  }, has_partial_output);
+}
+
+/** 把不合法的模型协议流归一为不可重试的 Provider 失败。 */
+export function normalize_model_protocol_failure(
+  error: unknown,
+  has_partial_output: boolean,
+): ModelStreamFailure {
+  if (error instanceof ModelStreamFailure) return error;
+  return new ModelStreamFailure({
+    code: "provider_error",
+    message: error instanceof Error ? error.message : String(error),
+    retryable: false,
+  }, has_partial_output);
+}
+
 /** 判断未知错误是否为可安全自动重试的无输出模型流失败。 */
 export function is_retryable_empty_model_stream_failure(
   error: unknown,

package/src/executor/services/ExecutorRecoveryPolicy.ts

@@ -3,17 +3,12 @@
  *
  * 关键点（中文）
  * - 统一封装“压缩后重试”和“普通失败兜底”逻辑。
- * - Executor 只负责准备输入与调用策略，不再直接承载重试状态机。
+ * - Executor 提供单次 Turn 行为，本模块只决定是否恢复并重试。
  * - 不改变外部行为，只把异常分流规则集中到一个地方。
  */
 
-import type { ModelClient } from "@downcity/type";
 import type { Logger } from "@/utils/logger/Logger.js";
-import type { SessionTurnContext } from "@/types/executor/SessionTurnContext.js";
-import type {
-  SessionStepExecutionInput,
-  SessionTurnExecutionResult,
-} from "@/types/session/SessionExecution.js";
+import type { SessionTurnExecutionResult } from "@/types/session/SessionExecution.js";
 
 /**
  * 可压缩错误的最大重试次数。
@@ -24,8 +19,8 @@ interface ExecutorRecoveryPolicyOptions {
   /** 当前 Session 稳定标识。 */
   session_id: string;
 
-  /** 判断错误是否需要持久化压缩后重试。 */
-  should_compact: (error: unknown) => boolean;
+  /** 请求 Composer 尝试推进上下文派生状态。 */
+  recover_context: (error: unknown) => Promise<boolean>;
 
   /**
    * 当前 session 统一日志器。
@@ -33,145 +28,64 @@ interface ExecutorRecoveryPolicyOptions {
   logger: Logger;
 }
 
-interface ExecutorPrepareExecutionInput {
-  /**
-   * 当前轮用户 query。
-   */
-  query: string;
-
-  /**
-   * 当前轮模型实例。
-   */
-  model: ModelClient;
-
-  /**
-   * 当前显式运行上下文。
-   */
-  turn_context: SessionTurnContext;
-
-  /**
-   * 当前压缩重试次数。
-   */
-  retry_count: number;
-}
-
-interface ExecutorExecutePreparedInput {
-  /**
-   * 已装配好的执行输入。
-   */
-  execute_input: SessionStepExecutionInput;
-
-  /**
-   * 当前轮模型实例。
-   */
-  model: ModelClient;
-
-  /**
-   * 当前显式运行上下文。
-   */
-  turn_context: SessionTurnContext;
-}
-
 interface ExecutorRecoveryInput {
-  /**
-   * 当前轮用户 query。
-   */
-  query: string;
-
-  /**
-   * 当前轮模型实例。
-   */
-  model: ModelClient;
-
-  /**
-   * 当前显式运行上下文。
-   */
-  turn_context: SessionTurnContext;
-
-  /**
-   * 运行前装配执行输入。
-   */
-  prepare_execute_input: (
-    input: ExecutorPrepareExecutionInput,
-  ) => Promise<SessionStepExecutionInput>;
-
-  /**
-   * 执行已装配好的运行输入。
-   */
-  execute_prepared_input: (
-    input: ExecutorExecutePreparedInput,
-  ) => Promise<SessionTurnExecutionResult>;
+  /** 按当前恢复次数执行完整 Turn。 */
+  execute_turn: (retry_count: number) => Promise<SessionTurnExecutionResult>;
 }
 
 /**
  * 执行恢复与重试策略服务。
  */
 export class ExecutorRecoveryPolicy {
-  private readonly should_compact: ExecutorRecoveryPolicyOptions["should_compact"];
+  private readonly recover_context: ExecutorRecoveryPolicyOptions["recover_context"];
   private readonly logger: Logger;
-  private retry_count = 0;
 
   constructor(options: ExecutorRecoveryPolicyOptions) {
     const session_id = String(options.session_id || "").trim();
-    this.should_compact = options.should_compact;
+    this.recover_context = options.recover_context;
     this.logger = options.logger;
     if (!session_id) {
       throw new Error("ExecutorRecoveryPolicy requires a non-empty session_id");
     }
   }
 
-  /**
-   * 重置当前 Turn 执行状态。
-   */
-  reset_execution_state(): void {
-    this.retry_count = 0;
-  }
-
   /**
    * 执行一次带恢复策略的 Session Turn。
    */
   async execute_with_retry(
     input: ExecutorRecoveryInput,
   ): Promise<SessionTurnExecutionResult> {
-    try {
-      const execute_input = await input.prepare_execute_input({
-        query: input.query,
-        model: input.model,
-        turn_context: input.turn_context,
-        retry_count: this.retry_count,
-      });
-      return await input.execute_prepared_input({
-        execute_input,
-        model: input.model,
-        turn_context: input.turn_context,
-      });
-    } catch (error) {
-      if (this.should_compact(error)) {
-        await this.logger.log("info", "[agent] compacting", {
-          retryCount: this.retry_count,
-          error: String(error),
-        });
-
-        if (this.retry_count < MAX_COMPACTION_RETRY_ATTEMPTS) {
-          this.retry_count += 1;
-          return await this.execute_with_retry(input);
+    let retry_count = 0;
+    while (true) {
+      try {
+        return await input.execute_turn(retry_count);
+      } catch (error) {
+        if (retry_count < MAX_COMPACTION_RETRY_ATTEMPTS) {
+          const recovered = await this.recover_context(error);
+          if (recovered) {
+            await this.logger.log("info", "[agent] compacting", {
+              retryCount: retry_count,
+              error: String(error),
+            });
+            retry_count += 1;
+            continue;
+          }
+        }
+        if (retry_count > 0) {
+          return this.build_failure_result({
+            error_text:
+              "Context length exceeded and retries failed. Please resend your question.",
+          });
         }
 
+        const error_text = String(error);
+        await this.logger.log("error", "Executor execution failed", {
+          error: error_text,
+        });
         return this.build_failure_result({
-          error_text:
-            "Context length exceeded and retries failed. Please resend your question.",
-          turn_context: input.turn_context,
+          error_text,
         });
       }
-
-      const error_text = String(error);
-      await this.logger.log("error", "Executor execution failed", {
-        error: error_text,
-      });
-      return this.build_failure_result({
-        error_text,
-        turn_context: input.turn_context,
-      });
     }
   }
 
@@ -181,18 +95,11 @@ export class ExecutorRecoveryPolicy {
      */
     error_text: string;
 
-    /**
-     * 当前显式运行上下文。
-     */
-    turn_context: SessionTurnContext;
   }): SessionTurnExecutionResult {
     return {
       success: false,
       text: "",
       error: input.error_text,
-      deferred_persisted_user_messages: [
-        ...input.turn_context.input.deferred_user_messages(),
-      ],
     };
   }
 }

package/src/executor/types/SessionHistoryMeta.ts

@@ -2,23 +2,23 @@
  * SessionHistoryMeta：随 session_id 持久化的元信息。
  *
  * 关键点（中文）
- * - 存储位置：Agent Storage `sessions/<encodedSessionId>/meta.json`
+ * - 存储位置：Session SQLite 的 `session_state` 表
  * - 用于保存 session 列表、详情和索引所需的轻量元信息
  */
 
-import type { SessionOrigin } from "@/types/session/SessionOrigin.js";
+import type { SessionOrigin } from "@downcity/type";
 
-export type SessionHistoryMetaV1 = {
+export type SessionHistoryMeta = {
   /** schema 版本。 */
-  v: 1;
+  v: 2;
   /** 当前元信息所属的 session_id。 */
   session_id: string;
   /** 当前 session 所属的 agent_id。 */
   agent_id: string;
   /** 当前 session 所属的 workspace_id。 */
   workspace_id?: string;
-  /** 当前 Session 的创建来源；未填写时视为用户直接创建。 */
-  origin?: SessionOrigin;
+  /** 当前 Session 的创建来源与物理存储分区。 */
+  origin: SessionOrigin;
   /** 当前 session 首次创建时间戳（ms）。 */
   created_at?: number;
   /** 当前 session 初始化时解析到的系统时区。 */
@@ -35,6 +35,4 @@ export type SessionHistoryMetaV1 = {
   message_count?: number;
   /** 当前 session 最后一条记录的用户可见摘要，用于列表预览。 */
   preview_text?: string;
-  /** 生成当前摘要时 messages.jsonl 的字节长度，用于校验摘要是否仍然有效。 */
-  historyBytes?: number;
 };

package/src/group/Group.ts

@@ -2,22 +2,33 @@
 
 import { AiDispatchStrategy } from "@/types/group/DispatchStrategy.js";
 import type { DispatchStrategy } from "@/types/group/DispatchStrategy.js";
-import type { AgentModel } from "@/agent/AgentModel.js";
+import type { ModelClient, StorageProvider } from "@downcity/type";
 import type { GroupContract, GroupOptions } from "@/types/group/Group.js";
 import type { Agent } from "@/agent/Agent.js";
 import { GroupSessions } from "@/group/GroupSessions.js";
-import { dispose_group_runtime, initialize_group_runtime } from "@/internal/GroupRuntime.js";
+import { AgentMemoryStorageProvider } from "@/agent/AgentMemoryStorage.js";
+import { LocalGroupSessionStore } from "@/group/storage/LocalGroupSessionStore.js";
+import type { GroupSessionStore } from "@/types/group/GroupSessionStore.js";
 
 /** Group 主体：只持有身份、成员、资源引用和群聊上下文集合。 */
 export class Group implements GroupContract {
   readonly id: string;
   readonly name: string;
   readonly instruction?: string;
-  readonly model?: AgentModel;
+  readonly model?: ModelClient;
   readonly members: readonly Agent[];
   readonly dispatch_strategy: DispatchStrategy;
   readonly sessions: GroupSessions;
 
+  /** 未加入宿主时使用的隔离进程内存储。 */
+  private storage_provider: StorageProvider = new AgentMemoryStorageProvider();
+  /** 当前 Group 所属宿主。 */
+  private storage_owner?: object;
+  /** 延迟创建的 GroupSession 持久化 Store。 */
+  private session_store?: GroupSessionStore;
+  /** 是否已经在无宿主存储中创建或恢复过 Session。 */
+  private memory_session_started = false;
+
   constructor(options: GroupOptions) {
     this.id = String(options.id || "").trim();
     if (!this.id) throw new Error("Group requires a non-empty id");
@@ -33,13 +44,57 @@ export class Group implements GroupContract {
     this.instruction = options.instruction?.trim() || undefined;
     this.model = options.model;
     this.dispatch_strategy = options.dispatch_strategy || new AiDispatchStrategy({ model: this.model });
-    initialize_group_runtime(this);
     this.sessions = new GroupSessions(this);
   }
 
+  /** 将宿主存储装配到 Group；必须在使用 GroupSessions 前完成。 */
+  attach(owner: object, storage_provider: StorageProvider): void {
+    if (this.storage_owner) {
+      if (this.storage_owner === owner) return;
+      throw new Error(`Group "${this.id}" already belongs to another host`);
+    }
+    if (this.memory_session_started || this.session_store) {
+      throw new Error(
+        `Group "${this.id}" already used standalone storage; attach it before using GroupSessions`,
+      );
+    }
+    this.storage_owner = owner;
+    this.storage_provider = storage_provider;
+  }
+
+  /** 解除指定宿主的存储装配并释放当前 Store。 */
+  async detach(owner: object): Promise<void> {
+    if (this.storage_owner !== owner) return;
+    await this.dispose_session_store();
+    this.storage_owner = undefined;
+    this.storage_provider = new AgentMemoryStorageProvider();
+  }
+
+  /** 获取或创建 Group 唯一的 Session Store。 */
+  get_session_store(): GroupSessionStore {
+    if (this.session_store) return this.session_store;
+    const scope = this.storage_provider.open_scope(["groups", this.id]);
+    this.session_store = new LocalGroupSessionStore({
+      files: scope.files,
+      storage_root_path: scope.root_path,
+      group_id: this.id,
+    });
+    return this.session_store;
+  }
+
+  /** 标记 Group 已经创建或恢复过 Session。 */
+  mark_session_started(): void {
+    if (!this.storage_owner) this.memory_session_started = true;
+  }
+
+  /** 释放当前 GroupSession Store。 */
+  async dispose_session_store(): Promise<void> {
+    await this.session_store?.dispose();
+    this.session_store = undefined;
+  }
+
   /** 释放 Group 所拥有的全部群聊上下文。 */
   async dispose(): Promise<void> {
     await this.sessions.dispose();
-    await dispose_group_runtime(this);
   }
 }