@ai-setting/roy-agent-core 1.0.0

package/src/env/session/session-message-converter.ts

@@ -0,0 +1,415 @@
+/**
+ * @fileoverview Session Message Converter
+ * 
+ * Converts between SessionMessage (storage format) and AI SDK ModelMessage (LLM format).
+ * 
+ * This module provides a class-based API for message conversion.
+ */
+
+import { randomUUID } from "crypto";
+import type { SessionMessage, TextPart, ToolCallPart, ToolResultPart, ReasoningPart, FilePart, SessionPart, MessagePart } from "./types";
+import { TracedAs } from "../log-trace/decorator";
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+/**
+ * Default budget tokens for extended reasoning (Anthropic-style)
+ */
+const DEFAULT_REASONING_BUDGET_TOKENS = 10000;
+
+// AI SDK ModelMessage type (simplified for this module)
+interface ModelMessage {
+  role: "user" | "assistant" | "system" | "tool";
+  content: string | ModelContentPart[];
+}
+
+/**
+ * Content part for AI SDK ModelMessage
+ */
+type ModelContentPart = 
+  | TextContentPart 
+  | ReasoningContentPart 
+  | ToolCallContentPart 
+  | ToolResultContentPart 
+  | FileContentPart;
+
+interface TextContentPart {
+  type: "text";
+  text: string;
+  synthetic?: boolean;
+}
+
+interface ReasoningContentPart {
+  type: "reasoning";
+  text: string;
+  reasoningType?: "core" | "effort" | "summary";
+}
+
+interface ToolCallContentPart {
+  type: "tool-call";
+  toolCallId: string;
+  toolName: string;
+  input: Record<string, unknown>;
+}
+
+interface ToolResultContentPart {
+  type: "tool-result";
+  toolCallId: string;
+  toolName: string;
+  output: string;
+}
+
+interface FileContentPart {
+  type: "file";
+  url: string;
+  mimeType?: string;
+  filename?: string;
+}
+
+/**
+ * SessionMessageConverter
+ * 
+ * Converts between SessionMessage (storage format) and AI SDK ModelMessage (LLM format).
+ * 
+ * @example
+ * ```typescript
+ * const converter = new SessionMessageConverter();
+ * const modelMsg = converter.toModelMessage(sessionMsg);
+ * const sessionMsg = converter.fromModelMessage(modelMsg);
+ * ```
+ */
+export class SessionMessageConverter {
+  /**
+   * Convert a SessionMessage to AI SDK ModelMessage format
+   * 
+   * @param msg - SessionMessage to convert
+   * @returns ModelMessage compatible with AI SDK v6
+   */
+  @TracedAs("session-message-converter.toModelMessage", { recordParams: true, recordResult: true, log: true })
+  toModelMessage(msg: SessionMessage): ModelMessage {
+    // ============ Assistant Message ============
+    if (msg.role === "assistant") {
+      const content: ModelContentPart[] = [];
+      
+      // Process all parts in order to preserve their original order
+      for (const part of msg.parts || []) {
+        if (part.type === "text") {
+          const textPart = part as TextPart;
+          content.push({ 
+            type: "text", 
+            text: textPart.content,
+            ...(textPart.synthetic !== undefined && { synthetic: textPart.synthetic }),
+          });
+        } else if (part.type === "reasoning") {
+          const reasoningPart = part as ReasoningPart;
+          content.push({ 
+            type: "reasoning", 
+            text: reasoningPart.content,
+            reasoningType: reasoningPart.reasoningType,
+          });
+        } else if (part.type === "tool-call") {
+          const toolPart = part as unknown as ToolCallPart;
+          let parsedArgs: Record<string, unknown> = {};
+          
+          // Safely parse JSON arguments with error handling
+          if (typeof toolPart.arguments === "string") {
+            try {
+              parsedArgs = JSON.parse(toolPart.arguments);
+            } catch {
+              // If JSON parse fails, try to use the string as-is
+              // This handles cases where arguments are not valid JSON
+              parsedArgs = { _raw: toolPart.arguments };
+            }
+          } else {
+            parsedArgs = toolPart.arguments;
+          }
+          
+          content.push({
+            type: "tool-call",
+            toolCallId: toolPart.toolCallId,
+            toolName: toolPart.toolName,
+            input: parsedArgs,
+          });
+        } else if (part.type === "file") {
+          // File parts in assistant messages are converted to AI SDK file content
+          const filePart = part as unknown as FilePart;
+          content.push({
+            type: "file",
+            url: filePart.url,
+            mimeType: filePart.mime,
+            filename: filePart.filename,
+          });
+        }
+        // Note: tool-result and checkpoint parts are skipped for assistant messages
+        // - tool-result belongs to tool messages (handled below)
+        // - checkpoint is a storage/compression marker, not needed for LLM calls
+        else if (part.type === "tool-result" || part.type === "checkpoint") {
+          // These types are intentionally skipped for assistant messages
+          // Tool results belong to tool role messages, checkpoints are metadata
+        }
+        else {
+          // Log any other unknown part types for debugging
+          console.debug(`[session-message-converter] Skipping unsupported part type in assistant: ${(part as any).type}`);
+        }
+      }
+      
+      // If no parts, fall back to content field
+      if (content.length === 0 && msg.content) {
+        return { role: "assistant", content: msg.content };
+      }
+      
+      return { role: "assistant", content };
+    }
+    
+    // ============ Tool Message ============
+    if (msg.role === "tool") {
+      const toolPart = msg.parts?.find(p => p.type === "tool-result") as ToolResultPart | undefined;
+      return {
+        role: "tool",
+        content: [{
+          type: "tool-result",
+          toolCallId: toolPart?.toolCallId || "",
+          toolName: toolPart?.toolName || "",
+          output: toolPart?.output || msg.content || "",
+        }],
+      };
+    }
+    
+    // ============ User / System Message ============
+    return {
+      role: msg.role as "system" | "user" | "assistant" | "tool",
+      content: msg.content || "",
+    };
+  }
+
+  /**
+   * Convert an AI SDK ModelMessage to SessionMessage format
+   * 
+   * @param aiMsg - AI SDK ModelMessage to convert (accepts any object with role and content)
+   * @param options - Optional sessionID and messageID
+   * @returns SessionMessage compatible with storage format
+   * 
+   * 设置 metadata.type 以便后续正确过滤：
+   * - "tool_call": assistant 消息包含 tool-call parts
+   * - "tool_result": tool 消息
+   */
+  @TracedAs("session-message-converter.fromModelMessage", { recordParams: true, recordResult: true, log: true })
+  fromModelMessage(
+    aiMsg: { role: string; content: unknown; [key: string]: unknown },
+    options?: { sessionID?: string; messageID?: string }
+  ): SessionMessage {
+    const parts: SessionPart[] = [];
+    // Handle content that could be string, array, or other types
+    const content = typeof aiMsg.content === 'string' || Array.isArray(aiMsg.content) 
+      ? aiMsg.content 
+      : "";
+    let hasToolCallPart = false;
+    let hasToolResultPart = false;
+    
+    if (typeof content === "string") {
+      parts.push({ type: "text", content });
+    } else if (Array.isArray(content)) {
+      for (const part of content) {
+        const p = part as unknown as Record<string, unknown>;
+        
+        if (p.type === "text") {
+          parts.push({ type: "text", content: (p.text as string) || "" });
+        } 
+        else if (p.type === "reasoning") {
+          parts.push({
+            type: "reasoning",
+            content: (p.text as string) || "",
+            reasoningType: p.reasoningType as "core" | "effort" | "summary" | undefined,
+            state: "completed",
+          } as SessionPart);
+        }
+        else if (p.type === "tool-call") {
+          hasToolCallPart = true;
+          parts.push({
+            type: "tool-call",
+            toolCallId: p.toolCallId as string,
+            toolName: p.toolName as string,
+            arguments: p.input as Record<string, unknown>,
+            state: "pending",
+          } as SessionPart);
+        }
+        else if (p.type === "tool-result") {
+          hasToolResultPart = true;
+          parts.push({
+            type: "tool-result",
+            toolCallId: p.toolCallId as string,
+            toolName: p.toolName as string,
+            output: typeof p.output === "string" ? p.output : JSON.stringify(p.output),
+            state: "completed",
+          } as SessionPart);
+        }
+        else if (p.type === "file") {
+          parts.push({
+            type: "file",
+            mime: (p.mimeType as string) || "application/octet-stream",
+            url: p.url as string,
+            filename: p.filename as string | undefined,
+          } as SessionPart);
+        }
+        else {
+          // Log unknown part type for debugging (Minor issue #4)
+          // Unknown types are skipped to maintain forward compatibility
+          console.debug(`[session-message-converter] Unknown part type: ${p.type}`);
+        }
+      }
+    }
+    
+    // Determine metadata type based on role and content parts
+    let metadataType: "tool_call" | "tool_result" | undefined;
+    if (aiMsg.role === "assistant" && hasToolCallPart) {
+      metadataType = "tool_call";
+    } else if (aiMsg.role === "tool") {
+      metadataType = "tool_result";
+    }
+    
+    // Build the result object
+    const result: SessionMessage = {
+      id: options?.messageID || `msg_${randomUUID()}`,
+      sessionID: options?.sessionID || "",
+      role: aiMsg.role as SessionMessage["role"],
+      timestamp: Date.now(),
+      parts,
+      content: typeof content === "string" ? content : "",
+    };
+    
+    // Add metadata with type if applicable
+    if (metadataType) {
+      result.metadata = { type: metadataType };
+    }
+    
+    return result;
+  }
+
+  /**
+   * Convert a list of SessionMessages to AI SDK history format
+   * 
+   * @param messages - Array of SessionMessages to convert
+   * @returns Array of ModelMessages filtered by archived status
+   */
+  sessionToHistory(messages: SessionMessage[]): ModelMessage[] {
+    return messages
+      .filter(msg => !msg.metadata?.isArchived && !msg.isArchived)
+      .map(msg => this.toModelMessage(msg));
+  }
+
+  /**
+   * Extract provider-specific options from SessionMessage
+   * 
+   * Some models (e.g., DeepSeek R1, Kimi k2.5) require reasoning configuration
+   * through providerOptions.
+   * 
+   * @param msg - SessionMessage to extract options from
+   * @returns Provider-specific options object for LLM calls
+   */
+  extractProviderOptions(msg: SessionMessage): Record<string, unknown> {
+    const options: Record<string, unknown> = {};
+    
+    // Check for reasoning parts that might need provider options
+    const reasoningParts = msg.parts?.filter(p => p.type === "reasoning") as ReasoningPart[] | undefined;
+    
+    if (reasoningParts && reasoningParts.length > 0) {
+      // Extract reasoning type from the first reasoning part
+      const firstReasoning = reasoningParts[0];
+      if (firstReasoning.reasoningType) {
+        // OpenAI-compatible thinking options
+        options.openai = {
+          thinking: {
+            type: firstReasoning.reasoningType === "effort" ? "extended" : "core",
+          },
+        };
+        
+        // Anthropic-style budget tokens (if effort type)
+        if (firstReasoning.reasoningType === "effort") {
+          // Get budget tokens from metadata or use default
+          const budgetTokens = (firstReasoning.metadata?.tokenCount as number) || DEFAULT_REASONING_BUDGET_TOKENS;
+          
+          options.anthropic = {
+            thinking: {
+              type: "enabled",
+              budgetTokens,
+            },
+          };
+        }
+      }
+    }
+    
+    return options;
+  }
+
+  /**
+   * Migrate old format message to new format
+   * 
+   * Handles backward compatibility by converting old messages with just content
+   * to new format with proper parts array.
+   * 
+   * @param oldMsg - Message in possibly old format
+   * @returns Message in new format with parts array
+   */
+  migrateMessage(oldMsg: Partial<SessionMessage>): SessionMessage {
+    // If already has parts with new format (parts have proper type field), return as is
+    if (oldMsg.parts && oldMsg.parts.length > 0) {
+      const firstPart = oldMsg.parts[0] as unknown as Record<string, unknown>;
+      // Check if it's new format by looking for type field
+      if (firstPart && typeof firstPart.type === "string" && firstPart.type.length > 0) {
+        return {
+          ...oldMsg,
+          content: oldMsg.content || "",
+        } as SessionMessage;
+      }
+    }
+    
+    // Old format: content is plain text, need to wrap as text part
+    return {
+      ...oldMsg,
+      content: oldMsg.content || "",
+      parts: oldMsg.content ? [{ type: "text", content: oldMsg.content }] : [],
+    } as SessionMessage;
+  }
+}
+
+// ============================================================================
+// Backward Compatibility - Deprecated exports
+// ============================================================================
+// 
+// These functions are kept for backward compatibility but will be removed in a future version.
+// Please use SessionMessageConverter class instead.
+//
+// @deprecated Use SessionMessageConverter.toModelMessage() instead
+export function toModelMessage(msg: SessionMessage): ModelMessage {
+  const converter = new SessionMessageConverter();
+  return converter.toModelMessage(msg);
+}
+
+// @deprecated Use SessionMessageConverter.fromModelMessage() instead
+export function fromModelMessage(
+  aiMsg: { role: string; content: unknown; [key: string]: unknown },
+  options?: { sessionID?: string; messageID?: string }
+): SessionMessage {
+  const converter = new SessionMessageConverter();
+  return converter.fromModelMessage(aiMsg, options);
+}
+
+// @deprecated Use SessionMessageConverter.sessionToHistory() instead
+export function sessionToHistory(messages: SessionMessage[]): ModelMessage[] {
+  const converter = new SessionMessageConverter();
+  return converter.sessionToHistory(messages);
+}
+
+// @deprecated Use SessionMessageConverter.extractProviderOptions() instead
+export function extractProviderOptions(msg: SessionMessage): Record<string, unknown> {
+  const converter = new SessionMessageConverter();
+  return converter.extractProviderOptions(msg);
+}
+
+// @deprecated Use SessionMessageConverter.migrateMessage() instead
+export function migrateMessage(oldMsg: Partial<SessionMessage>): SessionMessage {
+  const converter = new SessionMessageConverter();
+  return converter.migrateMessage(oldMsg);
+}