@tangle-network/agent-runtime 0.25.2 → 0.27.0

package/dist/index.d.ts

@@ -1,9 +1,9 @@
 import { AgentEvalError, KnowledgeReadinessReport, ControlEvalResult, KnowledgeRequirement } from '@tangle-network/agent-eval';
 export { AgentEvalError, AgentEvalErrorCode, ConfigError, ControlBudget, ControlDecision, ControlEvalResult, ControlRunResult, ControlStep, DataAcquisitionPlan, JudgeError, KnowledgeReadinessReport, KnowledgeRequirement, NotFoundError, RunRecord, ValidationError } from '@tangle-network/agent-eval';
-import { a as AgentBackendInput, b as AgentExecutionBackend, O as OpenAIChatTool, c as OpenAIChatToolChoice, d as AgentBackendContext, R as RuntimeStreamEvent, K as KnowledgeReadinessDecision, e as RunAgentTaskOptions, f as AgentTaskRunResult, g as RunAgentTaskStreamOptions, h as AgentRuntimeEvent, i as AgentTaskStatus, j as RuntimeSessionStore, k as RuntimeSession } from './types-BFgFD_sl.js';
-export { l as AgentAdapter, m as AgentKnowledgeProvider, n as AgentRuntimeEventSink, o as AgentTaskContext, A as AgentTaskSpec, B as BackendErrorDetail } from './types-BFgFD_sl.js';
-export { O as OtelAttribute, a as OtelExportConfig, b as OtelExporter, c as OtelSpan, d as createOtelExporter, l as loopEventToOtelSpan, m as mcpToolsForRuntimeMcp, e as mcpToolsForRuntimeMcpSubset } from './otel-export-B33Cy_60.js';
-export { R as RuntimeRunHandle, a as RuntimeRunPersistenceAdapter, b as RuntimeRunRow, s as startRuntimeRun } from './runtime-run-D5ItCKl_.js';
+import { a as AgentBackendInput, b as AgentExecutionBackend, O as OpenAIChatTool, c as OpenAIChatToolChoice, d as AgentBackendContext, R as RuntimeStreamEvent, K as KnowledgeReadinessDecision, e as RunAgentTaskOptions, f as AgentTaskRunResult, g as RunAgentTaskStreamOptions, h as AgentRuntimeEvent, i as AgentTaskStatus, j as RuntimeSessionStore, k as RuntimeSession } from './types-CsCCryln.js';
+export { l as AgentAdapter, m as AgentKnowledgeProvider, n as AgentRuntimeEventSink, o as AgentTaskContext, A as AgentTaskSpec, B as BackendErrorDetail } from './types-CsCCryln.js';
+export { b as OtelAttribute, c as OtelExportConfig, O as OtelExporter, d as OtelSpan, e as createOtelExporter, l as loopEventToOtelSpan, m as mcpToolsForRuntimeMcp, a as mcpToolsForRuntimeMcpSubset } from './otel-export-B2UBcPV4.js';
+export { R as RuntimeRunHandle, a as RuntimeRunPersistenceAdapter, b as RuntimeRunRow, s as startRuntimeRun } from './runtime-run-B8VIiOhI.js';
 
 /**
  * @stable
@@ -126,6 +126,692 @@ declare function createOpenAICompatibleBackend<TInput extends AgentBackendInput
     retry?: BackendRetryPolicy;
 }): AgentExecutionBackend<TInput>;
 
+/**
+ * @stable
+ *
+ * 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.
+ */
+/** 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;
+}
+declare class CircuitOpenError extends Error {
+    constructor(participant: string, retryAfterMs: number);
+}
+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;
+declare function sleep(ms: number): Promise<void>;
+
+/**
+ * @stable
+ *
+ * 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`.
+ */
+/** 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>>;
+
+/**
+ * @stable
+ *
+ * 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.
+ */
+
+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>;
+}
+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;
+}
+
+/**
+ * @stable
+ *
+ * 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 */
+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;
+    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;
+    /**
+     * 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;
+};
+
+/**
+ * @stable
+ *
+ * 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.
+ */
+
+declare function createConversationBackend(options: {
+    conversation: Conversation;
+    /** Optional backend kind label. Defaults to `'conversation'`. */
+    kind?: string;
+}): AgentExecutionBackend;
+
+/**
+ * @stable
+ *
+ * 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.
+ */
+
+declare function defineConversation(input: {
+    participants: ConversationParticipant[];
+    policy: ConversationPolicy;
+}): Conversation;
+
+/**
+ * @stable
+ *
+ * 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()
+ */
+
+/**
+ * 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>;
+}
+
+/**
+ * @stable
+ *
+ * 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:
+ *   - **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.
+ */
+
+declare function runConversation(conversation: Conversation, options: RunConversationOptions): Promise<ConversationResult>;
+declare function runConversationStream(conversation: Conversation, options: RunConversationOptions): AsyncIterable<ConversationStreamEvent>;
+
+/**
+ * @stable
+ *
+ * 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.
+ */
+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;
+
 /**
  * `handleChatTurn` — framework-neutral chat-turn HTTP orchestrator.
  * Owns the NDJSON `ChatStreamEvent` line protocol, the `session.run.*`
@@ -577,4 +1263,4 @@ declare function readinessServerSentEvent(report: KnowledgeReadinessReport, opti
 /** @stable */
 declare function runtimeStreamServerSentEvent(event: RuntimeStreamEvent, options?: RuntimeTelemetryOptions & ServerSentEventOptions): string;
 
-export { AgentBackendContext, AgentBackendInput, AgentExecutionBackend, AgentRuntimeEvent, AgentTaskRunResult, AgentTaskStatus, BackendTransportError, type ChatStreamEvent, type ChatTurnHooks, type ChatTurnIdentity, type ChatTurnProducer, type ChatTurnResult, DEFAULT_ROUTER_BASE_URL, InMemoryRuntimeSessionStore, type ModelInfo, OpenAIChatTool, OpenAIChatToolChoice, type ResolvedChatModel, type RouterEnv, type RunChatTurnInput, type RuntimeEventCollector, RuntimeRunStateError, RuntimeSessionStore, RuntimeStreamEvent, type RuntimeStreamEventCollector, type RuntimeTelemetryOptions, type SanitizedKnowledgeReadinessReport, cleanModelId, createIterableBackend, createOpenAICompatibleBackend, createRuntimeEventCollector, createRuntimeStreamEventCollector, createSandboxPromptBackend, decideKnowledgeReadiness, deriveExecutionId, getModels, handleChatTurn, readinessServerSentEvent, resolveChatModel, resolveRouterBaseUrl, runAgentTask, runAgentTaskStream, runtimeStreamServerSentEvent, sanitizeAgentRuntimeEvent, sanitizeKnowledgeReadinessReport, sanitizeRuntimeStreamEvent, validateChatModelId };
+export { AgentBackendContext, AgentBackendInput, AgentExecutionBackend, AgentRuntimeEvent, AgentTaskRunResult, AgentTaskStatus, type AuthSource, type BackendCallPolicy, BackendTransportError, type ChatStreamEvent, type ChatTurnHooks, type ChatTurnIdentity, type ChatTurnProducer, type ChatTurnResult, 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, DEFAULT_ROUTER_BASE_URL, DeadlineExceededError, FORWARD_HEADERS, FileConversationJournal, type ForwardHeaderName, type HaltContext, type HaltPredicate, type HaltReason, type HaltSignal, InMemoryConversationJournal, InMemoryRuntimeSessionStore, type ModelInfo, OpenAIChatTool, OpenAIChatToolChoice, type PropagatedHeaders, type ResolvedChatModel, type RetryBackoff, type RetryableErrorPredicate, type RouterEnv, type RunChatTurnInput, type RunConversationOptions, type RuntimeEventCollector, RuntimeRunStateError, RuntimeSessionStore, RuntimeStreamEvent, type RuntimeStreamEventCollector, type RuntimeTelemetryOptions, type SanitizedKnowledgeReadinessReport, type SqlAdapter, SqlConversationJournal, type TurnOrder, buildForwardHeaders, cleanModelId, computeBackoff, createConversationBackend, createIterableBackend, createOpenAICompatibleBackend, createRuntimeEventCollector, createRuntimeStreamEventCollector, createSandboxPromptBackend, d1ToSqlAdapter, decideKnowledgeReadiness, defaultIsRetryable, defineConversation, deriveExecutionId, getModels, handleChatTurn, isDepthExceeded, makePerAttemptSignal, readDepth, readinessServerSentEvent, resolveChatModel, resolveRouterBaseUrl, runAgentTask, runAgentTaskStream, runConversation, runConversationStream, runtimeStreamServerSentEvent, sanitizeAgentRuntimeEvent, sanitizeKnowledgeReadinessReport, sanitizeRuntimeStreamEvent, sleep, slugifySpeaker, turnId, validateChatModelId };