@simulacra-ai/core 0.0.3 → 0.0.4

package/dist/index.cjs

@@ -0,0 +1,2293 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __knownSymbol = (name, symbol) => (symbol = Symbol[name]) ? symbol : /* @__PURE__ */ Symbol.for("Symbol." + name);
+var __typeError = (msg) => {
+  throw TypeError(msg);
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var __using = (stack, value, async) => {
+  if (value != null) {
+    if (typeof value !== "object" && typeof value !== "function") __typeError("Object expected");
+    var dispose, inner;
+    if (async) dispose = value[__knownSymbol("asyncDispose")];
+    if (dispose === void 0) {
+      dispose = value[__knownSymbol("dispose")];
+      if (async) inner = dispose;
+    }
+    if (typeof dispose !== "function") __typeError("Object not disposable");
+    if (inner) dispose = function() {
+      try {
+        inner.call(this);
+      } catch (e) {
+        return Promise.reject(e);
+      }
+    };
+    stack.push([async, dispose, value]);
+  } else if (async) {
+    stack.push([async]);
+  }
+  return value;
+};
+var __callDispose = (stack, error, hasError) => {
+  var E = typeof SuppressedError === "function" ? SuppressedError : function(e, s, m, _) {
+    return _ = Error(m), _.name = "SuppressedError", _.error = e, _.suppressed = s, _;
+  };
+  var fail = (e) => error = hasError ? new E(e, error, "An error was suppressed during disposal") : (hasError = true, e);
+  var next = (it) => {
+    while (it = stack.pop()) {
+      try {
+        var result = it[1] && it[1].call(it[2]);
+        if (it[0]) return Promise.resolve(result).then(next, (e) => (fail(e), next()));
+      } catch (e) {
+        fail(e);
+      }
+    }
+    if (hasError) throw error;
+  };
+  return next();
+};
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  CancellationToken: () => CancellationToken,
+  CancellationTokenSource: () => CancellationTokenSource,
+  CheckpointContextTransformer: () => CheckpointContextTransformer,
+  CompositeContextTransformer: () => CompositeContextTransformer,
+  CompositePolicy: () => CompositePolicy,
+  Conversation: () => Conversation,
+  DefaultSummarizationStrategy: () => DefaultSummarizationStrategy,
+  NoopContextTransformer: () => NoopContextTransformer,
+  NoopPolicy: () => NoopPolicy,
+  OperationCanceledError: () => OperationCanceledError,
+  Policy: () => Policy,
+  RateLimitPolicy: () => RateLimitPolicy,
+  RetryPolicy: () => RetryPolicy,
+  StreamListener: () => StreamListener,
+  TokenLimitPolicy: () => TokenLimitPolicy,
+  TokenTracker: () => TokenTracker,
+  ToolContextTransformer: () => ToolContextTransformer,
+  Workflow: () => Workflow,
+  WorkflowManager: () => WorkflowManager,
+  deep_merge: () => deep_merge,
+  defaultRetryable: () => defaultRetryable,
+  getDefaultPolicy: () => getDefaultPolicy,
+  peek_generator: () => peek_generator,
+  sleep: () => sleep,
+  undefined_if_empty: () => undefined_if_empty
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/checkpoints/default-summarization-strategy.ts
+var DefaultSummarizationStrategy = class {
+  /**
+   * 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) {
+    const sections = [];
+    if (context.previous_checkpoint) {
+      sections.push(`## Previous Checkpoint Summary
+${context.previous_checkpoint.summary}`);
+    }
+    if (context.system) {
+      sections.push(`## System Prompt
+${context.system}`);
+    }
+    if (context.messages.length > 0) {
+      sections.push(`## Conversation
+${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 void 0;
+        }
+      }).filter(Boolean);
+      return `${role}: ${parts.join("\n")}`;
+    }).join("\n\n");
+  }
+};
+
+// src/conversations/conversation.ts
+var import_node_crypto = __toESM(require("crypto"), 1);
+var import_node_events2 = __toESM(require("events"), 1);
+var import_promises = require("timers/promises");
+
+// src/context-transformers/checkpoint-context-transformer.ts
+var CheckpointContextTransformer = class {
+  /**
+   * 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.
+   */
+  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)];
+  }
+  /** No-op. Returns the message unchanged. */
+  transform_completion(message) {
+    return Promise.resolve(message);
+  }
+};
+
+// src/context-transformers/composite-context-transformer.ts
+var CompositeContextTransformer = class {
+  #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;
+  }
+};
+
+// src/context-transformers/tool-context-transformer.ts
+var ToolContextTransformer = class {
+  /**
+   * 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);
+  }
+};
+
+// src/policies/types.ts
+var Policy = class {
+};
+
+// src/policies/noop-policy.ts
+var NoopPolicy = 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.
+   */
+  async execute(cancellation_token, fn, ...args) {
+    try {
+      cancellation_token.throw_if_cancellation_requested();
+      return {
+        result: true,
+        value: await Promise.race([fn(...args), cancellation_token.await_cancellation()]),
+        metadata: { policy: _NoopPolicy.name }
+      };
+    } catch (error) {
+      return {
+        result: false,
+        error,
+        metadata: { policy: _NoopPolicy.name }
+      };
+    }
+  }
+};
+
+// src/policies/composite-policy.ts
+var CompositePolicy = class _CompositePolicy extends Policy {
+  #policies;
+  /**
+   * Creates a new composite policy.
+   *
+   * @param policies - The policies to compose. If empty, uses a NoopPolicy.
+   */
+  constructor(...policies) {
+    super();
+    this.#policies = policies.length > 0 ? policies : [new NoopPolicy()];
+  }
+  /**
+   * 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.
+   */
+  async execute(cancellation_token, fn, ...args) {
+    let current_fn = fn;
+    const policy_metadata = {};
+    const execution_order = [];
+    for (let i = this.#policies.length - 1; i >= 0; i--) {
+      cancellation_token.throw_if_cancellation_requested();
+      const policy = this.#policies[i];
+      const policy_name = `${policy.constructor.name}[${i}]`;
+      execution_order.push(policy_name);
+      const wrapped_fn = current_fn;
+      current_fn = async (...wrapped_args) => {
+        const policy_result = await policy.execute(cancellation_token, wrapped_fn, ...wrapped_args);
+        policy_metadata[policy_name] = policy_result.metadata;
+        if (policy_result.result) {
+          return policy_result.value;
+        } else {
+          throw policy_result.error;
+        }
+      };
+    }
+    try {
+      return {
+        result: true,
+        value: await current_fn(...args),
+        metadata: {
+          policy: _CompositePolicy.name,
+          policies: policy_metadata,
+          execution_order: [...execution_order].reverse(),
+          policy_count: this.#policies.length
+        }
+      };
+    } catch (error) {
+      return {
+        result: false,
+        error,
+        metadata: {
+          policy: _CompositePolicy.name,
+          policies: policy_metadata,
+          execution_order: [...execution_order].reverse(),
+          policy_count: this.#policies.length
+        }
+      };
+    }
+  }
+};
+
+// src/utils/async.ts
+var import_node_events = __toESM(require("events"), 1);
+var CancellationToken = class _CancellationToken {
+  #source;
+  /**
+   * Creates a new cancellation token.
+   *
+   * @param source - Optional source that controls this token.
+   */
+  constructor(source) {
+    this.#source = source;
+  }
+  /**
+   * Whether cancellation has been requested.
+   */
+  get is_cancellation_requested() {
+    return !!this.#source?.is_cancelled;
+  }
+  /**
+   * Registers a one-time handler for cancellation.
+   *
+   * @param event - The event name (always "cancel").
+   * @param handler - The callback to invoke when cancelled.
+   */
+  once(event, handler) {
+    this.#source?.once(event, handler);
+  }
+  /**
+   * Removes a cancellation handler.
+   *
+   * @param event - The event name (always "cancel").
+   * @param handler - The callback to remove.
+   */
+  off(event, handler) {
+    this.#source?.off(event, handler);
+  }
+  /**
+   * Throws an error if cancellation has been requested.
+   */
+  throw_if_cancellation_requested() {
+    if (this.is_cancellation_requested) {
+      throw new OperationCanceledError(this);
+    }
+  }
+  /**
+   * Creates a promise that rejects when cancellation is requested.
+   *
+   * @returns A promise that never resolves but rejects on cancellation.
+   */
+  await_cancellation() {
+    return new Promise(
+      (_, reject) => this.once("cancel", () => reject(new OperationCanceledError(this)))
+    );
+  }
+  /**
+   * Creates an empty cancellation token that can never be cancelled.
+   *
+   * @returns A new cancellation token with no source.
+   */
+  static empty() {
+    return new _CancellationToken();
+  }
+};
+var CancellationTokenSource = class {
+  #event_emitter = new import_node_events.default();
+  #is_cancelled = false;
+  #is_disposed = false;
+  #token;
+  /**
+   * Disposes the cancellation token source.
+   *
+   * This method is called automatically when using the `using` keyword.
+   */
+  [Symbol.dispose]() {
+    if (this.#is_disposed) {
+      throw new Error("invalid state");
+    }
+    this.#is_disposed = true;
+    this.#event_emitter.removeAllListeners();
+  }
+  /**
+   * Gets a cancellation token associated with this source.
+   */
+  get token() {
+    if (!this.#token) {
+      this.#token = new CancellationToken(this);
+    }
+    return this.#token;
+  }
+  /**
+   * Whether cancellation has been triggered.
+   */
+  get is_cancelled() {
+    return this.#is_cancelled;
+  }
+  /**
+   * Registers a one-time handler for cancellation.
+   *
+   * @param event - The event name (always "cancel").
+   * @param handler - The callback to invoke when cancelled.
+   */
+  once(event, handler) {
+    if (this.#is_cancelled) {
+      throw new OperationCanceledError(new CancellationToken(this));
+    }
+    if (this.#is_disposed) {
+      throw new Error("invalid state");
+    }
+    this.#event_emitter.once(event, handler);
+  }
+  /**
+   * Removes a cancellation handler.
+   *
+   * @param event - The event name (always "cancel").
+   * @param handler - The callback to remove.
+   */
+  off(event, handler) {
+    this.#event_emitter.off(event, handler);
+  }
+  /**
+   * Triggers cancellation for all associated tokens.
+   */
+  cancel() {
+    if (this.#is_cancelled) {
+      throw new OperationCanceledError(new CancellationToken(this));
+    }
+    this.#is_cancelled = true;
+    this.#event_emitter.emit("cancel");
+  }
+};
+var OperationCanceledError = class extends Error {
+  #token;
+  /**
+   * Creates a new operation cancelled error.
+   *
+   * @param token - The cancellation token associated with this error.
+   */
+  constructor(token) {
+    super("The operation was cancelled", { cause: "cancelled" });
+    this.#token = token;
+  }
+  /**
+   * The cancellation token associated with this error.
+   */
+  get token() {
+    return this.#token;
+  }
+};
+function sleep(ms, cancellation_token) {
+  return new Promise((resolve, reject) => {
+    if (cancellation_token) {
+      const token = cancellation_token;
+      const on_cancel = () => {
+        clearTimeout(timeout);
+        reject(new OperationCanceledError(token));
+      };
+      const on_timeout = () => {
+        token.off("cancel", on_cancel);
+        resolve();
+      };
+      const timeout = setTimeout(on_timeout, ms);
+      if (token.is_cancellation_requested) {
+        clearTimeout(timeout);
+        reject(new OperationCanceledError(token));
+      } else {
+        token.once("cancel", on_cancel);
+      }
+    } else {
+      setTimeout(resolve, ms);
+    }
+  });
+}
+async function peek_generator(generator) {
+  const iterator = generator[Symbol.asyncIterator]();
+  let result = await iterator.next();
+  const wrapper = (async function* () {
+    while (true) {
+      if (result.done) {
+        break;
+      }
+      yield result.value;
+      result = await iterator.next();
+    }
+  })();
+  return {
+    peeked_value: result.value,
+    generator: wrapper
+  };
+}
+
+// src/policies/retry-policy.ts
+var RETRYABLE_NETWORK_ERROR_CODES = /* @__PURE__ */ new Set([
+  "ECONNRESET",
+  "ECONNREFUSED",
+  "ECONNABORTED",
+  "ETIMEDOUT",
+  "ENETUNREACH",
+  "EHOSTUNREACH",
+  "EPIPE",
+  "EAI_AGAIN",
+  "UND_ERR_CONNECT_TIMEOUT",
+  "UND_ERR_SOCKET"
+]);
+var RETRYABLE_HTTP_STATUS_CODES = /* @__PURE__ */ new Set([408, 429, 500, 502, 503, 504, 529]);
+function defaultRetryable(result) {
+  const error = result.error;
+  if (error !== null && error !== void 0 && typeof error === "object" && "status" in error) {
+    const status = error.status;
+    if (typeof status === "number") {
+      return RETRYABLE_HTTP_STATUS_CODES.has(status);
+    }
+  }
+  if (error !== null && error !== void 0 && typeof error === "object") {
+    const code = error.code;
+    if (typeof code === "string" && RETRYABLE_NETWORK_ERROR_CODES.has(code)) {
+      return true;
+    }
+    const cause = error.cause;
+    if (cause !== null && cause !== void 0 && typeof cause === "object") {
+      const causeCode = cause.code;
+      if (typeof causeCode === "string" && RETRYABLE_NETWORK_ERROR_CODES.has(causeCode)) {
+        return true;
+      }
+    }
+  }
+  if (error instanceof Error) {
+    const msg = error.message.toLowerCase();
+    if (msg.includes("timeout") || msg.includes("econnreset") || msg.includes("econnrefused") || msg.includes("socket hang up") || msg.includes("network error") || msg.includes("fetch failed")) {
+      return true;
+    }
+  }
+  return false;
+}
+var RetryPolicy = class _RetryPolicy extends Policy {
+  #options;
+  /**
+   * Creates a new retry policy.
+   *
+   * @param options - The retry configuration options.
+   */
+  constructor(options) {
+    super();
+    this.#options = { ...options, retryable: options.retryable ?? defaultRetryable };
+  }
+  /**
+   * 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.
+   */
+  async execute(cancellation_token, fn, ...args) {
+    let attempt = 1;
+    let backoff_ms = this.#options.initial_backoff_ms;
+    const metadata = {
+      policy: _RetryPolicy.name,
+      attempts: 0,
+      ...this.#options
+    };
+    while (true) {
+      cancellation_token.throw_if_cancellation_requested();
+      try {
+        const value = await Promise.race([fn(...args), cancellation_token.await_cancellation()]);
+        metadata.attempts = attempt;
+        return {
+          result: true,
+          value,
+          metadata
+        };
+      } catch (error) {
+        metadata.attempts = attempt;
+        const result = {
+          result: false,
+          error,
+          metadata
+        };
+        if (attempt >= this.#options.max_attempts || !this.#options.retryable(result)) {
+          return result;
+        }
+        await sleep(backoff_ms, cancellation_token);
+        metadata.lastError = error;
+        metadata.lastBackoffMs = backoff_ms;
+        backoff_ms *= this.#options.backoff_factor;
+        attempt++;
+      }
+    }
+  }
+};
+
+// src/policies/default-policy.ts
+function getDefaultPolicy() {
+  return new CompositePolicy(
+    new RetryPolicy({
+      max_attempts: 3,
+      initial_backoff_ms: 1e3,
+      backoff_factor: 2
+    })
+  );
+}
+
+// src/conversations/stream-listener.ts
+var StreamListener = class {
+  #listener;
+  #is_disposed = false;
+  /**
+   * Creates a new stream listener.
+   *
+   * @param listener - The callback to invoke with stream events.
+   */
+  constructor(listener) {
+    this.#listener = listener;
+  }
+  /**
+   * Disposes the stream listener.
+   *
+   * This method is called automatically when using the `using` keyword.
+   */
+  [Symbol.dispose]() {
+    this.#is_disposed = true;
+  }
+  /**
+   * Creates a StreamReceiver that forwards all events to the listener.
+   *
+   * @returns A new stream receiver instance.
+   */
+  create_receiver() {
+    const receiver = {
+      start_message: (...args) => this.#receive({ event: "start_message", payload: args }),
+      update_message: (...args) => this.#receive({ event: "update_message", payload: args }),
+      complete_message: (...args) => this.#receive({ event: "complete_message", payload: args }),
+      start_content: (...args) => this.#receive({ event: "start_content", payload: args }),
+      update_content: (...args) => this.#receive({ event: "update_content", payload: args }),
+      complete_content: (...args) => this.#receive({ event: "complete_content", payload: args }),
+      error: (...args) => this.#receive({ event: "error", payload: args }),
+      before_request: (...args) => this.#receive({ event: "before_request", payload: args }),
+      request_raw: (...args) => this.#receive({ event: "request_raw", payload: args }),
+      response_raw: (...args) => this.#receive({ event: "response_raw", payload: args }),
+      stream_raw: (...args) => this.#receive({ event: "stream_raw", payload: args }),
+      cancel: (...args) => this.#receive({ event: "cancel", payload: args })
+    };
+    return receiver;
+  }
+  #receive = (payload) => {
+    if (this.#is_disposed) {
+      return;
+    }
+    try {
+      const result = this.#listener(payload);
+      if (result && typeof result === "object" && "catch" in result) {
+        result.catch((error) => {
+          if (!this.#is_disposed && payload.event !== "error") {
+            this.#listener({ event: "error", payload: [error] });
+          }
+        });
+      }
+    } catch (error) {
+      if (!this.#is_disposed && payload.event !== "error") {
+        this.#listener({ event: "error", payload: [error] });
+      }
+    }
+  };
+};
+
+// src/conversations/conversation.ts
+var Conversation = class _Conversation {
+  #event_emitter;
+  #provider;
+  #policy;
+  #context_transformer;
+  #summarization_strategy;
+  #id = import_node_crypto.default.randomUUID();
+  #state = "idle";
+  #system;
+  #toolkit = [];
+  #messages = [];
+  #checkpoint_state;
+  #is_checkpoint = false;
+  /**
+   * 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, policy = getDefaultPolicy(), context_transformer = new CompositeContextTransformer([
+    new ToolContextTransformer(),
+    new CheckpointContextTransformer()
+  ]), summarization_strategy = new DefaultSummarizationStrategy()) {
+    this.#event_emitter = new import_node_events2.default();
+    this.#event_emitter.setMaxListeners(0);
+    this.#provider = provider;
+    this.#policy = policy;
+    this.#context_transformer = context_transformer;
+    this.#summarization_strategy = summarization_strategy;
+  }
+  /**
+   * The unique identifier for this conversation.
+   */
+  get id() {
+    return this.#id;
+  }
+  set id(value) {
+    this.#id = value;
+  }
+  /**
+   * The current state of the conversation.
+   */
+  get state() {
+    return this.#state;
+  }
+  /**
+   * The system prompt for this conversation.
+   */
+  get system() {
+    return this.#system;
+  }
+  set system(value) {
+    this.#system = value;
+  }
+  /**
+   * The collection of tools available to the model in this conversation.
+   */
+  get toolkit() {
+    return Object.freeze([...this.#toolkit]);
+  }
+  set toolkit(value) {
+    if (this.#state === "disposed") {
+      throw new Error("invalid state");
+    }
+    this.#toolkit = [...value];
+  }
+  /**
+   * The conversation message history.
+   */
+  get messages() {
+    return Object.freeze([...this.#messages.map((m) => Object.freeze({ ...m }))]);
+  }
+  /**
+   * 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() {
+    return this.#checkpoint_state ? Object.freeze({ ...this.#checkpoint_state }) : void 0;
+  }
+  set checkpoint_state(value) {
+    this.#checkpoint_state = value;
+  }
+  /**
+   * 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() {
+    return this.#is_checkpoint;
+  }
+  /**
+   * 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]() {
+    if (this.state === "disposed") {
+      throw new Error("invalid state");
+    }
+    const previous = this.#state;
+    this.#event_emitter.emit("dispose", this);
+    this.#state = "disposed";
+    this.#event_emitter.emit("state_change", { current: this.#state, previous }, this);
+    this.#event_emitter.removeAllListeners();
+  }
+  /**
+   * 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.
+   */
+  async prompt(prompt) {
+    return await this.send_message([
+      {
+        timestamp: Date.now(),
+        type: "text",
+        text: prompt
+      }
+    ]);
+  }
+  /**
+   * 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.
+   */
+  async send_message(contents) {
+    if (this.state !== "idle") {
+      throw new Error("invalid state");
+    }
+    let prompt_message = {
+      timestamp: Date.now(),
+      role: "user",
+      content: contents.map((c) => ({
+        timestamp: Date.now(),
+        ...c
+      })).map((c) => ({
+        ...c,
+        id: c.id ?? import_node_crypto.default.createHash("sha1").update(JSON.stringify(c)).digest("hex")
+      }))
+    };
+    prompt_message = {
+      ...prompt_message,
+      id: prompt_message.id ?? import_node_crypto.default.createHash("sha1").update(JSON.stringify(prompt_message)).digest("hex")
+    };
+    let request_id;
+    let result;
+    let policy_result;
+    try {
+      var _stack = [];
+      try {
+        const stream_listener = new StreamListener(async ({ event, payload }) => {
+          switch (event) {
+            case "start_message": {
+              const [{ message, usage }] = payload;
+              this.#set_state("streaming_response");
+              this.#event_emitter.emit("message_start", { request_id, usage, message }, this);
+              break;
+            }
+            case "update_message": {
+              const [{ message, usage }] = payload;
+              this.#event_emitter.emit("message_update", { request_id, usage, message }, this);
+              break;
+            }
+            case "complete_message": {
+              const [data] = payload;
+              let message = identify_message(data.message);
+              for (const t of this.#provider.context_transformers ?? []) {
+                if (t.transform_completion) {
+                  message = await t.transform_completion(message);
+                }
+              }
+              message = await this.#context_transformer.transform_completion(message);
+              const has_tool_calls = message.content.some((c) => c.type === "tool");
+              const stop_reason = has_tool_calls ? "tool_use" : data.stop_reason;
+              this.#set_state("idle");
+              this.#messages.push(prompt_message, message);
+              this.#event_emitter.emit(
+                "message_complete",
+                { request_id, ...data, message, stop_reason },
+                this
+              );
+              break;
+            }
+            case "start_content": {
+              const [data] = payload;
+              this.#event_emitter.emit("content_start", { request_id, ...data }, this);
+              break;
+            }
+            case "update_content": {
+              const [data] = payload;
+              this.#event_emitter.emit("content_update", { request_id, ...data }, this);
+              break;
+            }
+            case "complete_content": {
+              const [data] = payload;
+              this.#event_emitter.emit("content_complete", { request_id, ...data }, this);
+              break;
+            }
+            case "error": {
+              stream_listener[Symbol.dispose]();
+              const [error] = payload;
+              if (this.state !== "disposed") {
+                this.#set_state("idle");
+              }
+              this.#event_emitter.emit(
+                "request_error",
+                { request_id, message: prompt_message, error },
+                {},
+                this
+              );
+              break;
+            }
+            case "before_request": {
+              const [data] = payload;
+              this.#event_emitter.emit("before_request", { data }, this);
+              break;
+            }
+            case "request_raw": {
+              const [data] = payload;
+              this.#event_emitter.emit("raw_request", { request_id, data }, this);
+              break;
+            }
+            case "response_raw": {
+              const [data] = payload;
+              this.#event_emitter.emit("raw_response", { request_id, data }, this);
+              break;
+            }
+            case "stream_raw": {
+              const [data] = payload;
+              this.#event_emitter.emit("raw_stream", { request_id, data }, this);
+              break;
+            }
+            case "cancel": {
+              stream_listener[Symbol.dispose]();
+              if (this.state !== "disposed") {
+                this.#set_state("idle");
+              }
+              break;
+            }
+          }
+        });
+        const source = __using(_stack, new CancellationTokenSource());
+        const on_state_change = ({ current }) => {
+          if (current === "stopping") {
+            if (!source.is_cancelled) {
+              source.cancel();
+            }
+          }
+          if (current === "idle" || current === "disposed") {
+            this.off("state_change", on_state_change);
+          }
+        };
+        this.on("state_change", on_state_change);
+        const transformed_messages = await this.#get_prompt_context([
+          ...this.#messages,
+          prompt_message
+        ]);
+        const tool_definitions = this.#toolkit.map((t) => t.get_definition());
+        const result_promise = this.#policy.execute(source.token, async () => {
+          await this.#provider.execute_request(
+            {
+              messages: transformed_messages,
+              tools: tool_definitions,
+              system: this.#system
+            },
+            stream_listener.create_receiver(),
+            source.token
+          );
+          return { message: prompt_message };
+        });
+        this.#event_emitter.emit("prompt_send", { message: prompt_message }, this);
+        this.#set_state("awaiting_response");
+        policy_result = await Promise.race([
+          result_promise,
+          new Promise((resolve) => {
+            const on_state_change2 = ({ current }) => {
+              if (current === "stopping") {
+                stream_listener[Symbol.dispose]();
+                resolve(void 0);
+              } else if (current === "disposed") {
+                stream_listener[Symbol.dispose]();
+                resolve(void 0);
+              } else if (current === "streaming_response") {
+                this.off("state_change", on_state_change2);
+              }
+            };
+            this.on("state_change", on_state_change2);
+          })
+        ]);
+        request_id = request_id ?? import_node_crypto.default.randomUUID();
+        result = {
+          message: prompt_message,
+          request_id
+        };
+        if (policy_result) {
+          if (!policy_result.result) {
+            throw policy_result.error;
+          }
+          result = { ...result, ...policy_result.value };
+          this.#event_emitter.emit("request_success", result, policy_result.metadata ?? {}, this);
+        } else {
+          if (this.#state !== "disposed") {
+            this.#set_state("idle");
+          }
+        }
+      } catch (_) {
+        var _error = _, _hasError = true;
+      } finally {
+        __callDispose(_stack, _error, _hasError);
+      }
+    } catch (error) {
+      this.#event_emitter.emit(
+        "request_error",
+        { request_id, message: prompt_message, error },
+        {},
+        this
+      );
+      if (this.#state !== "disposed") {
+        this.#set_state("idle");
+      }
+    }
+    return result;
+  }
+  /**
+   * 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(event_name, listener) {
+    this.#event_emitter.once(event_name, listener);
+  }
+  /**
+   * 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(event_name, listener) {
+    this.#event_emitter.on(event_name, listener);
+  }
+  /**
+   * 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(event_name, listener) {
+    this.#event_emitter.off(event_name, listener);
+  }
+  /**
+   * Cancels an in-progress model response.
+   *
+   * Transitions the conversation to the "stopping" state, which triggers
+   * cancellation of the underlying request.
+   */
+  cancel_response() {
+    if (this.state === "idle" || this.state === "disposed") {
+      throw new Error("invalid state");
+    }
+    this.#set_state("stopping");
+  }
+  /**
+   * Clears all messages from the conversation history.
+   *
+   * Can only be called when the conversation is idle.
+   */
+  clear() {
+    if (this.state !== "idle") {
+      throw new Error("invalid state");
+    }
+    this.#messages = [];
+    this.#set_state("idle");
+  }
+  /**
+   * Loads messages into the conversation history.
+   *
+   * @param messages - The messages to load.
+   */
+  load(messages) {
+    if (this.state !== "idle") {
+      throw new Error("invalid state");
+    }
+    this.#messages = [...messages.map((m) => Object.freeze({ ...m }))];
+  }
+  /**
+   * 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, id, system_prompt, is_checkpoint) {
+    const child = new _Conversation(
+      this.#provider.clone(),
+      this.#policy,
+      this.#context_transformer,
+      this.#summarization_strategy
+    );
+    if (id) {
+      child.id = id;
+    }
+    if (system_prompt) {
+      child.system = system_prompt;
+    }
+    if (fork_session) {
+      child.load(this.#messages);
+    }
+    if (is_checkpoint) {
+      child.#is_checkpoint = true;
+    }
+    this.#attach_child_event(child, "state_change");
+    this.#attach_child_event(child, "checkpoint_begin");
+    this.#attach_child_event(child, "checkpoint_complete");
+    this.#attach_child_event(child, "prompt_send");
+    this.#attach_child_event(child, "message_start");
+    this.#attach_child_event(child, "message_update");
+    this.#attach_child_event(child, "message_complete");
+    this.#attach_child_event(child, "content_start");
+    this.#attach_child_event(child, "content_update");
+    this.#attach_child_event(child, "content_complete");
+    this.#attach_child_event(child, "request_success");
+    this.#attach_child_event(child, "request_error");
+    this.#attach_child_event(child, "before_request");
+    this.#attach_child_event(child, "raw_request");
+    this.#attach_child_event(child, "raw_response");
+    this.#attach_child_event(child, "raw_stream");
+    this.#attach_child_event(child, "create_child");
+    this.#attach_child_event(child, "child_event");
+    this.#attach_child_event(child, "lifecycle_error");
+    this.#attach_child_event(child, "dispose");
+    this.#event_emitter.emit("create_child", child, this);
+    return child;
+  }
+  /**
+   * 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.
+   */
+  async checkpoint(config) {
+    if (this.state !== "idle") {
+      throw new Error("invalid state");
+    }
+    if (this.#messages.length === 0) {
+      throw new Error("no messages to checkpoint");
+    }
+    const messages_since = this.#get_messages_since_checkpoint();
+    if (messages_since.length === 0) {
+      throw new Error("no new messages since last checkpoint");
+    }
+    const prompt_messages = this.#summarization_strategy.build_prompt({
+      session_id: this.#id,
+      messages: messages_since,
+      previous_checkpoint: this.#checkpoint_state,
+      system: this.#system,
+      context: config?.context
+    });
+    const child = this.spawn_child(false, void 0, void 0, true);
+    this.#event_emitter.emit("checkpoint_begin", child, this);
+    try {
+      if (prompt_messages.length > 1) {
+        child.load(prompt_messages.slice(0, -1));
+      }
+      const last = prompt_messages[prompt_messages.length - 1];
+      if (last.role !== "user") {
+        throw new Error("checkpoint prompt strategy must return a user message last");
+      }
+      const response_promise = new Promise((resolve, reject) => {
+        child.once("message_complete", ({ message }) => resolve(message));
+        child.once(
+          "request_error",
+          ({ error }) => reject(error instanceof Error ? error : new Error(String(error)))
+        );
+      });
+      await child.send_message(last.content);
+      const response = await response_promise;
+      const summary = response.content.filter((c) => c.type === "text").map((c) => c.text).join("\n");
+      if (!summary) {
+        throw new Error("checkpoint produced an empty summary");
+      }
+      const boundary = this.#messages[this.#messages.length - 1];
+      if (!boundary.id) {
+        throw new Error("boundary message has no id");
+      }
+      const state = {
+        message_id: boundary.id,
+        summary
+      };
+      this.#checkpoint_state = state;
+      this.#event_emitter.emit("checkpoint_complete", state, this);
+      return state;
+    } finally {
+      if (child.state !== "disposed") {
+        child[Symbol.dispose]();
+      }
+    }
+  }
+  #get_messages_since_checkpoint() {
+    const checkpointState = this.#checkpoint_state;
+    if (!checkpointState) {
+      return [...this.#messages];
+    }
+    const idx = this.#messages.findIndex((m) => m.id === checkpointState.message_id);
+    if (idx === -1) {
+      return [...this.#messages];
+    }
+    return this.#messages.slice(idx + 1);
+  }
+  #set_state(value) {
+    if (this.#state === "disposed" || value === "disposed") {
+      throw new Error("invalid state");
+    }
+    if (this.#state !== value) {
+      const previous = this.#state;
+      this.#state = value;
+      this.#event_emitter.emit(
+        "state_change",
+        {
+          current: value,
+          previous
+        },
+        this
+      );
+    }
+  }
+  async #get_prompt_context(messages) {
+    for (const t of this.#provider.context_transformers ?? []) {
+      if (t.transform_prompt) {
+        messages = await t.transform_prompt(messages);
+      }
+    }
+    const context = { checkpoint: this.#checkpoint_state };
+    return await this.#context_transformer.transform_prompt(messages, context);
+  }
+  #attach_child_event(child, event_name) {
+    const handler = (...args) => {
+      this.#event_emitter.emit(
+        "child_event",
+        {
+          event_name,
+          event_args: args
+        },
+        this
+      );
+    };
+    child.on(event_name, handler);
+    child.once("dispose", () => (0, import_promises.setImmediate)(() => child.off(event_name, handler)));
+  }
+};
+function identify_message(message) {
+  const content = message.content?.map(identify_content);
+  const id = message.id ?? import_node_crypto.default.createHash("sha1").update(JSON.stringify({ ...message, content })).digest("hex");
+  return {
+    timestamp: Date.now(),
+    ...message,
+    content,
+    id
+  };
+}
+function identify_content(content) {
+  const id = content.id ?? import_node_crypto.default.createHash("sha1").update(JSON.stringify(content)).digest("hex");
+  return {
+    timestamp: Date.now(),
+    ...content,
+    id
+  };
+}
+
+// src/conversations/token-tracker.ts
+var import_node_events3 = require("events");
+var TokenTracker = class {
+  #event_emitter = new import_node_events3.EventEmitter();
+  #conversation;
+  #stats = {
+    last_request: {
+      input: 0,
+      output: 0
+    },
+    total: {
+      input: 0,
+      output: 0
+    }
+  };
+  /**
+   * Creates a new token tracker.
+   *
+   * @param conversation - The conversation to track.
+   */
+  constructor(conversation) {
+    this.#conversation = conversation;
+    conversation.on("message_complete", this.#handle_event_with_usage);
+    conversation.on("child_event", this.#handle_child_event);
+  }
+  /**
+   * Disposes the token tracker and removes event listeners.
+   *
+   * This method is called automatically when using the `using` keyword.
+   */
+  [Symbol.dispose]() {
+    this.#conversation.off("message_complete", this.#handle_event_with_usage);
+    this.#conversation.off("child_event", this.#handle_child_event);
+    this.#event_emitter.removeAllListeners();
+  }
+  /**
+   * The current token statistics.
+   */
+  get stats() {
+    return Object.freeze({ ...this.#stats });
+  }
+  /**
+   * 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, listener) {
+    this.#event_emitter.on(event, listener);
+  }
+  /**
+   * Removes an event listener for statistics updates.
+   *
+   * @param event - The event name (always "stats_update").
+   * @param listener - The callback to remove.
+   */
+  off(event, listener) {
+    this.#event_emitter.off(event, listener);
+  }
+  #handle_event_with_usage = ({ usage }) => {
+    this.#process_usage(usage);
+  };
+  #handle_child_event = (event_data) => {
+    const { event_name, event_args } = event_data;
+    if (event_name === "message_complete") {
+      const [event_data2] = event_args;
+      if (event_data2 && "usage" in event_data2) {
+        this.#process_usage(event_data2.usage);
+      }
+    }
+    if (event_name === "child_event") {
+      const [child_event_data] = event_args;
+      this.#handle_child_event(child_event_data);
+    }
+  };
+  #process_usage = (usage) => {
+    if (usage) {
+      const input_tokens = usage.input_tokens || 0;
+      const output_tokens = usage.output_tokens || 0;
+      this.#stats = {
+        last_request: {
+          input: input_tokens,
+          output: output_tokens
+        },
+        total: {
+          input: this.stats.total.input + input_tokens,
+          output: this.stats.total.output + output_tokens
+        }
+      };
+      this.#event_emitter.emit("stats_update", this.stats);
+    }
+  };
+};
+
+// src/context-transformers/noop-context-transformer.ts
+var NoopContextTransformer = class {
+  /**
+   * 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);
+  }
+};
+
+// src/policies/rate-limit-policy.ts
+var RateLimitPolicy = class _RateLimitPolicy extends Policy {
+  #options;
+  #requests = [];
+  /**
+   * Creates a new rate limit policy.
+   *
+   * @param options - The rate limiting configuration.
+   */
+  constructor(options) {
+    super();
+    this.#options = options;
+  }
+  /**
+   * Attaches this policy to a conversation to track its requests.
+   *
+   * @param conversation - The conversation to monitor.
+   */
+  attach(conversation) {
+    conversation.on("request_success", this.#on_request_success);
+    conversation.on("child_event", this.#on_child_event);
+    conversation.once("dispose", () => {
+      conversation.off("request_success", this.#on_request_success);
+      conversation.off("child_event", this.#on_child_event);
+    });
+  }
+  /**
+   * 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.
+   */
+  async execute(cancellation_token, fn, ...args) {
+    const now = Date.now();
+    this.#requests = this.#requests.filter(
+      (timestamp) => now - timestamp < this.#options.period_ms
+    );
+    const current_usage = this.#requests.length;
+    const metadata = {
+      policy: _RateLimitPolicy.name,
+      limit: this.#options.limit,
+      period_ms: this.#options.period_ms,
+      current_usage
+    };
+    const wait_time = this.#calculate_wait_time(
+      current_usage,
+      this.#options.limit,
+      this.#options.period_ms
+    );
+    if (wait_time > 0) {
+      metadata.wait_time_ms = wait_time;
+      await sleep(wait_time, cancellation_token);
+    }
+    cancellation_token.throw_if_cancellation_requested();
+    try {
+      const value = await Promise.race([fn(...args), cancellation_token.await_cancellation()]);
+      return {
+        result: true,
+        value,
+        metadata
+      };
+    } catch (error) {
+      return {
+        result: false,
+        error,
+        metadata
+      };
+    }
+  }
+  #calculate_wait_time(current_usage, limit, period_ms) {
+    if (current_usage < limit) {
+      return 0;
+    }
+    const requests_over_limit = current_usage - limit + 1;
+    const time_per_request = period_ms / limit;
+    return requests_over_limit * time_per_request;
+  }
+  #on_request_success = () => {
+    const now = Date.now();
+    this.#requests.push(now);
+  };
+  #on_child_event = (event_data) => {
+    const { event_name, event_args } = event_data;
+    if (event_name === "request_success") {
+      this.#on_request_success();
+    }
+    if (event_name === "child_event") {
+      const [child_event_data] = event_args;
+      this.#on_child_event(child_event_data);
+    }
+  };
+};
+
+// src/policies/token-limit-policy.ts
+var TokenLimitPolicy = class _TokenLimitPolicy extends Policy {
+  #options;
+  #usage = [];
+  /**
+   * Creates a new token limit policy.
+   *
+   * @param options - The token limit configuration.
+   */
+  constructor(options) {
+    super();
+    this.#options = options;
+  }
+  /**
+   * 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.
+   */
+  async execute(cancellation_token, fn, ...args) {
+    const now = Date.now();
+    this.#usage = this.#usage.filter((record) => now - record.timestamp < this.#options.period_ms);
+    const input_tokens = this.#usage.reduce((sum, record) => sum + record.input_tokens, 0);
+    const output_tokens = this.#usage.reduce((sum, record) => sum + record.output_tokens, 0);
+    const total_tokens = input_tokens + output_tokens;
+    let wait_time;
+    const options = this.#options;
+    if ("total_tokens_per_period" in options) {
+      const total_token_wait_time = this.#calculate_wait_time(
+        total_tokens,
+        options.total_tokens_per_period
+      );
+      wait_time = total_token_wait_time;
+    } else {
+      const input_token_wait_time = this.#calculate_wait_time(
+        input_tokens,
+        options.input_tokens_per_period
+      );
+      const output_token_wait_time = this.#calculate_wait_time(
+        output_tokens,
+        options.output_tokens_per_period
+      );
+      wait_time = Math.max(input_token_wait_time, output_token_wait_time);
+    }
+    const metadata = {
+      policy: _TokenLimitPolicy.name,
+      ...this.#options,
+      current_period_start: now - this.#options.period_ms,
+      current_period_end: now,
+      input_tokens,
+      output_tokens,
+      total_tokens,
+      wait_time,
+      recent_usage_count: this.#usage.length,
+      recent_usage: this.#usage
+    };
+    if ("total_tokens_per_period" in options) {
+      metadata.total_token_wait_time = wait_time;
+    } else {
+      metadata.input_token_wait_time = this.#calculate_wait_time(
+        input_tokens,
+        options.input_tokens_per_period
+      );
+      metadata.output_token_wait_time = this.#calculate_wait_time(
+        output_tokens,
+        options.output_tokens_per_period
+      );
+    }
+    if (wait_time > 0) {
+      metadata.wait_time_ms = wait_time;
+      await sleep(wait_time, cancellation_token);
+    }
+    cancellation_token.throw_if_cancellation_requested();
+    try {
+      const value = await Promise.race([fn(...args), cancellation_token.await_cancellation()]);
+      return {
+        result: true,
+        value,
+        metadata
+      };
+    } catch (error) {
+      return {
+        result: false,
+        error,
+        metadata
+      };
+    }
+  }
+  /**
+   * Attaches this policy to a conversation to track its token usage.
+   *
+   * @param conversation - The conversation to monitor.
+   */
+  attach(conversation) {
+    conversation.on("message_complete", this.#on_message_complete);
+    conversation.on("child_event", this.#on_child_event);
+    conversation.once("dispose", () => {
+      conversation.off("message_complete", this.#on_message_complete);
+      conversation.off("child_event", this.#on_child_event);
+    });
+  }
+  #on_message_complete = ({ usage }) => {
+    const input_tokens = usage?.input_tokens || 0;
+    const output_tokens = usage?.output_tokens || 0;
+    this.#usage.push({
+      timestamp: Date.now(),
+      input_tokens,
+      output_tokens
+    });
+  };
+  #on_child_event = (event_data) => {
+    const { event_name, event_args } = event_data;
+    if (event_name === "message_complete") {
+      const [event_data2] = event_args;
+      if (event_data2) {
+        this.#on_message_complete(event_data2);
+      }
+    }
+    if (event_name === "child_event") {
+      const [child_event_data] = event_args;
+      this.#on_child_event(child_event_data);
+    }
+  };
+  #calculate_wait_time(current_tokens, tokens_per_period) {
+    if (current_tokens < tokens_per_period) {
+      return 0;
+    }
+    const now = Date.now();
+    const oldest = this.#usage[0];
+    if (!oldest) {
+      return 0;
+    }
+    return Math.max(0, oldest.timestamp + this.#options.period_ms - now);
+  }
+};
+
+// src/workflows/workflow.ts
+var import_node_crypto2 = require("crypto");
+var import_node_events4 = require("events");
+var import_promises2 = require("timers/promises");
+var Workflow = class _Workflow {
+  #event_emitter;
+  #conversation;
+  #context_data;
+  #parent;
+  #messages = [];
+  #queued_messages = [];
+  #id = (0, import_node_crypto2.randomUUID)();
+  #state = "idle";
+  #tool_context;
+  /**
+   * 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, options) {
+    this.#event_emitter = new import_node_events4.EventEmitter();
+    this.#event_emitter.setMaxListeners(0);
+    this.#conversation = conversation;
+    this.#context_data = options?.context_data ?? {};
+    this.#parent = options?.parent;
+    this.#conversation.on("prompt_send", this.#on_prompt_send);
+    this.#conversation.on("message_complete", this.#on_message_complete);
+    this.#conversation.on("request_error", this.#on_request_error);
+    this.#conversation.once("dispose", this.#on_conversation_dispose);
+    this.#parent?.once("workflow_end", this.#on_parent_workflow_end);
+  }
+  /**
+   * The unique identifier for this workflow.
+   */
+  get id() {
+    return this.#id;
+  }
+  set id(value) {
+    this.#id = value;
+  }
+  /**
+   * The current state of the workflow.
+   */
+  get state() {
+    return this.#state;
+  }
+  /**
+   * The conversation being managed by this workflow.
+   */
+  get conversation() {
+    return this.#conversation;
+  }
+  /**
+   * The parent workflow, if this is a child workflow.
+   */
+  get parent() {
+    return this.#parent;
+  }
+  /**
+   * The message history tracked by this workflow.
+   */
+  get messages() {
+    return Object.freeze([...this.#messages]);
+  }
+  /**
+   * Messages queued for sending after the current response completes.
+   */
+  get queued_messages() {
+    return [...this.#queued_messages];
+  }
+  /**
+   * Disposes the workflow and releases all resources.
+   *
+   * This method is called automatically when using the `using` keyword.
+   */
+  [Symbol.dispose]() {
+    this.#conversation.off("prompt_send", this.#on_prompt_send);
+    this.#conversation.off("message_complete", this.#on_message_complete);
+    this.#conversation.off("request_error", this.#on_request_error);
+    this.#conversation.off("dispose", this.#on_conversation_dispose);
+    this.#parent?.off("workflow_end", this.#on_parent_workflow_end);
+    this.#event_emitter.emit("dispose", this);
+    this.#set_state("disposed");
+    this.#event_emitter.removeAllListeners();
+  }
+  /**
+   * 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(event, listener) {
+    if (this.#state === "disposed") {
+      throw new Error("invalid state");
+    }
+    this.#event_emitter.once(event, listener);
+    return 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(event, listener) {
+    if (this.#state === "disposed") {
+      throw new Error("invalid state");
+    }
+    this.#event_emitter.on(event, listener);
+    return 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(event, listener) {
+    this.#event_emitter.off(event, listener);
+    return this;
+  }
+  /**
+   * Starts the workflow execution.
+   *
+   * @param message - Optional initial user message to begin the workflow.
+   */
+  start(message) {
+    if (this.#state !== "idle") {
+      throw new Error("invalid state");
+    }
+    if (message) {
+      this.#messages.push(message);
+      this.#event_emitter.emit("workflow_update", this);
+    }
+    this.#set_state("busy");
+  }
+  /**
+   * Cancels the workflow execution.
+   *
+   * This will cancel any in-progress model response and emit a workflow_end event.
+   */
+  cancel() {
+    if (this.#state === "disposed") {
+      throw new Error("invalid state");
+    }
+    if (this.#conversation.state === "awaiting_response" || this.#conversation.state === "streaming_response") {
+      this.#conversation.cancel_response();
+    }
+    this.#set_state("idle");
+    this.#event_emitter.emit("workflow_end", { reason: "cancel" }, this);
+    this[Symbol.dispose]();
+  }
+  /**
+   * 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, id, context_data) {
+    if (this.#state === "disposed") {
+      throw new Error("invalid state");
+    }
+    const merged_context = context_data ? { ...this.#context_data, ...context_data } : this.#context_data;
+    const child = new _Workflow(conversation, { context_data: merged_context, parent: this });
+    if (id) {
+      child.id = id;
+    }
+    this.#attach_child_event(child, "state_change");
+    this.#attach_child_event(child, "workflow_update");
+    this.#attach_child_event(child, "workflow_end");
+    this.#attach_child_event(child, "child_workflow_begin");
+    this.#attach_child_event(child, "child_workflow_event");
+    this.#attach_child_event(child, "message_queued");
+    this.#attach_child_event(child, "message_dequeued");
+    this.#attach_child_event(child, "queue_cleared");
+    this.#attach_child_event(child, "lifecycle_error");
+    this.#attach_child_event(child, "dispose");
+    this.#event_emitter.emit("child_workflow_begin", child, this);
+    return child;
+  }
+  /**
+   * Adds a message to the queue for sending after the current response completes.
+   *
+   * @param message - The text message to queue.
+   */
+  queue_message(message) {
+    if (this.#state === "disposed") {
+      throw new Error("invalid state");
+    }
+    this.#queued_messages.push(message);
+    this.#event_emitter.emit("message_queued", message, this);
+  }
+  /**
+   * Clears all queued messages.
+   */
+  clear_queue() {
+    if (this.#state === "disposed") {
+      throw new Error("invalid state");
+    }
+    this.#queued_messages.length = 0;
+    this.#event_emitter.emit("queue_cleared", this);
+  }
+  #set_state(state) {
+    if (this.#state === state) {
+      return;
+    }
+    const previous = this.state;
+    this.#state = state;
+    this.#event_emitter.emit("state_change", { previous, current: this.#state }, this);
+  }
+  async #execute_tools(message) {
+    const tool_calls = message.content.filter(
+      (c) => c.type === "tool"
+    );
+    const batches = [];
+    let current_batch = [];
+    for (const call of tool_calls) {
+      const tool_class = this.conversation.toolkit.find(
+        (t) => t.get_definition().name === call.tool
+      );
+      const is_parallel = tool_class?.get_definition().parallelizable !== false;
+      if (!is_parallel) {
+        if (current_batch.length > 0) {
+          batches.push(current_batch);
+          current_batch = [];
+        }
+        batches.push([call]);
+      } else {
+        current_batch.push(call);
+      }
+    }
+    if (current_batch.length > 0) {
+      batches.push(current_batch);
+    }
+    const results = [];
+    for (const batch of batches) {
+      const batch_results = await Promise.all(
+        batch.map(async (call) => {
+          const tool_class = this.conversation.toolkit.find(
+            (t) => t.get_definition().name === call.tool
+          );
+          if (tool_class) {
+            if (!this.#tool_context) {
+              this.#tool_context = {
+                ...this.#context_data,
+                conversation: this.conversation,
+                workflow: this
+              };
+            }
+            const context = this.#tool_context;
+            const tool = new tool_class(context);
+            try {
+              const result = await tool.execute(call.params);
+              return {
+                type: "tool_result",
+                tool: call.tool,
+                tool_request_id: call.tool_request_id,
+                result
+              };
+            } catch (error) {
+              const message2 = error instanceof Error ? error.message : "Tool execution failed";
+              return {
+                type: "tool_result",
+                tool: call.tool,
+                tool_request_id: call.tool_request_id,
+                result: { result: false, message: message2 }
+              };
+            }
+          }
+          return {
+            type: "tool_result",
+            tool: call.tool,
+            tool_request_id: call.tool_request_id,
+            result: { result: false, message: "invalid tool" }
+          };
+        })
+      );
+      results.push(...batch_results);
+      if (this.#state !== "busy") {
+        return;
+      }
+    }
+    await this.conversation.send_message(results);
+  }
+  #attach_child_event(child, event_name) {
+    const handler = (...args) => {
+      this.#event_emitter.emit(
+        "child_workflow_event",
+        {
+          event_name,
+          event_args: args
+        },
+        this
+      );
+    };
+    child.on(event_name, handler);
+    child.once("dispose", () => (0, import_promises2.setImmediate)(() => child.off(event_name, handler)));
+  }
+  #on_prompt_send = ({ message }) => {
+    this.#messages.push(message);
+    this.#event_emitter.emit("workflow_update", this);
+  };
+  #on_message_complete = async (event) => {
+    try {
+      this.#messages.push(event.message);
+      this.#event_emitter.emit("workflow_update", this);
+      if (event.stop_reason === "tool_use") {
+        await this.#execute_tools(event.message);
+      } else {
+        const queued_message = this.#queued_messages.shift();
+        if (queued_message) {
+          this.#event_emitter.emit("message_dequeued", queued_message, this);
+          await this.#conversation.prompt(queued_message);
+        } else {
+          this.#set_state("idle");
+          this.#event_emitter.emit("workflow_end", { reason: "complete" }, this);
+          this[Symbol.dispose]();
+        }
+      }
+    } catch {
+      this.#set_state("idle");
+      this.#event_emitter.emit("workflow_end", { reason: "error" }, this);
+      this[Symbol.dispose]();
+    }
+  };
+  #on_request_error = () => {
+    this.#set_state("idle");
+    this.#event_emitter.emit("workflow_end", { reason: "error" }, this);
+    this[Symbol.dispose]();
+  };
+  #on_conversation_dispose = () => this[Symbol.dispose]();
+  #on_parent_workflow_end = (event) => {
+    if (event.reason === "cancel") {
+      this.cancel();
+    }
+  };
+};
+
+// src/workflows/workflow-manager.ts
+var import_node_events5 = require("events");
+var import_promises3 = require("timers/promises");
+var WorkflowManager = class {
+  #event_emitter = new import_node_events5.EventEmitter();
+  #conversation;
+  #context_data;
+  #state = "idle";
+  #current_workflow;
+  /**
+   * 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, options) {
+    this.#conversation = conversation;
+    this.#context_data = options?.context_data ?? {};
+    this.#conversation.on("prompt_send", this.#on_prompt_send);
+    this.#conversation.on("checkpoint_begin", this.#on_checkpoint_begin);
+    this.#conversation.once("dispose", this.#on_conversation_dispose);
+  }
+  /**
+   * The current state of the workflow manager.
+   */
+  get state() {
+    return this.#state;
+  }
+  /**
+   * The conversation being managed.
+   */
+  get conversation() {
+    return this.#conversation;
+  }
+  /**
+   * The currently active workflow, if any.
+   */
+  get current_workflow() {
+    return this.#current_workflow;
+  }
+  /**
+   * Disposes the workflow manager and releases all resources.
+   *
+   * This method is called automatically when using the `using` keyword.
+   */
+  [Symbol.dispose]() {
+    this.#conversation.off("prompt_send", this.#on_prompt_send);
+    this.#conversation.off("checkpoint_begin", this.#on_checkpoint_begin);
+    this.#conversation.off("dispose", this.#on_conversation_dispose);
+    this.#event_emitter.emit("dispose", this);
+    this.#set_state("disposed");
+    this.#event_emitter.removeAllListeners();
+  }
+  /**
+   * 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(event, listener) {
+    if (this.#state === "disposed") {
+      throw new Error("invalid state");
+    }
+    this.#event_emitter.once(event, listener);
+    return 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(event, listener) {
+    if (this.#state === "disposed") {
+      throw new Error("invalid state");
+    }
+    this.#event_emitter.on(event, listener);
+    return 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(event, listener) {
+    this.#event_emitter.off(event, listener);
+    return this;
+  }
+  /**
+   * Manually starts a workflow.
+   *
+   * This is typically not needed as workflows are started automatically when messages are sent.
+   */
+  start_workflow() {
+    if (this.#state !== "idle") {
+      throw new Error("invalid state");
+    }
+  }
+  #on_prompt_send = ({ message }) => {
+    if (this.#current_workflow) {
+      return;
+    }
+    this.#current_workflow = new Workflow(this.#conversation, { context_data: this.#context_data });
+    this.#attach_workflow_event(this.#current_workflow, "state_change");
+    this.#attach_workflow_event(this.#current_workflow, "workflow_update");
+    this.#attach_workflow_event(this.#current_workflow, "workflow_end");
+    this.#attach_workflow_event(this.#current_workflow, "child_workflow_begin");
+    this.#attach_workflow_event(this.#current_workflow, "child_workflow_event");
+    this.#attach_workflow_event(this.#current_workflow, "message_queued");
+    this.#attach_workflow_event(this.#current_workflow, "message_dequeued");
+    this.#attach_workflow_event(this.#current_workflow, "queue_cleared");
+    this.#attach_workflow_event(this.#current_workflow, "lifecycle_error");
+    this.#attach_workflow_event(this.#current_workflow, "dispose");
+    this.#current_workflow.once("dispose", () => {
+      this.#current_workflow = void 0;
+      this.#set_state("idle");
+    });
+    this.#set_state("busy");
+    this.#event_emitter.emit("workflow_begin", this.#current_workflow, this);
+    this.#current_workflow.start(message);
+  };
+  #set_state(state) {
+    if (this.#state === state) {
+      return;
+    }
+    const previous = this.state;
+    this.#state = state;
+    this.#event_emitter.emit("state_change", { previous, current: this.#state }, this);
+  }
+  #attach_workflow_event(workflow, event_name) {
+    const handler = (...args) => {
+      this.#event_emitter.emit(
+        "workflow_event",
+        {
+          event_name,
+          event_args: args
+        },
+        this
+      );
+    };
+    workflow.on(event_name, handler);
+    workflow.once("dispose", () => (0, import_promises3.setImmediate)(() => workflow.off(event_name, handler)));
+  }
+  #on_checkpoint_begin = (child) => {
+    this.#set_state("busy");
+    child.once("dispose", () => {
+      this.#set_state("idle");
+    });
+  };
+  #on_conversation_dispose = () => this[Symbol.dispose]();
+};
+
+// src/utils/object.ts
+function defined_keys(obj) {
+  return Object.keys(obj).filter((key) => obj[key] !== void 0);
+}
+function undefined_if_empty(obj) {
+  if (!obj) {
+    return obj;
+  }
+  if (Array.isArray(obj)) {
+    return obj.length === 0 ? void 0 : obj;
+  }
+  if (typeof obj === "object") {
+    return defined_keys(obj).length === 0 ? void 0 : obj;
+  }
+  return obj;
+}
+function deep_merge(original, supplemental) {
+  if (supplemental === void 0 || supplemental === null) {
+    return original;
+  }
+  if (original === void 0 || original === null) {
+    return supplemental;
+  }
+  if (typeof original === "object" && typeof supplemental === "object") {
+    if (Array.isArray(original)) {
+      if (!Array.isArray(supplemental)) {
+        throw new Error("type mismatch");
+      }
+      return [...original, ...supplemental];
+    } else {
+      if (Array.isArray(supplemental)) {
+        throw new Error("type mismatch");
+      }
+      const result = { ...original };
+      for (const [key, value] of Object.entries(supplemental)) {
+        result[key] = deep_merge(result[key], value);
+      }
+      return result;
+    }
+  }
+  if (typeof supplemental !== typeof original) {
+    throw new Error("type mismatch");
+  }
+  if (typeof supplemental === "string" || typeof supplemental === "number" || typeof supplemental === "boolean") {
+    return supplemental;
+  }
+  throw new Error("unsupported type");
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CancellationToken,
+  CancellationTokenSource,
+  CheckpointContextTransformer,
+  CompositeContextTransformer,
+  CompositePolicy,
+  Conversation,
+  DefaultSummarizationStrategy,
+  NoopContextTransformer,
+  NoopPolicy,
+  OperationCanceledError,
+  Policy,
+  RateLimitPolicy,
+  RetryPolicy,
+  StreamListener,
+  TokenLimitPolicy,
+  TokenTracker,
+  ToolContextTransformer,
+  Workflow,
+  WorkflowManager,
+  deep_merge,
+  defaultRetryable,
+  getDefaultPolicy,
+  peek_generator,
+  sleep,
+  undefined_if_empty
+});
+//# sourceMappingURL=index.cjs.map