@loopingai/core 0.6.0 → 0.7.1

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

@@ -69,6 +69,17 @@ export declare abstract class LoopingAgent<TEnv extends Cloudflare.Env & AiEnv &
      * not depend on it surviving.
      */
     private identityKey?;
+    /**
+     * This deployment's own public origin, learned from the `jku` every turn
+     * carries and **pinned on the first one** this instance serves.
+     *
+     * Unlike {@link identityKey} this is shared by concurrent turns — the object
+     * is keyed by caller, not by origin — so it is pinned rather than
+     * last-write-wins: an immutable field cannot change under a credential thunk
+     * that reads it while a turn awaits a model call. See {@link SelfOrigin} for
+     * the full argument, and for why nothing is persisted.
+     */
+    private readonly selfOriginMemo;
     /**
      * Test-only model injection. A **field**, not a constructor argument or an RPC
      * parameter, so it never appears on the generated DO stub: production callers
@@ -197,6 +208,31 @@ export declare abstract class LoopingAgent<TEnv extends Cloudflare.Env & AiEnv &
      * exists.
      */
     protected requireIdentityKey(): string;
+    /**
+     * Offer this deployment's own origin from a value that carries it. The first
+     * usable one is kept for the life of the instance.
+     *
+     * Called wherever a {@link TurnPushContext} arrives — here for every agent
+     * shape, and at the entry of `RoundAgentBase`'s two RPCs, where the origin is
+     * needed *before* this channel would be built. All three matter because any of
+     * them can be the call that wakes a fresh isolate. Cheap and unfailing: past
+     * the first turn it is one truthiness check, and an unusable value is ignored
+     * rather than thrown, because a turn must not fail over this.
+     */
+    protected noteSelfOrigin(url: string | undefined): void;
+    /**
+     * This deployment's own public origin, if a turn has carried it to this
+     * instance yet. Constant once set, so it reads the same from any turn running
+     * on this object. See {@link SelfOrigin}.
+     */
+    protected selfOrigin(): string | undefined;
+    /**
+     * The same, for a caller that cannot proceed without it — signing a caller
+     * token with {@link file://../a2a/caller-token.ts signCallerToken} above all,
+     * whose `iss` this is. Throws naming the timing rather than producing a token
+     * with a nonsense issuer.
+     */
+    protected requireSelfOrigin(): string;
     /** The gateway callback channel for one turn. See {@link PushChannel}. */
     protected push(context: TurnPushContext): PushChannel;
     /**

package/dist/host/agent.js

@@ -5,6 +5,7 @@ import { resolveConfig } from "../config.js";
 import { AgentDB, stateOf } from "../db/index.js";
 import { callerContext } from "../a2a/caller.js";
 import { createPushChannel } from "../a2a/push.js";
+import { SelfOrigin } from "../a2a/self-origin.js";
 import { buildAgentSession } from "../agent/session.js";
 import { workersAIModels } from "../agent/workers-ai/index.js";
 /**
@@ -64,6 +65,17 @@ export class LoopingAgent extends Agent {
      * not depend on it surviving.
      */
     identityKey;
+    /**
+     * This deployment's own public origin, learned from the `jku` every turn
+     * carries and **pinned on the first one** this instance serves.
+     *
+     * Unlike {@link identityKey} this is shared by concurrent turns — the object
+     * is keyed by caller, not by origin — so it is pinned rather than
+     * last-write-wins: an immutable field cannot change under a credential thunk
+     * that reads it while a turn awaits a model call. See {@link SelfOrigin} for
+     * the full argument, and for why nothing is persisted.
+     */
+    selfOriginMemo = new SelfOrigin();
     /**
      * Test-only model injection. A **field**, not a constructor argument or an RPC
      * parameter, so it never appears on the generated DO stub: production callers
@@ -254,8 +266,40 @@ export class LoopingAgent extends Agent {
         }
         return (this.identityKey = key);
     }
+    /**
+     * Offer this deployment's own origin from a value that carries it. The first
+     * usable one is kept for the life of the instance.
+     *
+     * Called wherever a {@link TurnPushContext} arrives — here for every agent
+     * shape, and at the entry of `RoundAgentBase`'s two RPCs, where the origin is
+     * needed *before* this channel would be built. All three matter because any of
+     * them can be the call that wakes a fresh isolate. Cheap and unfailing: past
+     * the first turn it is one truthiness check, and an unusable value is ignored
+     * rather than thrown, because a turn must not fail over this.
+     */
+    noteSelfOrigin(url) {
+        this.selfOriginMemo.note(url);
+    }
+    /**
+     * This deployment's own public origin, if a turn has carried it to this
+     * instance yet. Constant once set, so it reads the same from any turn running
+     * on this object. See {@link SelfOrigin}.
+     */
+    selfOrigin() {
+        return this.selfOriginMemo.peek();
+    }
+    /**
+     * The same, for a caller that cannot proceed without it — signing a caller
+     * token with {@link file://../a2a/caller-token.ts signCallerToken} above all,
+     * whose `iss` this is. Throws naming the timing rather than producing a token
+     * with a nonsense issuer.
+     */
+    requireSelfOrigin() {
+        return this.selfOriginMemo.require();
+    }
     /** The gateway callback channel for one turn. See {@link PushChannel}. */
     push(context) {
+        this.noteSelfOrigin(context.jku);
         return createPushChannel(this.env.A2A_SIGNING_KEY, context);
     }
     /**

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/agent.js

@@ -83,6 +83,9 @@ export class RoundAgentBase extends LoopingAgent {
      * number, and none can report the wrong one.
      */
     async runTaskTurn(input) {
+        // Before anything can reach a model: a round that calls out mint-signed
+        // needs this deployment's own origin, and this is where it arrives.
+        this.noteSelfOrigin(input.push?.jku);
         const budget = newTurnBudget(input.turnsRemaining);
         const verdict = await this.decideRound(input, budget);
         return { ...verdict, turns: budget.spent };
@@ -300,6 +303,10 @@ export class RoundAgentBase extends LoopingAgent {
      * not outcomes.
      */
     async executeSubtaskChunk(id, chunk, push) {
+        // Recorded here rather than left to `this.push(push)` below, which runs only
+        // after the chunk has already executed — and the child is handed this
+        // origin on the way in.
+        this.noteSelfOrigin(push?.jku);
         const prepared = await this.prepareChunk(id);
         if (prepared.kind === "terminal") {
             return { done: true, status: prepared.subtask.status, progress: [] };
@@ -482,9 +489,18 @@ export class RoundAgentBase extends LoopingAgent {
      * a second mismatch is a genuine lifecycle bug and must surface).
      */
     async executeChunkInChild(name, request, chunk, runtime) {
+        // A facet has no request path of its own: it is reached only from here, so
+        // this is the only way it can learn what this deployment is called. Passed
+        // as its own argument, never folded into `request`, for the same reason
+        // `chunk` is — the request is fingerprinted, and this is not part of what
+        // the execution *is*, so it must not be able to make a retry look like a
+        // different one. Pinned on both sides, so it cannot change under a run;
+        // undefined only on an instance no turn has reached, where the facet's own
+        // `requireSelfOrigin` produces the readable error.
+        const selfOrigin = this.selfOrigin();
         const child = await this.subAgent(this.subagentClass(), name);
         try {
-            return await child.executeChunk(request, chunk, runtime);
+            return await child.executeChunk(request, chunk, runtime, selfOrigin);
         }
         catch (err) {
             if (!String(err).includes(FINGERPRINT_MISMATCH))
@@ -492,7 +508,7 @@ export class RoundAgentBase extends LoopingAgent {
             console.warn("[agent] stale subagent state, recreating", { name });
             await this.deleteSubAgent(this.subagentClass(), name);
             const fresh = await this.subAgent(this.subagentClass(), name);
-            return await fresh.executeChunk(request, chunk, runtime);
+            return await fresh.executeChunk(request, chunk, runtime, selfOrigin);
         }
     }
     /** Let the owning plugin release whatever `resolveRuntime` acquired. */

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

@@ -102,6 +102,14 @@ export declare abstract class RecipeSubagentBase<TEnv extends Cloudflare.Env = C
      * to interrupt. See {@link abortRun}.
      */
     private inflight?;
+    /**
+     * This deployment's own public origin, as the parent DO passes it on every
+     * chunk, pinned from the first. In memory for the same reason {@link inflight}
+     * is: a facet is reached only through {@link executeChunk}, so an instance that
+     * lost it is an instance that will be told again before it can run anything.
+     * See {@link SelfOrigin}.
+     */
+    private readonly selfOriginMemo;
     onStart(): Promise<void>;
     /**
      * Idempotent schema bootstrap. Also called lazily from the RPCs so
@@ -111,17 +119,30 @@ export declare abstract class RecipeSubagentBase<TEnv extends Cloudflare.Env = C
     private ensureTables;
     /** The recipe's durable workspace, backed by this facet's own SQLite storage. */
     private workspace;
+    /**
+     * This deployment's own public origin, if the parent has passed it to this
+     * instance yet. See {@link SelfOrigin}.
+     */
+    protected selfOrigin(): string | undefined;
+    /**
+     * The same, for a caller that cannot proceed without it — a facet that signs
+     * its own caller tokens, above all. Mirrors `LoopingAgent.requireSelfOrigin`,
+     * because a facet must run on the same provider, and so the same credential
+     * path, as the parent that delegated to it.
+     */
+    protected requireSelfOrigin(): string;
     /**
      * Execute one durable chunk of a Subtask under the parent's resolved Recipe.
      *
      * A terminal outcome (completed / failed) is cached and replayed on retry. A
      * mid-run chunk persists its rolling state to `run_state` and returns a
-     * `done: false` yield for the Workflow to run another chunk. `chunk` is a
-     * separate argument — never part of `request` — so every chunk fingerprints
-     * identically and the cache/resume keys line up. Only transient platform faults
-     * throw (nothing cached), so a Workflow retry resumes from the last checkpoint.
+     * `done: false` yield for the Workflow to run another chunk. `chunk` and
+     * `selfOrigin` are separate arguments — never part of `request` — so every
+     * chunk fingerprints identically and the cache/resume keys line up. Only
+     * transient platform faults throw (nothing cached), so a Workflow retry
+     * resumes from the last checkpoint.
      */
-    executeChunk(request: RecipeExecutionRequest, _chunk: number, runtime?: SubtaskRuntime): Promise<RecipeChunkResult>;
+    executeChunk(request: RecipeExecutionRequest, _chunk: number, runtime?: SubtaskRuntime, selfOrigin?: string): Promise<RecipeChunkResult>;
     /**
      * Interrupt the chunk running here right now, so a cancellation lands on the
      * current model call instead of at the next chunk boundary (up to `chunkSoftMs`

package/dist/subagent/index.js

@@ -4,6 +4,7 @@ import { CHUNK_SOFT_MS } from "../platform.js";
 import { buildRecipeTools } from "../runtime/tool-families.js";
 import { RecipeValidationError, validateRecipe } from "../contract/validation.js";
 import { SubtaskParamsError } from "../subtasks/subtask-types.js";
+import { SelfOrigin } from "../a2a/self-origin.js";
 import { renderSubagentPrompt } from "./prompt.js";
 import { makeWorkspaceHandle } from "./workspace.js";
 import { fingerprintRequest } from "./fingerprint.js";
@@ -77,6 +78,14 @@ export class RecipeSubagentBase extends Agent {
      * to interrupt. See {@link abortRun}.
      */
     inflight;
+    /**
+     * This deployment's own public origin, as the parent DO passes it on every
+     * chunk, pinned from the first. In memory for the same reason {@link inflight}
+     * is: a facet is reached only through {@link executeChunk}, so an instance that
+     * lost it is an instance that will be told again before it can run anything.
+     * See {@link SelfOrigin}.
+     */
+    selfOriginMemo = new SelfOrigin();
     async onStart() {
         this.ensureTables();
     }
@@ -107,18 +116,39 @@ export class RecipeSubagentBase extends Agent {
     workspace() {
         return (this._workspace ??= this.subagentRuntime().workspaceBacking(this.ctx.storage.sql, () => this.name));
     }
+    /**
+     * This deployment's own public origin, if the parent has passed it to this
+     * instance yet. See {@link SelfOrigin}.
+     */
+    selfOrigin() {
+        return this.selfOriginMemo.peek();
+    }
+    /**
+     * The same, for a caller that cannot proceed without it — a facet that signs
+     * its own caller tokens, above all. Mirrors `LoopingAgent.requireSelfOrigin`,
+     * because a facet must run on the same provider, and so the same credential
+     * path, as the parent that delegated to it.
+     */
+    requireSelfOrigin() {
+        return this.selfOriginMemo.require();
+    }
     /**
      * Execute one durable chunk of a Subtask under the parent's resolved Recipe.
      *
      * A terminal outcome (completed / failed) is cached and replayed on retry. A
      * mid-run chunk persists its rolling state to `run_state` and returns a
-     * `done: false` yield for the Workflow to run another chunk. `chunk` is a
-     * separate argument — never part of `request` — so every chunk fingerprints
-     * identically and the cache/resume keys line up. Only transient platform faults
-     * throw (nothing cached), so a Workflow retry resumes from the last checkpoint.
+     * `done: false` yield for the Workflow to run another chunk. `chunk` and
+     * `selfOrigin` are separate arguments — never part of `request` — so every
+     * chunk fingerprints identically and the cache/resume keys line up. Only
+     * transient platform faults throw (nothing cached), so a Workflow retry
+     * resumes from the last checkpoint.
      */
-    async executeChunk(request, _chunk, runtime = {}) {
+    async executeChunk(request, _chunk, runtime = {}, selfOrigin) {
         this.ensureTables();
+        // Before `subagentRuntime()`, which is where a host builds its model runtime
+        // — and a facet running on a provider it authenticates to mint-signed reads
+        // this origin from there.
+        this.selfOriginMemo.note(selfOrigin);
         const rt = this.subagentRuntime();
         const fingerprint = await fingerprintRequest(request);
         // A terminal result already exists → replay it (idempotent retry).

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";