conversationalist 0.0.1

package/dist/message.d.ts

@@ -0,0 +1,2 @@
+export { createMessage, messageHasImages, messageParts, messageText, messageToJSON, messageToString, } from './utilities';
+//# sourceMappingURL=message.d.ts.map

package/dist/message.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message.d.ts","sourceRoot":"","sources":["../src/message.ts"],"names":[],"mappings":"AACA,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,YAAY,EACZ,WAAW,EACX,aAAa,EACb,eAAe,GAChB,MAAM,aAAa,CAAC"}

package/dist/multi-modal.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Re-exports multi-modal types from @lasercat/homogenaize
+ */
+import type { MultiModalContent } from '@lasercat/homogenaize';
+export type { Message, MultiModalContent } from '@lasercat/homogenaize';
+/**
+ * TextContent and ImageContent are convenience types for discriminating MultiModalContent.
+ */
+export interface TextContent {
+    type: 'text';
+    text: string;
+}
+export interface ImageContent {
+    type: 'image';
+    url: string;
+    mimeType?: string;
+    text?: string;
+}
+/**
+ * Creates a shallow copy of a MultiModalContent item.
+ */
+export declare function copyMultiModalContent(item: MultiModalContent): MultiModalContent;
+/**
+ * Copies content, ensuring a mutable array is returned for multi-modal content.
+ */
+export declare function copyContent(content: string | ReadonlyArray<MultiModalContent>): string | MultiModalContent[];
+//# sourceMappingURL=multi-modal.d.ts.map

package/dist/multi-modal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"multi-modal.d.ts","sourceRoot":"","sources":["../src/multi-modal.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAE/D,YAAY,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAExE;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,OAAO,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,iBAAiB,GAAG,iBAAiB,CAWhF;AAED;;GAEG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,MAAM,GAAG,aAAa,CAAC,iBAAiB,CAAC,GACjD,MAAM,GAAG,iBAAiB,EAAE,CAK9B"}

package/dist/schemas.d.ts

@@ -0,0 +1,30 @@
+import { z } from 'zod';
+import type { ConversationJSON, ConversationStatus, MessageInput, MessageJSON, MessageRole, TokenUsage, ToolCall, ToolResult } from './types';
+export declare const multiModalContentSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"text">;
+    text: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"image">;
+    url: z.ZodString;
+    mimeType: z.ZodOptional<z.ZodString>;
+    text: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>], "type">;
+export declare const messageRoleSchema: z.ZodType<MessageRole>;
+export declare const toolCallSchema: z.ZodType<ToolCall>;
+export declare const toolResultSchema: z.ZodType<ToolResult>;
+export declare const tokenUsageSchema: z.ZodType<TokenUsage>;
+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 id: z.ZodString;
+    readonly title: z.ZodOptional<z.ZodString>;
+    readonly status: z.ZodType<ConversationStatus, unknown, z.core.$ZodTypeInternals<ConversationStatus, unknown>>;
+    readonly metadata: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    readonly tags: z.ZodArray<z.ZodString>;
+    readonly messages: z.ZodArray<z.ZodType<MessageJSON, unknown, z.core.$ZodTypeInternals<MessageJSON, unknown>>>;
+    readonly createdAt: z.ZodString;
+    readonly updatedAt: z.ZodString;
+};
+export declare const conversationSchema: z.ZodType<ConversationJSON>;
+//# sourceMappingURL=schemas.d.ts.map

package/dist/schemas.d.ts.map

@@ -0,0 +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"}

package/dist/streaming.d.ts

@@ -0,0 +1,37 @@
+import type { MultiModalContent } from '@lasercat/homogenaize';
+import { type ConversationEnvironment } from './environment';
+import type { Conversation, Message, TokenUsage } from './types';
+/**
+ * Checks if a message is currently streaming (has the streaming metadata flag).
+ */
+export declare function isStreamingMessage(message: Message): boolean;
+/**
+ * Gets the currently streaming message from a conversation, if any.
+ */
+export declare function getStreamingMessage(conversation: Conversation): Message | undefined;
+/**
+ * Creates a pending/streaming message placeholder and appends it to the conversation.
+ * Returns both the updated conversation and the ID of the new streaming message.
+ */
+export declare function appendStreamingMessage(conversation: Conversation, role: 'assistant' | 'user', metadata?: Record<string, unknown>, environment?: Partial<ConversationEnvironment>): {
+    conversation: Conversation;
+    messageId: string;
+};
+/**
+ * Updates the content of a streaming message.
+ * This replaces the existing content (use for accumulating streamed tokens).
+ */
+export declare function updateStreamingMessage(conversation: Conversation, messageId: string, content: string | MultiModalContent[], environment?: Partial<ConversationEnvironment>): Conversation;
+/**
+ * Marks a streaming message as complete, removing the streaming flag.
+ * Optionally adds token usage and additional metadata.
+ */
+export declare function finalizeStreamingMessage(conversation: Conversation, messageId: string, options?: {
+    tokenUsage?: TokenUsage;
+    metadata?: Record<string, unknown>;
+}, environment?: Partial<ConversationEnvironment>): Conversation;
+/**
+ * Cancels a streaming message by removing it from the conversation.
+ */
+export declare function cancelStreamingMessage(conversation: Conversation, messageId: string, environment?: Partial<ConversationEnvironment>): Conversation;
+//# sourceMappingURL=streaming.d.ts.map

package/dist/streaming.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"streaming.d.ts","sourceRoot":"","sources":["../src/streaming.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAE/D,OAAO,EACL,KAAK,uBAAuB,EAE7B,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAKjE;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAE5D;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,YAAY,GAAG,OAAO,GAAG,SAAS,CAEnF;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,YAAY,EAAE,YAAY,EAC1B,IAAI,EAAE,WAAW,GAAG,MAAM,EAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClC,WAAW,CAAC,EAAE,OAAO,CAAC,uBAAuB,CAAC,GAC7C;IAAE,YAAY,EAAE,YAAY,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAyBnD;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,YAAY,EAAE,YAAY,EAC1B,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,GAAG,iBAAiB,EAAE,EACrC,WAAW,CAAC,EAAE,OAAO,CAAC,uBAAuB,CAAC,GAC7C,YAAY,CAiCd;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,YAAY,EAAE,YAAY,EAC1B,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE;IACR,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC,EACD,WAAW,CAAC,EAAE,OAAO,CAAC,uBAAuB,CAAC,GAC7C,YAAY,CA4Cd;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,YAAY,EAAE,YAAY,EAC1B,SAAS,EAAE,MAAM,EACjB,WAAW,CAAC,EAAE,OAAO,CAAC,uBAAuB,CAAC,GAC7C,YAAY,CAqCd"}

package/dist/types.d.ts

@@ -0,0 +1,78 @@
+import type { MultiModalContent } from '@lasercat/homogenaize';
+export type MessageRole = 'user' | 'assistant' | 'system' | 'developer' | 'tool-use' | 'tool-result' | 'snapshot';
+export interface ToolCall {
+    id: string;
+    name: string;
+    arguments: unknown;
+}
+export interface ToolResult {
+    callId: string;
+    outcome: 'success' | 'error';
+    content: unknown;
+}
+export interface TokenUsage {
+    prompt: number;
+    completion: number;
+    total: number;
+}
+export interface MessageInput {
+    role: MessageRole;
+    content: string | MultiModalContent[];
+    metadata?: Record<string, unknown> | undefined;
+    hidden?: boolean | undefined;
+    toolCall?: ToolCall | undefined;
+    toolResult?: ToolResult | undefined;
+    tokenUsage?: TokenUsage | undefined;
+    /** Indicates if this message represents goal completion (assistant only) */
+    goalCompleted?: boolean | undefined;
+}
+export interface MessageJSON {
+    id: string;
+    role: MessageRole;
+    content: string | MultiModalContent[];
+    position: number;
+    createdAt: string;
+    metadata: Record<string, unknown>;
+    hidden: boolean;
+    toolCall?: ToolCall | undefined;
+    toolResult?: ToolResult | undefined;
+    tokenUsage?: TokenUsage | undefined;
+    /** Indicates if this message represents goal completion (assistant only) */
+    goalCompleted?: boolean | undefined;
+}
+export interface Message {
+    id: string;
+    role: MessageRole;
+    content: string | ReadonlyArray<MultiModalContent>;
+    position: number;
+    createdAt: string;
+    metadata: Readonly<Record<string, unknown>>;
+    hidden: boolean;
+    toolCall?: Readonly<ToolCall> | undefined;
+    toolResult?: Readonly<ToolResult> | undefined;
+    tokenUsage?: Readonly<TokenUsage> | undefined;
+    /** Indicates if this message represents goal completion (assistant only) */
+    goalCompleted?: boolean | undefined;
+}
+export type ConversationStatus = 'active' | 'archived' | 'deleted';
+export interface ConversationJSON {
+    id: string;
+    title?: string | undefined;
+    status: ConversationStatus;
+    metadata: Record<string, unknown>;
+    tags: string[];
+    messages: MessageJSON[];
+    createdAt: string;
+    updatedAt: string;
+}
+export interface Conversation {
+    id: string;
+    title?: string | undefined;
+    status: ConversationStatus;
+    metadata: Readonly<Record<string, unknown>>;
+    tags: ReadonlyArray<string>;
+    messages: ReadonlyArray<Message>;
+    createdAt: string;
+    updatedAt: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/utilities.d.ts

@@ -0,0 +1,79 @@
+import type { MultiModalContent } from '@lasercat/homogenaize';
+import type { Message, MessageJSON, ToolCall, ToolResult } from './types';
+/**
+ * Represents a paired tool call with its optional result.
+ */
+export interface ToolCallPair {
+    /** The tool call */
+    call: ToolCall;
+    /** The corresponding result, if available */
+    result?: ToolResult | undefined;
+}
+/**
+ * Pairs tool calls with their corresponding results from a list of messages.
+ *
+ * This is useful for UI rendering where tool calls and their results need
+ * to be displayed together. The function performs two passes:
+ * 1. Collects all tool results into a map by their callId
+ * 2. Pairs each tool call with its matching result (if any)
+ *
+ * @param messages - Array of messages that may contain tool calls and results
+ * @returns Array of tool call pairs, preserving the order of tool calls
+ *
+ * @example
+ * ```ts
+ * const pairs = pairToolCallsWithResults(conversation.messages);
+ * // pairs: [{ call: ToolCall, result?: ToolResult }, ...]
+ * ```
+ */
+export declare function pairToolCallsWithResults(messages: readonly MessageJSON[]): ToolCallPair[];
+/**
+ * Type-safe hasOwnProperty check.
+ * Narrows the type to include the checked property.
+ */
+export declare function hasOwnProperty<X extends object, Y extends PropertyKey>(obj: X, prop: Y): obj is X & Record<Y, unknown>;
+/**
+ * Casts a value to its readonly variant.
+ * Used to enforce immutability at the type level.
+ */
+export declare function toReadonly<T>(value: T): Readonly<T>;
+/**
+ * Creates an immutable Message from a JSON representation.
+ * Deep copies nested objects and arrays to ensure immutability.
+ */
+export declare function createMessage(props: MessageJSON): Message;
+/**
+ * Converts content to a multi-modal array format.
+ * Wraps strings in a text content object, normalizes single items to arrays.
+ */
+export declare function toMultiModalArray(input: string | MultiModalContent | MultiModalContent[]): MultiModalContent[];
+/**
+ * Normalizes content to either a string or multi-modal array.
+ * Single MultiModalContent items are wrapped in an array.
+ */
+export declare function normalizeContent(content?: string | MultiModalContent | MultiModalContent[]): string | MultiModalContent[] | undefined;
+/**
+ * Converts an immutable Message to a mutable JSON representation.
+ * Creates deep copies of all nested objects.
+ */
+export declare function messageToJSON(message: Message): MessageJSON;
+/**
+ * Extracts the content parts from a message as a multi-modal array.
+ * String content is converted to a single text part.
+ */
+export declare function messageParts(message: Message): ReadonlyArray<MultiModalContent>;
+/**
+ * Extracts all text content from a message, joined by the specified separator.
+ * Non-text parts are excluded from the result.
+ */
+export declare function messageText(message: Message, joiner?: string): string;
+/**
+ * Checks if a message contains any image content.
+ */
+export declare function messageHasImages(message: Message): boolean;
+/**
+ * Converts a message to a string representation.
+ * Images are rendered as markdown image syntax.
+ */
+export declare function messageToString(message: Message): string;
+//# sourceMappingURL=utilities.d.ts.map

package/dist/utilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utilities.d.ts","sourceRoot":"","sources":["../src/utilities.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAG/D,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE1E;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,oBAAoB;IACpB,IAAI,EAAE,QAAQ,CAAC;IACf,6CAA6C;IAC7C,MAAM,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,SAAS,WAAW,EAAE,GAC/B,YAAY,EAAE,CAsBhB;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,WAAW,EACpE,GAAG,EAAE,CAAC,EACN,IAAI,EAAE,CAAC,GACN,GAAG,IAAI,CAAC,GAAG,MAAM,CAAC,CAAC,EAAE,OAAO,CAAC,CAE/B;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAEnD;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAoBzD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,MAAM,GAAG,iBAAiB,GAAG,iBAAiB,EAAE,GACtD,iBAAiB,EAAE,CAGrB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,CAAC,EAAE,MAAM,GAAG,iBAAiB,GAAG,iBAAiB,EAAE,GACzD,MAAM,GAAG,iBAAiB,EAAE,GAAG,SAAS,CAI1C;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,WAAW,CAc3D;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,aAAa,CAAC,iBAAiB,CAAC,CAO/E;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,GAAE,MAAe,GAAG,MAAM,CAM7E;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAE1D;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CASxD"}

package/dist/with-conversation.d.ts

@@ -0,0 +1,125 @@
+import type { MultiModalContent } from '@lasercat/homogenaize';
+import type { Conversation, Message, MessageInput, TokenUsage } from './types';
+/**
+ * A mutable draft wrapper around a conversation.
+ * Methods return the draft for chaining and mutate the internal state.
+ *
+ * @example
+ * ```ts
+ * const result = withConversation(conversation, (draft) => {
+ *   draft
+ *     .appendSystemMessage('You are helpful.')
+ *     .appendUserMessage('Hello!')
+ *     .appendAssistantMessage('Hi there!');
+ * });
+ * ```
+ */
+export interface ConversationDraft {
+    /** The current immutable conversation value. */
+    readonly value: Conversation;
+    /**
+     * Appends one or more messages to the conversation.
+     * @param inputs - Message inputs to append.
+     */
+    appendMessages: (...inputs: MessageInput[]) => ConversationDraft;
+    /**
+     * Appends a user message to the conversation.
+     * @param content - Text or multi-modal content.
+     * @param metadata - Optional metadata to attach to the message.
+     */
+    appendUserMessage: (content: MessageInput['content'], metadata?: Record<string, unknown>) => ConversationDraft;
+    /**
+     * Appends an assistant message to the conversation.
+     * @param content - Text or multi-modal content.
+     * @param metadata - Optional metadata to attach to the message.
+     */
+    appendAssistantMessage: (content: MessageInput['content'], metadata?: Record<string, unknown>) => ConversationDraft;
+    /**
+     * Appends a system message to the conversation.
+     * @param content - The system message content.
+     * @param metadata - Optional metadata to attach to the message.
+     */
+    appendSystemMessage: (content: string, metadata?: Record<string, unknown>) => ConversationDraft;
+    /**
+     * Prepends a system message at position 0, renumbering existing messages.
+     * @param content - The system message content.
+     * @param metadata - Optional metadata to attach to the message.
+     */
+    prependSystemMessage: (content: string, metadata?: Record<string, unknown>) => ConversationDraft;
+    /**
+     * Replaces the first system message, or prepends if none exists.
+     * @param content - The new system message content.
+     * @param metadata - Optional metadata (uses original if not provided).
+     */
+    replaceSystemMessage: (content: string, metadata?: Record<string, unknown>) => ConversationDraft;
+    /**
+     * Collapses all system messages into the first one, deduplicating content.
+     */
+    collapseSystemMessages: () => ConversationDraft;
+    /**
+     * Redacts a message at the given position, replacing its content.
+     * @param position - The message position to redact.
+     * @param placeholder - Replacement text (default: '[REDACTED]').
+     */
+    redactMessageAtPosition: (position: number, placeholder?: string) => ConversationDraft;
+    /**
+     * Appends a streaming message placeholder.
+     * Returns the draft and the new message ID for subsequent updates.
+     * @param role - The role of the streaming message ('assistant' or 'user').
+     * @param metadata - Optional metadata to attach to the message.
+     */
+    appendStreamingMessage: (role: 'assistant' | 'user', metadata?: Record<string, unknown>) => {
+        draft: ConversationDraft;
+        messageId: string;
+    };
+    /**
+     * Updates the content of a streaming message.
+     * @param messageId - The ID of the streaming message to update.
+     * @param content - The new content (replaces existing content).
+     */
+    updateStreamingMessage: (messageId: string, content: string | MultiModalContent[]) => ConversationDraft;
+    /**
+     * Finalizes a streaming message, removing the streaming flag.
+     * @param messageId - The ID of the streaming message to finalize.
+     * @param options - Optional token usage and additional metadata.
+     */
+    finalizeStreamingMessage: (messageId: string, options?: {
+        tokenUsage?: TokenUsage;
+        metadata?: Record<string, unknown>;
+    }) => ConversationDraft;
+    /**
+     * Cancels a streaming message by removing it from the conversation.
+     * @param messageId - The ID of the streaming message to cancel.
+     */
+    cancelStreamingMessage: (messageId: string) => ConversationDraft;
+    /**
+     * Truncates the conversation to keep only messages from position onwards.
+     * @param position - The starting position to keep.
+     * @param options - Options for preserving system messages.
+     */
+    truncateFromPosition: (position: number, options?: {
+        preserveSystemMessages?: boolean;
+    }) => ConversationDraft;
+    /**
+     * Truncates the conversation to fit within a token limit.
+     * Removes oldest messages first while preserving system messages and optionally the last N messages.
+     * @param maxTokens - Maximum token count to target.
+     * @param estimateTokens - Function to estimate tokens per message.
+     * @param options - Options for preserving system messages and last N messages.
+     */
+    truncateToTokenLimit: (maxTokens: number, estimateTokens: (message: Message) => number, options?: {
+        preserveSystemMessages?: boolean;
+        preserveLastN?: number;
+    }) => ConversationDraft;
+}
+/**
+ * Executes a function with a mutable draft and returns the final conversation.
+ * Supports both synchronous and asynchronous operations.
+ */
+export declare function withConversation(conversation: Conversation, fn: (draft: ConversationDraft) => void | Promise<void>): Conversation | Promise<Conversation>;
+/**
+ * Applies a series of transformation functions to a conversation.
+ * Each function receives the result of the previous one.
+ */
+export declare function pipeConversation(conversation: Conversation, ...fns: Array<(conversation: Conversation) => Conversation>): Conversation;
+//# sourceMappingURL=with-conversation.d.ts.map

package/dist/with-conversation.d.ts.map

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

package/package.json

@@ -0,0 +1,113 @@
+{
+  "name": "conversationalist",
+  "version": "0.0.1",
+  "description": "A TypeScript library for managing AI conversation state",
+  "keywords": [
+    "conversation",
+    "ai",
+    "chat",
+    "llm",
+    "typescript"
+  ],
+  "homepage": "https://github.com/stevekinney/conversationalist#readme",
+  "bugs": {
+    "url": "https://github.com/stevekinney/conversationalist/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stevekinney/conversationalist.git"
+  },
+  "license": "MIT",
+  "author": "Steve Kinney <hello@stevekinney.net>",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./openai": {
+      "types": "./dist/adapters/openai/index.d.ts",
+      "import": "./dist/adapters/openai/index.js"
+    },
+    "./anthropic": {
+      "types": "./dist/adapters/anthropic/index.d.ts",
+      "import": "./dist/adapters/anthropic/index.js"
+    },
+    "./gemini": {
+      "types": "./dist/adapters/gemini/index.d.ts",
+      "import": "./dist/adapters/gemini/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "bun run scripts/build.ts",
+    "dev": "bun --watch run src/index.ts",
+    "format": "prettier --write \"**/*.{ts,tsx,js,jsx,json,md}\"",
+    "format:check": "prettier --check \"**/*.{ts,tsx,js,jsx,json,md}\"",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "prepare": "husky",
+    "prepublishOnly": "bun run validate && bun run build",
+    "start": "bun run src/index.ts",
+    "test": "bun test",
+    "test:coverage": "bun test --coverage",
+    "typecheck": "tsc --noEmit",
+    "validate": "bun run lint && bun run typecheck && bun run test"
+  },
+  "lint-staged": {
+    "src/**/*.{js,ts,tsx,jsx,mjs,cjs}": [
+      "eslint --fix",
+      "prettier --write"
+    ],
+    "scripts/**/*.{js,ts,tsx,jsx,mjs,cjs}": [
+      "eslint --fix",
+      "prettier --write"
+    ],
+    "**/*.{json,md,css,scss}": [
+      "prettier --write"
+    ],
+    "package.json": [
+      "sort-package-json"
+    ]
+  },
+  "dependencies": {
+    "change-case": "^5.4.4",
+    "zod": "^4.2.1"
+  },
+  "devDependencies": {
+    "@eslint/eslintrc": "^3.3.3",
+    "@eslint/js": "^9.39.2",
+    "@eslint/markdown": "^7.5.1",
+    "@lasercat/homogenaize": "^1.2.41",
+    "@types/bun": "^1.3.5",
+    "@typescript-eslint/eslint-plugin": "^8.50.0",
+    "@typescript-eslint/parser": "^8.50.0",
+    "chalk": "^5.6.2",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-import-resolver-typescript": "^4.4.4",
+    "eslint-plugin-eslint-comments": "^3.2.0",
+    "eslint-plugin-import": "^2.32.0",
+    "eslint-plugin-prettier": "^5.5.4",
+    "eslint-plugin-promise": "^7.2.1",
+    "eslint-plugin-regexp": "^2.10.0",
+    "eslint-plugin-simple-import-sort": "^12.1.1",
+    "eslint-plugin-unicorn": "^62.0.0",
+    "eslint-plugin-unused-imports": "^4.3.0",
+    "globals": "^16.5.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.2.7",
+    "prettier": "^3.7.4",
+    "sort-package-json": "^3.6.0",
+    "typescript-eslint": "^8.50.0"
+  },
+  "engines": {
+    "bun": ">=1.3.0"
+  }
+}