@simulacra-ai/core 0.0.2 → 0.0.4

package/dist/index.d.cts

@@ -0,0 +1,1631 @@
+/**
+ * Manages an agentic workflow with automatic tool execution.
+ *
+ * A Workflow wraps a Conversation and automatically executes tools requested
+ * by the model, continuing the conversation until completion or error.
+ */
+declare class Workflow {
+    #private;
+    /**
+     * Creates a new workflow instance.
+     *
+     * @param conversation - The conversation to manage.
+     * @param options - Optional configuration.
+     * @param options.context_data - Custom data to pass to tools via ToolContext.
+     * @param options.parent - Parent workflow if this is a child workflow.
+     */
+    constructor(conversation: Conversation, options?: {
+        context_data?: Record<string, unknown>;
+        parent?: Workflow;
+    });
+    /**
+     * The unique identifier for this workflow.
+     */
+    get id(): string;
+    set id(value: string);
+    /**
+     * The current state of the workflow.
+     */
+    get state(): WorkflowState;
+    /**
+     * The conversation being managed by this workflow.
+     */
+    get conversation(): Conversation;
+    /**
+     * The parent workflow, if this is a child workflow.
+     */
+    get parent(): Workflow | undefined;
+    /**
+     * The message history tracked by this workflow.
+     */
+    get messages(): readonly Readonly<Message>[];
+    /**
+     * Messages queued for sending after the current response completes.
+     */
+    get queued_messages(): string[];
+    /**
+     * Disposes the workflow and releases all resources.
+     *
+     * This method is called automatically when using the `using` keyword.
+     */
+    [Symbol.dispose](): void;
+    /**
+     * Registers a one-time event listener.
+     *
+     * @template E - The event name type.
+     * @param event - The name of the event to listen for.
+     * @param listener - The callback function to invoke when the event occurs.
+     * @returns This workflow instance for chaining.
+     */
+    once<E extends keyof WorkflowEvents>(event: E, listener: E extends keyof WorkflowEvents ? (...args: WorkflowEvents[E]) => void : never): this;
+    /**
+     * Registers a persistent event listener.
+     *
+     * @template E - The event name type.
+     * @param event - The name of the event to listen for.
+     * @param listener - The callback function to invoke when the event occurs.
+     * @returns This workflow instance for chaining.
+     */
+    on<E extends keyof WorkflowEvents>(event: E, listener: E extends keyof WorkflowEvents ? (...args: WorkflowEvents[E]) => void : never): this;
+    /**
+     * Removes an event listener.
+     *
+     * @template E - The event name type.
+     * @param event - The name of the event.
+     * @param listener - The callback function to remove.
+     * @returns This workflow instance for chaining.
+     */
+    off<E extends keyof WorkflowEvents>(event: E, listener: E extends keyof WorkflowEvents ? (...args: WorkflowEvents[E]) => void : never): this;
+    /**
+     * Starts the workflow execution.
+     *
+     * @param message - Optional initial user message to begin the workflow.
+     */
+    start(message?: UserMessage): void;
+    /**
+     * Cancels the workflow execution.
+     *
+     * This will cancel any in-progress model response and emit a workflow_end event.
+     */
+    cancel(): void;
+    /**
+     * Creates a child workflow with a different conversation.
+     *
+     * Child events are propagated to the parent as "child_workflow_event" events.
+     *
+     * @param conversation - The conversation for the child workflow.
+     * @param id - Optional custom ID for the child workflow.
+     * @param context_data - Additional context data to merge with this workflow's context data.
+     * @returns The newly created child workflow.
+     */
+    spawn_child(conversation: Conversation, id?: string, context_data?: Record<string, unknown>): Workflow;
+    /**
+     * Adds a message to the queue for sending after the current response completes.
+     *
+     * @param message - The text message to queue.
+     */
+    queue_message(message: string): void;
+    /**
+     * Clears all queued messages.
+     */
+    clear_queue(): void;
+}
+
+/**
+ * Automatically manages workflow lifecycle for a conversation.
+ *
+ * The WorkflowManager creates a new Workflow instance whenever a message is sent
+ * to its associated conversation, eliminating the need for manual workflow management.
+ */
+declare class WorkflowManager {
+    #private;
+    /**
+     * Creates a new workflow manager instance.
+     *
+     * @param conversation - The conversation to manage workflows for.
+     * @param options - Optional configuration.
+     * @param options.context_data - Custom data to pass to tools via ToolContext.
+     */
+    constructor(conversation: Conversation, options?: {
+        context_data?: Record<string, unknown>;
+    });
+    /**
+     * The current state of the workflow manager.
+     */
+    get state(): WorkflowState;
+    /**
+     * The conversation being managed.
+     */
+    get conversation(): Conversation;
+    /**
+     * The currently active workflow, if any.
+     */
+    get current_workflow(): Workflow | undefined;
+    /**
+     * Disposes the workflow manager and releases all resources.
+     *
+     * This method is called automatically when using the `using` keyword.
+     */
+    [Symbol.dispose](): void;
+    /**
+     * Registers a one-time event listener.
+     *
+     * @template E - The event name type.
+     * @param event - The name of the event to listen for.
+     * @param listener - The callback function to invoke when the event occurs.
+     * @returns This workflow manager instance for chaining.
+     */
+    once<E extends keyof WorkflowManagerEvents>(event: E, listener: E extends keyof WorkflowManagerEvents ? (...args: WorkflowManagerEvents[E]) => void : never): this;
+    /**
+     * Registers a persistent event listener.
+     *
+     * @template E - The event name type.
+     * @param event - The name of the event to listen for.
+     * @param listener - The callback function to invoke when the event occurs.
+     * @returns This workflow manager instance for chaining.
+     */
+    on<E extends keyof WorkflowManagerEvents>(event: E, listener: E extends keyof WorkflowManagerEvents ? (...args: WorkflowManagerEvents[E]) => void : never): this;
+    /**
+     * Removes an event listener.
+     *
+     * @template E - The event name type.
+     * @param event - The name of the event.
+     * @param listener - The callback function to remove.
+     * @returns This workflow manager instance for chaining.
+     */
+    off<E extends keyof WorkflowManagerEvents>(event: E, listener: E extends keyof WorkflowManagerEvents ? (...args: WorkflowManagerEvents[E]) => void : never): this;
+    /**
+     * Manually starts a workflow.
+     *
+     * This is typically not needed as workflows are started automatically when messages are sent.
+     */
+    start_workflow(): void;
+}
+
+/**
+ * Possible states of a workflow.
+ */
+type WorkflowState = "idle" | "busy" | "disposed";
+/**
+ * Event data describing why a workflow ended.
+ */
+type WorkflowEndEvent = {
+    reason: "complete" | "cancel" | "error";
+};
+/**
+ * Events emitted by a Workflow instance.
+ */
+interface WorkflowEvents {
+    /** Emitted when the workflow state changes. */
+    state_change: [ChangeEvent<WorkflowState>, Workflow];
+    /** Emitted when the workflow is updated with new messages. */
+    workflow_update: [Workflow];
+    /** Emitted when the workflow ends. */
+    workflow_end: [WorkflowEndEvent, Workflow];
+    /** Emitted when a child workflow is created. */
+    child_workflow_begin: [Workflow, Workflow];
+    /** Emitted when a child workflow emits an event. */
+    child_workflow_event: [
+        {
+            [E in keyof WorkflowEvents]: {
+                event_name: E;
+                event_args: WorkflowEvents[E];
+            };
+        }[keyof WorkflowEvents],
+        Workflow
+    ];
+    /** Emitted when a message is added to the queue. */
+    message_queued: [string, Workflow];
+    /** Emitted when a message is removed from the queue for sending. */
+    message_dequeued: [string, Workflow];
+    /** Emitted when the message queue is cleared. */
+    queue_cleared: [Workflow];
+    /** Emitted when an infrastructure or lifecycle operation fails. */
+    lifecycle_error: [LifecycleErrorEvent, Workflow];
+    /** Emitted when the workflow is disposed. */
+    dispose: [Workflow];
+}
+/**
+ * Events emitted by a WorkflowManager instance.
+ */
+interface WorkflowManagerEvents {
+    /** Emitted when the workflow manager state changes. */
+    state_change: [ChangeEvent<WorkflowState>, WorkflowManager];
+    /** Emitted when a new workflow begins. */
+    workflow_begin: [Workflow, WorkflowManager];
+    /** Emitted when a managed workflow emits an event. */
+    workflow_event: [
+        {
+            [E in keyof WorkflowEvents]: {
+                event_name: E;
+                event_args: WorkflowEvents[E];
+            };
+        }[keyof WorkflowEvents],
+        WorkflowManager
+    ];
+    /** Emitted when an infrastructure or lifecycle operation fails. */
+    lifecycle_error: [LifecycleErrorEvent, WorkflowManager];
+    /** Emitted when the workflow manager is disposed. */
+    dispose: [WorkflowManager];
+}
+
+/**
+ * Context provided to tools when they are executed.
+ *
+ * This interface can be extended with custom properties by passing
+ * additional data through the workflow's context_data.
+ */
+interface ToolContext {
+    /** The conversation instance where the tool is being executed. */
+    conversation: Conversation;
+    /** The workflow instance managing the tool execution. */
+    workflow: Workflow;
+    /** Additional custom context properties. */
+    [key: string]: unknown;
+}
+/**
+ * Result indicating successful tool execution.
+ */
+interface ToolSuccessResult {
+    result: true;
+}
+/**
+ * Result indicating failed tool execution.
+ */
+interface ToolErrorResult {
+    result: false;
+    /** Description of what went wrong. */
+    message: string;
+    /** Optional underlying error object. */
+    error?: unknown;
+}
+/**
+ * Union of all possible tool execution results.
+ */
+type ToolResult = ToolSuccessResult | ToolErrorResult;
+/**
+ * String parameter type definition.
+ */
+type StringParameterType = {
+    type: "string";
+    required: true;
+    default?: never;
+    description?: string;
+} | {
+    type: "string";
+    required?: false;
+    default?: string;
+    description?: string;
+};
+/**
+ * Enumeration parameter type definition.
+ */
+type EnumParameterType = {
+    type: "string";
+    required: true;
+    enum: string[];
+    default?: never;
+    description?: string;
+} | {
+    type: "string";
+    required?: false;
+    enum: string[];
+    default?: string;
+    description?: string;
+};
+/**
+ * Number parameter type definition.
+ */
+type NumberParameterType = {
+    type: "number";
+    required: true;
+    default?: never;
+    description?: string;
+} | {
+    type: "number";
+    required?: false;
+    default?: number;
+    description?: string;
+};
+/**
+ * Boolean parameter type definition.
+ */
+type BooleanParameterType = {
+    type: "boolean";
+    required: true;
+    default?: never;
+    description?: string;
+} | {
+    type: "boolean";
+    required?: false;
+    default?: boolean;
+    description?: string;
+};
+/**
+ * Union of all primitive parameter types.
+ */
+type PrimitiveParameterType = StringParameterType | EnumParameterType | NumberParameterType | BooleanParameterType;
+/**
+ * Object parameter type definition with nested properties.
+ */
+interface ObjectParameterType {
+    type: "object";
+    required?: boolean;
+    properties: Record<string, ParameterType>;
+    default?: never;
+    description?: string;
+}
+/**
+ * Array parameter type definition.
+ */
+interface ArrayParameterType {
+    type: "array";
+    required?: boolean;
+    items: ParameterType;
+    default?: never;
+    description?: string;
+}
+/**
+ * Union of all parameter types.
+ */
+type ParameterType = PrimitiveParameterType | ObjectParameterType | ArrayParameterType;
+/**
+ * A named parameter with its type definition and optional description.
+ */
+type ToolParameterDefinition = ParameterType & {
+    name: string;
+    description?: string;
+};
+/**
+ * Complete definition of a tool including its name, description, and parameters.
+ */
+interface ToolDefinition {
+    /** The unique name of the tool. */
+    name: string;
+    /** Description of what the tool does. */
+    description: string;
+    /** The parameters the tool accepts. */
+    parameters: ToolParameterDefinition[];
+    /** Whether this tool can be executed in parallel with other tools. */
+    parallelizable?: boolean;
+}
+/**
+ * Constructor interface for tool classes.
+ *
+ * @template TParams - The parameter type for the tool.
+ * @template TSuccessResult - The success result type.
+ * @template TErrorResult - The error result type.
+ */
+interface ToolClass<TParams extends Record<string, unknown> = Record<string, unknown>, TSuccessResult extends ToolSuccessResult = ToolSuccessResult, TErrorResult extends ToolErrorResult = ToolErrorResult> {
+    /**
+     * Constructs a new tool instance.
+     *
+     * @param context - The context for tool execution.
+     */
+    new (context: ToolContext): Tool<TParams, TSuccessResult, TErrorResult>;
+    /**
+     * Gets the static definition of this tool.
+     *
+     * @returns The tool definition.
+     */
+    get_definition(): ToolDefinition;
+}
+/**
+ * Interface that all tools must implement.
+ *
+ * @template TParams - The parameter type for the tool.
+ * @template TSuccessResult - The success result type.
+ * @template TErrorResult - The error result type.
+ */
+interface Tool<TParams extends Record<string, unknown> = Record<string, unknown>, TSuccessResult extends ToolSuccessResult = ToolSuccessResult, TErrorResult extends ToolErrorResult = ToolErrorResult> {
+    /**
+     * Executes the tool with the provided parameters.
+     *
+     * @param params - The parameters for tool execution.
+     * @returns A promise that resolves to either success or error result.
+     */
+    execute(params: TParams): Promise<TSuccessResult | TErrorResult>;
+}
+
+/**
+ * Token for monitoring and responding to cancellation requests.
+ *
+ * Provides a way to check if an operation has been cancelled and to
+ * register callbacks for when cancellation occurs.
+ */
+declare class CancellationToken {
+    #private;
+    /**
+     * Creates a new cancellation token.
+     *
+     * @param source - Optional source that controls this token.
+     */
+    constructor(source?: CancellationTokenSource);
+    /**
+     * Whether cancellation has been requested.
+     */
+    get is_cancellation_requested(): boolean;
+    /**
+     * Registers a one-time handler for cancellation.
+     *
+     * @param event - The event name (always "cancel").
+     * @param handler - The callback to invoke when cancelled.
+     */
+    once(event: "cancel", handler: () => void): void;
+    /**
+     * Removes a cancellation handler.
+     *
+     * @param event - The event name (always "cancel").
+     * @param handler - The callback to remove.
+     */
+    off(event: "cancel", handler: () => void): void;
+    /**
+     * Throws an error if cancellation has been requested.
+     */
+    throw_if_cancellation_requested(): void;
+    /**
+     * Creates a promise that rejects when cancellation is requested.
+     *
+     * @returns A promise that never resolves but rejects on cancellation.
+     */
+    await_cancellation(): Promise<never>;
+    /**
+     * Creates an empty cancellation token that can never be cancelled.
+     *
+     * @returns A new cancellation token with no source.
+     */
+    static empty(): CancellationToken;
+}
+/**
+ * Source for creating and controlling cancellation tokens.
+ *
+ * Allows triggering cancellation for associated tokens.
+ */
+declare class CancellationTokenSource {
+    #private;
+    /**
+     * Disposes the cancellation token source.
+     *
+     * This method is called automatically when using the `using` keyword.
+     */
+    [Symbol.dispose](): void;
+    /**
+     * Gets a cancellation token associated with this source.
+     */
+    get token(): CancellationToken;
+    /**
+     * Whether cancellation has been triggered.
+     */
+    get is_cancelled(): boolean;
+    /**
+     * Registers a one-time handler for cancellation.
+     *
+     * @param event - The event name (always "cancel").
+     * @param handler - The callback to invoke when cancelled.
+     */
+    once(event: "cancel", handler: () => void): void;
+    /**
+     * Removes a cancellation handler.
+     *
+     * @param event - The event name (always "cancel").
+     * @param handler - The callback to remove.
+     */
+    off(event: "cancel", handler: () => void): void;
+    /**
+     * Triggers cancellation for all associated tokens.
+     */
+    cancel(): void;
+}
+/**
+ * Error thrown when an operation is cancelled.
+ */
+declare class OperationCanceledError extends Error {
+    #private;
+    /**
+     * Creates a new operation cancelled error.
+     *
+     * @param token - The cancellation token associated with this error.
+     */
+    constructor(token: CancellationToken);
+    /**
+     * The cancellation token associated with this error.
+     */
+    get token(): CancellationToken;
+}
+/**
+ * Delays execution for a specified time period with cancellation support.
+ *
+ * @param ms - The number of milliseconds to sleep.
+ * @param cancellation_token - Optional token for cancelling the sleep.
+ * @returns A promise that resolves after the delay or rejects if cancelled.
+ */
+declare function sleep(ms: number, cancellation_token?: CancellationToken): Promise<void>;
+/**
+ * Peeks at the first value from an async generator without consuming it.
+ *
+ * @template T - The type of values yielded by the generator.
+ * @param generator - The async generator to peek.
+ * @returns An object containing the peeked value and a new generator that includes it.
+ */
+declare function peek_generator<T>(generator: AsyncGenerator<T>): Promise<{
+    peeked_value: T;
+    generator: AsyncGenerator<Awaited<T>, void, unknown>;
+}>;
+
+/**
+ * Represents a successful policy execution.
+ *
+ * @template T - The type of the result value.
+ */
+interface PolicySuccessResult<T> {
+    result: true;
+    /** Metadata about the policy execution. */
+    metadata: object;
+    /** The value returned by the wrapped function. */
+    value: T;
+}
+/**
+ * Represents a failed policy execution.
+ */
+interface PolicyErrorResult {
+    result: false;
+    /** Metadata about the policy execution. */
+    metadata: object;
+    /** The error that occurred. */
+    error: unknown;
+}
+/**
+ * Union of all possible policy execution results.
+ *
+ * @template T - The type of the success result value.
+ */
+type PolicyResult<T> = PolicySuccessResult<T> | PolicyErrorResult;
+/**
+ * Base class for all policies.
+ *
+ * Policies wrap function execution to provide cross-cutting concerns like
+ * retries, rate limiting, and token budget management.
+ */
+declare abstract class Policy {
+    /**
+     * Executes a function with this policy applied.
+     *
+     * @template TResult - The return type of the function.
+     * @template TArgs - The argument types of the function.
+     * @param cancellation_token - Token for cancelling the operation.
+     * @param fn - The function to execute.
+     * @param args - Arguments to pass to the function.
+     * @returns A promise that resolves to the policy result.
+     */
+    abstract execute<TResult, TArgs extends unknown[]>(cancellation_token: CancellationToken, fn: (...args: TArgs) => Promise<TResult>, ...args: TArgs): Promise<PolicyResult<TResult>>;
+}
+
+/**
+ * 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.
+ */
+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: ToolContextTransformer + CheckpointContextTransformer).
+     * @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, containing the summary text and the ID
+     * of the last message included in the checkpoint. Available after a
+     * successful call to `checkpoint()`. Used by CheckpointContextTransformer
+     * to replace pre-checkpoint messages with the summary on subsequent prompts.
+     */
+    get checkpoint_state(): Readonly<CheckpointState> | undefined;
+    set checkpoint_state(value: CheckpointState | undefined);
+    /**
+     * True when this conversation is an ephemeral child spawned to generate a
+     * checkpoint summary. Checkpoint sessions are short-lived, receive the
+     * conversation history as a summarization prompt, and are disposed after
+     * the summary is produced.
+     */
+    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>;
+}
+
+/**
+ * Discriminated union of all possible stream events and their payloads.
+ */
+type StreamListenerPayload = {
+    [E in keyof StreamReceiver]: {
+        event: E;
+        payload: Parameters<StreamReceiver[E]>;
+    };
+}[keyof StreamReceiver];
+/**
+ * Internal utility for converting StreamReceiver callbacks into a single event handler.
+ *
+ * This class is used internally by Conversation to manage streaming events.
+ */
+declare class StreamListener {
+    #private;
+    /**
+     * Creates a new stream listener.
+     *
+     * @param listener - The callback to invoke with stream events.
+     */
+    constructor(listener: (payload: StreamListenerPayload) => void | Promise<void>);
+    /**
+     * Disposes the stream listener.
+     *
+     * This method is called automatically when using the `using` keyword.
+     */
+    [Symbol.dispose](): void;
+    /**
+     * Creates a StreamReceiver that forwards all events to the listener.
+     *
+     * @returns A new stream receiver instance.
+     */
+    create_receiver(): StreamReceiver;
+}
+
+/**
+ * Statistics about token usage.
+ */
+interface TokenStats {
+    /** Token usage from the most recent request. */
+    last_request: {
+        /** Input tokens in the last request. */
+        input: number;
+        /** Output tokens in the last request. */
+        output: number;
+    };
+    /** Cumulative token usage across all requests. */
+    total: {
+        /** Total input tokens consumed. */
+        input: number;
+        /** Total output tokens generated. */
+        output: number;
+    };
+}
+/**
+ * Tracks token usage for a conversation and its children.
+ *
+ * Automatically monitors conversation events to accumulate token statistics.
+ */
+declare class TokenTracker {
+    #private;
+    /**
+     * Creates a new token tracker.
+     *
+     * @param conversation - The conversation to track.
+     */
+    constructor(conversation: Conversation);
+    /**
+     * Disposes the token tracker and removes event listeners.
+     *
+     * This method is called automatically when using the `using` keyword.
+     */
+    [Symbol.dispose](): void;
+    /**
+     * The current token statistics.
+     */
+    get stats(): Readonly<TokenStats>;
+    /**
+     * Registers an event listener for statistics updates.
+     *
+     * @param event - The event name (always "stats_update").
+     * @param listener - The callback to invoke when statistics update.
+     */
+    on(event: "stats_update", listener: (stats: TokenStats) => void): void;
+    /**
+     * Removes an event listener for statistics updates.
+     *
+     * @param event - The event name (always "stats_update").
+     * @param listener - The callback to remove.
+     */
+    off(event: "stats_update", listener: (stats: TokenStats) => void): void;
+}
+
+/**
+ * The active checkpoint state for a conversation.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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>;
+}
+
+/**
+ * Base interface for all content types.
+ */
+interface BaseContent {
+    /** Optional unique identifier for this content block. */
+    id?: string;
+    /** Optional timestamp when this content was created. */
+    timestamp?: number;
+}
+/**
+ * Raw content that contains provider-specific data.
+ */
+interface RawContent extends BaseContent {
+    type: "raw";
+    /** The kind of model provider this raw data belongs to. */
+    model_kind: string;
+    /** The raw serialized data from the provider. */
+    data: string;
+}
+/**
+ * Base interface for content that can be extended with custom properties.
+ */
+interface ExtendableContent extends BaseContent {
+    /** Optional custom properties that can be attached to this content. */
+    extended?: Record<string, unknown>;
+}
+/**
+ * Text content block.
+ */
+interface TextContent extends ExtendableContent {
+    type: "text";
+    /** The text content. */
+    text: string;
+}
+/**
+ * Tool execution result content.
+ *
+ * @template TTool - The type of tool that produced this result.
+ */
+interface ToolResultContent<TTool extends Tool = Tool> extends ExtendableContent {
+    type: "tool_result";
+    /** The name of the tool that was executed. */
+    tool: string;
+    /** The unique identifier matching the tool request. */
+    tool_request_id: string;
+    /** The result returned by the tool execution. */
+    result: Awaited<ReturnType<TTool["execute"]>>;
+}
+/**
+ * Content types that can appear in user messages.
+ */
+type UserContent = RawContent | TextContent | ToolResultContent;
+/**
+ * Thinking/reasoning content from the assistant.
+ */
+interface ThinkingMessageContent extends ExtendableContent {
+    type: "thinking";
+    /** The assistant's internal reasoning. */
+    thought: string;
+}
+/**
+ * Tool invocation request from the assistant.
+ *
+ * @template TTool - The type of tool being invoked.
+ */
+interface ToolContent<TTool extends Tool = Tool> extends ExtendableContent {
+    type: "tool";
+    /** Unique identifier for this tool request. */
+    tool_request_id: string;
+    /** The name of the tool to invoke. */
+    tool: string;
+    /** The parameters to pass to the tool. */
+    params: Parameters<TTool["execute"]>[0];
+}
+/**
+ * Content types that can appear in assistant messages.
+ */
+type AssistantContent = RawContent | TextContent | ThinkingMessageContent | ToolContent;
+/**
+ * Union of all content types.
+ */
+type Content = UserContent | AssistantContent;
+/**
+ * A message from the user.
+ */
+interface UserMessage {
+    /** Optional unique identifier for this message. */
+    id?: string;
+    /** Optional timestamp when this message was created. */
+    timestamp?: number;
+    /** The role of the message sender. */
+    role: "user";
+    /** The content blocks in this message. */
+    content: UserContent[];
+}
+/**
+ * A message from the assistant.
+ */
+interface AssistantMessage {
+    /** Optional unique identifier for this message. */
+    id?: string;
+    /** Optional timestamp when this message was created. */
+    timestamp?: number;
+    /** The role of the message sender. */
+    role: "assistant";
+    /** The content blocks in this message. */
+    content: AssistantContent[];
+}
+/**
+ * Union of all message types.
+ */
+type Message = UserMessage | AssistantMessage;
+/**
+ * Token usage information for a model request/response.
+ */
+interface Usage {
+    /** Number of tokens used to create cache. */
+    cache_creation_input_tokens?: number | null;
+    /** Number of cached input tokens read. */
+    cache_read_input_tokens?: number | null;
+    /** Number of input tokens consumed. */
+    input_tokens?: number | null;
+    /** Number of output tokens generated. */
+    output_tokens?: number | null;
+}
+/**
+ * Base data for any request.
+ */
+type RequestData = {
+    request_id?: string;
+};
+/**
+ * Data for a prompt request that includes the user message.
+ */
+type PromptRequestData = RequestData & {
+    message: UserMessage;
+};
+/**
+ * Streaming response data that includes usage information.
+ */
+type CompletionStreamingResponseData = RequestData & {
+    usage: Usage;
+};
+/**
+ * Complete response data that includes stop reason and details.
+ */
+type CompletionResponseData = CompletionStreamingResponseData & {
+    /** The reason why the model stopped generating. */
+    stop_reason: "end_turn" | "max_tokens" | "stop_sequence" | "tool_use" | "error" | "other";
+    /** Optional additional details about why the model stopped. */
+    stop_details?: string;
+};
+/**
+ * Represents a state change event.
+ *
+ * @template T - The type of state being changed.
+ */
+type ChangeEvent<T> = {
+    current: T;
+    previous: T;
+};
+/**
+ * Event containing raw data from the provider.
+ */
+type RawEvent = {
+    data: unknown;
+};
+/**
+ * Raw event with an associated request ID.
+ */
+type RawRequestEvent = RawEvent & RequestData;
+/**
+ * Event containing error information for a failed request.
+ */
+type ErrorRequestEvent = PromptRequestData & {
+    error: unknown;
+};
+/**
+ * Event emitted when an infrastructure or lifecycle operation fails.
+ *
+ * Unlike {@link ErrorRequestEvent} (which is specific to model provider request failures),
+ * this event covers operational failures such as session save errors, fork failures,
+ * or cleanup failures.
+ */
+interface LifecycleErrorEvent {
+    /** The error that occurred. */
+    error: unknown;
+    /** A short identifier for the operation that failed (e.g., "save", "fork", "disconnect"). */
+    operation: string;
+    /** Optional additional context about the failure. */
+    context?: Record<string, unknown>;
+}
+/**
+ * Partial message completion event during streaming.
+ */
+type PartialMessageCompletionEvent = CompletionStreamingResponseData & {
+    message: Partial<AssistantMessage>;
+};
+/**
+ * Complete message event when streaming finishes.
+ */
+type FullMessageCompletionEvent = CompletionResponseData & {
+    message: AssistantMessage;
+};
+/**
+ * Partial content completion event during streaming.
+ */
+type PartialContentCompletionEvent = PartialMessageCompletionEvent & {
+    content: Partial<AssistantContent>;
+};
+/**
+ * Complete content event when a content block finishes streaming.
+ */
+type FullContentCompletionEvent = PartialMessageCompletionEvent & {
+    content: AssistantContent;
+};
+/**
+ * Events emitted by a Conversation instance.
+ */
+interface ConversationEvents {
+    /** Emitted when the conversation state changes. */
+    state_change: [ChangeEvent<ConversationState>, Conversation];
+    /** Emitted when a prompt is sent to the model. */
+    prompt_send: [PromptRequestData, Conversation];
+    /** Emitted when the assistant starts generating a message. */
+    message_start: [PartialMessageCompletionEvent, Conversation];
+    /** Emitted during message generation with partial updates. */
+    message_update: [PartialMessageCompletionEvent, Conversation];
+    /** Emitted when message generation completes. */
+    message_complete: [FullMessageCompletionEvent, Conversation];
+    /** Emitted when a content block starts streaming. */
+    content_start: [PartialContentCompletionEvent, Conversation];
+    /** Emitted during content block streaming with updates. */
+    content_update: [PartialContentCompletionEvent, Conversation];
+    /** Emitted when a content block completes. */
+    content_complete: [FullContentCompletionEvent, Conversation];
+    /** Emitted when a request succeeds. */
+    request_success: [PromptRequestData, object, Conversation];
+    /** Emitted when a request fails. */
+    request_error: [ErrorRequestEvent, object, Conversation];
+    /** Emitted before a request is sent to the provider. */
+    before_request: [RawEvent, Conversation];
+    /** Emitted with raw request data. */
+    raw_request: [RawRequestEvent, Conversation];
+    /** Emitted with raw response data. */
+    raw_response: [RawRequestEvent, Conversation];
+    /** Emitted with raw streaming data. */
+    raw_stream: [RawRequestEvent, Conversation];
+    /** Emitted when a checkpoint operation begins. The payload is the child conversation used for summarization. */
+    checkpoint_begin: [Conversation, Conversation];
+    /** Emitted when a checkpoint operation completes. The payload is the new checkpoint state. */
+    checkpoint_complete: [CheckpointState, Conversation];
+    /** Emitted when a child conversation is created. */
+    create_child: [Conversation, Conversation];
+    /** Emitted when a child conversation emits an event. */
+    child_event: [
+        {
+            [E in keyof ConversationEvents]: {
+                event_name: E;
+                event_args: ConversationEvents[E];
+            };
+        }[keyof ConversationEvents],
+        Conversation
+    ];
+    /** Emitted when an infrastructure or lifecycle operation fails. */
+    lifecycle_error: [LifecycleErrorEvent, Conversation];
+    /** Emitted when the conversation is disposed. */
+    dispose: [Conversation];
+}
+/**
+ * Interface for receiving streaming events from model providers.
+ */
+interface StreamReceiver {
+    /** Called when a message starts streaming. */
+    start_message: (event: Omit<PartialMessageCompletionEvent, "request_id">) => void;
+    /** Called with message updates during streaming. */
+    update_message: (event: Omit<PartialMessageCompletionEvent, "request_id">) => void;
+    /** Called when a message completes. */
+    complete_message: (event: Omit<FullMessageCompletionEvent, "request_id">) => void;
+    /** Called when a content block starts. */
+    start_content: (event: Omit<PartialContentCompletionEvent, "request_id">) => void;
+    /** Called with content block updates. */
+    update_content: (event: Omit<PartialContentCompletionEvent, "request_id">) => void;
+    /** Called when a content block completes. */
+    complete_content: (event: Omit<FullContentCompletionEvent, "request_id">) => void;
+    /** Called when an error occurs. */
+    error: (error: unknown) => void;
+    /** Called before a request is sent. */
+    before_request: (data: unknown) => void;
+    /** Called with raw request data. */
+    request_raw: (data: unknown) => void;
+    /** Called with raw response data. */
+    response_raw: (data: unknown) => void;
+    /** Called with raw stream chunks. */
+    stream_raw: (data: unknown) => void;
+    /** Called when the stream is cancelled. */
+    cancel: () => void;
+}
+/**
+ * Possible states of a conversation.
+ */
+type ConversationState = "idle" | "awaiting_response" | "streaming_response" | "stopping" | "disposed";
+/**
+ * Request data sent to a model provider.
+ */
+interface ModelRequest {
+    /** The conversation messages. */
+    messages: Message[];
+    /** Available tool definitions. */
+    tools: ToolDefinition[];
+    /** Optional system prompt. */
+    system?: string;
+}
+/**
+ * Interface that model providers must implement.
+ */
+interface ModelProvider {
+    /**
+     * Provider-level context transformers that normalize provider-specific quirks.
+     *
+     * These run before conversation-level transformers and are read fresh on
+     * every request, allowing model routing providers to swap them at runtime.
+     */
+    context_transformers?: ProviderContextTransformer[];
+    /**
+     * Executes a request against the model.
+     *
+     * @param request - The model request containing messages and tools.
+     * @param receiver - The stream receiver for handling response events.
+     * @param cancellation - Token for cancelling the request.
+     * @returns A promise that resolves when the request completes.
+     */
+    execute_request(request: ModelRequest, receiver: StreamReceiver, cancellation: CancellationToken): Promise<void>;
+    /**
+     * Creates a clone of this provider.
+     *
+     * @returns A new instance of the provider with the same configuration.
+     */
+    clone(): ModelProvider;
+}
+
+/**
+ * Configuration for a checkpoint operation.
+ */
+interface CheckpointConfig {
+    /** Arbitrary context passed through to the prompt strategy. */
+    context?: Record<string, unknown>;
+}
+/**
+ * Strategy for generating a checkpoint summary of a conversation.
+ */
+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.
+ */
+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>;
+}
+
+/**
+ * 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.
+ */
+declare class DefaultSummarizationStrategy implements SummarizationStrategy {
+    #private;
+    /**
+     * Builds the summarization prompt from the conversation context. Assembles
+     * the previous checkpoint summary, system prompt, and recent messages into a
+     * structured text block, then appends instructions asking the model to produce
+     * a condensed summary suitable for continuing the conversation.
+     */
+    build_prompt(context: SummarizationContext): Message[];
+}
+
+/**
+ * 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.
+ */
+declare class CheckpointContextTransformer implements ContextTransformer {
+    /**
+     * Replaces all messages before the checkpoint boundary with a synthetic user
+     * message containing the checkpoint summary. Messages after the boundary are
+     * kept intact. Returns messages unchanged if no checkpoint is active.
+     */
+    transform_prompt(messages: Message[], context?: TransformContext): Promise<Message[]>;
+    /** No-op. Returns the message unchanged. */
+    transform_completion(message: AssistantMessage): Promise<AssistantMessage>;
+}
+
+/**
+ * Combines multiple context transformers into a single transformation pipeline.
+ *
+ * Transformers are applied in the order provided.
+ */
+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>;
+}
+
+/**
+ * Context transformer that performs no transformations.
+ *
+ * Returns messages unchanged.
+ */
+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>;
+}
+
+/**
+ * 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.
+ */
+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>;
+}
+
+/**
+ * Policy that combines multiple policies into a single execution chain.
+ *
+ * Policies are applied in the order provided, with each policy wrapping
+ * the execution of the next.
+ */
+declare class CompositePolicy extends Policy {
+    #private;
+    /**
+     * Creates a new composite policy.
+     *
+     * @param policies - The policies to compose. If empty, uses a NoopPolicy.
+     */
+    constructor(...policies: Policy[]);
+    /**
+     * Executes a function with all composed policies applied.
+     *
+     * @template TResult - The return type of the function.
+     * @template TArgs - The argument types of the function.
+     * @param cancellation_token - Token for cancelling the operation.
+     * @param fn - The function to execute.
+     * @param args - Arguments to pass to the function.
+     * @returns A promise that resolves to the policy result.
+     */
+    execute<TResult, TArgs extends unknown[]>(cancellation_token: CancellationToken, fn: (...args: TArgs) => Promise<TResult>, ...args: TArgs): Promise<PolicyResult<TResult>>;
+}
+
+/**
+ * The default policy used when none is passed to Conversation.
+ * A composite that includes retry with exponential backoff. Rate and token limits require attach(conversation) so are not in the default.
+ */
+declare function getDefaultPolicy(): Policy;
+
+/**
+ * Policy that performs no special operations.
+ *
+ * Simply executes the provided function with cancellation support.
+ */
+declare class NoopPolicy extends Policy {
+    /**
+     * Executes a function with no additional policy logic.
+     *
+     * @template TResult - The return type of the function.
+     * @template TArgs - The argument types of the function.
+     * @param cancellation_token - Token for cancelling the operation.
+     * @param fn - The function to execute.
+     * @param args - Arguments to pass to the function.
+     * @returns A promise that resolves to the policy result.
+     */
+    execute<TResult, TArgs extends unknown[]>(cancellation_token: CancellationToken, fn: (...args: TArgs) => Promise<TResult>, ...args: TArgs): Promise<PolicyResult<TResult>>;
+}
+
+/**
+ * Configuration options for rate limiting.
+ */
+type RateLimitPolicyOptions = {
+    /** Maximum number of requests allowed in the time period. */
+    limit: number;
+    /** Time period in milliseconds. */
+    period_ms: number;
+};
+/**
+ * Policy that enforces rate limits on operations.
+ *
+ * Tracks request timestamps and delays execution when the rate limit is exceeded.
+ */
+declare class RateLimitPolicy extends Policy {
+    #private;
+    /**
+     * Creates a new rate limit policy.
+     *
+     * @param options - The rate limiting configuration.
+     */
+    constructor(options: RateLimitPolicyOptions);
+    /**
+     * Attaches this policy to a conversation to track its requests.
+     *
+     * @param conversation - The conversation to monitor.
+     */
+    attach(conversation: Conversation): void;
+    /**
+     * Executes a function with rate limiting applied.
+     *
+     * @template TResult - The return type of the function.
+     * @template TArgs - The argument types of the function.
+     * @param cancellation_token - Token for cancelling the operation.
+     * @param fn - The function to execute.
+     * @param args - Arguments to pass to the function.
+     * @returns A promise that resolves to the policy result.
+     */
+    execute<TResult, TArgs extends unknown[]>(cancellation_token: CancellationToken, fn: (...args: TArgs) => Promise<TResult>, ...args: TArgs): Promise<PolicyResult<TResult>>;
+}
+
+/**
+ * Configuration options for retry behavior.
+ */
+interface RetryPolicyOptions {
+    /** Maximum number of attempts (including the initial attempt). */
+    max_attempts: number;
+    /** Initial backoff delay in milliseconds. */
+    initial_backoff_ms: number;
+    /** Factor by which to multiply the backoff after each retry. */
+    backoff_factor: number;
+    /** Optional function to determine if an error is retryable. */
+    retryable?: (result: PolicyErrorResult) => boolean;
+}
+declare function defaultRetryable(result: PolicyErrorResult): boolean;
+/**
+ * Policy that retries failed operations with exponential backoff.
+ *
+ * @template _TResult - The result type of the operation.
+ */
+declare class RetryPolicy<_TResult> extends Policy {
+    #private;
+    /**
+     * Creates a new retry policy.
+     *
+     * @param options - The retry configuration options.
+     */
+    constructor(options: RetryPolicyOptions);
+    /**
+     * Executes a function with retry logic applied.
+     *
+     * @template TResult - The return type of the function.
+     * @template TArgs - The argument types of the function.
+     * @param cancellation_token - Token for cancelling the operation.
+     * @param fn - The function to execute.
+     * @param args - Arguments to pass to the function.
+     * @returns A promise that resolves to the policy result.
+     */
+    execute<TResult, TArgs extends unknown[]>(cancellation_token: CancellationToken, fn: (...args: TArgs) => Promise<TResult>, ...args: TArgs): Promise<PolicyResult<TResult>>;
+}
+
+/**
+ * Record of token usage for a single request.
+ */
+interface TokenRecord {
+    /** When this usage occurred. */
+    timestamp: number;
+    /** Number of input tokens consumed. */
+    input_tokens: number;
+    /** Number of output tokens generated. */
+    output_tokens: number;
+}
+/**
+ * Base options for token limit policy.
+ */
+type BaseOptions = {
+    /** Time period in milliseconds for the token budget. */
+    period_ms: number;
+};
+/**
+ * Options for separate input and output token limits.
+ */
+type InputOutputTokenOptions = {
+    /** Maximum input tokens allowed per period. */
+    input_tokens_per_period: number;
+    /** Maximum output tokens allowed per period. */
+    output_tokens_per_period: number;
+};
+/**
+ * Options for a combined total token limit.
+ */
+type TotalTokenOptions = {
+    /** Maximum total tokens (input + output) allowed per period. */
+    total_tokens_per_period: number;
+};
+/**
+ * Configuration options for token limit policy.
+ *
+ * Can specify either separate input/output limits or a combined total limit.
+ */
+type TokenLimitPolicyOptions = BaseOptions & (InputOutputTokenOptions | TotalTokenOptions);
+/**
+ * Policy that enforces token usage limits over a time period.
+ *
+ * Tracks token consumption and delays execution when limits are exceeded.
+ */
+declare class TokenLimitPolicy extends Policy {
+    #private;
+    /**
+     * Creates a new token limit policy.
+     *
+     * @param options - The token limit configuration.
+     */
+    constructor(options: TokenLimitPolicyOptions);
+    /**
+     * Executes a function with token limit enforcement applied.
+     *
+     * @template TResult - The return type of the function.
+     * @template TArgs - The argument types of the function.
+     * @param cancellation_token - Token for cancelling the operation.
+     * @param fn - The function to execute.
+     * @param args - Arguments to pass to the function.
+     * @returns A promise that resolves to the policy result.
+     */
+    execute<TResult, TArgs extends unknown[]>(cancellation_token: CancellationToken, fn: (...args: TArgs) => Promise<TResult>, ...args: TArgs): Promise<PolicyResult<TResult>>;
+    /**
+     * Attaches this policy to a conversation to track its token usage.
+     *
+     * @param conversation - The conversation to monitor.
+     */
+    attach(conversation: Conversation): void;
+}
+
+/**
+ * Returns undefined if the value is empty (empty array or object with no defined keys).
+ *
+ * @template T - The type of the value.
+ * @param obj - The value to check.
+ * @returns The value if non-empty, otherwise undefined.
+ */
+declare function undefined_if_empty<T = unknown>(obj: T): T | undefined;
+/**
+ * Recursively merges two values together.
+ *
+ * For objects, properties are merged recursively. For arrays, elements are concatenated.
+ * For primitives, the supplemental value replaces the original.
+ *
+ * @template T - The type of values being merged.
+ * @param original - The original value.
+ * @param supplemental - The value to merge in.
+ * @returns The merged result.
+ */
+declare function deep_merge<T = unknown>(original: T, supplemental: T): T;
+
+/**
+ * Makes all properties of an object and their nested properties optional.
+ *
+ * @template T - The object type to make deeply partial.
+ */
+type DeepPartial<T> = Partial<{
+    [K in keyof T]: Partial<T[K]>;
+}>;
+/**
+ * Flattens intersection types for better IDE display.
+ *
+ * @template T - The type to prettify.
+ */
+type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+
+export { type ArrayParameterType, type AssistantContent, type AssistantMessage, type BooleanParameterType, CancellationToken, CancellationTokenSource, type ChangeEvent, type CheckpointConfig, CheckpointContextTransformer, type CheckpointState, type CompletionResponseData, type CompletionStreamingResponseData, CompositeContextTransformer, CompositePolicy, type Content, type ContextTransformer, Conversation, type ConversationEvents, type ConversationState, type DeepPartial, DefaultSummarizationStrategy, type EnumParameterType, type ErrorRequestEvent, type ExtendableContent, type FullContentCompletionEvent, type FullMessageCompletionEvent, type LifecycleErrorEvent, type Message, type ModelProvider, type ModelRequest, NoopContextTransformer, NoopPolicy, type NumberParameterType, type ObjectParameterType, OperationCanceledError, type ParameterType, type PartialContentCompletionEvent, type PartialMessageCompletionEvent, Policy, type PolicyErrorResult, type PolicyResult, type PolicySuccessResult, type Prettify, type PrimitiveParameterType, type PromptRequestData, type ProviderContextTransformer, RateLimitPolicy, type RateLimitPolicyOptions, type RawContent, type RawEvent, type RawRequestEvent, type RequestData, RetryPolicy, type RetryPolicyOptions, StreamListener, type StreamListenerPayload, type StreamReceiver, type StringParameterType, type SummarizationContext, type SummarizationStrategy, type TextContent, type ThinkingMessageContent, TokenLimitPolicy, type TokenLimitPolicyOptions, type TokenRecord, type TokenStats, TokenTracker, type Tool, type ToolClass, type ToolContent, type ToolContext, ToolContextTransformer, type ToolDefinition, type ToolErrorResult, type ToolParameterDefinition, type ToolResult, type ToolResultContent, type ToolSuccessResult, type TransformContext, type Usage, type UserContent, type UserMessage, Workflow, type WorkflowEndEvent, type WorkflowEvents, WorkflowManager, type WorkflowManagerEvents, type WorkflowState, deep_merge, defaultRetryable, getDefaultPolicy, peek_generator, sleep, undefined_if_empty };