@tangle-network/agent-runtime 0.104.0 → 0.106.0

package/dist/index-Efjb3nrQ.d.ts

@@ -0,0 +1,671 @@
+import { b as RuntimeSessionStore, i as AgentExecutionBackend } from "./types-C9j4qg6l.js";
+import { AgentProfile, MaximumCharge } from "@tangle-network/agent-eval";
+import { ProfileDispatchFn, Scenario } from "@tangle-network/agent-eval/campaign";
+//#region src/conversation/call-policy.d.ts
+/**
+ *
+ * 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>;
+//#endregion
+//#region src/conversation/headers.d.ts
+/**
+ *
+ * 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>>;
+//#endregion
+//#region src/conversation/journal.d.ts
+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;
+}
+//#endregion
+//#region src/conversation/types.d.ts
+/** @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;
+};
+//#endregion
+//#region src/conversation/conversation-backend.d.ts
+/** Adapt a multi-participant conversation into the standard execution backend contract. */
+declare function createConversationBackend(options: {
+  conversation: Conversation;
+  /** Optional backend kind label. Defaults to `'conversation'`. */
+  kind?: string;
+}): AgentExecutionBackend;
+//#endregion
+//#region src/conversation/define-conversation.d.ts
+/** Validate and define a conversation before execution. */
+declare function defineConversation(input: {
+  participants: ConversationParticipant[];
+  policy: ConversationPolicy;
+}): Conversation;
+//#endregion
+//#region src/conversation/journal-sql.d.ts
+/**
+ * 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>;
+}
+//#endregion
+//#region src/conversation/run-conversation.d.ts
+/** Run a conversation to completion and return its terminal result. */
+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>;
+//#endregion
+//#region src/conversation/run-persona.d.ts
+/** 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>;
+//#endregion
+//#region src/conversation/turn-id.d.ts
+/**
+ *
+ * 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;
+//#endregion
+export { sleep as $, RunConversationOptions as A, buildForwardHeaders as B, ConversationResult as C, HaltPredicate as D, HaltContext as E, InMemoryConversationJournal as F, CircuitBreakerState as G, readDepth as H, DEFAULT_MAX_DEPTH as I, RetryBackoff as J, CircuitOpenError as K, FORWARD_HEADERS as L, ConversationJournal as M, ConversationJournalEntry as N, HaltReason as O, FileConversationJournal as P, makePerAttemptSignal as Q, ForwardHeaderName as R, ConversationPolicy as S, ConversationTurn as T, BackendCallPolicy as U, isDepthExceeded as V, CircuitBreakerConfig as W, computeBackoff as X, RetryableErrorPredicate as Y, defaultIsRetryable as Z, createConversationBackend as _, RunPersonaConfig as a, ConversationDriveState as b, runPersonaDispatch as c, D1DatabaseLike as d, D1StmtLike as f, defineConversation as g, d1ToSqlAdapter as h, PersonaDriver as i, TurnOrder as j, HaltSignal as k, runConversation as l, SqlConversationJournal as m, turnId as n, RunPersonaConversationOptions as o, SqlAdapter as p, DeadlineExceededError as q, PersonaConversationResult as r, runPersonaConversation as s, slugifySpeaker as t, runConversationStream as u, AuthSource as v, ConversationStreamEvent as w, ConversationParticipant as x, Conversation as y, PropagatedHeaders as z };
+//# sourceMappingURL=index-Efjb3nrQ.d.ts.map