@loopingai/core 0.6.0 → 0.7.0

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

@@ -0,0 +1,38 @@
+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.
+     */
+    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,8 @@ 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 { 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,8 @@ 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 { callerContext } from "./caller.js";
 export { createPushChannel } from "./push.js";
 export { taskStateLabel } from "./task.js";

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/index.d.ts

@@ -14,6 +14,6 @@ export type { DelegationNames, RecipeLimits, ResolvedRecipe, SubtaskParams, Subt
 export { RecipeValidationError, resolveLimits, validateRecipe, type RecipePolicy } from "./contract/validation.js";
 export { ConfigError, DEFAULT_CORE_CONFIG, resolveConfig, type AgentLimits, type CoreConfig, type CoreConfigOverrides, type ModelConfig, type SessionConfig } from "./config.js";
 export { parseGatewayOrigins, type A2ASecretsEnv, type AiEnv, type CoreEnv } from "./env.js";
-export { CHUNK_SOFT_MS, MAX_CHUNKS_PER_BRANCH, MAX_TOOL_CALL_MS, STEP_TIMEOUT_MS, STEPS_PER_INSTANCE } from "./platform.js";
+export { CHUNK_SOFT_MS, CHUNK_STEP, MAX_CHUNKS_PER_BRANCH, MAX_TOOL_CALL_MS, STEP_TIMEOUT_MS, STEPS_PER_INSTANCE } from "./platform.js";
 export type { PluginStore } from "./db/db.js";
 export { makeWorkspaceHandle, memoryWorkspaceBacking, WorkspaceLimitError, WORKSPACE_MAX_FILES, WORKSPACE_MAX_FILE_BYTES, type WorkspaceBacking, type WorkspaceEntry, type WorkspaceHandle } from "./subagent/workspace.js";

package/dist/index.js

@@ -13,5 +13,5 @@ export { PLUGIN_CONTRACT_VERSION, definePlugin, restrictMainAgentTools } from ".
 export { RecipeValidationError, resolveLimits, validateRecipe } from "./contract/validation.js";
 export { ConfigError, DEFAULT_CORE_CONFIG, resolveConfig } from "./config.js";
 export { parseGatewayOrigins } from "./env.js";
-export { CHUNK_SOFT_MS, MAX_CHUNKS_PER_BRANCH, MAX_TOOL_CALL_MS, STEP_TIMEOUT_MS, STEPS_PER_INSTANCE } from "./platform.js";
+export { CHUNK_SOFT_MS, CHUNK_STEP, MAX_CHUNKS_PER_BRANCH, MAX_TOOL_CALL_MS, STEP_TIMEOUT_MS, STEPS_PER_INSTANCE } from "./platform.js";
 export { makeWorkspaceHandle, memoryWorkspaceBacking, WorkspaceLimitError, WORKSPACE_MAX_FILES, WORKSPACE_MAX_FILE_BYTES } from "./subagent/workspace.js";

package/dist/platform.d.ts

@@ -1,3 +1,4 @@
+import type { WorkflowStepConfig } from "cloudflare:workers";
 /**
  * What the Cloudflare Workflows runtime imposes, and the two numbers derived from
  * it. Nothing here is a budget or a preference — see {@link file://./config.ts}
@@ -107,3 +108,31 @@ export declare const MAX_TOOL_CALL_MS: number;
  * 2. The worst-case step product stays under {@link STEPS_PER_INSTANCE}.
  */
 export declare const MAX_CHUNKS_PER_BRANCH = 40;
+/**
+ * What a step holding a model call or a container command configures instead of
+ * inheriting Workflows' defaults. Both defaults were measured wrong for this
+ * workload.
+ *
+ * **`timeout`.** The default is ten minutes. A step here holds a model call and
+ * its provider retries, or a container command running a project's test suite;
+ * neither fits in ten minutes reliably, and neither uses meaningful CPU while it
+ * waits. Left inherited, that default silently became the ceiling
+ * {@link CHUNK_SOFT_MS} was sized against.
+ *
+ * **`retries`.** The default is five attempts with exponential backoff from ten
+ * seconds. Against a fault that is not transient — a severed Durable Object stub
+ * — that produced five failures in under 10ms each, spread across 160 seconds of
+ * backoff that bought nothing. Three attempts still cover a genuinely transient
+ * fault, since the model call has its own provider-level retry underneath this,
+ * and a flat five-second delay stops a fast permanent failure being paid for at
+ * exponential rates.
+ *
+ * Here rather than in `/round` because the agent that most needs it may not be a
+ * round agent: a single-inference agent runs one model call in one step and has
+ * the same two problems, and importing this from `/round` would put the whole
+ * delegation engine in its bundle.
+ *
+ * For the **short** bookkeeping steps — `working`, `complete`, `notify` and
+ * friends — the defaults are fine and a shared config would only hide that.
+ */
+export declare const CHUNK_STEP: WorkflowStepConfig;

package/dist/platform.js

@@ -107,3 +107,34 @@ export const MAX_TOOL_CALL_MS = 10 * 60_000;
  * 2. The worst-case step product stays under {@link STEPS_PER_INSTANCE}.
  */
 export const MAX_CHUNKS_PER_BRANCH = 40;
+/**
+ * What a step holding a model call or a container command configures instead of
+ * inheriting Workflows' defaults. Both defaults were measured wrong for this
+ * workload.
+ *
+ * **`timeout`.** The default is ten minutes. A step here holds a model call and
+ * its provider retries, or a container command running a project's test suite;
+ * neither fits in ten minutes reliably, and neither uses meaningful CPU while it
+ * waits. Left inherited, that default silently became the ceiling
+ * {@link CHUNK_SOFT_MS} was sized against.
+ *
+ * **`retries`.** The default is five attempts with exponential backoff from ten
+ * seconds. Against a fault that is not transient — a severed Durable Object stub
+ * — that produced five failures in under 10ms each, spread across 160 seconds of
+ * backoff that bought nothing. Three attempts still cover a genuinely transient
+ * fault, since the model call has its own provider-level retry underneath this,
+ * and a flat five-second delay stops a fast permanent failure being paid for at
+ * exponential rates.
+ *
+ * Here rather than in `/round` because the agent that most needs it may not be a
+ * round agent: a single-inference agent runs one model call in one step and has
+ * the same two problems, and importing this from `/round` would put the whole
+ * delegation engine in its bundle.
+ *
+ * For the **short** bookkeeping steps — `working`, `complete`, `notify` and
+ * friends — the defaults are fine and a shared config would only hide that.
+ */
+export const CHUNK_STEP = {
+    timeout: STEP_TIMEOUT_MS,
+    retries: { limit: 3, delay: 5_000, backoff: "constant" }
+};

package/dist/round/workflow.js

@@ -1,36 +1,6 @@
-import { MAX_CHUNKS_PER_BRANCH, STEP_TIMEOUT_MS } from "../platform.js";
+import { CHUNK_STEP, MAX_CHUNKS_PER_BRANCH, STEP_TIMEOUT_MS } from "../platform.js";
 import { buildCompletedTask, buildFailedTask } from "../a2a/notify.js";
-import { createPushChannel } from "../a2a/push.js";
-/**
- * What the long steps configure instead of inheriting.
- *
- * Both halves of this were previously left at Workflows' defaults, and both
- * defaults were wrong for this workload.
- *
- * **`timeout`.** The default is ten minutes. Nothing here passed a config, so that
- * default silently became the ceiling {@link CHUNK_SOFT_MS} was sized against —
- * see the note on `STEP_TIMEOUT_MS` in `platform.ts` for what that cost. A step
- * here holds a model call and its provider retries, or a container command running
- * a project's test suite; neither fits in ten minutes reliably and neither uses
- * meaningful CPU while it waits.
- *
- * **`retries`.** The default is five attempts with exponential backoff from ten
- * seconds. The failure documented on {@link ResolveAgent} is what that produces
- * when the fault is not transient: five retries against a severed stub, each
- * failing in under 10ms, spread across 160 seconds of backoff that bought nothing.
- * Three attempts still cover a genuinely transient fault — the model call has its
- * own provider-level retry underneath this — and a flat five-second delay stops a
- * fast, permanent failure from being paid for at exponential rates.
- *
- * Deliberately applied only to the chunk steps — see {@link turnStep} for why a
- * round does not share it. The short bookkeeping steps (`working`, `deadline:`,
- * `scan:`, `complete`, `notify`) are sub-second projections where the defaults
- * are fine and a shared config would only hide that.
- */
-const CHUNK_STEP = {
-    timeout: STEP_TIMEOUT_MS,
-    retries: { limit: 3, delay: 5_000, backoff: "constant" }
-};
+import { deliverTerminalTask } from "../a2a/deliver.js";
 /**
  * The same retries, and a timeout a **round** can actually be measured against.
  *
@@ -323,62 +293,37 @@ async function runBranch(p, step, agent, id, push) {
  * and is deliberately not given a kind of its own until something needs to tell
  * it apart.
  *
- * The Task is built **inside** the step and returned, so `notify` posts exactly
- * what was persisted: building it in the body would re-stamp `new Date()` on
- * every replay and post a Task that differs from the stored one.
- *
- * **The guarded write is the cancellation check.** `saveTask` refuses to write a
- * terminal state over a `canceled` row and says so, and it does that read and
- * write in one synchronous pass inside the DO. 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.
+ * The delivery itself is {@link deliverTerminalTask}, which is shared with agents
+ * that never delegate. What is a round's own is the two things passed to it: the
+ * choice of terminal Task, and the child sweep.
  */
 async function deliver(p, step, agent, reply, deps, failure) {
     // Resolved outside the step body so a replay cannot take a different branch
     // than the write it is replaying.
     const failedText = (failure && deps.failureCopy?.(failure.kind, failure.detail)) ||
         deps.policy.copy.taskFailed;
-    const task = await step.do("complete", async () => {
-        const terminal = reply !== null
-            ? buildCompletedTask(p.taskId, p.contextId, reply)
-            : buildFailedTask(p.taskId, p.contextId, failedText);
-        return (await agent().saveTask(terminal)) ? terminal : null;
-    });
-    if (!task)
-        return;
-    // Sweep this Task's managed children now that it is terminal and every `execute`
-    // step has unwound. Deleting them here — rather than right after each successful
-    // chunk — keeps `deleteSubAgent`'s facet-abort from landing on a still-open
-    // `executeChunk` RPC, which telemetry mis-records as a failure. Best-effort and
-    // idempotent, so it is safe on replay.
-    //
-    // 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 `notify` below — the gateway is owed its result regardless of whether
-    // this Task's children were reclaimed.
-    try {
-        await step.do("sweep", async () => {
-            await agent().sweepTaskChildren(p.taskId);
-        });
-    }
-    catch (err) {
-        console.error("[handle-task] sweep failed after retries", {
-            taskId: p.taskId,
-            err: String(err)
-        });
-    }
-    // Notify the gateway: a card-key-signed callback POST. Retried by the step on a
-    // non-2xx; the terminal messageId is deterministic and the gateway is
-    // idempotent/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(deps.signingKey, {
+    await deliverTerminalTask(step, {
+        push: {
             taskId: p.taskId,
             contextId: p.contextId,
             pushUrl: p.pushUrl,
             pushToken: p.pushToken,
             jku: p.jku
-        }).deliver(task);
+        },
+        signingKey: deps.signingKey,
+        // `agent()` inside the body, never hoisted: a stub is a live connection and
+        // a severed one never reconnects.
+        saveTask: (task) => agent().saveTask(task),
+        terminal: () => reply !== null
+            ? buildCompletedTask(p.taskId, p.contextId, reply)
+            : buildFailedTask(p.taskId, p.contextId, failedText),
+        // Sweep this Task's managed children now that it is terminal and every
+        // `execute` step has unwound. Deleting them here — rather than right after
+        // each successful chunk — keeps `deleteSubAgent`'s facet-abort from landing
+        // on a still-open `executeChunk` RPC, which telemetry mis-records as a
+        // failure. Best-effort and idempotent, so it is safe on replay.
+        sweep: async () => {
+            await agent().sweepTaskChildren(p.taskId);
+        }
     });
 }

package/dist/testing/do.d.ts

@@ -8,11 +8,11 @@ import { AgentDB, type AgentDBOptions } from "../db/db.js";
  * and {@link DoTestHelpers.withDb} hands over the whole `AgentDB` rather than
  * pre-selecting a table.
  */
-export interface DoTestHelpers {
+export interface DoTestHelpers<T extends Rpc.DurableObjectBranded | undefined> {
     /** Fresh, unique DO stub per test — state never leaks between tests. */
-    freshStub(label: string): DurableObjectStub;
+    freshStub(label: string): DurableObjectStub<T>;
     /** Run `fn` inside a fresh DO instance with a migrated {@link AgentDB}. */
-    withDb<T>(label: string, fn: (db: AgentDB) => T): Promise<T>;
+    withDb<R>(label: string, fn: (db: AgentDB) => R): Promise<R>;
 }
 /**
  * `ctx` is protected in the DO type system but public at runtime. Cast once so
@@ -26,4 +26,4 @@ export declare function doStorage(instance: unknown): DurableObjectStorage;
  * const { freshStub, withDb } = makeDoHelpers(env.MyAgent);
  * ```
  */
-export declare function makeDoHelpers(ns: DurableObjectNamespace, defaults?: AgentDBOptions): DoTestHelpers;
+export declare function makeDoHelpers<T extends Rpc.DurableObjectBranded | undefined = undefined>(ns: DurableObjectNamespace<T>, defaults?: AgentDBOptions): DoTestHelpers<T>;

package/dist/testing/index.d.ts

@@ -24,7 +24,7 @@
 export { setupRecording, cassetteNameFor, type SetupRecordingOptions } from "./vcr-spec.js";
 export { VCR_CONTROL_ORIGIN, VCR_MARKER_HEADER, CASSETTE_NAME_RE, type VcrReleaseResult } from "./vcr-shared.js";
 export { FakeSession } from "./fake-session.js";
-export { mockModel, finalReply, type MockStep } from "./mock-model.js";
+export { mockModel, finalReply, throwingModel, countingModel, rateLimitedModel, type MockStep } from "./mock-model.js";
 export { makeGatewayToken, type GatewayTokenOptions } from "./auth.js";
 export { AGENT_ORIGIN, GATEWAY_ORIGIN, TEST_AGENT_PRIVATE_JWK, TEST_GATEWAY_PRIVATE_JWK, TEST_MODELS, gatewayPublicJwks, testAgentMessage, testStatus, testTask } from "./fixtures.js";
 export { doStorage, makeDoHelpers, type DoTestHelpers } from "./do.js";

package/dist/testing/index.js

@@ -24,7 +24,11 @@
 export { setupRecording, cassetteNameFor } from "./vcr-spec.js";
 export { VCR_CONTROL_ORIGIN, VCR_MARKER_HEADER, CASSETTE_NAME_RE } from "./vcr-shared.js";
 export { FakeSession } from "./fake-session.js";
-export { mockModel, finalReply } from "./mock-model.js";
+// `throwingModel`, `countingModel` and `rateLimitedModel` were reachable only
+// through a deep `dist/` path until now, which meant a consumer could not assert
+// the one thing they exist for: that a rate limit is waited out on the *same*
+// model rather than falling through to the fallback slot.
+export { mockModel, finalReply, throwingModel, countingModel, rateLimitedModel } from "./mock-model.js";
 export { makeGatewayToken } from "./auth.js";
 export { AGENT_ORIGIN, GATEWAY_ORIGIN, TEST_AGENT_PRIVATE_JWK, TEST_GATEWAY_PRIVATE_JWK, TEST_MODELS, gatewayPublicJwks, testAgentMessage, testStatus, testTask } from "./fixtures.js";
 export { doStorage, makeDoHelpers } from "./do.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loopingai/core",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Shared, mandatory foundation for Looping agents on Cloudflare Workers: zero-trust A2A, durable task lifecycle, delegation and subagent runtime, test harness.",
   "keywords": [
     "a2a",
@@ -57,6 +57,10 @@
       "types": "./dist/host/index.d.ts",
       "import": "./dist/host/index.js"
     },
+    "./alarm": {
+      "types": "./dist/alarm/index.d.ts",
+      "import": "./dist/alarm/index.js"
+    },
     "./round": {
       "types": "./dist/round/index.d.ts",
       "import": "./dist/round/index.js"