@cef-ai/testing 0.1.0

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

@@ -0,0 +1,49 @@
+/**
+ * Typed model mocks for `ctx.models[alias]`.
+ *
+ * Two ways to use:
+ *
+ *   1. Plain stub — pass any object that implements `ModelHandle` (i.e.
+ *      `{ infer, stream }`) directly via `opts.models`. Simplest path,
+ *      good for one-off inputs.
+ *
+ *   2. Expectation form — `createModelMock()` returns a {@link ModelMockHandle}
+ *      with `.expect(input).respond(output)`. The next `infer` call
+ *      whose input deep-equals an expectation returns its output. Used
+ *      via `harness.models.<alias>.expect(...)` after construction.
+ *
+ * Expectations are matched by `JSON.stringify` deep-equality. That covers
+ * the typical "send-this-prompt → return-this-text" case without pulling
+ * in a deep-equal library; richer matching (regex, partial-match) lives
+ * outside D1.
+ */
+import type { ModelHandle } from "@cef-ai/agent-sdk";
+/**
+ * Mock handle returned by {@link createModelMock}. Behaves as a real
+ * `ModelHandle` for handler code, plus exposes `.expect()` and `.calls`
+ * for tests.
+ */
+export interface ModelMockHandle extends ModelHandle {
+    /** Register an expected input → output pair. Most-recent wins on duplicates. */
+    expect(input: unknown): {
+        respond: (output: unknown) => void;
+    };
+    /** Recorded invocations. */
+    calls: Array<{
+        method: "infer" | "stream";
+        input: unknown;
+    }>;
+}
+/**
+ * Build an expectation-style model mock. The same handle satisfies the
+ * runtime's `ModelHandle` shape so it can be passed via `opts.models`
+ * unchanged.
+ */
+export declare function createModelMock(): ModelMockHandle;
+/**
+ * Type-guard: does `m` look like a `ModelHandle`? Used by the harness to
+ * accept both expectation-style mocks and plain stubs in `opts.models`
+ * without forcing the user to wrap them.
+ */
+export declare function isModelHandle(m: unknown): m is ModelHandle;
+//# sourceMappingURL=model-mock.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"model-mock.d.ts","sourceRoot":"","sources":["../../src/harness/model-mock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD;;;;GAIG;AACH,MAAM,WAAW,eAAgB,SAAQ,WAAW;IAClD,gFAAgF;IAChF,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG;QAAE,OAAO,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAA;KAAE,CAAC;IAC/D,4BAA4B;IAC5B,KAAK,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,OAAO,GAAG,QAAQ,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CAC9D;AAED;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,eAAe,CAyCjD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,WAAW,CAM1D"}

package/dist/harness/model-mock.js

@@ -0,0 +1,56 @@
+/**
+ * Build an expectation-style model mock. The same handle satisfies the
+ * runtime's `ModelHandle` shape so it can be passed via `opts.models`
+ * unchanged.
+ */
+export function createModelMock() {
+    const expectations = [];
+    const calls = [];
+    const findOutput = (input) => {
+        // Walk in reverse so a later `.expect()` call shadows an earlier one
+        // when the same input is registered twice — the typical test pattern.
+        for (let i = expectations.length - 1; i >= 0; i--) {
+            const e = expectations[i];
+            if (JSON.stringify(e.input) === JSON.stringify(input)) {
+                return e.output;
+            }
+        }
+        throw new Error(`[modelMock] no expectation for input ${JSON.stringify(input)}`);
+    };
+    return {
+        calls,
+        expect(input) {
+            return {
+                respond(output) {
+                    expectations.push({ input, output });
+                },
+            };
+        },
+        async infer(input) {
+            calls.push({ method: "infer", input });
+            return findOutput(input);
+        },
+        async *stream(input) {
+            calls.push({ method: "stream", input });
+            const output = findOutput(input);
+            if (Array.isArray(output)) {
+                for (const c of output)
+                    yield c;
+            }
+            else {
+                yield output;
+            }
+        },
+    };
+}
+/**
+ * Type-guard: does `m` look like a `ModelHandle`? Used by the harness to
+ * accept both expectation-style mocks and plain stubs in `opts.models`
+ * without forcing the user to wrap them.
+ */
+export function isModelHandle(m) {
+    return (typeof m === "object" &&
+        m !== null &&
+        typeof m.infer === "function");
+}
+//# sourceMappingURL=model-mock.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"model-mock.js","sourceRoot":"","sources":["../../src/harness/model-mock.ts"],"names":[],"mappings":"AAiCA;;;;GAIG;AACH,MAAM,UAAU,eAAe;IAC7B,MAAM,YAAY,GAA+C,EAAE,CAAC;IACpE,MAAM,KAAK,GAA6B,EAAE,CAAC;IAE3C,MAAM,UAAU,GAAG,CAAC,KAAc,EAAW,EAAE;QAC7C,qEAAqE;QACrE,sEAAsE;QACtE,KAAK,IAAI,CAAC,GAAG,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YAClD,MAAM,CAAC,GAAG,YAAY,CAAC,CAAC,CAAE,CAAC;YAC3B,IAAI,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;gBACtD,OAAO,CAAC,CAAC,MAAM,CAAC;YAClB,CAAC;QACH,CAAC;QACD,MAAM,IAAI,KAAK,CACb,wCAAwC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAChE,CAAC;IACJ,CAAC,CAAC;IAEF,OAAO;QACL,KAAK;QACL,MAAM,CAAC,KAAK;YACV,OAAO;gBACL,OAAO,CAAC,MAAM;oBACZ,YAAY,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC;gBACvC,CAAC;aACF,CAAC;QACJ,CAAC;QACD,KAAK,CAAC,KAAK,CAAc,KAAc;YACrC,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;YACvC,OAAO,UAAU,CAAC,KAAK,CAAM,CAAC;QAChC,CAAC;QACD,KAAK,CAAC,CAAC,MAAM,CAAc,KAAc;YACvC,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC;YACxC,MAAM,MAAM,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;YACjC,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC1B,KAAK,MAAM,CAAC,IAAI,MAAM;oBAAE,MAAM,CAAM,CAAC;YACvC,CAAC;iBAAM,CAAC;gBACN,MAAM,MAAW,CAAC;YACpB,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,CAAU;IACtC,OAAO,CACL,OAAO,CAAC,KAAK,QAAQ;QACrB,CAAC,KAAK,IAAI;QACV,OAAQ,CAAyB,CAAC,KAAK,KAAK,UAAU,CACvD,CAAC;AACJ,CAAC"}

package/dist/harness/publish.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Capture-only `ctx.publish` collector for the test harness.
+ *
+ * The harness intercepts published events into a plain array (no router,
+ * no peer dispatch) so tests can assert against `harness.published`
+ * directly. Every entry is timestamped with the harness clock, so
+ * `advanceTime` shows up in assertions.
+ */
+/**
+ * A single captured publish call.
+ */
+export interface PublishedEvent {
+    type: string;
+    payload: unknown;
+    /** Stamped from the harness clock at publish time. */
+    ts: number;
+}
+export interface PublishCollector {
+    /** Backing array — exposed by the harness as `harness.published`. */
+    events: PublishedEvent[];
+    /** Drop-in for `ctx.publish`; matches the SDK's signature. */
+    publish: (type: string, payload: unknown) => Promise<void>;
+}
+/**
+ * Build a publish collector. `now()` is injected so the same clock
+ * driving event dispatch also stamps captured publishes.
+ */
+export declare function createPublishCollector(now: () => number): PublishCollector;
+//# sourceMappingURL=publish.d.ts.map

package/dist/harness/publish.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"publish.d.ts","sourceRoot":"","sources":["../../src/harness/publish.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,sDAAsD;IACtD,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,gBAAgB;IAC/B,qEAAqE;IACrE,MAAM,EAAE,cAAc,EAAE,CAAC;IACzB,8DAA8D;IAC9D,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5D;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,MAAM,GAAG,gBAAgB,CAM1E"}

package/dist/harness/publish.js

@@ -0,0 +1,20 @@
+/**
+ * Capture-only `ctx.publish` collector for the test harness.
+ *
+ * The harness intercepts published events into a plain array (no router,
+ * no peer dispatch) so tests can assert against `harness.published`
+ * directly. Every entry is timestamped with the harness clock, so
+ * `advanceTime` shows up in assertions.
+ */
+/**
+ * Build a publish collector. `now()` is injected so the same clock
+ * driving event dispatch also stamps captured publishes.
+ */
+export function createPublishCollector(now) {
+    const events = [];
+    const publish = async (type, payload) => {
+        events.push({ type, payload, ts: now() });
+    };
+    return { events, publish };
+}
+//# sourceMappingURL=publish.js.map

package/dist/harness/publish.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"publish.js","sourceRoot":"","sources":["../../src/harness/publish.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAmBH;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CAAC,GAAiB;IACtD,MAAM,MAAM,GAAqB,EAAE,CAAC;IACpC,MAAM,OAAO,GAAG,KAAK,EAAE,IAAY,EAAE,OAAgB,EAAiB,EAAE;QACtE,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;IAC5C,CAAC,CAAC;IACF,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;AAC7B,CAAC"}

package/dist/harness/replay.d.ts

@@ -0,0 +1,32 @@
+import type { TestCubby } from "./cubby.js";
+import type { PublishedEvent } from "./publish.js";
+export interface ReplayResult {
+    /** Events the agent published during this replay only (not including pre-replay state). */
+    published: PublishedEvent[];
+    /**
+     * Per-cubby table-rowcount summary: `{ alias: { tableName: rowCount } }`.
+     * Includes every user table (sqlite internal tables are filtered out).
+     */
+    cubbyState: Record<string, Record<string, number>>;
+    /** Wall-clock duration (`Date.now()` deltas, not the harness clock). */
+    durationMs: number;
+}
+/**
+ * Minimal harness surface `runReplay` needs. Kept structural so we don't
+ * import the full `TestHarness` type and create a circular reference.
+ */
+export interface ReplayHarness {
+    dispatch(input: {
+        type: string;
+        payload?: unknown;
+        from?: string;
+    }): Promise<PublishedEvent[]>;
+    published: PublishedEvent[];
+}
+/**
+ * Drive a JSONL fixture through `harness.dispatch`. Blank lines are
+ * skipped. Each non-blank line must parse to an object with at least a
+ * `type` field; `payload` and `from` are forwarded verbatim.
+ */
+export declare function runReplay(harness: ReplayHarness, jsonlPath: string, cubbies: Map<string, TestCubby>): Promise<ReplayResult>;
+//# sourceMappingURL=replay.d.ts.map

package/dist/harness/replay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay.d.ts","sourceRoot":"","sources":["../../src/harness/replay.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,MAAM,WAAW,YAAY;IAC3B,2FAA2F;IAC3F,SAAS,EAAE,cAAc,EAAE,CAAC;IAC5B;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACnD,wEAAwE;IACxE,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE;QACd,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;IAC9B,SAAS,EAAE,cAAc,EAAE,CAAC;CAC7B;AAED;;;;GAIG;AACH,wBAAsB,SAAS,CAC7B,OAAO,EAAE,aAAa,EACtB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,GAC9B,OAAO,CAAC,YAAY,CAAC,CAmDvB"}

package/dist/harness/replay.js

@@ -0,0 +1,72 @@
+/**
+ * JSONL fixture replay for the test harness.
+ *
+ * Reads a newline-delimited JSON file of platform-event envelopes (the
+ * format `prototype.md` §4 specifies for `<scope>/<context>/events/N-events.json`)
+ * and dispatches each through the harness, producing a quick at-a-glance
+ * summary of cubby row counts plus the events the agent emitted in
+ * response.
+ *
+ * Replay reuses `harness.dispatch`, which synthesizes fresh `id`/`ts`
+ * fields. We deliberately don't preserve the recorded ones — replay
+ * verifies *behavior* against a sequence of inputs, not exact metadata
+ * fidelity. If a future use case needs that, we can add a private
+ * `dispatchRaw` that takes a full Event envelope.
+ *
+ * `cubbyState` is a per-cubby table-rowcount summary: useful as a smoke
+ * check ("did the replay populate `history.messages` to N rows?") without
+ * forcing every test to write its own assertion query.
+ */
+import fs from "node:fs";
+import readline from "node:readline";
+/**
+ * Drive a JSONL fixture through `harness.dispatch`. Blank lines are
+ * skipped. Each non-blank line must parse to an object with at least a
+ * `type` field; `payload` and `from` are forwarded verbatim.
+ */
+export async function runReplay(harness, jsonlPath, cubbies) {
+    const start = Date.now();
+    const beforeLen = harness.published.length;
+    const stream = fs.createReadStream(jsonlPath, { encoding: "utf8" });
+    const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
+    let lineNo = 0;
+    for await (const line of rl) {
+        lineNo += 1;
+        if (!line.trim())
+            continue;
+        let event;
+        try {
+            event = JSON.parse(line);
+        }
+        catch (err) {
+            throw new Error(`[replay] invalid JSON on line ${lineNo} of ${jsonlPath}: ${err.message}`);
+        }
+        if (typeof event.type !== "string") {
+            throw new Error(`[replay] line ${lineNo}: missing or non-string "type" field`);
+        }
+        await harness.dispatch({
+            type: event.type,
+            payload: event.payload,
+            from: typeof event.from === "string" ? event.from : undefined,
+        });
+    }
+    const cubbyState = {};
+    for (const [alias, c] of cubbies) {
+        const tables = c.raw
+            .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'")
+            .all();
+        cubbyState[alias] = {};
+        for (const t of tables) {
+            // Identifier is sourced from sqlite_master, not user input; double-quote
+            // for safety against tables whose names happen to be SQL keywords.
+            const row = c.raw
+                .prepare(`SELECT count(*) AS n FROM "${t.name}"`)
+                .get();
+            cubbyState[alias][t.name] = row.n;
+        }
+    }
+    const published = harness.published.slice(beforeLen);
+    const durationMs = Date.now() - start;
+    return { published, cubbyState, durationMs };
+}
+//# sourceMappingURL=replay.js.map

package/dist/harness/replay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay.js","sourceRoot":"","sources":["../../src/harness/replay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,QAAQ,MAAM,eAAe,CAAC;AA6BrC;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,OAAsB,EACtB,SAAiB,EACjB,OAA+B;IAE/B,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACzB,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC,MAAM,CAAC;IAE3C,MAAM,MAAM,GAAG,EAAE,CAAC,gBAAgB,CAAC,SAAS,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;IACpE,MAAM,EAAE,GAAG,QAAQ,CAAC,eAAe,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,CAAC;IAC5E,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,IAAI,KAAK,EAAE,MAAM,IAAI,IAAI,EAAE,EAAE,CAAC;QAC5B,MAAM,IAAI,CAAC,CAAC;QACZ,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE;YAAE,SAAS;QAC3B,IAAI,KAA4D,CAAC;QACjE,IAAI,CAAC;YACH,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAiB,CAAC;QAC3C,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CACb,iCAAiC,MAAM,OAAO,SAAS,KAAM,GAAa,CAAC,OAAO,EAAE,CACrF,CAAC;QACJ,CAAC;QACD,IAAI,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YACnC,MAAM,IAAI,KAAK,CACb,iBAAiB,MAAM,sCAAsC,CAC9D,CAAC;QACJ,CAAC;QACD,MAAM,OAAO,CAAC,QAAQ,CAAC;YACrB,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,IAAI,EAAE,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS;SAC9D,CAAC,CAAC;IACL,CAAC;IAED,MAAM,UAAU,GAA2C,EAAE,CAAC;IAC9D,KAAK,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,IAAI,OAAO,EAAE,CAAC;QACjC,MAAM,MAAM,GAAG,CAAC,CAAC,GAAG;aACjB,OAAO,CACN,gFAAgF,CACjF;aACA,GAAG,EAA6B,CAAC;QACpC,UAAU,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC;QACvB,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;YACvB,yEAAyE;YACzE,mEAAmE;YACnE,MAAM,GAAG,GAAG,CAAC,CAAC,GAAG;iBACd,OAAO,CAAC,8BAA8B,CAAC,CAAC,IAAI,GAAG,CAAC;iBAChD,GAAG,EAAmB,CAAC;YAC1B,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC;QACpC,CAAC;IACH,CAAC;IAED,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IACrD,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC;IACtC,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,UAAU,EAAE,CAAC;AAC/C,CAAC"}

package/dist/harness/snapshot.d.ts

@@ -0,0 +1,44 @@
+/**
+ * In-memory snapshot/restore for the test harness.
+ *
+ * `captureSnapshot` serializes every cubby's SQLite database (via
+ * `db.serialize()`), shallow-copies the published-events array, and
+ * records the clock. `restoreSnapshot` rehydrates each cubby from its
+ * buffer, replaces the published array contents in place, and resets the
+ * clock — leaving the `TestHarness` object identity (and any references
+ * agents already hold) intact.
+ *
+ * Useful for fixture reuse: build a database state once, snapshot, then
+ * restore between scenarios without re-running migrations or replaying
+ * setup events.
+ */
+import Database from "better-sqlite3";
+import type { TestCubby } from "./cubby.js";
+import type { PublishedEvent } from "./publish.js";
+export interface HarnessSnapshot {
+    /** Per-alias serialized SQLite databases (via `better-sqlite3`'s `serialize()`). */
+    cubbies: Record<string, Buffer>;
+    /** Shallow copy of `harness.published` at snapshot time. */
+    published: PublishedEvent[];
+    /** Clock value (`harness.now()`) at snapshot time. */
+    clockNow: number;
+}
+/**
+ * Build a snapshot of the harness state. Cubby buffers are independent
+ * copies — subsequent writes to the harness do not mutate the snapshot.
+ */
+export declare function captureSnapshot(cubbies: Map<string, TestCubby>, published: PublishedEvent[], clockNow: number): HarnessSnapshot;
+/**
+ * Restore the harness to a previously captured snapshot.
+ *
+ *   - Cubbies present in `snap.cubbies` are reloaded from their buffers.
+ *     Aliases not in the snapshot are left untouched (so a snapshot taken
+ *     before a cubby was added doesn't accidentally drop it).
+ *   - The `published` array is mutated in place (length cleared, entries
+ *     re-pushed) so callers holding a reference to `harness.published`
+ *     observe the rollback without rebinding.
+ *   - `setClockNow` is invoked so the injected clock advances backward.
+ */
+export declare function restoreSnapshot(cubbies: Map<string, TestCubby>, published: PublishedEvent[], setClockNow: (n: number) => void, snap: HarnessSnapshot): void;
+export { Database };
+//# sourceMappingURL=snapshot.d.ts.map

package/dist/harness/snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.d.ts","sourceRoot":"","sources":["../../src/harness/snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,QAAQ,MAAM,gBAAgB,CAAC;AACtC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,MAAM,WAAW,eAAe;IAC9B,oFAAoF;IACpF,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,4DAA4D;IAC5D,SAAS,EAAE,cAAc,EAAE,CAAC;IAC5B,sDAAsD;IACtD,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,EAC/B,SAAS,EAAE,cAAc,EAAE,EAC3B,QAAQ,EAAE,MAAM,GACf,eAAe,CAWjB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,EAC/B,SAAS,EAAE,cAAc,EAAE,EAC3B,WAAW,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,EAChC,IAAI,EAAE,eAAe,GACpB,IAAI,CASN;AAID,OAAO,EAAE,QAAQ,EAAE,CAAC"}

package/dist/harness/snapshot.js

@@ -0,0 +1,58 @@
+/**
+ * In-memory snapshot/restore for the test harness.
+ *
+ * `captureSnapshot` serializes every cubby's SQLite database (via
+ * `db.serialize()`), shallow-copies the published-events array, and
+ * records the clock. `restoreSnapshot` rehydrates each cubby from its
+ * buffer, replaces the published array contents in place, and resets the
+ * clock — leaving the `TestHarness` object identity (and any references
+ * agents already hold) intact.
+ *
+ * Useful for fixture reuse: build a database state once, snapshot, then
+ * restore between scenarios without re-running migrations or replaying
+ * setup events.
+ */
+import Database from "better-sqlite3";
+/**
+ * Build a snapshot of the harness state. Cubby buffers are independent
+ * copies — subsequent writes to the harness do not mutate the snapshot.
+ */
+export function captureSnapshot(cubbies, published, clockNow) {
+    const out = {};
+    for (const [alias, c] of cubbies) {
+        out[alias] = c.serialize();
+    }
+    return {
+        cubbies: out,
+        // Copy each entry so post-snapshot mutation can't leak back.
+        published: published.map((e) => ({ ...e })),
+        clockNow,
+    };
+}
+/**
+ * Restore the harness to a previously captured snapshot.
+ *
+ *   - Cubbies present in `snap.cubbies` are reloaded from their buffers.
+ *     Aliases not in the snapshot are left untouched (so a snapshot taken
+ *     before a cubby was added doesn't accidentally drop it).
+ *   - The `published` array is mutated in place (length cleared, entries
+ *     re-pushed) so callers holding a reference to `harness.published`
+ *     observe the rollback without rebinding.
+ *   - `setClockNow` is invoked so the injected clock advances backward.
+ */
+export function restoreSnapshot(cubbies, published, setClockNow, snap) {
+    for (const [alias, buf] of Object.entries(snap.cubbies)) {
+        const c = cubbies.get(alias);
+        if (!c)
+            continue;
+        c.loadFromBuffer(buf);
+    }
+    published.length = 0;
+    for (const e of snap.published)
+        published.push({ ...e });
+    setClockNow(snap.clockNow);
+}
+// `Database` is re-exported for tests that want to instantiate a buffer
+// directly without pulling in a separate import.
+export { Database };
+//# sourceMappingURL=snapshot.js.map

package/dist/harness/snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.js","sourceRoot":"","sources":["../../src/harness/snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,QAAQ,MAAM,gBAAgB,CAAC;AAatC;;;GAGG;AACH,MAAM,UAAU,eAAe,CAC7B,OAA+B,EAC/B,SAA2B,EAC3B,QAAgB;IAEhB,MAAM,GAAG,GAA2B,EAAE,CAAC;IACvC,KAAK,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,IAAI,OAAO,EAAE,CAAC;QACjC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,CAAC;IAC7B,CAAC;IACD,OAAO;QACL,OAAO,EAAE,GAAG;QACZ,6DAA6D;QAC7D,SAAS,EAAE,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;QAC3C,QAAQ;KACT,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,eAAe,CAC7B,OAA+B,EAC/B,SAA2B,EAC3B,WAAgC,EAChC,IAAqB;IAErB,KAAK,MAAM,CAAC,KAAK,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QACxD,MAAM,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAC7B,IAAI,CAAC,CAAC;YAAE,SAAS;QACjB,CAAC,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC;IACxB,CAAC;IACD,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC;IACrB,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,SAAS;QAAE,SAAS,CAAC,IAAI,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;IACzD,WAAW,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;AAC7B,CAAC;AAED,wEAAwE;AACxE,iDAAiD;AACjD,OAAO,EAAE,QAAQ,EAAE,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { testAgent } from "./test-agent.js";
+export type { TestHarness, TestHarnessOptions, TestAgentMultiSpec, AgentCtor, PublishedEvent, CubbySpec, HarnessSnapshot, ReplayResult, } from "./test-agent.js";
+export { createModelMock } from "./harness/model-mock.js";
+export type { ModelMockHandle } from "./harness/model-mock.js";
+export type { FetchMock, FetchMatcher } from "./harness/fetch-mock.js";
+export { testPlatform, testWallet, mockAgent, fromMarketplace, } from "./test-platform.js";
+export type { TestPlatform, TestPlatformOptions, TestUser, TestWallet, UserAccessor, AgentClass, AgentSource, AgentRegistration, SingleAgentRegistration, MultiEngagementSpec, PlatformCubbySpec, AgentConnection, ConnectionEngagement, ConnectionManifest, Vault, VaultEvent, VaultScope, VaultStream, MockAgentDescriptor, MockAgentSpec, MockAgentSingleSpec, MockAgentMultiEngagementSpec, MockEngagementSpec, MockEngagementDescriptor, MockSettingSpec, Activity, ActivityStatus, Job, JobsFilter, JobState, } from "./test-platform.js";
+export type { Rule, Targeting, TargetingEngagement, } from "@cef-ai/agent-sdk";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,YAAY,EACV,WAAW,EACX,kBAAkB,EAClB,kBAAkB,EAClB,SAAS,EACT,cAAc,EACd,SAAS,EACT,eAAe,EACf,YAAY,GACb,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC1D,YAAY,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAE/D,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAEvE,OAAO,EACL,YAAY,EACZ,UAAU,EACV,SAAS,EACT,eAAe,GAChB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,YAAY,EACZ,mBAAmB,EACnB,QAAQ,EACR,UAAU,EACV,YAAY,EACZ,UAAU,EACV,WAAW,EACX,iBAAiB,EACjB,uBAAuB,EACvB,mBAAmB,EACnB,iBAAiB,EACjB,eAAe,EACf,oBAAoB,EACpB,kBAAkB,EAClB,KAAK,EACL,UAAU,EACV,UAAU,EACV,WAAW,EACX,mBAAmB,EACnB,aAAa,EACb,mBAAmB,EACnB,4BAA4B,EAC5B,kBAAkB,EAClB,wBAAwB,EACxB,eAAe,EACf,QAAQ,EACR,cAAc,EACd,GAAG,EACH,UAAU,EACV,QAAQ,GACT,MAAM,oBAAoB,CAAC;AAG5B,YAAY,EACV,IAAI,EACJ,SAAS,EACT,mBAAmB,GACpB,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export { testAgent } from "./test-agent.js";
+export { createModelMock } from "./harness/model-mock.js";
+export { testPlatform, testWallet, mockAgent, fromMarketplace, } from "./test-platform.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAY5C,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAK1D,OAAO,EACL,YAAY,EACZ,UAAU,EACV,SAAS,EACT,eAAe,GAChB,MAAM,oBAAoB,CAAC"}

package/dist/peers/from-marketplace.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `fromMarketplace(url)` — placeholder peer source that, in v2, will pull a
+ * published agent bundle from the CEF marketplace and load it into the
+ * simulator. v1 throws a clear error so test authors discover the limit
+ * immediately.
+ *
+ * Per the SDK plan (Task D4), the marker shape is reserved here so future
+ * work can add a `__fromMarketplace: true` descriptor without churning
+ * import paths in user tests.
+ */
+/**
+ * v1: not implemented. Throws synchronously with a self-explanatory message
+ * that names the URL the test attempted to load.
+ *
+ * v2 (future): fetch the bundle, materialise the agent class, and return a
+ * `MarketplaceAgentDescriptor` the platform recognises.
+ */
+export declare function fromMarketplace(url: string): never;
+//# sourceMappingURL=from-marketplace.d.ts.map

package/dist/peers/from-marketplace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"from-marketplace.d.ts","sourceRoot":"","sources":["../../src/peers/from-marketplace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAKlD"}

package/dist/peers/from-marketplace.js

@@ -0,0 +1,22 @@
+/**
+ * `fromMarketplace(url)` — placeholder peer source that, in v2, will pull a
+ * published agent bundle from the CEF marketplace and load it into the
+ * simulator. v1 throws a clear error so test authors discover the limit
+ * immediately.
+ *
+ * Per the SDK plan (Task D4), the marker shape is reserved here so future
+ * work can add a `__fromMarketplace: true` descriptor without churning
+ * import paths in user tests.
+ */
+/**
+ * v1: not implemented. Throws synchronously with a self-explanatory message
+ * that names the URL the test attempted to load.
+ *
+ * v2 (future): fetch the bundle, materialise the agent class, and return a
+ * `MarketplaceAgentDescriptor` the platform recognises.
+ */
+export function fromMarketplace(url) {
+    throw new Error(`[testPlatform] fromMarketplace("${url}") is not implemented in simulator mode (v1). ` +
+        `Use a typed Agent class or mockAgent() instead.`);
+}
+//# sourceMappingURL=from-marketplace.js.map

package/dist/peers/from-marketplace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"from-marketplace.js","sourceRoot":"","sources":["../../src/peers/from-marketplace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,GAAW;IACzC,MAAM,IAAI,KAAK,CACb,mCAAmC,GAAG,gDAAgD;QACpF,iDAAiD,CACpD,CAAC;AACJ,CAAC"}

package/dist/peers/mock-agent.d.ts

@@ -0,0 +1,108 @@
+/**
+ * `mockAgent({...})` — a lightweight, decoratorless agent peer for the
+ * multi-agent test platform.
+ *
+ * Use it when a test only needs a peer that publishes/echoes a fixed set of
+ * events; it's the "stunt double" alongside real, decorator-using agent
+ * classes. The `on` map plays the same role as `@OnEvent`: keys are event
+ * types, values are async handler functions invoked with the same
+ * `(event, ctx)` shape the runtime uses. `start` / `close` mirror the
+ * `@OnStart` / `@OnClose` lifecycle hooks.
+ *
+ * Two equivalent spec shapes (ADR-019 H4):
+ *
+ *   - Single-engagement shorthand: `mockAgent({ agentId, on, onStart?, onClose? })`
+ *     — produces one engagement with id `"default"`.
+ *   - Multi-engagement form: `mockAgent({ agentId, engagements: [...], targeting?, settings? })`
+ *     — each engagement has its own `on`/`onStart`/`onClose`; `targeting`
+ *     selects one at Job creation.
+ *
+ * Internally `testPlatform` recognises the descriptor by its
+ * `__mockAgent: true` tag and consumes a uniform normalised shape so dispatch
+ * code is unaware of single-vs-multi or class-vs-mock.
+ */
+import type { Context, Event, EngagementMeta, Targeting } from "@cef-ai/agent-sdk";
+/**
+ * Handler signatures the mock peer accepts. Mirrors the shape an
+ * `@OnEvent` method has (event, ctx) — `void` and `Promise<void>` are both
+ * fine since the runtime always awaits.
+ */
+export type MockEventHandler = (event: Event<unknown>, ctx: Context) => unknown | Promise<unknown>;
+/** Optional lifecycle hook for `mockAgent`. */
+export type MockLifecycleHandler = (ctx: Context, reason?: string) => unknown | Promise<unknown>;
+/** Settings schema entry (mirrors AgentConfig.settings shape). */
+export interface MockSettingSpec {
+    key: string;
+    type: "string" | "number" | "url" | "secret";
+    required?: boolean;
+    default?: unknown;
+}
+/** Single-engagement shorthand. */
+export interface MockAgentSingleSpec {
+    /** Stable agent id; matches what the platform connects under. */
+    agentId: string;
+    /** Map of event type → handler. Keys become the engagement's `handles`. */
+    on?: Record<string, MockEventHandler>;
+    /** Optional `@OnStart` equivalent. */
+    onStart?: MockLifecycleHandler;
+    /** Optional `@OnClose` equivalent. */
+    onClose?: MockLifecycleHandler;
+    /** Forward-looking: declared output types. The simulator does not enforce. */
+    publishes?: string[];
+}
+/** Per-engagement entry inside a multi-engagement mock spec. */
+export interface MockEngagementSpec {
+    id: string;
+    goal?: string;
+    on?: Record<string, MockEventHandler>;
+    onStart?: MockLifecycleHandler;
+    onClose?: MockLifecycleHandler;
+}
+/** Multi-engagement form (ADR-019 H4). */
+export interface MockAgentMultiEngagementSpec {
+    agentId: string;
+    engagements: MockEngagementSpec[];
+    /** Targeting decision table; defaults to `{ rules: [], default: <first id> }`. */
+    targeting?: Targeting;
+    /** Settings schema (forward-looking; simulator does not enforce). */
+    settings?: MockSettingSpec[];
+}
+/** Union accepted by `mockAgent(...)`. */
+export type MockAgentSpec = MockAgentSingleSpec | MockAgentMultiEngagementSpec;
+/**
+ * Per-engagement materialised entry on a {@link MockAgentDescriptor}. The
+ * `instance` is a synthetic object whose method names match `meta.events` /
+ * `meta.lifecycle` so the runtime can dispatch uniformly with class-based
+ * agents.
+ */
+export interface MockEngagementDescriptor {
+    id: string;
+    goal?: string;
+    instance: Record<string, unknown>;
+    meta: EngagementMeta;
+}
+/**
+ * Marker descriptor returned by {@link mockAgent}. The `__mockAgent` tag is
+ * how the platform tells a class peer apart from a mock peer at registration
+ * time. The descriptor exposes a normalised, post-validation shape so
+ * downstream consumers don't have to discriminate single vs multi.
+ */
+export interface MockAgentDescriptor {
+    readonly __mockAgent: true;
+    agentId: string;
+    engagements: MockEngagementDescriptor[];
+    targeting: Targeting;
+    settings?: MockSettingSpec[];
+}
+/**
+ * Build a {@link MockAgentDescriptor} from a spec. The returned object is
+ * what callers pass into `testPlatform({ agents: { foo: mockAgent({...}) } })`.
+ *
+ * The single-engagement shorthand is normalised to a one-element
+ * `engagements` array with id `"default"` and a degenerate targeting table,
+ * so consumers always see the same shape.
+ */
+export declare function mockAgent(spec: MockAgentSpec): MockAgentDescriptor;
+/** Type-guard used by `testPlatform` to dispatch on source kind. */
+export declare function isMockAgentDescriptor(value: unknown): value is MockAgentDescriptor;
+//# sourceMappingURL=mock-agent.d.ts.map

package/dist/peers/mock-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-agent.d.ts","sourceRoot":"","sources":["../../src/peers/mock-agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EACV,OAAO,EACP,KAAK,EACL,cAAc,EACd,SAAS,EACV,MAAM,mBAAmB,CAAC;AAE3B;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAC7B,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,EACrB,GAAG,EAAE,OAAO,KACT,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAEhC,+CAA+C;AAC/C,MAAM,MAAM,oBAAoB,GAAG,CACjC,GAAG,EAAE,OAAO,EACZ,MAAM,CAAC,EAAE,MAAM,KACZ,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAEhC,kEAAkE;AAClE,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,KAAK,GAAG,QAAQ,CAAC;IAC7C,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,mCAAmC;AACnC,MAAM,WAAW,mBAAmB;IAClC,iEAAiE;IACjE,OAAO,EAAE,MAAM,CAAC;IAChB,2EAA2E;IAC3E,EAAE,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IACtC,sCAAsC;IACtC,OAAO,CAAC,EAAE,oBAAoB,CAAC;IAC/B,sCAAsC;IACtC,OAAO,CAAC,EAAE,oBAAoB,CAAC;IAC/B,8EAA8E;IAC9E,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,gEAAgE;AAChE,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,EAAE,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IACtC,OAAO,CAAC,EAAE,oBAAoB,CAAC;IAC/B,OAAO,CAAC,EAAE,oBAAoB,CAAC;CAChC;AAED,0CAA0C;AAC1C,MAAM,WAAW,4BAA4B;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,kBAAkB,EAAE,CAAC;IAClC,kFAAkF;IAClF,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,qEAAqE;IACrE,QAAQ,CAAC,EAAE,eAAe,EAAE,CAAC;CAC9B;AAED,0CAA0C;AAC1C,MAAM,MAAM,aAAa,GAAG,mBAAmB,GAAG,4BAA4B,CAAC;AAE/E;;;;;GAKG;AACH,MAAM,WAAW,wBAAwB;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,IAAI,EAAE,cAAc,CAAC;CACtB;AAED;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,WAAW,EAAE,IAAI,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,wBAAwB,EAAE,CAAC;IACxC,SAAS,EAAE,SAAS,CAAC;IACrB,QAAQ,CAAC,EAAE,eAAe,EAAE,CAAC;CAC9B;AAiDD;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,aAAa,GAAG,mBAAmB,CAgElE;AAED,oEAAoE;AACpE,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,mBAAmB,CAM9B"}