@loopingai/core 0.5.1 → 0.7.0

package/dist/agent/model.d.ts

@@ -1,12 +1,24 @@
 import type { LanguageModel } from "ai";
 import type { ModelConfig } from "../config.js";
 /**
- * The Workers-AI model pair every loop runs on, built per agent instance.
+ * The provider contract every loop runs against — and nothing that implements
+ * it.
  *
- * The predecessor read `env.AI` and five config constants as module-level
- * imports. Neither survives packaging: `env` does not exist at module scope on
- * Workers, and a module constant cannot be overridden by a consumer. So this is
- * a factory over an injected binding and an injected {@link ModelConfig}.
+ * {@link ModelRuntime} is the whole seam: an agent that returns one runs every
+ * loop in core unchanged, because nothing downstream — the round loop, the
+ * control-tool repair ladder, the Session's compaction, the Workflow — ever sees
+ * 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.
+ *
+ * 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
+ * as *the* runtime with an escape hatch, rather than as one of N.
  */
 /**
  * Custom metadata attached to the AI Gateway log for every call a pair makes.
@@ -22,15 +34,16 @@ export interface ModelOverrides {
     /** Test override for the fallback slot. */
     fallbackModel?: LanguageModel;
     /**
-     * Workers-AI id for the primary slot (a recipe's, already code-validated
-     * against the allowlist by `validateRecipe`). Defaults to the configured
+     * The provider's model id for the primary slot. Defaults to the configured
      * `chatModelId`.
+     *
+     * The subagent path passes `ValidatedRecipe.primaryModelId`, which is the
+     * host's own configured id — `validateRecipe` copies the pair on, and a recipe
+     * has no field to name a model with. So this parameterizes the pair without
+     * ever widening which models are reachable.
      */
     primaryModelId?: string;
-    /**
-     * Workers-AI id for the fallback slot (already code-validated). Defaults to
-     * the configured `fallbackChatModelId`.
-     */
+    /** The provider's model id for the fallback slot. See {@link primaryModelId}. */
     fallbackModelId?: string;
     /** AI Gateway log metadata for correlation — see {@link GatewayMetadata}. */
     metadata?: GatewayMetadata;
@@ -45,23 +58,27 @@ export interface ModelPair {
 export interface ModelRuntime {
     /**
      * Lazily build + memoize a primary/fallback model pair (overridable in tests,
-     * id-parameterized for recipes). No allowlisting happens here —
-     * `validateRecipe` is the single validation owner for recipe-supplied ids.
+     * id-parameterized so a subagent can run the pair its validated recipe
+     * carries). Nothing is checked here — the ids reaching this can only be the
+     * host's own, which `resolveConfig` has already proven non-empty and distinct.
      */
     createModelPair(overrides?: ModelOverrides): ModelPair;
 }
-export interface ModelRuntimeDeps {
-    /** The `AI` binding. Read lazily — see {@link createModelRuntime}. */
-    ai: Ai;
-    config: ModelConfig;
-}
 /**
- * Build the model runtime for one agent instance.
+ * How a provider is supplied to an agent: given the Worker env and the agent's
+ * *resolved* model config, return a runtime.
+ *
+ * Both base-class seams — `LoopingAgent.modelRuntime` and
+ * `RecipeSubagentHost.modelRuntime` — take this shape, which is the point of it.
+ * A provider written as one of these is defined once and referenced from the
+ * agent and its subagent facet, instead of being spelled out twice in two class
+ * bodies that nothing keeps in step. See
+ * {@link file://./workers-ai/runtime.ts workersAIModels} for core's own.
  *
- * The provider is constructed on first *use*, not here. During `wrangler deploy`
- * Cloudflare evaluates module scope to validate the new version, and bindings
- * are not populated at that point — constructing eagerly makes `createWorkersAI`
- * throw "you must provide either a binding or credentials". The same laziness
- * protects a consumer who builds their runtime early.
+ * Config arrives as an argument rather than being read off `this`: the facet
+ * resolves its config inside `buildRuntime` and calls the seam from there, so
+ * there is no `this.config` to read at that point — and a factory that cannot
+ * reach for one cannot disagree with its caller about which gateway the agent
+ * is on.
  */
-export declare function createModelRuntime(deps: ModelRuntimeDeps): ModelRuntime;
+export type ModelRuntimeFactory<TEnv> = (env: TEnv, config: ModelConfig) => ModelRuntime;

package/dist/agent/model.js

@@ -1,48 +1 @@
-import { createWorkersAI } from "workers-ai-provider";
-/**
- * Build the model runtime for one agent instance.
- *
- * The provider is constructed on first *use*, not here. During `wrangler deploy`
- * Cloudflare evaluates module scope to validate the new version, and bindings
- * are not populated at that point — constructing eagerly makes `createWorkersAI`
- * throw "you must provide either a binding or credentials". The same laziness
- * protects a consumer who builds their runtime early.
- */
-export function createModelRuntime(deps) {
-    const { config } = deps;
-    let provider;
-    const workersai = () => (provider ??= createWorkersAI({
-        binding: deps.ai,
-        gateway: { id: config.aiGatewayId }
-    }));
-    /**
-     * Per-model Workers-AI settings: pin the gateway id (so per-call metadata does
-     * not drop the gateway route), attach correlation metadata when supplied, and
-     * set the reasoning budget.
-     *
-     * Always returns a settings object, even with no metadata: `reasoning_effort`
-     * has to reach the binding on every call, and an `undefined` return drops it.
-     */
-    const chatSettings = (metadata) => ({
-        gateway: { id: config.aiGatewayId, ...(metadata ? { metadata } : {}) },
-        reasoning_effort: config.reasoningEffort
-    });
-    return {
-        createModelPair(overrides = {}) {
-            const primaryId = overrides.primaryModelId ?? config.chatModelId;
-            const fallbackId = overrides.fallbackModelId ?? config.fallbackChatModelId;
-            let primary;
-            let fallback;
-            const settings = chatSettings(overrides.metadata);
-            return {
-                primary: () => (primary ??= overrides.model ?? workersai()(primaryId, settings)),
-                fallback: () => (fallback ??=
-                    overrides.fallbackModel ??
-                        overrides.model ??
-                        workersai()(fallbackId, settings)),
-                primaryId: () => primaryId,
-                fallbackId: () => fallbackId
-            };
-        }
-    };
-}
+export {};

package/dist/agent/session.d.ts

@@ -3,9 +3,8 @@ import { Session } from "agents/experimental/memory/session";
 import type { SessionMessage } from "agents/experimental/memory/session";
 import { createCompactFunction } from "agents/experimental/memory/utils";
 /**
- * The one continuous {@link Session} an agent Durable Object owns. Ported from
- * the looping-gateway admin agent's `shared/session.ts` (single Session per DO —
- * soul + memory + compaction).
+ * The one continuous {@link Session} an agent Durable Object owns: soul + memory
+ * + compaction, one Session per DO.
  *
  * Compaction is the one **lossy** thing this module does, so it is also the one
  * thing it announces: `onMessagesDisplaced` hands over the raw messages a
@@ -27,7 +26,7 @@ export interface SessionLike {
      * Read one message by id, or null. Reads the **raw stored row**, so it is
      * unaffected by compaction overlays — a message folded into a summary is still
      * readable here. That is what makes {@link appendOnce}'s read-back a reliable
-     * recovery path for a phase whose Workflow step re-ran.
+     * recovery path for a round whose Workflow step re-ran.
      */
     getMessage(id: string): Promise<SessionMessage | null>;
     refreshSystemPrompt(): Promise<string>;
@@ -40,13 +39,13 @@ export interface SessionLike {
  * is **durably stored** under that id.
  *
  * `Session.appendMessage` is already idempotent by id: appending an id that
- * exists is a no-op. The read-back is what matters for a re-run phase — if the
- * step crashed after appending and the retry re-inferred a *different* reply, the
+ * exists is a no-op. The read-back is what matters for a re-run step — if it
+ * crashed after appending and the retry re-inferred a *different* reply, the
  * append no-ops and this returns the original, durable text. The Session and the
  * value the caller goes on to deliver therefore never disagree.
  *
  * Falls back to the message's own text if the read-back returns null (it cannot,
- * having just been appended) rather than failing a phase over a missing echo.
+ * having just been appended) rather than failing a round over a missing echo.
  */
 export declare function appendOnce(session: SessionLike, message: SessionMessage): Promise<string>;
 export interface AgentSessionOptions {

package/dist/agent/session.js

@@ -7,13 +7,13 @@ import { sessionText } from "./history.js";
  * is **durably stored** under that id.
  *
  * `Session.appendMessage` is already idempotent by id: appending an id that
- * exists is a no-op. The read-back is what matters for a re-run phase — if the
- * step crashed after appending and the retry re-inferred a *different* reply, the
+ * exists is a no-op. The read-back is what matters for a re-run step — if it
+ * crashed after appending and the retry re-inferred a *different* reply, the
  * append no-ops and this returns the original, durable text. The Session and the
  * value the caller goes on to deliver therefore never disagree.
  *
  * Falls back to the message's own text if the read-back returns null (it cannot,
- * having just been appended) rather than failing a phase over a missing echo.
+ * having just been appended) rather than failing a round over a missing echo.
  */
 export async function appendOnce(session, message) {
     await session.appendMessage(message);

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

@@ -0,0 +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
+ * policy; it satisfies {@link file://../model.ts ModelRuntime} and stops.
+ *
+ * It differs from that sibling in two ways, both deliberate:
+ *
+ * **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.
+ *
+ * **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.
+ */
+export { createWorkersAIModelRuntime, workersAIModels, type WorkersAIRuntimeDeps } from "./runtime.js";

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

@@ -0,0 +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
+ * policy; it satisfies {@link file://../model.ts ModelRuntime} and stops.
+ *
+ * It differs from that sibling in two ways, both deliberate:
+ *
+ * **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.
+ *
+ * **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.
+ */
+export { createWorkersAIModelRuntime, workersAIModels } from "./runtime.js";

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

@@ -0,0 +1,42 @@
+import type { ModelConfig } from "../../config.js";
+import type { AiEnv } from "../../env.js";
+import type { ModelRuntime, ModelRuntimeFactory } from "../model.js";
+/**
+ * The Workers-AI model pair every loop runs on by default, built per agent
+ * instance.
+ *
+ * The predecessor read `env.AI` and five config constants as module-level
+ * imports. Neither survives packaging: `env` does not exist at module scope on
+ * Workers, and a module constant cannot be overridden by a consumer. So this is
+ * a factory over an injected binding and an injected {@link ModelConfig}.
+ */
+export interface WorkersAIRuntimeDeps {
+    /** The `AI` binding. Read lazily — see {@link createWorkersAIModelRuntime}. */
+    ai: Ai;
+    config: ModelConfig;
+}
+/**
+ * Build the Workers AI model runtime for one agent instance.
+ *
+ * The provider is constructed on first *use*, not here. During `wrangler deploy`
+ * Cloudflare evaluates module scope to validate the new version, and bindings
+ * are not populated at that point — constructing eagerly makes `createWorkersAI`
+ * throw "you must provide either a binding or credentials". The same laziness
+ * protects a consumer who builds their runtime early.
+ */
+export declare function createWorkersAIModelRuntime(deps: WorkersAIRuntimeDeps): ModelRuntime;
+/**
+ * Core's default provider — what every {@link ModelRuntimeFactory} seam lands on
+ * when an agent does not override it.
+ *
+ * One definition rather than one per base class. The body used to be written
+ * twice, once in {@link file://../../host/agent.ts LoopingAgent.modelRuntime}
+ * and once in
+ * {@link file://../../round/subagent.ts RecipeSubagentHost.modelRuntime}, which
+ * is the same duplication the seam exists to let a *consumer* avoid.
+ *
+ * Typed on {@link AiEnv} rather than a caller's full `Env`: a factory that
+ * accepts the narrow shape is callable with any env that satisfies it, so both
+ * base classes pass `this.env` straight through.
+ */
+export declare const workersAIModels: ModelRuntimeFactory<AiEnv>;

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

@@ -0,0 +1,63 @@
+import { createWorkersAI } from "workers-ai-provider";
+/**
+ * Build the Workers AI model runtime for one agent instance.
+ *
+ * The provider is constructed on first *use*, not here. During `wrangler deploy`
+ * Cloudflare evaluates module scope to validate the new version, and bindings
+ * are not populated at that point — constructing eagerly makes `createWorkersAI`
+ * throw "you must provide either a binding or credentials". The same laziness
+ * protects a consumer who builds their runtime early.
+ */
+export function createWorkersAIModelRuntime(deps) {
+    const { config } = deps;
+    let provider;
+    const workersai = () => (provider ??= createWorkersAI({
+        binding: deps.ai,
+        gateway: { id: config.aiGatewayId }
+    }));
+    /**
+     * Per-model Workers-AI settings: pin the gateway id (so per-call metadata does
+     * not drop the gateway route), attach correlation metadata when supplied, and
+     * set the reasoning budget.
+     *
+     * Always returns a settings object, even with no metadata: `reasoning_effort`
+     * has to reach the binding on every call, and an `undefined` return drops it.
+     */
+    const chatSettings = (metadata) => ({
+        gateway: { id: config.aiGatewayId, ...(metadata ? { metadata } : {}) },
+        reasoning_effort: config.reasoningEffort
+    });
+    return {
+        createModelPair(overrides = {}) {
+            const primaryId = overrides.primaryModelId ?? config.chatModelId;
+            const fallbackId = overrides.fallbackModelId ?? config.fallbackChatModelId;
+            let primary;
+            let fallback;
+            const settings = chatSettings(overrides.metadata);
+            return {
+                primary: () => (primary ??= overrides.model ?? workersai()(primaryId, settings)),
+                fallback: () => (fallback ??=
+                    overrides.fallbackModel ??
+                        overrides.model ??
+                        workersai()(fallbackId, settings)),
+                primaryId: () => primaryId,
+                fallbackId: () => fallbackId
+            };
+        }
+    };
+}
+/**
+ * Core's default provider — what every {@link ModelRuntimeFactory} seam lands on
+ * when an agent does not override it.
+ *
+ * One definition rather than one per base class. The body used to be written
+ * twice, once in {@link file://../../host/agent.ts LoopingAgent.modelRuntime}
+ * and once in
+ * {@link file://../../round/subagent.ts RecipeSubagentHost.modelRuntime}, which
+ * is the same duplication the seam exists to let a *consumer* avoid.
+ *
+ * Typed on {@link AiEnv} rather than a caller's full `Env`: a factory that
+ * accepts the narrow shape is callable with any env that satisfies it, so both
+ * base classes pass `this.env` straight through.
+ */
+export const workersAIModels = (env, config) => createWorkersAIModelRuntime({ ai: env.AI, config });

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

package/dist/alarm/index.js

@@ -0,0 +1,116 @@
+/**
+ * `@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.
+ */
+/** The single storage row holding every intent. Small, and written atomically. */
+export const WAKE_KEY = "wake";
+/** How far out {@link WakeMap.repair} re-arms when the handler itself failed. */
+export const WAKE_REPAIR_MS = 60_000;
+export class WakeMap {
+    #storage;
+    constructor(storage) {
+        this.#storage = storage;
+    }
+    /**
+     * 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.
+     */
+    async all() {
+        const stored = await this.#storage.get(WAKE_KEY);
+        const intents = Object.create(null);
+        // `Object.entries` is own-enumerable-only, so nothing from a prototype can
+        // enter here even if the stored value arrived with one.
+        if (stored) {
+            for (const [key, intent] of Object.entries(stored))
+                intents[key] = intent;
+        }
+        return intents;
+    }
+    async get(key) {
+        return (await this.all())[key];
+    }
+    async set(intent) {
+        const all = await this.all();
+        all[intent.key] = intent;
+        await this.#storage.put(WAKE_KEY, all);
+        await this.rearm();
+    }
+    async clear(key) {
+        const all = await this.all();
+        // `hasOwn`, not `in`: the dictionary has no prototype today, and this stays
+        // correct if that ever changes.
+        if (!Object.hasOwn(all, key))
+            return;
+        delete all[key];
+        await this.#storage.put(WAKE_KEY, all);
+        await this.rearm();
+    }
+    /** Every intent whose time has come, earliest first. */
+    async due(now) {
+        return Object.values(await this.all())
+            .filter((intent) => intent.notBefore <= now)
+            .sort((a, b) => a.notBefore - b.notBefore);
+    }
+    /**
+     * 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.
+     */
+    async rearm() {
+        const deadlines = Object.values(await this.all()).map((i) => i.notBefore);
+        const existing = await this.#storage.getAlarm();
+        if (deadlines.length === 0) {
+            if (existing !== null)
+                await this.#storage.deleteAlarm();
+            return;
+        }
+        const earliest = Math.min(...deadlines);
+        if (existing === null || existing > earliest) {
+            await this.#storage.setAlarm(earliest);
+        }
+    }
+    /**
+     * 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.
+     */
+    async repair(now) {
+        const existing = await this.#storage.getAlarm();
+        if (existing === null)
+            await this.#storage.setAlarm(now + WAKE_REPAIR_MS);
+    }
+}

package/dist/config.d.ts

@@ -1,16 +1,3 @@
-/**
- * The shapes of everything an agent tunes, plus a working set of defaults.
- *
- * In the predecessor repos this file held bare `export const`s that ~12 modules
- * imported directly. That is what this package cannot do: a module-level constant
- * read at import time is not overridable by a consumer, and it freezes the value
- * into the module graph before `env` exists. So core owns the *shapes* and a
- * baseline; a consuming agent passes overrides to {@link resolveConfig} once, at
- * DO start, and the resolved object is threaded through explicitly.
- *
- * The distinction against {@link file://./platform.ts} stays sharp: nothing here
- * is a platform fact, and nothing there is tunable.
- */
 /** Model ids and per-call generation settings. */
 export interface ModelConfig {
     /**
@@ -40,6 +27,21 @@ 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`
@@ -49,6 +51,38 @@ export interface ModelConfig {
     maxOutputTokens: number;
     /** Reasoning budget forwarded on the binding's `inputs` by workers-ai-provider. */
     reasoningEffort: "low" | "medium" | "high";
+    /**
+     * How many times a single model call is retried **on the same model** before
+     * the round gives up on that slot and moves to the fallback.
+     *
+     * This was hardcoded to `0` for a long time, with a reason that was right for
+     * one case and wrong for the other. The reason: primary→fallback recovery is
+     * ours, so provider-level backoff only adds latency and duplicates it. True
+     * when the two slots are different vendors, which is what
+     * {@link fallbackChatModelId} advises — a 429 on one says nothing about the
+     * other, so falling straight through is the fastest correct move.
+     *
+     * It is false for a rate limit on an agent whose slots share a credential. A
+     * coder running Opus with Sonnet as its step-down burns the fallback proving
+     * the same 429 twice, then throws, then the Workflow retries the whole round
+     * and does it again. Waiting the `retry-after` the provider actually sent is
+     * both cheaper and far more likely to work.
+     *
+     * 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.
+     *
+     * Bounded at 4 by `resolveConfig`. The retries happen *inside*
+     * `step.do("turn:<round>")`, and the SDK caps a single honoured `retry-after`
+     * at 60s, so the worst case is roughly `maxRetries` minutes of waiting before
+     * the round has spent a token of its own — against
+     * {@link file://./platform.ts STEP_TIMEOUT_MS}, which is where that ceiling is
+     * stated and the only place it should be read from.
+     */
+    maxRetries: number;
 }
 /**
  * An execution budget, in the only two currencies that mean anything: **turns**
@@ -126,8 +160,8 @@ export interface CoreConfig {
     toolOutputWindow: number;
     /**
      * Upper bound on subtasks per **round** — a core invariant: a delegating round
-     * emits `1..maxSubtasks` subtasks, which is also what bounds its fan-out (all
-     * dependency-ready subtasks run concurrently, with no other concurrency cap).
+     * emits `1..maxSubtasks` subtasks, which is also what bounds its fan-out (they
+     * all run concurrently, with no other concurrency cap).
      *
      * Not a budget but a shape: it is what the delegation schema offers the model,
      * and the data layer re-checks it as the durable guard.