@downcity/agent 1.1.217 → 1.1.224

package/src/session/recorder/JsonlSessionMessageStore.ts

@@ -0,0 +1,246 @@
+/**
+ * SessionMessage 的 JSONL 快照存储。
+ *
+ * messages.jsonl 只保存完整 Message 快照；运行中的唯一 Assistant 使用
+ * assistant_message.json 原子覆盖，避免把每个 delta 写入历史文件。
+ */
+
+import fs from "fs-extra";
+import { open, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { generateId } from "@/utils/Id.js";
+import type { SessionAssistantMessage, SessionMessage } from "@/types/session/SessionMessage.js";
+
+/** JSONL 快照存储构造参数。 */
+export interface JsonlSessionMessageStoreOptions {
+  /** 当前 Session 标识。 */
+  session_id: string;
+  /** messages.jsonl 的绝对或相对路径。 */
+  file_path: string;
+  /** Assistant 运行中快照路径，默认与 messages.jsonl 同目录。 */
+  assistant_message_file_path?: string;
+}
+
+/** 在写锁内计算新 Message 所需的状态。 */
+export interface SessionMessageCommitState {
+  /** 下一条新 Message 的线性顺序。 */
+  message_sequence: number;
+  /** 当前已持久化的完整 Message 快照。 */
+  messages: SessionMessage[];
+}
+
+/** 单一 JSONL 快照存储。 */
+export class JsonlSessionMessageStore {
+  readonly session_id: string;
+  readonly messages_file_path: string;
+  readonly assistant_message_file_path: string;
+  private readonly lock_file_path: string;
+
+  constructor(options: JsonlSessionMessageStoreOptions) {
+    this.session_id = String(options.session_id || "").trim();
+    this.messages_file_path = path.resolve(options.file_path);
+    this.assistant_message_file_path = path.resolve(
+      options.assistant_message_file_path ||
+        path.join(path.dirname(this.messages_file_path), "assistant_message.json"),
+    );
+    this.lock_file_path = `${this.messages_file_path}.lock`;
+    if (!this.session_id) throw new Error("JsonlSessionMessageStore requires session_id");
+  }
+
+  /** 创建目录和文件，并验证已有快照。 */
+  async initialize(): Promise<void> {
+    await this.ensure_layout();
+    const messages = await this.read_messages_unsafe();
+    const draft = await this.read_assistant_message();
+    if (draft && draft.session_id !== this.session_id) {
+      throw new Error("assistant_message.json session_id mismatch");
+    }
+    const finalized = draft && messages.find((message) => message.message_id === draft.message_id);
+    if (draft && finalized && finalized.revision >= draft.revision && finalized.type === "assistant" && finalized.status !== "streaming") {
+      await fs.remove(this.assistant_message_file_path);
+    }
+  }
+
+  /** 读取 JSONL 中每一行完整快照，并按 Message revision 折叠。 */
+  async list_messages(): Promise<SessionMessage[]> {
+    await this.ensure_layout();
+    const by_id = new Map<string, SessionMessage>();
+    const raw = await fs.readFile(this.messages_file_path, "utf8").catch(() => "");
+    for (const [index, line] of raw.split("\n").entries()) {
+      const value = line.trim();
+      if (!value) continue;
+      try {
+        const message = JSON.parse(value) as SessionMessage;
+        this.validate_message(message);
+        const previous = by_id.get(message.message_id);
+        if (!previous || message.revision > previous.revision) by_id.set(message.message_id, message);
+      } catch (error) {
+        throw new Error(`Invalid session message at line ${String(index + 1)}: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+    const draft = await this.read_assistant_message();
+    if (draft) {
+      const previous = by_id.get(draft.message_id);
+      if (!previous || draft.revision > previous.revision) by_id.set(draft.message_id, draft);
+    }
+    return [...by_id.values()].sort((left, right) => left.sequence - right.sequence);
+  }
+
+  /** 读取当前运行中的 Assistant 草稿。 */
+  async read_assistant_message(): Promise<SessionAssistantMessage | null> {
+    try {
+      const value = await fs.readJson(this.assistant_message_file_path) as SessionAssistantMessage;
+      this.validate_message(value);
+      if (value.type !== "assistant" || value.status !== "streaming") return null;
+      return value;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+      if (error instanceof SyntaxError) throw error;
+      throw error;
+    }
+  }
+
+  /** 原子覆盖运行中的 Assistant 草稿。 */
+  async write_assistant_message(message: SessionAssistantMessage): Promise<void> {
+    this.validate_message(message);
+    if (message.status !== "streaming") throw new Error("Assistant draft must be streaming");
+    await this.with_write_lock(async () => {
+      const current = await this.read_assistant_message();
+      if (!current || current.message_id !== message.message_id) {
+        throw new Error(`Assistant draft does not exist: ${message.message_id}`);
+      }
+      if (message.revision !== current.revision + 1) {
+        throw new Error(`Invalid Assistant draft revision: ${message.message_id}`);
+      }
+      await this.write_assistant_message_unsafe(message);
+    });
+  }
+
+  /** 在写锁内分配 Message sequence 并创建唯一 Assistant 草稿。 */
+  async create_assistant_message(
+    build_message: (state: SessionMessageCommitState) => SessionAssistantMessage,
+  ): Promise<SessionAssistantMessage> {
+    return await this.with_write_lock(async () => {
+      const current = await this.read_assistant_message();
+      if (current) throw new Error(`Assistant draft already exists: ${current.message_id}`);
+      const messages = await this.read_messages_unsafe();
+      const message = build_message({
+        message_sequence: messages.reduce((max, item) => Math.max(max, item.sequence + 1), 1),
+        messages,
+      });
+      this.validate_message(message);
+      if (message.status !== "streaming" || message.revision !== 1) {
+        throw new Error("New Assistant draft must be streaming at revision 1");
+      }
+      await this.write_assistant_message_unsafe(message);
+      return message;
+    });
+  }
+
+  /** 创建新 Message 或追加已有 Message revision 快照。 */
+  async append_message(
+    build_message: (state: SessionMessageCommitState) => SessionMessage,
+  ): Promise<SessionMessage> {
+    return await this.with_write_lock(async () => {
+      const messages = await this.read_messages_unsafe();
+      const draft = await this.read_assistant_message();
+      const current_messages = draft ? [...messages, draft] : messages;
+      const message = build_message({
+        message_sequence: current_messages.reduce((max, item) => Math.max(max, item.sequence + 1), 1),
+        messages: current_messages,
+      });
+      this.validate_message(message);
+      await fs.appendFile(this.messages_file_path, `${JSON.stringify(message)}\n`, "utf8");
+      return message;
+    });
+  }
+
+  /** 将 Assistant 草稿最终追加为历史快照，并删除草稿文件。 */
+  async finalize_assistant_message(message: SessionAssistantMessage): Promise<void> {
+    this.validate_message(message);
+    if (message.status === "streaming") throw new Error("Final Assistant message cannot be streaming");
+    await this.with_write_lock(async () => {
+      const current = await this.read_assistant_message();
+      if (!current || current.message_id !== message.message_id) {
+        throw new Error(`Assistant draft does not exist: ${message.message_id}`);
+      }
+      if (message.revision !== current.revision + 1) {
+        throw new Error(`Invalid final Assistant revision: ${message.message_id}`);
+      }
+      await fs.appendFile(this.messages_file_path, `${JSON.stringify(message)}\n`, "utf8");
+      await fs.remove(this.assistant_message_file_path);
+    });
+  }
+
+  private async read_messages_unsafe(): Promise<SessionMessage[]> {
+    const raw = await fs.readFile(this.messages_file_path, "utf8").catch(() => "");
+    const by_id = new Map<string, SessionMessage>();
+    for (const line of raw.split("\n")) {
+      if (!line.trim()) continue;
+      const message = JSON.parse(line) as SessionMessage;
+      this.validate_message(message);
+      const previous = by_id.get(message.message_id);
+      if (!previous || message.revision > previous.revision) by_id.set(message.message_id, message);
+    }
+    return [...by_id.values()].sort((left, right) => left.sequence - right.sequence);
+  }
+
+  private async write_assistant_message_unsafe(message: SessionAssistantMessage): Promise<void> {
+    const temporary_path = `${this.assistant_message_file_path}.${process.pid}.${Date.now()}.tmp`;
+    await fs.ensureDir(path.dirname(this.assistant_message_file_path));
+    await fs.writeJson(temporary_path, message, { spaces: 2 });
+    await fs.move(temporary_path, this.assistant_message_file_path, { overwrite: true });
+  }
+
+  private validate_message(message: SessionMessage): void {
+    if (!message || typeof message !== "object") throw new Error("message must be an object");
+    if (message.session_id !== this.session_id) throw new Error("session_id mismatch");
+    if (!message.message_id || !Number.isInteger(message.sequence) || !Number.isInteger(message.revision)) {
+      throw new Error("message identity, sequence and revision are required");
+    }
+    if (message.type === "assistant") {
+      const sequences = new Set<number>();
+      for (const part of message.parts) {
+        if (!Number.isInteger(part.sequence) || sequences.has(part.sequence)) {
+          throw new Error(`invalid Assistant part sequence: ${part.part_id}`);
+        }
+        sequences.add(part.sequence);
+      }
+    }
+  }
+
+  private async ensure_layout(): Promise<void> {
+    await fs.ensureDir(path.dirname(this.messages_file_path));
+    await fs.ensureFile(this.messages_file_path);
+  }
+
+  private async with_write_lock<T>(callback: () => Promise<T>): Promise<T> {
+    await this.ensure_layout();
+    const token = `${process.pid}:${Date.now()}:${generateId()}`;
+    const stale_ms = 30_000;
+    const started_at = Date.now();
+    while (true) {
+      try {
+        const file = await open(this.lock_file_path, "wx");
+        await file.writeFile(token, "utf8");
+        await file.close();
+        break;
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+        try {
+          const lock_stat = await stat(this.lock_file_path);
+          if (Date.now() - lock_stat.mtimeMs > stale_ms) await fs.remove(this.lock_file_path);
+        } catch { /* 锁文件可能刚被释放。 */ }
+        if (Date.now() - started_at > stale_ms * 2) throw new Error(`Session message lock timeout: ${this.lock_file_path}`);
+        await new Promise((resolve) => setTimeout(resolve, 40));
+      }
+    }
+    try {
+      return await callback();
+    } finally {
+      try {
+        if ((await readFile(this.lock_file_path, "utf8")).trim() === token) await fs.remove(this.lock_file_path);
+      } catch { /* 锁已被清理。 */ }
+    }
+  }
+}

package/src/session/recorder/SessionMessageCodec.ts

@@ -0,0 +1,284 @@
+/**
+ * SessionMessage 与 AI SDK UIMessage 的内部投影转换。
+ *
+ * 关键点（中文）
+ * - SessionMessage 是唯一持久化事实；UIMessage 只在 Executor/Composer 边界临时构造。
+ * - action/error 不转换为模型消息。
+ * - part_id 只服务 Session Message identity，不传入模型协议。
+ */
+
+import type { UIMessage } from "ai";
+import type {
+  SessionAssistantMessage,
+  SessionAssistantMessagePart,
+  SessionMessage,
+  SessionUserMessage,
+  SessionUserMessagePart,
+} from "@/types/session/SessionMessage.js";
+import type {
+  SessionMessageRecordV1,
+  SessionMetadataV1,
+} from "@/executor/types/SessionRecords.js";
+
+/** 把 Session Message 投影成 Executor 可消费的 UIMessage。 */
+export function to_executor_ui_message(
+  message: SessionMessage,
+): SessionMessageRecordV1 | null {
+  if (message.type !== "user" && message.type !== "assistant") return null;
+  const metadata: SessionMetadataV1 = {
+    v: 1,
+    ts: message.updated_at,
+    sessionId: message.session_id,
+    turnId: message.turn_id,
+    source:
+      message.type === "user"
+        ? "ingress"
+        : message.kind === "summary"
+          ? "compact"
+          : "egress",
+    kind:
+      message.type === "assistant" && message.kind === "summary"
+        ? "summary"
+        : "normal",
+    extra: {
+      sequence: message.sequence,
+      revision: message.revision,
+      visibility: message.visibility,
+      ...(message.type === "user"
+        ? { inputType: message.input_type }
+        : { segmentIndex: message.segment_index, status: message.status }),
+    },
+  };
+  return {
+    id: message.message_id,
+    role: message.type,
+    metadata,
+    parts:
+      message.type === "user"
+        ? to_ui_user_parts(message.parts)
+        : to_ui_assistant_parts(message.parts),
+  } as SessionMessageRecordV1;
+}
+
+/** 把 AI SDK user parts 转换成可持久化 Session parts。 */
+export function from_ui_user_parts(
+  parts: UIMessage["parts"] | null | undefined,
+): SessionUserMessagePart[] {
+  if (!Array.isArray(parts)) return [];
+  return parts.flatMap<SessionUserMessagePart>((part, index) => {
+    if (!part || typeof part !== "object") return [];
+    const candidate = part as Record<string, unknown>;
+    if (candidate.type === "text") {
+      return [{
+        part_id: `user-text:${index + 1}`,
+        type: "text" as const,
+        text: String(candidate.text || ""),
+        state: "done" as const,
+      }];
+    }
+    if (candidate.type === "file") {
+      return [{
+        part_id: `user-file:${index + 1}`,
+        type: "file" as const,
+        url: String(candidate.url || ""),
+        media_type: String(candidate.mediaType || "application/octet-stream"),
+        ...(candidate.filename ? { filename: String(candidate.filename) } : {}),
+      }];
+    }
+    if (String(candidate.type || "").startsWith("data-")) {
+      return [{
+        part_id: `user-data:${index + 1}`,
+        type: "data" as const,
+        data_type: String(candidate.type),
+        data: to_json_value(candidate.data),
+      }];
+    }
+    return [];
+  });
+}
+
+/** 把最终 AI SDK assistant parts 转换成 Session parts。 */
+export function from_ui_assistant_parts(
+  parts: UIMessage["parts"] | null | undefined,
+): SessionAssistantMessagePart[] {
+  if (!Array.isArray(parts)) return [];
+  return parts.flatMap<SessionAssistantMessagePart>((part, index) => {
+    if (!part || typeof part !== "object") return [];
+    const candidate = part as Record<string, unknown>;
+    const type = String(candidate.type || "");
+    if (type === "text" || type === "reasoning") {
+      return [{
+        part_id: `${type}:${index + 1}`,
+        sequence: index + 1,
+        type: type as "text" | "reasoning",
+        text: String(candidate.text || ""),
+        state: "done" as const,
+      }];
+    }
+    if (type === "file") {
+      return [{
+        part_id: `file:${index + 1}`,
+        sequence: index + 1,
+        type: "file" as const,
+        url: String(candidate.url || ""),
+        media_type: String(candidate.mediaType || "application/octet-stream"),
+        ...(candidate.filename ? { filename: String(candidate.filename) } : {}),
+      }];
+    }
+    if (type === "dynamic-tool" || type.startsWith("tool-")) {
+      const state = String(candidate.state || "");
+      return [{
+        part_id: String(candidate.toolCallId || `tool:${index + 1}`),
+        sequence: index + 1,
+        type: "tool" as const,
+        tool_call_id: String(candidate.toolCallId || `tool:${index + 1}`),
+        tool_name:
+          String(candidate.toolName || "").trim() ||
+          type.replace(/^tool-/, "") ||
+          "unknown",
+        state:
+          state === "output-available"
+            ? "completed" as const
+            : state === "output-error" || state === "output-denied"
+              ? "failed" as const
+              : state === "approval-requested"
+                ? "approval-required" as const
+                : state === "input-streaming"
+                  ? "input-streaming" as const
+                  : state === "input-available"
+                    ? "ready" as const
+                    : "running" as const,
+        ...(candidate.input !== undefined
+          ? { input: to_json_value(candidate.input) }
+          : {}),
+        ...(candidate.output !== undefined
+          ? { output: to_json_value(candidate.output) }
+          : {}),
+        ...(candidate.errorText ? { error: String(candidate.errorText) } : {}),
+      }];
+    }
+    return [];
+  });
+}
+
+/** 提取 Assistant Message 的最终可见文本。 */
+export function extract_session_assistant_text(
+  message: SessionAssistantMessage | null | undefined,
+): string {
+  if (!message) return "";
+  return message.parts
+    .flatMap((part) => part.type === "text" ? [part.text] : [])
+    .join("")
+    .trim();
+}
+
+function to_ui_user_parts(parts: SessionUserMessagePart[]): UIMessage["parts"] {
+  return parts.map((part) => {
+    if (part.type === "text") {
+      return { type: "text", text: part.text, state: part.state };
+    }
+    if (part.type === "file") {
+      return {
+        type: "file",
+        url: part.url,
+        mediaType: part.media_type,
+        ...(part.filename ? { filename: part.filename } : {}),
+      };
+    }
+    return {
+      type: part.data_type,
+      data: part.data,
+    } as UIMessage["parts"][number];
+  });
+}
+
+function to_ui_assistant_parts(
+  parts: SessionAssistantMessagePart[],
+): UIMessage["parts"] {
+  return parts.map((part) => {
+    if (part.type === "text" || part.type === "reasoning") {
+      return { type: part.type, text: part.text, state: part.state };
+    }
+    if (part.type === "file") {
+      return {
+        type: "file",
+        url: part.url,
+        mediaType: part.media_type,
+        ...(part.filename ? { filename: part.filename } : {}),
+      };
+    }
+    if (part.type === "data") {
+      return {
+        type: part.data_type,
+        data: part.data,
+      } as UIMessage["parts"][number];
+    }
+    if (!("tool_call_id" in part)) {
+      throw new Error(`Unsupported Assistant part: ${part.type}`);
+    }
+    const input = part.input ?? parse_json(part.input_text);
+    if (part.state === "completed") {
+      return {
+        type: "dynamic-tool",
+        toolName: part.tool_name,
+        toolCallId: part.tool_call_id,
+        state: "output-available",
+        input,
+        output: part.output,
+      };
+    }
+    if (part.state === "failed") {
+      return {
+        type: "dynamic-tool",
+        toolName: part.tool_name,
+        toolCallId: part.tool_call_id,
+        state: "output-error",
+        input,
+        errorText: part.error || "Tool failed",
+      };
+    }
+    if (part.state === "approval-required") {
+      return {
+        type: "dynamic-tool",
+        toolName: part.tool_name,
+        toolCallId: part.tool_call_id,
+        state: "approval-requested",
+        input,
+        approval: { id: part.approval_id || `approval:${part.tool_call_id}` },
+      };
+    }
+    return {
+      type: "dynamic-tool",
+      toolName: part.tool_name,
+      toolCallId: part.tool_call_id,
+      state: part.state === "input-streaming" ? "input-streaming" : "input-available",
+      input,
+    };
+  }) as UIMessage["parts"];
+}
+
+function parse_json(input: string | undefined): unknown {
+  const value = String(input || "").trim();
+  if (!value) return {};
+  try {
+    return JSON.parse(value);
+  } catch {
+    return value;
+  }
+}
+
+function to_json_value(input: unknown) {
+  if (input === undefined || input === null) return null;
+  if (
+    typeof input === "string" ||
+    typeof input === "number" ||
+    typeof input === "boolean"
+  ) {
+    return input;
+  }
+  try {
+    return JSON.parse(JSON.stringify(input));
+  } catch {
+    return String(input);
+  }
+}