@tangle-network/agent-runtime 0.13.1 → 0.14.1

package/dist/index.d.ts

@@ -59,6 +59,14 @@ interface BackendRetryPolicy {
     jitter?: number;
     /** Status codes that trigger a retry. Default: 408, 425, 429, 500, 502, 503, 504. */
     retryStatuses?: ReadonlyArray<number>;
+    /**
+     * Per-attempt wall-clock deadline in ms. If a single fetch attempt does
+     * not return headers within this window the attempt is aborted and
+     * retried. Default 120000 (2 min). Without this a hung upstream blocks
+     * the attempt indefinitely — observed in production as a 15-minute
+     * `fetch failed` that burned an entire eval persona. Set to 0 to disable.
+     */
+    requestTimeoutMs?: number;
 }
 declare function createOpenAICompatibleBackend<TInput extends AgentBackendInput = AgentBackendInput>(options: {
     apiKey: string;
@@ -384,6 +392,225 @@ declare class DurableAwaitEventTimeoutError extends DurableRunError {
     constructor(message: string);
 }
 
+/**
+ * `runDurableTurn` — a streaming, backend-agnostic, checkpoint+replay durable
+ * turn. The single reusable primitive every product's chat handler routes
+ * through, so per-product durability code drops to zero.
+ *
+ * A **turn** is one request→response unit: a producer yields a stream of
+ * events and, once drained, exposes the turn's final text. `runDurableTurn`
+ * wraps that with a `DurableRunStore`:
+ *
+ *   - **Fresh run** — no completed step for this `(runId)`. The producer
+ *     runs; its events forward live to the caller (streaming preserved)
+ *     while final text accumulates; on drain the text is checkpointed.
+ *
+ *   - **Replay** — a completed step already exists (the worker died after
+ *     the turn finished but before the response reached the client, and the
+ *     client retried the same turn). The cached text is emitted as a single
+ *     synthetic event; the producer is never constructed — no LLM call, no
+ *     double-billing.
+ *
+ *   - **Mid-stream crash** — a turn that died *while streaming* leaves step 0
+ *     in `running`/`failed`. There is no partial-stream checkpoint (the
+ *     substrate checkpoints JSON values at step granularity), so the turn
+ *     re-runs from the top. This is the honest durability ceiling: a
+ *     *completed* turn is free to replay; an *interrupted* turn re-runs.
+ *
+ * Generic over the event type `TEvent` so a product can stream its own NDJSON
+ * shape or the runtime's `RuntimeStreamEvent` — `runDurableTurn` never
+ * inspects events, it only forwards them and reads `finalText()` after drain.
+ *
+ * Lease: a turn is a single step, fast enough that the heartbeat in
+ * `runDurable` is unnecessary — `runDurableTurn` claims the lease once via
+ * `startOrResume` and releases it on `endRun`. Concurrent workers on the same
+ * `runId` are rejected with `DurableRunLeaseHeldError` (the client retried
+ * before the first attempt finished); callers surface that as "turn already
+ * in flight."
+ */
+
+/** The live side of a turn — what a fresh run produces. */
+interface DurableTurnProducer<TEvent> {
+    /** The turn's event stream. Forwarded verbatim to the caller. */
+    stream: AsyncGenerator<TEvent, void, unknown>;
+    /** The turn's final assistant text. Read once, after `stream` drains. */
+    finalText(): string;
+}
+interface RunDurableTurnOptions<TEvent> {
+    store: DurableRunStore;
+    /** Stable per-turn run id. Convention: `chat:<threadId>:<turnIndex>`. The
+     *  same id on a retry is what enables replay. */
+    runId: string;
+    manifest: DurableRunManifest;
+    /** Stable per-isolate worker id. Defaults to a fresh `deriveWorkerId()`
+     *  per call when omitted — fine for single-attempt turns. */
+    workerId: string;
+    /** Lease window in ms. Default 60_000 — a turn rarely runs longer. */
+    leaseMs?: number;
+    /** Human-readable step label. Default `turn`. */
+    intent?: string;
+    /** Builds the live producer. Called exactly once, on a fresh run; never
+     *  called on the replay path. */
+    produce: () => DurableTurnProducer<TEvent>;
+    /** Synthesizes the single event emitted on the replay path from the
+     *  cached final text (e.g. a product's `{ type: 'result', data: {...} }`). */
+    replayEvent: (finalText: string) => TEvent;
+    /** Optional live accumulator. When the producer's `finalText()` is only
+     *  valid after drain, this lets `runDurableTurn` also observe each event
+     *  to build the text — return the running text or `undefined` to ignore
+     *  an event. When omitted, `producer.finalText()` is the sole source. */
+    accumulate?: (event: TEvent, current: string) => string | undefined;
+}
+interface DurableTurnHandle<TEvent> {
+    /** Drop-in stream. Fresh runs forward producer events live; replays emit
+     *  exactly one `replayEvent(cachedText)`. */
+    stream: AsyncGenerator<TEvent, void, unknown>;
+    /** The turn's final text. Valid after `stream` drains. */
+    finalText(): string;
+    /** True iff this turn replayed a cached result (no producer ran). Valid
+     *  after `stream` drains. */
+    replayed(): boolean;
+    /** The durable `RunRecord` for this turn. Valid after `stream` drains. */
+    record(): RunRecord | undefined;
+}
+declare function runDurableTurn<TEvent>(options: RunDurableTurnOptions<TEvent>): DurableTurnHandle<TEvent>;
+
+/**
+ * `DurableChatTurnEngine` — the framework-neutral chat-turn orchestrator every
+ * product chat handler routes through. It owns the parts that were copy-pasted
+ * across legal / gtm / creative / tax: durable checkpointing, the NDJSON
+ * `StreamEvent` line protocol, the `session.run.*` lifecycle vocabulary, the
+ * runtime-run cost ledger, and trace flush. Everything genuinely
+ * product-specific is a hook the product supplies.
+ *
+ * What the engine owns:
+ *   - durable turn (`runDurableTurn`): completed turns replay free, no re-bill
+ *   - the `session.run.started` / `session.run.completed` / `session.run.failed`
+ *     event envelope around the producer's events
+ *   - NDJSON encoding into a `ReadableStream<Uint8Array>` (the body every
+ *     product returns, React Router or Hono alike)
+ *   - calling the product's persist / post-process hooks in the right order,
+ *     after the stream drains, with the assembled final text
+ *   - never throwing into the HTTP layer — a producer failure becomes an
+ *     `error` + `session.run.failed` event pair, the stream still closes
+ *
+ * What the product supplies (`ChatTurnHooks`):
+ *   - `produce`     — build the backend stream for this turn (sandbox / router
+ *                     / tcloud / runtime — the engine does not care which)
+ *   - `persistAssistantMessage` — write the assistant turn to the product DB
+ *   - `onTurnComplete` (optional) — post-process (proposals, citations, …)
+ *   - `onEvent` (optional)        — per-event side-channel (e.g. DO broadcast)
+ *   - `transformFinalText` (optional) — pre-persist transform (e.g. PII redact)
+ *
+ * Framework neutrality: the engine takes already-resolved values
+ * (`userId`, identity tuple, parsed message, a `DurableRunStore`, a
+ * `waitUntil`), never a `Request` or a `Context`. The product's thin route
+ * adapter does auth + parse + access-control, then calls `engine.runTurn(...)`
+ * and returns `result.body` as its platform `Response`.
+ */
+
+/** The NDJSON line protocol every product chat client already speaks. */
+interface ChatStreamEvent {
+    type: string;
+    data?: Record<string, unknown>;
+}
+/** Identity of a chat turn. `tenantId` is the workspace id for workspace-
+ *  scoped products and the user id for session-scoped products. */
+interface ChatTurnIdentity {
+    tenantId: string;
+    /** Thread / session id — the durable run is keyed on this + `turnIndex`. */
+    sessionId: string;
+    userId: string;
+    /** Monotonic 0-based turn index within the session. */
+    turnIndex: number;
+}
+interface ChatTurnHooks {
+    /**
+     * Build the backend stream for this turn. The engine never inspects which
+     * backend this is — sandbox container, tcloud router, direct runtime, a
+     * test double — it only forwards the events and reads `finalText()`.
+     */
+    produce(): DurableTurnProducer<ChatStreamEvent>;
+    /**
+     * Persist the completed assistant message to the product's own store.
+     * Called once, after the stream drains, on a fresh (non-replay) run.
+     * Receives the assembled (and `transformFinalText`-transformed) text.
+     */
+    persistAssistantMessage(input: {
+        identity: ChatTurnIdentity;
+        finalText: string;
+        record: RunRecord | undefined;
+    }): Promise<void>;
+    /**
+     * Optional post-processing after persistence — proposal extraction,
+     * citation validation, credit metering, etc. Product policy; the engine
+     * has no shared logic here. Errors are swallowed + logged (post-process
+     * must never fail the turn that already streamed successfully).
+     */
+    onTurnComplete?(input: {
+        identity: ChatTurnIdentity;
+        finalText: string;
+    }): Promise<void>;
+    /**
+     * Optional per-event side channel (e.g. Durable Object broadcast). Runs
+     * for every event the engine emits, lifecycle envelope included. Errors
+     * are swallowed — a broadcast failure must not break the chat stream.
+     */
+    onEvent?(event: ChatStreamEvent): void | Promise<void>;
+    /**
+     * Optional pre-persist transform of the final text (e.g. PII redaction).
+     * Affects only what is persisted; the live stream is never altered.
+     */
+    transformFinalText?(text: string): string | Promise<string>;
+    /**
+     * Optional trace flush — resolves when OTLP export completes. The engine
+     * hands it to `waitUntil` so the worker isolate stays alive for the POST.
+     */
+    traceFlush?(): Promise<void>;
+}
+interface RunChatTurnInput {
+    identity: ChatTurnIdentity;
+    /** The user's message for this turn. Hashed into the durable run identity. */
+    userMessage: string;
+    /** Product id for telemetry / the durable manifest (`legal-agent`, …). */
+    projectId: string;
+    /** Domain tag for the task spec (`legal`, `gtm`, …). */
+    domain: string;
+    /** Model id, when known — recorded on the manifest. */
+    model?: string;
+    store: DurableRunStore;
+    hooks: ChatTurnHooks;
+    /** Worker liveness hook (`ctx.waitUntil` / `executionCtx.waitUntil`). When
+     *  omitted, trace flush is awaited inline before the stream closes. */
+    waitUntil?: (p: Promise<unknown>) => void;
+    /** Stable per-isolate worker id. Defaults to a fresh `deriveWorkerId()`. */
+    workerId?: string;
+    /** Lease window in ms. Default 60_000. */
+    leaseMs?: number;
+    /** Optional structured logger for swallowed hook errors. */
+    log?: (message: string, meta?: Record<string, unknown>) => void;
+}
+interface ChatTurnResult {
+    /** NDJSON body — return this as the platform `Response` body. */
+    body: ReadableStream<Uint8Array>;
+    /** Content type for the response. */
+    contentType: 'application/x-ndjson';
+}
+/**
+ * The engine. One instance is stateless and reusable across requests — all
+ * per-turn state lives in `runTurn`'s closure.
+ */
+declare class DurableChatTurnEngine {
+    /**
+     * Run one durable chat turn. Returns immediately with a `ReadableStream`
+     * body; the turn executes as the body is pulled. Never rejects — backend
+     * failures surface as `error` + `session.run.failed` events.
+     */
+    runTurn(input: RunChatTurnInput): ChatTurnResult;
+}
+/** Convenience singleton — the engine is stateless, one instance is enough. */
+declare const durableChatTurnEngine: DurableChatTurnEngine;
+
 /**
  * D1DurableRunStore — the production path for Cloudflare Workers. Backed by
  * a D1 (SQLite-compatible) database via the binding the worker already holds.
@@ -1424,4 +1651,4 @@ declare function createTraceBridge(options: TraceBridgeOptions): TraceBridge;
  */
 declare function toAgentEvalTrace(event: RuntimeStreamEvent, options: TraceBridgeOptions): TraceEvent | undefined;
 
-export { AgentBackendContext, AgentBackendInput, AgentExecutionBackend, AgentRuntimeEvent, AgentTaskRunResult, AgentTaskRunSummary, AgentTaskSpec, AgentTaskStatus, type BackendRetryPolicy, BackendTransportError, ChatTurnError, type ChatTurnMessage, type ChatTurnOverlay, type ChatTurnSandbox, type ClassifyIntentOptions, type ClassifyIntentResult, type ConformanceIssue, type ConformanceOptions, type ConformanceResult, type D1DatabaseLike, D1DurableRunStore, type D1PreparedStatementLike, DURABLE_SCHEMA_SQL, DURABLE_SCHEMA_VERSION, DurableAwaitEventTimeoutError, type DurableContext, DurableRunDivergenceError, DurableRunError, DurableRunInputMismatchError, DurableRunLeaseHeldError, type DurableRunManifest, type DurableRunStore, type EventRecord, FileSystemDurableRunStore, InMemoryDurableRunStore, InMemoryRuntimeSessionStore, KnowledgeReadinessDecision, RunAgentTaskOptions, RunAgentTaskStreamOptions, type RunChatTurnOptions, type RunDurableInput, type RunDurableResult, type RunOnWorkflowStepInput, type RunOutcome, type RunStatus, type RuntimeEventCollector, type RuntimeRunCompleteInput, type RuntimeRunCost, type RuntimeRunHandle, type RuntimeRunOptions, type RuntimeRunPersistenceAdapter, type RuntimeRunRow, RuntimeRunStateError, type RuntimeRunStatus, RuntimeSession, RuntimeSessionStore, RuntimeStreamEvent, type RuntimeStreamEventCollector, type RuntimeStreamEventSink, type RuntimeStreamEventSummary, type RuntimeTelemetryOptions, type SanitizedKnowledgeReadinessReport, type SanitizedKnowledgeRequirement, type ServerSentEventOptions, SessionMismatchError, type StepError, type StepKind, type StepRecord, type StepStatus, type SubagentMatcher, type TraceBridge, type TraceBridgeOptions, type WorkflowStepConfig, type WorkflowStepLike, assertProfileConformance, canonicalHash, canonicalJson, classifyIntent, composeTurnProfile, createIterableBackend, createOpenAICompatibleBackend, createRuntimeEventCollector, createRuntimeStreamEventCollector, createSandboxPromptBackend, createTraceBridge, decideKnowledgeReadiness, deriveWorkerId, encodeServerSentEvent, manifestHash, readinessServerSentEvent, runAgentTask, runAgentTaskStream, runChatTurn, runDurable, runOnWorkflowStep, runtimeStreamServerSentEvent, sandboxAsChatTurnTarget, sanitizeAgentRuntimeEvent, sanitizeKnowledgeReadinessReport, sanitizeRuntimeStreamEvent, startRuntimeRun, stepId, summarizeAgentTaskRun, toAgentEvalTrace };
+export { AgentBackendContext, AgentBackendInput, AgentExecutionBackend, AgentRuntimeEvent, AgentTaskRunResult, AgentTaskRunSummary, AgentTaskSpec, AgentTaskStatus, type BackendRetryPolicy, BackendTransportError, type ChatStreamEvent, ChatTurnError, type ChatTurnHooks, type ChatTurnIdentity, type ChatTurnMessage, type ChatTurnOverlay, type ChatTurnResult, type ChatTurnSandbox, type ClassifyIntentOptions, type ClassifyIntentResult, type ConformanceIssue, type ConformanceOptions, type ConformanceResult, type D1DatabaseLike, D1DurableRunStore, type D1PreparedStatementLike, DURABLE_SCHEMA_SQL, DURABLE_SCHEMA_VERSION, DurableAwaitEventTimeoutError, DurableChatTurnEngine, type DurableContext, DurableRunDivergenceError, DurableRunError, DurableRunInputMismatchError, DurableRunLeaseHeldError, type DurableRunManifest, type DurableRunStore, type DurableTurnHandle, type DurableTurnProducer, type EventRecord, FileSystemDurableRunStore, InMemoryDurableRunStore, InMemoryRuntimeSessionStore, KnowledgeReadinessDecision, RunAgentTaskOptions, RunAgentTaskStreamOptions, type RunChatTurnInput, type RunChatTurnOptions, type RunDurableInput, type RunDurableResult, type RunDurableTurnOptions, type RunOnWorkflowStepInput, type RunOutcome, type RunStatus, type RuntimeEventCollector, type RuntimeRunCompleteInput, type RuntimeRunCost, type RuntimeRunHandle, type RuntimeRunOptions, type RuntimeRunPersistenceAdapter, type RuntimeRunRow, RuntimeRunStateError, type RuntimeRunStatus, RuntimeSession, RuntimeSessionStore, RuntimeStreamEvent, type RuntimeStreamEventCollector, type RuntimeStreamEventSink, type RuntimeStreamEventSummary, type RuntimeTelemetryOptions, type SanitizedKnowledgeReadinessReport, type SanitizedKnowledgeRequirement, type ServerSentEventOptions, SessionMismatchError, type StepError, type StepKind, type StepRecord, type StepStatus, type SubagentMatcher, type TraceBridge, type TraceBridgeOptions, type WorkflowStepConfig, type WorkflowStepLike, assertProfileConformance, canonicalHash, canonicalJson, classifyIntent, composeTurnProfile, createIterableBackend, createOpenAICompatibleBackend, createRuntimeEventCollector, createRuntimeStreamEventCollector, createSandboxPromptBackend, createTraceBridge, decideKnowledgeReadiness, deriveWorkerId, durableChatTurnEngine, encodeServerSentEvent, manifestHash, readinessServerSentEvent, runAgentTask, runAgentTaskStream, runChatTurn, runDurable, runDurableTurn, runOnWorkflowStep, runtimeStreamServerSentEvent, sandboxAsChatTurnTarget, sanitizeAgentRuntimeEvent, sanitizeKnowledgeReadinessReport, sanitizeRuntimeStreamEvent, startRuntimeRun, stepId, summarizeAgentTaskRun, toAgentEvalTrace };

package/dist/index.js

@@ -113,6 +113,32 @@ function pickRetryDelayMs(attempt, policy) {
   const jitter = capped * policy.jitter * (Math.random() * 2 - 1);
   return Math.max(0, Math.round(capped + jitter));
 }
+function withTimeout(callerSignal, timeoutMs) {
+  if (timeoutMs <= 0) {
+    return { signal: callerSignal ?? new AbortController().signal, dispose: () => void 0 };
+  }
+  const controller = new AbortController();
+  const timer = setTimeout(
+    () => controller.abort(new Error(`request timed out after ${timeoutMs}ms`)),
+    timeoutMs
+  );
+  if (typeof timer.unref === "function") {
+    ;
+    timer.unref();
+  }
+  const onCallerAbort = () => controller.abort(callerSignal?.reason ?? new Error("aborted"));
+  if (callerSignal) {
+    if (callerSignal.aborted) onCallerAbort();
+    else callerSignal.addEventListener("abort", onCallerAbort, { once: true });
+  }
+  return {
+    signal: controller.signal,
+    dispose: () => {
+      clearTimeout(timer);
+      callerSignal?.removeEventListener("abort", onCallerAbort);
+    }
+  };
+}
 function sleep(ms, signal) {
   return new Promise((resolve, reject) => {
     if (signal?.aborted) {
@@ -138,7 +164,8 @@ function createOpenAICompatibleBackend(options) {
     initialBackoffMs: options.retry?.initialBackoffMs ?? 1e3,
     maxBackoffMs: options.retry?.maxBackoffMs ?? 3e4,
     jitter: options.retry?.jitter ?? 0.25,
-    retryStatuses: options.retry?.retryStatuses ?? DEFAULT_RETRY_STATUSES
+    retryStatuses: options.retry?.retryStatuses ?? DEFAULT_RETRY_STATUSES,
+    requestTimeoutMs: options.retry?.requestTimeoutMs ?? 12e4
   };
   return {
     kind,
@@ -146,24 +173,40 @@ function createOpenAICompatibleBackend(options) {
       return newRuntimeSession(kind, context.requestedSessionId);
     },
     async *stream(input, context) {
+      const url = `${options.baseUrl.replace(/\/$/, "")}/chat/completions`;
+      const requestBody = JSON.stringify({
+        model: options.model,
+        stream: true,
+        messages: input.messages ?? [
+          { role: "user", content: input.message ?? context.task.intent }
+        ]
+      });
       let response;
       let lastStatus = 0;
+      let lastThrown;
       for (let attempt = 1; attempt <= retryPolicy.maxAttempts; attempt++) {
-        response = await fetcher(`${options.baseUrl.replace(/\/$/, "")}/chat/completions`, {
-          method: "POST",
-          headers: {
-            Authorization: `Bearer ${options.apiKey}`,
-            "Content-Type": "application/json"
-          },
-          body: JSON.stringify({
-            model: options.model,
-            stream: true,
-            messages: input.messages ?? [
-              { role: "user", content: input.message ?? context.task.intent }
-            ]
-          }),
-          signal: context.signal
-        });
+        lastThrown = void 0;
+        const attemptSignal = withTimeout(context.signal, retryPolicy.requestTimeoutMs);
+        try {
+          response = await fetcher(url, {
+            method: "POST",
+            headers: {
+              Authorization: `Bearer ${options.apiKey}`,
+              "Content-Type": "application/json"
+            },
+            body: requestBody,
+            signal: attemptSignal.signal
+          });
+        } catch (err) {
+          attemptSignal.dispose();
+          if (context.signal?.aborted) throw err;
+          lastThrown = err;
+          response = void 0;
+          if (attempt === retryPolicy.maxAttempts) break;
+          await sleep(pickRetryDelayMs(attempt, retryPolicy), context.signal);
+          continue;
+        }
+        attemptSignal.dispose();
         if (response.ok) break;
         lastStatus = response.status;
         if (!retryPolicy.retryStatuses.includes(response.status)) break;
@@ -175,7 +218,15 @@ function createOpenAICompatibleBackend(options) {
         const delayMs = pickRetryDelayMs(attempt, retryPolicy);
         await sleep(delayMs, context.signal);
       }
-      if (!response || !response.ok) {
+      if (!response) {
+        const reason = lastThrown instanceof Error ? lastThrown.message : String(lastThrown);
+        throw new BackendTransportError(
+          kind,
+          `chat backend unreachable after ${retryPolicy.maxAttempts} attempts: ${reason}`,
+          { status: 0 }
+        );
+      }
+      if (!response.ok) {
         throw new BackendTransportError(kind, `chat backend returned ${lastStatus || "unknown"}`, {
           status: lastStatus || 0
         });
@@ -497,6 +548,228 @@ function deriveWorkerId() {
   return `${host}:${pid}:${rand}:${counter}`;
 }
 
+// src/durable/turn.ts
+var STEP_INDEX = 0;
+function runDurableTurn(options) {
+  const { store, runId, manifest, workerId } = options;
+  const leaseMs = options.leaseMs ?? 6e4;
+  const intent = options.intent ?? "turn";
+  const inputHash = canonicalHash(manifest.input);
+  let accumulated = "";
+  let didReplay = false;
+  let finalRecord;
+  async function* stream() {
+    const { completedSteps } = await store.startOrResume({
+      runId,
+      manifest,
+      workerId,
+      leaseMs
+    });
+    const prior = completedSteps.find((s) => s.stepIndex === STEP_INDEX);
+    if (prior && prior.status === "completed") {
+      didReplay = true;
+      const cached = prior.result;
+      accumulated = cached?.finalText ?? "";
+      yield options.replayEvent(accumulated);
+      finalRecord = await store.endRun({ runId, workerId, status: "completed" });
+      return;
+    }
+    await store.beginStep({
+      runId,
+      stepIndex: STEP_INDEX,
+      intent,
+      kind: "llm",
+      inputHash
+    });
+    try {
+      const producer = options.produce();
+      for await (const event of producer.stream) {
+        if (options.accumulate) {
+          const next = options.accumulate(event, accumulated);
+          if (typeof next === "string") accumulated = next;
+        }
+        yield event;
+      }
+      const producerText = producer.finalText();
+      if (producerText) accumulated = producerText;
+      await store.completeStep({
+        runId,
+        stepIndex: STEP_INDEX,
+        result: { finalText: accumulated }
+      });
+      finalRecord = await store.endRun({
+        runId,
+        workerId,
+        status: "completed",
+        outcome: { notes: intent, metadata: { chars: accumulated.length } }
+      });
+    } catch (err) {
+      await store.failStep({
+        runId,
+        stepIndex: STEP_INDEX,
+        error: { message: err instanceof Error ? err.message : String(err) }
+      });
+      finalRecord = await store.endRun({ runId, workerId, status: "failed" });
+      throw err;
+    }
+  }
+  return {
+    stream: stream(),
+    finalText: () => accumulated,
+    replayed: () => didReplay,
+    record: () => finalRecord
+  };
+}
+
+// src/durable/chat-engine.ts
+var encoder = new TextEncoder();
+function encodeLine(event) {
+  return encoder.encode(`${JSON.stringify(event)}
+`);
+}
+var DurableChatTurnEngine = class {
+  /**
+   * Run one durable chat turn. Returns immediately with a `ReadableStream`
+   * body; the turn executes as the body is pulled. Never rejects — backend
+   * failures surface as `error` + `session.run.failed` events.
+   */
+  runTurn(input) {
+    const workerId = input.workerId ?? deriveWorkerId();
+    const log = input.log ?? (() => void 0);
+    const { identity } = input;
+    const runId = `chat:${identity.sessionId}:${identity.turnIndex}`;
+    const manifest = {
+      projectId: input.projectId,
+      scenarioId: identity.sessionId,
+      task: {
+        id: `${input.projectId}:chat:${identity.sessionId}:${identity.turnIndex}`,
+        intent: `Run a ${input.domain} chat turn with workspace context.`,
+        domain: input.domain,
+        requiredKnowledge: [],
+        metadata: {
+          tenantId: identity.tenantId,
+          sessionId: identity.sessionId,
+          turnIndex: identity.turnIndex
+        }
+      },
+      input: {
+        userMessage: input.userMessage,
+        model: input.model ?? null
+      },
+      tags: {
+        session_id: identity.sessionId,
+        tenant_id: identity.tenantId
+      }
+    };
+    const body = new ReadableStream({
+      start: async (controller) => {
+        const emit2 = async (event) => {
+          controller.enqueue(encodeLine(event));
+          if (input.hooks.onEvent) {
+            try {
+              await input.hooks.onEvent(event);
+            } catch (err) {
+              log("[chat-engine] onEvent hook threw", {
+                error: err instanceof Error ? err.message : String(err)
+              });
+            }
+          }
+        };
+        let turnFailed = false;
+        try {
+          await emit2({
+            type: "session.run.started",
+            data: {
+              sessionId: identity.sessionId,
+              tenantId: identity.tenantId,
+              turnIndex: identity.turnIndex
+            }
+          });
+          const turn = runDurableTurn({
+            store: input.store,
+            runId,
+            manifest,
+            workerId,
+            leaseMs: input.leaseMs,
+            intent: `chat:turn-${identity.turnIndex}`,
+            produce: input.hooks.produce,
+            replayEvent: (finalText2) => ({ type: "result", data: { finalText: finalText2 } }),
+            accumulate: (event, current) => {
+              if (event.type === "message.part.updated") {
+                const data = event.data ?? {};
+                const delta = typeof data.delta === "string" ? data.delta : "";
+                const part = data.part;
+                if (delta) return current + delta;
+                if (part?.type === "text" && typeof part.text === "string") return part.text;
+                return void 0;
+              }
+              if (event.type === "result") {
+                const data = event.data ?? {};
+                if (typeof data.finalText === "string") return data.finalText;
+              }
+              return void 0;
+            }
+          });
+          for await (const event of turn.stream) {
+            await emit2(event);
+          }
+          const rawFinal = turn.finalText();
+          const finalText = input.hooks.transformFinalText ? await input.hooks.transformFinalText(rawFinal) : rawFinal;
+          if (!turn.replayed()) {
+            try {
+              await input.hooks.persistAssistantMessage({
+                identity,
+                finalText,
+                record: turn.record()
+              });
+            } catch (err) {
+              log("[chat-engine] persistAssistantMessage threw", {
+                error: err instanceof Error ? err.message : String(err)
+              });
+            }
+            if (input.hooks.onTurnComplete) {
+              try {
+                await input.hooks.onTurnComplete({ identity, finalText });
+              } catch (err) {
+                log("[chat-engine] onTurnComplete threw", {
+                  error: err instanceof Error ? err.message : String(err)
+                });
+              }
+            }
+          }
+          await emit2({
+            type: "session.run.completed",
+            data: { sessionId: identity.sessionId, replayed: turn.replayed() }
+          });
+        } catch (err) {
+          turnFailed = true;
+          const message = err instanceof Error ? err.message : String(err);
+          log("[chat-engine] turn failed", { error: message });
+          await emit2({ type: "error", data: { message } });
+          await emit2({
+            type: "session.run.failed",
+            data: { sessionId: identity.sessionId, message }
+          });
+        } finally {
+          if (input.hooks.traceFlush) {
+            const flush = input.hooks.traceFlush().catch(
+              (err) => log("[chat-engine] traceFlush threw", {
+                error: err instanceof Error ? err.message : String(err)
+              })
+            );
+            if (input.waitUntil) input.waitUntil(flush);
+            else await flush;
+          }
+          controller.close();
+          void turnFailed;
+        }
+      }
+    });
+    return { body, contentType: "application/x-ndjson" };
+  }
+};
+var durableChatTurnEngine = new DurableChatTurnEngine();
+
 // src/durable/types.ts
 var DurableRunError = class extends Error {
   constructor(message, code) {
@@ -2865,6 +3138,7 @@ export {
   DURABLE_SCHEMA_SQL,
   DURABLE_SCHEMA_VERSION,
   DurableAwaitEventTimeoutError,
+  DurableChatTurnEngine,
   DurableRunDivergenceError,
   DurableRunError,
   DurableRunInputMismatchError,
@@ -2892,6 +3166,7 @@ export {
   createTraceBridge,
   decideKnowledgeReadiness,
   deriveWorkerId,
+  durableChatTurnEngine,
   encodeServerSentEvent,
   manifestHash,
   readinessServerSentEvent,
@@ -2899,6 +3174,7 @@ export {
   runAgentTaskStream,
   runChatTurn,
   runDurable,
+  runDurableTurn,
   runOnWorkflowStep,
   runtimeStreamServerSentEvent,
   sandboxAsChatTurnTarget,