rosetta-ai 1.5.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:

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,6 +245,7 @@ function getKnownFields(metadata) {
         isError: known?.isError,
         isRefusal: known?.isRefusal,
         originalType: known?.originalType,
+        messageIndex: known?.messageIndex,
     };
 }
 /**
@@ -298,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":
@@ -1567,6 +1574,8 @@ 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();
 /**
@@ -1731,18 +1740,41 @@ 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") {
-                system.push(...transformed.parts);
+                // 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 {
                 filtered.push(transformed);
@@ -1774,6 +1806,48 @@ function applyMetadataModeToGenAIMessage(message, mode) {
     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