@loopingai/core 0.6.0 → 0.7.1

package/README.md

@@ -39,11 +39,12 @@ optional is a plugin. Anything opinionated belongs to your app.
 npx looping-keys
 ```
 
-Set the private JWK as `A2A_SIGNING_KEY` (`.dev.vars` locally, `wrangler secret put`
-when deployed) and the origins you accept calls from as `GATEWAY_ORIGINS`:
+Set the private JWK as `A2A_SIGNING_KEY` (`.env` locally; `wrangler deploy
+--secrets-file .env` or `wrangler secret put` when deployed) and the origins you accept
+calls from as `GATEWAY_ORIGINS`:
 
 ```ini
-# .dev.vars
+# .env
 A2A_SIGNING_KEY={"crv":"Ed25519","d":"…","x":"…","kty":"OKP","kid":"a2a-2026-08-01"}
 GATEWAY_ORIGINS=["https://gateway.example.com"]
 ```
@@ -268,6 +269,38 @@ makes the served document a fixed point under the repeated decoding a verifier
 performs. A gateway pins the card's `kid` + `jku` on first registration
 (Trust-On-First-Use).
 
+### 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
+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.
+
+Its `iss` is **not** something to configure. Inside a Durable Object it is:
+
+```ts
+protected override modelRuntime(model: ModelConfig): ModelRuntime {
+  return myProvider(this.env, model, () => this.requireSelfOrigin());
+}
+```
+
+`requireSelfOrigin()` (and `selfOrigin()`, which returns `undefined` instead of
+throwing) answer with the origin core already delivers: the executor computes the
+callback `jku` from `new URL(request.url).origin`, and it rides every turn into the DO
+and on into each subagent facet. A `SELF_ORIGIN` secret only restates that, and has to
+be kept byte-identical with the verifier's allowlist by hand in every environment.
+
+The first turn an instance serves **pins** it, and nothing is persisted. Pinning is
+what makes it safe to read: turns run concurrently in one Durable Object and a
+credential thunk fires several frames below the turn that set the value, so a mutable
+field could hand one turn another's origin. An agent has one endpoint anyway — the one
+its card advertises and a verifier allowlists — and a fresh isolate on deploy re-learns
+it.
+
+It is known **inside a turn or a chunk**: `onStart`, a constructor and a scheduled
+callback all run before any request has said what this deployment is called, and
+`requireSelfOrigin()` throws there saying so.
+
 ---
 
 ## Plugins

package/dist/a2a/caller-token.d.ts

@@ -0,0 +1,44 @@
+export interface CallerTokenOptions {
+    /** This agent's raw private JWK JSON — the same `A2A_SIGNING_KEY` its card is signed with. */
+    signingKey: string;
+    /**
+     * This agent's own origin. It becomes `iss`, and `jku` is derived from it, and
+     * the two must agree: a verifier that accepts a `jku` on a different origin
+     * than `iss` lets one allowlisted origin impersonate another.
+     *
+     * **Not something to configure.** Inside a Durable Object it is
+     * `requireSelfOrigin()` — see {@link file://./self-origin.ts SelfOrigin},
+     * which learns it from the `jku` every turn already carries. A `SELF_ORIGIN`
+     * secret restates what the request path knows and has to be kept
+     * byte-identical with the verifier's allowlist by hand.
+     */
+    issuer: string;
+    /**
+     * Who the token is for. Normalized to a bare origin, because a verifier
+     * typically derives what it expects from `new URL(request.url).origin` and
+     * `jose` compares `aud` byte-for-byte — a trailing slash or a stray path is a
+     * 401 on every request with nothing to catch it. Throws on a value that is not
+     * an absolute URL, which is the right moment for that to fail.
+     */
+    audience: string;
+    /** The identity this agent asserts. */
+    identity: Record<string, unknown>;
+    /** Which tenant of this deployment the token speaks for. */
+    tenant: string;
+    /** Lifetime in seconds. Defaults to 120. */
+    ttlSeconds?: number;
+}
+/**
+ * Sign a short-lived token identifying **this agent as a caller** to another
+ * service that trusts its card key.
+ *
+ * The production sibling of `makeGatewayToken`, which core previously shipped
+ * only from `/testing` — so an agent that had to call out mint-signed had to
+ * hand-write this shape, and every deployment that did so wrote its own subtly
+ * different version of the `iss`/`jku` agreement above.
+ *
+ * Distinct from {@link signCallbackJwt}, which carries **no** claims: that one
+ * proves "the agent you called is calling you back about this task", where this
+ * proves "this is who I am and which tenant I speak for".
+ */
+export declare function signCallerToken(options: CallerTokenOptions): Promise<string>;

package/dist/a2a/caller-token.js

@@ -0,0 +1,61 @@
+import { importJWK, SignJWT } from "jose";
+import { A2A_JWS_ALG, IDENTITY_CLAIM, TENANT_CLAIM, jwksUrl } from "@loopingai/a2a-protocol";
+import { parsePrivateJwk } from "./card.js";
+/** Default lifetime: long enough for clock skew, short enough to be worthless from a log. */
+const DEFAULT_TTL_SECONDS = 120;
+/**
+ * `importJWK` does real work and this is on the per-request path.
+ *
+ * Keyed by the raw secret so a rotated key invalidates the entry rather than
+ * being ignored for the life of the isolate.
+ */
+let cached;
+async function signingKeyFor(raw) {
+    if (cached?.raw === raw)
+        return cached;
+    const jwk = parsePrivateJwk(raw);
+    // Not cast to `CryptoKey`: `importJWK` returns a union, and asserting the
+    // branch would be a lie the day this key is anything but Ed25519.
+    const key = await importJWK(jwk, A2A_JWS_ALG);
+    cached = { raw, key, kid: jwk.kid };
+    return cached;
+}
+/**
+ * Sign a short-lived token identifying **this agent as a caller** to another
+ * service that trusts its card key.
+ *
+ * The production sibling of `makeGatewayToken`, which core previously shipped
+ * only from `/testing` — so an agent that had to call out mint-signed had to
+ * hand-write this shape, and every deployment that did so wrote its own subtly
+ * different version of the `iss`/`jku` agreement above.
+ *
+ * Distinct from {@link signCallbackJwt}, which carries **no** claims: that one
+ * proves "the agent you called is calling you back about this task", where this
+ * proves "this is who I am and which tenant I speak for".
+ */
+export async function signCallerToken(options) {
+    const { key, kid } = await signingKeyFor(options.signingKey);
+    // Normalized for the same reason `audience` is, and it has to happen before
+    // both uses: `jku` names only the origin, so an `issuer` carrying a trailing
+    // slash or a path would sign an `iss` that disagrees with it — and a verifier
+    // comparing `iss` byte-for-byte against a normalized origin allowlist rejects
+    // the token even though the two URLs share an origin.
+    const issuer = new URL(options.issuer).origin;
+    return new SignJWT({
+        [IDENTITY_CLAIM]: options.identity,
+        [TENANT_CLAIM]: options.tenant
+    })
+        .setProtectedHeader({
+        alg: A2A_JWS_ALG,
+        kid,
+        // Where the far side fetches the public half. A verifier must check this
+        // origin against its own allowlist *before* fetching, which is what stops
+        // a forged token nominating an attacker-controlled JWKS.
+        jku: jwksUrl(issuer)
+    })
+        .setIssuer(issuer)
+        .setAudience(new URL(options.audience).origin)
+        .setIssuedAt()
+        .setExpirationTime(`${options.ttlSeconds ?? DEFAULT_TTL_SECONDS}s`)
+        .sign(key);
+}

package/dist/a2a/deliver.d.ts

@@ -0,0 +1,49 @@
+import type { WorkflowStep } from "cloudflare:workers";
+import { type TurnPushContext } from "./push.js";
+import type { PlainTask } from "./task.js";
+/** What {@link deliverTerminalTask} needs to finish a turn. */
+export interface DeliverTerminalOptions {
+    /** Which Task this is about, and where its callback goes. */
+    push: TurnPushContext;
+    /** The agent's card-signing key, for the callback JWT. */
+    signingKey: string;
+    /**
+     * The guarded write, and **the cancellation check**. Return whether it
+     * applied: `false` must mean the row was already terminal (canceled), which is
+     * what suppresses the callback.
+     *
+     * Resolve any Durable Object stub *inside* this function, never above it — a
+     * stub hoisted out of a step body is a live connection that a replay cannot
+     * reconnect.
+     */
+    saveTask: (task: PlainTask) => Promise<boolean>;
+    /**
+     * Build the terminal Task. Called **inside** the `complete` step so that what
+     * gets notified is exactly what was persisted: building it outside would
+     * re-stamp `new Date()` on every replay and post a Task that differs from the
+     * stored one.
+     */
+    terminal: () => PlainTask;
+    /**
+     * Optional best-effort cleanup, run after the write and before the callback.
+     * An agent with no managed children omits it and no `sweep` step appears.
+     */
+    sweep?: () => Promise<void>;
+}
+/**
+ * Persist a turn's terminal Task, then notify the gateway.
+ *
+ * **The guarded write is the cancellation check.** `saveTask` refuses to write a
+ * terminal state over a `canceled` row and says so, doing that read and write in
+ * one synchronous pass inside the Durable Object. Probing first and saving
+ * second would leave a window — between the two calls, and again between this
+ * step and `notify` — in which a `tasks/cancel` lands and the gateway still
+ * receives a `completed` callback. Keying the notify on "did the write apply"
+ * closes it, and that has already been got wrong once.
+ *
+ * In `/a2a` rather than `/round` because the shape is not a round's: an agent
+ * whose turn is a single inference ends it the same way, and importing this from
+ * `/round` would put the whole delegation engine in a bundle that must not carry
+ * it. Everything it calls already lives here.
+ */
+export declare function deliverTerminalTask(step: WorkflowStep, options: DeliverTerminalOptions): Promise<void>;

package/dist/a2a/deliver.js

@@ -0,0 +1,49 @@
+import { createPushChannel } from "./push.js";
+/**
+ * Persist a turn's terminal Task, then notify the gateway.
+ *
+ * **The guarded write is the cancellation check.** `saveTask` refuses to write a
+ * terminal state over a `canceled` row and says so, doing that read and write in
+ * one synchronous pass inside the Durable Object. Probing first and saving
+ * second would leave a window — between the two calls, and again between this
+ * step and `notify` — in which a `tasks/cancel` lands and the gateway still
+ * receives a `completed` callback. Keying the notify on "did the write apply"
+ * closes it, and that has already been got wrong once.
+ *
+ * In `/a2a` rather than `/round` because the shape is not a round's: an agent
+ * whose turn is a single inference ends it the same way, and importing this from
+ * `/round` would put the whole delegation engine in a bundle that must not carry
+ * it. Everything it calls already lives here.
+ */
+export async function deliverTerminalTask(step, options) {
+    const task = await step.do("complete", async () => {
+        const terminal = options.terminal();
+        return (await options.saveTask(terminal)) ? terminal : null;
+    });
+    if (!task)
+        return;
+    // Caught, not left to propagate: the terminal Task is already durably saved,
+    // so a sweep that still fails once the step's own retries are exhausted must
+    // not block the callback — the gateway is owed its result either way.
+    if (options.sweep) {
+        const sweep = options.sweep;
+        try {
+            await step.do("sweep", async () => {
+                await sweep();
+            });
+        }
+        catch (err) {
+            console.error("[deliver] sweep failed after retries", {
+                taskId: options.push.taskId,
+                err: String(err)
+            });
+        }
+    }
+    // A card-key-signed callback POST. Retried by the step on a non-2xx; the
+    // terminal messageId is deterministic and the gateway is idempotent and
+    // single-use, so retries are safe. If it ultimately fails, the gateway's own
+    // reaction backstop clears the pending marker.
+    await step.do("notify", async () => {
+        await createPushChannel(options.signingKey, options.push).deliver(task);
+    });
+}

package/dist/a2a/index.d.ts

@@ -22,6 +22,9 @@ export { A2A_JWS_ALG, audienceFor, endpointUrl, jwksUrl } from "@loopingai/a2a-p
 export { IDENTITY_CLAIM, TENANT_CLAIM, GatewayAuthError, bearerToken, normalizeGatewayOrigins, verifyGatewayToken, type GatewayIdentity, type VerifyOptions } from "./verify.js";
 export { A2A_RPC_PATH, buildBaseCard, signCard, wireCard, parsePrivateJwk, publicCardJwks, type AgentManifest, type BuildCardOptions, type CardSigningConfig, type WireAgentCard } from "./card.js";
 export { NOTIFICATION_TOKEN_HEADER, buildSubmittedTask, buildWorkingTask, buildCompletedTask, buildFailedTask, buildNoReplyCompletedTask, signCallbackJwt, postNotification } from "./notify.js";
+export { deliverTerminalTask, type DeliverTerminalOptions } from "./deliver.js";
+export { signCallerToken, type CallerTokenOptions } from "./caller-token.js";
+export { SelfOrigin } from "./self-origin.js";
 export { callerContext } from "./caller.js";
 export { createPushChannel, type PushChannel, type TurnPushContext } from "./push.js";
 export { taskStateLabel, type PlainArtifact, type PlainMessage, type PlainPart, type PlainStatus, type PlainTask } from "./task.js";

package/dist/a2a/index.js

@@ -22,6 +22,9 @@ export { A2A_JWS_ALG, audienceFor, endpointUrl, jwksUrl } from "@loopingai/a2a-p
 export { IDENTITY_CLAIM, TENANT_CLAIM, GatewayAuthError, bearerToken, normalizeGatewayOrigins, verifyGatewayToken } from "./verify.js";
 export { A2A_RPC_PATH, buildBaseCard, signCard, wireCard, parsePrivateJwk, publicCardJwks } from "./card.js";
 export { NOTIFICATION_TOKEN_HEADER, buildSubmittedTask, buildWorkingTask, buildCompletedTask, buildFailedTask, buildNoReplyCompletedTask, signCallbackJwt, postNotification } from "./notify.js";
+export { deliverTerminalTask } from "./deliver.js";
+export { signCallerToken } from "./caller-token.js";
+export { SelfOrigin } from "./self-origin.js";
 export { callerContext } from "./caller.js";
 export { createPushChannel } from "./push.js";
 export { taskStateLabel } from "./task.js";

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

@@ -0,0 +1,91 @@
+/**
+ * This deployment's own public origin — learned from the request path, never
+ * configured.
+ *
+ * ## Why an agent needs it at all
+ *
+ * A Worker that only *answers* never needs to know its own name.
+ * {@link file://../worker/index.ts createA2AWorker} derives its audience, its
+ * card and its `jku` from `new URL(request.url).origin`, and none of it outlives
+ * the request. An agent that **calls out** mint-signed does need it:
+ * {@link file://./caller-token.ts signCallerToken} puts it in `iss` and derives
+ * the token's `jku` from it. That call happens inside a Durable Object, where
+ * there is no `Request` — which is the whole difficulty.
+ *
+ * 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.
+ *
+ * ## Where the value comes from
+ *
+ * Core already sends the origin into the Durable Object on every turn, one field
+ * short of this use. `A2AExecutor` computes `jku` as `${origin}${jwksPath}` and
+ * it rides {@link file://./push.ts TurnPushContext} through the Workflow into
+ * `runTaskTurn` and `executeSubtaskChunk`.
+ *
+ * That is the same origin `signCallerToken` needs, and not by coincidence: a
+ * caller token's `jku` **must** be the JWKS the verifier fetches, and `iss` must
+ * agree with it — the third check in {@link file://./verify.ts verify.ts}. An
+ * origin derived from anywhere else is exactly what that check exists to catch,
+ * so deriving it from the `jku` core already serves makes the agreement
+ * structural instead of clerical.
+ *
+ * ## Pinned on the first turn, and in memory
+ *
+ * The first origin an isolate is told wins, and later ones are ignored. That is
+ * not laziness about staleness — it is what makes the value safe to *read*.
+ *
+ * A Durable Object's input gate stays open across a non-storage await, and this
+ * package runs concurrent RPCs into one object by design (`round/workflow.ts`
+ * runs a round's branches under `Promise.all`). Mutable instance state can
+ * therefore change while a turn is awaiting a model call, and the credential
+ * thunks that read this are lazy — they run several frames below the turn, when
+ * the client is built. Pinned, the field is immutable after its first write, so
+ * every concurrent reader in the isolate gets the same string and no turn can
+ * sign as another turn's origin.
+ *
+ * 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.
+ *
+ * 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
+ * deployment re-learns its origin from the next turn it serves.
+ */
+export declare class SelfOrigin {
+    private observed?;
+    /**
+     * Offer the origin of an absolute URL seen on the request path — a `jku`, an
+     * endpoint, or a bare origin. Only `.origin` is kept, so a path or a trailing
+     * slash cannot reach a token claim.
+     *
+     * **The first usable value wins**; every later call is a no-op, including one
+     * naming a different origin. Called at each RPC entry and again when the push
+     * channel is built, so most calls are already no-ops — but the reason for the
+     * pin is the read side, not the write side. See the note above the class.
+     *
+     * Silently ignores anything unusable (absent, relative, or a scheme that has
+     * no meaningful origin), and an unusable value never pins: the parse comes
+     * first and the field is assigned only on success. This runs at the top of a
+     * turn, where a diagnostic value must never be the thing that fails it; the
+     * throw belongs at {@link require}, where something actually wanted the value.
+     */
+    note(url: string | undefined): void;
+    /** The pinned origin, or `undefined` when nothing has carried one yet. */
+    peek(): string | undefined;
+    /**
+     * The pinned origin, for a caller that cannot proceed without it.
+     *
+     * Throws naming the timing, because that is what the mistake always is: the
+     * value arrives with a turn, so `onStart`, a constructor and a scheduled
+     * callback all run before any request has said what this deployment is called.
+     */
+    require(): string;
+}

package/dist/a2a/self-origin.js

@@ -0,0 +1,114 @@
+/**
+ * This deployment's own public origin — learned from the request path, never
+ * configured.
+ *
+ * ## Why an agent needs it at all
+ *
+ * A Worker that only *answers* never needs to know its own name.
+ * {@link file://../worker/index.ts createA2AWorker} derives its audience, its
+ * card and its `jku` from `new URL(request.url).origin`, and none of it outlives
+ * the request. An agent that **calls out** mint-signed does need it:
+ * {@link file://./caller-token.ts signCallerToken} puts it in `iss` and derives
+ * the token's `jku` from it. That call happens inside a Durable Object, where
+ * there is no `Request` — which is the whole difficulty.
+ *
+ * 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.
+ *
+ * ## Where the value comes from
+ *
+ * Core already sends the origin into the Durable Object on every turn, one field
+ * short of this use. `A2AExecutor` computes `jku` as `${origin}${jwksPath}` and
+ * it rides {@link file://./push.ts TurnPushContext} through the Workflow into
+ * `runTaskTurn` and `executeSubtaskChunk`.
+ *
+ * That is the same origin `signCallerToken` needs, and not by coincidence: a
+ * caller token's `jku` **must** be the JWKS the verifier fetches, and `iss` must
+ * agree with it — the third check in {@link file://./verify.ts verify.ts}. An
+ * origin derived from anywhere else is exactly what that check exists to catch,
+ * so deriving it from the `jku` core already serves makes the agreement
+ * structural instead of clerical.
+ *
+ * ## Pinned on the first turn, and in memory
+ *
+ * The first origin an isolate is told wins, and later ones are ignored. That is
+ * not laziness about staleness — it is what makes the value safe to *read*.
+ *
+ * A Durable Object's input gate stays open across a non-storage await, and this
+ * package runs concurrent RPCs into one object by design (`round/workflow.ts`
+ * runs a round's branches under `Promise.all`). Mutable instance state can
+ * therefore change while a turn is awaiting a model call, and the credential
+ * thunks that read this are lazy — they run several frames below the turn, when
+ * the client is built. Pinned, the field is immutable after its first write, so
+ * every concurrent reader in the isolate gets the same string and no turn can
+ * sign as another turn's origin.
+ *
+ * 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.
+ *
+ * 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
+ * deployment re-learns its origin from the next turn it serves.
+ */
+export class SelfOrigin {
+    observed;
+    /**
+     * Offer the origin of an absolute URL seen on the request path — a `jku`, an
+     * endpoint, or a bare origin. Only `.origin` is kept, so a path or a trailing
+     * slash cannot reach a token claim.
+     *
+     * **The first usable value wins**; every later call is a no-op, including one
+     * naming a different origin. Called at each RPC entry and again when the push
+     * channel is built, so most calls are already no-ops — but the reason for the
+     * pin is the read side, not the write side. See the note above the class.
+     *
+     * Silently ignores anything unusable (absent, relative, or a scheme that has
+     * no meaningful origin), and an unusable value never pins: the parse comes
+     * first and the field is assigned only on success. This runs at the top of a
+     * turn, where a diagnostic value must never be the thing that fails it; the
+     * throw belongs at {@link require}, where something actually wanted the value.
+     */
+    note(url) {
+        if (this.observed || !url)
+            return;
+        let parsed;
+        try {
+            parsed = new URL(url);
+        }
+        catch {
+            return;
+        }
+        if (parsed.protocol !== "https:" && parsed.protocol !== "http:")
+            return;
+        this.observed = parsed.origin;
+    }
+    /** The pinned origin, or `undefined` when nothing has carried one yet. */
+    peek() {
+        return this.observed;
+    }
+    /**
+     * The pinned origin, for a caller that cannot proceed without it.
+     *
+     * Throws naming the timing, because that is what the mistake always is: the
+     * value arrives with a turn, so `onStart`, a constructor and a scheduled
+     * callback all run before any request has said what this deployment is called.
+     */
+    require() {
+        if (!this.observed) {
+            throw new Error("this deployment's own origin is not known on this instance yet: it is " +
+                "learned from the `jku` that arrives with every turn, so it is " +
+                "available inside a turn or a subtask chunk — not from onStart, a " +
+                "constructor or a scheduled callback");
+        }
+        return this.observed;
+    }
+}

package/dist/alarm/index.d.ts

@@ -0,0 +1,77 @@
+/**
+ * `@loopingai/core/alarm` — many deadlines over a Durable Object's one alarm.
+ *
+ * A Durable Object has exactly **one** alarm, and an object that needs to wake
+ * for more than one reason cannot simply call `setAlarm` from each of them: the
+ * last writer silently wins, and whatever the loser was waiting on never
+ * happens. {@link WakeMap} is the fix — one storage row holding every pending
+ * intent, and the only thing in a DO that calls `setAlarm`.
+ *
+ * **Its own subpath, deliberately.** This is useful to a plain `DurableObject`,
+ * not only to a {@link LoopingAgent}, so it must be importable without pulling
+ * the agent machinery into a bundle.
+ *
+ * **Why not `Agent.schedule()`.** The `agents` SDK has the same mechanism, but
+ * sells it only as a method on `Agent`: adopting it means the object becomes an
+ * `Agent`, whose constructor creates `cf_agents_state`, `cf_agents_mcp_servers`
+ * and `cf_agents_queues` in that object's SQLite, builds an `MCPClientManager`,
+ * and prototype-patches every public method for tracing. For an object whose
+ * SQLite is something else already — a container's filesystem, say — that is a
+ * large import for a small one. `agents/schedule` is not an alternative: it is a
+ * prompt and a zod schema for parsing natural-language dates, not alarm
+ * machinery.
+ *
+ * This owns *when* an object wakes. What it owes on waking is the object's own:
+ * `alarm()` reads {@link WakeMap.due} and dispatches.
+ */
+/** One scheduled wake-up. */
+export interface WakeIntent {
+    /** Why we are waking. Namespace it, e.g. `sync-retry:container-shell`. */
+    key: string;
+    /** Epoch ms at which this intent becomes due. */
+    notBefore: number;
+    /** Retry counter, for the intents that carry one. */
+    attempt?: number;
+}
+/** The single storage row holding every intent. Small, and written atomically. */
+export declare const WAKE_KEY = "wake";
+/** How far out {@link WakeMap.repair} re-arms when the handler itself failed. */
+export declare const WAKE_REPAIR_MS = 60000;
+export declare class WakeMap {
+    #private;
+    constructor(storage: DurableObjectStorage);
+    /**
+     * Every pending intent, as a **null-prototype** dictionary rebuilt from own
+     * entries only.
+     *
+     * {@link WakeIntent.key} is a caller-supplied string, so an ordinary object
+     * literal would let three of them misbehave: `get("toString")` would return an
+     * inherited function rather than `undefined`, `clear("constructor")` would
+     * treat a key it never held as present, and `set` on `"__proto__"` would hit
+     * `Object.prototype`'s setter and change the prototype instead of storing the
+     * intent. With no prototype there is nothing to inherit and nothing to poison,
+     * and every string round-trips as an ordinary key.
+     */
+    all(): Promise<Record<string, WakeIntent>>;
+    get(key: string): Promise<WakeIntent | undefined>;
+    set(intent: WakeIntent): Promise<void>;
+    clear(key: string): Promise<void>;
+    /** Every intent whose time has come, earliest first. */
+    due(now: number): Promise<WakeIntent[]>;
+    /**
+     * Point the alarm at the earliest deadline.
+     *
+     * Only ever moved **earlier**, never later: an alarm that fires too soon finds
+     * nothing due, re-arms, and costs one wake-up, whereas an alarm pushed later
+     * by a coincidental write silently delays whatever was already waiting. When
+     * no intents remain the alarm is deleted outright, so an idle object does not
+     * wake on a schedule it has no use for.
+     */
+    rearm(): Promise<void>;
+    /**
+     * Re-arm shortly, for when the handler failed before it could work out what
+     * it owed. Distinct from {@link rearm} because that one trusts the map, and
+     * the map is what we just failed to read.
+     */
+    repair(now: number): Promise<void>;
+}