conversationalist 0.0.6 → 0.0.7

package/README.md

@@ -2,7 +2,7 @@
 
 A TypeScript-first library for managing LLM conversation state with **immutable updates**, **type-safe APIs**, and **provider-agnostic adapters**.
 
-[![Tests](https://github.com/stevekinney/conversationalist/actions/workflows/test.yml/badge.svg)](https://github.com/stevekinney/conversationalist/actions/workflows/test.yml)
+[![CI](https://github.com/stevekinney/conversationalist/actions/workflows/ci.yml/badge.svg)](https://github.com/stevekinney/conversationalist/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 ## What is Conversationalist?
@@ -611,6 +611,112 @@ const restoredWithEnv = ConversationHistory.from(json, {
 });
 ```
 
+## Advanced Serialization
+
+### Schema Versioning
+
+Conversations include a `schemaVersion` field for forward compatibility. When loading older data, use `migrateConversationJSON` to upgrade it to the current schema:
+
+```ts
+import {
+  migrateConversationJSON,
+  deserializeConversation,
+  CURRENT_SCHEMA_VERSION,
+} from 'conversationalist';
+
+// Old data without schemaVersion
+const legacyData = JSON.parse(oldStorage);
+const migrated = migrateConversationJSON(legacyData);
+// migrated.schemaVersion === CURRENT_SCHEMA_VERSION
+
+const conversation = deserializeConversation(migrated);
+```
+
+### Serialization Options
+
+`serializeConversation` accepts options for controlling the output:
+
+```ts
+import { serializeConversation } from 'conversationalist';
+
+const json = serializeConversation(conversation, {
+  // Sort keys and messages for stable, diff-friendly output
+  deterministic: true,
+
+  // Remove metadata keys starting with '_' (transient UI state)
+  stripTransient: true,
+
+  // Replace tool arguments with '[REDACTED]'
+  redactToolArguments: true,
+
+  // Replace tool result content with '[REDACTED]'
+  redactToolResults: true,
+});
+```
+
+### Transient Metadata Convention
+
+Keys prefixed with `_` are considered transient—temporary UI state that shouldn't be persisted:
+
+```ts
+import {
+  isTransientKey,
+  stripTransientFromRecord,
+  stripTransientMetadata,
+} from 'conversationalist';
+
+// Check if a key is transient
+isTransientKey('_tempId'); // true
+isTransientKey('source'); // false
+
+// Strip transient keys from a metadata object
+stripTransientFromRecord({ _loading: true, source: 'web' });
+// { source: 'web' }
+
+// Strip transient metadata from an entire conversation
+const cleaned = stripTransientMetadata(conversation);
+```
+
+### Deterministic Output
+
+For reproducible snapshots or tests, use the deterministic utilities:
+
+```ts
+import { sortObjectKeys, sortMessagesByPosition } from 'conversationalist';
+
+// Sort object keys alphabetically (recursive)
+const sorted = sortObjectKeys({ z: 1, a: 2, nested: { b: 3, a: 4 } });
+// { a: 2, nested: { a: 4, b: 3 }, z: 1 }
+
+// Sort messages by position, createdAt, then id
+const orderedMessages = sortMessagesByPosition(messages);
+```
+
+### Role Labels
+
+Export human-readable labels for message roles:
+
+```ts
+import {
+  ROLE_LABELS,
+  LABEL_TO_ROLE,
+  getRoleLabel,
+  getRoleFromLabel,
+} from 'conversationalist';
+
+// Get display label for a role
+getRoleLabel('tool-use'); // 'Tool Use'
+getRoleLabel('assistant'); // 'Assistant'
+
+// Get role from a label
+getRoleFromLabel('Tool Result'); // 'tool-result'
+getRoleFromLabel('Unknown'); // undefined
+
+// Access the mappings directly
+ROLE_LABELS['developer']; // 'Developer'
+LABEL_TO_ROLE['System']; // 'system'
+```
+
 ### Markdown Serialization
 
 You can also convert a conversation to Markdown format for human-readable storage or export, and restore it later.
@@ -799,16 +905,19 @@ Svelte 5's runes pair perfectly with **Conversationalist**. You can use the `Con
 
 ## API Overview
 
-| Category         | Key Functions                                                                                            |
-| :--------------- | :------------------------------------------------------------------------------------------------------- |
-| **Creation**     | `createConversation`, `serializeConversation`, `deserializeConversation`                                 |
-| **Appending**    | `appendUserMessage`, `appendAssistantMessage`, `appendSystemMessage`, `appendMessages`                   |
-| **Streaming**    | `appendStreamingMessage`, `updateStreamingMessage`, `finalizeStreamingMessage`, `cancelStreamingMessage` |
-| **Modification** | `redactMessageAtPosition`, `replaceSystemMessage`, `collapseSystemMessages`                              |
-| **Context**      | `truncateToTokenLimit`, `getRecentMessages`, `estimateConversationTokens`                                |
-| **Querying**     | `getConversationMessages`, `getMessageByIdentifier`, `computeConversationStatistics`                     |
-| **Conversion**   | `toMarkdown`, `fromMarkdown`, `toChatMessages`, `pairToolCallsWithResults`                               |
-| **History**      | `ConversationHistory`, `bindToConversationHistory`                                                       |
+| Category          | Key Functions                                                                                            |
+| :---------------- | :------------------------------------------------------------------------------------------------------- |
+| **Creation**      | `createConversation`, `serializeConversation`, `deserializeConversation`, `migrateConversationJSON`      |
+| **Appending**     | `appendUserMessage`, `appendAssistantMessage`, `appendSystemMessage`, `appendMessages`                   |
+| **Streaming**     | `appendStreamingMessage`, `updateStreamingMessage`, `finalizeStreamingMessage`, `cancelStreamingMessage` |
+| **Modification**  | `redactMessageAtPosition`, `replaceSystemMessage`, `collapseSystemMessages`                              |
+| **Context**       | `truncateToTokenLimit`, `getRecentMessages`, `estimateConversationTokens`                                |
+| **Querying**      | `getConversationMessages`, `getMessageByIdentifier`, `computeConversationStatistics`                     |
+| **Conversion**    | `toMarkdown`, `fromMarkdown`, `toChatMessages`, `pairToolCallsWithResults`                               |
+| **Role Labels**   | `ROLE_LABELS`, `LABEL_TO_ROLE`, `getRoleLabel`, `getRoleFromLabel`                                       |
+| **Transient**     | `isTransientKey`, `stripTransientFromRecord`, `stripTransientMetadata`                                   |
+| **Deterministic** | `sortObjectKeys`, `sortMessagesByPosition`                                                               |
+| **History**       | `ConversationHistory`, `bindToConversationHistory`                                                       |
 
 ## Deterministic Environments (Testing)
 

package/dist/conversation/index.d.ts

@@ -4,6 +4,6 @@ export { appendAssistantMessage, appendMessages, appendSystemMessage, appendUser
 export { computeConversationStatistics, getConversationMessages, getMessageAtPosition, getMessageByIdentifier, searchConversationMessages, } from './query';
 export { collapseSystemMessages, getFirstSystemMessage, getSystemMessages, hasSystemMessage, prependSystemMessage, replaceSystemMessage, } from './system-messages';
 export { redactMessageAtPosition } from './modify';
-export { deserializeConversation, serializeConversation } from './serialization';
+export { deserializeConversation, migrateConversationJSON, serializeConversation, } from './serialization';
 export { toChatMessages } from './transform';
 //# sourceMappingURL=index.d.ts.map

package/dist/conversation/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/conversation/index.ts"],"names":[],"mappings":"AACA,YAAY,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAG9D,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAG9C,OAAO,EACL,sBAAsB,EACtB,cAAc,EACd,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,UAAU,CAAC;AAGlB,OAAO,EACL,6BAA6B,EAC7B,uBAAuB,EACvB,oBAAoB,EACpB,sBAAsB,EACtB,0BAA0B,GAC3B,MAAM,SAAS,CAAC;AAGjB,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EACrB,iBAAiB,EACjB,gBAAgB,EAChB,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EAAE,uBAAuB,EAAE,MAAM,UAAU,CAAC;AAGnD,OAAO,EAAE,uBAAuB,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAGjF,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/conversation/index.ts"],"names":[],"mappings":"AACA,YAAY,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAG9D,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAG9C,OAAO,EACL,sBAAsB,EACtB,cAAc,EACd,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,UAAU,CAAC;AAGlB,OAAO,EACL,6BAA6B,EAC7B,uBAAuB,EACvB,oBAAoB,EACpB,sBAAsB,EACtB,0BAA0B,GAC3B,MAAM,SAAS,CAAC;AAGjB,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EACrB,iBAAiB,EACjB,gBAAgB,EAChB,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EAAE,uBAAuB,EAAE,MAAM,UAAU,CAAC;AAGnD,OAAO,EACL,uBAAuB,EACvB,uBAAuB,EACvB,qBAAqB,GACtB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC"}

package/dist/conversation/serialization.d.ts

@@ -1,13 +1,51 @@
-import type { Conversation, ConversationJSON } from '../types';
+import type { Conversation, ConversationJSON, SerializeOptions } from '../types';
+/**
+ * Migrates a conversation JSON object to the current schema version.
+ * Handles data from older versions that may not have a schemaVersion field.
+ *
+ * @param json - The conversation JSON to migrate (may be from an older version)
+ * @returns A ConversationJSON with the current schema version
+ *
+ * @example
+ * ```ts
+ * // Old data without schemaVersion
+ * const old = { id: 'conv-1', status: 'active', ... };
+ * const migrated = migrateConversationJSON(old);
+ * // migrated.schemaVersion === CURRENT_SCHEMA_VERSION
+ * ```
+ */
+export declare function migrateConversationJSON(json: unknown): ConversationJSON;
 /**
  * Converts a conversation to a plain JSON-serializable object.
  * Creates deep copies of all nested objects to ensure immutability.
+ *
+ * @param conversation - The conversation to serialize
+ * @param options - Serialization options
+ * @returns A JSON-serializable conversation object
+ *
+ * @example
+ * ```ts
+ * // Basic serialization
+ * const json = serializeConversation(conversation);
+ *
+ * // With options
+ * const json = serializeConversation(conversation, {
+ *   deterministic: true,
+ *   stripTransient: true,
+ *   redactToolArguments: true,
+ * });
+ * ```
  */
-export declare function serializeConversation(conversation: Conversation): ConversationJSON;
+export declare function serializeConversation(conversation: Conversation, options?: SerializeOptions): ConversationJSON;
 /**
  * Reconstructs a conversation from a JSON object.
+ * Automatically migrates data from older schema versions.
  * Validates message positions are contiguous and tool results reference valid calls.
  * Throws a serialization error if validation fails.
+ *
+ * @param json - The conversation JSON to deserialize (may be from an older version)
+ * @returns A Conversation object
+ * @throws {SerializationError} If validation fails
  */
-export declare function deserializeConversation(json: ConversationJSON): Conversation;
+export declare function deserializeConversation(json: unknown): Conversation;
 //# sourceMappingURL=serialization.d.ts.map

package/dist/conversation/serialization.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serialization.d.ts","sourceRoot":"","sources":["../../src/conversation/serialization.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAW,MAAM,UAAU,CAAC;AAIxE;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,YAAY,GAAG,gBAAgB,CAuBlF;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,gBAAgB,GAAG,YAAY,CA2C5E"}
+{"version":3,"file":"serialization.d.ts","sourceRoot":"","sources":["../../src/conversation/serialization.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,YAAY,EACZ,gBAAgB,EAGhB,gBAAgB,EACjB,MAAM,UAAU,CAAC;AAUlB;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,OAAO,GAAG,gBAAgB,CA2BvE;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,qBAAqB,CACnC,YAAY,EAAE,YAAY,EAC1B,OAAO,GAAE,gBAAqB,GAC7B,gBAAgB,CAqElB;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,OAAO,GAAG,YAAY,CA8CnE"}

package/dist/conversation.d.ts

@@ -1,6 +1,6 @@
 import type { Message as ExternalMessage } from '@lasercat/homogenaize';
 import { type ConversationEnvironment } from './environment';
-import type { Conversation, ConversationJSON, ConversationStatus, Message, MessageInput } from './types';
+import type { Conversation, ConversationJSON, ConversationStatus, Message, MessageInput, SerializeOptions } from './types';
 export type { ConversationEnvironment } from './environment';
 export declare function createConversation(options?: {
     id?: string;
@@ -33,7 +33,21 @@ export declare function prependSystemMessage(conversation: Conversation, content
 export declare function replaceSystemMessage(conversation: Conversation, content: string, metadata?: Record<string, unknown>, environment?: Partial<ConversationEnvironment>): Conversation;
 export declare function collapseSystemMessages(conversation: Conversation, environment?: Partial<ConversationEnvironment>): Conversation;
 export declare function redactMessageAtPosition(conversation: Conversation, position: number, placeholder?: string, environment?: Partial<ConversationEnvironment>): Conversation;
-export declare function serializeConversation(conversation: Conversation): ConversationJSON;
-export declare function deserializeConversation(json: ConversationJSON): Conversation;
+/**
+ * Migrates a conversation JSON object to the current schema version.
+ * Handles data from older versions that may not have a schemaVersion field.
+ */
+export declare function migrateConversationJSON(json: unknown): ConversationJSON;
+/**
+ * Converts a conversation to a plain JSON-serializable object.
+ * Creates deep copies of all nested objects to ensure immutability.
+ */
+export declare function serializeConversation(conversation: Conversation, options?: SerializeOptions): ConversationJSON;
+/**
+ * Reconstructs a conversation from a JSON object.
+ * Automatically migrates data from older schema versions.
+ * Validates message positions are contiguous and tool results reference valid calls.
+ */
+export declare function deserializeConversation(json: unknown): Conversation;
 export declare function toChatMessages(conversation: Conversation): ExternalMessage[];
 //# sourceMappingURL=conversation.d.ts.map

package/dist/conversation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"conversation.d.ts","sourceRoot":"","sources":["../src/conversation.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"conversation.d.ts","sourceRoot":"","sources":["../src/conversation.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,16 +1,17 @@
 export type { ImageContent, TextContent } from './multi-modal';
 export { copyContent, copyMultiModalContent } from './multi-modal';
 export type { Message as ExternalMessage, MultiModalContent, } from '@lasercat/homogenaize';
-export type { Conversation, ConversationJSON, ConversationStatus, Message, MessageInput, MessageJSON, MessageRole, TokenUsage, ToolCall, ToolResult, } from './types';
+export type { Conversation, ConversationJSON, ConversationStatus, ExportOptions, Message, MessageInput, MessageJSON, MessageRole, SerializeOptions, TokenUsage, ToMarkdownOptions, ToolCall, ToolResult, } from './types';
+export { CURRENT_SCHEMA_VERSION } from './types';
 export { conversationSchema, conversationShape, messageInputSchema, messageJSONSchema, messageRoleSchema, multiModalContentSchema, tokenUsageSchema, toolCallSchema, toolResultSchema, } from './schemas';
 export type { ConversationEnvironment } from './conversation';
-export { appendAssistantMessage, appendMessages, appendSystemMessage, appendUserMessage, collapseSystemMessages, computeConversationStatistics, createConversation, deserializeConversation, getConversationMessages, getFirstSystemMessage, getMessageAtPosition, getMessageByIdentifier, getSystemMessages, hasSystemMessage, prependSystemMessage, redactMessageAtPosition, replaceSystemMessage, searchConversationMessages, serializeConversation, toChatMessages, } from './conversation';
+export { appendAssistantMessage, appendMessages, appendSystemMessage, appendUserMessage, collapseSystemMessages, computeConversationStatistics, createConversation, deserializeConversation, getConversationMessages, getFirstSystemMessage, getMessageAtPosition, getMessageByIdentifier, getSystemMessages, hasSystemMessage, migrateConversationJSON, prependSystemMessage, redactMessageAtPosition, replaceSystemMessage, searchConversationMessages, serializeConversation, toChatMessages, } from './conversation';
 export { withEnvironment } from './environment';
 export { createMessage } from './utilities';
 export type { ConversationalistErrorCode } from './errors';
 export { ConversationalistError, createDuplicateIdError, createInvalidInputError, createInvalidPositionError, createInvalidToolReferenceError, createLockedError, createNotFoundError, createSerializationError, createValidationError, } from './errors';
-export type { ToMarkdownOptions, ToolCallPair } from './utilities';
-export { fromMarkdown, MarkdownParseError, normalizeContent, pairToolCallsWithResults, toMarkdown, toMultiModalArray, } from './utilities';
+export type { ToolCallPair } from './utilities';
+export { fromMarkdown, getRoleFromLabel, getRoleLabel, isTransientKey, LABEL_TO_ROLE, MarkdownParseError, normalizeContent, pairToolCallsWithResults, ROLE_LABELS, sortMessagesByPosition, sortObjectKeys, stripTransientFromRecord, stripTransientMetadata, toMarkdown, toMultiModalArray, } from './utilities';
 export type { ConversationDraft } from './with-conversation';
 export { pipeConversation, withConversation } from './with-conversation';
 export { bindToConversationHistory, ConversationHistory } from './history';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC/D,OAAO,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AACnE,YAAY,EACV,OAAO,IAAI,eAAe,EAC1B,iBAAiB,GAClB,MAAM,uBAAuB,CAAC;AAG/B,YAAY,EACV,YAAY,EACZ,gBAAgB,EAChB,kBAAkB,EAClB,OAAO,EACP,YAAY,EACZ,WAAW,EACX,WAAW,EACX,UAAU,EACV,QAAQ,EACR,UAAU,GACX,MAAM,SAAS,CAAC;AAGjB,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACjB,uBAAuB,EACvB,gBAAgB,EAChB,cAAc,EACd,gBAAgB,GACjB,MAAM,WAAW,CAAC;AAGnB,YAAY,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAC9D,OAAO,EACL,sBAAsB,EACtB,cAAc,EACd,mBAAmB,EACnB,iBAAiB,EACjB,sBAAsB,EACtB,6BAA6B,EAC7B,kBAAkB,EAClB,uBAAuB,EACvB,uBAAuB,EACvB,qBAAqB,EACrB,oBAAoB,EACpB,sBAAsB,EACtB,iBAAiB,EACjB,gBAAgB,EAChB,oBAAoB,EACpB,uBAAuB,EACvB,oBAAoB,EACpB,0BAA0B,EAC1B,qBAAqB,EACrB,cAAc,GACf,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAGhD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAG5C,YAAY,EAAE,0BAA0B,EAAE,MAAM,UAAU,CAAC;AAC3D,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EACtB,uBAAuB,EACvB,0BAA0B,EAC1B,+BAA+B,EAC/B,iBAAiB,EACjB,mBAAmB,EACnB,wBAAwB,EACxB,qBAAqB,GACtB,MAAM,UAAU,CAAC;AAGlB,YAAY,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACnE,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,gBAAgB,EAChB,wBAAwB,EACxB,UAAU,EACV,iBAAiB,GAClB,MAAM,aAAa,CAAC;AAGrB,YAAY,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAGzE,OAAO,EAAE,yBAAyB,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAC3E,YAAY,EAAE,uBAAuB,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAGxE,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EACtB,wBAAwB,EACxB,mBAAmB,EACnB,kBAAkB,EAClB,sBAAsB,GACvB,MAAM,aAAa,CAAC;AAGrB,OAAO,EACL,0BAA0B,EAC1B,iBAAiB,EACjB,oBAAoB,EACpB,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC/D,OAAO,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AACnE,YAAY,EACV,OAAO,IAAI,eAAe,EAC1B,iBAAiB,GAClB,MAAM,uBAAuB,CAAC;AAG/B,YAAY,EACV,YAAY,EACZ,gBAAgB,EAChB,kBAAkB,EAClB,aAAa,EACb,OAAO,EACP,YAAY,EACZ,WAAW,EACX,WAAW,EACX,gBAAgB,EAChB,UAAU,EACV,iBAAiB,EACjB,QAAQ,EACR,UAAU,GACX,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,sBAAsB,EAAE,MAAM,SAAS,CAAC;AAGjD,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACjB,uBAAuB,EACvB,gBAAgB,EAChB,cAAc,EACd,gBAAgB,GACjB,MAAM,WAAW,CAAC;AAGnB,YAAY,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAC9D,OAAO,EACL,sBAAsB,EACtB,cAAc,EACd,mBAAmB,EACnB,iBAAiB,EACjB,sBAAsB,EACtB,6BAA6B,EAC7B,kBAAkB,EAClB,uBAAuB,EACvB,uBAAuB,EACvB,qBAAqB,EACrB,oBAAoB,EACpB,sBAAsB,EACtB,iBAAiB,EACjB,gBAAgB,EAChB,uBAAuB,EACvB,oBAAoB,EACpB,uBAAuB,EACvB,oBAAoB,EACpB,0BAA0B,EAC1B,qBAAqB,EACrB,cAAc,GACf,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAGhD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAG5C,YAAY,EAAE,0BAA0B,EAAE,MAAM,UAAU,CAAC;AAC3D,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EACtB,uBAAuB,EACvB,0BAA0B,EAC1B,+BAA+B,EAC/B,iBAAiB,EACjB,mBAAmB,EACnB,wBAAwB,EACxB,qBAAqB,GACtB,MAAM,UAAU,CAAC;AAGlB,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,YAAY,EACZ,cAAc,EACd,aAAa,EACb,kBAAkB,EAClB,gBAAgB,EAChB,wBAAwB,EACxB,WAAW,EACX,sBAAsB,EACtB,cAAc,EACd,wBAAwB,EACxB,sBAAsB,EACtB,UAAU,EACV,iBAAiB,GAClB,MAAM,aAAa,CAAC;AAGrB,YAAY,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAGzE,OAAO,EAAE,yBAAyB,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAC3E,YAAY,EAAE,uBAAuB,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAGxE,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EACtB,wBAAwB,EACxB,mBAAmB,EACnB,kBAAkB,EAClB,sBAAsB,GACvB,MAAM,aAAa,CAAC;AAGrB,OAAO,EACL,0BAA0B,EAC1B,iBAAiB,EACjB,oBAAoB,EACpB,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -3514,6 +3514,8 @@ function copyContent(content) {
   }
   return content.map(copyMultiModalContent);
 }
+// src/types.ts
+var CURRENT_SCHEMA_VERSION = 1;
 // src/schemas.ts
 import { z } from "zod";
 var multiModalContentSchema = z.discriminatedUnion("type", [
@@ -3578,6 +3580,7 @@ var conversationStatusSchema = z.enum([
   "deleted"
 ]);
 var conversationShape = {
+  schemaVersion: z.number().int().min(1),
   id: z.string(),
   title: z.string().optional(),
   status: conversationStatusSchema,
@@ -3601,6 +3604,32 @@ function normalizeContent(content) {
     return content;
   return Array.isArray(content) ? content : [content];
 }
+// src/utilities/deterministic.ts
+function sortObjectKeys(obj) {
+  if (obj === null || typeof obj !== "object") {
+    return obj;
+  }
+  if (Array.isArray(obj)) {
+    return obj.map(sortObjectKeys);
+  }
+  const sorted = {};
+  const keys = Object.keys(obj).sort();
+  for (const key of keys) {
+    sorted[key] = sortObjectKeys(obj[key]);
+  }
+  return sorted;
+}
+function sortMessagesByPosition(messages) {
+  return [...messages].sort((a, b) => {
+    if (a.position !== b.position) {
+      return a.position - b.position;
+    }
+    if (a.createdAt !== b.createdAt) {
+      return a.createdAt.localeCompare(b.createdAt);
+    }
+    return a.id.localeCompare(b.id);
+  });
+}
 // src/utilities/markdown.ts
 var import_gray_matter = __toESM(require_gray_matter(), 1);
 
@@ -3645,7 +3674,7 @@ function messageHasImages(message) {
 }
 
 // src/utilities/markdown.ts
-var ROLE_DISPLAY_NAMES = {
+var ROLE_LABELS = {
   user: "User",
   assistant: "Assistant",
   system: "System",
@@ -3654,7 +3683,8 @@ var ROLE_DISPLAY_NAMES = {
   "tool-result": "Tool Result",
   snapshot: "Snapshot"
 };
-var DISPLAY_NAME_TO_ROLE = {
+var ROLE_DISPLAY_NAMES = ROLE_LABELS;
+var LABEL_TO_ROLE = {
   User: "user",
   Assistant: "assistant",
   System: "system",
@@ -3663,6 +3693,13 @@ var DISPLAY_NAME_TO_ROLE = {
   "Tool Result": "tool-result",
   Snapshot: "snapshot"
 };
+var DISPLAY_NAME_TO_ROLE = LABEL_TO_ROLE;
+function getRoleLabel(role) {
+  return ROLE_LABELS[role];
+}
+function getRoleFromLabel(label) {
+  return LABEL_TO_ROLE[label];
+}
 function formatMessageContent(message) {
   if (typeof message.content === "string")
     return message.content;
@@ -3884,6 +3921,44 @@ function pairToolCallsWithResults(messages) {
   }
   return pairs;
 }
+// src/utilities/transient.ts
+function isTransientKey(key) {
+  return key.startsWith("_");
+}
+function stripTransientFromRecord(metadata) {
+  const result = {};
+  for (const [key, value] of Object.entries(metadata)) {
+    if (!isTransientKey(key)) {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+function stripTransientMetadata(conversation) {
+  const strippedMessages = conversation.messages.map((message) => toReadonly({
+    id: message.id,
+    role: message.role,
+    content: message.content,
+    position: message.position,
+    createdAt: message.createdAt,
+    metadata: toReadonly(stripTransientFromRecord({ ...message.metadata })),
+    hidden: message.hidden,
+    toolCall: message.toolCall,
+    toolResult: message.toolResult,
+    tokenUsage: message.tokenUsage,
+    goalCompleted: message.goalCompleted
+  }));
+  return toReadonly({
+    id: conversation.id,
+    title: conversation.title,
+    status: conversation.status,
+    metadata: toReadonly(stripTransientFromRecord({ ...conversation.metadata })),
+    tags: conversation.tags,
+    messages: strippedMessages,
+    createdAt: conversation.createdAt,
+    updatedAt: conversation.updatedAt
+  });
+}
 // src/environment.ts
 function simpleTokenEstimator(message) {
   const text = messageText(message);
@@ -4237,33 +4312,88 @@ function redactMessageAtPosition(conversation, position, placeholder = "[REDACTE
   const next = { ...conversation, messages, updatedAt: now };
   return toReadonly(next);
 }
-function serializeConversation(conversation) {
-  return {
-    id: conversation.id,
-    title: conversation.title,
-    status: conversation.status,
-    metadata: { ...conversation.metadata },
-    tags: [...conversation.tags],
-    messages: conversation.messages.map((m) => ({
+var REDACTED = "[REDACTED]";
+function migrateConversationJSON(json) {
+  if (typeof json !== "object" || json === null || Array.isArray(json)) {
+    return {
+      schemaVersion: CURRENT_SCHEMA_VERSION,
+      id: "",
+      status: "active",
+      metadata: {},
+      tags: [],
+      messages: [],
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString()
+    };
+  }
+  const data = json;
+  if (!("schemaVersion" in json)) {
+    return {
+      ...data,
+      schemaVersion: CURRENT_SCHEMA_VERSION
+    };
+  }
+  return data;
+}
+function serializeConversation(conversation, options2 = {}) {
+  const {
+    deterministic = false,
+    stripTransient = false,
+    redactToolArguments = false,
+    redactToolResults = false
+  } = options2;
+  let metadata = { ...conversation.metadata };
+  if (stripTransient) {
+    metadata = stripTransientFromRecord(metadata);
+  }
+  let messages = conversation.messages.map((m) => {
+    let msgMetadata = { ...m.metadata };
+    if (stripTransient) {
+      msgMetadata = stripTransientFromRecord(msgMetadata);
+    }
+    return {
       id: m.id,
       role: m.role,
       content: copyContent(m.content),
       position: m.position,
       createdAt: m.createdAt,
-      metadata: { ...m.metadata },
+      metadata: msgMetadata,
       hidden: m.hidden,
-      toolCall: m.toolCall ? { ...m.toolCall } : undefined,
-      toolResult: m.toolResult ? { ...m.toolResult } : undefined,
+      toolCall: m.toolCall ? {
+        ...m.toolCall,
+        arguments: redactToolArguments ? REDACTED : m.toolCall.arguments
+      } : undefined,
+      toolResult: m.toolResult ? {
+        ...m.toolResult,
+        content: redactToolResults ? REDACTED : m.toolResult.content
+      } : undefined,
       tokenUsage: m.tokenUsage ? { ...m.tokenUsage } : undefined,
       goalCompleted: m.goalCompleted
-    })),
+    };
+  });
+  if (deterministic) {
+    messages = sortMessagesByPosition(messages);
+  }
+  let result = {
+    schemaVersion: CURRENT_SCHEMA_VERSION,
+    id: conversation.id,
+    title: conversation.title,
+    status: conversation.status,
+    metadata,
+    tags: [...conversation.tags],
+    messages,
     createdAt: conversation.createdAt,
     updatedAt: conversation.updatedAt
   };
+  if (deterministic) {
+    result = sortObjectKeys(result);
+  }
+  return result;
 }
 function deserializeConversation(json) {
+  const migrated = migrateConversationJSON(json);
   try {
-    json.messages.reduce((state, message, index) => {
+    migrated.messages.reduce((state, message, index) => {
       if (message.position !== index) {
         throw createInvalidPositionError(index, message.position);
       }
@@ -4277,16 +4407,16 @@ function deserializeConversation(json) {
       }
       return state;
     }, { toolUses: new Map });
-    const messages = json.messages.map((m) => createMessage(m));
+    const messages = migrated.messages.map((m) => createMessage(m));
     const conv = {
-      id: json.id,
-      title: json.title,
-      status: json.status,
-      metadata: { ...json.metadata },
-      tags: [...json.tags],
+      id: migrated.id,
+      title: migrated.title,
+      status: migrated.status,
+      metadata: { ...migrated.metadata },
+      tags: [...migrated.tags],
       messages,
-      createdAt: json.createdAt,
-      updatedAt: json.updatedAt
+      createdAt: migrated.createdAt,
+      updatedAt: migrated.updatedAt
     };
     return toReadonly(conv);
   } catch (error) {
@@ -4950,6 +5080,10 @@ export {
   toMultiModalArray,
   toMarkdown,
   toChatMessages,
+  stripTransientMetadata,
+  stripTransientFromRecord,
+  sortObjectKeys,
+  sortMessagesByPosition,
   simpleTokenEstimator,
   serializeConversation,
   searchConversationMessages,
@@ -4960,13 +5094,17 @@ export {
   pairToolCallsWithResults,
   normalizeContent,
   multiModalContentSchema,
+  migrateConversationJSON,
   messageRoleSchema,
   messageJSONSchema,
   messageInputSchema,
+  isTransientKey,
   isStreamingMessage,
   hasSystemMessage,
   getSystemMessages,
   getStreamingMessage,
+  getRoleLabel,
+  getRoleFromLabel,
   getRecentMessages,
   getMessageByIdentifier,
   getMessageAtPosition,
@@ -4999,9 +5137,12 @@ export {
   appendStreamingMessage,
   appendMessages,
   appendAssistantMessage,
+  ROLE_LABELS,
   MarkdownParseError,
+  LABEL_TO_ROLE,
   ConversationalistError,
-  ConversationHistory
+  ConversationHistory,
+  CURRENT_SCHEMA_VERSION
 };
 
-//# debugId=5ABC5C6EA1F008F764756E2164756E21
+//# debugId=5DC3B590F98C078D64756E2164756E21