conversationalist 0.0.6 → 0.0.7

package/dist/schemas.d.ts

@@ -17,6 +17,7 @@ export declare const messageInputSchema: z.ZodType<MessageInput>;
 export declare const messageJSONSchema: z.ZodType<MessageJSON>;
 export declare const conversationStatusSchema: z.ZodType<ConversationStatus>;
 export declare const conversationShape: {
+    readonly schemaVersion: z.ZodNumber;
     readonly id: z.ZodString;
     readonly title: z.ZodOptional<z.ZodString>;
     readonly status: z.ZodType<ConversationStatus, unknown, z.core.$ZodTypeInternals<ConversationStatus, unknown>>;

package/dist/schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EACV,gBAAgB,EAChB,kBAAkB,EAClB,YAAY,EACZ,WAAW,EACX,WAAW,EACX,UAAU,EACV,QAAQ,EACR,UAAU,EACX,MAAM,SAAS,CAAC;AAEjB,eAAO,MAAM,uBAAuB;;;;;;;;2BAQlC,CAAC;AAEH,eAAO,MAAM,iBAAiB,EAQb,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;AAExC,eAAO,MAAM,cAAc,EAIV,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;AAErC,eAAO,MAAM,gBAAgB,EAIZ,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;AAEvC,eAAO,MAAM,gBAAgB,EAIZ,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;AAEvC,eAAO,MAAM,kBAAkB,EASd,CAAC,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;AAEzC,eAAO,MAAM,iBAAiB,EAcC,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;AAEtD,eAAO,MAAM,wBAAwB,EAIpB,CAAC,CAAC,OAAO,CAAC,kBAAkB,CAAC,CAAC;AAG/C,eAAO,MAAM,iBAAiB;;;;;;;;;CASpB,CAAC;AAEX,eAAO,MAAM,kBAAkB,EAEf,CAAC,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC"}
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EACV,gBAAgB,EAChB,kBAAkB,EAClB,YAAY,EACZ,WAAW,EACX,WAAW,EACX,UAAU,EACV,QAAQ,EACR,UAAU,EACX,MAAM,SAAS,CAAC;AAEjB,eAAO,MAAM,uBAAuB;;;;;;;;2BAQlC,CAAC;AAEH,eAAO,MAAM,iBAAiB,EAQb,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;AAExC,eAAO,MAAM,cAAc,EAIV,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;AAErC,eAAO,MAAM,gBAAgB,EAIZ,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;AAEvC,eAAO,MAAM,gBAAgB,EAIZ,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;AAEvC,eAAO,MAAM,kBAAkB,EASd,CAAC,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;AAEzC,eAAO,MAAM,iBAAiB,EAcC,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;AAEtD,eAAO,MAAM,wBAAwB,EAIpB,CAAC,CAAC,OAAO,CAAC,kBAAkB,CAAC,CAAC;AAG/C,eAAO,MAAM,iBAAiB;;;;;;;;;;CAUpB,CAAC;AAEX,eAAO,MAAM,kBAAkB,EAEf,CAAC,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC"}

package/dist/types.d.ts

@@ -1,4 +1,9 @@
 import type { MultiModalContent } from '@lasercat/homogenaize';
+/**
+ * Current schema version for ConversationJSON.
+ * Increment when making breaking changes to the schema.
+ */
+export declare const CURRENT_SCHEMA_VERSION = 1;
 export type MessageRole = 'user' | 'assistant' | 'system' | 'developer' | 'tool-use' | 'tool-result' | 'snapshot';
 export interface ToolCall {
     id: string;
@@ -56,6 +61,7 @@ export interface Message {
 }
 export type ConversationStatus = 'active' | 'archived' | 'deleted';
 export interface ConversationJSON {
+    schemaVersion: number;
     id: string;
     title?: string | undefined;
     status: ConversationStatus;
@@ -97,4 +103,46 @@ export interface ConversationHistoryJSON {
     root: HistoryNodeJSON;
     currentPath: number[];
 }
+/**
+ * Base options for all export operations.
+ */
+export interface ExportOptions {
+    /**
+     * When true, produces deterministic output with sorted keys and messages.
+     * Useful for testing, diffing, and content-addressable storage.
+     * @default false
+     */
+    deterministic?: boolean;
+    /**
+     * When true, strips transient metadata (keys starting with '_').
+     * @default false
+     */
+    stripTransient?: boolean;
+    /**
+     * When true, redacts tool call arguments with '[REDACTED]'.
+     * @default false
+     */
+    redactToolArguments?: boolean;
+    /**
+     * When true, redacts tool result content with '[REDACTED]'.
+     * @default false
+     */
+    redactToolResults?: boolean;
+}
+/**
+ * Options for exporting to markdown format.
+ */
+export interface ToMarkdownOptions extends ExportOptions {
+    /**
+     * When true, includes YAML frontmatter with full metadata for lossless round-trip.
+     * Headers include message ID: `### Role (msg-id)`
+     * @default false
+     */
+    includeMetadata?: boolean;
+}
+/**
+ * Options for serializing conversations to JSON.
+ * Alias for ExportOptions for API consistency.
+ */
+export type SerializeOptions = ExportOptions;
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/utilities/deterministic.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Recursively sorts object keys alphabetically for deterministic JSON output.
+ * Arrays are processed recursively but maintain their element order.
+ * Primitives and null are returned as-is.
+ *
+ * @param obj - The value to process
+ * @returns A new object with sorted keys (or the original value for non-objects)
+ *
+ * @example
+ * ```ts
+ * sortObjectKeys({ z: 1, a: 2 });
+ * // Returns: { a: 2, z: 1 }
+ *
+ * sortObjectKeys({ b: { y: 1, x: 2 }, a: 1 });
+ * // Returns: { a: 1, b: { x: 2, y: 1 } }
+ * ```
+ */
+export declare function sortObjectKeys<T>(obj: T): T;
+/**
+ * Sorts messages by position for deterministic output.
+ * When positions are equal, falls back to createdAt, then id.
+ *
+ * @param messages - Array of messages to sort
+ * @returns A new sorted array (does not mutate the original)
+ *
+ * @example
+ * ```ts
+ * const sorted = sortMessagesByPosition(messages);
+ * // Messages are ordered by position (ascending)
+ * ```
+ */
+export declare function sortMessagesByPosition<T extends {
+    position: number;
+    createdAt: string;
+    id: string;
+}>(messages: readonly T[]): T[];
+//# sourceMappingURL=deterministic.d.ts.map

package/dist/utilities/deterministic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deterministic.d.ts","sourceRoot":"","sources":["../../src/utilities/deterministic.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAiB3C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CACpC,CAAC,SAAS;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,EAC7D,QAAQ,EAAE,SAAS,CAAC,EAAE,GAAG,CAAC,EAAE,CAU7B"}

package/dist/utilities/index.d.ts

@@ -1,8 +1,10 @@
+export type { ToMarkdownOptions } from '../types';
 export { normalizeContent, toMultiModalArray } from './content';
-export type { ToMarkdownOptions } from './markdown';
-export { fromMarkdown, MarkdownParseError, toMarkdown } from './markdown';
+export { sortMessagesByPosition, sortObjectKeys } from './deterministic';
+export { fromMarkdown, getRoleFromLabel, getRoleLabel, LABEL_TO_ROLE, MarkdownParseError, ROLE_LABELS, toMarkdown, } from './markdown';
 export { createMessage, messageHasImages, messageParts, messageText, messageToJSON, messageToString, } from './message';
 export type { ToolCallPair } from './tool-calls';
 export { pairToolCallsWithResults } from './tool-calls';
+export { isTransientKey, stripTransientFromRecord, stripTransientMetadata, } from './transient';
 export { hasOwnProperty, toReadonly } from './type-helpers';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utilities/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAGhE,YAAY,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAG1E,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,YAAY,EACZ,WAAW,EACX,aAAa,EACb,eAAe,GAChB,MAAM,WAAW,CAAC;AAGnB,YAAY,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AAGxD,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utilities/index.ts"],"names":[],"mappings":"AACA,YAAY,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAGlD,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAGhE,OAAO,EAAE,sBAAsB,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAGzE,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,kBAAkB,EAClB,WAAW,EACX,UAAU,GACX,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,YAAY,EACZ,WAAW,EACX,aAAa,EACb,eAAe,GAChB,MAAM,WAAW,CAAC;AAGnB,YAAY,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AAGxD,OAAO,EACL,cAAc,EACd,wBAAwB,EACxB,sBAAsB,GACvB,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/utilities/markdown.d.ts

@@ -1,25 +1,51 @@
-import type { Conversation } from '../types';
+import type { Conversation, MessageRole, ToMarkdownOptions } from '../types';
 /**
- * Options for the toMarkdown function.
+ * Maps message roles to human-readable display labels.
+ *
+ * @example
+ * ```ts
+ * ROLE_LABELS['tool-use']; // 'Tool Use'
+ * ROLE_LABELS.assistant;   // 'Assistant'
+ * ```
  */
-export interface ToMarkdownOptions {
-    /**
-     * Whether to include metadata (YAML frontmatter with message metadata)
-     * for lossless round-trip conversion.
-     *
-     * When `true`:
-     * - Includes YAML frontmatter with conversation and message metadata
-     * - Headers include message ID: `### Role (msg-id)`
-     * - Supports lossless round-trip via `fromMarkdown`
-     *
-     * When `false` (default):
-     * - Outputs clean, human-readable markdown
-     * - Headers only include role: `### Role`
-     *
-     * @default false
-     */
-    includeMetadata?: boolean;
-}
+export declare const ROLE_LABELS: Record<MessageRole, string>;
+/**
+ * Maps display labels back to message roles.
+ *
+ * @example
+ * ```ts
+ * LABEL_TO_ROLE['Tool Use']; // 'tool-use'
+ * LABEL_TO_ROLE.User;        // 'user'
+ * ```
+ */
+export declare const LABEL_TO_ROLE: Record<string, MessageRole>;
+/**
+ * Gets the human-readable display label for a message role.
+ *
+ * @param role - The message role
+ * @returns The display label for the role
+ *
+ * @example
+ * ```ts
+ * getRoleLabel('assistant');  // 'Assistant'
+ * getRoleLabel('tool-use');   // 'Tool Use'
+ * ```
+ */
+export declare function getRoleLabel(role: MessageRole): string;
+/**
+ * Gets the message role from a display label.
+ *
+ * @param label - The display label
+ * @returns The message role, or undefined if the label is not recognized
+ *
+ * @example
+ * ```ts
+ * getRoleFromLabel('Assistant');  // 'assistant'
+ * getRoleFromLabel('Tool Use');   // 'tool-use'
+ * getRoleFromLabel('Unknown');    // undefined
+ * ```
+ */
+export declare function getRoleFromLabel(label: string): MessageRole | undefined;
 /**
  * Converts a conversation to a Markdown string representation.
  *

package/dist/utilities/markdown.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../../src/utilities/markdown.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,YAAY,EAOb,MAAM,UAAU,CAAC;AA6ElB;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;;;;;;;;;;OAcG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,UAAU,CACxB,YAAY,EAAE,YAAY,EAC1B,OAAO,GAAE,iBAAsB,GAC9B,MAAM,CAQR;AAqFD;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM;CAI5B;AASD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,CAW3D"}
+{"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../../src/utilities/markdown.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,YAAY,EAGZ,WAAW,EAEX,iBAAiB,EAGlB,MAAM,UAAU,CAAC;AAIlB;;;;;;;;GAQG;AACH,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,CAQnD,CAAC;AAKF;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAQrD,CAAC;AAKF;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,CAEtD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAEvE;AAuDD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,UAAU,CACxB,YAAY,EAAE,YAAY,EAC1B,OAAO,GAAE,iBAAsB,GAC9B,MAAM,CAQR;AAqFD;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM;CAI5B;AASD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,CAW3D"}

package/dist/utilities/transient.d.ts

@@ -0,0 +1,47 @@
+import type { Conversation } from '../types';
+/**
+ * Checks if a metadata key is transient (starts with '_').
+ * Transient metadata is intended for temporary UI state and should not be persisted.
+ *
+ * @param key - The metadata key to check
+ * @returns true if the key starts with '_'
+ *
+ * @example
+ * ```ts
+ * isTransientKey('_tempId');     // true
+ * isTransientKey('__internal');  // true
+ * isTransientKey('source');      // false
+ * ```
+ */
+export declare function isTransientKey(key: string): boolean;
+/**
+ * Strips transient metadata (keys starting with '_') from a metadata object.
+ *
+ * @param metadata - The metadata object to filter
+ * @returns A new object with transient keys removed
+ *
+ * @example
+ * ```ts
+ * stripTransientFromRecord({ _temp: 1, source: 'web' });
+ * // Returns: { source: 'web' }
+ * ```
+ */
+export declare function stripTransientFromRecord(metadata: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Strips all transient metadata from a conversation.
+ * Transient metadata is identified by keys starting with '_'.
+ * This is useful for persisting conversations without temporary UI state.
+ *
+ * @param conversation - The conversation to process
+ * @returns A new conversation with transient metadata removed from both
+ *          the conversation and all messages
+ *
+ * @example
+ * ```ts
+ * const cleaned = stripTransientMetadata(conversation);
+ * // conversation.metadata._tempState is removed
+ * // message.metadata._deliveryStatus is removed
+ * ```
+ */
+export declare function stripTransientMetadata(conversation: Conversation): Conversation;
+//# sourceMappingURL=transient.d.ts.map

package/dist/utilities/transient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transient.d.ts","sourceRoot":"","sources":["../../src/utilities/transient.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAW,MAAM,UAAU,CAAC;AAGtD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAQzB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,sBAAsB,CAAC,YAAY,EAAE,YAAY,GAAG,YAAY,CA4B/E"}

package/dist/utilities.d.ts

@@ -2,16 +2,20 @@
  * This file re-exports all utilities from the utilities/ directory.
  * For new code, prefer importing directly from the specific modules:
  * - './utilities/content' for content normalization
+ * - './utilities/deterministic' for deterministic output
  * - './utilities/markdown' for markdown conversion
  * - './utilities/message' for message utilities
  * - './utilities/tool-calls' for tool call pairing
+ * - './utilities/transient' for transient metadata handling
  * - './utilities/type-helpers' for type guard helpers
  */
+export type { ToMarkdownOptions } from './types';
 export { normalizeContent, toMultiModalArray } from './utilities/content';
-export type { ToMarkdownOptions } from './utilities/markdown';
-export { fromMarkdown, MarkdownParseError, toMarkdown } from './utilities/markdown';
+export { sortMessagesByPosition, sortObjectKeys } from './utilities/deterministic';
+export { fromMarkdown, getRoleFromLabel, getRoleLabel, LABEL_TO_ROLE, MarkdownParseError, ROLE_LABELS, toMarkdown, } from './utilities/markdown';
 export { createMessage, messageHasImages, messageParts, messageText, messageToJSON, messageToString, } from './utilities/message';
 export type { ToolCallPair } from './utilities/tool-calls';
 export { pairToolCallsWithResults } from './utilities/tool-calls';
+export { isTransientKey, stripTransientFromRecord, stripTransientMetadata, } from './utilities/transient';
 export { hasOwnProperty, toReadonly } from './utilities/type-helpers';
 //# sourceMappingURL=utilities.d.ts.map

package/dist/utilities.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utilities.d.ts","sourceRoot":"","sources":["../src/utilities.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAG1E,YAAY,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAGpF,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,YAAY,EACZ,WAAW,EACX,aAAa,EACb,eAAe,GAChB,MAAM,qBAAqB,CAAC;AAG7B,YAAY,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAC;AAGlE,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC"}
+{"version":3,"file":"utilities.d.ts","sourceRoot":"","sources":["../src/utilities.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,YAAY,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAGjD,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAG1E,OAAO,EAAE,sBAAsB,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAGnF,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,kBAAkB,EAClB,WAAW,EACX,UAAU,GACX,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,YAAY,EACZ,WAAW,EACX,aAAa,EACb,eAAe,GAChB,MAAM,qBAAqB,CAAC;AAG7B,YAAY,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAC;AAGlE,OAAO,EACL,cAAc,EACd,wBAAwB,EACxB,sBAAsB,GACvB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "conversationalist",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "description": "A TypeScript library for managing AI conversation state",
   "keywords": [
     "conversation",