@cef-ai/testing 0.1.0

package/README.md

@@ -0,0 +1,132 @@
+# @cef-ai/testing
+
+Simulator harness for CEF agents — `testAgent` for single-agent in-process
+tests, `testPlatform` for multi-agent tests with a vault simulation.
+
+## Install
+
+```sh
+pnpm add -D @cef-ai/testing
+```
+
+Import the harness directly from `@cef-ai/testing` in test files:
+
+```ts
+import { testAgent, testPlatform } from "@cef-ai/testing";
+```
+
+## `testAgent` quickstart
+
+`testAgent(AgentClass, opts)` constructs an in-memory simulator around a
+single agent class. It wires `ctx.cubby` to per-alias SQLite, `ctx.fetch`
+to a URL-pattern mock, `ctx.models[alias]` to stubs, and `ctx.publish` to a
+collector you can assert on.
+
+```ts
+import { describe, it, expect, afterEach } from "vitest";
+import { testAgent, type TestHarness } from "@cef-ai/testing";
+import Echo from "../src/agent.js";
+
+describe("echo", () => {
+  let h: TestHarness | undefined;
+  afterEach(() => h?.dispose());
+
+  it("acks user_message", async () => {
+    h = testAgent(Echo, {
+      cubbies: [{ alias: "history", migrations: "./migrations/history" }],
+    });
+    const events = await h.dispatch({
+      type: "user_message",
+      payload: { text: "hello" },
+    });
+    expect(events.map((e) => e.type)).toContain("ack");
+  });
+});
+```
+
+## `testPlatform` quickstart
+
+`testPlatform({ agents, models, ... })` lifts the harness into a multi-agent
+world: each agent runs in its own simulator, a shared vault routes events
+between them, and the test drives interactions through `vault.agents` /
+`vault.events`. Use this when an agent talks to peers or when an
+application client (your "app") publishes into the vault.
+
+```ts
+import { describe, it, expect, afterEach } from "vitest";
+import { testPlatform, createModelMock, type TestPlatform } from "@cef-ai/testing";
+import Assistant from "../agent/src/assistant.js";
+
+describe("assistant + app", () => {
+  let p: TestPlatform | undefined;
+  afterEach(() => p?.dispose());
+
+  it("answers a user message", async () => {
+    const llm = createModelMock();
+    llm.expect({ prompt: "hi" }).respond({ text: "hello back" });
+
+    p = testPlatform({
+      agents: {
+        assistant: {
+          source: Assistant,
+          cubbies: [{ alias: "history", migrations: "./migrations/history" }],
+        },
+      },
+      models: { llm },
+    });
+
+    await p.vault.agents.connect({ agentId: "assistant" });
+    // ...drive the vault, assert published events / cubby state
+  });
+});
+```
+
+## API summary
+
+| Symbol | Returns | Notes |
+| --- | --- | --- |
+| `testAgent(AgentClass, opts?)` | `TestHarness` | Single-agent simulator. Reads `AGENT_METADATA` to find decorated handlers. |
+| `testPlatform(opts)` | `TestPlatform` | Multi-agent simulator with a shared vault, model registry, and per-agent cubbies. |
+| `mockAgent(spec)` | `MockAgentDescriptor` | Peer descriptor for `testPlatform` — drop in for an agent you don't want to bring into the test bundle. |
+| `fromMarketplace(url)` | `MockAgentDescriptor` | v1: throws (not yet wired). v2: will fetch a published bundle. |
+| `createModelMock()` | `ModelMockHandle` | Expectation-builder model handle: `mock.expect(input).respond(output)`. |
+
+`TestHarness` exposes:
+
+- `dispatch({ type, payload, from? })` — drive a single event; returns the
+  publishes from this call.
+- `published` — every publish since construction (cumulative log).
+- `cubby(alias)` — `CubbyHandle` for assertions.
+- `runInCubby(alias, fn)` — run with both the public handle and the raw
+  `better-sqlite3` database for sync, prepared-statement assertions.
+- `start()` / `close(reason?)` — drive `@OnStart` / `@OnClose`.
+- `lifecycle` — `{ state: "idle" | "started" | "closed", terminalReason?: ... }`.
+- `snapshot()` / `restore(snap)` — capture and restore cubbies + clock +
+  publish log.
+- `replay(jsonlPath)` — feed a JSONL fixture of events through the harness.
+- `advanceTime(ms)` / `now()` — manipulate the injected clock.
+- `fetchMock()` — URL-pattern fetch mock attached to `ctx.fetch`.
+- `models` — the model handle map attached to `ctx.models`.
+- `dispose()` — release SQLite handles. Idempotent.
+
+`TestPlatform` exposes:
+
+- `vault` — the simulated vault (`agents.connect`, event streams, scoped
+  per-conversation channels).
+- `runInCubby(agentId, alias, fn)` — assert on a specific agent's cubby.
+- `dispose()` — tear down every per-agent simulator.
+
+## Companion packages
+
+- [`@cef-ai/agent-sdk`](../agent-sdk) — the decorators and types the harness
+  is testing.
+- [`@cef-ai/cli`](../cli) — `cef build` / `cef typegen` for the build that
+  these tests run alongside.
+
+## References
+
+- Agent SDK spec: `../../../company-memory-bank/specs/platform/03-components/agent-sdk.md` §9 (testing surface).
+- Runtime integration contract: `../../../company-memory-bank/specs/platform/03-components/sdk-runtime-integration-contract.md`.
+
+The `../company-memory-bank/...` paths point at an internal sibling repo
+and are not browsable from a fresh clone.

package/dist/harness/clock.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Injectable test clock used by the `testAgent` harness.
+ *
+ * The harness threads `clock.now()` through every place the runtime would
+ * normally read `Date.now()` (event timestamps, `published[].ts`, etc.) so
+ * tests can pin time deterministically and step it forward via
+ * `advanceTime(ms)`.
+ *
+ * We deliberately do NOT monkey-patch the global `Date` or `Date.now` —
+ * staying off the globals keeps the harness composable with vitest's own
+ * fake timers and other test utilities the user might bring.
+ */
+export interface TestClock {
+    /** Current time in unix-millis. */
+    now(): number;
+    /** Move the clock forward by `ms` milliseconds. */
+    advanceTime(ms: number): void;
+    /** Set the clock to an absolute unix-millis. Used by `restoreSnapshot`. */
+    setNow(ms: number): void;
+}
+/**
+ * Build a {@link TestClock}. Defaults to the real wall-clock time at
+ * construction so unspecified-time tests still produce sane timestamps.
+ */
+export declare function createClock(initial?: number): TestClock;
+//# sourceMappingURL=clock.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"clock.d.ts","sourceRoot":"","sources":["../../src/harness/clock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,SAAS;IACxB,mCAAmC;IACnC,GAAG,IAAI,MAAM,CAAC;IACd,mDAAmD;IACnD,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,2EAA2E;IAC3E,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAWvD"}

package/dist/harness/clock.js

@@ -0,0 +1,17 @@
+/**
+ * Build a {@link TestClock}. Defaults to the real wall-clock time at
+ * construction so unspecified-time tests still produce sane timestamps.
+ */
+export function createClock(initial) {
+    let t = initial ?? Date.now();
+    return {
+        now: () => t,
+        advanceTime: (ms) => {
+            t += ms;
+        },
+        setNow: (ms) => {
+            t = ms;
+        },
+    };
+}
+//# sourceMappingURL=clock.js.map

package/dist/harness/clock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock.js","sourceRoot":"","sources":["../../src/harness/clock.ts"],"names":[],"mappings":"AAqBA;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,OAAgB;IAC1C,IAAI,CAAC,GAAG,OAAO,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;IAC9B,OAAO;QACL,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC;QACZ,WAAW,EAAE,CAAC,EAAU,EAAE,EAAE;YAC1B,CAAC,IAAI,EAAE,CAAC;QACV,CAAC;QACD,MAAM,EAAE,CAAC,EAAU,EAAE,EAAE;YACrB,CAAC,GAAG,EAAE,CAAC;QACT,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/harness/cubby.d.ts

@@ -0,0 +1,57 @@
+/**
+ * In-memory `better-sqlite3` cubby for the test harness.
+ *
+ * Each declared cubby alias gets its own isolated `:memory:` database, so
+ * tests don't bleed state across agents within a single run and don't
+ * require fixture cleanup. Migrations are read from a directory of `.sql`
+ * files (sorted lexicographically and applied in order) — the same shape
+ * the production runtime uses.
+ *
+ * Note on `exec` semantics: better-sqlite3's `prepare()` only accepts a
+ * single statement, but `db.exec()` handles multi-statement scripts. We
+ * use the latter for migration loading, but keep the public
+ * `CubbyHandle.exec` (single-statement DML with parameter binding) on
+ * top of `prepare().run()` so the surface matches the production runtime
+ * exactly.
+ *
+ * `TestCubby` is implemented as a class (rather than a closure-based
+ * factory) so `query`/`exec` always read `this.raw` at call time. That
+ * lets `loadFromBuffer` swap the underlying database — needed by the
+ * `snapshot`/`restore` machinery — without invalidating the `CubbyHandle`
+ * references the agent already holds.
+ */
+import Database from "better-sqlite3";
+import type { CubbyHandle } from "@cef-ai/agent-sdk";
+/**
+ * Per-alias test cubby — extends the public {@link CubbyHandle} with
+ * disposal hooks the harness uses for teardown.
+ */
+export declare class TestCubby implements CubbyHandle {
+    /** Underlying database — exposed for advanced harness extensions (e.g. `runInCubby`). */
+    raw: Database.Database;
+    /** Alias for diagnostics. */
+    readonly alias: string;
+    private closed;
+    constructor(alias: string, migrationsDir?: string);
+    query<T = unknown>(sql: string, params?: unknown[]): Promise<T[]>;
+    exec(sql: string, params?: unknown[]): Promise<{
+        changes: number;
+        lastInsertRowid: number | bigint;
+    }>;
+    /** Serialize the database to a Buffer (powers `harness.snapshot()`). */
+    serialize(): Buffer;
+    /**
+     * Replace the underlying database from a serialized buffer. The previous
+     * handle is closed first. Existing `CubbyHandle` references stay valid
+     * because `query`/`exec` read `this.raw` lazily.
+     */
+    loadFromBuffer(buf: Buffer): void;
+    /** Release the SQLite handle. Idempotent. */
+    close(): void;
+}
+/**
+ * Factory that mirrors the original closure-based API. Equivalent to
+ * `new TestCubby(alias, migrationsDir)`.
+ */
+export declare function createCubby(alias: string, migrationsDir?: string): TestCubby;
+//# sourceMappingURL=cubby.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cubby.d.ts","sourceRoot":"","sources":["../../src/harness/cubby.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,QAAQ,MAAM,gBAAgB,CAAC;AAGtC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD;;;GAGG;AACH,qBAAa,SAAU,YAAW,WAAW;IAC3C,yFAAyF;IACzF,GAAG,EAAE,QAAQ,CAAC,QAAQ,CAAC;IACvB,6BAA6B;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,MAAM,CAAS;gBAEX,KAAK,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM;IAsB3C,KAAK,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IAKjE,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE;;yBAKG,MAAM,GAAG,MAAM;;IAI5D,wEAAwE;IACxE,SAAS,IAAI,MAAM;IAInB;;;;OAIG;IACH,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAKjC,6CAA6C;IAC7C,KAAK,IAAI,IAAI;CAKd;AAED;;;GAGG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,MAAM,EACb,aAAa,CAAC,EAAE,MAAM,GACrB,SAAS,CAEX"}

package/dist/harness/cubby.js

@@ -0,0 +1,94 @@
+/**
+ * In-memory `better-sqlite3` cubby for the test harness.
+ *
+ * Each declared cubby alias gets its own isolated `:memory:` database, so
+ * tests don't bleed state across agents within a single run and don't
+ * require fixture cleanup. Migrations are read from a directory of `.sql`
+ * files (sorted lexicographically and applied in order) — the same shape
+ * the production runtime uses.
+ *
+ * Note on `exec` semantics: better-sqlite3's `prepare()` only accepts a
+ * single statement, but `db.exec()` handles multi-statement scripts. We
+ * use the latter for migration loading, but keep the public
+ * `CubbyHandle.exec` (single-statement DML with parameter binding) on
+ * top of `prepare().run()` so the surface matches the production runtime
+ * exactly.
+ *
+ * `TestCubby` is implemented as a class (rather than a closure-based
+ * factory) so `query`/`exec` always read `this.raw` at call time. That
+ * lets `loadFromBuffer` swap the underlying database — needed by the
+ * `snapshot`/`restore` machinery — without invalidating the `CubbyHandle`
+ * references the agent already holds.
+ */
+import Database from "better-sqlite3";
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * Per-alias test cubby — extends the public {@link CubbyHandle} with
+ * disposal hooks the harness uses for teardown.
+ */
+export class TestCubby {
+    /** Underlying database — exposed for advanced harness extensions (e.g. `runInCubby`). */
+    raw;
+    /** Alias for diagnostics. */
+    alias;
+    closed = false;
+    constructor(alias, migrationsDir) {
+        this.alias = alias;
+        this.raw = new Database(":memory:");
+        if (migrationsDir) {
+            if (!fs.existsSync(migrationsDir)) {
+                throw new Error(`[testAgent] cubby "${alias}" migrations dir not found: ${migrationsDir}`);
+            }
+            const files = fs
+                .readdirSync(migrationsDir)
+                .filter((f) => f.endsWith(".sql"))
+                .sort();
+            for (const f of files) {
+                const sql = fs.readFileSync(path.join(migrationsDir, f), "utf8");
+                // db.exec handles multi-statement migration scripts; prepare() does not.
+                this.raw.exec(sql);
+            }
+        }
+    }
+    async query(sql, params) {
+        const stmt = this.raw.prepare(sql);
+        return stmt.all(...(params ?? []));
+    }
+    async exec(sql, params) {
+        const stmt = this.raw.prepare(sql);
+        const info = stmt.run(...(params ?? []));
+        return {
+            changes: info.changes,
+            lastInsertRowid: info.lastInsertRowid,
+        };
+    }
+    /** Serialize the database to a Buffer (powers `harness.snapshot()`). */
+    serialize() {
+        return this.raw.serialize();
+    }
+    /**
+     * Replace the underlying database from a serialized buffer. The previous
+     * handle is closed first. Existing `CubbyHandle` references stay valid
+     * because `query`/`exec` read `this.raw` lazily.
+     */
+    loadFromBuffer(buf) {
+        this.raw.close();
+        this.raw = new Database(buf);
+    }
+    /** Release the SQLite handle. Idempotent. */
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.raw.close();
+    }
+}
+/**
+ * Factory that mirrors the original closure-based API. Equivalent to
+ * `new TestCubby(alias, migrationsDir)`.
+ */
+export function createCubby(alias, migrationsDir) {
+    return new TestCubby(alias, migrationsDir);
+}
+//# sourceMappingURL=cubby.js.map

package/dist/harness/cubby.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cubby.js","sourceRoot":"","sources":["../../src/harness/cubby.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,QAAQ,MAAM,gBAAgB,CAAC;AACtC,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAG7B;;;GAGG;AACH,MAAM,OAAO,SAAS;IACpB,yFAAyF;IACzF,GAAG,CAAoB;IACvB,6BAA6B;IACpB,KAAK,CAAS;IACf,MAAM,GAAG,KAAK,CAAC;IAEvB,YAAY,KAAa,EAAE,aAAsB;QAC/C,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,GAAG,GAAG,IAAI,QAAQ,CAAC,UAAU,CAAC,CAAC;QAEpC,IAAI,aAAa,EAAE,CAAC;YAClB,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,aAAa,CAAC,EAAE,CAAC;gBAClC,MAAM,IAAI,KAAK,CACb,sBAAsB,KAAK,+BAA+B,aAAa,EAAE,CAC1E,CAAC;YACJ,CAAC;YACD,MAAM,KAAK,GAAG,EAAE;iBACb,WAAW,CAAC,aAAa,CAAC;iBAC1B,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;iBACjC,IAAI,EAAE,CAAC;YACV,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;gBACtB,MAAM,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;gBACjE,yEAAyE;gBACzE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACrB,CAAC;QACH,CAAC;IACH,CAAC;IAED,KAAK,CAAC,KAAK,CAAc,GAAW,EAAE,MAAkB;QACtD,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACnC,OAAO,IAAI,CAAC,GAAG,CAAC,GAAI,CAAC,MAAM,IAAI,EAAE,CAAe,CAAQ,CAAC;IAC3D,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,GAAW,EAAE,MAAkB;QACxC,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACnC,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,GAAI,CAAC,MAAM,IAAI,EAAE,CAAe,CAAC,CAAC;QACxD,OAAO;YACL,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,eAAe,EAAE,IAAI,CAAC,eAAkC;SACzD,CAAC;IACJ,CAAC;IAED,wEAAwE;IACxE,SAAS;QACP,OAAO,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC;IAC9B,CAAC;IAED;;;;OAIG;IACH,cAAc,CAAC,GAAW;QACxB,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC;QACjB,IAAI,CAAC,GAAG,GAAG,IAAI,QAAQ,CAAC,GAAG,CAAC,CAAC;IAC/B,CAAC;IAED,6CAA6C;IAC7C,KAAK;QACH,IAAI,IAAI,CAAC,MAAM;YAAE,OAAO;QACxB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACnB,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC;IACnB,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CACzB,KAAa,EACb,aAAsB;IAEtB,OAAO,IAAI,SAAS,CAAC,KAAK,EAAE,aAAa,CAAC,CAAC;AAC7C,CAAC"}

package/dist/harness/dispatch.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Event synthesis + handler dispatch for the test harness.
+ *
+ * `makeEvent` produces a runtime-shaped {@link Event} (id, ts from the
+ * clock, default `from`) from the partial input the test supplies; the
+ * runtime would normally do this on inbound delivery.
+ *
+ * `dispatchEvent` looks up the right handler from the class's
+ * {@link EngagementMeta} and invokes it. Unknown event types are silently
+ * dropped — that's how the production runtime behaves (no metadata match
+ * → no dispatch); raising here would punish tests for declaring agents
+ * that handle a subset of types.
+ */
+import type { EngagementMeta, Context, Event } from "@cef-ai/agent-sdk";
+/**
+ * Look up `event.type` in the agent metadata and call the matching
+ * handler with the constructed ctx. Resolves silently when no handler is
+ * declared for the type, matching runtime behavior.
+ */
+export declare function dispatchEvent(instance: Record<string, unknown>, meta: EngagementMeta, event: Event<unknown>, ctx: Context): Promise<void>;
+/**
+ * Construct a runtime-shaped event from a `dispatch()` input. Fills in
+ * `id` (random hex), `ts` (from the clock), and `from` (`"test"` unless
+ * overridden) so handlers can rely on the same shape they'd see in
+ * production.
+ */
+export declare function makeEvent(type: string, payload: unknown, opts: {
+    now: () => number;
+    from?: string;
+}): Event<unknown>;
+//# sourceMappingURL=dispatch.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../../src/harness/dispatch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAExE;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,IAAI,EAAE,cAAc,EACpB,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,EACrB,GAAG,EAAE,OAAO,GACX,OAAO,CAAC,IAAI,CAAC,CAcf;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE;IAAE,GAAG,EAAE,MAAM,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GACzC,KAAK,CAAC,OAAO,CAAC,CAQhB"}

package/dist/harness/dispatch.js

@@ -0,0 +1,37 @@
+/**
+ * Look up `event.type` in the agent metadata and call the matching
+ * handler with the constructed ctx. Resolves silently when no handler is
+ * declared for the type, matching runtime behavior.
+ */
+export async function dispatchEvent(instance, meta, event, ctx) {
+    const handlerName = meta.events[event.type];
+    if (!handlerName)
+        return;
+    const fn = instance[handlerName];
+    if (typeof fn !== "function") {
+        throw new Error(`[testAgent] handler "${handlerName}" for "${event.type}" is not a function on instance`);
+    }
+    await fn.call(instance, event, ctx);
+}
+/**
+ * Construct a runtime-shaped event from a `dispatch()` input. Fills in
+ * `id` (random hex), `ts` (from the clock), and `from` (`"test"` unless
+ * overridden) so handlers can rely on the same shape they'd see in
+ * production.
+ */
+export function makeEvent(type, payload, opts) {
+    return {
+        id: `evt-${randomHex(8)}`,
+        type,
+        ts: opts.now(),
+        from: opts.from ?? "test",
+        payload,
+    };
+}
+function randomHex(bytes) {
+    const buf = new Uint8Array(bytes);
+    // Node 20 / browsers both expose globalThis.crypto.
+    globalThis.crypto.getRandomValues(buf);
+    return Array.from(buf, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+//# sourceMappingURL=dispatch.js.map

package/dist/harness/dispatch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.js","sourceRoot":"","sources":["../../src/harness/dispatch.ts"],"names":[],"mappings":"AAeA;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,QAAiC,EACjC,IAAoB,EACpB,KAAqB,EACrB,GAAY;IAEZ,MAAM,WAAW,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC5C,IAAI,CAAC,WAAW;QAAE,OAAO;IACzB,MAAM,EAAE,GAAG,QAAQ,CAAC,WAAW,CAAC,CAAC;IACjC,IAAI,OAAO,EAAE,KAAK,UAAU,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CACb,wBAAwB,WAAW,UAAU,KAAK,CAAC,IAAI,iCAAiC,CACzF,CAAC;IACJ,CAAC;IACD,MAAO,EAAiD,CAAC,IAAI,CAC3D,QAAQ,EACR,KAAK,EACL,GAAG,CACJ,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CACvB,IAAY,EACZ,OAAgB,EAChB,IAA0C;IAE1C,OAAO;QACL,EAAE,EAAE,OAAO,SAAS,CAAC,CAAC,CAAC,EAAE;QACzB,IAAI;QACJ,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE;QACd,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,MAAM;QACzB,OAAO;KACR,CAAC;AACJ,CAAC;AAED,SAAS,SAAS,CAAC,KAAa;IAC9B,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC;IAClC,oDAAoD;IACpD,UAAU,CAAC,MAAM,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC;IACvC,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AAC1E,CAAC"}

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

@@ -0,0 +1,43 @@
+/**
+ * Tiny URL-pattern fetch mock used by the test harness.
+ *
+ * Scope is deliberately small: enough to assert that the agent issued the
+ * expected outbound HTTP requests and to stub a response body. We don't
+ * try to be a general-purpose nock — for that, tests can replace
+ * `ctx.fetch` directly via the harness's published model-mock pattern.
+ *
+ * URL matching:
+ *   - `string`: matches by exact equality OR by `startsWith` (covers the
+ *     "any path under https://api.example.com" case ergonomically).
+ *   - `RegExp`: matches by `RegExp.test`.
+ *
+ * Method matching is case-insensitive and optional (omitted means "any
+ * method"). Stubs are tried in declaration order; the first match wins.
+ */
+import type { FetchInit } from "@cef-ai/agent-sdk";
+export interface FetchMatcher {
+    url: string | RegExp;
+    method?: string;
+}
+export interface FetchReply {
+    status: number;
+    body?: string | object;
+    headers?: Record<string, string>;
+}
+export interface FetchMock {
+    /** Register a stub. Returns a `.reply()` builder. */
+    when(matcher: FetchMatcher): {
+        reply: (status: number, body?: string | object, headers?: Record<string, string>) => void;
+    };
+    /** Throw if no recorded call matched `matcher`. */
+    assertCalled(matcher: FetchMatcher): void;
+    /** Captured calls; exposed for ad-hoc assertions. */
+    calls: Array<{
+        url: string;
+        method: string;
+    }>;
+    /** Drop-in for `ctx.fetch`. */
+    fetch: (url: string | URL, init?: FetchInit) => Promise<Response>;
+}
+export declare function createFetchMock(): FetchMock;
+//# sourceMappingURL=fetch-mock.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-mock.d.ts","sourceRoot":"","sources":["../../src/harness/fetch-mock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAEnD,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,SAAS;IACxB,qDAAqD;IACrD,IAAI,CAAC,OAAO,EAAE,YAAY,GAAG;QAC3B,KAAK,EAAE,CACL,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,EACtB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAC7B,IAAI,CAAC;KACX,CAAC;IACF,mDAAmD;IACnD,YAAY,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI,CAAC;IAC1C,qDAAqD;IACrD,KAAK,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC9C,+BAA+B;IAC/B,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,EAAE,IAAI,CAAC,EAAE,SAAS,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;CACnE;AAED,wBAAgB,eAAe,IAAI,SAAS,CA4D3C"}

package/dist/harness/fetch-mock.js

@@ -0,0 +1,58 @@
+export function createFetchMock() {
+    const stubs = [];
+    const calls = [];
+    const mock = {
+        when(matcher) {
+            return {
+                reply(status, body, headers) {
+                    stubs.push({ matcher, reply: { status, body, headers } });
+                },
+            };
+        },
+        assertCalled(matcher) {
+            const found = calls.some((c) => matchUrl(c.url, matcher.url) &&
+                (matcher.method
+                    ? c.method.toUpperCase() === matcher.method.toUpperCase()
+                    : true));
+            if (!found) {
+                throw new Error(`[fetchMock] expected ${describeMatcher(matcher)} not called. Actual: ${calls.length === 0
+                    ? "(no calls)"
+                    : calls.map((c) => `${c.method} ${c.url}`).join(", ")}`);
+            }
+        },
+        calls,
+        async fetch(url, init) {
+            const u = url.toString();
+            const method = (init?.method ?? "GET").toUpperCase();
+            calls.push({ url: u, method });
+            const stub = stubs.find((s) => matchUrl(u, s.matcher.url) &&
+                (s.matcher.method
+                    ? method === s.matcher.method.toUpperCase()
+                    : true));
+            if (!stub) {
+                throw new Error(`[fetchMock] no stub for ${method} ${u}`);
+            }
+            const body = typeof stub.reply.body === "string"
+                ? stub.reply.body
+                : JSON.stringify(stub.reply.body ?? null);
+            return new Response(body, {
+                status: stub.reply.status,
+                headers: {
+                    "content-type": "application/json",
+                    ...(stub.reply.headers ?? {}),
+                },
+            });
+        },
+    };
+    return mock;
+}
+function matchUrl(url, pattern) {
+    return typeof pattern === "string"
+        ? url === pattern || url.startsWith(pattern)
+        : pattern.test(url);
+}
+function describeMatcher(m) {
+    const u = typeof m.url === "string" ? m.url : m.url.toString();
+    return m.method ? `${m.method.toUpperCase()} ${u}` : u;
+}
+//# sourceMappingURL=fetch-mock.js.map

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

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

package/dist/harness/lifecycle.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Lifecycle controller for the test harness — drives `@OnStart` /
+ * `@OnClose` from the agent's metadata and tracks the externally
+ * observable state (`idle` → `started` → `closed`).
+ *
+ * The harness owns calling these explicitly (`harness.start()` /
+ * `harness.close(reason)`) rather than implicitly on `dispatch`, mirroring
+ * sdk-runtime-integration-contract §4 where the runtime, not the agent,
+ * controls lifecycle transitions.
+ */
+import type { EngagementMeta, Context, OnCloseReason } from "@cef-ai/agent-sdk";
+export type LifecycleState = "idle" | "started" | "closed";
+export interface LifecycleTracker {
+    /** Current externally observable state. */
+    state: LifecycleState;
+    /** Reason recorded by the most recent `close` call. */
+    terminalReason?: OnCloseReason | string;
+    /** Invoke the agent's `@OnStart` handler (if any) and transition to `started`. */
+    start(instance: Record<string, unknown>, ctx: Context, meta: EngagementMeta): Promise<void>;
+    /** Invoke the agent's `@OnClose` handler (if any) and transition to `closed`. */
+    close(instance: Record<string, unknown>, ctx: Context, meta: EngagementMeta, reason: OnCloseReason | string): Promise<void>;
+}
+/**
+ * Build a fresh lifecycle tracker. Idempotent on `start` and `close` —
+ * subsequent calls are no-ops, matching the runtime contract that
+ * lifecycle hooks fire at most once per agent instance.
+ */
+export declare function createLifecycle(): LifecycleTracker;
+//# sourceMappingURL=lifecycle.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../src/harness/lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEhF,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,CAAC;AAE3D,MAAM,WAAW,gBAAgB;IAC/B,2CAA2C;IAC3C,KAAK,EAAE,cAAc,CAAC;IACtB,uDAAuD;IACvD,cAAc,CAAC,EAAE,aAAa,GAAG,MAAM,CAAC;IACxC,kFAAkF;IAClF,KAAK,CACH,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,cAAc,GACnB,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,iFAAiF;IACjF,KAAK,CACH,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,cAAc,EACpB,MAAM,EAAE,aAAa,GAAG,MAAM,GAC7B,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB;AAED;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,gBAAgB,CA8BlD"}

package/dist/harness/lifecycle.js

@@ -0,0 +1,37 @@
+/**
+ * Build a fresh lifecycle tracker. Idempotent on `start` and `close` —
+ * subsequent calls are no-ops, matching the runtime contract that
+ * lifecycle hooks fire at most once per agent instance.
+ */
+export function createLifecycle() {
+    const t = {
+        state: "idle",
+        async start(instance, ctx, meta) {
+            if (t.state !== "idle")
+                return;
+            const m = meta.lifecycle?.start;
+            if (m) {
+                const fn = instance[m];
+                if (typeof fn === "function") {
+                    await fn.call(instance, ctx);
+                }
+            }
+            t.state = "started";
+        },
+        async close(instance, ctx, meta, reason) {
+            if (t.state === "closed")
+                return;
+            const m = meta.lifecycle?.close;
+            if (m) {
+                const fn = instance[m];
+                if (typeof fn === "function") {
+                    await fn.call(instance, ctx, reason);
+                }
+            }
+            t.state = "closed";
+            t.terminalReason = reason;
+        },
+    };
+    return t;
+}
+//# sourceMappingURL=lifecycle.js.map

package/dist/harness/lifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.js","sourceRoot":"","sources":["../../src/harness/lifecycle.ts"],"names":[],"mappings":"AAkCA;;;;GAIG;AACH,MAAM,UAAU,eAAe;IAC7B,MAAM,CAAC,GAAqB;QAC1B,KAAK,EAAE,MAAM;QACb,KAAK,CAAC,KAAK,CAAC,QAAQ,EAAE,GAAG,EAAE,IAAI;YAC7B,IAAI,CAAC,CAAC,KAAK,KAAK,MAAM;gBAAE,OAAO;YAC/B,MAAM,CAAC,GAAG,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC;YAChC,IAAI,CAAC,EAAE,CAAC;gBACN,MAAM,EAAE,GAAI,QAAoC,CAAC,CAAC,CAAC,CAAC;gBACpD,IAAI,OAAO,EAAE,KAAK,UAAU,EAAE,CAAC;oBAC7B,MAAO,EAA8B,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;gBAC5D,CAAC;YACH,CAAC;YACD,CAAC,CAAC,KAAK,GAAG,SAAS,CAAC;QACtB,CAAC;QACD,KAAK,CAAC,KAAK,CAAC,QAAQ,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM;YACrC,IAAI,CAAC,CAAC,KAAK,KAAK,QAAQ;gBAAE,OAAO;YACjC,MAAM,CAAC,GAAG,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC;YAChC,IAAI,CAAC,EAAE,CAAC;gBACN,MAAM,EAAE,GAAI,QAAoC,CAAC,CAAC,CAAC,CAAC;gBACpD,IAAI,OAAO,EAAE,KAAK,UAAU,EAAE,CAAC;oBAC7B,MACE,EACD,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC;gBAChC,CAAC;YACH,CAAC;YACD,CAAC,CAAC,KAAK,GAAG,QAAQ,CAAC;YACnB,CAAC,CAAC,cAAc,GAAG,MAAM,CAAC;QAC5B,CAAC;KACF,CAAC;IACF,OAAO,CAAC,CAAC;AACX,CAAC"}