@tangle-network/agent-runtime 0.13.0 → 0.14.0

package/dist/index.d.ts

@@ -384,6 +384,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.
@@ -740,6 +959,25 @@ interface RunDurableResult<TResult> {
 }
 declare function runDurable<TResult>(input: RunDurableInput<TResult>): Promise<RunDurableResult<TResult>>;
 
+/**
+ * The durable-runs SQL schema as a string constant. Inlined so consumers
+ * (Cloudflare Workers via D1) can apply it without bundling a `.sql` file:
+ *
+ *   import { DURABLE_SCHEMA_SQL } from '@tangle-network/agent-runtime'
+ *   await env.DB.exec(DURABLE_SCHEMA_SQL)
+ *
+ * The canonical source is `src/durable/schema.sql` — this string MUST stay
+ * byte-identical to it. The build does not copy `.sql` files into `dist/`,
+ * so the constant is the only path consumers have. A unit test asserts the
+ * two stay in sync (`durable-schema.test.ts`).
+ *
+ * `DURABLE_SCHEMA_VERSION` reflects the latest migration version applied by
+ * this string. Bump it on every backwards-incompatible change AND add a new
+ * migration entry to durable_schema_info instead of mutating prior rows.
+ */
+declare const DURABLE_SCHEMA_VERSION = 1;
+declare const DURABLE_SCHEMA_SQL = "-- Durable-run substrate \u2014 versioned schema for D1 / SQLite.\n--\n-- Apply once per database. Subsequent migrations append; never rewrite a\n-- prior version. See `durable_schema_info` for the migration trail.\n--\n-- Concurrency notes for D1:\n--   - SQLite supports UNIQUE constraints for first-emit-wins (`durable_events`\n--     PK is (run_id, key) \u2014 duplicate insert raises, caller treats as \"already\n--     emitted\").\n--   - Lease takeover happens via a conditional UPDATE: we only claim the lease\n--     if (lease_holder_id IS NULL OR lease_expires_at < :now) \u2014 atomic under\n--     SQLite's row-level locking.\n--   - All timestamps stored as ISO-8601 TEXT for cross-platform consistency.\n--   - `result_json` / `error_json` / `outcome_json` / `payload_json` are\n--     JSON-encoded TEXT; the application enforces canonical-JSON discipline at\n--     the boundary so the store stays type-agnostic.\n\nCREATE TABLE IF NOT EXISTS durable_schema_info (\n  version    INTEGER PRIMARY KEY,\n  applied_at TEXT    NOT NULL\n);\n\nCREATE TABLE IF NOT EXISTS durable_runs (\n  run_id           TEXT    PRIMARY KEY,\n  manifest_hash    TEXT    NOT NULL,\n  project_id       TEXT    NOT NULL,\n  scenario_id      TEXT,\n  status           TEXT    NOT NULL CHECK (status IN ('pending','running','completed','failed','suspended')),\n  created_at       TEXT    NOT NULL,\n  updated_at       TEXT    NOT NULL,\n  completed_at     TEXT,\n  lease_holder_id  TEXT,\n  lease_expires_at TEXT,\n  outcome_json     TEXT,\n  step_count       INTEGER NOT NULL DEFAULT 0\n);\n\nCREATE INDEX IF NOT EXISTS idx_durable_runs_project_status ON durable_runs(project_id, status);\nCREATE INDEX IF NOT EXISTS idx_durable_runs_lease_expires ON durable_runs(lease_expires_at);\n\nCREATE TABLE IF NOT EXISTS durable_steps (\n  run_id       TEXT    NOT NULL,\n  step_index   INTEGER NOT NULL,\n  intent       TEXT    NOT NULL,\n  kind         TEXT    NOT NULL,\n  input_hash   TEXT    NOT NULL DEFAULT '',\n  status       TEXT    NOT NULL CHECK (status IN ('pending','running','completed','failed')),\n  attempts     INTEGER NOT NULL DEFAULT 0,\n  result_json  TEXT,\n  error_json   TEXT,\n  started_at   TEXT,\n  completed_at TEXT,\n  PRIMARY KEY (run_id, step_index)\n);\n\nCREATE INDEX IF NOT EXISTS idx_durable_steps_status ON durable_steps(run_id, status);\n\nCREATE TABLE IF NOT EXISTS durable_events (\n  run_id     TEXT NOT NULL,\n  key        TEXT NOT NULL,\n  payload_json TEXT,\n  emitted_at TEXT NOT NULL,\n  PRIMARY KEY (run_id, key)\n);\n\nINSERT OR IGNORE INTO durable_schema_info (version, applied_at)\nVALUES (1, strftime('%Y-%m-%dT%H:%M:%fZ', 'now'));\n";
+
 /**
  * Cloudflare Workflows integration for the durable-run substrate.
  *
@@ -1405,4 +1643,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, 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

@@ -497,6 +497,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) {
@@ -1489,6 +1711,77 @@ function cryptoRandomUuid() {
   return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
 }
 
+// src/durable/schema.ts
+var DURABLE_SCHEMA_VERSION = 1;
+var DURABLE_SCHEMA_SQL = `-- Durable-run substrate \u2014 versioned schema for D1 / SQLite.
+--
+-- Apply once per database. Subsequent migrations append; never rewrite a
+-- prior version. See \`durable_schema_info\` for the migration trail.
+--
+-- Concurrency notes for D1:
+--   - SQLite supports UNIQUE constraints for first-emit-wins (\`durable_events\`
+--     PK is (run_id, key) \u2014 duplicate insert raises, caller treats as "already
+--     emitted").
+--   - Lease takeover happens via a conditional UPDATE: we only claim the lease
+--     if (lease_holder_id IS NULL OR lease_expires_at < :now) \u2014 atomic under
+--     SQLite's row-level locking.
+--   - All timestamps stored as ISO-8601 TEXT for cross-platform consistency.
+--   - \`result_json\` / \`error_json\` / \`outcome_json\` / \`payload_json\` are
+--     JSON-encoded TEXT; the application enforces canonical-JSON discipline at
+--     the boundary so the store stays type-agnostic.
+
+CREATE TABLE IF NOT EXISTS durable_schema_info (
+  version    INTEGER PRIMARY KEY,
+  applied_at TEXT    NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS durable_runs (
+  run_id           TEXT    PRIMARY KEY,
+  manifest_hash    TEXT    NOT NULL,
+  project_id       TEXT    NOT NULL,
+  scenario_id      TEXT,
+  status           TEXT    NOT NULL CHECK (status IN ('pending','running','completed','failed','suspended')),
+  created_at       TEXT    NOT NULL,
+  updated_at       TEXT    NOT NULL,
+  completed_at     TEXT,
+  lease_holder_id  TEXT,
+  lease_expires_at TEXT,
+  outcome_json     TEXT,
+  step_count       INTEGER NOT NULL DEFAULT 0
+);
+
+CREATE INDEX IF NOT EXISTS idx_durable_runs_project_status ON durable_runs(project_id, status);
+CREATE INDEX IF NOT EXISTS idx_durable_runs_lease_expires ON durable_runs(lease_expires_at);
+
+CREATE TABLE IF NOT EXISTS durable_steps (
+  run_id       TEXT    NOT NULL,
+  step_index   INTEGER NOT NULL,
+  intent       TEXT    NOT NULL,
+  kind         TEXT    NOT NULL,
+  input_hash   TEXT    NOT NULL DEFAULT '',
+  status       TEXT    NOT NULL CHECK (status IN ('pending','running','completed','failed')),
+  attempts     INTEGER NOT NULL DEFAULT 0,
+  result_json  TEXT,
+  error_json   TEXT,
+  started_at   TEXT,
+  completed_at TEXT,
+  PRIMARY KEY (run_id, step_index)
+);
+
+CREATE INDEX IF NOT EXISTS idx_durable_steps_status ON durable_steps(run_id, status);
+
+CREATE TABLE IF NOT EXISTS durable_events (
+  run_id     TEXT NOT NULL,
+  key        TEXT NOT NULL,
+  payload_json TEXT,
+  emitted_at TEXT NOT NULL,
+  PRIMARY KEY (run_id, key)
+);
+
+INSERT OR IGNORE INTO durable_schema_info (version, applied_at)
+VALUES (1, strftime('%Y-%m-%dT%H:%M:%fZ', 'now'));
+`;
+
 // src/durable/workflows.ts
 async function runOnWorkflowStep(workflowStep, input) {
   const stepCfg = input.stepConfig;
@@ -2791,7 +3084,10 @@ export {
   ChatTurnError,
   ConfigError,
   D1DurableRunStore,
+  DURABLE_SCHEMA_SQL,
+  DURABLE_SCHEMA_VERSION,
   DurableAwaitEventTimeoutError,
+  DurableChatTurnEngine,
   DurableRunDivergenceError,
   DurableRunError,
   DurableRunInputMismatchError,
@@ -2819,6 +3115,7 @@ export {
   createTraceBridge,
   decideKnowledgeReadiness,
   deriveWorkerId,
+  durableChatTurnEngine,
   encodeServerSentEvent,
   manifestHash,
   readinessServerSentEvent,
@@ -2826,6 +3123,7 @@ export {
   runAgentTaskStream,
   runChatTurn,
   runDurable,
+  runDurableTurn,
   runOnWorkflowStep,
   runtimeStreamServerSentEvent,
   sandboxAsChatTurnTarget,