@tangle-network/agent-runtime 0.104.0 → 0.106.0

package/dist/conversation.d.ts

@@ -1,804 +1,2 @@
-import { c as AgentExecutionBackend, k as RuntimeSessionStore } from './types-BwoZWq-i.js';
-import { AgentProfile, MaximumCharge } from '@tangle-network/agent-eval';
-import { Scenario, ProfileDispatchFn } from '@tangle-network/agent-eval/campaign';
-
-/**
- *
- * Per-call resilience policy for participant backends: deadline, retry with
- * backoff, and a circuit breaker. Each policy is applied *around* a single
- * turn's backend invocation, not across the whole conversation — the
- * conversation-level credit cap and `maxTurns` bound the broader run.
- *
- * Deadlines abort the underlying backend stream via `AbortSignal` linkage so
- * the OpenAI/SDK clients tear down their HTTP request cleanly instead of
- * leaking sockets. Retries replay the same logical turn (same `turnId`) so
- * any caching gateway can dedupe. Circuit breakers are *per participant*: A's
- * failures don't open B's breaker.
- *
- * @stable
- */
-/** Pure judgment of whether an error is worth retrying. Defaults: TimeoutError, AbortError, fetch-level network errors. */
-type RetryableErrorPredicate = (err: unknown) => boolean;
-/** Backoff between attempts. Constant ms, or `(attempt: 1-indexed) => ms`. */
-type RetryBackoff = number | ((attempt: number) => number);
-/** Circuit-breaker tuning. `failuresToOpen` consecutive failures opens it; closed only after `cooldownMs`. */
-interface CircuitBreakerConfig {
-    failuresToOpen: number;
-    cooldownMs: number;
-}
-interface BackendCallPolicy {
-    /** Per-attempt wall clock limit. Exceeding fires an AbortSignal and is treated as a retryable failure. */
-    perAttemptDeadlineMs?: number;
-    /** Number of retries after the first attempt; total attempts = 1 + maxRetries. Default 0. */
-    maxRetries?: number;
-    /** Backoff between attempts. Default 250ms with jitter. */
-    retryBackoffMs?: RetryBackoff;
-    /** Custom retry classifier. Defaults to {@link defaultIsRetryable}. */
-    isRetryable?: RetryableErrorPredicate;
-    /** Circuit breaker that opens after N consecutive failures per participant. */
-    circuitBreaker?: CircuitBreakerConfig;
-}
-/** Thrown when the circuit breaker is open for a participant and no retry is allowed yet. */
-declare class CircuitOpenError extends Error {
-    constructor(participant: string, retryAfterMs: number);
-}
-/** Thrown when a backend call exceeds its per-attempt deadline. */
-declare class DeadlineExceededError extends Error {
-    constructor(deadlineMs: number);
-}
-/**
- * Default retryable classification — network/timeout class errors. Errors
- * a model deliberately throws (validation, refusal, 4xx) are not retried;
- * those represent real outcomes, not transient infrastructure faults.
- */
-declare const defaultIsRetryable: RetryableErrorPredicate;
-/** Live circuit-breaker state — one instance per (participant, conversation run). */
-declare class CircuitBreakerState {
-    private readonly config;
-    private consecutiveFailures;
-    private openedAt;
-    constructor(config: CircuitBreakerConfig | undefined);
-    /**
-     * Check whether the next call is allowed. Throws `CircuitOpenError` when
-     * the breaker is open and the cooldown hasn't elapsed.
-     */
-    preflight(participant: string, now?: number): void;
-    recordSuccess(): void;
-    recordFailure(now?: number): void;
-}
-/**
- * Build a per-attempt AbortSignal linked to the parent signal AND fired when
- * the deadline elapses. The returned `dispose()` MUST be called in a
- * `finally` (clears the timer, detaches the listener) so we don't leak.
- *
- * When the deadline fires, the signal's `reason` is a `DeadlineExceededError`
- * — callers can detect timeout-vs-cancel by reading `signal.reason` after
- * the underlying operation throws.
- */
-declare function makePerAttemptSignal(parentSignal: AbortSignal | undefined, deadlineMs: number | undefined): {
-    signal: AbortSignal;
-    dispose: () => void;
-    getDeadlineError(): DeadlineExceededError | undefined;
-};
-/** Compute the delay before the next attempt. Default: 250ms exponential with jitter. */
-declare function computeBackoff(spec: RetryBackoff | undefined, attempt: number): number;
-/** Resolve after `ms` milliseconds — used for retry backoff in conversation call policy. */
-declare function sleep(ms: number): Promise<void>;
-
-/**
- *
- * Cross-gateway forwarding headers — the wire-level contract that makes
- * agent-to-agent communication composable across organizational boundaries.
- * Every header here is read on inbound and re-emitted on outbound, so a chain
- * `caller → A's gateway → A's runtime → B's gateway → B's runtime` ends with
- * B billing the original user, the depth counter monotonically incremented,
- * and the run/turn correlation IDs preserved end-to-end.
- *
- * The actual depth refusal (HTTP 413 at MAX_DEPTH) is enforced by
- * `agent-gateway`'s middleware; this module owns the names + the propagation
- * rules so both sides agree.
- *
- * Full protocol: `docs/agent-bus-protocol.md`.
- *
- * @stable
- */
-/** Standard names — lowercased so Headers maps interop on every runtime. */
-declare const FORWARD_HEADERS: {
-    /** Forwarded original-user identity (`Bearer sk-tan-<user>`); downstream gateways bill against this. */
-    readonly authorization: "x-tangle-forwarded-authorization";
-    /** Monotonically incremented on every gateway hop. Refused at MAX_DEPTH. */
-    readonly depth: "x-tangle-forwarded-depth";
-    /** Top-level conversation run identifier, propagated through every nested call. */
-    readonly runId: "x-tangle-runid";
-    /** This call's turn within the run; deterministic + stable across retries. */
-    readonly turnId: "x-tangle-turnid";
-    /** When the call is *inside* another turn (recursion), the parent turn's id. */
-    readonly parentTurnId: "x-tangle-parent-turnid";
-    /** Logical conversation peer label at the sending side, for trace stitching. */
-    readonly speaker: "x-tangle-speaker";
-};
-type ForwardHeaderName = (typeof FORWARD_HEADERS)[keyof typeof FORWARD_HEADERS];
-/** Hard cap on chained gateway hops; refused beyond this. Default keeps recursion bounded. */
-declare const DEFAULT_MAX_DEPTH = 4;
-/**
- * Read the depth counter off an inbound request. Missing → 0 (caller is the
- * origin). Non-integer → throws — silent coercion would let a bad caller
- * reset depth and bypass the limit.
- */
-declare function readDepth(headers: Readonly<Record<string, string | string[] | undefined>>): number;
-/**
- * Refuse further forwarding when the inbound depth has reached the limit.
- * Callers (the gateway middleware) translate the boolean to an HTTP 413.
- */
-declare function isDepthExceeded(inboundDepth: number, max?: number): boolean;
-/**
- * Build the headers to emit on an outbound participant call, given the
- * conversation's propagation context. Depth is incremented from the inbound
- * value; runId / turnId / speaker stamp the current hop; the user's
- * `Authorization` is preserved verbatim so the downstream gateway bills the
- * right wallet.
- */
-declare function buildForwardHeaders(input: {
-    inboundDepth: number;
-    forwardedAuthorization?: string;
-    runId: string;
-    turnId: string;
-    parentTurnId?: string;
-    speaker: string;
-}): Record<string, string>;
-/**
- * Header bag carried through `AgentBackendContext.propagatedHeaders` so
- * backends that opt in can merge them into their outbound HTTP requests.
- * Distinct from `buildForwardHeaders` so callers can attach extra
- * non-protocol headers (e.g. tracing) without colliding.
- */
-type PropagatedHeaders = Readonly<Record<string, string>>;
-
-/**
- *
- * Durable conversation transcript — survives a driver process crash mid-run.
- * The runner journals every committed turn before yielding `turn_end`, so a
- * resumed run replays the same `runId` against the same journal and picks up
- * from the first un-recorded turn. Combined with the deterministic
- * `turnId(runId, index, speaker)`, a retried turn collides with the prior
- * attempt's id and any caching gateway can dedupe.
- *
- * The interface is small enough that a Cloudflare D1 / R2 / postgres adapter
- * is ~30 lines. The in-memory adapter is the default for tests and scratch.
- * The file adapter (JSONL on disk) is the default-durable choice when no
- * upstream store is wired.
- *
- * @stable
- */
-
-interface ConversationJournalEntry {
-    runId: string;
-    startedAt: string;
-    /** Set when the run reaches a terminal state. */
-    halted?: HaltReason;
-    endedAt?: string;
-    turns: ConversationTurn[];
-}
-interface ConversationJournal {
-    /**
-     * Load any prior state for `runId`. Returns `undefined` for a fresh run.
-     * Implementations MUST NOT mutate the returned object — the runner clones
-     * before continuing — but the runtime treats absence and emptiness
-     * identically, so a journal with zero turns is equivalent to "fresh."
-     */
-    loadRun(runId: string): Promise<ConversationJournalEntry | undefined>;
-    /**
-     * Initialise journal state for a fresh run. Called once per run, before any
-     * `appendTurn`. Idempotent: calling with an existing runId is a no-op if
-     * the entry already exists with the same `startedAt`.
-     */
-    beginRun(runId: string, startedAt: string): Promise<void>;
-    /**
-     * Append a committed turn. The runner only calls this AFTER the turn's
-     * backend stream completed and the credit total has been updated, so an
-     * appended turn is observed-committed and never speculative.
-     */
-    appendTurn(runId: string, turn: ConversationTurn): Promise<void>;
-    /**
-     * Record the run's terminal halt reason + end time. Once called, the run
-     * is observed-final; subsequent `loadRun` returns the same halt.
-     */
-    recordHalt(runId: string, halt: HaltReason, endedAt: string): Promise<void>;
-}
-/** In-memory `ConversationJournal` — suitable for testing and single-process runs. */
-declare class InMemoryConversationJournal implements ConversationJournal {
-    private readonly entries;
-    loadRun(runId: string): Promise<ConversationJournalEntry | undefined>;
-    beginRun(runId: string, startedAt: string): Promise<void>;
-    appendTurn(runId: string, turn: ConversationTurn): Promise<void>;
-    recordHalt(runId: string, halt: HaltReason, endedAt: string): Promise<void>;
-}
-/**
- * JSONL on disk. One line per record; first line is the `begin`, subsequent
- * lines are `turn` records, terminal line is `halt`. Replays the whole file
- * on `loadRun` — cheap for the conversation sizes this is designed for
- * (thousands of turns, not millions). For huge runs, plug in a real DB
- * adapter; the interface is small.
- *
- * Each `appendTurn` / `recordHalt` calls `fsync` after the write so a
- * process crash between writes never loses an acknowledged turn.
- */
-declare class FileConversationJournal implements ConversationJournal {
-    private readonly path;
-    constructor(path: string);
-    loadRun(runId: string): Promise<ConversationJournalEntry | undefined>;
-    beginRun(runId: string, startedAt: string): Promise<void>;
-    appendTurn(runId: string, turn: ConversationTurn): Promise<void>;
-    recordHalt(runId: string, halt: HaltReason, endedAt: string): Promise<void>;
-    private appendRecord;
-}
-
-/**
- *
- * Public types for multi-agent conversations. A `Conversation` is two-or-more
- * participants taking turns through their own `AgentExecutionBackend`s, driven
- * by a `ConversationPolicy` (turn order, halting, hard credit ceiling).
- *
- * Each participant's backend can resolve to any reachable endpoint —
- * in-process iterable, local cli-bridge, sandbox, router, or a remote
- * agent-gateway — so the same `runConversation` call drives same-machine,
- * same-cloud, and cross-cloud orchestration without code change.
- *
- * @stable
- */
-
-/** @stable */
-interface ConversationParticipant {
-    /**
-     * Stable name used as the speaker label in the transcript. Must be unique
-     * within a `Conversation`.
-     */
-    name: string;
-    /**
-     * Backend that runs this participant's turn. Reuses the existing
-     * `AgentExecutionBackend` contract from `runAgentTaskStream`, so any
-     * registered backend (iterable, sandbox, OpenAI-compatible) works without
-     * adaptation.
-     */
-    backend: AgentExecutionBackend;
-    /**
-     * Optional human label for traces / dashboards. Distinct from `name`, which
-     * is the addressing key.
-     */
-    label?: string;
-    /**
-     * Optional per-participant override of the conversation's default
-     * `callPolicy`. Use to tighten the deadline or raise the retry budget for
-     * a participant known to be slow or flaky.
-     */
-    callPolicy?: BackendCallPolicy;
-    /**
-     * Who pays for THIS participant's outbound calls?
-     *
-     * - `'forward-user'` (default) — propagate the caller's
-     *   `X-Tangle-Forwarded-Authorization` so the downstream gateway bills the
-     *   original user. Right for pass-through agents that aggregate/route
-     *   without taking economic risk.
-     * - `'agent-owned'` — DO NOT forward the user's auth; the participant's
-     *   backend uses its own credentials (typically a sk-tan-AGENT or x402
-     *   wallet baked into the backend at construction). Downstream charges
-     *   land on the agent, not the user. Right for resold-bundle agents that
-     *   take margin between their inbound price and their sub-agent costs.
-     * - `(state) => AuthSource` — per-turn / per-condition decision, e.g. base
-     *   sub-services are agent-owned but premium add-ons forward the user.
-     *
-     * The agent's own credentials live on the backend (set at construction
-     * time, e.g. `createOpenAICompatibleBackend({ apiKey })`); this field is
-     * purely about *whether to also forward the user's identity downstream*.
-     */
-    authSource?: AuthSource;
-}
-/** @stable */
-type AuthSource = 'forward-user' | 'agent-owned' | ((state: ConversationDriveState) => 'forward-user' | 'agent-owned');
-/** @stable */
-type TurnOrder = 'alternate' | 'round-robin' | ((state: ConversationDriveState) => number);
-/** @stable */
-interface ConversationDriveState {
-    transcript: readonly ConversationTurn[];
-    turnIndex: number;
-    spentCreditsCents: number;
-}
-/** @stable */
-interface HaltContext extends ConversationDriveState {
-    lastTurn: ConversationTurn;
-}
-/** @stable */
-interface HaltSignal {
-    halted: true;
-    reason: string;
-}
-/** @stable */
-type HaltPredicate = (ctx: HaltContext) => boolean | HaltSignal | Promise<boolean | HaltSignal>;
-/** @stable */
-type HaltReason = {
-    kind: 'max_turns';
-    turns: number;
-} | {
-    kind: 'max_credits';
-    spentCents: number;
-    capCents: number;
-} | {
-    kind: 'predicate';
-    reason: string;
-} | {
-    kind: 'abort';
-} | {
-    kind: 'participant_error';
-    participant: string;
-    message: string;
-};
-/** @stable */
-interface ConversationPolicy {
-    /** Hard cap on speaker-turns. Each call into a participant's backend counts as 1. */
-    maxTurns: number;
-    /**
-     * Hard cap on aggregate credit spend across all participants, in cents.
-     * Computed by summing `llm_call.costUsd` from every participant's stream.
-     * Unset (`undefined`) means no credit ceiling — the run is bounded only by
-     * `maxTurns` and `haltOn`.
-     */
-    maxCreditsCents?: number;
-    /**
-     * Speaker selection. Defaults to `'alternate'` for two-participant
-     * conversations and `'round-robin'` for any other arity.
-     */
-    turnOrder?: TurnOrder;
-    /**
-     * Optional convergence / content-based halt. Called after every turn ends;
-     * returning truthy stops the loop with `{ kind: 'predicate', ... }`.
-     */
-    haltOn?: HaltPredicate;
-    /**
-     * Default per-turn resilience policy applied to every participant call
-     * (deadline, retries, circuit breaker). Individual participants may
-     * override via `ConversationParticipant.callPolicy`.
-     */
-    defaultCallPolicy?: BackendCallPolicy;
-}
-/** @stable */
-interface ConversationTurn {
-    index: number;
-    speaker: string;
-    /**
-     * Deterministic turn identifier — stable across retries of the same logical
-     * turn so caching gateways and trace backends can dedupe. Shape:
-     * `${runId}.t${index}.${speakerSlug}`.
-     */
-    turnId: string;
-    /** Backend session used for this turn. Present on turns recorded by session-aware runners. */
-    sessionId?: string;
-    text: string;
-    /**
-     * Aggregated backend usage for this turn alone. Populated from any
-     * `llm_call` stream events the backend emitted; `undefined` when the
-     * backend reports no usage.
-     */
-    usage?: {
-        tokensIn?: number;
-        tokensOut?: number;
-        costUsd?: number;
-        latencyMs?: number;
-        model?: string;
-    };
-    /**
-     * Number of attempts that ran before this turn committed. `1` is the
-     * common case; higher means the call policy retried after transient
-     * failures.
-     */
-    attempts: number;
-    startedAt: string;
-    endedAt: string;
-}
-/** @stable */
-interface Conversation {
-    participants: readonly ConversationParticipant[];
-    policy: ConversationPolicy;
-}
-/** @stable */
-interface RunConversationOptions {
-    /** First message kicking off the conversation. Routes to the first speaker. */
-    seed: string;
-    /**
-     * Optional run identifier for cross-participant trace correlation. Auto-
-     * generated when omitted. Reusing a runId against the same `journal`
-     * resumes the prior run — the runner replays the persisted transcript and
-     * continues from the first un-recorded turn.
-     */
-    runId?: string;
-    /** Cancellation signal — aborts mid-stream and halts with `{ kind: 'abort' }`. */
-    signal?: AbortSignal;
-    /**
-     * Event sink for per-turn micro-events. Distinct from the result transcript:
-     * the sink fires for every text-delta, every turn-start/end, and the
-     * conversation-start/end markers. Used to drive SSE / dashboard updates
-     * without waiting for the conversation to finish.
-     */
-    onEvent?: (event: ConversationStreamEvent) => void | Promise<void>;
-    /**
-     * Optional durable transcript. When set, the runner persists every
-     * committed turn before yielding `turn_end`. Reusing the same `runId`
-     * against the same journal resumes from the last committed turn — so a
-     * driver process crash mid-run loses zero acknowledged turns.
-     */
-    journal?: ConversationJournal;
-    /**
-     * Stores each participant's backend session. The runner keeps an in-memory
-     * store for one invocation when omitted. Reuse a durable store with the same
-     * `runId` and journal after a process restart. Backends implementing `resume`
-     * continue their provider session; other backends receive the full transcript.
-     */
-    sessionStore?: RuntimeSessionStore;
-    /**
-     * Headers to forward verbatim to every participant backend call (gateway
-     * propagation: `X-Tangle-Forwarded-Authorization`, run/turn correlation,
-     * depth counter). Backends opt in by reading `propagatedHeaders` from
-     * their `AgentBackendContext`; backends that ignore the field still work.
-     */
-    propagatedHeaders?: PropagatedHeaders;
-    /**
-     * Inbound depth at the point this driver was invoked. The runner
-     * increments it on every outbound participant call; gateways refuse at
-     * `DEFAULT_MAX_DEPTH`. Default 0 (origin caller).
-     */
-    inboundDepth?: number;
-    /**
-     * Parent turn id when this conversation is *inside* another turn (i.e. the
-     * driver is itself a participant via `createConversationBackend`). The
-     * runner stamps each outbound call with this as `X-Tangle-Parent-TurnId`
-     * so trace stitching survives nested orchestration.
-     */
-    parentTurnId?: string;
-}
-/** @stable */
-interface ConversationResult {
-    runId: string;
-    transcript: ConversationTurn[];
-    turns: number;
-    spentCreditsCents: number;
-    halted: HaltReason;
-    durationMs: number;
-    startedAt: string;
-    endedAt: string;
-}
-/** @stable */
-type ConversationStreamEvent = {
-    type: 'conversation_start';
-    runId: string;
-    participants: readonly string[];
-    seed: string;
-    timestamp: string;
-} | {
-    type: 'conversation_resumed';
-    runId: string;
-    participants: readonly string[];
-    transcript: readonly ConversationTurn[];
-    timestamp: string;
-} | {
-    type: 'turn_start';
-    runId: string;
-    index: number;
-    speaker: string;
-    turnId: string;
-    attempt: number;
-    timestamp: string;
-} | {
-    type: 'turn_text_delta';
-    runId: string;
-    index: number;
-    speaker: string;
-    turnId: string;
-    text: string;
-    timestamp?: string;
-} | {
-    type: 'turn_retry';
-    runId: string;
-    index: number;
-    speaker: string;
-    turnId: string;
-    attempt: number;
-    reason: string;
-    timestamp: string;
-} | {
-    type: 'turn_end';
-    runId: string;
-    turn: ConversationTurn;
-    timestamp: string;
-} | {
-    type: 'conversation_end';
-    runId: string;
-    result: ConversationResult;
-    timestamp: string;
-};
-
-/**
- *
- * Wrap a `Conversation` so it satisfies `AgentExecutionBackend`. The result is
- * an addressable "single agent" whose internal behavior is an N-party
- * orchestrated conversation — the recursion primitive that lets a swarm be a
- * participant inside another swarm, or be published behind a single
- * agent-gateway endpoint.
- *
- * Stream events from inner participants are NOT forwarded verbatim. Outer
- * callers see one `text_delta` per inner turn (the turn's full text), tagged
- * with `[speaker] ` prefix so the outer transcript stays attributable. The
- * conversation's `conversation_end` halt reason rides on a `final` event.
- *
- * @stable
- */
-
-declare function createConversationBackend(options: {
-    conversation: Conversation;
-    /** Optional backend kind label. Defaults to `'conversation'`. */
-    kind?: string;
-}): AgentExecutionBackend;
-
-/**
- *
- * Declarative constructor for a multi-agent `Conversation`. Validates inputs
- * fail-loud at definition time (duplicate participant names, alternate order
- * with ≠2 participants, non-positive `maxTurns`) so misconfiguration is caught
- * before `runConversation` is called and not buried inside a streaming run.
- *
- * @stable
- */
-
-declare function defineConversation(input: {
-    participants: ConversationParticipant[];
-    policy: ConversationPolicy;
-}): Conversation;
-
-/**
- *
- * Durable conversation journal backed by any SQL store. Adapter-agnostic by
- * design: callers wire a `SqlAdapter` against their driver of choice (D1,
- * postgres, sqlite, libSQL…) and the same journal implementation persists
- * conversation runs durably across process restarts. The schema is two
- * tables — runs (latest state) + events (append-only log) — so a partial
- * crash in the middle of a turn leaves an unambiguous "last committed turn"
- * to resume from.
- *
- * Why not bake in a specific driver? agent-runtime ships against multiple
- * runtimes (Cloudflare Workers, Node, Bun, Deno) and consumers' fleets have
- * already standardized on one of D1 / postgres / sqlite / libSQL. Adapter
- * indirection costs ~5 lines per driver in the consumer's code and keeps the
- * SDK free of native deps.
- *
- * @example D1 (Cloudflare Workers)
- *   import { SqlConversationJournal, d1ToSqlAdapter } from '@tangle-network/agent-runtime'
- *   const journal = new SqlConversationJournal(d1ToSqlAdapter(env.DB))
- *   await journal.migrate()                     // once at deploy
- *   await runConversation(conv, { seed, journal, runId: 'run_abc' })
- *
- * @example node-postgres
- *   import { Pool } from 'pg'
- *   const pool = new Pool({ connectionString: process.env.DATABASE_URL })
- *   const pg: SqlAdapter = {
- *     exec: async (sql, params = []) => {
- *       const r = await pool.query(sql, params as never)
- *       return { rowsAffected: r.rowCount ?? 0 }
- *     },
- *     query: async (sql, params = []) => (await pool.query(sql, params as never)).rows,
- *   }
- *   const journal = new SqlConversationJournal(pg)
- *   await journal.migrate()
- *
- * @stable
- */
-
-/**
- * Minimal SQL driver shape. Implementations forward to whichever client the
- * deployment already uses; agent-runtime takes no opinion on which.
- *
- * Parameter placeholders MUST be `?` (positional). All adapters listed in the
- * file header accept this convention.
- */
-interface SqlAdapter {
-    /** Execute a write statement (INSERT/UPDATE/DELETE/DDL). */
-    exec(sql: string, params?: readonly unknown[]): Promise<{
-        rowsAffected: number;
-    }>;
-    /** Execute a read statement (SELECT). Returns rows as plain objects. */
-    query<TRow = Record<string, unknown>>(sql: string, params?: readonly unknown[]): Promise<TRow[]>;
-}
-/**
- * Adapt a Cloudflare D1 binding to the SqlAdapter shape. Lives here so D1
- * consumers don't have to write the wrapper themselves; the runtime never
- * imports `@cloudflare/workers-types` directly (peer-style typing).
- */
-declare function d1ToSqlAdapter(db: D1DatabaseLike): SqlAdapter;
-/**
- * Structural type matching the surface of `D1Database` we depend on, so the
- * SDK never imports `@cloudflare/workers-types`. Consumers pass their real
- * `D1Database` from `env.DB` and TS structural compatibility lines it up.
- */
-interface D1DatabaseLike {
-    prepare(sql: string): D1StmtLike;
-}
-interface D1StmtLike {
-    bind(...params: unknown[]): D1StmtLike;
-    run(): Promise<unknown>;
-    all<TRow = unknown>(): Promise<{
-        results?: TRow[];
-    }>;
-}
-/**
- * SQL-backed ConversationJournal. Two tables — runs (one row per runId, holds
- * start/halt timestamps + halt reason) and turns (one row per committed turn,
- * payload is the ConversationTurn JSON). Replays the turns table on
- * `loadRun` and writes append-only per `appendTurn`.
- */
-declare class SqlConversationJournal implements ConversationJournal {
-    private readonly db;
-    private readonly table;
-    /**
-     * @param db    SQL adapter (D1, postgres, sqlite, libSQL — all work)
-     * @param table Table-name prefix; the journal creates `${table}_runs` and
-     *              `${table}_turns`. Lets multiple journals share a database
-     *              without colliding (e.g. one per product surface).
-     */
-    constructor(db: SqlAdapter, table?: string);
-    /**
-     * Create the journal's tables if absent. Idempotent. Call once at deploy
-     * (or at app boot) — running on every request is harmless but adds latency.
-     */
-    migrate(): Promise<void>;
-    loadRun(runId: string): Promise<ConversationJournalEntry | undefined>;
-    beginRun(runId: string, startedAt: string): Promise<void>;
-    appendTurn(runId: string, turn: ConversationTurn): Promise<void>;
-    recordHalt(runId: string, halt: HaltReason, endedAt: string): Promise<void>;
-}
-
-/**
- *
- * Conversation orchestrator. Drives N participants in turn through their own
- * `AgentExecutionBackend`s, aggregating per-turn text + usage, enforcing
- * `maxTurns` / `maxCreditsCents` / `haltOn`, and emitting per-event stream
- * markers so callers can plumb the run through SSE without buffering.
- *
- * `runConversation` returns the full result; `runConversationStream` returns
- * an `AsyncIterable<ConversationStreamEvent>` for callers that want to
- * forward events as they arrive. Both share one driving loop.
- *
- * Distributed-systems primitives layered on top of the loop:
- *   - **Participant sessions**: one backend session per participant is resumed
- *     between turns; stateless backends receive one reconstructed transcript.
- *   - **Idempotent turn ids** — `turnId(runId, index, speaker)` stays stable
- *     across retries so caching gateways can dedupe.
- *   - **Durable journal** — optional `ConversationJournal` persists every
- *     committed turn; reusing a runId against the same journal resumes
- *     transparently from the last committed turn.
- *   - **Per-turn call policy** — deadline, retry-with-backoff, and a
- *     per-participant circuit breaker. Retries replay the same logical turn
- *     (same `turnId`); the retry loop lives inside the outer generator so
- *     deltas yield naturally without cross-coroutine buffering.
- *   - **Header propagation** — run/turn/depth headers (+ forwarded user
- *     authorization) stamped onto every outbound backend call so downstream
- *     gateways can bill the right user and enforce `X-Tangle-Forwarded-Depth`.
- *
- * Credit cap is enforced *between turns*, not mid-stream: a turn that
- * overshoots the cap completes, the cap then halts the conversation before
- * the next turn.
- *
- * @stable
- */
-
-declare function runConversation(conversation: Conversation, options: RunConversationOptions): Promise<ConversationResult>;
-/** Streaming conversation orchestrator: drives N participants in turn through their own backends, enforcing `maxTurns` / `maxCreditsCents` / `haltOn`, yielding per-event stream markers. */
-declare function runConversationStream(conversation: Conversation, options: RunConversationOptions): AsyncIterable<ConversationStreamEvent>;
-
-/**
- * `runPersonaConversation` — the persona loop runner: run a WORKER `AgentProfile`
- * (the agent under test) as a multi-round conversation driven by a PERSONA (the
- * simulated user), over the persistent conversation transcript.
- *
- * It is profiles-vs-profiles: the persona is itself a driver `AgentProfile` (an
- * LLM role-playing the user from its facts) — `runConversation` runs the two
- * against each other. Scripted persona turns are kept as a deterministic
- * fast-path. Only the WORKER is metered (it is the side under test); the
- * persona-driver is the test harness, not billed against the agent.
- *
- * `runPersonaDispatch` wraps the runner as a `ProfileDispatchFn` so it drops
- * straight into `runProfileMatrix({ dispatch })` — the same loop serves a single
- * cell and the whole matrix, replacing the per-agent hand-rolled
- * `dispatchWithSurface` bridges.
- */
-
-/** A persona that drives the conversation: either a full driver `AgentProfile`
- *  (an LLM user-sim) or a deterministic script of user turns (the fast-path). */
-type PersonaDriver = {
-    kind: 'profile';
-    profile: AgentProfile;
-} | {
-    kind: 'scripted';
-    turns: string[];
-};
-interface RunPersonaConversationOptions {
-    /** The agent under test. Metered; its rendered prompt leads its turns. */
-    worker: AgentProfile;
-    /** The simulated user driving the dialogue. */
-    persona: PersonaDriver;
-    /** Turn an `AgentProfile` into a runnable backend (router / sandbox / fake).
-     *  Applied to the worker and to a `profile`-kind persona. */
-    backendFor: (profile: AgentProfile, role: 'worker' | 'persona') => AgentExecutionBackend;
-    /** Render a profile's system prompt — prepended to that profile's messages. */
-    systemPromptOf: (profile: AgentProfile) => string;
-    /** Speaker-turn cap. Default for a scripted persona = `2 * turns.length`
-     *  (worker answers each user turn). REQUIRED for a `profile` persona. */
-    maxTurns?: number;
-    /** Kickoff message routed to the first speaker (the persona). Default 'Begin.' */
-    seed?: string;
-    /** Content-based "until satisfied" halt, called after every turn. `maxTurns` is the
-     *  hard ceiling; this is the early stop (the persona declares the goal met / unreachable). */
-    haltOn?: HaltPredicate;
-    signal?: AbortSignal;
-    /** Worker participant / transcript speaker label. Default 'agent'. */
-    workerName?: string;
-}
-interface PersonaConversationResult {
-    transcript: ConversationTurn[];
-    turns: number;
-    halted: HaltReason;
-    /** Worker-only spend (the side under test). */
-    costUsd: number;
-    tokensIn: number;
-    tokensOut: number;
-}
-/**
- * Run one worker profile against one persona as a multi-round conversation.
- * The persona leads (participant 0): it speaks, the worker answers, repeat,
- * until `maxTurns`. Returns the persistent transcript + worker-only usage.
- */
-declare function runPersonaConversation(opts: RunPersonaConversationOptions): Promise<PersonaConversationResult>;
-interface RunPersonaConfig<TScenario extends Scenario, TArtifact> {
-    /** Turn an `AgentProfile` into a runnable backend (router / sandbox / fake). */
-    backendFor: (profile: AgentProfile, role: 'worker' | 'persona') => AgentExecutionBackend;
-    /** Render a profile's system prompt. */
-    systemPromptOf: (profile: AgentProfile) => string;
-    /** The persona driving each scenario — a driver profile or scripted turns. */
-    personaOf: (scenario: TScenario) => PersonaDriver;
-    /** Build the scored artifact from the finished transcript. */
-    artifactOf: (transcript: ConversationTurn[], scenario: TScenario) => TArtifact;
-    /** Speaker-turn cap (required when a persona is profile-driven). */
-    maxTurns?: (scenario: TScenario) => number;
-    seed?: (scenario: TScenario) => string;
-    workerName?: string;
-    /** Provider- or executor-enforced maximum for the whole worker conversation.
-     * Required before execution when the enclosing campaign is cost-capped. */
-    maximumCharge?: MaximumCharge | ((worker: AgentProfile, scenario: TScenario) => MaximumCharge | undefined);
-}
-/**
- * Wrap {@link runPersonaConversation} as a `ProfileDispatchFn` for
- * `runProfileMatrix`: the profile axis is the worker-under-test, the scenario
- * axis is the persona, and the runner is the cell. Meters the worker through
- * `ctx.cost` so the matrix's backend-integrity guard sees real usage.
- */
-declare function runPersonaDispatch<TScenario extends Scenario, TArtifact>(config: RunPersonaConfig<TScenario, TArtifact>): ProfileDispatchFn<TScenario, TArtifact>;
-
-/**
- *
- * Deterministic turn identifier. Stable across retries of the same logical
- * turn so backends (and any caching gateway in between) can dedupe on it.
- * A retry triggered by a network blip or deadline timeout MUST produce the
- * same `turn_id`; only the underlying attempt count differs.
- *
- * Shape: `${runId}.t${index}.${speakerSlug}` — readable in logs, sortable by
- * turn index, attributable to a speaker. Slugify keeps the speaker portion
- * URL-safe so it can ride in HTTP headers without escaping.
- *
- * @stable
- */
-declare function turnId(runId: string, index: number, speaker: string): string;
-/**
- * Reduce a speaker name to ASCII alphanumerics + dashes. Preserves enough
- * substance to read in a log line; collisions between speakers within a
- * single Conversation are prevented by `defineConversation`'s
- * unique-name check, so the slug only needs to be deterministic, not unique.
- */
-declare function slugifySpeaker(speaker: string): string;
-
-export { type AuthSource, type BackendCallPolicy, type CircuitBreakerConfig, CircuitBreakerState, CircuitOpenError, type Conversation, type ConversationDriveState, type ConversationJournal, type ConversationJournalEntry, type ConversationParticipant, type ConversationPolicy, type ConversationResult, type ConversationStreamEvent, type ConversationTurn, type D1DatabaseLike, type D1StmtLike, DEFAULT_MAX_DEPTH, DeadlineExceededError, FORWARD_HEADERS, FileConversationJournal, type ForwardHeaderName, type HaltContext, type HaltPredicate, type HaltReason, type HaltSignal, InMemoryConversationJournal, type PersonaConversationResult, type PersonaDriver, type PropagatedHeaders, type RetryBackoff, type RetryableErrorPredicate, type RunConversationOptions, type RunPersonaConfig, type RunPersonaConversationOptions, type SqlAdapter, SqlConversationJournal, type TurnOrder, buildForwardHeaders, computeBackoff, createConversationBackend, d1ToSqlAdapter, defaultIsRetryable, defineConversation, isDepthExceeded, makePerAttemptSignal, readDepth, runConversation, runConversationStream, runPersonaConversation, runPersonaDispatch, sleep, slugifySpeaker, turnId };
+import { $ as sleep, A as RunConversationOptions, B as buildForwardHeaders, C as ConversationResult, D as HaltPredicate, E as HaltContext, F as InMemoryConversationJournal, G as CircuitBreakerState, H as readDepth, I as DEFAULT_MAX_DEPTH, J as RetryBackoff, K as CircuitOpenError, L as FORWARD_HEADERS, M as ConversationJournal, N as ConversationJournalEntry, O as HaltReason, P as FileConversationJournal, Q as makePerAttemptSignal, R as ForwardHeaderName, S as ConversationPolicy, T as ConversationTurn, U as BackendCallPolicy, V as isDepthExceeded, W as CircuitBreakerConfig, X as computeBackoff, Y as RetryableErrorPredicate, Z as defaultIsRetryable, _ as createConversationBackend, a as RunPersonaConfig, b as ConversationDriveState, c as runPersonaDispatch, d as D1DatabaseLike, f as D1StmtLike, g as defineConversation, h as d1ToSqlAdapter, i as PersonaDriver, j as TurnOrder, k as HaltSignal, l as runConversation, m as SqlConversationJournal, n as turnId, o as RunPersonaConversationOptions, p as SqlAdapter, q as DeadlineExceededError, r as PersonaConversationResult, s as runPersonaConversation, t as slugifySpeaker, u as runConversationStream, v as AuthSource, w as ConversationStreamEvent, x as ConversationParticipant, y as Conversation, z as PropagatedHeaders } from "./index-Efjb3nrQ.js";
+export { type AuthSource, type BackendCallPolicy, type CircuitBreakerConfig, CircuitBreakerState, CircuitOpenError, type Conversation, type ConversationDriveState, type ConversationJournal, type ConversationJournalEntry, type ConversationParticipant, type ConversationPolicy, type ConversationResult, type ConversationStreamEvent, type ConversationTurn, type D1DatabaseLike, type D1StmtLike, DEFAULT_MAX_DEPTH, DeadlineExceededError, FORWARD_HEADERS, FileConversationJournal, type ForwardHeaderName, type HaltContext, type HaltPredicate, type HaltReason, type HaltSignal, InMemoryConversationJournal, type PersonaConversationResult, type PersonaDriver, type PropagatedHeaders, type RetryBackoff, type RetryableErrorPredicate, type RunConversationOptions, type RunPersonaConfig, type RunPersonaConversationOptions, type SqlAdapter, SqlConversationJournal, type TurnOrder, buildForwardHeaders, computeBackoff, createConversationBackend, d1ToSqlAdapter, defaultIsRetryable, defineConversation, isDepthExceeded, makePerAttemptSignal, readDepth, runConversation, runConversationStream, runPersonaConversation, runPersonaDispatch, sleep, slugifySpeaker, turnId };