@dynamicagents/core 0.9.0

package/dist/testing/auth.d.ts

@@ -0,0 +1,34 @@
+export interface GatekeeperTokenOptions {
+    /**
+     * Who the token is for. Defaults to an agent at the default RPC path
+     * (`${AGENT_ORIGIN}${A2A_RPC_PATH}`), which is what a gatekeeper mints: the
+     * agent's **endpoint**, not its origin.
+     *
+     * Pass this explicitly when a spec mounts an agent somewhere else — an agent
+     * at `/proactive/a2a` expects that string and refuses this default, which is
+     * the whole point of scoping the audience to the endpoint.
+     */
+    audience?: string;
+    issuer?: string;
+    /** Relative string ("5m"), absolute epoch seconds, or Date. Past values expire the token. */
+    expiresIn?: string | number | Date;
+    identity?: Record<string, unknown>;
+    /** Claim the identity is carried in. Defaults to core's `IDENTITY_CLAIM`. */
+    identityClaim?: string;
+    /**
+     * Which agent on the target origin this token authorizes, defaulting to
+     * `"main"`.
+     *
+     * The tenants of one deployment share an endpoint and therefore an audience,
+     * so this claim is the only thing distinguishing them. Set it to a *different*
+     * tenant than the request addresses to exercise the replay case; set it to
+     * `""` to mint a token carrying no tenant at all, which is rejected.
+     */
+    tenant?: string;
+    /** Claim the tenant is carried in. Defaults to core's `TENANT_CLAIM`. */
+    tenantClaim?: string;
+}
+/** The tenant `makeGatekeeperToken` authorizes unless a spec says otherwise. */
+export declare const TEST_TENANT = "main";
+/** Sign a short-lived EdDSA gatekeeper JWT using the test gatekeeper key. */
+export declare function makeGatekeeperToken(options?: GatekeeperTokenOptions): Promise<string>;

package/dist/testing/auth.js

@@ -0,0 +1,35 @@
+import { importJWK, SignJWT } from "jose";
+import { A2A_JWS_ALG, A2A_RPC_PATH, IDENTITY_CLAIM, TENANT_CLAIM, endpointUrl, jwksUrl } from "@dynamicagents/g2a-protocol";
+import { TEST_GATEKEEPER_PRIVATE_JWK, GATEKEEPER_ORIGIN, AGENT_ORIGIN } from "./fixtures.js";
+/** The tenant `makeGatekeeperToken` authorizes unless a spec says otherwise. */
+export const TEST_TENANT = "main";
+/** Sign a short-lived EdDSA gatekeeper JWT using the test gatekeeper key. */
+export async function makeGatekeeperToken(options = {}) {
+    const privateKey = await importJWK(TEST_GATEKEEPER_PRIVATE_JWK, "EdDSA");
+    const tenant = options.tenant ?? TEST_TENANT;
+    return (new SignJWT({
+        [options.identityClaim ?? IDENTITY_CLAIM]: options.identity ?? {
+            key: "custom:1:test-agent",
+            name: "Test Agent",
+            kind: "custom",
+            workspaceId: 1
+        },
+        // An empty tenant omits the claim entirely rather than signing `""` — that
+        // is the "gatekeeper too old to scope its tokens" case, and it must be
+        // rejected rather than treated as a wildcard.
+        ...(tenant ? { [options.tenantClaim ?? TENANT_CLAIM]: tenant } : {})
+    })
+        // Composed from `@dynamicagents/g2a-protocol`, the same package the real
+        // gatekeeper mints with. A fixture that agrees with the verifier but not with
+        // the issuer is worse than no fixture: the suite goes green on tokens
+        // nothing in production would ever send.
+        .setProtectedHeader({
+        alg: A2A_JWS_ALG,
+        kid: TEST_GATEKEEPER_PRIVATE_JWK.kid,
+        jku: jwksUrl(GATEKEEPER_ORIGIN)
+    })
+        .setIssuer(options.issuer ?? GATEKEEPER_ORIGIN)
+        .setAudience(options.audience ?? endpointUrl(AGENT_ORIGIN, A2A_RPC_PATH))
+        .setExpirationTime(options.expiresIn ?? "5m")
+        .sign(privateKey));
+}

package/dist/testing/do.d.ts

@@ -0,0 +1,29 @@
+import { AgentDB, type AgentDBOptions } from "../db/db.js";
+/**
+ * Durable Object test helpers.
+ *
+ * The predecessor hardcoded its own DO binding and exposed one `with*` wrapper
+ * per named `AgentDB` domain — including one for a domain that belonged to a
+ * plugin. Both are parameterized here: a consumer binds their namespace once,
+ * and {@link DoTestHelpers.withDb} hands over the whole `AgentDB` rather than
+ * pre-selecting a table.
+ */
+export interface DoTestHelpers<T extends Rpc.DurableObjectBranded | undefined> {
+    /** Fresh, unique DO stub per test — state never leaks between tests. */
+    freshStub(label: string): DurableObjectStub<T>;
+    /** Run `fn` inside a fresh DO instance with a migrated {@link AgentDB}. */
+    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
+ * callers don't repeat the assertion.
+ */
+export declare function doStorage(instance: unknown): DurableObjectStorage;
+/**
+ * Bind the helpers to a consumer's DO namespace.
+ *
+ * ```ts
+ * const { freshStub, withDb } = makeDoHelpers(env.MyAgent);
+ * ```
+ */
+export declare function makeDoHelpers<T extends Rpc.DurableObjectBranded | undefined = undefined>(ns: DurableObjectNamespace<T>, defaults?: AgentDBOptions): DoTestHelpers<T>;

package/dist/testing/do.js

@@ -0,0 +1,25 @@
+import { runInDurableObject } from "cloudflare:test";
+import { AgentDB } from "../db/db.js";
+/**
+ * `ctx` is protected in the DO type system but public at runtime. Cast once so
+ * callers don't repeat the assertion.
+ */
+export function doStorage(instance) {
+    return instance.ctx.storage;
+}
+/**
+ * Bind the helpers to a consumer's DO namespace.
+ *
+ * ```ts
+ * const { freshStub, withDb } = makeDoHelpers(env.MyAgent);
+ * ```
+ */
+export function makeDoHelpers(ns, defaults = { maxSubtasks: 8 }) {
+    const freshStub = (label) => ns.get(ns.idFromName(`test:${label}:${crypto.randomUUID()}`));
+    return {
+        freshStub,
+        withDb(label, fn) {
+            return runInDurableObject(freshStub(label), (instance) => fn(new AgentDB(doStorage(instance), defaults)));
+        }
+    };
+}

package/dist/testing/fake-session.d.ts

@@ -0,0 +1,26 @@
+import type { ToolSet } from "ai";
+import type { SessionMessage } from "agents/experimental/memory/session";
+import type { SessionLike } from "../agent/session.js";
+/**
+ * An in-memory {@link SessionLike} standing in for the DO's real continuous
+ * Session. Shared by the turn, decomposition, and composition specs so a change
+ * to the Session contract breaks in one place.
+ *
+ * Mirrors the two real behaviors the phased pipeline depends on:
+ *
+ * - `appendMessage` **dedupes by id** — appending an existing id is a no-op, the
+ *   property that makes deterministic-id appends exactly-once on a step re-run.
+ * - `getMessage` reads the raw stored message back.
+ */
+export declare class FakeSession implements SessionLike {
+    messages: SessionMessage[];
+    system: string;
+    /** Compaction overlays to report — non-empty ⇒ history has been displaced. */
+    compactions: unknown[];
+    appendMessage(m: SessionMessage): void;
+    getHistory(): Promise<SessionMessage[]>;
+    getMessage(id: string): Promise<SessionMessage | null>;
+    refreshSystemPrompt(): Promise<string>;
+    tools(): Promise<ToolSet>;
+    getCompactions(): Promise<unknown[]>;
+}

package/dist/testing/fake-session.js

@@ -0,0 +1,37 @@
+/**
+ * An in-memory {@link SessionLike} standing in for the DO's real continuous
+ * Session. Shared by the turn, decomposition, and composition specs so a change
+ * to the Session contract breaks in one place.
+ *
+ * Mirrors the two real behaviors the phased pipeline depends on:
+ *
+ * - `appendMessage` **dedupes by id** — appending an existing id is a no-op, the
+ *   property that makes deterministic-id appends exactly-once on a step re-run.
+ * - `getMessage` reads the raw stored message back.
+ */
+export class FakeSession {
+    messages = [];
+    system = "SOUL BLOCK\n\n## memory\n(empty)";
+    /** Compaction overlays to report — non-empty ⇒ history has been displaced. */
+    compactions = [];
+    appendMessage(m) {
+        if (this.messages.some((existing) => existing.id === m.id))
+            return;
+        this.messages.push(m);
+    }
+    async getHistory() {
+        return this.messages;
+    }
+    async getMessage(id) {
+        return this.messages.find((m) => m.id === id) ?? null;
+    }
+    async refreshSystemPrompt() {
+        return this.system;
+    }
+    async tools() {
+        return {};
+    }
+    async getCompactions() {
+        return this.compactions;
+    }
+}

package/dist/testing/fixtures.d.ts

@@ -0,0 +1,64 @@
+/**
+ * `@dynamicagents/core/testing/fixtures` — the **realm-neutral** slice of the
+ * harness: fixed keys, origins, and task/message builders.
+ *
+ * Its own subpath because it is the one part a consumer's `vitest.config.ts`
+ * needs, and that file runs in **Node**. The `/testing` barrel pulls in
+ * `cloudflare:test` (DO helpers) and `vitest` (the VCR spec hooks), so importing
+ * it from a config fails at load with `ERR_UNSUPPORTED_ESM_URL_SCHEME` before a
+ * single test runs. Nothing here imports either, so it is safe from a config, a
+ * spec, or a plain Node script.
+ *
+ * Seeding the required secrets from these values is the intended use:
+ *
+ * ```ts
+ * // vitest.config.ts
+ * import { GATEKEEPER_ORIGIN, TEST_AGENT_PRIVATE_JWK } from "@dynamicagents/core/testing/fixtures";
+ *
+ * process.env.A2A_SIGNING_KEY ??= JSON.stringify(TEST_AGENT_PRIVATE_JWK);
+ * process.env.GATEKEEPER_ORIGINS ??= JSON.stringify([GATEKEEPER_ORIGIN]);
+ * ```
+ */
+import { type JWK } from "jose";
+import { type Message, type Task, type TaskState } from "@a2a-js/sdk";
+/**
+ * A model pair for specs, and the only place one should be spelled.
+ *
+ * Core ships no model default — {@link ModelConfig.chatModelId} explains why —
+ * so every `resolveConfig` call needs one, including in tests. Without a shared
+ * fixture each spec invents its own id, and a suite full of invented ids is a
+ * suite that cannot tell "the config requires a model" from "this spec forgot
+ * one".
+ *
+ * The ids are deliberately obvious placeholders rather than real Workers AI
+ * models: nothing here reaches a binding, and a real id in a fixture is an
+ * invitation to copy it into an agent without deciding anything.
+ */
+export declare const TEST_MODELS: {
+    readonly chatModelId: "test:primary";
+    readonly fallbackChatModelId: "test:fallback";
+};
+/** The gatekeeper origin used in all tests. Must match vitest.config.ts and the MockAgent setup. */
+export declare const GATEKEEPER_ORIGIN = "https://gatekeeper.test";
+/** Agent origin matching `url.origin` for requests to `http://localhost`. */
+export declare const AGENT_ORIGIN = "http://localhost";
+/** Fixed Ed25519 private JWK used as A2A_SIGNING_KEY in tests. */
+export declare const TEST_AGENT_PRIVATE_JWK: JWK & {
+    kid: string;
+};
+/** Fixed Ed25519 private JWK for signing gatekeeper JWTs in tests. */
+export declare const TEST_GATEKEEPER_PRIVATE_JWK: JWK & {
+    kid: string;
+};
+/** Public JWKS the gatekeeper would serve at its `jku` (the private key minus `d`). */
+export declare function gatekeeperPublicJwks(): string;
+/**
+ * Build an A2A v1.0 `TaskStatus` for tests. The generated protobuf types require
+ * every field to be present (`message` included, holding `undefined` when there
+ * is none), so this keeps the specs from spelling that out each time.
+ */
+export declare function testStatus(state: TaskState, message?: Message): NonNullable<Task["status"]>;
+/** An agent-role `Message` carrying a single v1.0 text part. */
+export declare function testAgentMessage(messageId: string, text: string, contextId?: string, taskId?: string): Message;
+/** A complete v1.0 `Task` in the given state. */
+export declare function testTask(id: string, contextId: string, state: TaskState, message?: Message): Task;

package/dist/testing/fixtures.js

@@ -0,0 +1,104 @@
+/**
+ * `@dynamicagents/core/testing/fixtures` — the **realm-neutral** slice of the
+ * harness: fixed keys, origins, and task/message builders.
+ *
+ * Its own subpath because it is the one part a consumer's `vitest.config.ts`
+ * needs, and that file runs in **Node**. The `/testing` barrel pulls in
+ * `cloudflare:test` (DO helpers) and `vitest` (the VCR spec hooks), so importing
+ * it from a config fails at load with `ERR_UNSUPPORTED_ESM_URL_SCHEME` before a
+ * single test runs. Nothing here imports either, so it is safe from a config, a
+ * spec, or a plain Node script.
+ *
+ * Seeding the required secrets from these values is the intended use:
+ *
+ * ```ts
+ * // vitest.config.ts
+ * import { GATEKEEPER_ORIGIN, TEST_AGENT_PRIVATE_JWK } from "@dynamicagents/core/testing/fixtures";
+ *
+ * process.env.A2A_SIGNING_KEY ??= JSON.stringify(TEST_AGENT_PRIVATE_JWK);
+ * process.env.GATEKEEPER_ORIGINS ??= JSON.stringify([GATEKEEPER_ORIGIN]);
+ * ```
+ */
+import {} from "jose";
+import { Role } from "@a2a-js/sdk";
+/**
+ * A model pair for specs, and the only place one should be spelled.
+ *
+ * Core ships no model default — {@link ModelConfig.chatModelId} explains why —
+ * so every `resolveConfig` call needs one, including in tests. Without a shared
+ * fixture each spec invents its own id, and a suite full of invented ids is a
+ * suite that cannot tell "the config requires a model" from "this spec forgot
+ * one".
+ *
+ * The ids are deliberately obvious placeholders rather than real Workers AI
+ * models: nothing here reaches a binding, and a real id in a fixture is an
+ * invitation to copy it into an agent without deciding anything.
+ */
+export const TEST_MODELS = {
+    chatModelId: "test:primary",
+    fallbackChatModelId: "test:fallback"
+};
+/** The gatekeeper origin used in all tests. Must match vitest.config.ts and the MockAgent setup. */
+export const GATEKEEPER_ORIGIN = "https://gatekeeper.test";
+/** Agent origin matching `url.origin` for requests to `http://localhost`. */
+export const AGENT_ORIGIN = "http://localhost";
+/** Fixed Ed25519 private JWK used as A2A_SIGNING_KEY in tests. */
+export const TEST_AGENT_PRIVATE_JWK = {
+    crv: "Ed25519",
+    d: "sbR9EgZV1zUY-K6ENkvSLY8c8Q9kJ9NnxsXc4GVx_1g",
+    x: "1dXrUHeE89GBnZbd7MjzJK-3Xvu7khZCK9ZrQauZQ6s",
+    kty: "OKP",
+    kid: "test-agent-key-1"
+};
+/** Fixed Ed25519 private JWK for signing gatekeeper JWTs in tests. */
+export const TEST_GATEKEEPER_PRIVATE_JWK = {
+    crv: "Ed25519",
+    d: "OVKcn3LDH-qybNIdUbr7T9wbmlxNk2maU4_nILbaLKY",
+    x: "jYiAbquXL6db7RihLvp2nsp1ShAolDI0tGOjuwsZVnI",
+    kty: "OKP",
+    kid: "test-gk-key-1"
+};
+/** Public JWKS the gatekeeper would serve at its `jku` (the private key minus `d`). */
+export function gatekeeperPublicJwks() {
+    const { d: _d, ...pub } = TEST_GATEKEEPER_PRIVATE_JWK;
+    return JSON.stringify({ keys: [{ ...pub, use: "sig", alg: "EdDSA" }] });
+}
+/**
+ * Build an A2A v1.0 `TaskStatus` for tests. The generated protobuf types require
+ * every field to be present (`message` included, holding `undefined` when there
+ * is none), so this keeps the specs from spelling that out each time.
+ */
+export function testStatus(state, message) {
+    return { state, message, timestamp: new Date().toISOString() };
+}
+/** An agent-role `Message` carrying a single v1.0 text part. */
+export function testAgentMessage(messageId, text, contextId = "", taskId = "") {
+    return {
+        messageId,
+        contextId,
+        taskId,
+        role: Role.ROLE_AGENT,
+        parts: [
+            {
+                content: { $case: "text", value: text },
+                metadata: undefined,
+                filename: "",
+                mediaType: "text/plain"
+            }
+        ],
+        metadata: undefined,
+        extensions: [],
+        referenceTaskIds: []
+    };
+}
+/** A complete v1.0 `Task` in the given state. */
+export function testTask(id, contextId, state, message) {
+    return {
+        id,
+        contextId,
+        status: testStatus(state, message),
+        artifacts: [],
+        history: [],
+        metadata: undefined
+    };
+}

package/dist/testing/harness.d.ts

@@ -0,0 +1,97 @@
+import type { PlainTask } from "../a2a/task.js";
+/**
+ * Drive one A2A turn against a Worker the way a gatekeeper does.
+ *
+ * Core already shipped every *piece* of this — a token signer, Ed25519 fixtures,
+ * a fake session, a scripted model — and no assembly, so every consumer wrote the
+ * assembly themselves and got the same four things wrong first: the token's
+ * audience is the **endpoint** and not the origin, the tenant claim has to match
+ * the tenant in the body, `SendMessage` is refused without a push config, and the
+ * gatekeeper's own JWKS has to be reachable or verification fails before anything
+ * interesting happens.
+ *
+ * None of that is a property of any one agent, so none of it should be written
+ * more than once.
+ *
+ * ```ts
+ * const harness = createAgentHarness({ worker, env, tenant: "reactive" });
+ * using _ = harness.interceptGatekeeper();
+ *
+ * const accepted = await harness.send("what's the weather?");
+ * expect(accepted.status.state).toBe(TaskState.TASK_STATE_SUBMITTED);
+ * ```
+ *
+ * What it covers is the **synchronous accept**: everything from the gatekeeper's
+ * bearer token to the `submitted` Task the Worker returns. The turn itself runs
+ * in a Workflow the test runtime does not start, so assert on the callbacks with
+ * {@link AgentHarness.callbacks} while driving the workflow body directly with a
+ * fake `step`.
+ */
+/** The minimum of an `ExportedHandler` this harness calls. */
+export interface HarnessWorker<TEnv> {
+    fetch(request: Request, env: TEnv): Promise<Response> | Response;
+}
+export interface AgentHarnessOptions<TEnv> {
+    /** The Worker module under test — usually `import worker from "@/index"`. */
+    worker: HarnessWorker<TEnv>;
+    /** The `env` the pool built from `wrangler.jsonc`. */
+    env: TEnv;
+    /** Which agent to address. Must be a tenant the Worker mounts. */
+    tenant?: string;
+    /** Where the Worker serves JSON-RPC. Defaults to core's `/a2a`. */
+    rpcPath?: string;
+    /** The origin the Worker is addressed on. Defaults to the test fixture's. */
+    origin?: string;
+}
+/** One push notification the agent POSTed back, already decoded. */
+export interface CapturedCallback {
+    /** The `taskId` the callback was about. */
+    taskId: string;
+    /** The task state, e.g. `TASK_STATE_WORKING`. */
+    state: string;
+    /** The message text, joined across parts. `""` for a no-reply completion. */
+    text: string;
+    /** The per-task validation token echoed in the callback header. */
+    token: string | null;
+    /** The raw decoded body, for anything the projection above drops. */
+    body: unknown;
+}
+export interface AgentHarness {
+    /** The endpoint a token is minted for — the audience, not the origin. */
+    readonly endpoint: string;
+    /** The gatekeeper webhook the agent is told to call back on. */
+    readonly pushUrl: string;
+    /**
+     * Send one turn and return the accepted Task.
+     *
+     * Throws on a JSON-RPC error rather than returning it, so a spec asserting the
+     * happy path fails with the agent's own message instead of on a later
+     * `undefined`. Use {@link rpc} for the refusal cases.
+     */
+    send(text: string, options?: {
+        taskId?: string;
+    }): Promise<PlainTask>;
+    /**
+     * One raw JSON-RPC call with a valid gatekeeper token, returning the `Response`.
+     * For specs about what the edge *refuses*.
+     */
+    rpc(body: unknown, init?: {
+        token?: string;
+    }): Promise<Response>;
+    /** A valid gatekeeper token for this harness's tenant and endpoint. */
+    token(overrides?: {
+        tenant?: string;
+    }): Promise<string>;
+    /**
+     * Stub `fetch` so the gatekeeper's JWKS resolves and every push callback is
+     * captured instead of leaving the isolate.
+     *
+     * Returns a disposable — `using _ = harness.interceptGatekeeper()` — that restores
+     * the global on scope exit. Anything neither the JWKS nor the webhook 404s, so
+     * an unexpected outbound call fails loudly rather than hanging.
+     */
+    interceptGatekeeper(): Disposable;
+    /** Callbacks captured since {@link interceptGatekeeper}, in arrival order. */
+    readonly callbacks: CapturedCallback[];
+}
+export declare function createAgentHarness<TEnv>(options: AgentHarnessOptions<TEnv>): AgentHarness;

package/dist/testing/harness.js

@@ -0,0 +1,138 @@
+import { A2A_PROTOCOL_VERSION } from "@a2a-js/sdk";
+import { A2A_RPC_PATH, NOTIFICATION_TOKEN_HEADER, endpointUrl, jwksUrl } from "@dynamicagents/g2a-protocol";
+import { makeGatekeeperToken, TEST_TENANT } from "./auth.js";
+import { AGENT_ORIGIN, GATEKEEPER_ORIGIN, gatekeeperPublicJwks } 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 gatekeeper 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 gatekeeper would send.
+    const endpoint = endpointUrl(origin, rpcPath);
+    const tenant = options.tenant ?? TEST_TENANT;
+    const pushUrl = `${GATEKEEPER_ORIGIN}/a2a/push`;
+    const pushToken = "harness-push-token";
+    const callbacks = [];
+    const token = (overrides = {}) => makeGatekeeperToken({
+        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;
+        },
+        interceptGatekeeper() {
+            const original = globalThis.fetch;
+            globalThis.fetch = (async (input, init) => {
+                const url = typeof input === "string" ? input : String(input);
+                // The gatekeeper'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(GATEKEEPER_ORIGIN)) {
+                    return new Response(gatekeeperPublicJwks(), {
+                        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;
+                }
+            };
+        }
+    };
+}

package/dist/testing/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `@dynamicagents/core/testing` — the harness both predecessor agents grew, shipped so
+ * a consumer does not grow it a third time.
+ *
+ * Never import this from runtime code. It is a separate subpath precisely so it
+ * cannot reach a production bundle, and it pulls in `cloudflare:test`, which
+ * does not exist in a deployed Worker.
+ *
+ * **This barrel is the workerd half** — safe to import from a spec. The VCR
+ * recorder needs `node:fs`, so it lives behind `@dynamicagents/core/testing/node`
+ * and must not be re-exported here: pulling it into this graph would drag Node
+ * builtins into every spec that wanted a fixture. `vcr-shared.ts` is the seam
+ * both realms may load.
+ *
+ * Three things live here:
+ *
+ * - **VCR (spec side)** — `setupRecording()`, which names a cassette per test and
+ *   talks to the Node-side recorder over the in-band control channel.
+ * - **Fakes** — a `SessionLike` reference implementation and a scripted
+ *   `LanguageModel`, so a loop can be driven with no model call at all.
+ * - **Fixtures** — Ed25519 keypairs and a gatekeeper-JWT signer, so the zero-trust
+ *   path can be exercised end to end without a real gatekeeper.
+ */
+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, throwingModel, countingModel, rateLimitedModel, type MockStep } from "./mock-model.js";
+export { makeGatekeeperToken, type GatekeeperTokenOptions } from "./auth.js";
+export { AGENT_ORIGIN, GATEKEEPER_ORIGIN, TEST_AGENT_PRIVATE_JWK, TEST_GATEKEEPER_PRIVATE_JWK, TEST_MODELS, gatekeeperPublicJwks, 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";

package/dist/testing/index.js

@@ -0,0 +1,35 @@
+/**
+ * `@dynamicagents/core/testing` — the harness both predecessor agents grew, shipped so
+ * a consumer does not grow it a third time.
+ *
+ * Never import this from runtime code. It is a separate subpath precisely so it
+ * cannot reach a production bundle, and it pulls in `cloudflare:test`, which
+ * does not exist in a deployed Worker.
+ *
+ * **This barrel is the workerd half** — safe to import from a spec. The VCR
+ * recorder needs `node:fs`, so it lives behind `@dynamicagents/core/testing/node`
+ * and must not be re-exported here: pulling it into this graph would drag Node
+ * builtins into every spec that wanted a fixture. `vcr-shared.ts` is the seam
+ * both realms may load.
+ *
+ * Three things live here:
+ *
+ * - **VCR (spec side)** — `setupRecording()`, which names a cassette per test and
+ *   talks to the Node-side recorder over the in-band control channel.
+ * - **Fakes** — a `SessionLike` reference implementation and a scripted
+ *   `LanguageModel`, so a loop can be driven with no model call at all.
+ * - **Fixtures** — Ed25519 keypairs and a gatekeeper-JWT signer, so the zero-trust
+ *   path can be exercised end to end without a real gatekeeper.
+ */
+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";
+// `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 { makeGatekeeperToken } from "./auth.js";
+export { AGENT_ORIGIN, GATEKEEPER_ORIGIN, TEST_AGENT_PRIVATE_JWK, TEST_GATEKEEPER_PRIVATE_JWK, TEST_MODELS, gatekeeperPublicJwks, testAgentMessage, testStatus, testTask } from "./fixtures.js";
+export { doStorage, makeDoHelpers } from "./do.js";
+export { createAgentHarness } from "./harness.js";