@loopingai/core 0.7.1 → 0.8.1

package/README.md

@@ -229,7 +229,6 @@ not drag in the A2A adapter, and the test harness cannot reach a production bund
 | `@loopingai/core/agent`        | session, history, models + Workers AI, inference, budget, control tools     |
 | `@loopingai/core/host`         | `LoopingAgent` — the Durable Object body — and `PluginHost`                 |
 | `@loopingai/core/round`        | the delegating round loop: `RoundAgentBase`, `runHandleTask`, `runTurn`     |
-| `@loopingai/core/anthropic`    | Claude as a second provider — _optional peer on `@anthropic-ai/sdk`_        |
 | `@loopingai/core/subtasks`     | delegation types, decomposition, the `delegate` tool                        |
 | `@loopingai/core/subagent`     | `RecipeSubagentBase`, resumable runs, fingerprinting, workspace             |
 | `@loopingai/core/db`           | `AgentDB`, `notify_tasks` + `subtasks` schema, migrations, `PluginStore`    |
@@ -271,8 +270,9 @@ performs. A gateway pins the card's `kid` + `jku` on first registration
 
 ### Calling out, and knowing your own origin
 
-The same key proves this agent to services that are not the gateway — an inference
-proxy, another agent. `signCallerToken` mints the short-lived token for that: `iss` is
+The same key proves this agent to services that are not the gateway — another agent,
+or any service that verifies against the published JWKS. `signCallerToken` mints the
+short-lived token for that: `iss` is
 this deployment's origin, `jku` is derived from it, and the audience is normalized to a
 bare origin because the far side compares it byte-for-byte.
 
@@ -499,7 +499,6 @@ await withDb("accepts a turn once", async (db) => {
 - **Bindings:** `AI`, one Durable Object, one Workflow
 - **Secrets:** `A2A_SIGNING_KEY`, `GATEWAY_ORIGINS`
 - **Peers, never bundled:** `agents`, `ai`, `workers-ai-provider`
-- **Optional peer:** `@anthropic-ai/sdk`, needed only by `@loopingai/core/anthropic`
 
 That last point is not stylistic: two copies of `agents` in one Worker breaks the
 `Session` / `SessionMessage` types and every `instanceof`. For local development

package/dist/a2a/self-origin.d.ts

@@ -15,10 +15,10 @@
  * The obvious answer is a `SELF_ORIGIN` secret, and it is the wrong one. It
  * restates a value the request already carries, and it has to be kept
  * byte-identical by hand with the origin allowlist on the far side, in every
- * environment, forever. Both siblings that tried it took it back out:
- * `looping-anthropic-proxy` deleted `PROXY_AUDIENCE` in favour of `url.origin`,
- * and `looping-gateway` discovers its own origin from the first
- * signature-verified request rather than being told.
+ * environment, forever. Every sibling that tried it took it back out —
+ * `looping-gateway` discovers its own origin from the first signature-verified
+ * request rather than being told, and a verifying Worker that once carried a
+ * configured audience replaced it with `url.origin`.
  *
  * ## Where the value comes from
  *
@@ -51,9 +51,9 @@
  * The cost of pinning is what an agent does not have: several identities. An
  * agent has one endpoint — the one its card advertises, the one a gateway calls
  * and a verifier allowlists — so there is nothing to follow. Note the asymmetry
- * with `looping-anthropic-proxy`, which derives its audience per request and
- * refuses to cache: a *verifier* must accept every hostname it answers on, while
- * a *signer* needs one stable identity.
+ * with a *verifier*, which derives the audience it expects per request and must
+ * not cache it: a verifier has to accept every hostname it answers on, while a
+ * signer needs one stable identity.
  *
  * Nothing is persisted, which is what keeps a pin from outliving its truth. An
  * isolate is fresh on every `wrangler deploy` and recycles on its own, so a moved

package/dist/a2a/self-origin.js

@@ -15,10 +15,10 @@
  * The obvious answer is a `SELF_ORIGIN` secret, and it is the wrong one. It
  * restates a value the request already carries, and it has to be kept
  * byte-identical by hand with the origin allowlist on the far side, in every
- * environment, forever. Both siblings that tried it took it back out:
- * `looping-anthropic-proxy` deleted `PROXY_AUDIENCE` in favour of `url.origin`,
- * and `looping-gateway` discovers its own origin from the first
- * signature-verified request rather than being told.
+ * environment, forever. Every sibling that tried it took it back out —
+ * `looping-gateway` discovers its own origin from the first signature-verified
+ * request rather than being told, and a verifying Worker that once carried a
+ * configured audience replaced it with `url.origin`.
  *
  * ## Where the value comes from
  *
@@ -51,9 +51,9 @@
  * The cost of pinning is what an agent does not have: several identities. An
  * agent has one endpoint — the one its card advertises, the one a gateway calls
  * and a verifier allowlists — so there is nothing to follow. Note the asymmetry
- * with `looping-anthropic-proxy`, which derives its audience per request and
- * refuses to cache: a *verifier* must accept every hostname it answers on, while
- * a *signer* needs one stable identity.
+ * with a *verifier*, which derives the audience it expects per request and must
+ * not cache it: a verifier has to accept every hostname it answers on, while a
+ * signer needs one stable identity.
  *
  * Nothing is persisted, which is what keeps a pin from outliving its truth. An
  * isolate is fresh on every `wrangler deploy` and recycles on its own, so a moved

package/dist/agent/errors.d.ts

@@ -6,7 +6,7 @@
  * any particular one exists. `nonRecoverableKind` in
  * {@link file://./inference.ts inference.ts} keys on this file, so a provider
  * written outside core — the thing `ModelRuntimeFactory` exists to make cheap —
- * gets the same handling as `agent/anthropic` with no change to core.
+ * gets the same handling as core's own, with no change to core.
  *
  * ## Why a third classification was needed at all
  *
@@ -24,26 +24,26 @@
 /**
  * Who refused the request, when a `401` came back.
  *
- * There can be up to three authorities on the path, each with its own
- * credential: the AI Gateway (`cf-aig-authorization`), an optional intermediary
- * a deployment puts between the gateway and the provider (`"proxy"`), and the
- * model provider itself (`Authorization`). They fail with the same status code
- * and completely different remedies, so a rejection that does not say which one
- * it was sends an operator to rotate the wrong secret — which is exactly what
- * happened before this existed.
- *
- * `"proxy"` is the odd one out: it is generally *not* a secret to rotate. An
- * intermediary that mints its caller credential per request fails for reasons
- * upstream of any stored secret — configuration drift, a rotated signing key,
- * clock skew — so the remedy is to look, not to rotate. Core recognises no
- * particular intermediary; a deployment that has one supplies its own classifier
- * (see `AnthropicModelDeps.classifyAuthFailure`).
+ * Two authorities sit on the path, each with its own credential: the AI Gateway
+ * (`cf-aig-authorization`) and the model provider itself (`Authorization`). They
+ * fail with the same status code and have completely different remedies, so a
+ * rejection that does not say which one it was sends an operator to rotate the
+ * wrong secret — which is exactly what happened before this existed.
  *
  * `"unknown"` is a real answer and the default. Guessing `"provider"` for an
  * unrecognised body is how the misdiagnosis happens; saying "one of these, here
  * is how to check each" is worse copy and better information.
+ *
+ * A third arm, `"proxy"`, named an optional intermediary between the two — the
+ * shape where a deployment terminates the gateway's request at its own Worker to
+ * attach a credential. It was removed in 0.8.0 with the deployment that had one.
+ * If you build that topology again, the honest classification for its refusals
+ * is `"unknown"` until you widen this union, because the remedy genuinely
+ * differs: an intermediary minting its caller credential per request fails for
+ * reasons upstream of any stored secret, so the fix is to look rather than to
+ * rotate.
  */
-export type CredentialRejectedBy = "provider" | "gateway" | "proxy" | "unknown";
+export type CredentialRejectedBy = "provider" | "gateway" | "unknown";
 /**
  * A credential on the path to the model was rejected (HTTP 401 / 403).
  *

package/dist/agent/errors.js

@@ -6,7 +6,7 @@
  * any particular one exists. `nonRecoverableKind` in
  * {@link file://./inference.ts inference.ts} keys on this file, so a provider
  * written outside core — the thing `ModelRuntimeFactory` exists to make cheap —
- * gets the same handling as `agent/anthropic` with no change to core.
+ * gets the same handling as core's own, with no change to core.
  *
  * ## Why a third classification was needed at all
  *

package/dist/agent/inference.d.ts

@@ -49,14 +49,16 @@ export declare function isTransientAiError(err: unknown): boolean;
  * - `gateway-credential` — the gateway *in front of* the provider rejected the
  *   request, which the provider therefore never saw. Rotate the gateway's token
  *   instead; the model credential is very likely fine.
- * - `proxy-credential` — an intermediary between the gateway and the provider
- *   rejected the caller. Notably **not** a token to rotate: the credential it
- *   refused is minted per request, so the fault is upstream of the secret —
- *   configuration drift, a rotated signing key, or clock skew.
  * - `unknown-credential` — a `401`/`403` matching none of the shapes. Says so,
  *   rather than picking one and sending an operator to rotate a working secret.
+ *
+ * A fourth, `proxy-credential`, was removed in 0.8.0 along with
+ * {@link file://./errors.ts CredentialRejectedBy}'s `"proxy"` arm. Adding a kind
+ * back is a breaking change for every consumer, because the `Record` they map it
+ * with is total — which is the property that makes a new kind impossible to
+ * ignore, and the reason to remove one rather than leave it unreachable.
  */
-export type NonRecoverableKind = "credential" | "gateway-credential" | "proxy-credential" | "unknown-credential";
+export type NonRecoverableKind = "credential" | "gateway-credential" | "unknown-credential";
 /**
  * Why a round ended with no answer — one terminal status, two situations.
  *

package/dist/agent/inference.js

@@ -80,8 +80,6 @@ export function nonRecoverableKind(err) {
             return "credential";
         case "gateway":
             return "gateway-credential";
-        case "proxy":
-            return "proxy-credential";
         // Includes an error that crossed a realm boundary carrying no `source` at
         // all: `isInstance` is structural, so that is reachable, and "unknown" is
         // the honest reading of it.

package/dist/agent/model.d.ts

@@ -10,11 +10,17 @@ import type { ModelConfig } from "../config.js";
  * more than a `LanguageModel` from `ai`. It never learns which provider produced
  * it.
  *
- * The implementations are siblings under `agent/`, one directory each:
- * {@link file://./workers-ai/index.ts `./workers-ai`} is core's default, and
- * {@link file://./anthropic/index.ts `./anthropic`} is Claude behind an optional
- * peer dependency. A third provider is a third directory exporting one
- * {@link ModelRuntimeFactory}; nothing here has to change to admit it.
+ * Core ships exactly one implementation —
+ * {@link file://./workers-ai/index.ts `./workers-ai`} — as a sibling directory
+ * under `agent/`. A second provider is a second directory exporting one
+ * {@link ModelRuntimeFactory}, and nothing here has to change to admit it;
+ * a consumer can equally supply one from outside the package, which is the
+ * point of the seam.
+ *
+ * There was a `./anthropic` sibling until 0.8.0 — a hand-written Messages API
+ * adapter behind an optional peer dependency. It was removed with the only
+ * deployment that used it. Nothing about this contract changed when it went,
+ * which is the strongest thing that can be said for the contract.
  *
  * Which is why this file has no runtime imports at all. The Workers AI factory
  * used to live in it, and a contract that ships one implementation inline reads

package/dist/agent/workers-ai/index.d.ts

@@ -1,23 +1,23 @@
 /**
  * Workers AI — core's default model provider.
  *
- * A sibling of {@link file://../anthropic/index.ts `./anthropic`}, and like it a
- * provider rather than a capability: it ships no tools, no prompt copy and no
+ * A provider rather than a capability: it ships no tools, no prompt copy and no
  * policy; it satisfies {@link file://../model.ts ModelRuntime} and stops.
  *
- * It differs from that sibling in two ways, both deliberate:
+ * Two things about its shape are worth stating, because both look like
+ * omissions:
  *
  * **No `LanguageModel` adapter.** `workers-ai-provider` ships one, so this
- * directory is a factory and nothing else. The Anthropic side hand-builds the
- * adapter — the prompt mapping, the cache control, the error taxonomy — which is
- * why it is five files and this is one.
+ * directory is a factory and nothing else — one file rather than the five a
+ * hand-written adapter costs (a prompt mapping, a cache-control policy, an
+ * error taxonomy). That is what makes it the cheap default.
  *
- * **No package subpath.** `/anthropic` has one because `@anthropic-ai/sdk` is an
- * *optional* peer and an agent on Workers AI must not pay for a provider it
- * never calls. That argument does not apply here: `workers-ai-provider` is a
- * required peer, and this is the default every un-overridden seam reaches
- * through `LoopingAgent` itself, so it is in every consumer's module graph
- * already. It is exported from `@loopingai/core/agent` — one symbol, one import
- * path.
+ * **No package subpath.** `workers-ai-provider` is a *required* peer and this is
+ * the default every un-overridden seam reaches through `LoopingAgent` itself, so
+ * it is in every consumer's module graph already and a subpath would buy
+ * nothing. It is exported from `@loopingai/core/agent` — one symbol, one import
+ * path. A provider behind an *optional* peer would want its own subpath instead,
+ * so that an agent never calling it does not pay for it; `./anthropic` was one
+ * until 0.8.0.
  */
 export { createWorkersAIModelRuntime, workersAIModels, type WorkersAIRuntimeDeps } from "./runtime.js";

package/dist/agent/workers-ai/index.js

@@ -1,23 +1,23 @@
 /**
  * Workers AI — core's default model provider.
  *
- * A sibling of {@link file://../anthropic/index.ts `./anthropic`}, and like it a
- * provider rather than a capability: it ships no tools, no prompt copy and no
+ * A provider rather than a capability: it ships no tools, no prompt copy and no
  * policy; it satisfies {@link file://../model.ts ModelRuntime} and stops.
  *
- * It differs from that sibling in two ways, both deliberate:
+ * Two things about its shape are worth stating, because both look like
+ * omissions:
  *
  * **No `LanguageModel` adapter.** `workers-ai-provider` ships one, so this
- * directory is a factory and nothing else. The Anthropic side hand-builds the
- * adapter — the prompt mapping, the cache control, the error taxonomy — which is
- * why it is five files and this is one.
+ * directory is a factory and nothing else — one file rather than the five a
+ * hand-written adapter costs (a prompt mapping, a cache-control policy, an
+ * error taxonomy). That is what makes it the cheap default.
  *
- * **No package subpath.** `/anthropic` has one because `@anthropic-ai/sdk` is an
- * *optional* peer and an agent on Workers AI must not pay for a provider it
- * never calls. That argument does not apply here: `workers-ai-provider` is a
- * required peer, and this is the default every un-overridden seam reaches
- * through `LoopingAgent` itself, so it is in every consumer's module graph
- * already. It is exported from `@loopingai/core/agent` — one symbol, one import
- * path.
+ * **No package subpath.** `workers-ai-provider` is a *required* peer and this is
+ * the default every un-overridden seam reaches through `LoopingAgent` itself, so
+ * it is in every consumer's module graph already and a subpath would buy
+ * nothing. It is exported from `@loopingai/core/agent` — one symbol, one import
+ * path. A provider behind an *optional* peer would want its own subpath instead,
+ * so that an agent never calling it does not pay for it; `./anthropic` was one
+ * until 0.8.0.
  */
 export { createWorkersAIModelRuntime, workersAIModels } from "./runtime.js";

package/dist/config.d.ts

@@ -27,21 +27,6 @@ export interface ModelConfig {
     fallbackChatModelId: string;
     /** AI Gateway slug; `"default"` auto-provisions on first request. */
     aiGatewayId: string;
-    /**
-     * The segment after the gateway slug in `.../{gateway}/{provider}` — either a
-     * provider-native path like `"anthropic"` or a
-     * [custom provider](https://developers.cloudflare.com/ai-gateway/configuration/custom-providers/)
-     * slug. Core never reads it; a `ModelRuntime` that builds its own base URL
-     * does.
-     *
-     * Config rather than a literal at that call site because the parent agent and
-     * its subagent facet resolve their config independently, and a value that
-     * drifts between them routes delegated subtasks through a different provider
-     * than the round that delegated them — silently, since both satisfy
-     * `ModelRuntime`. Which path to pick, and why, belongs with the agent that
-     * picks it.
-     */
-    aiGatewayProvider: string;
     /**
      * Output-token ceiling for every chat call. Left unset, the binding applies a
      * per-model default which a reasoning model spends on `reasoning_content`
@@ -71,9 +56,9 @@ export interface ModelConfig {
      * The AI SDK does the waiting, and it does it properly:
      * `retryWithExponentialBackoffRespectingRetryHeaders` honours `retry-after-ms`
      * and `retry-after` and falls back to exponential backoff. It only fires for
-     * an `APICallError` carrying `isRetryable`, which is why
-     * {@link file://./agent/anthropic/language-model.ts} maps provider errors into
-     * that shape rather than rethrowing them raw.
+     * an `APICallError` carrying `isRetryable`, so a provider written outside core
+     * has to map its errors into that shape rather than rethrowing them raw, or
+     * none of this fires for it.
      *
      * Bounded at 4 by `resolveConfig`. The retries happen *inside*
      * `step.do("turn:<round>")`, and the SDK caps a single honoured `retry-after`

package/dist/config.js

@@ -32,10 +32,6 @@ export const DEFAULT_CORE_CONFIG = {
         // Not a model: an AI Gateway slug, and `"default"` is Cloudflare's own
         // auto-provision behaviour rather than a choice core is making for anyone.
         aiGatewayId: "default",
-        // The provider-native Anthropic endpoint, which is what a deployment with
-        // no custom provider registered has. Agents that must own the credential
-        // themselves override this with their `custom-*` slug.
-        aiGatewayProvider: "anthropic",
         maxOutputTokens: 16_384,
         reasoningEffort: "medium",
         // Two, which is the AI SDK's own default and enough to ride out the kind of

package/dist/host/agent.d.ts

@@ -118,12 +118,11 @@ export declare abstract class LoopingAgent<TEnv extends Cloudflare.Env & AiEnv &
      * a trap that only shows up as a performance bug. This is called once.
      *
      * `ModelRuntime` is the whole contract: return anything satisfying it and
-     * every loop in core keeps working unchanged. Core ships two implementations,
-     * one directory each — {@link file://../agent/workers-ai/index.ts
-     * `agent/workers-ai`} (the default below) and `@loopingai/core/anthropic` —
-     * and a third provider is a third directory exporting one
-     * {@link file://../agent/model.ts ModelRuntimeFactory}, not a change to
-     * anything on this path.
+     * every loop in core keeps working unchanged. Core ships one implementation,
+     * {@link file://../agent/workers-ai/index.ts `agent/workers-ai`} (the default
+     * below); a second provider is one more
+     * {@link file://../agent/model.ts ModelRuntimeFactory}, defined here or in the
+     * consumer, not a change to anything on this path.
      *
      * Takes the resolved {@link ModelConfig} rather than reading `this.config`, so
      * that this signature matches

package/dist/host/agent.js

@@ -125,12 +125,11 @@ export class LoopingAgent extends Agent {
      * a trap that only shows up as a performance bug. This is called once.
      *
      * `ModelRuntime` is the whole contract: return anything satisfying it and
-     * every loop in core keeps working unchanged. Core ships two implementations,
-     * one directory each — {@link file://../agent/workers-ai/index.ts
-     * `agent/workers-ai`} (the default below) and `@loopingai/core/anthropic` —
-     * and a third provider is a third directory exporting one
-     * {@link file://../agent/model.ts ModelRuntimeFactory}, not a change to
-     * anything on this path.
+     * every loop in core keeps working unchanged. Core ships one implementation,
+     * {@link file://../agent/workers-ai/index.ts `agent/workers-ai`} (the default
+     * below); a second provider is one more
+     * {@link file://../agent/model.ts ModelRuntimeFactory}, defined here or in the
+     * consumer, not a change to anything on this path.
      *
      * Takes the resolved {@link ModelConfig} rather than reading `this.config`, so
      * that this signature matches

package/dist/job/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `@loopingai/core/job` — a long job a Durable Object owns through its alarm.
+ *
+ * **The sibling of `@loopingai/core/alarm`, and the pairing is the point.**
+ * `WakeMap` owns *when* an object wakes; this owns *what a job owes on waking*.
+ * Neither depends on the other's reason for existing, and both are useful to a
+ * plain `DurableObject` rather than only to a `LoopingAgent` — which is why they
+ * are subpaths and not part of the agent machinery.
+ *
+ * **Mechanism only.** Nothing here knows what a job *does*: no command, no
+ * container, no filesystem, no vendor library. A consumer supplies the handle
+ * and the meaning; this supplies the four rules that are wrong in the same way
+ * every time — arming before the work starts, one job at a time, a drain that
+ * can outlive its job, and a job nobody is draining. See {@link JobLifecycle}.
+ *
+ * Deliberately **not** called `task`. Core already has a `Task` — the A2A one,
+ * with its own lifecycle, its own guarded writes and its own table — and two
+ * unrelated meanings in one namespace is a cost paid forever by every reader.
+ */
+export { isRearmable, isRunning, type DoneJob, type FailedJob, type IdleJob, type JobState, type RunningJob, type SkippedJob } from "./state.js";
+export { JobLifecycle, type JobContext, type JobHandle, type JobLifecycleOptions, type JobResult } from "./lifecycle.js";

package/dist/job/index.js

@@ -0,0 +1,21 @@
+/**
+ * `@loopingai/core/job` — a long job a Durable Object owns through its alarm.
+ *
+ * **The sibling of `@loopingai/core/alarm`, and the pairing is the point.**
+ * `WakeMap` owns *when* an object wakes; this owns *what a job owes on waking*.
+ * Neither depends on the other's reason for existing, and both are useful to a
+ * plain `DurableObject` rather than only to a `LoopingAgent` — which is why they
+ * are subpaths and not part of the agent machinery.
+ *
+ * **Mechanism only.** Nothing here knows what a job *does*: no command, no
+ * container, no filesystem, no vendor library. A consumer supplies the handle
+ * and the meaning; this supplies the four rules that are wrong in the same way
+ * every time — arming before the work starts, one job at a time, a drain that
+ * can outlive its job, and a job nobody is draining. See {@link JobLifecycle}.
+ *
+ * Deliberately **not** called `task`. Core already has a `Task` — the A2A one,
+ * with its own lifecycle, its own guarded writes and its own table — and two
+ * unrelated meanings in one namespace is a cost paid forever by every reader.
+ */
+export { isRearmable, isRunning } from "./state.js";
+export { JobLifecycle } from "./lifecycle.js";

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;
+    };
+}