@downcity/agent 1.1.200 → 1.1.202

package/src/executor/core-engine/CoreEngineSignals.ts

@@ -12,7 +12,7 @@ import {
   isTextUIPart,
   isToolUIPart,
 } from "ai";
-import type { SessionModelMessageV1 } from "@/executor/types/SessionMessages.js";
+import type { SessionMessageRecordV1 } from "@/executor/types/SessionRecords.js";
 import type { JsonObject } from "@/types/common/Json.js";
 
 /**
@@ -192,7 +192,7 @@ export function summarizeStepForDebug(stepResult: unknown): JsonObject {
  * 汇总最终 assistant UI 消息的调试摘要。
  */
 export function summarizeUiMessageForDebug(
-  message: SessionModelMessageV1 | null | undefined,
+  message: SessionMessageRecordV1 | null | undefined,
 ): JsonObject {
   const parts = Array.isArray(message?.parts) ? message.parts : [];
   const text = parts
@@ -230,9 +230,9 @@ export function summarizeUiMessageForDebug(
  * - 多 step 场景下，最终 assistant message 需要把各 step 的 UI part 串起来。
  */
 export function mergeAssistantUiMessages(
-  base: SessionModelMessageV1 | null,
-  incoming: SessionModelMessageV1,
-): SessionModelMessageV1 {
+  base: SessionMessageRecordV1 | null,
+  incoming: SessionMessageRecordV1,
+): SessionMessageRecordV1 {
   if (!base) return incoming;
   const baseMetadata = base.metadata;
   const incomingMetadata = incoming.metadata;
@@ -254,7 +254,7 @@ export function mergeAssistantUiMessages(
 }
 
 function pickIncompleteToolParts(
-  message: SessionModelMessageV1 | null | undefined,
+  message: SessionMessageRecordV1 | null | undefined,
 ): Array<{
   toolName: string;
   state: string;
@@ -304,7 +304,7 @@ export function buildIncompleteResponseRecoveryNudge(
  */
 export function detectIncompleteResponse(params: {
   stepResult: unknown;
-  assistantMessage: SessionModelMessageV1 | null | undefined;
+  assistantMessage: SessionMessageRecordV1 | null | undefined;
 }): {
   reason: string;
   details: JsonObject;

package/src/executor/core-engine/CoreEngineUiStreamCollector.ts

@@ -10,7 +10,7 @@
 import type { streamText } from "ai";
 import type { Logger } from "@/utils/logger/Logger.js";
 import type { JsonObject } from "@/types/common/Json.js";
-import type { SessionModelMessageV1 } from "@/executor/types/SessionMessages.js";
+import type { SessionMessageRecordV1 } from "@/executor/types/SessionRecords.js";
 import type { SessionUiMessageChunkCallback } from "@/executor/types/SessionRun.js";
 import { generateId } from "@/utils/Id.js";
 import {
@@ -37,7 +37,7 @@ export async function collectFinalAssistantMessageFromUiStream(params: {
   /**
    * 构造 fallback assistant 消息的工厂函数。
    */
-  buildFallbackAssistantMessage: (text: string) => SessionModelMessageV1;
+  buildFallbackAssistantMessage: (text: string) => SessionMessageRecordV1;
   /**
    * UI stream chunk 回调。
    */
@@ -50,12 +50,12 @@ export async function collectFinalAssistantMessageFromUiStream(params: {
    * - 此时仍应尽量用已经收到的 text delta 构造可持久化 assistant 消息。
    */
   abortSignal?: AbortSignal;
-}): Promise<SessionModelMessageV1> {
-  let streamedAssistantMessage: SessionModelMessageV1 | null = null;
+}): Promise<SessionMessageRecordV1> {
+  let streamedAssistantMessage: SessionMessageRecordV1 | null = null;
   let uiFinishSummary: JsonObject | null = null;
   let streamed_text = "";
 
-  const uiStream = params.result.toUIMessageStream<SessionModelMessageV1>({
+  const uiStream = params.result.toUIMessageStream<SessionMessageRecordV1>({
     // 关键点（中文）：SDK stream 需要 reasoning 旁路事件时可直接消费；最终落盘仍由 responseMessage 收敛。
     originalMessages: [],
     generateMessageId: () => `a:${params.sessionId}:${generateId()}`,

package/src/executor/messages/AssistantResultPersistence.ts

@@ -8,9 +8,9 @@
  */
 
 import type {
-  SessionMessageV1,
-  SessionModelMessageV1,
-} from "@/executor/types/SessionMessages.js";
+  SessionRecordV1,
+  SessionMessageRecordV1,
+} from "@/executor/types/SessionRecords.js";
 import { resolveAssistantMessageForPersistence } from "@/executor/messages/UserVisibleText.js";
 
 /**
@@ -20,11 +20,11 @@ export interface AssistantResultPersistenceWriter {
   /**
    * 追加 assistant 消息。
    */
-  appendAssistantMessage(params: {
+  append_assistant_message(params: {
     /**
      * 已构造好的完整 assistant 消息。
      */
-    message?: SessionMessageV1 | null;
+    message?: SessionRecordV1 | null;
     /**
      * 在没有完整 message 可写时的兜底文本。
      */
@@ -43,7 +43,7 @@ export interface PersistAssistantResultParams {
   /**
    * 本轮执行得到的 assistant message。
    */
-  assistantMessage: SessionModelMessageV1 | null | undefined;
+  assistantMessage: SessionMessageRecordV1 | null | undefined;
   /**
    * 可选兜底文本。
    *
@@ -68,7 +68,7 @@ export function buildAssistantResultPersistencePayload(
   /**
    * 已构造好的完整 assistant message。
    */
-  message?: SessionModelMessageV1 | null;
+  message?: SessionMessageRecordV1 | null;
   /**
    * 允许写入的兜底文本。
    */
@@ -101,6 +101,6 @@ export async function persistAssistantResult(
     fallbackText: params.fallbackText,
   });
   if (!payload) return false;
-  await params.writer.appendAssistantMessage(payload);
+  await params.writer.append_assistant_message(payload);
   return true;
 }

package/src/executor/messages/SessionAttachmentMapper.ts

@@ -18,9 +18,9 @@ import {
 } from "ai";
 import type { SessionUserMessagePart } from "@/types/sdk/AgentSessionPrompt.js";
 import type {
-  SessionMessageV1,
-  SessionModelMessageV1,
-} from "@/executor/types/SessionMessages.js";
+  SessionRecordV1,
+  SessionMessageRecordV1,
+} from "@/executor/types/SessionRecords.js";
 import { parseChatMessageMarkup } from "@/executor/messages/ChatMessageMarkup.js";
 
 /**
@@ -174,12 +174,12 @@ export async function hydrateUserPromptFileParts(
  * - 新历史保留 Agent 根目录相对路径，旧历史的 `file://` 仍继续兼容。
  */
 export async function hydrateFileUrlPartsForModel(
-  messages: SessionModelMessageV1[],
+  messages: SessionMessageRecordV1[],
   projectRoot?: string,
-): Promise<SessionModelMessageV1[]> {
+): Promise<SessionMessageRecordV1[]> {
   if (!Array.isArray(messages) || messages.length === 0) return messages;
 
-  const out: SessionModelMessageV1[] = [];
+  const out: SessionMessageRecordV1[] = [];
   for (const message of messages) {
     const parts = Array.isArray(message?.parts) ? message.parts : [];
     if (!parts.some((part) => isFileUIPart(part as FileUIPart))) {
@@ -187,7 +187,7 @@ export async function hydrateFileUrlPartsForModel(
       continue;
     }
 
-    const nextParts: SessionModelMessageV1["parts"] = [];
+    const nextParts: SessionMessageRecordV1["parts"] = [];
     let changed = false;
     for (const part of parts) {
       if (!isFileUIPart(part as FileUIPart)) {
@@ -196,7 +196,7 @@ export async function hydrateFileUrlPartsForModel(
       }
       const nextPart = await hydrateFileUrlPart(part as FileUIPart, projectRoot);
       if (nextPart !== part) changed = true;
-      nextParts.push(nextPart as SessionModelMessageV1["parts"][number]);
+      nextParts.push(nextPart as SessionMessageRecordV1["parts"][number]);
     }
 
     out.push(changed ? { ...message, parts: nextParts } : message);
@@ -209,13 +209,13 @@ export async function hydrateFileUrlPartsForModel(
  * 在 user 消息上注入 FileUIPart，以便多模态模型直接消费本地附件。
  */
 export async function injectFilePartsFromAttachments(
-  messages: SessionModelMessageV1[],
+  messages: SessionMessageRecordV1[],
   projectRoot?: string,
-): Promise<SessionModelMessageV1[]> {
+): Promise<SessionMessageRecordV1[]> {
   if (!Array.isArray(messages) || messages.length === 0) return messages;
 
   const root = path.resolve(String(projectRoot || "").trim() || process.cwd());
-  const out: SessionModelMessageV1[] = [];
+  const out: SessionMessageRecordV1[] = [];
 
   for (const message of messages) {
     if (!message || typeof message !== "object" || message.role !== "user") {

package/src/executor/messages/SessionMessageCodec.ts

@@ -15,9 +15,9 @@ import {
   type ToolSet,
 } from "ai";
 import {
-  isSessionModelMessage,
-  type SessionMessageV1,
-} from "@/executor/types/SessionMessages.js";
+  is_session_message_record,
+  type SessionRecordV1,
+} from "@/executor/types/SessionRecords.js";
 import {
   hydrateFileUrlPartsForModel,
   injectFilePartsFromAttachments,
@@ -28,19 +28,19 @@ import {
  *
  * 关键点（中文）
  * - 用途：从 onStepCallback 返回的消息里挑出可并入推理上下文的 user 文本。
- * - 输入：任意 SessionMessageV1[]（可能混有 assistant/tool/action/空消息）。
+ * - 输入：任意 SessionRecordV1[]（可能混有 assistant/tool/action/空消息）。
  * - 输出：只包含“非空 user 文本”的消息数组。
  */
 export function pickMergedUserMessages(
-  messages: SessionMessageV1[],
-): SessionMessageV1[] {
+  messages: SessionRecordV1[],
+): SessionRecordV1[] {
   // 如果不是数组，直接返回空数组，避免后续 filter 报错。
   if (!Array.isArray(messages)) return [];
 
   // 逐条过滤消息。
   return messages.filter((message) => {
     // 防御 1：消息必须是对象。
-    if (!isSessionModelMessage(message)) return false;
+    if (!is_session_message_record(message)) return false;
 
     // 防御 2：只接受 user 角色。
     if (message.role !== "user") return false;
@@ -73,15 +73,15 @@ export function pickMergedUserMessages(
  * - 输出：可直接喂给 streamText 的 messages。
  */
 export async function toModelMessages(
-  messages: SessionMessageV1[],
+  messages: SessionRecordV1[],
   tools: Record<string, Tool>,
   projectRoot?: string,
 ): Promise<ModelMessage[]> {
   // 空输入快速返回，避免调用转换器的额外开销。
   if (!Array.isArray(messages) || messages.length === 0) return [];
 
-  // action message 只服务前端时间线，不能传入模型。
-  const model_messages = messages.filter(isSessionModelMessage);
+  // action record 只服务前端时间线，不能传入模型。
+  const model_messages = messages.filter(is_session_message_record);
   if (model_messages.length === 0) return [];
 
   // 第一步（中文）：在 user 消息上注入 file parts（多模态附件）。

package/src/executor/messages/SessionMessageLog.ts

@@ -9,13 +9,13 @@
 
 import { isTextUIPart } from "ai";
 import type { Logger } from "@/utils/logger/Logger.js";
-import type { SessionModelMessageV1 } from "@/executor/types/SessionMessages.js";
+import type { SessionMessageRecordV1 } from "@/executor/types/SessionRecords.js";
 
 /**
  * 从 UI message 中提取 assistant 文本部分。
  */
 export function extractAssistantTextForLog(
-  message: SessionModelMessageV1,
+  message: SessionMessageRecordV1,
 ): string {
   if (!Array.isArray(message.parts)) return "";
   return message.parts
@@ -30,7 +30,7 @@ export function extractAssistantTextForLog(
  */
 export async function logAssistantMessageNow(
   logger: Logger,
-  message: SessionModelMessageV1,
+  message: SessionMessageRecordV1,
 ): Promise<void> {
   const text = extractAssistantTextForLog(message) || "-";
   const normalized = text.replace(/\r\n/g, "\n");

package/src/executor/messages/SessionStepEventMapper.ts

@@ -7,7 +7,7 @@
  * - 每个 step 前插入 `step-start`，便于在 UI 中保留多 step 边界。
  */
 
-import type { SessionModelMessageV1 } from "@/executor/types/SessionMessages.js";
+import type { SessionMessageRecordV1 } from "@/executor/types/SessionRecords.js";
 
 type UnknownRecord = Record<string, unknown>;
 
@@ -112,8 +112,8 @@ export function buildSessionStepParts(params: {
   stepResult?: unknown;
   text: string;
   visibility?: "visible" | "internal";
-}): SessionModelMessageV1["parts"] {
-  const out: SessionModelMessageV1["parts"] = [];
+}): SessionMessageRecordV1["parts"] {
+  const out: SessionMessageRecordV1["parts"] = [];
   const stepRecord = toRecord(params.stepResult) || {};
   const toolCalls = Array.isArray(stepRecord.toolCalls) ? stepRecord.toolCalls : [];
   const toolResults = Array.isArray(stepRecord.toolResults)
@@ -171,7 +171,7 @@ export function buildSessionStepParts(params: {
               state: "output-available",
               output,
             }),
-      } as SessionModelMessageV1["parts"][number],
+      } as SessionMessageRecordV1["parts"][number],
     );
   }
 
@@ -183,7 +183,7 @@ export function buildSessionStepParts(params: {
       {
         type: toDataPartType(type),
         data: resolveAcpEventData(acpEvent),
-      } as SessionModelMessageV1["parts"][number],
+      } as SessionMessageRecordV1["parts"][number],
     );
   }
 

package/src/executor/messages/UserVisibleText.ts

@@ -8,10 +8,10 @@
  */
 
 import {
-  isSessionModelMessage,
-  type SessionMessageV1,
-  type SessionModelMessageV1,
-} from "@/executor/types/SessionMessages.js";
+  is_session_message_record,
+  type SessionRecordV1,
+  type SessionMessageRecordV1,
+} from "@/executor/types/SessionRecords.js";
 import {
   extractTextFromUiMessage,
   extractToolCallsFromUiMessage,
@@ -25,10 +25,10 @@ import {
  * - 运行中 step/tool 的中断恢复由 inflight 快照承担，不再通过跳过最终 message 收口。
  */
 export function resolveAssistantMessageForPersistence(
-  message: SessionMessageV1 | null | undefined,
-): SessionModelMessageV1 | null {
+  message: SessionRecordV1 | null | undefined,
+): SessionMessageRecordV1 | null {
   if (!message || typeof message !== "object") return null;
-  if (!isSessionModelMessage(message)) return null;
+  if (!is_session_message_record(message)) return null;
   return message;
 }
 
@@ -40,9 +40,9 @@ export function resolveAssistantMessageForPersistence(
  * - 若无 tool call，则回退到 message 文本内容。
  */
 export function pickLastSuccessfulChatSendText(
-  message: SessionMessageV1 | null | undefined,
+  message: SessionRecordV1 | null | undefined,
 ): string {
-  if (!isSessionModelMessage(message)) return "";
+  if (!is_session_message_record(message)) return "";
   const toolCalls = extractToolCallsFromUiMessage(message);
   // 关键点（中文）：优先从 chat_send 的 input.text 还原"用户可见回复"。
   for (let i = toolCalls.length - 1; i >= 0; i -= 1) {

package/src/executor/services/ExecutorInflightService.ts

@@ -9,8 +9,8 @@
 
 import { generateId } from "@/utils/Id.js";
 import type { SessionHistoryStore } from "@/executor/store/history/SessionHistoryStore.js";
-import type { SessionModelMessageV1 } from "@/executor/types/SessionMessages.js";
-import { isSessionModelMessage } from "@/executor/types/SessionMessages.js";
+import type { SessionMessageRecordV1 } from "@/executor/types/SessionRecords.js";
+import { is_session_message_record } from "@/executor/types/SessionRecords.js";
 
 interface ExecutorInflightServiceOptions {
   /**
@@ -52,18 +52,18 @@ export class ExecutorInflightService {
    * 把 step/tool 过程增量写入当前运行中的 assistant 快照。
    */
   async append_assistant_step_parts(
-    parts: SessionModelMessageV1["parts"],
+    parts: SessionMessageRecordV1["parts"],
   ): Promise<void> {
     const normalized_parts = Array.isArray(parts)
       ? parts.filter((part) => part && typeof part === "object")
       : [];
     if (normalized_parts.length === 0) return;
 
-    const current_inflight = await this.history_store.readInflight();
-    const normalized_inflight = isSessionModelMessage(current_inflight)
+    const current_inflight = await this.history_store.read_inflight();
+    const normalized_inflight = is_session_message_record(current_inflight)
       ? current_inflight
       : null;
-    const next_message: SessionModelMessageV1 = normalized_inflight
+    const next_message: SessionMessageRecordV1 = normalized_inflight
       ? {
           ...normalized_inflight,
           metadata: {
@@ -97,7 +97,7 @@ export class ExecutorInflightService {
           parts: normalized_parts,
         };
 
-    await this.history_store.writeInflight(next_message);
+    await this.history_store.write_inflight(next_message);
     if (this.run_after_session_updated_async) {
       await this.run_after_session_updated_async();
     }

package/src/executor/store/history/SessionHistoryStore.ts

@@ -1,20 +1,19 @@
 /**
- * SessionHistoryStore：会话历史事实源接口。
+ * SessionHistoryStore：会话 record 事实源接口。
  *
  * 关键点（中文）
- * - Store 负责消息、meta、archive、lock 等持久化能力。
- * - Composer 只负责把 Store 中的历史组装成本轮模型输入。
+ * - Store 负责 records、meta、archive、lock 等持久化能力。
+ * - Composer 只负责把 Store 中的模型消息 record 组装成本轮模型输入。
  * - 这个接口刻意独立于 Composer，避免把“落盘事实源”误当成“组装策略”。
  */
 
 import type { LanguageModel } from "ai";
 import type {
-  SessionActionMessageV1,
-  SessionMessageV1,
+  SessionActionRecordV1,
+  SessionRecordV1,
   SessionMetadataV1,
-} from "@/executor/types/SessionMessages.js";
+} from "@/executor/types/SessionRecords.js";
 import type { SessionSystemMessage } from "@/executor/types/SessionPrompts.js";
-import type { AgentSessionActionRecord } from "@/types/sdk/AgentSessionAction.js";
 
 /**
  * compact 输入参数。
@@ -53,7 +52,7 @@ export type SessionHistoryCompactInput = {
   /**
    * 可选 action 发布回调。
    */
-  onAction?: (action: AgentSessionActionRecord) => Promise<void>;
+  onAction?: (action: SessionActionRecordV1) => Promise<void>;
 };
 
 /**
@@ -66,39 +65,43 @@ export interface SessionHistoryStore {
   readonly sessionId: string;
 
   /**
-   * 追加一条消息到历史。
+   * 写入一条 session record。
+   *
+   * 说明（中文）
+   * - 模型消息会追加到 JSONL。
+   * - action record 会按稳定 ID upsert 为同一条 record。
    */
-  append(message: SessionMessageV1): Promise<void>;
+  write_record(message: SessionRecordV1): Promise<void>;
 
   /**
    * 读取当前运行中的 assistant 快照。
    */
-  readInflight(): Promise<SessionMessageV1 | null>;
+  read_inflight(): Promise<SessionRecordV1 | null>;
 
   /**
    * 写入当前运行中的 assistant 快照。
    */
-  writeInflight(message: SessionMessageV1): Promise<void>;
+  write_inflight(message: SessionRecordV1): Promise<void>;
 
   /**
    * 用最终 assistant 收口 inflight 快照。
    */
-  finalizeInflight(message?: SessionMessageV1 | null): Promise<void>;
+  finalize_inflight(message?: SessionRecordV1 | null): Promise<void>;
 
   /**
-   * 读取完整消息历史。
+   * 读取完整 session records。
    */
-  list(): Promise<SessionMessageV1[]>;
+  list_records(): Promise<SessionRecordV1[]>;
 
   /**
-   * 读取消息区间 [start, end)。
+   * 读取 session record 区间 [start, end)。
    */
-  slice(start: number, end: number): Promise<SessionMessageV1[]>;
+  slice_records(start: number, end: number): Promise<SessionRecordV1[]>;
 
   /**
-   * 读取消息总条数。
+   * 读取 session record 总条数。
    */
-  size(): Promise<number>;
+  record_count(): Promise<number>;
 
   /**
    * 读取元信息。
@@ -132,7 +135,7 @@ export interface SessionHistoryStore {
      * 可选消息 ID（默认自动生成）。
      */
     id?: string;
-  }): SessionMessageV1;
+  }): SessionRecordV1;
 
   /**
    * 构造 assistant 文本消息。
@@ -163,7 +166,7 @@ export interface SessionHistoryStore {
      * 消息来源（egress/compact）。
      */
     source?: "egress" | "compact";
-  }): SessionMessageV1;
+  }): SessionRecordV1;
 
   /**
    * 构造 action 消息。
@@ -172,7 +175,7 @@ export interface SessionHistoryStore {
     /**
      * 当前 action 结构化记录。
      */
-    action: AgentSessionActionRecord;
+    action: SessionActionRecordV1;
 
     /**
      * 消息元信息（除 schema 字段）。
@@ -184,5 +187,5 @@ export interface SessionHistoryStore {
      * 可选消息 ID（默认自动生成）。
      */
     id?: string;
-  }): SessionActionMessageV1;
+  }): SessionActionRecordV1;
 }