@loopingai/core 0.1.0

package/dist/testing/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `@loopingai/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 `undici` and `node:fs`, so it lives behind
+ * `@loopingai/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 gateway-JWT signer, so the zero-trust
+ *   path can be exercised end to end without a real gateway.
+ */
+export { setupRecording, cassetteNameFor } from "./vcr-spec.js";
+export { VCR_CONTROL_ORIGIN, CASSETTE_NAME_RE } from "./vcr-shared.js";
+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 { doStorage, makeDoHelpers, type DoTestHelpers } from "./do.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChE,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAEvE,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"}

package/dist/testing/index.js

@@ -0,0 +1,31 @@
+/**
+ * `@loopingai/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 `undici` and `node:fs`, so it lives behind
+ * `@loopingai/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 gateway-JWT signer, so the zero-trust
+ *   path can be exercised end to end without a real gateway.
+ */
+export { setupRecording, cassetteNameFor } from "./vcr-spec.js";
+export { VCR_CONTROL_ORIGIN, CASSETTE_NAME_RE } from "./vcr-shared.js";
+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 { doStorage, makeDoHelpers } from "./do.js";
+//# sourceMappingURL=index.js.map

package/dist/testing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChE,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAEvE,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"}

package/dist/testing/mock-model.d.ts

@@ -0,0 +1,43 @@
+import { MockLanguageModelV3 } from "ai/test";
+export interface MockStep {
+    /**
+     * Assistant text for this step. On its own → finishReason "stop", which for the
+     * main-agent round is a *failed* attempt: prose is not an ending there, so use
+     * {@link finalReply} to script an answer. Alongside `toolCall` → the
+     * intermediate content emitted before a tool call.
+     */
+    text?: string;
+    /** Emit a tool call (finishReason "tool-calls"); may accompany `text`. */
+    toolCall?: {
+        toolName: string;
+        input?: unknown;
+    };
+    /**
+     * Emit several tool calls in **one** step, which a real model does whenever it
+     * decides two things at once. That is the only way to script the cases the round
+     * has to arbitrate: two different endings in one step (precedence decides), or
+     * the same ending twice (the tool's own `parse` decides).
+     */
+    toolCalls?: {
+        toolName: string;
+        input?: unknown;
+    }[];
+}
+/**
+ * A step where the main agent answers the user — the `final_reply` control call.
+ *
+ * Scripting a bare `{ text }` instead reproduces the bug this tool exists to catch
+ * (a model narrating rather than acting) and fails the attempt, which is what the
+ * error-path specs use it for.
+ */
+export declare function finalReply(text: string, opts?: {
+    text?: string;
+}): MockStep;
+/**
+ * A mock model that returns each step in sequence — one per `generateText` call.
+ * Uses the function form (with our own counter) rather than the array form, whose
+ * call-count indexing is off by one in this SDK version. Extra calls repeat the
+ * last step.
+ */
+export declare function mockModel(...steps: MockStep[]): MockLanguageModelV3;
+//# sourceMappingURL=mock-model.d.ts.map

package/dist/testing/mock-model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-model.d.ts","sourceRoot":"","sources":["../../src/testing/mock-model.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAc9C,MAAM,WAAW,QAAQ;IACvB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0EAA0E;IAC1E,QAAQ,CAAC,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IACjD;;;;;OAKG;IACH,SAAS,CAAC,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAAE,CAAC;CACrD;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CACxB,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAO,GAC3B,QAAQ,CAKV;AA+BD;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,GAAG,KAAK,EAAE,QAAQ,EAAE,GAAG,mBAAmB,CAKnE"}

package/dist/testing/mock-model.js

@@ -0,0 +1,62 @@
+import { MockLanguageModelV3 } from "ai/test";
+/**
+ * Test doubles for the LLM. Lets the tool-loop / executor specs run the real
+ * `generateText` machinery (tool execution, multi-step, fallback) against a
+ * scripted model with no network or `AI` binding.
+ */
+/** Zeroed usage block satisfying the LanguageModelV3 result shape. */
+const USAGE = {
+    inputTokens: { total: 0, noCache: 0, cacheRead: 0, cacheWrite: 0 },
+    outputTokens: { total: 0, text: 0, reasoning: 0 }
+};
+/**
+ * A step where the main agent answers the user — the `final_reply` control call.
+ *
+ * Scripting a bare `{ text }` instead reproduces the bug this tool exists to catch
+ * (a model narrating rather than acting) and fails the attempt, which is what the
+ * error-path specs use it for.
+ */
+export function finalReply(text, opts = {}) {
+    return {
+        ...(opts.text !== undefined ? { text: opts.text } : {}),
+        toolCall: { toolName: "final_reply", input: { text } }
+    };
+}
+function stepResult(step) {
+    const content = [];
+    // Keep the empty-string text part so a `{ text: "" }` step still yields "".
+    if (step.text !== undefined)
+        content.push({ type: "text", text: step.text });
+    const calls = [
+        ...(step.toolCall ? [step.toolCall] : []),
+        ...(step.toolCalls ?? [])
+    ];
+    for (const call of calls) {
+        content.push({
+            type: "tool-call",
+            toolCallId: crypto.randomUUID(),
+            toolName: call.toolName,
+            input: JSON.stringify(call.input ?? {})
+        });
+    }
+    const unified = calls.length > 0 ? "tool-calls" : "stop";
+    return {
+        content,
+        finishReason: { unified, raw: undefined },
+        usage: USAGE,
+        warnings: []
+    };
+}
+/**
+ * A mock model that returns each step in sequence — one per `generateText` call.
+ * Uses the function form (with our own counter) rather than the array form, whose
+ * call-count indexing is off by one in this SDK version. Extra calls repeat the
+ * last step.
+ */
+export function mockModel(...steps) {
+    let i = 0;
+    return new MockLanguageModelV3({
+        doGenerate: async () => stepResult(steps[Math.min(i++, steps.length - 1)])
+    });
+}
+//# sourceMappingURL=mock-model.js.map

package/dist/testing/mock-model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-model.js","sourceRoot":"","sources":["../../src/testing/mock-model.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAE9C;;;;GAIG;AAEH,sEAAsE;AACtE,MAAM,KAAK,GAAG;IACZ,WAAW,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE;IAClE,YAAY,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE;CAClD,CAAC;AAqBF;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CACxB,IAAY,EACZ,OAA0B,EAAE;IAE5B,OAAO;QACL,GAAG,CAAC,IAAI,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACvD,QAAQ,EAAE,EAAE,QAAQ,EAAE,aAAa,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,EAAE;KACvD,CAAC;AACJ,CAAC;AAED,SAAS,UAAU,CAAC,IAAc;IAChC,MAAM,OAAO,GAGT,EAAE,CAAC;IACP,4EAA4E;IAC5E,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS;QAAE,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;IAC7E,MAAM,KAAK,GAAG;QACZ,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACzC,GAAG,CAAC,IAAI,CAAC,SAAS,IAAI,EAAE,CAAC;KAC1B,CAAC;IACF,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,OAAO,CAAC,IAAI,CAAC;YACX,IAAI,EAAE,WAAW;YACjB,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE;YAC/B,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,KAAK,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;SACxC,CAAC,CAAC;IACL,CAAC;IACD,MAAM,OAAO,GACX,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAE,YAAsB,CAAC,CAAC,CAAE,MAAgB,CAAC;IACjE,OAAO;QACL,OAAO;QACP,YAAY,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,SAAS,EAAE;QACzC,KAAK,EAAE,KAAK;QACZ,QAAQ,EAAE,EAAE;KACb,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CAAC,GAAG,KAAiB;IAC5C,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,OAAO,IAAI,mBAAmB,CAAC;QAC7B,UAAU,EAAE,KAAK,IAAI,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC;KAC3E,CAAC,CAAC;AACL,CAAC"}

package/dist/testing/node.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `@loopingai/core/testing/node` — the **Node-realm** half of the VCR harness.
+ *
+ * Separate from `@loopingai/core/testing` because the two halves cannot share a
+ * module graph. This side imports `undici` and `node:fs`; the other side runs
+ * inside workerd, which has neither. `vcr-shared.ts` is the only thing both may
+ * touch, and it is deliberately dependency-free so it can load in either realm.
+ *
+ * Import this from a Vitest **config** (or anything else running in Node), never
+ * from a spec:
+ *
+ * ```ts
+ * // vitest.config.ts
+ * import { createVcrAgent } from "@loopingai/core/testing/node";
+ * ```
+ *
+ * For the common case — wiring cassette flush/teardown — you do not need this
+ * subpath at all. Point `globalSetup` at
+ * `@loopingai/core/testing/vcr-global-setup`, which is this module's `setup`/
+ * `teardown` pair already packaged for Vitest.
+ */
+export { createVcrAgent, closeVcr, VcrAgent, type CreateVcrAgentOptions } from "./vcr.js";
+export { VCR_CONTROL_ORIGIN, CASSETTE_NAME_RE } from "./vcr-shared.js";
+//# sourceMappingURL=node.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../src/testing/node.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EACL,cAAc,EACd,QAAQ,EACR,QAAQ,EACR,KAAK,qBAAqB,EAC3B,MAAM,UAAU,CAAC;AAElB,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/testing/node.js

@@ -0,0 +1,24 @@
+/**
+ * `@loopingai/core/testing/node` — the **Node-realm** half of the VCR harness.
+ *
+ * Separate from `@loopingai/core/testing` because the two halves cannot share a
+ * module graph. This side imports `undici` and `node:fs`; the other side runs
+ * inside workerd, which has neither. `vcr-shared.ts` is the only thing both may
+ * touch, and it is deliberately dependency-free so it can load in either realm.
+ *
+ * Import this from a Vitest **config** (or anything else running in Node), never
+ * from a spec:
+ *
+ * ```ts
+ * // vitest.config.ts
+ * import { createVcrAgent } from "@loopingai/core/testing/node";
+ * ```
+ *
+ * For the common case — wiring cassette flush/teardown — you do not need this
+ * subpath at all. Point `globalSetup` at
+ * `@loopingai/core/testing/vcr-global-setup`, which is this module's `setup`/
+ * `teardown` pair already packaged for Vitest.
+ */
+export { createVcrAgent, closeVcr, VcrAgent } from "./vcr.js";
+export { VCR_CONTROL_ORIGIN, CASSETTE_NAME_RE } from "./vcr-shared.js";
+//# sourceMappingURL=node.js.map

package/dist/testing/node.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.js","sourceRoot":"","sources":["../../src/testing/node.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EACL,cAAc,EACd,QAAQ,EACR,QAAQ,EAET,MAAM,UAAU,CAAC;AAElB,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/testing/vcr-global-setup.d.ts

@@ -0,0 +1,3 @@
+export declare function setup(): void;
+export declare function teardown(): Promise<void>;
+//# sourceMappingURL=vcr-global-setup.d.ts.map

package/dist/testing/vcr-global-setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vcr-global-setup.d.ts","sourceRoot":"","sources":["../../src/testing/vcr-global-setup.ts"],"names":[],"mappings":"AAKA,wBAAgB,KAAK,IAAI,IAAI,CAAG;AAEhC,wBAAsB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAE9C"}

package/dist/testing/vcr-global-setup.js

@@ -0,0 +1,9 @@
+import { closeVcr } from "./vcr.js";
+// Vitest globalSetup: the exported teardown runs after all tests but before Vite
+// tears down its server, so closing the VCR agent here (flush cassette, stop the
+// recorder timer, close real sockets) prevents the record-run hang.
+export function setup() { }
+export async function teardown() {
+    await closeVcr();
+}
+//# sourceMappingURL=vcr-global-setup.js.map

package/dist/testing/vcr-global-setup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vcr-global-setup.js","sourceRoot":"","sources":["../../src/testing/vcr-global-setup.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAEpC,iFAAiF;AACjF,iFAAiF;AACjF,oEAAoE;AACpE,MAAM,UAAU,KAAK,KAAU,CAAC;AAEhC,MAAM,CAAC,KAAK,UAAU,QAAQ;IAC5B,MAAM,QAAQ,EAAE,CAAC;AACnB,CAAC"}

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

@@ -0,0 +1,21 @@
+/**
+ * Constants shared between the two sides of the VCR harness that must NOT import
+ * each other: the Node-side agent (`vcr.ts`, imports `undici`) and the
+ * worker-side spec helper (`vcr-spec.ts`, runs in workerd). Keep this file
+ * dependency-free so both realms can load it.
+ */
+/**
+ * Reserved origin for the in-band control channel. A recorded spec `fetch`es
+ * here (via the single Miniflare `fetchMock`) to tell the Node-side agent which
+ * cassette is active for the current test — see `setupRecording` (vcr-spec.ts)
+ * and `VcrAgent` (vcr.ts). Never a real network host.
+ */
+export declare const VCR_CONTROL_ORIGIN = "https://vcr.internal";
+/**
+ * Cassette filenames are derived from kebab-cased file + describe + test names
+ * (see `cassetteNameFor`), so they are always lowercase `a-z0-9-` plus the
+ * `.snapshot.json` suffix. Enforced on the control channel as a path-traversal
+ * guard (no `/`, no `..`) before the name is joined to the snapshots dir.
+ */
+export declare const CASSETTE_NAME_RE: RegExp;
+//# sourceMappingURL=vcr-shared.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vcr-shared.d.ts","sourceRoot":"","sources":["../../src/testing/vcr-shared.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,yBAAyB,CAAC;AAEzD;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,QAAiC,CAAC"}

package/dist/testing/vcr-shared.js

@@ -0,0 +1,21 @@
+/**
+ * Constants shared between the two sides of the VCR harness that must NOT import
+ * each other: the Node-side agent (`vcr.ts`, imports `undici`) and the
+ * worker-side spec helper (`vcr-spec.ts`, runs in workerd). Keep this file
+ * dependency-free so both realms can load it.
+ */
+/**
+ * Reserved origin for the in-band control channel. A recorded spec `fetch`es
+ * here (via the single Miniflare `fetchMock`) to tell the Node-side agent which
+ * cassette is active for the current test — see `setupRecording` (vcr-spec.ts)
+ * and `VcrAgent` (vcr.ts). Never a real network host.
+ */
+export const VCR_CONTROL_ORIGIN = "https://vcr.internal";
+/**
+ * Cassette filenames are derived from kebab-cased file + describe + test names
+ * (see `cassetteNameFor`), so they are always lowercase `a-z0-9-` plus the
+ * `.snapshot.json` suffix. Enforced on the control channel as a path-traversal
+ * guard (no `/`, no `..`) before the name is joined to the snapshots dir.
+ */
+export const CASSETTE_NAME_RE = /^[a-z0-9-]+\.snapshot\.json$/;
+//# sourceMappingURL=vcr-shared.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vcr-shared.js","sourceRoot":"","sources":["../../src/testing/vcr-shared.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,sBAAsB,CAAC;AAEzD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,8BAA8B,CAAC"}

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

@@ -0,0 +1,17 @@
+import type { RunnerTestCase } from "vitest";
+/**
+ * Cassette filename for a test: `kebab(<file rel to test/, minus .spec.ts>)`
+ * then each describe level then the test name, all kebab-cased and joined by
+ * `--`, plus `.snapshot.json`. Example:
+ * `recipes-arc-game-recorded--arc-game-recorded-real-api--starts-a-real-game-and-closes-the-scorecard-on-abort.snapshot.json`.
+ * Exported for debugging / the cassette-rename step.
+ */
+export declare function cassetteNameFor(task: RunnerTestCase): string;
+/**
+ * Call once at the top of a recorded spec file (outside any `describe`). Adds
+ * per-test hooks that activate the test's cassette before it runs and release
+ * it after. A missing cassette **fails** the test with instructions to record
+ * (never skips — CI must go red so the gap is visible).
+ */
+export declare function setupRecording(): void;
+//# sourceMappingURL=vcr-spec.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vcr-spec.d.ts","sourceRoot":"","sources":["../../src/testing/vcr-spec.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAmB,MAAM,QAAQ,CAAC;AA0B9D;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,CAc5D;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,IAAI,IAAI,CA8BrC"}

package/dist/testing/vcr-spec.js

@@ -0,0 +1,72 @@
+import { beforeEach, afterEach } from "vitest";
+import { VCR_CONTROL_ORIGIN } from "./vcr-shared.js";
+/**
+ * Worker-side half of the VCR harness. `setupRecording()` is the *only* thing a
+ * recorded spec wires up: one call at the top of the file gives every `it` its
+ * own cassette, auto-named from the file + describe + test names, recorded under
+ * `RECORD=1` and replayed otherwise. No per-recipe config, no registry.
+ *
+ * How it reaches the Node-side agent: specs run in workerd (no filesystem), so
+ * the active cassette is announced over an in-band control channel — a `fetch`
+ * to {@link VCR_CONTROL_ORIGIN} that `VcrAgent` (test/helpers/vcr.ts) answers
+ * from the same Miniflare `fetchMock` every worker fetch already flows through.
+ */
+const kebab = (s) => s
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+/** The File task (root of the tree) carries `filepath`; describe suites don't. */
+function isFileTask(suite) {
+    return typeof suite.filepath === "string";
+}
+/**
+ * Cassette filename for a test: `kebab(<file rel to test/, minus .spec.ts>)`
+ * then each describe level then the test name, all kebab-cased and joined by
+ * `--`, plus `.snapshot.json`. Example:
+ * `recipes-arc-game-recorded--arc-game-recorded-real-api--starts-a-real-game-and-closes-the-scorecard-on-abort.snapshot.json`.
+ * Exported for debugging / the cassette-rename step.
+ */
+export function cassetteNameFor(task) {
+    const rel = task.file.filepath
+        .split(/[\\/]test[\\/]/)
+        .pop()
+        .replace(/\.spec\.ts$/, "");
+    const suites = [];
+    let suite = task.suite;
+    while (suite && !isFileTask(suite)) {
+        suites.unshift(suite.name);
+        suite = suite.suite;
+    }
+    return [rel, ...suites, task.name].map(kebab).join("--") + ".snapshot.json";
+}
+/**
+ * Call once at the top of a recorded spec file (outside any `describe`). Adds
+ * per-test hooks that activate the test's cassette before it runs and release
+ * it after. A missing cassette **fails** the test with instructions to record
+ * (never skips — CI must go red so the gap is visible).
+ */
+export function setupRecording() {
+    beforeEach(async (ctx) => {
+        const cassette = cassetteNameFor(ctx.task);
+        const res = await fetch(`${VCR_CONTROL_ORIGIN}/use?cassette=${cassette}`, {
+            method: "POST"
+        });
+        if (res.status === 404) {
+            throw new Error(`No VCR cassette "${cassette}". Record it with \`npm run test:record\` ` +
+                `(add \`-- -t "${ctx.task.name}"\` to record only this test), which ` +
+                `needs a real ARC_API_KEY in .env.test.`);
+        }
+        if (res.status === 409) {
+            throw new Error(`VCR cassette "${cassette}" could not activate: another recorded test is ` +
+                `already using the shared agent. Recorded specs must not run in ` +
+                `parallel — keep them sequential.`);
+        }
+        if (!res.ok) {
+            throw new Error(`VCR control channel error (HTTP ${res.status}) activating "${cassette}".`);
+        }
+    });
+    afterEach(async () => {
+        await fetch(`${VCR_CONTROL_ORIGIN}/release`, { method: "POST" });
+    });
+}
+//# sourceMappingURL=vcr-spec.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vcr-spec.js","sourceRoot":"","sources":["../../src/testing/vcr-spec.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AAE/C,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAErD;;;;;;;;;;GAUG;AAEH,MAAM,KAAK,GAAG,CAAC,CAAS,EAAU,EAAE,CAClC,CAAC;KACE,WAAW,EAAE;KACb,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC;KAC3B,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;AAE7B,kFAAkF;AAClF,SAAS,UAAU,CAAC,KAAsB;IACxC,OAAO,OAAQ,KAA+B,CAAC,QAAQ,KAAK,QAAQ,CAAC;AACvE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,IAAoB;IAClD,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ;SAC3B,KAAK,CAAC,gBAAgB,CAAC;SACvB,GAAG,EAAG;SACN,OAAO,CAAC,aAAa,EAAE,EAAE,CAAC,CAAC;IAE9B,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,IAAI,KAAK,GAAgC,IAAI,CAAC,KAAK,CAAC;IACpD,OAAO,KAAK,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;QACnC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC3B,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;IACtB,CAAC;IAED,OAAO,CAAC,GAAG,EAAE,GAAG,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,gBAAgB,CAAC;AAC9E,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc;IAC5B,UAAU,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE;QACvB,MAAM,QAAQ,GAAG,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC3C,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,kBAAkB,iBAAiB,QAAQ,EAAE,EAAE;YACxE,MAAM,EAAE,MAAM;SACf,CAAC,CAAC;QACH,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CACb,oBAAoB,QAAQ,4CAA4C;gBACtE,iBAAiB,GAAG,CAAC,IAAI,CAAC,IAAI,uCAAuC;gBACrE,wCAAwC,CAC3C,CAAC;QACJ,CAAC;QACD,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CACb,iBAAiB,QAAQ,iDAAiD;gBACxE,iEAAiE;gBACjE,kCAAkC,CACrC,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CACb,mCAAmC,GAAG,CAAC,MAAM,iBAAiB,QAAQ,IAAI,CAC3E,CAAC;QACJ,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,SAAS,CAAC,KAAK,IAAI,EAAE;QACnB,MAAM,KAAK,CAAC,GAAG,kBAAkB,UAAU,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACnE,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/testing/vcr.d.ts

@@ -0,0 +1,81 @@
+import { MockAgent, type Dispatcher } from "undici";
+export interface CreateVcrAgentOptions {
+    /** Absolute path of the cassettes directory (test/snapshots/). */
+    snapshotsDir: string;
+    /**
+     * true → every activated cassette records real traffic, unconditionally
+     * overwriting whatever was there (undici's `"record"` mode never loads or
+     * matches existing entries, unlike `"update"` — see {@link VcrAgent.agentFor}).
+     * false → replay.
+     */
+    record: boolean;
+    /** Hosts served by ordinary MockAgent interceptors, never VCR'd (the gateway JWKS). */
+    passthroughHosts: string[];
+    /** Request headers never written to a cassette (secrets: API keys, auth). */
+    excludeHeaders?: string[];
+    /** Headers stored but excluded from request matching (e.g. session cookies). */
+    ignoreHeaders?: string[];
+}
+/**
+ * The single agent Miniflare accepts as `fetchMock` (it allows only one), fanning
+ * outbound worker requests out by role:
+ *
+ *  - **Control channel** ({@link VCR_CONTROL_ORIGIN}) → ordinary MockAgent
+ *    interceptors whose reply callbacks flip the *active cassette*. This is how a
+ *    spec running in workerd (no filesystem) tells this Node-side agent which
+ *    test is running — see `setupRecording` (vcr-spec.ts).
+ *  - **Passthrough hosts** (the gateway JWKS) → ordinary MockAgent interceptors,
+ *    unchanged from before VCR existed.
+ *  - **Everything else, while a cassette is active** → that cassette's undici
+ *    {@link SnapshotAgent} record/replay. In playback a request with no matching
+ *    recording throws `No snapshot found` — offline, never the network.
+ *  - **Everything else, with no active cassette** → ordinary MockAgent behavior
+ *    (`disableNetConnect()` → offline error). A non-recorded test never reaches
+ *    the network.
+ *
+ * There is **no registry**: cassettes are keyed per test (file + describe + test
+ * name) by the spec helper, activated one at a time over the control channel. A
+ * new recorded spec touches only its own `.spec` file.
+ *
+ * Why `VcrAgent extends MockAgent` rather than `SnapshotAgent`: a `SnapshotAgent`'s
+ * `dispatch` fully overrides `MockAgent`'s (it never falls back to the interceptor
+ * path), so one `SnapshotAgent` cannot also serve the control/interceptor fixtures
+ * — and cannot serve more than one cassette. Keeping one internal `SnapshotAgent`
+ * per cassette and dispatching to the active one, with an ordinary
+ * `MockAgent.dispatch` fallback for control/passthrough/offline, leaves the
+ * interceptor path exactly as it always worked. Miniflare validates `fetchMock`
+ * with `instanceof MockAgent`, which `VcrAgent` satisfies directly.
+ */
+export declare class VcrAgent extends MockAgent {
+    #private;
+    constructor(options: CreateVcrAgentOptions);
+    dispatch(opts: Dispatcher.DispatchOptions, handler: Dispatcher.DispatchHandler): boolean;
+    /**
+     * Closes every cassette's `SnapshotAgent`, then this agent.
+     *
+     * Record mode: `SnapshotAgent.close()` saves each cassette, stops its
+     * recorder's auto-flush timer, and closes its real sockets — all required (see
+     * {@link closeVcr}). We then {@link stripVolatileFields} from each saved file
+     * so the committed cassette carries no `callCount`/`timestamp`.
+     *
+     * Playback mode: undici's `SnapshotAgent.close()` *unconditionally* re-saves
+     * the cassette, writing back the `callCount` its recorder mutates on every
+     * replay — the side effect that dirtied cassettes on a plain `npm test`. There
+     * is nothing to save and no real socket in playback, so we skip that save
+     * entirely and only stop each recorder's timers.
+     */
+    close(): Promise<void>;
+}
+export declare function createVcrAgent(options: CreateVcrAgentOptions): VcrAgent;
+/**
+ * Flush and close the active VCR agent (all its cassettes). In record mode,
+ * undici's recorder arms a self-refreshing, non-`unref`ed auto-flush timer and
+ * the real `SnapshotAgent` keeps sockets open — both keep the process alive
+ * after tests finish and trip Vitest's "close timed out" at teardown. Calling
+ * this (from a Vitest `globalSetup` teardown, which runs before Vite closes its
+ * own server) stops them. A no-op if no agent was created, and in playback only
+ * stops recorder timers — {@link VcrAgent.close} deliberately does not re-save
+ * the cassette there (see its doc).
+ */
+export declare function closeVcr(): Promise<void>;
+//# sourceMappingURL=vcr.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vcr.d.ts","sourceRoot":"","sources":["../../src/testing/vcr.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAiB,KAAK,UAAU,EAAE,MAAM,QAAQ,CAAC;AAmCnE,MAAM,WAAW,qBAAqB;IACpC,kEAAkE;IAClE,YAAY,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,MAAM,EAAE,OAAO,CAAC;IAChB,uFAAuF;IACvF,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,6EAA6E;IAC7E,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,gFAAgF;IAChF,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,QAAS,SAAQ,SAAS;;gBAWzB,OAAO,EAAE,qBAAqB;IA6E1C,QAAQ,CACN,IAAI,EAAE,UAAU,CAAC,eAAe,EAChC,OAAO,EAAE,UAAU,CAAC,eAAe,GAClC,OAAO;IAWV;;;;;;;;;;;;;OAaG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAW7B;AAED,wBAAgB,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,QAAQ,CAIvE;AAOD;;;;;;;;;GASG;AACH,wBAAsB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAM9C"}