@loopingai/core 0.3.0 → 0.4.0

package/dist/testing/harness.js

@@ -0,0 +1,139 @@
+import { A2A_PROTOCOL_VERSION } from "@a2a-js/sdk";
+import { A2A_RPC_PATH, NOTIFICATION_TOKEN_HEADER, endpointUrl, jwksUrl } from "@loopingai/a2a-protocol";
+import { makeGatewayToken, TEST_TENANT } from "./auth.js";
+import { AGENT_ORIGIN, GATEWAY_ORIGIN, gatewayPublicJwks } from "./fixtures.js";
+/**
+ * Project the push envelope onto the three fields a spec usually asserts.
+ *
+ * Reads `status.message.parts` — the key the wire form actually uses. It read
+ * `content` until `harness.spec.ts` drove a real callback through it, which
+ * made `text` the empty string on every capture: silently, since a harness
+ * reporting `""` for what an agent said looks exactly like an agent that said
+ * nothing, and the no-reply completion is a legitimate outcome.
+ */
+function projectCallback(body, token) {
+    const task = body.task ?? body;
+    const t = task;
+    const parts = t.status?.message?.parts ?? [];
+    return {
+        taskId: t.id ?? "",
+        state: t.status?.state ?? "",
+        text: parts
+            .map((p) => p.text ?? "")
+            .join("")
+            .trim(),
+        token,
+        body
+    };
+}
+export function createAgentHarness(options) {
+    const origin = options.origin ?? AGENT_ORIGIN;
+    const rpcPath = options.rpcPath ?? A2A_RPC_PATH;
+    // The audience a gateway actually mints: the endpoint this deployment serves,
+    // which is also exactly what its card advertises as its interface. Composed
+    // with the protocol package's own helper, so a harness cannot agree with the
+    // verifier while disagreeing with what a real gateway would send.
+    const endpoint = endpointUrl(origin, rpcPath);
+    const tenant = options.tenant ?? TEST_TENANT;
+    const pushUrl = `${GATEWAY_ORIGIN}/a2a/push`;
+    const pushToken = "harness-push-token";
+    const callbacks = [];
+    const token = (overrides = {}) => makeGatewayToken({
+        audience: endpoint,
+        tenant: overrides.tenant ?? tenant
+    });
+    const rpc = async (body, init = {}) => options.worker.fetch(new Request(endpoint, {
+        method: "POST",
+        headers: {
+            "content-type": "application/json",
+            "A2A-Version": A2A_PROTOCOL_VERSION,
+            authorization: `Bearer ${init.token ?? (await token())}`
+        },
+        body: JSON.stringify(body)
+    }), options.env);
+    return {
+        endpoint,
+        pushUrl,
+        callbacks,
+        token,
+        rpc,
+        async send(text, sendOptions = {}) {
+            const messageId = crypto.randomUUID();
+            const res = await rpc({
+                jsonrpc: "2.0",
+                id: 1,
+                method: "SendMessage",
+                // `SendMessageRequest` is **flat**: `tenant`, `message`, `configuration`,
+                // `metadata`. There is no `request` wrapper, and wrapping is silent when
+                // you do it — `fromJSON` drops unknown keys rather than rejecting them,
+                // so the whole turn decodes to an empty message with no push config and
+                // the agent refuses it for "missing" fields the caller did send.
+                //
+                // This harness shipped with exactly that envelope. Nothing caught it,
+                // because nothing in this package drove the harness against a real
+                // Worker until `harness.spec.ts` — which is the argument for that spec
+                // existing, made by the code it tests.
+                params: {
+                    tenant,
+                    message: {
+                        messageId,
+                        role: "ROLE_USER",
+                        // `parts`, not `content`. The decoded `Message` exposes `parts`, and
+                        // `fromJSON` silently yields an empty list for anything else — so a
+                        // turn sent under the wrong key arrives as a message with no text
+                        // and the agent answers a blank prompt.
+                        parts: [{ text }],
+                        ...(sendOptions.taskId ? { taskId: sendOptions.taskId } : {})
+                    },
+                    configuration: {
+                        // Required by the accept-and-notify contract: an agent that replies
+                        // out of band and is given nowhere to call back has accepted a turn
+                        // it can never answer.
+                        taskPushNotificationConfig: { url: pushUrl, token: pushToken }
+                    }
+                }
+            });
+            const envelope = await res.json();
+            if (envelope.error) {
+                throw new Error(`SendMessage was refused (${envelope.error.code}): ${envelope.error.message}`);
+            }
+            const result = envelope.result;
+            const task = (result?.task ?? result);
+            if (!task) {
+                throw new Error(`SendMessage returned no task: ${JSON.stringify(envelope)}`);
+            }
+            return task;
+        },
+        interceptGateway() {
+            const original = globalThis.fetch;
+            globalThis.fetch = (async (input, init) => {
+                const url = typeof input === "string" ? input : String(input);
+                // The gateway's public JWKS — without it every token fails to verify and
+                // every spec below it reports a 401 that has nothing to do with its subject.
+                if (url === jwksUrl(GATEWAY_ORIGIN)) {
+                    return new Response(gatewayPublicJwks(), {
+                        headers: { "content-type": "application/json" }
+                    });
+                }
+                if (url === pushUrl) {
+                    const request = new Request(input, init);
+                    const body = await request.json().catch(() => null);
+                    callbacks.push(projectCallback(body, request.headers.get(NOTIFICATION_TOKEN_HEADER)));
+                    return new Response(null, { status: 202 });
+                }
+                // Anything else is a call this harness did not expect. 404 rather than
+                // pass through: a spec that silently reaches the real network is a spec
+                // that passes for the wrong reason.
+                return new Response(`unexpected outbound fetch: ${url}`, {
+                    status: 404
+                });
+            });
+            return {
+                [Symbol.dispose]() {
+                    globalThis.fetch = original;
+                }
+            };
+        }
+    };
+}
+//# sourceMappingURL=harness.js.map

package/dist/testing/harness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"harness.js","sourceRoot":"","sources":["../../src/testing/harness.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EACL,YAAY,EACZ,yBAAyB,EACzB,WAAW,EACX,OAAO,EACR,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAgGhF;;;;;;;;GAQG;AACH,SAAS,eAAe,CACtB,IAAa,EACb,KAAoB;IAEpB,MAAM,IAAI,GAAI,IAA2B,CAAC,IAAI,IAAI,IAAI,CAAC;IACvD,MAAM,CAAC,GAAG,IAGT,CAAC;IACF,MAAM,KAAK,GAAG,CAAC,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,IAAI,EAAE,CAAC;IAC7C,OAAO;QACL,MAAM,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE;QAClB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,KAAK,IAAI,EAAE;QAC5B,IAAI,EAAE,KAAK;aACR,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC;aACxB,IAAI,CAAC,EAAE,CAAC;aACR,IAAI,EAAE;QACT,KAAK;QACL,IAAI;KACL,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,kBAAkB,CAChC,OAAkC;IAElC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,YAAY,CAAC;IAC9C,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,YAAY,CAAC;IAChD,8EAA8E;IAC9E,4EAA4E;IAC5E,6EAA6E;IAC7E,kEAAkE;IAClE,MAAM,QAAQ,GAAG,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9C,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,WAAW,CAAC;IAC7C,MAAM,OAAO,GAAG,GAAG,cAAc,WAAW,CAAC;IAC7C,MAAM,SAAS,GAAG,oBAAoB,CAAC;IACvC,MAAM,SAAS,GAAuB,EAAE,CAAC;IAEzC,MAAM,KAAK,GAAG,CAAC,YAAiC,EAAE,EAAE,EAAE,CACpD,gBAAgB,CAAC;QACf,QAAQ,EAAE,QAAQ;QAClB,MAAM,EAAE,SAAS,CAAC,MAAM,IAAI,MAAM;KACnC,CAAC,CAAC;IAEL,MAAM,GAAG,GAAG,KAAK,EACf,IAAa,EACb,OAA2B,EAAE,EACV,EAAE,CACrB,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,IAAI,OAAO,CAAC,QAAQ,EAAE;QACpB,MAAM,EAAE,MAAM;QACd,OAAO,EAAE;YACP,cAAc,EAAE,kBAAkB;YAClC,aAAa,EAAE,oBAAoB;YACnC,aAAa,EAAE,UAAU,IAAI,CAAC,KAAK,IAAI,CAAC,MAAM,KAAK,EAAE,CAAC,EAAE;SACzD;QACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;KAC3B,CAAC,EACF,OAAO,CAAC,GAAG,CACS,CAAC;IAEzB,OAAO;QACL,QAAQ;QACR,OAAO;QACP,SAAS;QACT,KAAK;QACL,GAAG;QAEH,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,WAAW,GAAG,EAAE;YAC/B,MAAM,SAAS,GAAG,MAAM,CAAC,UAAU,EAAE,CAAC;YACtC,MAAM,GAAG,GAAG,MAAM,GAAG,CAAC;gBACpB,OAAO,EAAE,KAAK;gBACd,EAAE,EAAE,CAAC;gBACL,MAAM,EAAE,aAAa;gBACrB,0EAA0E;gBAC1E,yEAAyE;gBACzE,wEAAwE;gBACxE,wEAAwE;gBACxE,iEAAiE;gBACjE,EAAE;gBACF,sEAAsE;gBACtE,mEAAmE;gBACnE,uEAAuE;gBACvE,uCAAuC;gBACvC,MAAM,EAAE;oBACN,MAAM;oBACN,OAAO,EAAE;wBACP,SAAS;wBACT,IAAI,EAAE,WAAW;wBACjB,qEAAqE;wBACrE,oEAAoE;wBACpE,kEAAkE;wBAClE,wCAAwC;wBACxC,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC;wBACjB,GAAG,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;qBAC9D;oBACD,aAAa,EAAE;wBACb,oEAAoE;wBACpE,oEAAoE;wBACpE,uBAAuB;wBACvB,0BAA0B,EAAE,EAAE,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE;qBAC/D;iBACF;aACF,CAAC,CAAC;YAEH,MAAM,QAAQ,GAAG,MAAM,GAAG,CAAC,IAAI,EAG3B,CAAC;YACL,IAAI,QAAQ,CAAC,KAAK,EAAE,CAAC;gBACnB,MAAM,IAAI,KAAK,CACb,4BAA4B,QAAQ,CAAC,KAAK,CAAC,IAAI,MAAM,QAAQ,CAAC,KAAK,CAAC,OAAO,EAAE,CAC9E,CAAC;YACJ,CAAC;YACD,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC;YAC/B,MAAM,IAAI,GAAG,CAAC,MAAM,EAAE,IAAI,IAAI,MAAM,CAA0B,CAAC;YAC/D,IAAI,CAAC,IAAI,EAAE,CAAC;gBACV,MAAM,IAAI,KAAK,CACb,iCAAiC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,CAC5D,CAAC;YACJ,CAAC;YACD,OAAO,IAAI,CAAC;QACd,CAAC;QAED,gBAAgB;YACd,MAAM,QAAQ,GAAG,UAAU,CAAC,KAAK,CAAC;YAClC,UAAU,CAAC,KAAK,GAAG,CAAC,KAAK,EACvB,KAAwB,EACxB,IAAkB,EACC,EAAE;gBACrB,MAAM,GAAG,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;gBAE9D,yEAAyE;gBACzE,6EAA6E;gBAC7E,IAAI,GAAG,KAAK,OAAO,CAAC,cAAc,CAAC,EAAE,CAAC;oBACpC,OAAO,IAAI,QAAQ,CAAC,iBAAiB,EAAE,EAAE;wBACvC,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;qBAChD,CAAC,CAAC;gBACL,CAAC;gBAED,IAAI,GAAG,KAAK,OAAO,EAAE,CAAC;oBACpB,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,KAAoB,EAAE,IAAI,CAAC,CAAC;oBACxD,MAAM,IAAI,GAAY,MAAM,OAAO,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;oBAC7D,SAAS,CAAC,IAAI,CACZ,eAAe,CACb,IAAI,EACJ,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,yBAAyB,CAAC,CAC/C,CACF,CAAC;oBACF,OAAO,IAAI,QAAQ,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC;gBAC7C,CAAC;gBAED,uEAAuE;gBACvE,wEAAwE;gBACxE,oCAAoC;gBACpC,OAAO,IAAI,QAAQ,CAAC,8BAA8B,GAAG,EAAE,EAAE;oBACvD,MAAM,EAAE,GAAG;iBACZ,CAAC,CAAC;YACL,CAAC,CAAiB,CAAC;YAEnB,OAAO;gBACL,CAAC,MAAM,CAAC,OAAO,CAAC;oBACd,UAAU,CAAC,KAAK,GAAG,QAAQ,CAAC;gBAC9B,CAAC;aACF,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/testing/index.d.ts

@@ -26,6 +26,7 @@ export { VCR_CONTROL_ORIGIN, VCR_MARKER_HEADER, CASSETTE_NAME_RE, type VcrReleas
 export { FakeSession } from "./fake-session.js";
 export { mockModel, finalReply, 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, gatewayPublicJwks, testAgentMessage, testStatus, testTask } from "./fixtures.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";
+export { createAgentHarness, type AgentHarness, type AgentHarnessOptions, type CapturedCallback, type HarnessWorker } from "./harness.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/testing/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EACL,cAAc,EACd,eAAe,EACf,KAAK,qBAAqB,EAC3B,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,KAAK,gBAAgB,EACtB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,KAAK,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAEvE,OAAO,EAAE,gBAAgB,EAAE,KAAK,mBAAmB,EAAE,MAAM,WAAW,CAAC;AACvE,OAAO,EACL,YAAY,EACZ,cAAc,EACd,sBAAsB,EACtB,wBAAwB,EACxB,iBAAiB,EACjB,gBAAgB,EAChB,UAAU,EACV,QAAQ,EACT,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,KAAK,aAAa,EAAE,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EACL,cAAc,EACd,eAAe,EACf,KAAK,qBAAqB,EAC3B,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,KAAK,gBAAgB,EACtB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,KAAK,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAEvE,OAAO,EAAE,gBAAgB,EAAE,KAAK,mBAAmB,EAAE,MAAM,WAAW,CAAC;AACvE,OAAO,EACL,YAAY,EACZ,cAAc,EACd,sBAAsB,EACtB,wBAAwB,EACxB,WAAW,EACX,iBAAiB,EACjB,gBAAgB,EAChB,UAAU,EACV,QAAQ,EACT,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,KAAK,aAAa,EAAE,MAAM,SAAS,CAAC;AAEvE,OAAO,EACL,kBAAkB,EAClB,KAAK,YAAY,EACjB,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,EACrB,KAAK,aAAa,EACnB,MAAM,cAAc,CAAC"}

package/dist/testing/index.js

@@ -26,6 +26,7 @@ export { VCR_CONTROL_ORIGIN, VCR_MARKER_HEADER, CASSETTE_NAME_RE } from "./vcr-s
 export { FakeSession } from "./fake-session.js";
 export { mockModel, finalReply } from "./mock-model.js";
 export { makeGatewayToken } from "./auth.js";
-export { AGENT_ORIGIN, GATEWAY_ORIGIN, TEST_AGENT_PRIVATE_JWK, TEST_GATEWAY_PRIVATE_JWK, gatewayPublicJwks, testAgentMessage, testStatus, testTask } from "./fixtures.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";
+export { createAgentHarness } from "./harness.js";
 //# sourceMappingURL=index.js.map

package/dist/testing/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EACL,cAAc,EACd,eAAe,EAEhB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAEjB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,SAAS,EAAE,UAAU,EAAiB,MAAM,iBAAiB,CAAC;AAEvE,OAAO,EAAE,gBAAgB,EAA4B,MAAM,WAAW,CAAC;AACvE,OAAO,EACL,YAAY,EACZ,cAAc,EACd,sBAAsB,EACtB,wBAAwB,EACxB,iBAAiB,EACjB,gBAAgB,EAChB,UAAU,EACV,QAAQ,EACT,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,SAAS,EAAE,aAAa,EAAsB,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EACL,cAAc,EACd,eAAe,EAEhB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAEjB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,SAAS,EAAE,UAAU,EAAiB,MAAM,iBAAiB,CAAC;AAEvE,OAAO,EAAE,gBAAgB,EAA4B,MAAM,WAAW,CAAC;AACvE,OAAO,EACL,YAAY,EACZ,cAAc,EACd,sBAAsB,EACtB,wBAAwB,EACxB,WAAW,EACX,iBAAiB,EACjB,gBAAgB,EAChB,UAAU,EACV,QAAQ,EACT,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,SAAS,EAAE,aAAa,EAAsB,MAAM,SAAS,CAAC;AAEvE,OAAO,EACL,kBAAkB,EAKnB,MAAM,cAAc,CAAC"}

package/dist/testing/vcr-store.d.ts

@@ -5,7 +5,7 @@ export interface RecordedRequest {
     headers: Record<string, string | string[]>;
     body: string;
 }
-/** A stored response. `body` is base64, as `SnapshotAgent` wrote it. */
+/** A stored response. `body` is base64, so a binary payload survives the file. */
 export interface RecordedResponse {
     statusCode: number;
     headers: Record<string, string | string[]>;
@@ -48,10 +48,10 @@ export declare function replayable(response: RecordedResponse): ReplayableRespon
  * One cassette file, loaded lazily and written only when it has changed.
  *
  * Playback is **read-only**: nothing here mutates on a replay, which is what
- * stops a plain `npm test` from dirtying committed cassettes. `SnapshotAgent`
- * persisted its `callCount` and re-saved on close, so every run left the files
- * modified; the equivalent counter here ({@link #calls}) is in memory and dies
- * with the process.
+ * stops a plain `npm test` from dirtying committed cassettes. The sequence
+ * counter ({@link #calls}) is in memory and dies with the process, deliberately
+ * — `SnapshotAgent` persisted its equivalent and re-saved on close, so every
+ * run left every cassette modified in git.
  */
 export declare class Cassette {
     #private;
@@ -60,16 +60,13 @@ export declare class Cassette {
     /** Every request in the file, as `METHOD url`, for error messages. */
     get recorded(): string[];
     /**
-     * Read the file into memory. Tolerates both shapes: `SnapshotAgent` wrapped
-     * each entry in `{ hash, snapshot: { request, responses } }`, this writes the
-     * same wrapper (so a re-record diffs cleanly against an old cassette) but
-     * ignores `hash`, `callCount` and `timestamp` — all three were volatile
-     * bookkeeping and none is needed to replay.
+     * Read the file into memory, keying each entry by its own request rather than
+     * trusting anything stored alongside it.
      *
-     * Entries are re-keyed on load rather than trusted, which is the point of the
-     * rewrite. Two legacy entries that differed *only* by a request header now
-     * collapse onto one key; their responses are concatenated in file order,
-     * which is exactly the sequential-response semantics {@link match} walks.
+     * Two entries that key the same are a mistake rather than a merge: a request
+     * that was issued twice belongs in one entry with two `responses`, which is
+     * what {@link match} walks. Saying so here turns a hand-edit slip into a named
+     * error instead of a replay that silently serves the wrong response second.
      */
     load(): void;
     /**
@@ -77,10 +74,9 @@ export declare class Cassette {
      * recorded.
      *
      * Repeated identical requests walk `responses` in order and then **hold on
-     * the last one**, matching what `SnapshotAgent` did
-     * (`responses[min(callCount, length - 1)]`). A recording that captured one
-     * response therefore replays it for every call, which is what a poll loop
-     * needs.
+     * the last one**, so a recording that captured a single response replays it
+     * for every call — which is what a poll loop needs when it runs a different
+     * number of times on replay than it did while recording.
      */
     match(method: string, url: string, body: string): ReplayableResponse | null;
     /** Append a live response. Repeats of a request extend its `responses`. */

package/dist/testing/vcr-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vcr-store.d.ts","sourceRoot":"","sources":["../../src/testing/vcr-store.ts"],"names":[],"mappings":"AAyBA,uFAAuF;AACvF,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;IAC3C,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wEAAwE;AACxE,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,eAAe,CAAC;IACzB,SAAS,EAAE,gBAAgB,EAAE,CAAC;CAC/B;AAsBD,qFAAqF;AACrF,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC;IAC5B,IAAI,EAAE,UAAU,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,iFAAiF;IACjF,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,sEAAsE;AACtE,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAG5E;AAaD;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,gBAAgB,GAAG,kBAAkB,CAazE;AAED;;;;;;;;GAQG;AACH,qBAAa,QAAQ;;gBASP,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB;IAOvD,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,sEAAsE;IACtE,IAAI,QAAQ,IAAI,MAAM,EAAE,CAIvB;IAED;;;;;;;;;;;OAWG;IACH,IAAI,IAAI,IAAI;IAiBZ;;;;;;;;;OASG;IACH,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI;IAW3E,2EAA2E;IAC3E,MAAM,CAAC,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,gBAAgB,GAAG,IAAI;IAqBlE,gFAAgF;IAChF,KAAK,IAAI,IAAI;CASd"}
+{"version":3,"file":"vcr-store.d.ts","sourceRoot":"","sources":["../../src/testing/vcr-store.ts"],"names":[],"mappings":"AAgCA,uFAAuF;AACvF,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;IAC3C,IAAI,EAAE,MAAM,CAAC;CACd;AAED,kFAAkF;AAClF,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,eAAe,CAAC;IACzB,SAAS,EAAE,gBAAgB,EAAE,CAAC;CAC/B;AAsBD,qFAAqF;AACrF,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC;IAC5B,IAAI,EAAE,UAAU,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,iFAAiF;IACjF,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,sEAAsE;AACtE,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAG5E;AAaD;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,gBAAgB,GAAG,kBAAkB,CAazE;AAED;;;;;;;;GAQG;AACH,qBAAa,QAAQ;;gBASP,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB;IAOvD,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,sEAAsE;IACtE,IAAI,QAAQ,IAAI,MAAM,EAAE,CAIvB;IAED;;;;;;;;OAQG;IACH,IAAI,IAAI,IAAI;IAoBZ;;;;;;;;OAQG;IACH,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI;IAW3E,2EAA2E;IAC3E,MAAM,CAAC,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,gBAAgB,GAAG,IAAI;IAqBlE,gFAAgF;IAChF,KAAK,IAAI,IAAI;CAOd"}

package/dist/testing/vcr-store.js

@@ -16,8 +16,15 @@
  * are still stored (minus secrets, see {@link CassetteOptions.excludeHeaders})
  * because they are useful to read in a diff, but they cannot break a replay.
  *
- * The on-disk format is deliberately unchanged from `SnapshotAgent`'s, so
- * cassettes recorded before this rewrite replay untouched — see {@link load}.
+ * The on-disk format owes `SnapshotAgent` nothing: a flat array of
+ * {@link CassetteEntry}. Cassettes it wrote are not readable, and deliberately
+ * so — its recorder keyed on `String(opts.body)`, and a Worker's POST body
+ * reaches a dispatcher as a `ReadableStream`, so every streamed request it ever
+ * captured stored the literal text `[object ReadableStream]` where the payload
+ * belonged. Those bodies are not recoverable from the file, and a reader that
+ * papered over it would have to match such entries on method + URL alone —
+ * quietly reintroducing the ambiguity this store exists to remove. Re-record
+ * instead.
  */
 import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
@@ -81,10 +88,10 @@ export function replayable(response) {
  * One cassette file, loaded lazily and written only when it has changed.
  *
  * Playback is **read-only**: nothing here mutates on a replay, which is what
- * stops a plain `npm test` from dirtying committed cassettes. `SnapshotAgent`
- * persisted its `callCount` and re-saved on close, so every run left the files
- * modified; the equivalent counter here ({@link #calls}) is in memory and dies
- * with the process.
+ * stops a plain `npm test` from dirtying committed cassettes. The sequence
+ * counter ({@link #calls}) is in memory and dies with the process, deliberately
+ * — `SnapshotAgent` persisted its equivalent and re-saved on close, so every
+ * run left every cassette modified in git.
  */
 export class Cassette {
     #file;
@@ -106,16 +113,13 @@ export class Cassette {
         return [...this.#entries.values()].map((e) => `${e.request.method} ${e.request.url}`);
     }
     /**
-     * Read the file into memory. Tolerates both shapes: `SnapshotAgent` wrapped
-     * each entry in `{ hash, snapshot: { request, responses } }`, this writes the
-     * same wrapper (so a re-record diffs cleanly against an old cassette) but
-     * ignores `hash`, `callCount` and `timestamp` — all three were volatile
-     * bookkeeping and none is needed to replay.
+     * Read the file into memory, keying each entry by its own request rather than
+     * trusting anything stored alongside it.
      *
-     * Entries are re-keyed on load rather than trusted, which is the point of the
-     * rewrite. Two legacy entries that differed *only* by a request header now
-     * collapse onto one key; their responses are concatenated in file order,
-     * which is exactly the sequential-response semantics {@link match} walks.
+     * Two entries that key the same are a mistake rather than a merge: a request
+     * that was issued twice belongs in one entry with two `responses`, which is
+     * what {@link match} walks. Saying so here turns a hand-edit slip into a named
+     * error instead of a replay that silently serves the wrong response second.
      */
     load() {
         if (!existsSync(this.#file))
@@ -124,16 +128,15 @@ export class Cassette {
         if (!Array.isArray(raw)) {
             throw new Error(`VCR cassette ${this.#file} is not a JSON array`);
         }
-        for (const item of raw) {
-            const entry = (item.snapshot ??
-                item);
+        for (const entry of raw) {
             const { request, responses } = entry;
             const key = requestKey(request.method, request.url, request.body ?? "");
-            const existing = this.#entries.get(key);
-            if (existing)
-                existing.responses.push(...responses);
-            else
-                this.#entries.set(key, { request, responses: [...responses] });
+            if (this.#entries.has(key)) {
+                throw new Error(`VCR cassette ${path.basename(this.#file)} has two entries for ` +
+                    `${request.method} ${request.url} with the same body. Put the ` +
+                    `responses in one entry's \`responses\` array instead.`);
+            }
+            this.#entries.set(key, { request, responses: [...responses] });
         }
     }
     /**
@@ -141,10 +144,9 @@ export class Cassette {
      * recorded.
      *
      * Repeated identical requests walk `responses` in order and then **hold on
-     * the last one**, matching what `SnapshotAgent` did
-     * (`responses[min(callCount, length - 1)]`). A recording that captured one
-     * response therefore replays it for every call, which is what a poll loop
-     * needs.
+     * the last one**, so a recording that captured a single response replays it
+     * for every call — which is what a poll loop needs when it runs a different
+     * number of times on replay than it did while recording.
      */
     match(method, url, body) {
         const key = requestKey(method, url, body);
@@ -182,9 +184,7 @@ export class Cassette {
         if (!this.#dirty)
             return;
         mkdirSync(path.dirname(this.#file), { recursive: true });
-        const entries = [...this.#entries.values()].map((snapshot) => ({
-            snapshot
-        }));
+        const entries = [...this.#entries.values()];
         writeFileSync(this.#file, `${JSON.stringify(entries, null, 2)}\n`);
         this.#dirty = false;
     }

package/dist/testing/vcr-store.js.map

@@ -1 +1 @@
-{"version":3,"file":"vcr-store.js","sourceRoot":"","sources":["../../src/testing/vcr-store.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"vcr-store.js","sourceRoot":"","sources":["../../src/testing/vcr-store.ts"],"names":[],"mappings":"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"}

package/dist/worker/define-agent.d.ts

@@ -0,0 +1,124 @@
+import type { AgentManifest } from "../a2a/card.js";
+import type { GatewayIdentity } from "../a2a/verify.js";
+import type { TaskAgent } from "../a2a/agent-stub.js";
+import { type AcceptedTurn } from "../a2a/executor.js";
+/**
+ * One agent's wiring, declared once.
+ *
+ * ## What this replaces
+ *
+ * Mounting an agent used to mean writing the same four things by hand and keeping
+ * them in agreement: a `getAgent(identity)` that guards `identity.key` and reads a
+ * Durable Object binding, a `startTurn` that derives an idempotent workflow id and
+ * swallows the already-exists race, an entry in the `tenants` map, and — in the
+ * agent's own Workflow entrypoint — a second reference to the same DO binding.
+ *
+ * Four copies of one fact, and only the first two were even adjacent. The wiring
+ * also type-checked when it was **wrong**: naming a sibling's workflow binding on
+ * a tenant compiles perfectly and fails at runtime, after auth, after the turn was
+ * accepted, as a task that simply never calls back.
+ *
+ * ```ts
+ * export const reactive = defineAgent({
+ *   tenant: "reactive",
+ *   manifest,
+ *   agent: (env: Env) => env.ReactiveAgent,
+ *   workflow: (env: Env) => env.HANDLE_TASK_WORKFLOW
+ * });
+ *
+ * // the Worker entry
+ * export default {
+ *   fetch: createA2AWorker<Env>({ manifest: hostManifest, agents: [reactive] })
+ * };
+ *
+ * // the agent's Workflow entrypoint
+ * await runHandleTask(event.payload, step, {
+ *   resolveAgent: (identity) => reactive.resolveAgent(this.env, identity),
+ *   …
+ * });
+ * ```
+ *
+ * ## Why accessors rather than binding names
+ *
+ * `agent` and `workflow` are functions of `env`, not strings. A string would have
+ * to be checked against `keyof Env` and then widened back to a namespace, which
+ * loses the Durable Object's own class — so the Workflow could not see the very
+ * methods it exists to drive. An accessor infers both: the tenant is mounted and
+ * the Workflow is driven from one declaration, `env.RactiveAgent` is a compile
+ * error, and `resolveAgent` comes back typed as the agent itself.
+ *
+ * `env` stays a parameter throughout, for the reason `src/env.ts` gives: core
+ * never reaches for a consumer's ambient bindings, and on Workers `env` does not
+ * exist at module scope anyway.
+ */
+/**
+ * What `createA2AWorker` needs in order to mount an agent. The Durable Object's
+ * own class is irrelevant to routing, so this shape forgets it —
+ * {@link AgentDefinition} keeps it for the agent's Workflow.
+ */
+export interface MountedAgent<TEnv> {
+    /** The tenant id a caller addresses this agent with. */
+    tenant: string;
+    /** The transport-independent half of this agent's card. */
+    manifest: AgentManifest;
+    resolveAgent(env: TEnv, identity: GatewayIdentity): TaskAgent;
+    startTurn(env: TEnv, turn: AcceptedTurn): Promise<void>;
+}
+/**
+ * {@link AgentDefinition} deliberately does **not** declare `extends
+ * MountedAgent`, even though every one satisfies it.
+ *
+ * A generic `DurableObjectStub<TAgent>` cannot be proven assignable to
+ * {@link TaskAgent} while `TAgent` is unresolved: the RPC stub type widens an
+ * *optional* method (`listTasks?`) to `Promise<undefined> | (…) => …`, and
+ * forcing the comparison also trips TypeScript's instantiation-depth limit — the
+ * same wall that made `PlainTask` necessary. At a concrete call site, where
+ * `TAgent` is a real agent class, the assignment resolves normally. So the check
+ * happens where it can actually succeed: passing `agents: [reactive]` to
+ * `createA2AWorker`.
+ */
+export interface DefineAgentOptions<TEnv, TAgent extends Rpc.DurableObjectBranded> {
+    /**
+     * The tenant id a caller addresses this agent with, and what a gateway
+     * registers against. Renaming one is a re-registration, not a refactor.
+     */
+    tenant: string;
+    /** The transport-independent half of this agent's card. */
+    manifest: AgentManifest;
+    /**
+     * This agent's Durable Object namespace. One instance per verified caller —
+     * the tenant picks the agent, `identity.key` picks which instance of it.
+     */
+    agent: (env: TEnv) => DurableObjectNamespace<TAgent>;
+    /** The Workflow this agent's turns run on. */
+    workflow: (env: TEnv) => Workflow<AcceptedTurn>;
+}
+export interface AgentDefinition<TEnv, TAgent extends Rpc.DurableObjectBranded> {
+    /** The tenant id a caller addresses this agent with. */
+    tenant: string;
+    /** The transport-independent half of this agent's card. */
+    manifest: AgentManifest;
+    /**
+     * Resolve the per-caller agent DO stub, keyed by the verified `identity.key`.
+     *
+     * Typed as the agent's **own** class, so the Workflow that drives its round
+     * methods reaches them through the same declaration the tenant is mounted with
+     * — the two cannot address different Durable Objects.
+     *
+     * Refuses a caller with no key rather than falling back to a shared instance:
+     * that key is what makes one caller's tasks unreachable from another's, so a
+     * missing one is a routing failure, not a default.
+     */
+    resolveAgent(env: TEnv, identity: GatewayIdentity): DurableObjectStub<TAgent>;
+    /**
+     * Start this agent's durable turn, idempotently.
+     *
+     * The instance id is derived from the gateway's `messageId`, which is stable
+     * across dispatch retries — so a retry finding its instance already running is
+     * the idempotency working, not a failure. {@link ignoreAlreadyExists} swallows
+     * exactly that race and rethrows everything else.
+     */
+    startTurn(env: TEnv, turn: AcceptedTurn): Promise<void>;
+}
+export declare function defineAgent<TEnv, TAgent extends Rpc.DurableObjectBranded>(options: DefineAgentOptions<TEnv, TAgent>): AgentDefinition<TEnv, TAgent>;
+//# sourceMappingURL=define-agent.d.ts.map

package/dist/worker/define-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-agent.d.ts","sourceRoot":"","sources":["../../src/worker/define-agent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAGL,KAAK,YAAY,EAClB,MAAM,oBAAoB,CAAC;AAE5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAEH;;;;GAIG;AACH,MAAM,WAAW,YAAY,CAAC,IAAI;IAChC,wDAAwD;IACxD,MAAM,EAAE,MAAM,CAAC;IACf,2DAA2D;IAC3D,QAAQ,EAAE,aAAa,CAAC;IACxB,YAAY,CAAC,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,eAAe,GAAG,SAAS,CAAC;IAC9D,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzD;AAED;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,kBAAkB,CACjC,IAAI,EACJ,MAAM,SAAS,GAAG,CAAC,oBAAoB;IAEvC;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,2DAA2D;IAC3D,QAAQ,EAAE,aAAa,CAAC;IACxB;;;OAGG;IACH,KAAK,EAAE,CAAC,GAAG,EAAE,IAAI,KAAK,sBAAsB,CAAC,MAAM,CAAC,CAAC;IACrD,8CAA8C;IAC9C,QAAQ,EAAE,CAAC,GAAG,EAAE,IAAI,KAAK,QAAQ,CAAC,YAAY,CAAC,CAAC;CACjD;AAED,MAAM,WAAW,eAAe,CAC9B,IAAI,EACJ,MAAM,SAAS,GAAG,CAAC,oBAAoB;IAEvC,wDAAwD;IACxD,MAAM,EAAE,MAAM,CAAC;IACf,2DAA2D;IAC3D,QAAQ,EAAE,aAAa,CAAC;IACxB;;;;;;;;;;OAUG;IACH,YAAY,CAAC,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,eAAe,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAAC;IAC9E;;;;;;;OAOG;IACH,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzD;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,SAAS,GAAG,CAAC,oBAAoB,EACvE,OAAO,EAAE,kBAAkB,CAAC,IAAI,EAAE,MAAM,CAAC,GACxC,eAAe,CAAC,IAAI,EAAE,MAAM,CAAC,CAsB/B"}

package/dist/worker/define-agent.js

@@ -0,0 +1,21 @@
+import { ignoreAlreadyExists, workflowIdForMessage } from "../a2a/executor.js";
+export function defineAgent(options) {
+    return {
+        tenant: options.tenant,
+        manifest: options.manifest,
+        resolveAgent(env, identity) {
+            if (!identity.key) {
+                throw new Error("identity.key is required to route to the agent DO");
+            }
+            const ns = options.agent(env);
+            return ns.get(ns.idFromName(identity.key));
+        },
+        startTurn(env, turn) {
+            return ignoreAlreadyExists(() => options.workflow(env).create({
+                id: workflowIdForMessage(turn.messageId),
+                params: { ...turn }
+            }));
+        }
+    };
+}
+//# sourceMappingURL=define-agent.js.map

package/dist/worker/define-agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-agent.js","sourceRoot":"","sources":["../../src/worker/define-agent.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EAErB,MAAM,oBAAoB,CAAC;AAmI5B,MAAM,UAAU,WAAW,CACzB,OAAyC;IAEzC,OAAO;QACL,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAE1B,YAAY,CAAC,GAAG,EAAE,QAAQ;YACxB,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC;gBAClB,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC;YACvE,CAAC;YACD,MAAM,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YAC9B,OAAO,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC;QAC7C,CAAC;QAED,SAAS,CAAC,GAAG,EAAE,IAAI;YACjB,OAAO,mBAAmB,CAAC,GAAG,EAAE,CAC9B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC;gBAC3B,EAAE,EAAE,oBAAoB,CAAC,IAAI,CAAC,SAAS,CAAC;gBACxC,MAAM,EAAE,EAAE,GAAG,IAAI,EAAE;aACpB,CAAC,CACH,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/worker/index.d.ts

@@ -2,6 +2,7 @@ import { type AgentManifest } from "../a2a/card.js";
 import { type TurnStarter } from "../a2a/executor.js";
 import type { AgentResolver } from "../a2a/agent-stub.js";
 import { type A2ASecretsEnv } from "../env.js";
+import type { MountedAgent } from "./define-agent.js";
 /**
  * The A2A Worker: the zero-trust, no-shared-secrets edge every Looping agent
  * puts in front of its Durable Object.
@@ -53,8 +54,17 @@ import { type A2ASecretsEnv } from "../env.js";
  * agent on it*. The second is what makes `tenant` more than an unauthenticated
  * routing hint in the request body.
  */
-/** Default path serving the card-signing public JWKS (the card's `jku`). */
-export declare const JWKS_PATH = "/.well-known/jwks.json";
+export { defineAgent, type AgentDefinition, type DefineAgentOptions, type MountedAgent } from "./define-agent.js";
+/**
+ * Default path serving the card-signing public JWKS (the card's `jku`).
+ *
+ * From `@loopingai/a2a-protocol`, because the gateway serves its own JWKS at
+ * the same path and fetches ours from whatever `jku` says — see
+ * {@link file://../a2a/verify.ts} for why the two sides share a package rather
+ * than a comment. Re-exported so this stays importable from
+ * `@loopingai/core/worker`, where it has always lived.
+ */
+export { JWKS_PATH } from "@loopingai/a2a-protocol";
 /** The two secrets a mount signs and verifies with, already read off `env`. */
 export interface A2ASecrets {
     /** Ed25519 private JWK, as JSON. See {@link A2ASecretsEnv.A2A_SIGNING_KEY}. */
@@ -88,7 +98,7 @@ export interface A2AWorkerOptions<TEnv = A2ASecretsEnv> {
      */
     manifest: AgentManifest;
     /**
-     * The agents on this origin, keyed by tenant id. At least one.
+     * The agents on this origin, keyed by tenant id.
      *
      * The id is opaque to the protocol — "an opaque string used for routing
      * requests to a specific agent or tenant when multiple agents are served
@@ -98,8 +108,23 @@ export interface A2AWorkerOptions<TEnv = A2ASecretsEnv> {
      * The tenant chooses *which agent*; the verified `identity.key` still chooses
      * *which instance of it*, so two callers of one tenant stay in separate
      * Durable Objects exactly as before.
+     *
+     * The escape hatch, and still fully supported: use it for an agent whose
+     * routing or turn-start is genuinely its own. {@link A2AWorkerOptions.agents}
+     * is the shorter form for the ordinary case. Supply at least one of the two.
+     */
+    tenants?: Record<string, TenantAgent>;
+    /**
+     * The agents on this origin, each declared once with
+     * {@link file://./define-agent.ts defineAgent}.
+     *
+     * Prefer this to {@link A2AWorkerOptions.tenants}: one declaration produces the
+     * tenant entry here *and* the resolver the agent's Workflow entrypoint uses, so
+     * the two cannot drift, and the binding names are type-constrained to bindings
+     * of the right kind. Merged over `tenants`, which is checked for duplicate
+     * tenant ids rather than silently overriding.
      */
-    tenants: Record<string, TenantAgent>;
+    agents?: readonly MountedAgent<TEnv>[];
     /** Path serving the public JWKS. Defaults to {@link JWKS_PATH}. */
     jwksPath?: string;
     /** Path this agent answers JSON-RPC on. Defaults to `/a2a`. */

package/dist/worker/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/worker/index.ts"],"names":[],"mappings":"AAOA,OAAO,EAOL,KAAK,aAAa,EACnB,MAAM,gBAAgB,CAAC;AAQxB,OAAO,EAAe,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEnE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAuB,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAEH,4EAA4E;AAC5E,eAAO,MAAM,SAAS,2BAA2B,CAAC;AAKlD,+EAA+E;AAC/E,MAAM,WAAW,UAAU;IACzB,+EAA+E;IAC/E,UAAU,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,iFAAiF;AACjF,MAAM,WAAW,WAAW;IAC1B,2DAA2D;IAC3D,QAAQ,EAAE,aAAa,CAAC;IACxB,uDAAuD;IACvD,YAAY,EAAE,aAAa,CAAC;IAC5B,4EAA4E;IAC5E,SAAS,EAAE,WAAW,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB,CAAC,IAAI,GAAG,aAAa;IACpD;;;;;;;;;;;;;OAaG;IACH,QAAQ,EAAE,aAAa,CAAC;IACxB;;;;;;;;;;;OAWG;IACH,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACrC,mEAAmE;IACnE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,IAAI,KAAK,UAAU,CAAC;IACpC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,GAAG,EAAE,GAAG,KAAK,MAAM,CAAC,CAAC;IAC3C;;;;OAIG;IACH,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC,6EAA6E;IAC7E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;;;;OASG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;OAOG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AA2ED;;;;;;;;;;;;;;;;;;GAkBG;AAEH,wBAAgB,eAAe,CAAC,IAAI,SAAS,aAAa,EACxD,OAAO,EAAE,gBAAgB,CAAC,IAAI,CAAC,GAC9B,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEtD,wBAAgB,eAAe,CAAC,IAAI,SAAS,MAAM,EACjD,OAAO,EAAE,gBAAgB,CAAC,IAAI,CAAC,GAAG;IAChC,OAAO,EAAE,CAAC,GAAG,EAAE,IAAI,KAAK,UAAU,CAAC;CACpC,GACA,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/worker/index.ts"],"names":[],"mappings":"AAQA,OAAO,EAOL,KAAK,aAAa,EACnB,MAAM,gBAAgB,CAAC;AAQxB,OAAO,EAAe,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEnE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAuB,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC;AACpE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAEH,OAAO,EACL,WAAW,EACX,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,YAAY,EAClB,MAAM,mBAAmB,CAAC;AAE3B;;;;;;;;GAQG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAKpD,+EAA+E;AAC/E,MAAM,WAAW,UAAU;IACzB,+EAA+E;IAC/E,UAAU,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,iFAAiF;AACjF,MAAM,WAAW,WAAW;IAC1B,2DAA2D;IAC3D,QAAQ,EAAE,aAAa,CAAC;IACxB,uDAAuD;IACvD,YAAY,EAAE,aAAa,CAAC;IAC5B,4EAA4E;IAC5E,SAAS,EAAE,WAAW,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB,CAAC,IAAI,GAAG,aAAa;IACpD;;;;;;;;;;;;;OAaG;IACH,QAAQ,EAAE,aAAa,CAAC;IACxB;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACtC;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,SAAS,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC;IACvC,mEAAmE;IACnE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,IAAI,KAAK,UAAU,CAAC;IACpC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,GAAG,EAAE,GAAG,KAAK,MAAM,CAAC,CAAC;IAC3C;;;;OAIG;IACH,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC,6EAA6E;IAC7E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;;;;OASG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;OAOG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AA2ED;;;;;;;;;;;;;;;;;;GAkBG;AAEH,wBAAgB,eAAe,CAAC,IAAI,SAAS,aAAa,EACxD,OAAO,EAAE,gBAAgB,CAAC,IAAI,CAAC,GAC9B,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEtD,wBAAgB,eAAe,CAAC,IAAI,SAAS,MAAM,EACjD,OAAO,EAAE,gBAAgB,CAAC,IAAI,CAAC,GAAG;IAChC,OAAO,EAAE,CAAC,GAAG,EAAE,IAAI,KAAK,UAAU,CAAC;CACpC,GACA,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC"}