@tangle-network/agent-runtime 0.25.2 → 0.27.0

package/dist/index.js

@@ -175,7 +175,14 @@ function createOpenAICompatibleBackend(options) {
             method: "POST",
             headers: {
               Authorization: `Bearer ${options.apiKey}`,
-              "Content-Type": "application/json"
+              "Content-Type": "application/json",
+              // Cross-gateway forwarding: when this call is part of a
+              // multi-agent conversation, the runner stamps run/turn/
+              // depth/forwarded-auth headers onto the context. They flow
+              // through to the downstream gateway verbatim so the original
+              // user gets billed, the recursion depth stays bounded, and
+              // the trace correlates across hops.
+              ...context.propagatedHeaders ?? {}
             },
             body: requestBody,
             signal: attemptSignal.signal
@@ -624,6 +631,1009 @@ function stringValue(value) {
   return typeof value === "string" && value.length > 0 ? value : void 0;
 }
 
+// src/conversation/call-policy.ts
+var CircuitOpenError = class extends Error {
+  constructor(participant, retryAfterMs) {
+    super(
+      `circuit open for participant '${participant}'; ${retryAfterMs}ms remaining before retry allowed`
+    );
+    this.name = "CircuitOpenError";
+  }
+};
+var DeadlineExceededError = class extends Error {
+  constructor(deadlineMs) {
+    super(`backend call exceeded per-attempt deadline of ${deadlineMs}ms`);
+    this.name = "DeadlineExceededError";
+  }
+};
+var defaultIsRetryable = (err) => {
+  if (err instanceof DeadlineExceededError) return true;
+  if (err instanceof Error) {
+    const name = err.name;
+    const message = err.message.toLowerCase();
+    if (name === "AbortError" || name === "TimeoutError") return true;
+    if (message.includes("econnreset") || message.includes("etimedout") || message.includes("econnrefused") || message.includes("socket hang up") || message.includes("network") || message.includes("fetch failed")) {
+      return true;
+    }
+  }
+  return false;
+};
+var CircuitBreakerState = class {
+  constructor(config) {
+    this.config = config;
+  }
+  config;
+  consecutiveFailures = 0;
+  openedAt;
+  /**
+   * Check whether the next call is allowed. Throws `CircuitOpenError` when
+   * the breaker is open and the cooldown hasn't elapsed.
+   */
+  preflight(participant, now = Date.now()) {
+    if (!this.config || this.openedAt === void 0) return;
+    const remaining = this.config.cooldownMs - (now - this.openedAt);
+    if (remaining > 0) {
+      throw new CircuitOpenError(participant, remaining);
+    }
+    this.openedAt = void 0;
+    this.consecutiveFailures = 0;
+  }
+  recordSuccess() {
+    this.consecutiveFailures = 0;
+    this.openedAt = void 0;
+  }
+  recordFailure(now = Date.now()) {
+    if (!this.config) return;
+    this.consecutiveFailures += 1;
+    if (this.consecutiveFailures >= this.config.failuresToOpen) {
+      this.openedAt = now;
+    }
+  }
+};
+function makePerAttemptSignal(parentSignal, deadlineMs) {
+  const controller = new AbortController();
+  let deadlineError;
+  const cleanups = [];
+  if (parentSignal) {
+    if (parentSignal.aborted) controller.abort(parentSignal.reason);
+    else {
+      const onAbort = () => controller.abort(parentSignal.reason);
+      parentSignal.addEventListener("abort", onAbort, { once: true });
+      cleanups.push(() => parentSignal.removeEventListener("abort", onAbort));
+    }
+  }
+  if (deadlineMs !== void 0) {
+    const ms = deadlineMs;
+    const timer = setTimeout(() => {
+      deadlineError = new DeadlineExceededError(ms);
+      controller.abort(deadlineError);
+    }, ms);
+    cleanups.push(() => clearTimeout(timer));
+  }
+  return {
+    signal: controller.signal,
+    dispose() {
+      for (const c of cleanups) c();
+    },
+    getDeadlineError() {
+      return deadlineError;
+    }
+  };
+}
+function computeBackoff(spec, attempt) {
+  if (spec === void 0) {
+    const base = 250;
+    const jitter = Math.floor(Math.random() * base);
+    return base * 2 ** (attempt - 1) + jitter;
+  }
+  if (typeof spec === "function") return Math.max(0, spec(attempt));
+  return Math.max(0, spec);
+}
+function sleep2(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/conversation/headers.ts
+var FORWARD_HEADERS = {
+  /** Forwarded original-user identity (`Bearer sk-tan-<user>`); downstream gateways bill against this. */
+  authorization: "x-tangle-forwarded-authorization",
+  /** Monotonically incremented on every gateway hop. Refused at MAX_DEPTH. */
+  depth: "x-tangle-forwarded-depth",
+  /** Top-level conversation run identifier, propagated through every nested call. */
+  runId: "x-tangle-runid",
+  /** This call's turn within the run; deterministic + stable across retries. */
+  turnId: "x-tangle-turnid",
+  /** When the call is *inside* another turn (recursion), the parent turn's id. */
+  parentTurnId: "x-tangle-parent-turnid",
+  /** Logical conversation peer label at the sending side, for trace stitching. */
+  speaker: "x-tangle-speaker"
+};
+var DEFAULT_MAX_DEPTH = 4;
+function lc(name) {
+  return name.toLowerCase();
+}
+function readDepth(headers) {
+  const raw = pickHeader(headers, FORWARD_HEADERS.depth);
+  if (raw === void 0 || raw === "") return 0;
+  const n = Number(raw);
+  if (!Number.isInteger(n) || n < 0) {
+    throw new Error(
+      `invalid ${FORWARD_HEADERS.depth} header value '${raw}' \u2014 must be a non-negative integer`
+    );
+  }
+  return n;
+}
+function isDepthExceeded(inboundDepth, max = DEFAULT_MAX_DEPTH) {
+  return inboundDepth >= max;
+}
+function buildForwardHeaders(input) {
+  const out = {
+    [FORWARD_HEADERS.depth]: String(input.inboundDepth + 1),
+    [FORWARD_HEADERS.runId]: input.runId,
+    [FORWARD_HEADERS.turnId]: input.turnId,
+    [FORWARD_HEADERS.speaker]: input.speaker
+  };
+  if (input.forwardedAuthorization !== void 0) {
+    out[FORWARD_HEADERS.authorization] = input.forwardedAuthorization;
+  }
+  if (input.parentTurnId !== void 0) {
+    out[FORWARD_HEADERS.parentTurnId] = input.parentTurnId;
+  }
+  return out;
+}
+function pickHeader(headers, name) {
+  const target = lc(name);
+  for (const key of Object.keys(headers)) {
+    if (lc(key) === target) {
+      const value = headers[key];
+      if (Array.isArray(value)) return value[0];
+      return value;
+    }
+  }
+  return void 0;
+}
+
+// src/conversation/turn-id.ts
+function turnId(runId, index, speaker) {
+  return `${runId}.t${index}.${slugifySpeaker(speaker)}`;
+}
+function slugifySpeaker(speaker) {
+  const cleaned = speaker.normalize("NFKD").replace(/[^\w-]+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "").toLowerCase();
+  return cleaned || "anon";
+}
+
+// src/conversation/run-conversation.ts
+async function runConversation(conversation, options) {
+  let result;
+  for await (const event of runConversationStream(conversation, options)) {
+    if (options.onEvent) await options.onEvent(event);
+    if (event.type === "conversation_end") result = event.result;
+  }
+  if (!result) {
+    throw new BackendTransportError(
+      "conversation",
+      "conversation stream ended without a conversation_end event"
+    );
+  }
+  return result;
+}
+async function* runConversationStream(conversation, options) {
+  const runId = options.runId ?? `conv_${crypto.randomUUID()}`;
+  const inboundDepth = options.inboundDepth ?? 0;
+  const callerHeaders = options.propagatedHeaders ?? {};
+  const forwardedAuthorization = callerHeaders[FORWARD_HEADERS.authorization];
+  const breakers = /* @__PURE__ */ new Map();
+  for (const participant of conversation.participants) {
+    const cfg = participant.callPolicy?.circuitBreaker ?? conversation.policy.defaultCallPolicy?.circuitBreaker;
+    breakers.set(participant.name, new CircuitBreakerState(cfg));
+  }
+  let transcript = [];
+  let spentCreditsCents = 0;
+  let startedAt = nowIso();
+  let resumed = false;
+  if (options.journal) {
+    const prior = await options.journal.loadRun(runId);
+    if (prior) {
+      if (prior.halted) {
+        const replayResult = {
+          runId,
+          transcript: prior.turns,
+          turns: prior.turns.length,
+          spentCreditsCents: prior.turns.reduce(
+            (sum, t) => sum + centsFromUsd(t.usage?.costUsd ?? 0),
+            0
+          ),
+          halted: prior.halted,
+          durationMs: 0,
+          startedAt: prior.startedAt,
+          endedAt: prior.endedAt ?? prior.startedAt
+        };
+        yield {
+          type: "conversation_resumed",
+          runId,
+          participants: conversation.participants.map((p) => p.name),
+          transcript: prior.turns,
+          timestamp: nowIso()
+        };
+        yield { type: "conversation_end", runId, result: replayResult, timestamp: nowIso() };
+        return;
+      }
+      transcript = [...prior.turns];
+      spentCreditsCents = transcript.reduce(
+        (sum, t) => sum + centsFromUsd(t.usage?.costUsd ?? 0),
+        0
+      );
+      startedAt = prior.startedAt;
+      resumed = true;
+    } else {
+      await options.journal.beginRun(runId, startedAt);
+    }
+  }
+  const startedAtMs = Date.now();
+  if (resumed) {
+    yield {
+      type: "conversation_resumed",
+      runId,
+      participants: conversation.participants.map((p) => p.name),
+      // Snapshot the resumed transcript — the live `transcript` array gets
+      // pushed to as the run continues, so handing the bare reference to a
+      // subscriber would leak future writes into a past event.
+      transcript: [...transcript],
+      timestamp: nowIso()
+    };
+  } else {
+    yield {
+      type: "conversation_start",
+      runId,
+      participants: conversation.participants.map((p) => p.name),
+      seed: options.seed,
+      timestamp: startedAt
+    };
+  }
+  let currentInput = transcript.length === 0 ? options.seed : transcript[transcript.length - 1]?.text ?? options.seed;
+  let halt;
+  const initialOffset = transcript.length;
+  for (let turnIndex = initialOffset; turnIndex < conversation.policy.maxTurns; turnIndex++) {
+    if (options.signal?.aborted) {
+      halt = { kind: "abort" };
+      break;
+    }
+    if (conversation.policy.maxCreditsCents !== void 0 && spentCreditsCents >= conversation.policy.maxCreditsCents) {
+      halt = {
+        kind: "max_credits",
+        spentCents: spentCreditsCents,
+        capCents: conversation.policy.maxCreditsCents
+      };
+      break;
+    }
+    const speakerIdx = selectSpeaker(
+      conversation.policy.turnOrder,
+      conversation.participants.length,
+      { transcript, turnIndex, spentCreditsCents }
+    );
+    const speaker = conversation.participants[speakerIdx];
+    if (!speaker) {
+      throw new BackendTransportError(
+        "conversation",
+        `turnOrder selector returned out-of-range index ${speakerIdx} for ${conversation.participants.length} participants`
+      );
+    }
+    const tid = turnId(runId, turnIndex, speaker.name);
+    const callPolicy = speaker.callPolicy ?? conversation.policy.defaultCallPolicy;
+    const breaker = breakers.get(speaker.name);
+    if (!breaker) {
+      throw new BackendTransportError(
+        "conversation",
+        `internal: no circuit-breaker state registered for participant '${speaker.name}'`
+      );
+    }
+    const isRetryable = callPolicy?.isRetryable ?? defaultIsRetryable;
+    const totalAttempts = 1 + (callPolicy?.maxRetries ?? 0);
+    yield {
+      type: "turn_start",
+      runId,
+      index: turnIndex,
+      speaker: speaker.name,
+      turnId: tid,
+      attempt: 1,
+      timestamp: nowIso()
+    };
+    let aggregator;
+    let attemptCount = 0;
+    let lastError;
+    let breakerOpenFailure;
+    for (let attempt = 1; attempt <= totalAttempts; attempt++) {
+      attemptCount = attempt;
+      try {
+        breaker.preflight(speaker.name);
+      } catch (err) {
+        breakerOpenFailure = err;
+        break;
+      }
+      if (attempt > 1) {
+        yield {
+          type: "turn_retry",
+          runId,
+          index: turnIndex,
+          speaker: speaker.name,
+          turnId: tid,
+          attempt,
+          reason: lastError instanceof Error ? lastError.message : String(lastError),
+          timestamp: nowIso()
+        };
+      }
+      const perAttempt = makePerAttemptSignal(options.signal, callPolicy?.perAttemptDeadlineMs);
+      const localAgg = new TurnAggregator({
+        index: turnIndex,
+        speaker: speaker.name,
+        startedAt: nowIso()
+      });
+      try {
+        for await (const delta of driveSingleAttempt({
+          speaker,
+          participants: conversation.participants,
+          input: currentInput,
+          turnIndex,
+          runId,
+          turnId: tid,
+          transcript,
+          signal: perAttempt.signal,
+          aggregator: localAgg,
+          propagatedHeaders: buildForwardHeaders({
+            inboundDepth,
+            // When the participant elects to pay for its own outbound calls,
+            // drop the forwarded user identity so the downstream gateway
+            // bills the participant's own credentials instead. The backend
+            // brings its own `Authorization` header at construction time
+            // (e.g. `createOpenAICompatibleBackend({ apiKey: sk-tan-AGENT })`);
+            // omitting the forwarded header is what flips the billing target.
+            forwardedAuthorization: resolveAuthForwarding(speaker, {
+              transcript,
+              turnIndex,
+              spentCreditsCents
+            }) ? forwardedAuthorization : void 0,
+            runId,
+            turnId: tid,
+            parentTurnId: options.parentTurnId,
+            speaker: speaker.name
+          })
+        })) {
+          yield {
+            type: "turn_text_delta",
+            runId,
+            index: turnIndex,
+            speaker: speaker.name,
+            turnId: tid,
+            text: delta.text,
+            timestamp: delta.timestamp
+          };
+        }
+        perAttempt.dispose();
+        breaker.recordSuccess();
+        aggregator = localAgg;
+        break;
+      } catch (err) {
+        perAttempt.dispose();
+        breaker.recordFailure();
+        lastError = perAttempt.getDeadlineError() ?? err;
+        if (attempt >= totalAttempts || !isRetryable(lastError)) {
+          break;
+        }
+        await sleep2(computeBackoff(callPolicy?.retryBackoffMs, attempt));
+      }
+    }
+    if (!aggregator) {
+      const failure = breakerOpenFailure ?? lastError;
+      const message = failure instanceof Error ? failure.message : String(failure);
+      halt = { kind: "participant_error", participant: speaker.name, message };
+      break;
+    }
+    const turn = aggregator.toTurn({ turnId: tid, attempts: attemptCount });
+    transcript.push(turn);
+    spentCreditsCents += centsFromUsd(turn.usage?.costUsd ?? 0);
+    if (options.journal) {
+      await options.journal.appendTurn(runId, turn);
+    }
+    yield { type: "turn_end", runId, turn, timestamp: nowIso() };
+    if (conversation.policy.haltOn) {
+      const haltCtx = {
+        transcript,
+        lastTurn: turn,
+        turnIndex,
+        spentCreditsCents
+      };
+      const decision = await conversation.policy.haltOn(haltCtx);
+      if (decision === true) {
+        halt = { kind: "predicate", reason: "predicate_true" };
+        break;
+      }
+      if (typeof decision === "object" && decision !== null && decision.halted) {
+        halt = { kind: "predicate", reason: decision.reason };
+        break;
+      }
+    }
+    currentInput = turn.text;
+  }
+  if (!halt) halt = { kind: "max_turns", turns: transcript.length };
+  const endedAt = nowIso();
+  const result = {
+    runId,
+    transcript,
+    turns: transcript.length,
+    spentCreditsCents,
+    halted: halt,
+    durationMs: Date.now() - startedAtMs,
+    startedAt,
+    endedAt
+  };
+  if (options.journal) {
+    await options.journal.recordHalt(runId, halt, endedAt);
+  }
+  yield { type: "conversation_end", runId, result, timestamp: endedAt };
+}
+async function* driveSingleAttempt(args) {
+  const task = {
+    id: args.turnId,
+    intent: args.input,
+    metadata: {
+      runId: args.runId,
+      turnId: args.turnId,
+      turnIndex: args.turnIndex,
+      speaker: args.speaker.name,
+      participants: args.participants.map((p) => p.name)
+    }
+  };
+  const knowledge = passingReadiness(task.id);
+  const messages = buildMessagesFor(args.speaker.name, args.transcript, args.input);
+  const backendInput = { task, message: args.input, messages };
+  const startCtx = {
+    task,
+    knowledge,
+    signal: args.signal,
+    runId: args.runId,
+    turnId: args.turnId,
+    propagatedHeaders: args.propagatedHeaders
+  };
+  const session = args.speaker.backend.start ? touchSession(await args.speaker.backend.start(backendInput, startCtx)) : newRuntimeSession(args.speaker.backend.kind, void 0, {
+    runId: args.runId,
+    turnIndex: args.turnIndex,
+    turnId: args.turnId,
+    speaker: args.speaker.name
+  });
+  const streamCtx = {
+    task,
+    knowledge,
+    session,
+    signal: args.signal,
+    runId: args.runId,
+    turnId: args.turnId,
+    propagatedHeaders: args.propagatedHeaders
+  };
+  for await (const event of args.speaker.backend.stream(backendInput, streamCtx)) {
+    if (args.signal.aborted) {
+      const reason = args.signal.reason;
+      throw reason instanceof Error ? reason : new Error("aborted");
+    }
+    if (event.type === "text_delta") {
+      args.aggregator.appendText(event.text);
+      yield { text: event.text, timestamp: event.timestamp };
+    } else if (event.type === "llm_call") {
+      args.aggregator.recordUsage(event);
+    } else if (event.type === "final") {
+      args.aggregator.adoptFinalText(event.text);
+    }
+  }
+}
+var TurnAggregator = class {
+  constructor(base) {
+    this.base = base;
+  }
+  base;
+  text = "";
+  adoptedFinal = false;
+  usage;
+  appendText(text) {
+    if (this.adoptedFinal) return;
+    this.text += text;
+  }
+  /**
+   * Use the backend's `final.text` only when no streamed deltas were observed.
+   * Some backends emit deltas AND a final summary; treating both as content
+   * would double-count.
+   */
+  adoptFinalText(text) {
+    if (!text) return;
+    if (this.text.length > 0) return;
+    this.text = text;
+    this.adoptedFinal = true;
+  }
+  recordUsage(event) {
+    const u = this.usage ?? {};
+    if (event.tokensIn !== void 0) u.tokensIn = (u.tokensIn ?? 0) + event.tokensIn;
+    if (event.tokensOut !== void 0) u.tokensOut = (u.tokensOut ?? 0) + event.tokensOut;
+    if (event.costUsd !== void 0) u.costUsd = (u.costUsd ?? 0) + event.costUsd;
+    if (event.latencyMs !== void 0) u.latencyMs = event.latencyMs;
+    if (event.model !== void 0) u.model = event.model;
+    this.usage = u;
+  }
+  toTurn(meta) {
+    return {
+      index: this.base.index,
+      speaker: this.base.speaker,
+      turnId: meta.turnId,
+      text: this.text.trim(),
+      usage: this.usage,
+      attempts: meta.attempts,
+      startedAt: this.base.startedAt,
+      endedAt: nowIso()
+    };
+  }
+};
+function buildMessagesFor(speakerName, transcript, currentInput) {
+  const messages = [];
+  for (const turn of transcript) {
+    if (turn.speaker === speakerName) {
+      messages.push({ role: "assistant", content: turn.text });
+    } else {
+      messages.push({ role: "user", content: `[${turn.speaker}] ${turn.text}` });
+    }
+  }
+  if (currentInput) messages.push({ role: "user", content: currentInput });
+  return messages;
+}
+function resolveAuthForwarding(participant, state) {
+  const decision = typeof participant.authSource === "function" ? participant.authSource(state) : participant.authSource ?? "forward-user";
+  return decision === "forward-user";
+}
+function selectSpeaker(order, participantCount, state) {
+  const resolved = order ?? (participantCount === 2 ? "alternate" : "round-robin");
+  if (resolved === "alternate" || resolved === "round-robin") {
+    return state.turnIndex % participantCount;
+  }
+  if (typeof resolved === "function") {
+    const idx = resolved(state);
+    if (!Number.isInteger(idx) || idx < 0 || idx >= participantCount) {
+      throw new BackendTransportError(
+        "conversation",
+        `turnOrder function returned invalid index ${String(idx)} for ${participantCount} participants`
+      );
+    }
+    return idx;
+  }
+  throw new BackendTransportError("conversation", `unknown turnOrder: ${String(resolved)}`);
+}
+function centsFromUsd(usd) {
+  return Math.round(usd * 100);
+}
+function passingReadiness(taskId) {
+  return {
+    taskId,
+    readinessScore: 1,
+    blockingMissingRequirements: [],
+    nonBlockingGaps: [],
+    recommendedAction: "run_agent",
+    bundle: {
+      taskId,
+      requirements: [],
+      evidenceIds: [],
+      claimIds: [],
+      wikiPageIds: [],
+      userAnswers: {},
+      missing: [],
+      readinessScore: 1
+    },
+    severity: "info",
+    reason: "conversation-mode: readiness gating not applied per-turn"
+  };
+}
+
+// src/conversation/conversation-backend.ts
+function createConversationBackend(options) {
+  const kind = options.kind ?? "conversation";
+  return {
+    kind,
+    start(_input, context) {
+      return newRuntimeSession(kind, context.requestedSessionId, {
+        participants: options.conversation.participants.map((p) => p.name)
+      });
+    },
+    async *stream(input, context) {
+      const seed = input.message ?? input.messages?.at(-1)?.content ?? context.task.intent;
+      const task = context.task;
+      const session = context.session;
+      yield { type: "backend_start", task, session, backend: kind, timestamp: nowIso() };
+      let finalText = "";
+      let totalCostUsd = 0;
+      let totalTokensIn = 0;
+      let totalTokensOut = 0;
+      const inboundDepth = parseInboundDepth(context.propagatedHeaders);
+      for await (const event of runConversationStream(options.conversation, {
+        seed,
+        signal: context.signal,
+        runId: context.runId,
+        propagatedHeaders: context.propagatedHeaders,
+        inboundDepth,
+        parentTurnId: context.turnId
+      })) {
+        if (event.type === "turn_end") {
+          const tagged = `[${event.turn.speaker}] ${event.turn.text}
+`;
+          finalText += tagged;
+          yield { type: "text_delta", task, session, text: tagged, timestamp: event.timestamp };
+          if (event.turn.usage) {
+            const u = event.turn.usage;
+            if (u.costUsd !== void 0) totalCostUsd += u.costUsd;
+            if (u.tokensIn !== void 0) totalTokensIn += u.tokensIn;
+            if (u.tokensOut !== void 0) totalTokensOut += u.tokensOut;
+            yield {
+              type: "llm_call",
+              task,
+              session,
+              model: u.model ?? `${kind}/${event.turn.speaker}`,
+              tokensIn: u.tokensIn,
+              tokensOut: u.tokensOut,
+              costUsd: u.costUsd,
+              latencyMs: u.latencyMs,
+              timestamp: event.timestamp
+            };
+          }
+        } else if (event.type === "conversation_end") {
+          const halt = event.result.halted;
+          yield {
+            type: "final",
+            task,
+            session,
+            status: halt.kind === "participant_error" ? "failed" : "completed",
+            reason: describeHalt(halt),
+            text: finalText.trim(),
+            metadata: {
+              conversationRunId: event.result.runId,
+              turns: event.result.turns,
+              spentCreditsCents: event.result.spentCreditsCents,
+              halted: halt,
+              durationMs: event.result.durationMs,
+              tokensIn: totalTokensIn,
+              tokensOut: totalTokensOut,
+              costUsd: totalCostUsd
+            },
+            timestamp: event.timestamp
+          };
+        }
+      }
+      yield { type: "backend_end", task, session, backend: kind, timestamp: nowIso() };
+    }
+  };
+}
+function parseInboundDepth(headers) {
+  if (!headers) return 0;
+  const raw = headers[FORWARD_HEADERS.depth];
+  if (raw === void 0) return 0;
+  try {
+    return readDepth({ [FORWARD_HEADERS.depth]: raw });
+  } catch {
+    return 0;
+  }
+}
+function describeHalt(halt) {
+  switch (halt.kind) {
+    case "max_turns":
+      return `max_turns (${halt.turns})`;
+    case "max_credits":
+      return `max_credits (${halt.spentCents}/${halt.capCents}\xA2)`;
+    case "predicate":
+      return `predicate: ${halt.reason}`;
+    case "abort":
+      return "abort";
+    case "participant_error":
+      return `participant_error[${halt.participant}]: ${halt.message}`;
+  }
+}
+
+// src/conversation/define-conversation.ts
+function defineConversation(input) {
+  if (input.participants.length < 2) {
+    throw new ValidationError(
+      `Conversation requires at least 2 participants; received ${input.participants.length}.`
+    );
+  }
+  const seen = /* @__PURE__ */ new Set();
+  for (const p of input.participants) {
+    if (!p.name || p.name.trim() === "") {
+      throw new ValidationError("Conversation participant.name must be a non-empty string.");
+    }
+    if (seen.has(p.name)) {
+      throw new ValidationError(
+        `Conversation participant names must be unique within a Conversation; '${p.name}' appears more than once.`
+      );
+    }
+    seen.add(p.name);
+    if (!p.backend || typeof p.backend.stream !== "function") {
+      throw new ValidationError(
+        `Conversation participant '${p.name}' is missing a backend with a stream() method.`
+      );
+    }
+  }
+  const policy = normalizePolicy(input.policy, input.participants.length);
+  return {
+    participants: input.participants,
+    policy
+  };
+}
+function normalizePolicy(policy, participantCount) {
+  if (!Number.isInteger(policy.maxTurns) || policy.maxTurns < 1) {
+    throw new ValidationError(
+      `ConversationPolicy.maxTurns must be a positive integer; received ${String(policy.maxTurns)}.`
+    );
+  }
+  if (policy.maxCreditsCents !== void 0 && (!Number.isFinite(policy.maxCreditsCents) || policy.maxCreditsCents < 0)) {
+    throw new ValidationError(
+      `ConversationPolicy.maxCreditsCents must be a non-negative finite number when set; received ${String(
+        policy.maxCreditsCents
+      )}.`
+    );
+  }
+  const turnOrder = policy.turnOrder ?? (participantCount === 2 ? "alternate" : "round-robin");
+  if (turnOrder === "alternate" && participantCount !== 2) {
+    throw new ValidationError(
+      `ConversationPolicy.turnOrder 'alternate' requires exactly 2 participants; received ${participantCount}. Use 'round-robin' or a custom selector for N-party conversations.`
+    );
+  }
+  return { ...policy, turnOrder };
+}
+
+// src/conversation/journal.ts
+var InMemoryConversationJournal = class {
+  entries = /* @__PURE__ */ new Map();
+  async loadRun(runId) {
+    const entry = this.entries.get(runId);
+    if (!entry) return void 0;
+    return {
+      runId: entry.runId,
+      startedAt: entry.startedAt,
+      halted: entry.halted,
+      endedAt: entry.endedAt,
+      turns: [...entry.turns]
+    };
+  }
+  async beginRun(runId, startedAt) {
+    const existing = this.entries.get(runId);
+    if (existing) {
+      if (existing.startedAt !== startedAt) {
+        throw new Error(
+          `runId '${runId}' already exists with startedAt=${existing.startedAt}; refusing to overwrite with ${startedAt}`
+        );
+      }
+      return;
+    }
+    this.entries.set(runId, { runId, startedAt, turns: [] });
+  }
+  async appendTurn(runId, turn) {
+    const entry = this.entries.get(runId);
+    if (!entry) {
+      throw new Error(
+        `appendTurn called for unknown runId '${runId}'; call beginRun first or use the runner which handles it`
+      );
+    }
+    if (entry.halted) {
+      throw new Error(
+        `cannot append turn to halted run '${runId}' (halt reason: ${JSON.stringify(entry.halted)})`
+      );
+    }
+    entry.turns.push(turn);
+  }
+  async recordHalt(runId, halt, endedAt) {
+    const entry = this.entries.get(runId);
+    if (!entry) {
+      throw new Error(`recordHalt called for unknown runId '${runId}'`);
+    }
+    entry.halted = halt;
+    entry.endedAt = endedAt;
+  }
+};
+var FileConversationJournal = class {
+  constructor(path) {
+    this.path = path;
+  }
+  path;
+  async loadRun(runId) {
+    const fs = await import("fs/promises");
+    let text;
+    try {
+      text = await fs.readFile(this.path, "utf8");
+    } catch (err) {
+      if (isNoEntError(err)) return void 0;
+      throw err;
+    }
+    const lines = text.split("\n").filter((line) => line.length > 0);
+    let entry;
+    for (const line of lines) {
+      const record = JSON.parse(line);
+      if (record.runId !== runId) continue;
+      if (record.kind === "begin") {
+        entry = { runId, startedAt: record.startedAt, turns: [] };
+      } else if (record.kind === "turn") {
+        if (!entry) {
+          throw new Error(
+            `journal corrupted: turn record for runId '${runId}' precedes its begin record`
+          );
+        }
+        entry.turns.push(record.turn);
+      } else if (record.kind === "halt") {
+        if (!entry) {
+          throw new Error(
+            `journal corrupted: halt record for runId '${runId}' precedes its begin record`
+          );
+        }
+        entry.halted = record.halted;
+        entry.endedAt = record.endedAt;
+      }
+    }
+    return entry;
+  }
+  async beginRun(runId, startedAt) {
+    const existing = await this.loadRun(runId);
+    if (existing) {
+      if (existing.startedAt !== startedAt) {
+        throw new Error(
+          `runId '${runId}' already exists in ${this.path} with startedAt=${existing.startedAt}; refusing to overwrite with ${startedAt}`
+        );
+      }
+      return;
+    }
+    await this.appendRecord({ kind: "begin", runId, startedAt });
+  }
+  async appendTurn(runId, turn) {
+    await this.appendRecord({ kind: "turn", runId, turn });
+  }
+  async recordHalt(runId, halt, endedAt) {
+    await this.appendRecord({ kind: "halt", runId, halted: halt, endedAt });
+  }
+  async appendRecord(record) {
+    const fs = await import("fs/promises");
+    const path = await import("path");
+    await fs.mkdir(path.dirname(this.path), { recursive: true });
+    const fh = await fs.open(this.path, "a");
+    try {
+      await fh.write(`${JSON.stringify(record)}
+`);
+      await fh.sync();
+    } finally {
+      await fh.close();
+    }
+  }
+};
+function isNoEntError(err) {
+  return typeof err === "object" && err !== null && "code" in err && err.code === "ENOENT";
+}
+
+// src/conversation/journal-sql.ts
+function d1ToSqlAdapter(db) {
+  return {
+    async exec(sql, params = []) {
+      const stmt = db.prepare(sql);
+      const bound = params.length > 0 ? stmt.bind(...params) : stmt;
+      const result = await bound.run();
+      const meta = result.meta;
+      return { rowsAffected: meta?.rows_written ?? meta?.changes ?? 0 };
+    },
+    async query(sql, params = []) {
+      const stmt = db.prepare(sql);
+      const bound = params.length > 0 ? stmt.bind(...params) : stmt;
+      const result = await bound.all();
+      return result.results ?? [];
+    }
+  };
+}
+var RUNS_TABLE_DDL = (table) => `
+  CREATE TABLE IF NOT EXISTS ${table}_runs (
+    run_id TEXT PRIMARY KEY,
+    started_at TEXT NOT NULL,
+    halted_kind TEXT,
+    halted_payload TEXT,
+    ended_at TEXT
+  )
+`;
+var TURNS_TABLE_DDL = (table) => `
+  CREATE TABLE IF NOT EXISTS ${table}_turns (
+    run_id TEXT NOT NULL,
+    turn_index INTEGER NOT NULL,
+    payload TEXT NOT NULL,
+    PRIMARY KEY (run_id, turn_index)
+  )
+`;
+var TURNS_INDEX_DDL = (table) => `
+  CREATE INDEX IF NOT EXISTS idx_${table}_turns_run ON ${table}_turns (run_id, turn_index)
+`;
+var SqlConversationJournal = class {
+  /**
+   * @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, table = "agent_runtime_journal") {
+    this.db = db;
+    this.table = table;
+  }
+  db;
+  table;
+  /**
+   * 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.
+   */
+  async migrate() {
+    await this.db.exec(RUNS_TABLE_DDL(this.table));
+    await this.db.exec(TURNS_TABLE_DDL(this.table));
+    await this.db.exec(TURNS_INDEX_DDL(this.table));
+  }
+  async loadRun(runId) {
+    const runs = await this.db.query(
+      `SELECT run_id, started_at, halted_kind, halted_payload, ended_at FROM ${this.table}_runs WHERE run_id = ?`,
+      [runId]
+    );
+    const row = runs[0];
+    if (!row) return void 0;
+    const turns = await this.db.query(
+      `SELECT payload, turn_index FROM ${this.table}_turns WHERE run_id = ? ORDER BY turn_index ASC`,
+      [runId]
+    );
+    return {
+      runId: row.run_id,
+      startedAt: row.started_at,
+      halted: row.halted_payload ? JSON.parse(row.halted_payload) : void 0,
+      endedAt: row.ended_at ?? void 0,
+      turns: turns.map((t) => JSON.parse(t.payload))
+    };
+  }
+  async beginRun(runId, startedAt) {
+    const existing = await this.db.query(
+      `SELECT started_at FROM ${this.table}_runs WHERE run_id = ?`,
+      [runId]
+    );
+    if (existing.length > 0) {
+      if (existing[0]?.started_at !== startedAt) {
+        throw new Error(
+          `runId '${runId}' already exists with startedAt=${existing[0]?.started_at}; refusing to overwrite with ${startedAt}`
+        );
+      }
+      return;
+    }
+    await this.db.exec(`INSERT INTO ${this.table}_runs (run_id, started_at) VALUES (?, ?)`, [
+      runId,
+      startedAt
+    ]);
+  }
+  async appendTurn(runId, turn) {
+    const halted = await this.db.query(
+      `SELECT halted_kind FROM ${this.table}_runs WHERE run_id = ?`,
+      [runId]
+    );
+    if (halted.length === 0) {
+      throw new Error(
+        `appendTurn called for unknown runId '${runId}'; call beginRun first or use the runner which handles it`
+      );
+    }
+    if (halted[0]?.halted_kind) {
+      throw new Error(
+        `cannot append turn to halted run '${runId}' (halt kind: ${halted[0]?.halted_kind})`
+      );
+    }
+    await this.db.exec(
+      `INSERT INTO ${this.table}_turns (run_id, turn_index, payload) VALUES (?, ?, ?)`,
+      [runId, turn.index, JSON.stringify(turn)]
+    );
+  }
+  async recordHalt(runId, halt, endedAt) {
+    const rs = await this.db.exec(
+      `UPDATE ${this.table}_runs SET halted_kind = ?, halted_payload = ?, ended_at = ? WHERE run_id = ?`,
+      [halt.kind, JSON.stringify(halt), endedAt, runId]
+    );
+    if (rs.rowsAffected === 0) {
+      throw new Error(`recordHalt called for unknown runId '${runId}'`);
+    }
+  }
+};
+
 // src/durable/chat-engine.ts
 var encoder = new TextEncoder();
 function encodeLine(event) {
@@ -1681,37 +2691,59 @@ function stripNewlines(value) {
 export {
   AgentEvalError,
   BackendTransportError,
+  CircuitBreakerState,
+  CircuitOpenError,
   ConfigError,
+  DEFAULT_MAX_DEPTH,
   DEFAULT_ROUTER_BASE_URL,
+  DeadlineExceededError,
+  FORWARD_HEADERS,
+  FileConversationJournal,
+  InMemoryConversationJournal,
   InMemoryRuntimeSessionStore,
   JudgeError,
   NotFoundError,
   RuntimeRunStateError,
+  SqlConversationJournal,
   ValidationError,
+  buildForwardHeaders,
   cleanModelId,
+  computeBackoff,
+  createConversationBackend,
   createIterableBackend,
   createOpenAICompatibleBackend,
   createOtelExporter,
   createRuntimeEventCollector,
   createRuntimeStreamEventCollector,
   createSandboxPromptBackend,
+  d1ToSqlAdapter,
   decideKnowledgeReadiness,
+  defaultIsRetryable,
+  defineConversation,
   deriveExecutionId,
   getModels,
   handleChatTurn,
+  isDepthExceeded,
   loopEventToOtelSpan,
+  makePerAttemptSignal,
   mcpToolsForRuntimeMcp,
   mcpToolsForRuntimeMcpSubset,
+  readDepth,
   readinessServerSentEvent,
   resolveChatModel,
   resolveRouterBaseUrl,
   runAgentTask,
   runAgentTaskStream,
+  runConversation,
+  runConversationStream,
   runtimeStreamServerSentEvent,
   sanitizeAgentRuntimeEvent,
   sanitizeKnowledgeReadinessReport,
   sanitizeRuntimeStreamEvent,
+  sleep2 as sleep,
+  slugifySpeaker,
   startRuntimeRun,
+  turnId,
   validateChatModelId
 };
 //# sourceMappingURL=index.js.map