@dynamicagents/core 0.9.0

package/dist/job/lifecycle.d.ts

@@ -0,0 +1,176 @@
+import type { WakeMap } from "../alarm/index.js";
+import { type JobState, type RunningJob } from "./state.js";
+/**
+ * The choreography around a long job a Durable Object owns through its alarm.
+ *
+ * The job itself — what command, where, and what its output means — belongs to
+ * the owner. What lives here is the part that is the same every time and is
+ * wrong in the same four ways every time:
+ *
+ * 1. **Arming writes `running` before anything runs.** The alarm has not fired
+ *    yet, and a `done` record in that window lets a gated caller through against
+ *    a workspace that is not ready. Writing `running` first also makes arming
+ *    self-limiting: the next call sees it and stops.
+ * 2. **One job at a time**, guarded by a read that goes *through* the staleness
+ *    bound — so a `running` record left by a dead isolate resolves rather than
+ *    blocking every retry forever.
+ * 3. **A drain can outlive the job it watched.** `ctx.waitUntil` keeps running
+ *    after the RPC returns, and a late drain writing its verdict over a record
+ *    describing a *live* job is silent corruption. {@link generation} is the
+ *    marker that makes it harmless.
+ * 4. **Nobody may be draining at all.** A watch intent re-attaches to a job
+ *    whose isolate went away mid-flight.
+ *
+ * What is deliberately *not* here is the drain loop. Two real consumers want
+ * different ones — an install runs to completion under `waitUntil` and writes a
+ * single verdict; a coding-agent run is drained in bounded windows and reports
+ * partial progress between them. They share the four rules above and nothing
+ * below them, so the loop stays with the owner.
+ *
+ * ## Storage keys
+ *
+ * Derived from {@link JobLifecycleOptions.id} so one object can own several
+ * jobs. For `id: "install"` they come out as `install`, `install:armed`,
+ * `install:last-armed`, `install:context`, and the wake intents `install-run`
+ * and `install-watch` — the exact keys the predecessor wrote by hand, which is
+ * why adopting this needs no storage migration.
+ */
+/** What a job's result looks like to the lifecycle. Deliberately minimal. */
+export interface JobResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+/** A running command, reduced to what the lifecycle needs of it. */
+export interface JobHandle {
+    result(): Promise<JobResult>;
+    [Symbol.dispose](): void;
+}
+/**
+ * The per-job record naming what is running and *which* run it is.
+ *
+ * `startedAt` is the generation marker, so it is the one required field: a drain
+ * compares the stamp it captured against the stamp on disk, and a mismatch means
+ * it has been superseded and has nothing useful left to say.
+ */
+export interface JobContext {
+    startedAt: number;
+}
+export interface JobLifecycleOptions {
+    /** Namespaces every key and intent. Also the state record's own key. */
+    id: string;
+    storage: DurableObjectStorage;
+    wake: WakeMap;
+    /**
+     * How long a `running` record may stand before it is presumed dead.
+     *
+     * Measured from `startedAt` and compared against the job's own timeout plus
+     * this, never against this alone — the point is to outlast a job that is
+     * merely slow, and only then to declare one that is gone.
+     */
+    staleMs?: number;
+    /** How often the watch intent re-checks a job nobody is draining. */
+    watchMs?: number;
+    /**
+     * The floor between two arming attempts.
+     *
+     * Without it a job that cannot start re-arms on every call into the object.
+     */
+    armCooldownMs?: number;
+}
+export declare class JobLifecycle<TExtra extends object = Record<never, never>, TContext extends JobContext = JobContext> {
+    #private;
+    /** `install` — the state record. */
+    readonly stateKey: string;
+    /** `install:armed` — the stamp the arming path wrote, for the alarm to match. */
+    readonly armedKey: string;
+    /** `install:last-armed` — the cooldown floor. */
+    readonly lastArmedKey: string;
+    /** `install:context` — where the generation marker lives. */
+    readonly contextKey: string;
+    /** `install-run` — the intent that *runs* a job. */
+    readonly runIntent: string;
+    /** `install-watch` — the intent that re-attaches to one nobody is draining. */
+    readonly watchIntent: string;
+    constructor(options: JobLifecycleOptions);
+    /** The raw record, with no staleness repair. `idle` when nothing is written. */
+    read(): Promise<JobState<TExtra>>;
+    write(state: JobState<TExtra>): Promise<void>;
+    context(): Promise<TContext | undefined>;
+    /**
+     * Record which run this is, **before** spawning.
+     *
+     * The order is the whole point: a drain captures `startedAt` after the spawn,
+     * so a context written afterwards would let two runs share a generation.
+     */
+    putContext(context: TContext): Promise<void>;
+    /**
+     * Hand a cold job to the alarm, if one is not already pending.
+     *
+     * Returns the stamp it armed with, or `undefined` when it declined — the
+     * caller needs the stamp because it is what the alarm must present to
+     * {@link claim} to get past the single-flight guard.
+     *
+     * An arming caller must **not** own the run. The predecessor handed one to
+     * `ctx.waitUntil` from a gate poll that returned in milliseconds, and the
+     * drain was disposed underneath it mid-command. An alarm invocation belongs to
+     * the object rather than to any request, so nothing it awaits can be cut short.
+     */
+    arm(placeholder: Omit<RunningJob<TExtra>, "state" | "startedAt">): Promise<number | undefined>;
+    /** The stamp {@link arm} wrote, so the alarm can recognise its own placeholder. */
+    armedAt(): Promise<number | undefined>;
+    clearArmed(): Promise<void>;
+    /**
+     * Decide whether a new run may start.
+     *
+     * `takeOverArmedAt` is the one exemption and it is narrow on purpose. The
+     * alarm's placeholder *is* a `running` record for a job that has not started,
+     * so the alarm has to pass its own guard — and only its own. Matching the
+     * exact stamp it wrote is what stops this becoming "take over any running
+     * job", which is the displacement bug the guard exists to prevent: three
+     * callers spawning under one exec id in fifty seconds, each displacing the
+     * last, every displaced drain still attached and still writing verdicts.
+     *
+     * Applies the staleness bound **itself**, rather than trusting the caller to
+     * have repaired the record first. An earlier draft took an
+     * "already-repaired" state and said so in prose, which enforced nothing: the
+     * repaired and raw types are identical, so a caller passing a raw read got a
+     * `running` record that could never be claimed and a job wedged forever.
+     * `timeoutMs` is the job's own budget; see {@link isStale}.
+     */
+    claim(state: JobState<TExtra>, timeoutMs: number, takeOverArmedAt?: number): {
+        ok: true;
+    } | {
+        ok: false;
+        current: RunningJob<TExtra>;
+    };
+    /**
+     * Whether a `running` record has stood long enough to be presumed dead.
+     *
+     * `timeoutMs` is the job's own budget; the bound is that plus `staleMs`, so a
+     * job that is merely slow is never declared gone.
+     */
+    isStale(state: RunningJob<TExtra>, timeoutMs: number, now?: number): boolean;
+    /** Arm the watchdog that re-attaches to a job nobody is draining. */
+    armWatch(now?: number): Promise<void>;
+    /**
+     * Disarm the watchdog.
+     *
+     * Never call this from a superseded drain: the watchdog belongs to whichever
+     * run owns the record *now*, and clearing it there disarms the one recovery
+     * path the live run has.
+     */
+    clearWatch(): Promise<void>;
+    /**
+     * A predicate a drain calls before every write, to ask whether it still owns
+     * the record.
+     *
+     * Captures the stamp once, at drain start, and compares it against disk each
+     * time. The closure also latches, so a drain can ask afterwards whether it was
+     * superseded — which is what decides if it may touch the watchdog.
+     */
+    generation(startedAt: number): {
+        stillMine: () => Promise<boolean>;
+        superseded: () => boolean;
+    };
+}

package/dist/job/lifecycle.js

@@ -0,0 +1,230 @@
+import { isRearmable } from "./state.js";
+/**
+ * `WakeMap`'s own storage row, spelled here rather than imported.
+ *
+ * Importing `WAKE_KEY` would be a *value* import from `../alarm`, and this
+ * module is careful to reach that package only for types — a runtime edge would
+ * pull the whole alarm module into any bundle that imports `/job`. So the string
+ * is duplicated, and `lifecycle.spec.ts` asserts it still equals `WAKE_KEY`;
+ * specs never ship, so the check costs nothing at runtime and fails loudly if
+ * the two ever drift.
+ */
+const WAKE_MAP_KEY = "wake";
+const DEFAULT_STALE_MS = 5 * 60_000;
+const DEFAULT_WATCH_MS = 60_000;
+const DEFAULT_ARM_COOLDOWN_MS = 5 * 60_000;
+export class JobLifecycle {
+    #o;
+    /** `install` — the state record. */
+    stateKey;
+    /** `install:armed` — the stamp the arming path wrote, for the alarm to match. */
+    armedKey;
+    /** `install:last-armed` — the cooldown floor. */
+    lastArmedKey;
+    /** `install:context` — where the generation marker lives. */
+    contextKey;
+    /** `install-run` — the intent that *runs* a job. */
+    runIntent;
+    /** `install-watch` — the intent that re-attaches to one nobody is draining. */
+    watchIntent;
+    constructor(options) {
+        /**
+         * An id is a storage key, so a bad one is not a bad name — it is a write
+         * landing on somebody else's row.
+         *
+         * `"wake"` is the one that matters and the reason this guard exists: it is
+         * `WakeMap`'s single row, so a job with that id would overwrite the whole
+         * intent map on its first state write, and the `wake.set()` immediately
+         * after would then read job fields as intents. Every pending wake-up on the
+         * object — not just this job's — silently stops happening.
+         *
+         * Empty is rejected for the same reason one level down: it yields the
+         * intents `-run` and `-watch`, which two differently-broken callers would
+         * share.
+         */
+        if (!options.id)
+            throw new Error("a job id must be a non-empty string");
+        if (options.id === WAKE_MAP_KEY) {
+            throw new Error(`"${WAKE_MAP_KEY}" is reserved: it is WakeMap's storage row, and a job ` +
+                `with that id would overwrite every pending intent on this object`);
+        }
+        this.#o = {
+            ...options,
+            staleMs: options.staleMs ?? DEFAULT_STALE_MS,
+            watchMs: options.watchMs ?? DEFAULT_WATCH_MS,
+            armCooldownMs: options.armCooldownMs ?? DEFAULT_ARM_COOLDOWN_MS
+        };
+        this.stateKey = options.id;
+        this.armedKey = `${options.id}:armed`;
+        this.lastArmedKey = `${options.id}:last-armed`;
+        this.contextKey = `${options.id}:context`;
+        this.runIntent = `${options.id}-run`;
+        this.watchIntent = `${options.id}-watch`;
+    }
+    // --- the record ------------------------------------------------------------
+    /** The raw record, with no staleness repair. `idle` when nothing is written. */
+    async read() {
+        return ((await this.#o.storage.get(this.stateKey)) ??
+            { state: "idle" });
+    }
+    async write(state) {
+        await this.#o.storage.put(this.stateKey, state);
+    }
+    async context() {
+        return await this.#o.storage.get(this.contextKey);
+    }
+    /**
+     * Record which run this is, **before** spawning.
+     *
+     * The order is the whole point: a drain captures `startedAt` after the spawn,
+     * so a context written afterwards would let two runs share a generation.
+     */
+    async putContext(context) {
+        await this.#o.storage.put(this.contextKey, context);
+    }
+    // --- arming ----------------------------------------------------------------
+    /**
+     * Hand a cold job to the alarm, if one is not already pending.
+     *
+     * Returns the stamp it armed with, or `undefined` when it declined — the
+     * caller needs the stamp because it is what the alarm must present to
+     * {@link claim} to get past the single-flight guard.
+     *
+     * An arming caller must **not** own the run. The predecessor handed one to
+     * `ctx.waitUntil` from a gate poll that returned in milliseconds, and the
+     * drain was disposed underneath it mid-command. An alarm invocation belongs to
+     * the object rather than to any request, so nothing it awaits can be cut short.
+     */
+    async arm(placeholder) {
+        const state = await this.read();
+        if (!isRearmable(state))
+            return undefined;
+        const lastArmed = await this.#o.storage.get(this.lastArmedKey);
+        if (lastArmed !== undefined &&
+            Date.now() - lastArmed < this.#o.armCooldownMs)
+            return undefined;
+        const armedAt = Date.now();
+        await this.write({
+            ...placeholder,
+            state: "running",
+            startedAt: armedAt
+        });
+        await this.#o.storage.put(this.armedKey, armedAt);
+        // Kept even if the scheduling below fails, deliberately: a floor that only
+        // applied to *successful* arming would let a persistently failing schedule
+        // re-arm on every call into the object, which is what it exists to prevent.
+        await this.#o.storage.put(this.lastArmedKey, armedAt);
+        /**
+         * The placeholder and the alarm that owns it are two writes, and between
+         * them is the one window where this can strand a job: a `running` record no
+         * run intent points at, which every later {@link arm} then declines to
+         * replace *because* it is running.
+         *
+         * The staleness bound in {@link claim} would eventually free it, but only
+         * after a full timeout — so unwind instead, and leave the record exactly as
+         * re-armable as it was found.
+         */
+        try {
+            await this.#o.wake.set({ key: this.runIntent, notBefore: armedAt });
+        }
+        catch (err) {
+            await this.write(state);
+            await this.#o.storage.delete(this.armedKey).catch(() => { });
+            throw err;
+        }
+        return armedAt;
+    }
+    /** The stamp {@link arm} wrote, so the alarm can recognise its own placeholder. */
+    async armedAt() {
+        return await this.#o.storage.get(this.armedKey);
+    }
+    async clearArmed() {
+        await this.#o.storage.delete(this.armedKey);
+    }
+    // --- the single-flight guard ------------------------------------------------
+    /**
+     * Decide whether a new run may start.
+     *
+     * `takeOverArmedAt` is the one exemption and it is narrow on purpose. The
+     * alarm's placeholder *is* a `running` record for a job that has not started,
+     * so the alarm has to pass its own guard — and only its own. Matching the
+     * exact stamp it wrote is what stops this becoming "take over any running
+     * job", which is the displacement bug the guard exists to prevent: three
+     * callers spawning under one exec id in fifty seconds, each displacing the
+     * last, every displaced drain still attached and still writing verdicts.
+     *
+     * Applies the staleness bound **itself**, rather than trusting the caller to
+     * have repaired the record first. An earlier draft took an
+     * "already-repaired" state and said so in prose, which enforced nothing: the
+     * repaired and raw types are identical, so a caller passing a raw read got a
+     * `running` record that could never be claimed and a job wedged forever.
+     * `timeoutMs` is the job's own budget; see {@link isStale}.
+     */
+    claim(state, timeoutMs, takeOverArmedAt) {
+        if (state.state !== "running")
+            return { ok: true };
+        // The alarm presenting its own placeholder — the one narrow exemption.
+        if (state.startedAt === takeOverArmedAt)
+            return { ok: true };
+        // A record whose isolate is gone must not block every later run.
+        if (this.isStale(state, timeoutMs))
+            return { ok: true };
+        return { ok: false, current: state };
+    }
+    // --- staleness and re-attach -------------------------------------------------
+    /**
+     * Whether a `running` record has stood long enough to be presumed dead.
+     *
+     * `timeoutMs` is the job's own budget; the bound is that plus `staleMs`, so a
+     * job that is merely slow is never declared gone.
+     */
+    isStale(state, timeoutMs, now = Date.now()) {
+        return now - state.startedAt > timeoutMs + this.#o.staleMs;
+    }
+    /** Arm the watchdog that re-attaches to a job nobody is draining. */
+    async armWatch(now = Date.now()) {
+        await this.#o.wake.set({
+            key: this.watchIntent,
+            notBefore: now + this.#o.watchMs
+        });
+    }
+    /**
+     * Disarm the watchdog.
+     *
+     * Never call this from a superseded drain: the watchdog belongs to whichever
+     * run owns the record *now*, and clearing it there disarms the one recovery
+     * path the live run has.
+     */
+    async clearWatch() {
+        await this.#o.wake.clear(this.watchIntent).catch(() => { });
+    }
+    // --- generation --------------------------------------------------------------
+    /**
+     * A predicate a drain calls before every write, to ask whether it still owns
+     * the record.
+     *
+     * Captures the stamp once, at drain start, and compares it against disk each
+     * time. The closure also latches, so a drain can ask afterwards whether it was
+     * superseded — which is what decides if it may touch the watchdog.
+     */
+    generation(startedAt) {
+        let superseded = false;
+        return {
+            stillMine: async () => {
+                // The latch is checked *before* the read, not after. Ownership is not
+                // recoverable: once another run has owned this record, a stamp that
+                // happens to match again does not hand it back, and a drain that
+                // regained write access here would be the corruption the marker exists
+                // to prevent.
+                if (superseded)
+                    return false;
+                const now = await this.context();
+                if (now?.startedAt === startedAt)
+                    return true;
+                superseded = true;
+                return false;
+            },
+            superseded: () => superseded
+        };
+    }
+}

package/dist/job/state.d.ts

@@ -0,0 +1,92 @@
+/**
+ * The record an alarm-owned job writes about itself, and the shape a gate reads.
+ *
+ * This is the contract between two halves that do not own each other: the
+ * Durable Object *runs* the job, and something else — a shell tool, a subagent
+ * executor — refuses to proceed while one is in flight. A shape they agreed on
+ * informally would drift, and the drift shows up as a command running halfway
+ * through the job it was supposed to wait for.
+ *
+ * ## Why `TExtra` intersects rather than nests
+ *
+ * The obvious generic is `{ state: "running"; meta: TExtra }`. It is wrong here,
+ * and expensively so: every existing reader spells the job's own field at the
+ * top level (`status.command`), so nesting would rewrite every read site and
+ * every spec assertion in both consumers to buy nothing. Intersecting keeps
+ * `JobState<{ command: string }>` *byte-identical* to the hand-written union it
+ * replaces, which is what makes adopting this a type change and not a refactor.
+ *
+ * The cost of the choice is that `TExtra` must not collide with the field names
+ * below. That is a real constraint, and it is why they are named for the
+ * mechanism (`startedAt`, `finishedAt`, `exitCode`) rather than for any job.
+ */
+/**
+ * A job's durable state.
+ *
+ * Five variants, and the two that look redundant are not:
+ *
+ * - `idle` — nothing has ever run. There is no context recording *where* or
+ *   *what*, so a caller cannot re-drive it; that is the owner's job.
+ * - `skipped` — something looked and decided there was nothing to do. Terminal
+ *   and *correct*, which is why it is not `done`: a gate must not treat a
+ *   deliberate no-op as a failure to retry, and an arming path must not re-drive
+ *   it forever.
+ * - `running` — in flight, or believed to be. Never trusted without the
+ *   staleness bound in {@link JobLifecycle.claim}, because the isolate that
+ *   wrote it may be long gone.
+ * - `done` / `failed` — terminal, carrying enough to explain the outcome without
+ *   the caller reaching for the transcript.
+ */
+/** Nothing has ever run; no context exists naming what would. */
+export type IdleJob = {
+    state: "idle";
+};
+/** Something looked and decided there was nothing to do. Terminal and correct. */
+export type SkippedJob = {
+    state: "skipped";
+    reason: string;
+};
+/** In flight, or believed to be. Never trusted without the staleness bound. */
+export type RunningJob<TExtra = Record<never, never>> = {
+    state: "running";
+    startedAt: number;
+    tail?: string;
+} & TExtra;
+export type DoneJob<TExtra = Record<never, never>> = {
+    state: "done";
+    exitCode: number;
+    finishedAt: number;
+    ms: number;
+    tail?: string;
+} & TExtra;
+export type FailedJob<TExtra = Record<never, never>> = {
+    state: "failed";
+    finishedAt: number;
+    error: string;
+    exitCode?: number;
+    tail?: string;
+} & TExtra;
+/**
+ * A job's durable state.
+ *
+ * The variants are named types rather than inlined into the union because
+ * `Extract<JobState<TExtra>, { state: "running" }>` cannot narrow while `TExtra`
+ * is generic — the compiler has no way to prove `DoneJob & TExtra` does not also
+ * carry `state: "running"`. Naming them is what lets a caller say
+ * `RunningJob<TExtra>` and get its fields.
+ */
+export type JobState<TExtra = Record<never, never>> = IdleJob | SkippedJob | RunningJob<TExtra> | DoneJob<TExtra> | FailedJob<TExtra>;
+/**
+ * Whether a state is one a new run may start from.
+ *
+ * `done` and `failed` both qualify, and the second was a gap worth closing in
+ * the predecessor: arming used to require `done`, so one bad run left a record
+ * that declined to re-arm forever — one failure poisoning every task after it.
+ *
+ * `skipped` and `idle` are excluded for different reasons. `skipped` means the
+ * answer is already correct and permanent. `idle` means no context exists naming
+ * what to run, so there is nothing to re-drive.
+ */
+export declare function isRearmable<TExtra extends object>(state: JobState<TExtra>): boolean;
+/** Whether a state claims a job is in flight. Never conclusive on its own. */
+export declare function isRunning<TExtra extends object>(state: JobState<TExtra>): state is RunningJob<TExtra>;

package/dist/job/state.js

@@ -0,0 +1,40 @@
+/**
+ * The record an alarm-owned job writes about itself, and the shape a gate reads.
+ *
+ * This is the contract between two halves that do not own each other: the
+ * Durable Object *runs* the job, and something else — a shell tool, a subagent
+ * executor — refuses to proceed while one is in flight. A shape they agreed on
+ * informally would drift, and the drift shows up as a command running halfway
+ * through the job it was supposed to wait for.
+ *
+ * ## Why `TExtra` intersects rather than nests
+ *
+ * The obvious generic is `{ state: "running"; meta: TExtra }`. It is wrong here,
+ * and expensively so: every existing reader spells the job's own field at the
+ * top level (`status.command`), so nesting would rewrite every read site and
+ * every spec assertion in both consumers to buy nothing. Intersecting keeps
+ * `JobState<{ command: string }>` *byte-identical* to the hand-written union it
+ * replaces, which is what makes adopting this a type change and not a refactor.
+ *
+ * The cost of the choice is that `TExtra` must not collide with the field names
+ * below. That is a real constraint, and it is why they are named for the
+ * mechanism (`startedAt`, `finishedAt`, `exitCode`) rather than for any job.
+ */
+/**
+ * Whether a state is one a new run may start from.
+ *
+ * `done` and `failed` both qualify, and the second was a gap worth closing in
+ * the predecessor: arming used to require `done`, so one bad run left a record
+ * that declined to re-arm forever — one failure poisoning every task after it.
+ *
+ * `skipped` and `idle` are excluded for different reasons. `skipped` means the
+ * answer is already correct and permanent. `idle` means no context exists naming
+ * what to run, so there is nothing to re-drive.
+ */
+export function isRearmable(state) {
+    return state.state === "done" || state.state === "failed";
+}
+/** Whether a state claims a job is in flight. Never conclusive on its own. */
+export function isRunning(state) {
+    return state.state === "running";
+}

package/dist/platform.d.ts

@@ -0,0 +1,138 @@
+import type { WorkflowStepConfig } from "cloudflare:workers";
+/**
+ * What the Cloudflare Workflows runtime imposes, and the two numbers derived from
+ * it. Nothing here is a budget or a preference — see {@link file://./config.ts}
+ * for those, and note that no Recipe can reach these. They change when the
+ * platform changes, and for no other reason.
+ *
+ * The distinction is worth keeping sharp, because collapsing it produces a
+ * specific bug: using a *turn count* to keep a step under the step timeout only
+ * works if you can predict how long a turn takes. You cannot. Time bounds time
+ * here; turns bound cost, over in `config.ts`.
+ */
+/**
+ * The step timeout **we configure**, passed as `WorkflowStepConfig.timeout` on
+ * every step that can hold a model call or a container command.
+ *
+ * This is the one value in this file that is **not** a platform fact, and
+ * treating it as one is the mistake to avoid: ten minutes is Workflows'
+ * *default* step timeout, not its ceiling, and a step that never passes a config
+ * inherits it silently. Sizing {@link CHUNK_SOFT_MS} against that inherited
+ * default is what once ran a production task as ten four-minute slices, one of
+ * which blew the ten minutes anyway and was retried whole.
+ *
+ * The genuine platform facts are narrower and do not bind us: wall-clock time per
+ * step is effectively unlimited, and a step is bounded by **CPU** time. Measured
+ * over a 59-minute task, the chunk steps used ~100 ms of CPU against 3,146 s of
+ * wall — this ceiling is nowhere near the real one.
+ *
+ * It is still a ceiling worth having, because it is what turns a hung container
+ * into a retry rather than a task that never ends. {@link CHUNK_SOFT_MS} is sized
+ * against it, and that relationship is asserted in `platform.spec.ts`.
+ */
+export declare const STEP_TIMEOUT_MS: number;
+/**
+ * Platform fact: a single Workflow instance may run 10,000 steps by default on the
+ * paid plan. Cloudflare will raise it to 25,000 on request — worth knowing, and
+ * worth not relying on: {@link MAX_CHUNKS_PER_BRANCH} is sized against the default
+ * so nothing here needs an account-level exception to be correct. See the
+ * worst-case product asserted in `platform.spec.ts`.
+ */
+export declare const STEPS_PER_INSTANCE = 10000;
+/**
+ * How long one durable chunk may run before it checkpoints and yields a fresh
+ * step. Comfortably inside {@link STEP_TIMEOUT_MS} so a slow model turn in flight
+ * when the soft limit trips still has room to finish.
+ *
+ * This is the *only* thing keeping a step under the timeout. A subagent otherwise
+ * runs until its turn or wall-clock budget is spent, however many turns that takes
+ * — which is the point: the runner no longer guesses at turn duration.
+ *
+ * ## Why this is 15 minutes and not 4
+ *
+ * A chunk boundary is not free. It checkpoints, returns through two RPC hops,
+ * starts a fresh step, and re-hydrates the subagent — and for a coding agent it
+ * also means the container connection is re-established. Four minutes bought a
+ * boundary roughly every third tool call: a task that edited one README line spent
+ * 59 minutes across **ten** chunks, and the model was idle for most of each one,
+ * blocked on a single `sb_exec` running the project's test gate.
+ *
+ * ## Why it is not larger, which is the part that bit us
+ *
+ * This is a **soft** deadline, checked between turns (`stopWhen` in
+ * `subagent/run.ts`). A turn that starts one millisecond before it trips still runs
+ * to completion, so the real worst case is:
+ *
+ *     chunk wall  ≤  CHUNK_SOFT_MS + one whole turn
+ *
+ * and one turn is a model call plus a tool call. The old pair ignored that: four
+ * minutes soft under a ten-minute timeout looked like six minutes of headroom, but
+ * a single `sb_exec` may run for {@link MAX_TOOL_CALL_MS}, so a turn could add ten.
+ * That is not a hypothetical — it is the `WorkflowTimeoutError` that cost a
+ * production task ten minutes and a full chunk replay.
+ *
+ * So the headroom is sized against a whole turn, not against a guess:
+ * `STEP_TIMEOUT_MS - CHUNK_SOFT_MS` is 15 minutes, covering
+ * {@link MAX_TOOL_CALL_MS} of tool call plus five minutes for the model call and
+ * its provider retries. Asserted in `platform.spec.ts` — raise the step timeout
+ * before raising this.
+ */
+export declare const CHUNK_SOFT_MS: number;
+/**
+ * The longest a **single tool call** may run, and a contract rather than a
+ * mechanism: core has no way to enforce it, because core installs no tools.
+ *
+ * It exists because {@link CHUNK_SOFT_MS} cannot be reasoned about without it. The
+ * soft deadline is checked between turns, so a host that lets one tool block for
+ * longer than the headroom under {@link STEP_TIMEOUT_MS} reintroduces exactly the
+ * step-timeout kill this pair is sized to prevent — and it reintroduces it
+ * invisibly, in a plugin, a long way from this file.
+ *
+ * A host installing a tool that can block (a shell, a container command, a fetch
+ * with no ceiling of its own) must bound it at or below this. See the `timeoutMs`
+ * passed to `@dynamicagents/plugins/computer` in starter.
+ */
+export declare const MAX_TOOL_CALL_MS: number;
+/**
+ * Hard ceiling on durable chunk steps for one Subtask branch. A backstop, not a
+ * budget: the Workflow *fails* a branch that reaches it, so reaching it is a bug.
+ * It is held unreachable by two constraints, both asserted in
+ * `platform.spec.ts`:
+ *
+ * 1. It exceeds every Recipe's `maxTurns`. A chunk that yields always advanced at
+ *    least one turn, so a run takes at most `maxTurns` chunks however short they
+ *    are — and they do get short, because `CHUNK_SOFT_MS` and progress events both
+ *    end one early. Counting turns is what makes the bound survive that; any
+ *    estimate of turns-per-chunk would not, since neither of those two is
+ *    predictable.
+ * 2. The worst-case step product stays under {@link STEPS_PER_INSTANCE}.
+ */
+export declare const MAX_CHUNKS_PER_BRANCH = 40;
+/**
+ * What a step holding a model call or a container command configures instead of
+ * inheriting Workflows' defaults. Both defaults were measured wrong for this
+ * workload.
+ *
+ * **`timeout`.** The default is ten minutes. A step here holds a model call and
+ * its provider retries, or a container command running a project's test suite;
+ * neither fits in ten minutes reliably, and neither uses meaningful CPU while it
+ * waits. Left inherited, that default silently became the ceiling
+ * {@link CHUNK_SOFT_MS} was sized against.
+ *
+ * **`retries`.** The default is five attempts with exponential backoff from ten
+ * seconds. Against a fault that is not transient — a severed Durable Object stub
+ * — that produced five failures in under 10ms each, spread across 160 seconds of
+ * backoff that bought nothing. Three attempts still cover a genuinely transient
+ * fault, since the model call has its own provider-level retry underneath this,
+ * and a flat five-second delay stops a fast permanent failure being paid for at
+ * exponential rates.
+ *
+ * Here rather than in `/round` because the agent that most needs it may not be a
+ * round agent: a single-inference agent runs one model call in one step and has
+ * the same two problems, and importing this from `/round` would put the whole
+ * delegation engine in its bundle.
+ *
+ * For the **short** bookkeeping steps — `working`, `complete`, `notify` and
+ * friends — the defaults are fine and a shared config would only hide that.
+ */
+export declare const CHUNK_STEP: WorkflowStepConfig;