@downcity/agent 1.1.216 → 1.1.222

package/src/session/recorder/SessionMessageCodec.ts

@@ -0,0 +1,279 @@
+/**
+ * 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}`,
+        type: type as "text" | "reasoning",
+        text: String(candidate.text || ""),
+        state: "done" as const,
+      }];
+    }
+    if (type === "file") {
+      return [{
+        part_id: `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 (type === "dynamic-tool" || type.startsWith("tool-")) {
+      const state = String(candidate.state || "");
+      return [{
+        part_id: String(candidate.toolCallId || `tool:${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
+                  : "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);
+  }
+}

package/src/session/recorder/SessionMessageReducer.ts

@@ -0,0 +1,155 @@
+/**
+ * Session Message Mutation reducer。
+ *
+ * 历史重放与实时消费者共享 message、part、delta 三种归并语义。
+ */
+
+import type { SessionAssistantMessage, SessionMessage } from "@/types/session/SessionMessage.js";
+import type { SessionMessageMutation } from "@/types/session/SessionMessageMutation.js";
+
+/** 将单条 Mutation 应用到已有 Message。 */
+export function reduce_session_message(
+  current_message: SessionMessage | undefined,
+  mutation: SessionMessageMutation,
+): SessionMessage {
+  if (mutation.variant === "message") {
+    validate_message_snapshot(current_message, mutation);
+    return structuredClone(mutation.message);
+  }
+  if (!current_message) {
+    throw new Error(`Session Message does not exist: ${mutation.message_id}`);
+  }
+  validate_next_revision(current_message, mutation);
+  const assistant = require_streaming_assistant(current_message);
+
+  if (mutation.variant === "part") {
+    if (mutation.part.part_id !== mutation.part_id) {
+      throw new Error(`Part Mutation identity mismatch: ${mutation.part_id}`);
+    }
+    if (mutation.part.type !== mutation.type) {
+      throw new Error(`Part Mutation type mismatch: ${mutation.part_id}`);
+    }
+    const exists = assistant.parts.some(
+      (part) => part.part_id === mutation.part_id,
+    );
+    const parts = exists
+      ? assistant.parts.map((part) =>
+          part.part_id === mutation.part_id
+            ? structuredClone(mutation.part)
+            : part,
+        )
+      : [...assistant.parts, structuredClone(mutation.part)];
+    return with_revision(assistant, mutation, { parts });
+  }
+
+  const existing_part = assistant.parts.find(
+    (part) => part.part_id === mutation.part_id,
+  );
+  if (
+    !existing_part ||
+    (existing_part.type !== "text" && existing_part.type !== "reasoning")
+  ) {
+    throw new Error(`Delta target Part does not exist: ${mutation.part_id}`);
+  }
+  if (existing_part.type !== mutation.type) {
+    throw new Error(`Delta type changed for Part: ${mutation.part_id}`);
+  }
+  const parts = assistant.parts.map((part) =>
+    part.part_id === mutation.part_id &&
+    (part.type === "text" || part.type === "reasoning")
+      ? { ...part, text: part.text + mutation.delta }
+      : part,
+  );
+  return with_revision(assistant, mutation, { parts });
+}
+
+/** 按 commit_sequence 重放 Mutation，恢复线性 Message snapshot。 */
+export function reduce_session_messages(
+  mutations: SessionMessageMutation[],
+): SessionMessage[] {
+  const messages = new Map<string, SessionMessage>();
+  const ordered = [...mutations].sort(
+    (left, right) => left.commit_sequence - right.commit_sequence,
+  );
+  let previous_commit_sequence = 0;
+  for (const mutation of ordered) {
+    if (mutation.commit_sequence <= previous_commit_sequence) {
+      throw new Error(`Duplicate commit_sequence: ${String(mutation.commit_sequence)}`);
+    }
+    messages.set(
+      mutation.message_id,
+      reduce_session_message(messages.get(mutation.message_id), mutation),
+    );
+    previous_commit_sequence = mutation.commit_sequence;
+  }
+  return [...messages.values()].sort(
+    (left, right) => left.sequence - right.sequence,
+  );
+}
+
+function validate_message_snapshot(
+  current_message: SessionMessage | undefined,
+  mutation: Extract<SessionMessageMutation, { variant: "message" }>,
+): void {
+  if (mutation.message.message_id !== mutation.message_id) {
+    throw new Error(`Message Mutation identity mismatch: ${mutation.message_id}`);
+  }
+  if (mutation.message.type !== mutation.type) {
+    throw new Error(`Message Mutation type mismatch: ${mutation.message_id}`);
+  }
+  if (mutation.message.sequence !== mutation.sequence) {
+    throw new Error(`Message Mutation sequence mismatch: ${mutation.message_id}`);
+  }
+  if (mutation.message.revision !== mutation.revision) {
+    throw new Error(`Message Mutation revision mismatch: ${mutation.message_id}`);
+  }
+  if (!current_message) {
+    if (mutation.revision !== 1) {
+      throw new Error(`New Message revision must be 1: ${mutation.message_id}`);
+    }
+    return;
+  }
+  validate_next_revision(current_message, mutation);
+  if (current_message.type !== mutation.type) {
+    throw new Error(`Message type changed: ${mutation.message_id}`);
+  }
+  if (current_message.sequence !== mutation.sequence) {
+    throw new Error(`Message sequence changed: ${mutation.message_id}`);
+  }
+}
+
+function validate_next_revision(
+  current_message: SessionMessage,
+  mutation: SessionMessageMutation,
+): void {
+  if (mutation.revision !== current_message.revision + 1) {
+    throw new Error(
+      `Invalid Message revision for ${mutation.message_id}: expected ${String(current_message.revision + 1)}, received ${String(mutation.revision)}`,
+    );
+  }
+}
+
+function require_streaming_assistant(
+  message: SessionMessage,
+): SessionAssistantMessage {
+  if (message.type !== "assistant") {
+    throw new Error(`Session Message is not assistant: ${message.message_id}`);
+  }
+  if (message.status !== "streaming") {
+    throw new Error(`Assistant Message is already closed: ${message.message_id}`);
+  }
+  return message;
+}
+
+function with_revision<TMessage extends SessionMessage>(
+  message: TMessage,
+  mutation: SessionMessageMutation,
+  changes: object,
+): TMessage {
+  return {
+    ...message,
+    ...changes,
+    revision: mutation.revision,
+    updated_at: mutation.created_at,
+  } as TMessage;
+}