rosetta-ai 1.4.0 → 1.6.0

package/README.md

@@ -15,6 +15,7 @@ Rosetta converts messages between different LLM providers using [**GenAI**](http
 - 📝 Full TypeScript support with strict types
 - ✅ Runtime validation with Zod schemas
 - 💾 Preserve provider-specific metadata for lossless round-trips
+- 📌 System message order preservation - system messages retain their original position in conversation when translating between providers
 - 🌐 Works in Node.js and browsers
 - 🌳 Tree-shakeable ESM build
 
@@ -292,6 +293,8 @@ if (result.error) {
 - **fromGenAI** = Can translate *to* this provider from GenAI (target)
 - **Separated System** = Provider separates system instructions from messages (use the `system` option if needed)
 
+**System message order preservation**: When translating to a provider that separates system instructions (like GenAI), system messages are extracted from the conversation and returned in the `system` field. Rosetta preserves the original position of each system message so that when translating back to a provider with inline system messages (like Promptl or Vercel AI), the system messages are re-inserted at their original positions in the conversation.
+
 ### Universal Compatibility
 
 The **Compat** provider is a universal fallback that handles messages from *any* LLM provider—even ones not explicitly supported. When you call `translate()` without specifying a source provider, Rosetta tries to match against known provider schemas. If none match, it automatically falls back to Compat, which:
@@ -368,6 +371,10 @@ const message: GenAIMessage = {
         toolName: "get_weather",  // Tool name (GenAI schema doesn't include it)
         isError: true,            // Error indicator
       },
+      // Parts metadata - collapsed part-level metadata (for providers with string-only content)
+      _partsMetadata: {
+        _promptlSourceMap: [...], // Part metadata moved to message level
+      },
       // Extra fields - any other provider-specific data
       annotations: [...],
     },
@@ -375,6 +382,8 @@ const message: GenAIMessage = {
 };
 ```
 
+**Note on `_partsMetadata`**: Some providers require string content for certain message types (e.g., VercelAI system messages). When translating to these providers, part-level metadata is collected and stored in `_partsMetadata` at the message level. When translating back to a provider that supports structured content, this metadata is automatically restored to the first content part. **Important**: In passthrough mode, if the target provider doesn't support structured content (like VercelAI system messages), part-level metadata stored in `_partsMetadata` will be lost. Use **preserve** mode if you need to retain this metadata through round-trips.
+
 #### Provider Metadata Mode
 
 The `providerMetadata` option controls how metadata (extra fields) is handled in the output.

package/dist/index.cjs

@@ -221,10 +221,15 @@ function extractExtraFields(obj, knownKeys) {
  * Reads metadata from an entity, checking both casings (snake_case and camelCase).
  * This is necessary because messages may have been previously translated by Rosetta
  * with different target providers (GenAI uses snake_case, VercelAI uses camelCase).
+ * Returns undefined if metadata is not present or is an empty object.
  */
 function readMetadata(entity) {
     // biome-ignore lint/complexity/useLiteralKeys: required for index signature access
-    return (entity["_provider_metadata"] ?? entity["_providerMetadata"]);
+    const metadata = (entity["_provider_metadata"] ?? entity["_providerMetadata"]);
+    // Return undefined for empty objects to prevent empty metadata from propagating
+    if (!metadata || Object.keys(metadata).length === 0)
+        return undefined;
+    return metadata;
 }
 /**
  * Extracts known fields from metadata, checking both casings.
@@ -240,8 +245,23 @@ function getKnownFields(metadata) {
         isError: known?.isError,
         isRefusal: known?.isRefusal,
         originalType: known?.originalType,
+        messageIndex: known?.messageIndex,
     };
 }
+/**
+ * Extracts parts metadata from message metadata, checking both casings.
+ * Parts metadata is used to preserve part-level metadata when converting to providers
+ * that require string content (e.g., VercelAI system messages).
+ *
+ * @param metadata - The message metadata to extract from
+ * @returns The parts metadata object, or undefined if not present
+ */
+function getPartsMetadata(metadata) {
+    if (!metadata)
+        return undefined;
+    // biome-ignore lint/complexity/useLiteralKeys: required for index signature access
+    return (metadata["_parts_metadata"] ?? metadata["_partsMetadata"]);
+}
 /**
  * Stores metadata on a GenAI entity, merging with any existing metadata.
  * This is used in toGenAI to build the _provider_metadata field.
@@ -284,7 +304,8 @@ function storeMetadata(existingMetadata, extraFields, knownFields) {
  * @returns The entity with metadata applied according to the mode
  */
 function applyMetadataMode(entity, metadata, mode, useCamelCase = true) {
-    if (!metadata)
+    // Return early if no metadata or empty metadata object
+    if (!metadata || Object.keys(metadata).length === 0)
         return entity;
     switch (mode) {
         case "strip":
@@ -294,20 +315,30 @@ function applyMetadataMode(entity, metadata, mode, useCamelCase = true) {
             // Add metadata field with target provider's casing
             const metadataKey = useCamelCase ? "_providerMetadata" : "_provider_metadata";
             const knownFieldsKey = useCamelCase ? "_knownFields" : "_known_fields";
-            // Normalize the known fields key in the metadata
-            const { _known_fields, _knownFields, ...rest } = metadata;
+            const partsMetadataKey = useCamelCase ? "_partsMetadata" : "_parts_metadata";
+            // Normalize the known fields and parts metadata keys in the metadata
+            const { _known_fields, _knownFields, _parts_metadata, _partsMetadata, ...rest } = metadata;
             const knownFields = _known_fields ?? _knownFields;
+            const partsMetadata = _parts_metadata ?? _partsMetadata;
             const hasKnownFields = knownFields && Object.keys(knownFields).length > 0;
-            const normalizedMetadata = hasKnownFields ? { ...rest, [knownFieldsKey]: knownFields } : rest;
+            const hasPartsMetadata = partsMetadata && Object.keys(partsMetadata).length > 0;
+            const normalizedMetadata = { ...rest };
+            if (hasKnownFields) {
+                normalizedMetadata[knownFieldsKey] = knownFields;
+            }
+            if (hasPartsMetadata) {
+                normalizedMetadata[partsMetadataKey] = partsMetadata;
+            }
             // Only add metadata field if there's something to store
             if (Object.keys(normalizedMetadata).length === 0)
                 return entity;
             return { ...entity, [metadataKey]: normalizedMetadata };
         }
         case "passthrough": {
-            // Spread all fields EXCEPT known fields (either casing)
-            const { _known_fields, _knownFields, ...extraFields } = metadata;
-            // Only spread if there are extra fields
+            // Spread all extra fields EXCEPT known fields and parts metadata (either casing)
+            // _partsMetadata should be restored to parts by the provider's fromGenAI, not spread at entity level
+            const { _known_fields, _knownFields, _parts_metadata, _partsMetadata, ...extraFields } = metadata;
+            // Only spread if there are extra fields to add
             if (Object.keys(extraFields).length === 0)
                 return entity;
             return { ...entity, ...extraFields };
@@ -1543,12 +1574,27 @@ const KnownFieldsSchema = zod.z
     isRefusal: zod.z.boolean().optional(),
     /** Original type when mapping to a different GenAI type (for lossy conversions) */
     originalType: zod.z.string().optional(),
+    /** Original message index for system parts extracted into a separate system array */
+    messageIndex: zod.z.number().optional(),
+})
+    .passthrough();
+/**
+ * Schema for collapsed part-level metadata (used when target doesn't support structured content).
+ * Has the same structure as part metadata: known fields + extra fields.
+ */
+const PartsMetadataSchema = zod.z
+    .object({
+    /** Known fields from collapsed parts */
+    _known_fields: KnownFieldsSchema.optional(),
+    /** Also check camelCase version */
+    _knownFields: KnownFieldsSchema.optional(),
 })
     .passthrough();
 /**
  * Provider metadata schema for preserving provider-specific data.
  * This is a flat structure with:
  * - `_known_fields`: Internal fields used for building correct translations
+ * - `_parts_metadata`: Collapsed part-level metadata (when target uses string content)
  * - All other fields: Extra data from the source provider, passed through
  *
  * The metadata is stored at `_provider_metadata` on GenAI entities.
@@ -1561,6 +1607,10 @@ const ProviderMetadataSchema = zod.z
     _known_fields: KnownFieldsSchema.optional(),
     /** Also check camelCase version (from VercelAI/Promptl targets) */
     _knownFields: KnownFieldsSchema.optional(),
+    /** Collapsed part-level metadata (when target uses string content) */
+    _parts_metadata: PartsMetadataSchema.optional(),
+    /** Also check camelCase version (from VercelAI/Promptl targets) */
+    _partsMetadata: PartsMetadataSchema.optional(),
 })
     .passthrough();
 /** Role of the entity that created the message. */
@@ -1690,22 +1740,44 @@ const GenAISpecification = {
         }
         const parsedSystem = GenAISystemSchema.optional().parse(system);
         if (parsedSystem && parsedSystem.length > 0) {
-            parsedMessages.unshift({ role: "system", parts: parsedSystem });
+            const partsByIndex = groupPartsByMessageIndex(parsedSystem);
+            if (partsByIndex) {
+                // Insert system messages at their original positions (lowest index first).
+                // Ascending order is correct because messageIndex refers to the position in the full
+                // conversation (including system messages). As we insert left-to-right, each insertion
+                // naturally shifts subsequent positions to account for the added messages.
+                const sortedIndices = [...partsByIndex.keys()].sort((a, b) => a - b);
+                for (const index of sortedIndices) {
+                    // biome-ignore lint/style/noNonNullAssertion: key comes from the map
+                    const parts = partsByIndex.get(index);
+                    // Clamp to valid range: -1 (no index) and 0 both go to position 0
+                    const insertAt = index < 0 ? 0 : Math.min(index, parsedMessages.length);
+                    parsedMessages.splice(insertAt, 0, { role: "system", parts });
+                }
+            }
+            else {
+                // No parts have messageIndex - fall back to prepending all as one system message
+                parsedMessages.unshift({ role: "system", parts: parsedSystem });
+            }
         }
         return { messages: parsedMessages };
     },
     fromGenAI({ messages, providerMetadata }) {
         const system = [];
         const filtered = [];
-        for (const message of messages) {
+        for (let i = 0; i < messages.length; i++) {
+            // biome-ignore lint/style/noNonNullAssertion: index is within bounds
+            const message = messages[i];
+            // Apply metadata mode to message and its parts (handles _partsMetadata restoration)
+            const transformed = applyMetadataModeToGenAIMessage(message, providerMetadata);
             if (message.role === "system") {
-                // Apply metadata mode to system parts
-                const transformedParts = message.parts.map((part) => applyMetadataModeToGenAI(part, providerMetadata));
-                system.push(...transformedParts);
+                // Store the original message index on each part so the position can be reconstructed
+                for (const part of transformed.parts) {
+                    system.push(storeMessageIndexOnPart(part, i));
+                }
             }
             else {
-                // Apply metadata mode to message and its parts
-                filtered.push(applyMetadataModeToGenAIMessage(message, providerMetadata));
+                filtered.push(transformed);
             }
         }
         return { messages: filtered, system: system.length > 0 ? system : undefined };
@@ -1722,11 +1794,60 @@ function applyMetadataModeToGenAI(part, mode) {
 function applyMetadataModeToGenAIMessage(message, mode) {
     const msgMetadata = readMetadata(message);
     const transformedParts = message.parts.map((part) => applyMetadataModeToGenAI(part, mode));
+    // Extract _partsMetadata from message metadata and apply to first part
+    // This restores part-level metadata that was merged when converting to string content
+    const partsMetadata = getPartsMetadata(msgMetadata);
+    if (partsMetadata && transformedParts.length > 0) {
+        // biome-ignore lint/style/noNonNullAssertion: length check guarantees element exists
+        transformedParts[0] = applyMetadataMode(transformedParts[0], partsMetadata, mode, false);
+    }
     // Remove existing metadata keys before applying mode
     const { _provider_metadata, _providerMetadata, parts, ...baseMessage } = message;
     const baseWithParts = { ...baseMessage, parts: transformedParts };
     return applyMetadataMode(baseWithParts, msgMetadata, mode, false);
 }
+/** Store the original message index on a system part via _provider_metadata._known_fields. */
+function storeMessageIndexOnPart(part, index) {
+    const existingMetadata = readMetadata(part);
+    const metadata = storeMetadata(existingMetadata ?? {}, {}, { messageIndex: index });
+    if (!metadata)
+        return part;
+    return { ...part, _provider_metadata: metadata };
+}
+/**
+ * Groups system parts by their messageIndex known field.
+ * Returns a Map from index to parts array, or null if no parts have a messageIndex.
+ */
+function groupPartsByMessageIndex(parts) {
+    let hasAnyIndex = false;
+    const grouped = new Map();
+    for (const part of parts) {
+        const metadata = readMetadata(part);
+        const known = getKnownFields(metadata);
+        if (known.messageIndex !== undefined) {
+            hasAnyIndex = true;
+            const idx = known.messageIndex;
+            const existing = grouped.get(idx);
+            if (existing) {
+                existing.push(part);
+            }
+            else {
+                grouped.set(idx, [part]);
+            }
+        }
+        else {
+            // Parts without an index go into a group keyed by -1 (will be prepended)
+            const existing = grouped.get(-1);
+            if (existing) {
+                existing.push(part);
+            }
+            else {
+                grouped.set(-1, [part]);
+            }
+        }
+    }
+    return hasAnyIndex ? grouped : null;
+}
 
 /**
  * Google Gemini API Schemas
@@ -3684,6 +3805,15 @@ function genAIMessageToPromptl(message, toolCallNameMap, mode) {
                 toolMessages.push(createToolMessageFromPart(part, toolCallNameMap, mode));
             }
         }
+        // Apply _partsMetadata to the first tool message's content if present
+        const partsMetadata = getPartsMetadata(msgMetadata);
+        if (partsMetadata && toolMessages.length > 0) {
+            const firstMsg = toolMessages[0];
+            if (firstMsg.content.length > 0) {
+                // biome-ignore lint/style/noNonNullAssertion: length check guarantees element exists
+                firstMsg.content[0] = applyMetadataMode(firstMsg.content[0], partsMetadata, mode, true);
+            }
+        }
         return toolMessages.length > 0 ? toolMessages : [];
     }
     // Handle assistant role - check if any parts are tool_call_response
@@ -3707,10 +3837,27 @@ function genAIMessageToPromptl(message, toolCallNameMap, mode) {
                     }
                 }
                 if (content.length > 0) {
+                    // Extract _partsMetadata from message metadata and apply to first content part
+                    const partsMetadata = getPartsMetadata(msgMetadata);
+                    if (partsMetadata) {
+                        // biome-ignore lint/style/noNonNullAssertion: length check guarantees element exists
+                        content[0] = applyMetadataMode(content[0], partsMetadata, mode, true);
+                    }
                     const assistantMsg = { role: "assistant", content };
                     result.unshift(applyMetadataMode(assistantMsg, msgMetadata, mode, true));
                 }
             }
+            else {
+                // No other parts - apply _partsMetadata to the first tool message's content
+                const partsMetadata = getPartsMetadata(msgMetadata);
+                if (partsMetadata && result.length > 0) {
+                    const firstMsg = result[0];
+                    if (firstMsg.content.length > 0) {
+                        // biome-ignore lint/style/noNonNullAssertion: length check guarantees element exists
+                        firstMsg.content[0] = applyMetadataMode(firstMsg.content[0], partsMetadata, mode, true);
+                    }
+                }
+            }
             return result;
         }
     }
@@ -3722,6 +3869,13 @@ function genAIMessageToPromptl(message, toolCallNameMap, mode) {
             content.push(converted);
         }
     }
+    // Extract _partsMetadata from message metadata and apply to first content part
+    // This restores part-level metadata that was merged when converting to string content
+    const partsMetadata = getPartsMetadata(msgMetadata);
+    if (partsMetadata && content.length > 0) {
+        // biome-ignore lint/style/noNonNullAssertion: length check guarantees element exists
+        content[0] = applyMetadataMode(content[0], partsMetadata, mode, true);
+    }
     // Map role - Promptl only accepts specific roles
     let role;
     if (message.role === "system") {
@@ -4472,6 +4626,14 @@ function genAIMessageToVercelAI(message, toolCallNameMap, mode) {
     const msgMetadata = readMetadata(message);
     // Helper to apply metadata mode to a message
     const applyMode = (msg) => applyMetadataMode(msg, msgMetadata, mode, true);
+    // Helper to check if any part has metadata that should be preserved
+    const hasPartMetadata = () => message.parts.some((p) => {
+        const meta = readMetadata(p);
+        return meta && Object.keys(meta).length > 0;
+    });
+    // Helper to determine if we should collapse single text part to string
+    // Only collapse if mode is "strip" OR no parts have metadata
+    const shouldCollapseToString = () => mode === "strip" || !hasPartMetadata();
     // Handle system messages
     if (message.role === "system") {
         // Extract text content
@@ -4479,8 +4641,21 @@ function genAIMessageToVercelAI(message, toolCallNameMap, mode) {
             .filter((p) => p.type === "text")
             .map((p) => p.content)
             .join("\n");
+        // System messages must use string content, so collect part metadata into _partsMetadata
+        let combinedMeta = msgMetadata ? { ...msgMetadata } : undefined;
+        let partsMetadata;
+        for (const part of message.parts.filter((p) => p.type === "text")) {
+            const partMeta = readMetadata(part);
+            if (partMeta && Object.keys(partMeta).length > 0) {
+                partsMetadata = { ...partsMetadata, ...partMeta };
+            }
+        }
+        if (partsMetadata) {
+            combinedMeta = { ...combinedMeta, _partsMetadata: partsMetadata };
+        }
+        const applyModeCombined = (msg) => applyMetadataMode(msg, combinedMeta, mode, true);
         return [
-            applyMode({
+            applyModeCombined({
                 role: "system",
                 content: textContent,
             }),
@@ -4498,6 +4673,12 @@ function genAIMessageToVercelAI(message, toolCallNameMap, mode) {
         if (toolParts.length === 0) {
             return [];
         }
+        // Apply _partsMetadata to the first tool part if present
+        const partsMetadata = getPartsMetadata(msgMetadata);
+        if (partsMetadata && toolParts.length > 0) {
+            // biome-ignore lint/style/noNonNullAssertion: length check guarantees element exists
+            toolParts[0] = applyMetadataMode(toolParts[0], partsMetadata, mode, true);
+        }
         return [
             applyMode({
                 role: "tool",
@@ -4514,8 +4695,10 @@ function genAIMessageToVercelAI(message, toolCallNameMap, mode) {
                 userParts.push(converted);
             }
         }
-        // If only one text part, use string content
-        if (userParts.length === 1 && userParts[0]?.type === "text") {
+        // Check for _partsMetadata - if present, we need array content to apply it
+        const partsMetadata = getPartsMetadata(msgMetadata);
+        // If only one text part and no metadata to preserve (including _partsMetadata), use string content
+        if (userParts.length === 1 && userParts[0]?.type === "text" && shouldCollapseToString() && !partsMetadata) {
             return [
                 applyMode({
                     role: "user",
@@ -4523,6 +4706,11 @@ function genAIMessageToVercelAI(message, toolCallNameMap, mode) {
                 }),
             ];
         }
+        // Apply _partsMetadata to the first user part if present
+        if (partsMetadata && userParts.length > 0) {
+            // biome-ignore lint/style/noNonNullAssertion: length check guarantees element exists
+            userParts[0] = applyMetadataMode(userParts[0], partsMetadata, mode, true);
+        }
         return [
             applyMode({
                 role: "user",
@@ -4539,8 +4727,13 @@ function genAIMessageToVercelAI(message, toolCallNameMap, mode) {
                 assistantParts.push(converted);
             }
         }
-        // If only one text part, use string content
-        if (assistantParts.length === 1 && assistantParts[0]?.type === "text") {
+        // Check for _partsMetadata - if present, we need array content to apply it
+        const partsMetadata = getPartsMetadata(msgMetadata);
+        // If only one text part and no metadata to preserve (including _partsMetadata), use string content
+        if (assistantParts.length === 1 &&
+            assistantParts[0]?.type === "text" &&
+            shouldCollapseToString() &&
+            !partsMetadata) {
             return [
                 applyMode({
                     role: "assistant",
@@ -4548,6 +4741,11 @@ function genAIMessageToVercelAI(message, toolCallNameMap, mode) {
                 }),
             ];
         }
+        // Apply _partsMetadata to the first assistant part if present
+        if (partsMetadata && assistantParts.length > 0) {
+            // biome-ignore lint/style/noNonNullAssertion: length check guarantees element exists
+            assistantParts[0] = applyMetadataMode(assistantParts[0], partsMetadata, mode, true);
+        }
         return [
             applyMode({
                 role: "assistant",
@@ -4560,6 +4758,12 @@ function genAIMessageToVercelAI(message, toolCallNameMap, mode) {
         .filter((p) => p.type === "text")
         .map((p) => ({ type: "text", text: p.content }));
     if (textParts.length > 0) {
+        // Apply _partsMetadata to the first text part if present
+        const partsMetadata = getPartsMetadata(msgMetadata);
+        if (partsMetadata) {
+            // biome-ignore lint/style/noNonNullAssertion: length check guarantees element exists
+            textParts[0] = applyMetadataMode(textParts[0], partsMetadata, mode, true);
+        }
         return [
             applyMode({
                 role: "user",