@tangle-network/agent-runtime 0.12.1 → 0.13.1

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { AgentEvalError, KnowledgeReadinessReport, ControlEvalResult, KnowledgeRequirement, TraceEvent } from '@tangle-network/agent-eval';
 export { AgentEvalError, AgentEvalErrorCode, CaptureIntegrityError, ConfigError, ControlBudget, ControlDecision, ControlEvalResult, ControlRunResult, ControlStep, DataAcquisitionPlan, JudgeError, KnowledgeReadinessReport, KnowledgeRequirement, NotFoundError, ReplayError, RunRecord, UserQuestion, ValidationError, VerificationError } from '@tangle-network/agent-eval';
-import { A as AgentBackendInput, a as AgentExecutionBackend, b as AgentBackendContext, R as RuntimeStreamEvent, K as KnowledgeReadinessDecision, c as RunAgentTaskOptions, d as AgentTaskRunResult, e as RunAgentTaskStreamOptions, f as AgentTaskRunSummary, g as AgentTaskSpec, h as AgentRuntimeEvent, i as AgentTaskStatus, j as RuntimeSessionStore, k as RuntimeSession } from './types-afLuHk1G.js';
-export { l as AgentAdapter, m as AgentKnowledgeProvider, n as AgentRuntimeEventSink, o as AgentTaskContext } from './types-afLuHk1G.js';
+import { A as AgentBackendInput, a as AgentExecutionBackend, b as AgentBackendContext, R as RuntimeStreamEvent, c as AgentTaskSpec, K as KnowledgeReadinessDecision, d as RunAgentTaskOptions, e as AgentTaskRunResult, f as RunAgentTaskStreamOptions, g as AgentTaskRunSummary, h as AgentRuntimeEvent, i as AgentTaskStatus, j as RuntimeSessionStore, k as RuntimeSession } from './types-jr_EFhrD.js';
+export { l as AgentAdapter, m as AgentKnowledgeProvider, n as AgentRuntimeEventSink, o as AgentTaskContext } from './types-jr_EFhrD.js';
 import { AgentProfilePrompt, AgentProfileResources, AgentSubagentProfile, AgentProfile, SandboxInstance } from '@tangle-network/sandbox';
 
 /**
@@ -168,6 +168,699 @@ declare function sandboxAsChatTurnTarget(instance: SandboxInstance, opts?: {
     };
 }): ChatTurnSandbox;
 
+/**
+ * Durable-run substrate: the typed contract for checkpointed agent runs that
+ * survive worker crashes, deploy rolls, OOM, and transient transport errors.
+ *
+ * The model — directly inspired by Absurd (Postgres-backed) and Cloudflare
+ * Workflows — splits a run into ordered, idempotent **steps**. Each step's
+ * result is persisted before the next step runs. On resume, the runner reads
+ * the prior steps from a `DurableRunStore` and fast-replays them (returning
+ * cached values) until it reaches the first unfinished step, where execution
+ * actually resumes.
+ *
+ * Three boundary disciplines:
+ *
+ *   1. Step results MUST be JSON-serializable. No closures, no class
+ *      instances, no live streams. The store treats results as opaque JSON.
+ *
+ *   2. Step intents MUST be stable across replays. The runner derives a
+ *      stable step id from (runId, stepIndex, intent). Mismatched intent at
+ *      the same index = `DurableRunDivergenceError`.
+ *
+ *   3. Non-determinism (now / uuid / random) MUST flow through the
+ *      `DurableContext` helpers — `ctx.now()`, `ctx.uuid()` — so the values
+ *      are checkpointed and identical on replay. Bare `Date.now()` /
+ *      `crypto.randomUUID()` inside a task fn breaks replay equality.
+ */
+
+/** Caller-facing kinds. The runner uses these for telemetry + querying. */
+type StepKind = 
+/** Logical step that ran user code (the default for ctx.step). */
+'logic'
+/** A wrapped LLM call. */
+ | 'llm'
+/** A wrapped tool call. */
+ | 'tool'
+/** A wrapped readiness probe. */
+ | 'readiness'
+/** A deterministic clock or uuid read. */
+ | 'deterministic'
+/** A suspend-for-event boundary. */
+ | 'event';
+type StepStatus = 'pending' | 'running' | 'completed' | 'failed';
+interface StepError {
+    message: string;
+    code?: string;
+    /** Optional stack — stored for diagnostics, NEVER replayed as an exception. */
+    stack?: string;
+}
+interface StepRecord<T = unknown> {
+    runId: string;
+    /** Monotonic 0-based index. Position is the load-bearing identifier — the
+     *  same intent string at different positions is a different step. */
+    stepIndex: number;
+    /** Caller-supplied label; intended for human reading + log correlation. */
+    intent: string;
+    kind: StepKind;
+    /** sha256 of the canonical input fingerprint at begin-time. Used to detect
+     *  divergence (caller changed inputs across replays). Empty for steps where
+     *  the input cannot be canonicalized (e.g. ctx.now()). */
+    inputHash: string;
+    status: StepStatus;
+    /** Re-entry count. Increments each time the step begins. */
+    attempts: number;
+    /** JSON-serializable result. Present when status === 'completed'. */
+    result?: T;
+    error?: StepError;
+    startedAt?: string;
+    completedAt?: string;
+}
+interface EventRecord {
+    runId: string;
+    key: string;
+    payload: unknown;
+    emittedAt: string;
+}
+type RunStatus = 'pending' | 'running' | 'completed' | 'failed' | 'suspended';
+interface RunOutcome {
+    pass?: boolean;
+    score?: number;
+    notes?: string;
+    /** Free-form bag of run-level metrics — surfaced in OTLP / TraceStore. */
+    metadata?: Record<string, unknown>;
+}
+interface DurableRunManifest {
+    /** Stable per-product id (e.g. 'legal-agent', 'creative-agent'). */
+    projectId: string;
+    /** Optional scenario / persona / session id — surfaced in telemetry. */
+    scenarioId?: string;
+    task: AgentTaskSpec;
+    /** Input payload. Hashed into the run identity so two runs with the same
+     *  runId but different inputs raise DurableRunInputMismatchError. */
+    input: Record<string, unknown>;
+    /** Free-form tags surfaced into RunRecord / OTLP. */
+    tags?: Record<string, string>;
+}
+interface RunRecord {
+    runId: string;
+    manifestHash: string;
+    projectId: string;
+    scenarioId?: string;
+    status: RunStatus;
+    createdAt: string;
+    updatedAt: string;
+    completedAt?: string;
+    /** Stable per-worker id holding the lease. */
+    leaseHolderId?: string;
+    leaseExpiresAt?: string;
+    outcome?: RunOutcome;
+    stepCount: number;
+}
+/**
+ * The durable-run substrate. Implementations: in-memory (dev), file-system
+ * (eval harness), D1 (Cloudflare prod). All stores share this exact contract
+ * — swap by changing one factory call.
+ *
+ * Concurrency model: at most one worker holds a run's lease at a time. Lease
+ * renewal happens on a heartbeat; on lease expiry, another worker can
+ * `startOrResume` and pick up. Steps committed by the prior worker survive.
+ */
+interface DurableRunStore {
+    /**
+     * Begin or resume a run. Returns the canonical RunRecord, all previously
+     * completed steps (in order), and the lease deadline.
+     *
+     * If the run did not exist, creates it with status='running'. If it existed
+     * with a different manifest hash, throws DurableRunInputMismatchError.
+     * If it existed with a live lease held by a different worker, throws
+     * DurableRunLeaseHeldError (caller can retry or back off).
+     */
+    startOrResume(input: {
+        runId: string;
+        manifest: DurableRunManifest;
+        workerId: string;
+        leaseMs?: number;
+    }): Promise<{
+        run: RunRecord;
+        completedSteps: ReadonlyArray<StepRecord>;
+        leaseExpiresAt: string;
+    }>;
+    /** Renew the lease. Returns false if another worker now holds it. */
+    renewLease(input: {
+        runId: string;
+        workerId: string;
+        leaseMs?: number;
+    }): Promise<{
+        ok: boolean;
+        leaseExpiresAt?: string;
+    }>;
+    /** Load a step by position. Returns undefined if not yet begun. */
+    loadStep(runId: string, stepIndex: number): Promise<StepRecord | undefined>;
+    /** Record step start (intent + input hash + kind). Bumps attempt count. */
+    beginStep(input: {
+        runId: string;
+        stepIndex: number;
+        intent: string;
+        kind: StepKind;
+        inputHash: string;
+    }): Promise<StepRecord>;
+    /** Mark step completed with a JSON-serializable result. */
+    completeStep(input: {
+        runId: string;
+        stepIndex: number;
+        result: unknown;
+    }): Promise<StepRecord>;
+    /** Mark step failed with a captured error. */
+    failStep(input: {
+        runId: string;
+        stepIndex: number;
+        error: StepError;
+    }): Promise<StepRecord>;
+    /** End the run; releases lease. */
+    endRun(input: {
+        runId: string;
+        workerId: string;
+        status: 'completed' | 'failed';
+        outcome?: RunOutcome;
+    }): Promise<RunRecord>;
+    /**
+     * Emit an event. First emit wins; subsequent emits return the existing
+     * record under `existing` and accepted=false. Caller can treat that as
+     * idempotency-by-design — never double-fire a downstream side effect.
+     */
+    emitEvent(input: {
+        runId: string;
+        key: string;
+        payload: unknown;
+    }): Promise<{
+        accepted: boolean;
+        record: EventRecord;
+    }>;
+    /** Load the cached event payload if it has been emitted. */
+    loadEvent(runId: string, key: string): Promise<EventRecord | undefined>;
+    /** Cleanup hook for in-memory / fs stores; no-op for D1. Idempotent. */
+    close(): Promise<void>;
+}
+/** Base class for durable-run errors. */
+declare class DurableRunError extends Error {
+    readonly code: 'lease_held' | 'manifest_mismatch' | 'step_divergence' | 'step_input_mismatch' | 'await_event_timeout' | 'event_emit_race';
+    constructor(message: string, code: 'lease_held' | 'manifest_mismatch' | 'step_divergence' | 'step_input_mismatch' | 'await_event_timeout' | 'event_emit_race');
+}
+/** Thrown when another worker holds the lease for this runId. */
+declare class DurableRunLeaseHeldError extends DurableRunError {
+    constructor(message: string);
+}
+/** Thrown when the manifest hash differs from a prior run with the same id. */
+declare class DurableRunInputMismatchError extends DurableRunError {
+    constructor(message: string);
+}
+/** Thrown when the same stepIndex re-runs with a different intent string. */
+declare class DurableRunDivergenceError extends DurableRunError {
+    constructor(message: string);
+}
+/** Thrown when `awaitEvent` times out. */
+declare class DurableAwaitEventTimeoutError extends DurableRunError {
+    constructor(message: string);
+}
+
+/**
+ * D1DurableRunStore — the production path for Cloudflare Workers. Backed by
+ * a D1 (SQLite-compatible) database via the binding the worker already holds.
+ *
+ * Apply `./schema.sql` once before use; the store itself does not run DDL.
+ * Migration version is recorded in `durable_schema_info`; consumers can
+ * inspect `getSchemaVersion()` if they ship a migration tool.
+ *
+ * Why structural typing: agent-runtime stays Cloudflare-free at the dep
+ * level. Consumers pass their `D1Database` binding — TypeScript matches the
+ * minimal `D1DatabaseLike` surface below. Tests use the same interface with
+ * a fake.
+ */
+
+/**
+ * Minimal D1 surface this store uses. Compatible with Cloudflare's
+ * `D1Database` from `@cloudflare/workers-types`. Defined locally so
+ * agent-runtime does not depend on workers-types at the package level.
+ */
+interface D1DatabaseLike {
+    prepare(query: string): D1PreparedStatementLike;
+    batch(statements: D1PreparedStatementLike[]): Promise<unknown[]>;
+}
+interface D1PreparedStatementLike {
+    bind(...values: unknown[]): D1PreparedStatementLike;
+    first<T = unknown>(): Promise<T | null>;
+    all<T = unknown>(): Promise<{
+        results: T[];
+    }>;
+    run(): Promise<{
+        success: boolean;
+        meta?: {
+            changes?: number;
+        };
+    }>;
+}
+declare class D1DurableRunStore implements DurableRunStore {
+    private readonly db;
+    constructor(db: D1DatabaseLike);
+    /** Override for tests — defaults to Date.now(). */
+    now: () => number;
+    startOrResume(input: {
+        runId: string;
+        manifest: DurableRunManifest;
+        workerId: string;
+        leaseMs?: number;
+    }): ReturnType<DurableRunStore['startOrResume']>;
+    renewLease(input: {
+        runId: string;
+        workerId: string;
+        leaseMs?: number;
+    }): Promise<{
+        ok: boolean;
+        leaseExpiresAt?: string;
+    }>;
+    loadStep(runId: string, stepIndex: number): Promise<StepRecord | undefined>;
+    beginStep(input: {
+        runId: string;
+        stepIndex: number;
+        intent: string;
+        kind: StepKind;
+        inputHash: string;
+    }): Promise<StepRecord>;
+    completeStep(input: {
+        runId: string;
+        stepIndex: number;
+        result: unknown;
+    }): Promise<StepRecord>;
+    failStep(input: {
+        runId: string;
+        stepIndex: number;
+        error: StepError;
+    }): Promise<StepRecord>;
+    endRun(input: {
+        runId: string;
+        workerId: string;
+        status: 'completed' | 'failed';
+        outcome?: RunOutcome;
+    }): Promise<RunRecord>;
+    emitEvent(input: {
+        runId: string;
+        key: string;
+        payload: unknown;
+    }): ReturnType<DurableRunStore['emitEvent']>;
+    loadEvent(runId: string, key: string): Promise<EventRecord | undefined>;
+    close(): Promise<void>;
+    /** Inspect the currently-applied schema version. */
+    getSchemaVersion(): Promise<number | undefined>;
+    private readSteps;
+    private bumpUpdated;
+}
+
+/**
+ * FileSystemDurableRunStore — durable-run substrate backed by a directory
+ * tree under a single root. One subdir per run:
+ *
+ *   <root>/<runId>/
+ *     run.json         — RunRecord (rewritten on every mutation; the only
+ *                        scalar fields are status/lease, so this stays small)
+ *     steps.jsonl      — append-only StepRecord stream; one JSON per line
+ *     events.jsonl     — append-only EventRecord stream
+ *     lease.json       — current leaseholder + deadline (separate from
+ *                        run.json so renewLease writes one tiny file
+ *                        instead of round-tripping the whole run record)
+ *
+ * Concurrency: the eval harness is single-process — we rely on Node's
+ * append-mode semantics for atomicity of step / event writes (single-line
+ * writes < PIPE_BUF are atomic on POSIX). For run.json / lease.json we write
+ * to a `<file>.tmp` then `rename` to make replacement atomic. This is
+ * sufficient for the single-process eval harness use case. Multi-process
+ * concurrency on the SAME filesystem requires a flock-based extension;
+ * for that path use D1DurableRunStore.
+ */
+
+declare class FileSystemDurableRunStore implements DurableRunStore {
+    private readonly root;
+    constructor(root: string);
+    /** Override for tests — defaults to Date.now(). */
+    now: () => number;
+    startOrResume(input: {
+        runId: string;
+        manifest: DurableRunManifest;
+        workerId: string;
+        leaseMs?: number;
+    }): ReturnType<DurableRunStore['startOrResume']>;
+    renewLease(input: {
+        runId: string;
+        workerId: string;
+        leaseMs?: number;
+    }): Promise<{
+        ok: boolean;
+        leaseExpiresAt?: string;
+    }>;
+    loadStep(runId: string, stepIndex: number): Promise<StepRecord | undefined>;
+    beginStep(input: {
+        runId: string;
+        stepIndex: number;
+        intent: string;
+        kind: StepKind;
+        inputHash: string;
+    }): Promise<StepRecord>;
+    completeStep(input: {
+        runId: string;
+        stepIndex: number;
+        result: unknown;
+    }): Promise<StepRecord>;
+    failStep(input: {
+        runId: string;
+        stepIndex: number;
+        error: StepError;
+    }): Promise<StepRecord>;
+    endRun(input: {
+        runId: string;
+        workerId: string;
+        status: 'completed' | 'failed';
+        outcome?: RunOutcome;
+    }): Promise<RunRecord>;
+    emitEvent(input: {
+        runId: string;
+        key: string;
+        payload: unknown;
+    }): ReturnType<DurableRunStore['emitEvent']>;
+    loadEvent(runId: string, key: string): Promise<EventRecord | undefined>;
+    close(): Promise<void>;
+    /** @internal — used by tests to list runs in the store. */
+    _listRunIds(): Promise<string[]>;
+    private runDir;
+    private readRun;
+    private writeRun;
+    private readLeaseSafe;
+    private writeLease;
+    private readSteps;
+    private appendStep;
+    private bumpRunUpdated;
+}
+
+/**
+ * Identity + canonical-hash helpers for the durable-runs substrate.
+ *
+ * Two boundary disciplines:
+ *
+ *   1. **Manifest hash** — sha256 over a sorted-key JSON of (projectId,
+ *      scenarioId, task.id, task.intent, task.domain, input). Same hash =
+ *      same run identity. Used to detect "same runId, different inputs."
+ *
+ *   2. **Step input hash** — sha256 over a sorted-key JSON of the step's
+ *      input fingerprint. Used to detect drift across replays.
+ *
+ * Sorted-key JSON makes hashes deterministic regardless of object insertion
+ * order. NaN / Infinity / undefined / functions / symbols / class instances
+ * are rejected — pure JSON only at the boundary, so the hash matches whatever
+ * the store round-trips.
+ */
+
+/** sha256-hex over a JSON-canonicalized value. */
+declare function canonicalHash(value: unknown): string;
+/** Canonical JSON: object keys sorted lexicographically; arrays preserved. */
+declare function canonicalJson(value: unknown): string;
+/** Hash a DurableRunManifest into the run identity component. */
+declare function manifestHash(manifest: DurableRunManifest): string;
+/** Stable per-step identifier — hash of (runId, position, intent). */
+declare function stepId(runId: string, stepIndex: number, intent: string): string;
+/**
+ * Stable worker id for a single process. Format: `host:pid:rand`. Random
+ * suffix prevents collisions when the host/pid pair is short-lived (e.g.,
+ * Cloudflare isolates that recycle fast).
+ */
+declare function deriveWorkerId(): string;
+
+/**
+ * In-memory DurableRunStore for dev + tests. Single-process. All state lives
+ * in maps. Lease enforcement is real (Date.now() vs lease deadline) so the
+ * crash-recovery + multi-worker race tests run identically against this and
+ * the file-system / D1 stores.
+ */
+
+declare class InMemoryDurableRunStore implements DurableRunStore {
+    private readonly runs;
+    /** Override for tests — defaults to Date.now(). */
+    now: () => number;
+    startOrResume(input: {
+        runId: string;
+        manifest: DurableRunManifest;
+        workerId: string;
+        leaseMs?: number;
+    }): ReturnType<DurableRunStore['startOrResume']>;
+    renewLease(input: {
+        runId: string;
+        workerId: string;
+        leaseMs?: number;
+    }): Promise<{
+        ok: boolean;
+        leaseExpiresAt?: string;
+    }>;
+    loadStep(runId: string, stepIndex: number): Promise<StepRecord | undefined>;
+    beginStep(input: {
+        runId: string;
+        stepIndex: number;
+        intent: string;
+        kind: StepKind;
+        inputHash: string;
+    }): Promise<StepRecord>;
+    completeStep(input: {
+        runId: string;
+        stepIndex: number;
+        result: unknown;
+    }): Promise<StepRecord>;
+    failStep(input: {
+        runId: string;
+        stepIndex: number;
+        error: StepError;
+    }): Promise<StepRecord>;
+    endRun(input: {
+        runId: string;
+        workerId: string;
+        status: 'completed' | 'failed';
+        outcome?: RunOutcome;
+    }): Promise<RunRecord>;
+    emitEvent(input: {
+        runId: string;
+        key: string;
+        payload: unknown;
+    }): ReturnType<DurableRunStore['emitEvent']>;
+    loadEvent(runId: string, key: string): Promise<EventRecord | undefined>;
+    close(): Promise<void>;
+    /** @internal — used by tests to inspect lease metadata. */
+    _inspect(runId: string): RunRecord | undefined;
+    /** @internal — used by tests to simulate lease expiry. */
+    _expireLease(runId: string): void;
+    private requireRun;
+}
+
+/**
+ * Durable runner — wraps a user-supplied async function in checkpoint /
+ * resume / lease semantics. The user writes plain async code, awaiting
+ * `ctx.step(intent, fn)` boundaries. On worker crash, the next caller with
+ * the same `runId` skips completed steps and resumes from the first unfinished
+ * one.
+ *
+ * Invariants:
+ *
+ *   - Step positions are derived from a monotonic counter on the ctx. The
+ *     same intent at position N is the same step across replays. If the user
+ *     reorders steps, position N changes intent and we raise
+ *     DurableRunDivergenceError fail-loud.
+ *
+ *   - `ctx.now()` and `ctx.uuid()` are checkpointed as zero-input logic steps
+ *     with kind='deterministic'. On replay they return the recorded value.
+ *
+ *   - `awaitEvent` writes a 'event' step that records the event payload on
+ *     first awaited completion. On replay, the cached payload returns
+ *     synchronously. If the event has not been emitted and the runner is in
+ *     a fresh execution, it polls the store until timeout.
+ *
+ *   - Lease renewal happens on a wall-clock interval (every leaseMs/3). If
+ *     the store reports a lost lease, the runner aborts the current step
+ *     execution and throws — letting whichever worker holds the lease pick
+ *     up. Committed steps survive.
+ */
+
+interface DurableContext {
+    readonly runId: string;
+    readonly projectId: string;
+    readonly scenarioId?: string;
+    /**
+     * Execute a checkpointed step. The step is identified by its **position**
+     * (monotonic counter on this ctx); `intent` is a human-readable label that
+     * must stay stable across replays.
+     *
+     * On first execution: runs `fn`, records the result, returns it.
+     * On replay: returns the recorded result WITHOUT calling `fn`.
+     *
+     * The `inputFingerprint` (optional) lets the runner detect "same intent,
+     * different inputs" — it gets hashed and compared. If you don't supply
+     * one, drift is allowed (input not checked).
+     */
+    step<T>(intent: string, fn: () => Promise<T>, opts?: {
+        kind?: StepKind;
+        inputFingerprint?: unknown;
+    }): Promise<T>;
+    /** Race-free first-emit-wins event wait. */
+    awaitEvent<T = unknown>(key: string, opts?: {
+        timeoutMs?: number;
+        pollMs?: number;
+    }): Promise<T>;
+    /** Emit an event. First emit wins. Subsequent emits no-op. */
+    emitEvent(key: string, payload: unknown): Promise<{
+        accepted: boolean;
+    }>;
+    /** Deterministic clock — checkpointed once per call. */
+    now(): Promise<Date>;
+    /** Deterministic uuid — checkpointed once per call. */
+    uuid(): Promise<string>;
+}
+interface RunDurableInput<TResult> {
+    runId: string;
+    manifest: DurableRunManifest;
+    store: DurableRunStore;
+    workerId?: string;
+    leaseMs?: number;
+    /** Total time budget for the run. Used for awaitEvent timeouts; runner
+     *  itself doesn't kill long-running steps (the step fn must respect
+     *  AbortSignal if it cares). */
+    signal?: AbortSignal;
+    taskFn: (ctx: DurableContext) => Promise<TResult>;
+    /** Default outcome on successful completion. */
+    defaultOutcome?: RunOutcome;
+}
+interface RunDurableResult<TResult> {
+    result: TResult;
+    record: RunRecord;
+    /** All steps captured this run (replayed + freshly executed). */
+    steps: ReadonlyArray<StepRecord>;
+}
+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.
+ *
+ * Two valid deployment patterns on Cloudflare:
+ *
+ *   A. **Plain Worker + D1DurableRunStore.** Each request invokes
+ *      `runDurable(...)` directly against a D1 binding. Survives worker
+ *      isolate restarts; lease takeover happens via D1 row-level
+ *      conditional UPDATE. The default path; no Workflows binding needed.
+ *
+ *   B. **Cloudflare Workflows entrypoint.** Wrap an entire `runDurable(...)`
+ *      call inside a single Workflow `step.do(...)`. Workflows gives you
+ *      retry-on-throw with platform-managed exponential backoff and
+ *      survives full Workers deploy rolls. Use it when the task can take
+ *      minutes to hours, or when you want the Workflows dashboard for
+ *      observability. Inside the step, `runDurable` still uses D1 for
+ *      step-level checkpoints — so a half-completed run resumes from
+ *      its last checkpoint on retry rather than restarting from scratch.
+ *
+ * This module provides the surface for pattern B: a thin helper that
+ * converts a Workflows `WorkflowStep` into a `DurableContext`. We do not
+ * take a runtime dep on `cloudflare:workers` — the integration is purely
+ * structural typing.
+ *
+ * Example (pattern B):
+ *
+ *   import { WorkflowEntrypoint } from 'cloudflare:workers'
+ *   import { runOnWorkflowStep } from '@tangle-network/agent-runtime'
+ *
+ *   export class LegalChatWorkflow extends WorkflowEntrypoint<Env, ChatParams> {
+ *     async run(event, step) {
+ *       return runOnWorkflowStep(step, {
+ *         workflowName: 'legal-chat',
+ *         taskFn: async (ctx) => {
+ *           const ready  = await ctx.step('readiness',   () => probeKnowledge(...))
+ *           const answer = await ctx.step('llm:turn-1',  () => callLlm(...))
+ *           const shipped = await ctx.awaitEvent('shipped', { timeoutMs: 5 * 60_000 })
+ *           return { answer, shipped }
+ *         },
+ *       })
+ *     }
+ *   }
+ *
+ * Step ordering, replay semantics, and divergence detection inside the
+ * `taskFn` are inherited from Cloudflare's Workflows engine — we
+ * intentionally do NOT layer a second durable store inside this path.
+ * Pick pattern A or pattern B per agent; do not mix.
+ */
+
+/**
+ * Structural subset of Cloudflare's `WorkflowStep`. Mirrors the public surface
+ * documented at https://developers.cloudflare.com/workflows/build/. Defined
+ * here so this module imposes zero `cloudflare:workers` runtime dependency.
+ */
+interface WorkflowStepLike {
+    do<T>(name: string, opts: WorkflowStepConfig, fn: () => Promise<T>): Promise<T>;
+    do<T>(name: string, fn: () => Promise<T>): Promise<T>;
+    sleep(name: string, duration: string | number): Promise<void>;
+    waitForEvent<T = unknown>(name: string, opts: {
+        type: string;
+        timeout?: string;
+    }): Promise<{
+        payload: T;
+        timestamp: number;
+        type: string;
+    }>;
+}
+interface WorkflowStepConfig {
+    retries?: {
+        limit: number;
+        delay: string | number;
+        backoff?: 'constant' | 'linear' | 'exponential';
+    };
+    timeout?: string | number;
+}
+interface RunOnWorkflowStepInput<TResult> {
+    /** Logical workflow name; used as a prefix on step ids for filtering. */
+    workflowName: string;
+    /** User task — same shape as runDurable's taskFn. */
+    taskFn: (ctx: DurableContext) => Promise<TResult>;
+    /** Optional per-step retry / timeout policy applied to ctx.step calls. */
+    stepConfig?: WorkflowStepConfig;
+    /** Optional clock — defaults to Date.now. */
+    now?: () => number;
+}
+/**
+ * Adapt a Cloudflare `WorkflowStep` into a `DurableContext` and run a task.
+ *
+ * Every `ctx.step(intent, fn)` becomes `step.do(<name>, fn)` with stable
+ * names — Workflows checkpoints + replays based on step name + position,
+ * matching our model.
+ *
+ * `ctx.awaitEvent(key)` becomes `step.waitForEvent(key, { type: key })`.
+ * Caller is responsible for emitting from the platform side (e.g. via the
+ * Workflows REST API or a sibling worker that publishes events).
+ *
+ * `ctx.now()` and `ctx.uuid()` go through `step.do` so the values are
+ * captured in the platform's checkpoint state and remain stable across
+ * replay — same invariant as our own stores.
+ */
+declare function runOnWorkflowStep<TResult>(workflowStep: WorkflowStepLike, input: RunOnWorkflowStepInput<TResult>): Promise<TResult>;
+
 /**
  * @stable
  *
@@ -731,4 +1424,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, BackendTransportError, ChatTurnError, type ChatTurnMessage, type ChatTurnOverlay, type ChatTurnSandbox, type ClassifyIntentOptions, type ClassifyIntentResult, type ConformanceIssue, type ConformanceOptions, type ConformanceResult, InMemoryRuntimeSessionStore, KnowledgeReadinessDecision, RunAgentTaskOptions, RunAgentTaskStreamOptions, type RunChatTurnOptions, 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 SubagentMatcher, type TraceBridge, type TraceBridgeOptions, assertProfileConformance, classifyIntent, composeTurnProfile, createIterableBackend, createOpenAICompatibleBackend, createRuntimeEventCollector, createRuntimeStreamEventCollector, createSandboxPromptBackend, createTraceBridge, decideKnowledgeReadiness, encodeServerSentEvent, readinessServerSentEvent, runAgentTask, runAgentTaskStream, runChatTurn, runtimeStreamServerSentEvent, sandboxAsChatTurnTarget, sanitizeAgentRuntimeEvent, sanitizeKnowledgeReadinessReport, sanitizeRuntimeStreamEvent, startRuntimeRun, summarizeAgentTaskRun, toAgentEvalTrace };
+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 };