@tangle-network/agent-runtime 0.12.1 → 0.13.0

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,680 @@ 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>>;
+
+/**
+ * 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 +1405,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, 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 };