@simulacra-ai/core 0.0.1

package/README.md

@@ -0,0 +1,232 @@
+# Simulacra Core
+
+Core conversation engine, tool system, workflow management, policies, and context transformers for Simulacra.
+
+## Installation
+
+```bash
+npm install @simulacra-ai/core
+```
+
+## Quick Start
+
+```typescript
+import { Conversation } from "@simulacra-ai/core";
+import { AnthropicProvider } from "@simulacra-ai/anthropic";
+import Anthropic from "@anthropic-ai/sdk";
+
+const provider = new AnthropicProvider(new Anthropic(), { model: MODEL_NAME });
+const conversation = new Conversation(provider);
+
+await conversation.prompt("Hello!");
+console.log(conversation.messages);
+```
+
+## Conversation
+
+`Conversation` is a concrete class that accepts a `ModelProvider` at construction time. Provider packages (`@simulacra-ai/anthropic`, `@simulacra-ai/openai`, `@simulacra-ai/google`) supply `ModelProvider` implementations. All model-specific configuration (model name, token limits, thinking, caching) lives in the provider, not the conversation.
+
+```typescript
+const conversation = new Conversation(provider);
+conversation.system = "You are a helpful assistant.";
+
+const result = await conversation.prompt("Hello!");
+console.log(conversation.messages);
+```
+
+Properties include `id`, `state`, `system`, `toolkit`, and `messages`.
+
+Methods include `prompt(text)`, `send_message(contents)`, `cancel_response()`, `clear()`, `load(messages)`, `spawn_child(fork?, id?, system?, is_checkpoint?)`, and `checkpoint(config?)`.
+
+State transitions flow: `idle` → `awaiting_response` → `streaming_response` → `idle` (or `stopping` → `idle` on cancel, `disposed` on disposal).
+
+### Conversation Events
+
+Key events for streaming: `message_start`, `content_update`, `message_complete`. For tool use: `content_start`, `content_complete`. For lifecycle: `state_change`, `dispose`.
+
+See the [developer guide](DEVELOPER_GUIDE.md#events) for the full event reference.
+
+## Tool System
+
+Tools are implemented via the `ToolClass` interface:
+
+```typescript
+import type {
+  ToolClass,
+  ToolContext,
+  ToolDefinition,
+  ToolSuccessResult,
+  ToolErrorResult,
+} from "@simulacra-ai/core";
+
+class SearchTool {
+  #context: ToolContext;
+
+  static get_definition(): ToolDefinition {
+    return {
+      name: "search",
+      description: "Search the web for information",
+      parameters: [
+        { name: "query", type: "string", required: true, description: "Search query" },
+        { name: "max_results", type: "number", required: false, default: 5 },
+      ],
+      parallelizable: true,
+    };
+  }
+
+  constructor(context: ToolContext) {
+    this.#context = context;
+  }
+
+  async execute(params: {
+    query: string;
+    max_results?: number;
+  }): Promise<ToolSuccessResult | ToolErrorResult> {
+    const results = await doSearch(params.query, params.max_results ?? 5);
+    return { result: true, ...results };
+  }
+}
+
+conversation.toolkit = [SearchTool as ToolClass];
+```
+
+### ToolDefinition
+
+```typescript
+interface ToolDefinition {
+  name: string;
+  description: string;
+  parameters: ToolParameterDefinition[];
+  parallelizable?: boolean; // default: true
+}
+```
+
+### ToolContext
+
+Every tool instance receives `{ conversation, workflow }` at construction time, plus any application-specific data passed via `context_data`.
+
+### Parameter Types
+
+`ToolParameterDefinition` supports: `string`, `number`, `boolean`, `object` (with nested `properties`), `array` (with `items`). String parameters support `enum` arrays. All types have `name`, `description?`, `required?`, and `default?`.
+
+### Parallel Execution
+
+The `parallelizable` flag (default `true`) controls batching in the workflow engine:
+
+- **`true` (default)**: the workflow can batch this tool call with other parallelizable calls into `Promise.all`
+- **`false`**: acts as a barrier; the workflow executes this tool alone, waiting for it to complete before continuing
+
+This allows tools with side effects or ordering requirements to be marked as sequential while allowing read-only tools to run concurrently.
+
+## Workflows
+
+`WorkflowManager` is the agentic loop. It listens for tool-use responses, executes tools, sends results back, and repeats until the model produces a final response.
+
+```typescript
+import { WorkflowManager } from "@simulacra-ai/core";
+
+const manager = new WorkflowManager(conversation);
+await conversation.prompt("Use my tools to answer this question.");
+```
+
+For lower-level control, `Workflow` can be used directly — see the [developer guide](DEVELOPER_GUIDE.md#workflows).
+
+Key events: `workflow_end` (loop finished with reason `complete` | `cancel` | `error`), `workflow_update` (tool results sent), `state_change`. See the [developer guide](DEVELOPER_GUIDE.md#events) for the full event reference.
+
+## Policies
+
+Policies wrap the LLM request with cross-cutting concerns. All policies implement `execute(cancellation_token, fn, ...args)`.
+
+### RetryPolicy
+
+`RetryPolicy` retries failed requests with exponential backoff.
+
+```typescript
+import { RetryPolicy } from "@simulacra-ai/core";
+
+const policy = new RetryPolicy({
+  max_attempts: 3,
+  initial_backoff_ms: 1000,
+  backoff_factor: 2,
+  retryable: (error) => error.error?.status === 429, // optional filter
+});
+```
+
+### RateLimitPolicy
+
+`RateLimitPolicy` limits requests per time window. Pass it to the conversation constructor, then call `attach()` to subscribe to events.
+
+```typescript
+import { Conversation, RateLimitPolicy } from "@simulacra-ai/core";
+
+const policy = new RateLimitPolicy({ limit: 10, period_ms: 60_000 });
+const conversation = new Conversation(provider, policy);
+policy.attach(conversation);
+```
+
+### TokenLimitPolicy
+
+`TokenLimitPolicy` limits tokens per time window. Like `RateLimitPolicy`, it requires both constructor injection and `attach()`.
+
+```typescript
+import { Conversation, TokenLimitPolicy } from "@simulacra-ai/core";
+
+const policy = new TokenLimitPolicy({
+  period_ms: 60_000,
+  total_tokens_per_period: 120_000,
+});
+const conversation = new Conversation(provider, policy);
+policy.attach(conversation);
+```
+
+### CompositePolicy
+
+`CompositePolicy` chains multiple policies together.
+
+```typescript
+import { CompositePolicy } from "@simulacra-ai/core";
+
+const policy = new CompositePolicy(
+  new RateLimitPolicy({ limit: 10, period_ms: 60_000 }),
+  new RetryPolicy({ max_attempts: 3, initial_backoff_ms: 1000, backoff_factor: 2 }),
+);
+```
+
+## Context Transformers
+
+Context transformers modify messages at two points: before sending (`transform_prompt`) and after receiving (`transform_completion`).
+
+By default, `Conversation` uses `ToolContextTransformer` and `CheckpointContextTransformer`. Pass a custom transformer to override.
+
+### ToolContextTransformer (default)
+
+Removes orphaned tool calls that lack corresponding tool results, preventing provider errors when tool execution was interrupted.
+
+### CheckpointContextTransformer (default)
+
+Replaces pre-checkpoint messages with the checkpoint summary, reducing context size while preserving conversation continuity. See [Checkpoints](DEVELOPER_GUIDE.md#checkpoints) in the developer guide.
+
+### CompositeContextTransformer
+
+Chains multiple transformers sequentially.
+
+### NoopContextTransformer
+
+Pass-through that disables all conversation-level transformations.
+
+### Provider Context Transformers
+
+Model providers can bundle their own transformers via `context_transformers`. These run before conversation-level transformers and handle provider-specific quirks automatically. The conversation reads them fresh on every request, supporting runtime provider swaps.
+
+See the [developer guide](DEVELOPER_GUIDE.md#provider-context-transformers) for the `ProviderContextTransformer` interface.
+
+## Utilities
+
+- **`TokenTracker`**: attach to a conversation to accumulate input/output token counts across requests
+- **`CancellationTokenSource` / `CancellationToken`**: cooperative cancellation for async operations
+- **`sleep(ms, cancellationToken?)`**: cancellable delay
+- **`deep_merge(original, supplemental)`**: recursive object merge
+
+## License
+
+MIT

package/dist/checkpoints/default-summarization-strategy.d.ts

@@ -0,0 +1,13 @@
+import type { Message } from "../conversations/types.ts";
+import type { SummarizationContext, SummarizationStrategy } from "./types.ts";
+/**
+ * Default summarization strategy for checkpoints.
+ *
+ * Serializes the conversation context into a structured text block and appends
+ * an instruction asking the model to produce a condensed summary.
+ */
+export declare class DefaultSummarizationStrategy implements SummarizationStrategy {
+    #private;
+    build_prompt(context: SummarizationContext): Message[];
+}
+//# sourceMappingURL=default-summarization-strategy.d.ts.map

package/dist/checkpoints/default-summarization-strategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"default-summarization-strategy.d.ts","sourceRoot":"","sources":["../../src/checkpoints/default-summarization-strategy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,KAAK,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAE9E;;;;;GAKG;AACH,qBAAa,4BAA6B,YAAW,qBAAqB;;IACxE,YAAY,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,EAAE;CA8DvD"}

package/dist/checkpoints/default-summarization-strategy.js

@@ -0,0 +1,63 @@
+/**
+ * Default summarization strategy for checkpoints.
+ *
+ * Serializes the conversation context into a structured text block and appends
+ * an instruction asking the model to produce a condensed summary.
+ */
+export class DefaultSummarizationStrategy {
+    build_prompt(context) {
+        const sections = [];
+        if (context.previous_checkpoint) {
+            sections.push(`## Previous Checkpoint Summary\n${context.previous_checkpoint.summary}`);
+        }
+        if (context.system) {
+            sections.push(`## System Prompt\n${context.system}`);
+        }
+        if (context.messages.length > 0) {
+            sections.push(`## Conversation\n${this.#serialize_messages(context.messages)}`);
+        }
+        sections.push([
+            "## Instructions",
+            "Summarize the above conversation concisely. Preserve:",
+            "- Key decisions and their rationale",
+            "- Current state of any in-progress work",
+            "- Important facts, names, and values established",
+            "- Tool outcomes",
+            "- Any explicit user preferences or instructions",
+            "",
+            "Omit redundant back-and-forth and superseded plans.",
+            "Format as a structured briefing the model can use to continue the conversation seamlessly.",
+        ].join("\n"));
+        return [
+            {
+                role: "user",
+                content: [{ type: "text", text: sections.join("\n\n") }],
+            },
+        ];
+    }
+    #serialize_messages(messages) {
+        return messages
+            .map((m) => {
+            const role = m.role === "user" ? "User" : "Assistant";
+            const parts = m.content
+                .map((c) => {
+                switch (c.type) {
+                    case "text":
+                        return c.text;
+                    case "thinking":
+                        return `[Thinking: ${c.thought}]`;
+                    case "tool":
+                        return `[Called tool: ${c.tool}]`;
+                    case "tool_result":
+                        return `[Tool ${c.tool} returned: ${JSON.stringify(c.result)}]`;
+                    default:
+                        return undefined;
+                }
+            })
+                .filter(Boolean);
+            return `${role}: ${parts.join("\n")}`;
+        })
+            .join("\n\n");
+    }
+}
+//# sourceMappingURL=default-summarization-strategy.js.map

package/dist/checkpoints/default-summarization-strategy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"default-summarization-strategy.js","sourceRoot":"","sources":["../../src/checkpoints/default-summarization-strategy.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,MAAM,OAAO,4BAA4B;IACvC,YAAY,CAAC,OAA6B;QACxC,MAAM,QAAQ,GAAa,EAAE,CAAC;QAE9B,IAAI,OAAO,CAAC,mBAAmB,EAAE,CAAC;YAChC,QAAQ,CAAC,IAAI,CAAC,mCAAmC,OAAO,CAAC,mBAAmB,CAAC,OAAO,EAAE,CAAC,CAAC;QAC1F,CAAC;QAED,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;YACnB,QAAQ,CAAC,IAAI,CAAC,qBAAqB,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;QACvD,CAAC;QAED,IAAI,OAAO,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAChC,QAAQ,CAAC,IAAI,CAAC,oBAAoB,IAAI,CAAC,mBAAmB,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;QAClF,CAAC;QAED,QAAQ,CAAC,IAAI,CACX;YACE,iBAAiB;YACjB,uDAAuD;YACvD,qCAAqC;YACrC,yCAAyC;YACzC,kDAAkD;YAClD,iBAAiB;YACjB,iDAAiD;YACjD,EAAE;YACF,qDAAqD;YACrD,4FAA4F;SAC7F,CAAC,IAAI,CAAC,IAAI,CAAC,CACb,CAAC;QAEF,OAAO;YACL;gBACE,IAAI,EAAE,MAAM;gBACZ,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;aACzD;SACF,CAAC;IACJ,CAAC;IAED,mBAAmB,CAAC,QAA4B;QAC9C,OAAO,QAAQ;aACZ,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;YACT,MAAM,IAAI,GAAG,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC;YACtD,MAAM,KAAK,GAAG,CAAC,CAAC,OAAO;iBACpB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;gBACT,QAAQ,CAAC,CAAC,IAAI,EAAE,CAAC;oBACf,KAAK,MAAM;wBACT,OAAO,CAAC,CAAC,IAAI,CAAC;oBAChB,KAAK,UAAU;wBACb,OAAO,cAAc,CAAC,CAAC,OAAO,GAAG,CAAC;oBACpC,KAAK,MAAM;wBACT,OAAO,iBAAiB,CAAC,CAAC,IAAI,GAAG,CAAC;oBACpC,KAAK,aAAa;wBAChB,OAAO,SAAS,CAAC,CAAC,IAAI,cAAc,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;oBAClE;wBACE,OAAO,SAAS,CAAC;gBACrB,CAAC;YACH,CAAC,CAAC;iBACD,MAAM,CAAC,OAAO,CAAC,CAAC;YACnB,OAAO,GAAG,IAAI,KAAK,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACxC,CAAC,CAAC;aACD,IAAI,CAAC,MAAM,CAAC,CAAC;IAClB,CAAC;CACF"}

package/dist/checkpoints/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./types.ts";
+export * from "./default-summarization-strategy.ts";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/checkpoints/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,qCAAqC,CAAC"}

package/dist/checkpoints/index.js

@@ -0,0 +1,3 @@
+export * from "./types.js";
+export * from "./default-summarization-strategy.js";
+//# sourceMappingURL=index.js.map

package/dist/checkpoints/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/checkpoints/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,qCAAqC,CAAC"}

package/dist/checkpoints/types.d.ts

@@ -0,0 +1,32 @@
+import type { Message } from "../conversations/types.ts";
+import type { CheckpointState } from "../context-transformers/types.ts";
+/**
+ * Configuration for a checkpoint operation.
+ */
+export interface CheckpointConfig {
+    /** Arbitrary context passed through to the prompt strategy. */
+    context?: Record<string, unknown>;
+}
+/**
+ * Strategy for generating a checkpoint summary of a conversation.
+ */
+export interface SummarizationStrategy {
+    /** Builds the messages for the checkpoint conversation from the parent's context. */
+    build_prompt(context: SummarizationContext): Message[];
+}
+/**
+ * Context provided to the summarization strategy.
+ */
+export interface SummarizationContext {
+    /** The session ID of the conversation being checkpointed. */
+    session_id: string;
+    /** The conversation messages since the last checkpoint (or all if first checkpoint). */
+    messages: readonly Message[];
+    /** The previous checkpoint state, if this is an incremental checkpoint. */
+    previous_checkpoint?: CheckpointState;
+    /** The system prompt of the conversation being checkpointed. */
+    system?: string;
+    /** Arbitrary context forwarded from CheckpointConfig. */
+    context?: Record<string, unknown>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/checkpoints/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/checkpoints/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAExE;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,qFAAqF;IACrF,YAAY,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,EAAE,CAAC;CACxD;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,6DAA6D;IAC7D,UAAU,EAAE,MAAM,CAAC;IACnB,wFAAwF;IACxF,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC;IAC7B,2EAA2E;IAC3E,mBAAmB,CAAC,EAAE,eAAe,CAAC;IACtC,gEAAgE;IAChE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yDAAyD;IACzD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC"}

package/dist/checkpoints/types.js

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

package/dist/checkpoints/types.js.map

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

package/dist/context-transformers/checkpoint-context-transformer.d.ts

@@ -0,0 +1,13 @@
+import type { AssistantMessage, Message } from "../conversations/index.ts";
+import type { ContextTransformer, TransformContext } from "./types.ts";
+/**
+ * Context transformer that trims pre-checkpoint messages and inserts
+ * the checkpoint summary as a synthetic first user message. The boundary
+ * message (an assistant response) is retained as the natural response to
+ * the summary, maintaining proper message alternation.
+ */
+export declare class CheckpointContextTransformer implements ContextTransformer {
+    transform_prompt(messages: Message[], context?: TransformContext): Promise<Message[]>;
+    transform_completion(message: AssistantMessage): Promise<AssistantMessage>;
+}
+//# sourceMappingURL=checkpoint-context-transformer.d.ts.map

package/dist/context-transformers/checkpoint-context-transformer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint-context-transformer.d.ts","sourceRoot":"","sources":["../../src/context-transformers/checkpoint-context-transformer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAC;AAC3E,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEvE;;;;;GAKG;AACH,qBAAa,4BAA6B,YAAW,kBAAkB;IAC/D,gBAAgB,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAwB3F,oBAAoB,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC;CAG3E"}

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

@@ -0,0 +1,32 @@
+/**
+ * Context transformer that trims pre-checkpoint messages and inserts
+ * the checkpoint summary as a synthetic first user message. The boundary
+ * message (an assistant response) is retained as the natural response to
+ * the summary, maintaining proper message alternation.
+ */
+export class CheckpointContextTransformer {
+    async transform_prompt(messages, context) {
+        const checkpoint = context?.checkpoint;
+        if (!checkpoint) {
+            return messages;
+        }
+        const boundary = messages.findIndex((m) => m.id === checkpoint.message_id);
+        if (boundary === -1) {
+            return messages;
+        }
+        const summary_message = {
+            role: "user",
+            timestamp: Date.now(),
+            content: [{ type: "text", timestamp: Date.now(), text: checkpoint.summary }],
+        };
+        const boundary_message = messages[boundary];
+        if (boundary_message.role === "user") {
+            return [summary_message, ...messages.slice(boundary + 1)];
+        }
+        return [summary_message, ...messages.slice(boundary)];
+    }
+    transform_completion(message) {
+        return Promise.resolve(message);
+    }
+}
+//# sourceMappingURL=checkpoint-context-transformer.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint-context-transformer.js","sourceRoot":"","sources":["../../src/context-transformers/checkpoint-context-transformer.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,MAAM,OAAO,4BAA4B;IACvC,KAAK,CAAC,gBAAgB,CAAC,QAAmB,EAAE,OAA0B;QACpE,MAAM,UAAU,GAAG,OAAO,EAAE,UAAU,CAAC;QACvC,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,OAAO,QAAQ,CAAC;QAClB,CAAC;QAED,MAAM,QAAQ,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,UAAU,CAAC,UAAU,CAAC,CAAC;QAC3E,IAAI,QAAQ,KAAK,CAAC,CAAC,EAAE,CAAC;YACpB,OAAO,QAAQ,CAAC;QAClB,CAAC;QAED,MAAM,eAAe,GAAY;YAC/B,IAAI,EAAE,MAAM;YACZ,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;YACrB,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,IAAI,EAAE,UAAU,CAAC,OAAO,EAAE,CAAC;SAC7E,CAAC;QAEF,MAAM,gBAAgB,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC;QAC5C,IAAI,gBAAgB,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;YACrC,OAAO,CAAC,eAAe,EAAE,GAAG,QAAQ,CAAC,KAAK,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC,CAAC;QAC5D,CAAC;QACD,OAAO,CAAC,eAAe,EAAE,GAAG,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC;IACxD,CAAC;IAED,oBAAoB,CAAC,OAAyB;QAC5C,OAAO,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAClC,CAAC;CACF"}

package/dist/context-transformers/composite-context-transformer.d.ts

@@ -0,0 +1,31 @@
+import { AssistantMessage, Message } from "../conversations/index.ts";
+import { ContextTransformer, TransformContext } from "./types.ts";
+/**
+ * Combines multiple context transformers into a single transformation pipeline.
+ *
+ * Transformers are applied in the order provided.
+ */
+export declare class CompositeContextTransformer implements ContextTransformer {
+    #private;
+    /**
+     * Creates a new composite context transformer.
+     *
+     * @param transformers - The transformers to compose.
+     */
+    constructor(transformers: ContextTransformer[]);
+    /**
+     * Transforms prompt messages by applying all transformers in sequence.
+     *
+     * @param messages - The messages to transform.
+     * @returns A promise that resolves to the transformed messages.
+     */
+    transform_prompt(messages: Message[], context?: TransformContext): Promise<Message[]>;
+    /**
+     * Transforms a completion message by applying all transformers in sequence.
+     *
+     * @param message - The assistant message to transform.
+     * @returns A promise that resolves to the transformed message.
+     */
+    transform_completion(message: AssistantMessage): Promise<AssistantMessage>;
+}
+//# sourceMappingURL=composite-context-transformer.d.ts.map

package/dist/context-transformers/composite-context-transformer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composite-context-transformer.d.ts","sourceRoot":"","sources":["../../src/context-transformers/composite-context-transformer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAC;AACtE,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAElE;;;;GAIG;AACH,qBAAa,2BAA4B,YAAW,kBAAkB;;IAGpE;;;;OAIG;gBACS,YAAY,EAAE,kBAAkB,EAAE;IAI9C;;;;;OAKG;IACG,gBAAgB,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAO3F;;;;;OAKG;IACG,oBAAoB,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC;CAMjF"}

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

@@ -0,0 +1,41 @@
+/**
+ * Combines multiple context transformers into a single transformation pipeline.
+ *
+ * Transformers are applied in the order provided.
+ */
+export class CompositeContextTransformer {
+    #transformers;
+    /**
+     * Creates a new composite context transformer.
+     *
+     * @param transformers - The transformers to compose.
+     */
+    constructor(transformers) {
+        this.#transformers = transformers;
+    }
+    /**
+     * Transforms prompt messages by applying all transformers in sequence.
+     *
+     * @param messages - The messages to transform.
+     * @returns A promise that resolves to the transformed messages.
+     */
+    async transform_prompt(messages, context) {
+        for (const transformer of this.#transformers) {
+            messages = await transformer.transform_prompt(messages, context);
+        }
+        return messages;
+    }
+    /**
+     * Transforms a completion message by applying all transformers in sequence.
+     *
+     * @param message - The assistant message to transform.
+     * @returns A promise that resolves to the transformed message.
+     */
+    async transform_completion(message) {
+        for (const transformer of this.#transformers) {
+            message = await transformer.transform_completion(message);
+        }
+        return message;
+    }
+}
+//# sourceMappingURL=composite-context-transformer.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"composite-context-transformer.js","sourceRoot":"","sources":["../../src/context-transformers/composite-context-transformer.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,MAAM,OAAO,2BAA2B;IAC7B,aAAa,CAAuB;IAE7C;;;;OAIG;IACH,YAAY,YAAkC;QAC5C,IAAI,CAAC,aAAa,GAAG,YAAY,CAAC;IACpC,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,gBAAgB,CAAC,QAAmB,EAAE,OAA0B;QACpE,KAAK,MAAM,WAAW,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;YAC7C,QAAQ,GAAG,MAAM,WAAW,CAAC,gBAAgB,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QACnE,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,oBAAoB,CAAC,OAAyB;QAClD,KAAK,MAAM,WAAW,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;YAC7C,OAAO,GAAG,MAAM,WAAW,CAAC,oBAAoB,CAAC,OAAO,CAAC,CAAC;QAC5D,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;CACF"}

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

@@ -0,0 +1,6 @@
+export * from "./checkpoint-context-transformer.ts";
+export * from "./composite-context-transformer.ts";
+export * from "./noop-context-transformer.ts";
+export * from "./tool-context-transformer.ts";
+export * from "./types.ts";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/context-transformers/index.ts"],"names":[],"mappings":"AAAA,cAAc,qCAAqC,CAAC;AACpD,cAAc,oCAAoC,CAAC;AACnD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,YAAY,CAAC"}

package/dist/context-transformers/index.js

@@ -0,0 +1,6 @@
+export * from "./checkpoint-context-transformer.js";
+export * from "./composite-context-transformer.js";
+export * from "./noop-context-transformer.js";
+export * from "./tool-context-transformer.js";
+export * from "./types.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/context-transformers/index.ts"],"names":[],"mappings":"AAAA,cAAc,qCAAqC,CAAC;AACpD,cAAc,oCAAoC,CAAC;AACnD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,YAAY,CAAC"}

package/dist/context-transformers/noop-context-transformer.d.ts

@@ -0,0 +1,24 @@
+import { AssistantMessage, Message } from "../conversations/index.ts";
+import { ContextTransformer } from "./types.ts";
+/**
+ * Context transformer that performs no transformations.
+ *
+ * Returns messages unchanged.
+ */
+export declare class NoopContextTransformer implements ContextTransformer {
+    /**
+     * Returns the prompt messages unchanged.
+     *
+     * @param messages - The messages to pass through.
+     * @returns A promise that resolves to the same messages.
+     */
+    transform_prompt(messages: Message[]): Promise<Message[]>;
+    /**
+     * 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: AssistantMessage): Promise<AssistantMessage>;
+}
+//# sourceMappingURL=noop-context-transformer.d.ts.map

package/dist/context-transformers/noop-context-transformer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"noop-context-transformer.d.ts","sourceRoot":"","sources":["../../src/context-transformers/noop-context-transformer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAC;AACtE,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAEhD;;;;GAIG;AACH,qBAAa,sBAAuB,YAAW,kBAAkB;IAC/D;;;;;OAKG;IACH,gBAAgB,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAIzD;;;;;OAKG;IACH,oBAAoB,CAAC,OAAO,EAAE,gBAAgB;CAG/C"}

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

@@ -0,0 +1,26 @@
+/**
+ * Context transformer that performs no transformations.
+ *
+ * Returns messages unchanged.
+ */
+export class NoopContextTransformer {
+    /**
+     * Returns the prompt messages unchanged.
+     *
+     * @param messages - The messages to pass through.
+     * @returns A promise that resolves to the same messages.
+     */
+    transform_prompt(messages) {
+        return Promise.resolve(messages);
+    }
+    /**
+     * 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=noop-context-transformer.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"noop-context-transformer.js","sourceRoot":"","sources":["../../src/context-transformers/noop-context-transformer.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,MAAM,OAAO,sBAAsB;IACjC;;;;;OAKG;IACH,gBAAgB,CAAC,QAAmB;QAClC,OAAO,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACnC,CAAC;IAED;;;;;OAKG;IACH,oBAAoB,CAAC,OAAyB;QAC5C,OAAO,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAClC,CAAC;CACF"}

package/dist/context-transformers/tool-context-transformer.d.ts

@@ -0,0 +1,26 @@
+import { AssistantMessage, Message } from "../conversations/index.ts";
+import { ContextTransformer } from "./types.ts";
+/**
+ * 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 declare class ToolContextTransformer implements ContextTransformer {
+    /**
+     * 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: Message[]): Promise<Message[]>;
+    /**
+     * 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: AssistantMessage): Promise<AssistantMessage>;
+}
+//# sourceMappingURL=tool-context-transformer.d.ts.map

package/dist/context-transformers/tool-context-transformer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-context-transformer.d.ts","sourceRoot":"","sources":["../../src/context-transformers/tool-context-transformer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAC;AACtE,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAEhD;;;;;;GAMG;AACH,qBAAa,sBAAuB,YAAW,kBAAkB;IAC/D;;;;;OAKG;IACH,gBAAgB,CAAC,QAAQ,EAAE,OAAO,EAAE;IA+BpC;;;;;OAKG;IACH,oBAAoB,CAAC,OAAO,EAAE,gBAAgB;CAG/C"}