@simulacra-ai/core 0.0.1

package/dist/context-transformers/tool-context-transformer.js

@@ -0,0 +1,52 @@
+/**
+ * Context transformer that removes unreferenced tool invocations from message history.
+ *
+ * Filters out tool content blocks that don't have a corresponding tool_result,
+ * reducing context size when tools were invoked but their results are no longer
+ * relevant to the conversation.
+ */
+export class ToolContextTransformer {
+    /**
+     * Transforms prompt messages by removing unreferenced tool invocations.
+     *
+     * @param messages - The messages to transform.
+     * @returns A promise that resolves to the transformed messages.
+     */
+    transform_prompt(messages) {
+        const tool_ids = [];
+        const message_context = [];
+        for (const message of messages.toReversed()) {
+            tool_ids.push(...message.content.filter((c) => c.type === "tool_result").map((c) => c.tool_request_id));
+            const cleaned_message = {
+                ...message,
+                content: message.content.filter((c) => c.type !== "tool" || tool_ids.includes(c.tool_request_id)),
+            };
+            if (cleaned_message.content.length) {
+                message_context.unshift(cleaned_message);
+            }
+            else if (message.role === "assistant") {
+                message_context.unshift({
+                    ...message,
+                    content: [{ type: "text", text: "" }],
+                });
+            }
+            else if (message.role === "user") {
+                message_context.unshift({
+                    ...message,
+                    content: [{ type: "text", text: "" }],
+                });
+            }
+        }
+        return Promise.resolve(message_context);
+    }
+    /**
+     * Returns the completion message unchanged.
+     *
+     * @param message - The assistant message to pass through.
+     * @returns A promise that resolves to the same message.
+     */
+    transform_completion(message) {
+        return Promise.resolve(message);
+    }
+}
+//# sourceMappingURL=tool-context-transformer.js.map

package/dist/context-transformers/tool-context-transformer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-context-transformer.js","sourceRoot":"","sources":["../../src/context-transformers/tool-context-transformer.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;AACH,MAAM,OAAO,sBAAsB;IACjC;;;;;OAKG;IACH,gBAAgB,CAAC,QAAmB;QAClC,MAAM,QAAQ,GAAa,EAAE,CAAC;QAC9B,MAAM,eAAe,GAAc,EAAE,CAAC;QAEtC,KAAK,MAAM,OAAO,IAAI,QAAQ,CAAC,UAAU,EAAE,EAAE,CAAC;YAC5C,QAAQ,CAAC,IAAI,CACX,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,aAAa,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,eAAe,CAAC,CACzF,CAAC;YACF,MAAM,eAAe,GAAG;gBACtB,GAAG,OAAO;gBACV,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,MAAM,CAC7B,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,IAAI,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,eAAe,CAAC,CACjE;aACF,CAAC;YACF,IAAI,eAAe,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;gBACnC,eAAe,CAAC,OAAO,CAAC,eAA0B,CAAC,CAAC;YACtD,CAAC;iBAAM,IAAI,OAAO,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;gBACxC,eAAe,CAAC,OAAO,CAAC;oBACtB,GAAG,OAAO;oBACV,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;iBAC3B,CAAC,CAAC;YAChB,CAAC;iBAAM,IAAI,OAAO,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;gBACnC,eAAe,CAAC,OAAO,CAAC;oBACtB,GAAG,OAAO;oBACV,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;iBAC3B,CAAC,CAAC;YAChB,CAAC;QACH,CAAC;QACD,OAAO,OAAO,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC;IAC1C,CAAC;IAED;;;;;OAKG;IACH,oBAAoB,CAAC,OAAyB;QAC5C,OAAO,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAClC,CAAC;CACF"}

package/dist/context-transformers/types.d.ts

@@ -0,0 +1,65 @@
+import { AssistantMessage, Message } from "../conversations/index.ts";
+/**
+ * The active checkpoint state for a conversation.
+ */
+export interface CheckpointState {
+    /** The ID of the last message included in the checkpoint. */
+    message_id: string;
+    /** The condensed summary produced by the checkpoint model call. */
+    summary: string;
+}
+/**
+ * Additional context passed to transformers alongside messages.
+ */
+export interface TransformContext {
+    /** The active checkpoint, if any. */
+    checkpoint?: CheckpointState;
+}
+/**
+ * Interface for transforming conversation context before and after model requests.
+ *
+ * Context transformers can modify messages before they are sent to the model
+ * and transform assistant responses before they are added to conversation history.
+ */
+export interface ContextTransformer {
+    /**
+     * Transforms the prompt messages before sending to the model.
+     *
+     * @param messages - The messages to transform.
+     * @param context - Additional context such as checkpoint state.
+     * @returns A promise that resolves to the transformed messages.
+     */
+    transform_prompt(messages: Message[], context?: TransformContext): Promise<Message[]>;
+    /**
+     * Transforms the assistant's completion message before adding to history.
+     *
+     * @param message - The assistant message to transform.
+     * @returns A promise that resolves to the transformed message.
+     */
+    transform_completion(message: AssistantMessage): Promise<AssistantMessage>;
+}
+/**
+ * Interface for provider-level context transformers.
+ *
+ * Provider transformers normalize provider-specific quirks at the wire level.
+ * They run before conversation-level transformers and do not receive
+ * conversation context (checkpoints, etc.). Both methods are optional —
+ * most provider transformers only need one direction.
+ */
+export interface ProviderContextTransformer {
+    /**
+     * Transforms prompt messages before sending to the model.
+     *
+     * @param messages - The messages to transform.
+     * @returns A promise that resolves to the transformed messages.
+     */
+    transform_prompt?(messages: Message[]): Promise<Message[]>;
+    /**
+     * Transforms the assistant's completion message before adding to history.
+     *
+     * @param message - The assistant message to transform.
+     * @returns A promise that resolves to the transformed message.
+     */
+    transform_completion?(message: AssistantMessage): Promise<AssistantMessage>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/context-transformers/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/context-transformers/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAC;AAEtE;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,6DAA6D;IAC7D,UAAU,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,qCAAqC;IACrC,UAAU,CAAC,EAAE,eAAe,CAAC;CAC9B;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;;OAMG;IACH,gBAAgB,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IAEtF;;;;;OAKG;IACH,oBAAoB,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;CAC5E;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,0BAA0B;IACzC;;;;;OAKG;IACH,gBAAgB,CAAC,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IAE3D;;;;;OAKG;IACH,oBAAoB,CAAC,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;CAC7E"}

package/dist/context-transformers/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/context-transformers/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/context-transformers/types.ts"],"names":[],"mappings":""}

package/dist/conversations/conversation.d.ts

@@ -0,0 +1,146 @@
+import type { CheckpointState, ContextTransformer } from "../context-transformers/types.ts";
+import type { CheckpointConfig, SummarizationStrategy } from "../checkpoints/types.ts";
+import type { ToolClass } from "../tools/types.ts";
+import type { Policy } from "../policies/types.ts";
+import { ConversationEvents, ConversationState, Message, ModelProvider, PromptRequestData, UserContent } from "./types.ts";
+/**
+ * Manages a conversation with a language model.
+ *
+ * The Conversation class handles message exchange, tool execution coordination,
+ * event emission, and state management for interactions with language models.
+ */
+export declare class Conversation {
+    #private;
+    /**
+     * Creates a new conversation instance.
+     *
+     * @param provider - The model provider for executing requests.
+     * @param policy - The policy for controlling request execution (default: retry + rate limiting).
+     * @param context_transformer - Transformer for modifying messages before sending (default: noop).
+     * @param summarization_strategy - Strategy for generating checkpoint summaries (default: DefaultSummarizationStrategy).
+     */
+    constructor(provider: ModelProvider, policy?: Policy, context_transformer?: ContextTransformer, summarization_strategy?: SummarizationStrategy);
+    /**
+     * The unique identifier for this conversation.
+     */
+    get id(): string;
+    set id(value: string);
+    /**
+     * The current state of the conversation.
+     */
+    get state(): ConversationState;
+    /**
+     * The system prompt for this conversation.
+     */
+    get system(): string | undefined;
+    set system(value: string | undefined);
+    /**
+     * The collection of tools available to the model in this conversation.
+     */
+    get toolkit(): Readonly<ToolClass[]>;
+    set toolkit(value: ToolClass[]);
+    /**
+     * The conversation message history.
+     */
+    get messages(): Readonly<Readonly<Message>[]>;
+    /**
+     * The most recent checkpoint state, if any.
+     */
+    get checkpoint_state(): Readonly<CheckpointState> | undefined;
+    set checkpoint_state(value: CheckpointState | undefined);
+    /**
+     * Whether this conversation is a checkpoint session.
+     */
+    get is_checkpoint(): boolean;
+    /**
+     * Disposes the conversation and releases all resources.
+     *
+     * This method is called automatically when using the `using` keyword.
+     * Emits a dispose event and transitions to the disposed state.
+     */
+    [Symbol.dispose](): void;
+    /**
+     * Sends a text prompt to the model.
+     *
+     * @param prompt - The text prompt to send.
+     * @returns A promise that resolves with the request data, or undefined if cancelled.
+     */
+    prompt(prompt: string): Promise<PromptRequestData | undefined>;
+    /**
+     * Sends a message with custom content to the model.
+     *
+     * @param contents - The content blocks to include in the message.
+     * @returns A promise that resolves with the request data, or undefined if cancelled.
+     */
+    send_message(contents: UserContent[]): Promise<PromptRequestData | undefined>;
+    /**
+     * Registers a one-time event listener.
+     *
+     * @template E - The event name type.
+     * @param event_name - The name of the event to listen for.
+     * @param listener - The callback function to invoke when the event occurs.
+     */
+    once<E extends keyof ConversationEvents>(event_name: E, listener: E extends keyof ConversationEvents ? (...arg: ConversationEvents[E]) => void : never): void;
+    /**
+     * Registers a persistent event listener.
+     *
+     * @template E - The event name type.
+     * @param event_name - The name of the event to listen for.
+     * @param listener - The callback function to invoke when the event occurs.
+     */
+    on<E extends keyof ConversationEvents>(event_name: E, listener: E extends keyof ConversationEvents ? (...arg: ConversationEvents[E]) => void : never): void;
+    /**
+     * Removes an event listener.
+     *
+     * @template E - The event name type.
+     * @param event_name - The name of the event.
+     * @param listener - The callback function to remove.
+     */
+    off<E extends keyof ConversationEvents>(event_name: E, listener: E extends keyof ConversationEvents ? (...arg: ConversationEvents[E]) => void : never): void;
+    /**
+     * Cancels an in-progress model response.
+     *
+     * Transitions the conversation to the "stopping" state, which triggers
+     * cancellation of the underlying request.
+     */
+    cancel_response(): void;
+    /**
+     * Clears all messages from the conversation history.
+     *
+     * Can only be called when the conversation is idle.
+     */
+    clear(): void;
+    /**
+     * Loads messages into the conversation history.
+     *
+     * @param messages - The messages to load.
+     */
+    load(messages: Message[]): void;
+    /**
+     * Creates a child conversation that inherits configuration from this conversation.
+     *
+     * Child events are propagated to the parent as "child_event" events.
+     *
+     * @param fork_session - Whether to copy the current message history to the child.
+     * @param id - Optional custom ID for the child conversation.
+     * @param system_prompt - Optional system prompt override for the child.
+     * @param is_checkpoint - Whether this child is a checkpoint summarization session.
+     * @returns The newly created child conversation.
+     */
+    spawn_child(fork_session?: boolean, id?: string, system_prompt?: string, is_checkpoint?: boolean): Conversation;
+    /**
+     * Creates a checkpoint summarizing the conversation so far.
+     *
+     * Spawns an ephemeral child conversation, sends the checkpoint prompt,
+     * and stores the resulting summary as the new checkpoint state.
+     *
+     * Requires a CheckpointContextTransformer (or composite that includes one)
+     * in the context transformer pipeline for the checkpoint state to take effect
+     * on subsequent prompts.
+     *
+     * @param config - Optional checkpoint configuration.
+     * @returns The new checkpoint state.
+     */
+    checkpoint(config?: CheckpointConfig): Promise<CheckpointState>;
+}
+//# sourceMappingURL=conversation.d.ts.map

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

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