@cef-ai/testing 0.1.0

package/dist/platform/runtime.js.map

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

package/dist/platform/targeting.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Runtime targeting evaluator.
+ *
+ * Mirrors the build-time validator: `targeting.engagements[]` is sorted by
+ * `priority` (lower = higher priority), then within the top-priority tier
+ * a weighted-random selection picks one (per `prototype.md` §"Targeting on
+ * the Manifest body" and the legacy `Deployment.Engagements` evaluator).
+ *
+ * The simulator treats `limit` rules as advisory in v1 — daily UTC caps
+ * are persistence-heavy and out of scope for the in-memory test platform.
+ * Production targeting honours them via the Redis-backed counter; tests
+ * that need to assert limit behaviour should use mock platform options.
+ */
+import type { Targeting } from "@cef-ai/agent-sdk";
+/**
+ * Pick an engagement id from `targeting.engagements[]` against the runtime
+ * settings. Settings are accepted for parity with prototype.md (future
+ * predicate-based rules) but are unused by the v1 priority/weight vocabulary.
+ *
+ * Selection algorithm:
+ *  1. Resolve every entry's `(priority, weight)` (defaults: 0, 100).
+ *  2. Group by priority; pick the lowest priority value (highest priority).
+ *  3. Within that tier, weighted-random pick by `weight`.
+ *
+ * Throws when `targeting.engagements[]` is empty — the caller should have
+ * defaulted it during config validation.
+ */
+export declare function evaluateTargeting(targeting: Targeting, _settings: Record<string, unknown>, rng?: () => number): string;
+//# sourceMappingURL=targeting.d.ts.map

package/dist/platform/targeting.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"targeting.d.ts","sourceRoot":"","sources":["../../src/platform/targeting.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAQ,SAAS,EAAuB,MAAM,mBAAmB,CAAC;AAyB9E;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,SAAS,EACpB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClC,GAAG,GAAE,MAAM,MAAoB,GAC9B,MAAM,CAmBR"}

package/dist/platform/targeting.js

@@ -0,0 +1,64 @@
+/**
+ * Runtime targeting evaluator.
+ *
+ * Mirrors the build-time validator: `targeting.engagements[]` is sorted by
+ * `priority` (lower = higher priority), then within the top-priority tier
+ * a weighted-random selection picks one (per `prototype.md` §"Targeting on
+ * the Manifest body" and the legacy `Deployment.Engagements` evaluator).
+ *
+ * The simulator treats `limit` rules as advisory in v1 — daily UTC caps
+ * are persistence-heavy and out of scope for the in-memory test platform.
+ * Production targeting honours them via the Redis-backed counter; tests
+ * that need to assert limit behaviour should use mock platform options.
+ */
+const DEFAULT_PRIORITY = 0;
+const DEFAULT_WEIGHT = 100;
+function resolveRules(rules) {
+    let priority = DEFAULT_PRIORITY;
+    let weight = DEFAULT_WEIGHT;
+    for (const r of rules ?? []) {
+        if (r.name === "priority")
+            priority = r.value;
+        else if (r.name === "weight")
+            weight = r.value;
+    }
+    return { priority, weight };
+}
+function resolve(entry) {
+    return { id: entry.id, ...resolveRules(entry.rules) };
+}
+/**
+ * Pick an engagement id from `targeting.engagements[]` against the runtime
+ * settings. Settings are accepted for parity with prototype.md (future
+ * predicate-based rules) but are unused by the v1 priority/weight vocabulary.
+ *
+ * Selection algorithm:
+ *  1. Resolve every entry's `(priority, weight)` (defaults: 0, 100).
+ *  2. Group by priority; pick the lowest priority value (highest priority).
+ *  3. Within that tier, weighted-random pick by `weight`.
+ *
+ * Throws when `targeting.engagements[]` is empty — the caller should have
+ * defaulted it during config validation.
+ */
+export function evaluateTargeting(targeting, _settings, rng = Math.random) {
+    if (!targeting.engagements || targeting.engagements.length === 0) {
+        throw new Error("[targeting] targeting.engagements is empty");
+    }
+    const resolved = targeting.engagements.map(resolve);
+    resolved.sort((a, b) => a.priority - b.priority);
+    const top = resolved[0].priority;
+    const tier = resolved.filter((r) => r.priority === top);
+    if (tier.length === 1)
+        return tier[0].id;
+    const totalWeight = tier.reduce((s, r) => s + Math.max(0, r.weight), 0);
+    if (totalWeight <= 0)
+        return tier[0].id;
+    let pick = rng() * totalWeight;
+    for (const r of tier) {
+        pick -= Math.max(0, r.weight);
+        if (pick <= 0)
+            return r.id;
+    }
+    return tier[tier.length - 1].id;
+}
+//# sourceMappingURL=targeting.js.map

package/dist/platform/targeting.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"targeting.js","sourceRoot":"","sources":["../../src/platform/targeting.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,MAAM,gBAAgB,GAAG,CAAC,CAAC;AAC3B,MAAM,cAAc,GAAG,GAAG,CAAC;AAQ3B,SAAS,YAAY,CAAC,KAAyB;IAC7C,IAAI,QAAQ,GAAG,gBAAgB,CAAC;IAChC,IAAI,MAAM,GAAG,cAAc,CAAC;IAC5B,KAAK,MAAM,CAAC,IAAI,KAAK,IAAI,EAAE,EAAE,CAAC;QAC5B,IAAI,CAAC,CAAC,IAAI,KAAK,UAAU;YAAE,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC;aACzC,IAAI,CAAC,CAAC,IAAI,KAAK,QAAQ;YAAE,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC;IACjD,CAAC;IACD,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;AAC9B,CAAC;AAED,SAAS,OAAO,CAAC,KAA0B;IACzC,OAAO,EAAE,EAAE,EAAE,KAAK,CAAC,EAAE,EAAE,GAAG,YAAY,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;AACxD,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,iBAAiB,CAC/B,SAAoB,EACpB,SAAkC,EAClC,MAAoB,IAAI,CAAC,MAAM;IAE/B,IAAI,CAAC,SAAS,CAAC,WAAW,IAAI,SAAS,CAAC,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACjE,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC;IAChE,CAAC;IACD,MAAM,QAAQ,GAAG,SAAS,CAAC,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACpD,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC;IACjD,MAAM,GAAG,GAAG,QAAQ,CAAC,CAAC,CAAE,CAAC,QAAQ,CAAC;IAClC,MAAM,IAAI,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,GAAG,CAAC,CAAC;IAExD,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC,CAAC,CAAE,CAAC,EAAE,CAAC;IAE1C,MAAM,WAAW,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC;IACxE,IAAI,WAAW,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC,CAAC,CAAE,CAAC,EAAE,CAAC;IACzC,IAAI,IAAI,GAAG,GAAG,EAAE,GAAG,WAAW,CAAC;IAC/B,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;QACrB,IAAI,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC;QAC9B,IAAI,IAAI,IAAI,CAAC;YAAE,OAAO,CAAC,CAAC,EAAE,CAAC;IAC7B,CAAC;IACD,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAE,CAAC,EAAE,CAAC;AACnC,CAAC"}

package/dist/platform/vault.d.ts

@@ -0,0 +1,185 @@
+/**
+ * In-memory implementation of the vault-sdk surface for the multi-agent
+ * simulator.
+ *
+ * Provides the same shape app-side test code uses against the real
+ * vault-sdk — `vault.scope(...).publish/subscribe/stream`,
+ * `vault.agents.connect/disconnect/get/list`, `vault.jobs.list/get` — so
+ * fixtures can exercise an entire flow without a real vault server.
+ *
+ * Internally, every publish:
+ *   1. is recorded in the per-vault event log (powers `stream(ctx).events.list`);
+ *   2. is routed through the {@link EventRuntime} to subscribed agents;
+ *   3. is broadcast to any open `subscribe()` async iterators.
+ *
+ * The vault exposes a small `_terminate` back-channel used by `ctx.close()`
+ * inside the runtime. It's prefixed with `_` to mark it as platform-internal,
+ * not part of the public vault-sdk surface.
+ */
+import type { EngagementMeta, Event, Targeting } from "@cef-ai/agent-sdk";
+import type { TestCubby } from "../harness/cubby.js";
+import type { EventRuntime } from "./event-runtime.js";
+import type { Job, JobsFilter, Orchestrator } from "./orchestrator.js";
+/**
+ * Per-engagement entry on a connection's manifest. Mirrors the shape an
+ * agent class exposes via {@link EngagementMeta} but lives at the engagement
+ * level rather than the agent level (per ADR-019).
+ */
+export interface ConnectionEngagement {
+    id: string;
+    goal?: string;
+    /** Event type → method name on the engagement's instance. */
+    events: EngagementMeta["events"];
+    /** Method names for `@OnStart` / `@OnClose` (if declared). */
+    lifecycle?: EngagementMeta["lifecycle"];
+}
+/**
+ * Connection-level manifest. An agent contains multiple engagements (per
+ * ADR-019); `targeting` picks one at Job creation. Single-engagement agents
+ * collapse to one entry with id `"default"`.
+ */
+export interface ConnectionManifest {
+    engagements: ConnectionEngagement[];
+    targeting: Targeting;
+}
+/**
+ * A live agent registration on the vault. The simulator stores the actual
+ * agent instance plus its synthesised manifest; production would only
+ * carry the manifest cid + connection token.
+ */
+export interface AgentConnection {
+    agentId: string;
+    /**
+     * Engagement-aware manifest. Synthesised from a class's
+     * `ENGAGEMENT_METADATA` (single-engagement shorthand) or from a
+     * `mockAgent({...})` descriptor / multi-engagement registration. Dispatch
+     * code looks up handlers via `manifest.engagements[engagementId]` after
+     * targeting picks an engagement at Job creation.
+     */
+    manifest: ConnectionManifest;
+    /**
+     * Per-engagement instance map. Each value is the JS object whose methods
+     * are invoked when an event fires for that engagement.
+     */
+    engagementInstances: Record<string, object>;
+    /** Per-alias cubbies — populated lazily; kept on the vault platform. */
+    cubbies: Map<string, TestCubby>;
+    /** Frozen settings record visible to handlers via `ctx.settings`. */
+    settings: Record<string, unknown>;
+}
+/**
+ * Event as recorded in the vault log. Augments the SDK `Event` shape with
+ * the routing metadata (`vaultId`, `scope`, `context`) the simulator
+ * partitions on. ADR-019 H5: events are partitioned by user identity, with
+ * `vaultId` carrying the publishing user id so two users sharing a scope
+ * + context still see disjoint streams.
+ */
+export interface VaultEvent extends Event<unknown> {
+    vaultId: string;
+    scope: string;
+    context: string;
+}
+export interface VaultPublishOptions {
+    /** Conversation/job context key. Defaults to the vault's default scope. */
+    context?: string;
+    /** Override the publisher identifier. Defaults to `"app"`. */
+    from?: string;
+}
+export interface VaultStream {
+    events: {
+        /** Synchronous read of all events recorded against `(scope, ctx)`. */
+        list(filter?: {
+            types?: string[];
+        }): VaultEvent[];
+    };
+}
+export interface VaultScope {
+    /**
+     * Publish an event. Resolves only after all directly-routed handlers
+     * (and any chained publishes they trigger) have settled — `await` is the
+     * test's drain primitive.
+     */
+    publish(eventType: string, payload: unknown, opts?: VaultPublishOptions): Promise<{
+        eventId: string;
+    }>;
+    /**
+     * Subscribe to live events on this scope. Returns an async iterable that
+     * yields each new {@link VaultEvent}. Optional `context` filter.
+     */
+    subscribe(opts?: {
+        context?: string;
+    }): AsyncIterable<VaultEvent>;
+    /**
+     * Open a "stream" view rooted at `(scope, context)`. Today only
+     * `events.list()` is implemented — enough for assertions in fixtures.
+     */
+    stream(context: string): VaultStream;
+}
+export interface VaultAgentsApi {
+    connect(opts: {
+        agentId: string;
+        manifestCid?: string;
+        settings?: Record<string, unknown>;
+    }): Promise<AgentConnection>;
+    disconnect(agentId: string): Promise<void>;
+    get(agentId: string): AgentConnection | undefined;
+    list(): AgentConnection[];
+}
+export interface VaultJobsApi {
+    list(filter?: JobsFilter): Job[];
+    get(jobId: string): Job | undefined;
+}
+export interface Vault {
+    vaultId: string;
+    scope(name: string): VaultScope;
+    agents: VaultAgentsApi;
+    jobs: VaultJobsApi;
+    /**
+     * Internal: terminate a job on the orchestrator. Exposed for the runtime's
+     * `ctx.close()` plumbing — not part of the public vault-sdk surface.
+     */
+    _terminate(jobId: string, reason: string, connection?: AgentConnection): Promise<void>;
+}
+export interface VaultOptions {
+    /**
+     * The user id this vault belongs to. ADR-019 H5: each user gets its own
+     * vault instance, and `vaultId` is stamped onto every published event so
+     * downstream filters partition correctly.
+     */
+    vaultId: string;
+    /** Default `scope` and `context` used when callers omit them. */
+    defaultScope?: string;
+    defaultContext?: string;
+    eventRuntime: EventRuntime;
+    orchestrator: Orchestrator;
+    clock: () => number;
+    /**
+     * Resolves the manifest + per-engagement instances for `agentId` at connect
+     * time. The platform owns this map (since classes need to be instantiated),
+     * so the vault delegates rather than reaching into the platform globals.
+     */
+    resolveAgent(agentId: string): {
+        manifest: ConnectionManifest;
+        engagementInstances: Record<string, object>;
+    } | undefined;
+    /**
+     * Per-`(user, agent)` cubbies — owned by the platform. The vault is given
+     * its own user's slice and binds each connection to its alias map without
+     * copying. Per the contract's instanceID derivation
+     * (`sha256(vaultId + "/" + scope + "/" + agentId + "/" + alias)`), cubby
+     * state is naturally partitioned by user.
+     */
+    cubbies: Map<string, Map<string, TestCubby>>;
+    /**
+     * Shared, append-only event log across all per-user vaults on the platform.
+     * Each event carries `vaultId`, so per-user `stream()` calls filter to
+     * only their own slice.
+     */
+    events: VaultEvent[];
+}
+/** Per-user accessor returned from `platform.user(id)` (ADR-019 H5). */
+export interface UserAccessor {
+    vault: Vault;
+}
+export declare function createVault(opts: VaultOptions): Vault;
+//# sourceMappingURL=vault.d.ts.map

package/dist/platform/vault.d.ts.map

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

package/dist/platform/vault.js

@@ -0,0 +1,200 @@
+/**
+ * In-memory implementation of the vault-sdk surface for the multi-agent
+ * simulator.
+ *
+ * Provides the same shape app-side test code uses against the real
+ * vault-sdk — `vault.scope(...).publish/subscribe/stream`,
+ * `vault.agents.connect/disconnect/get/list`, `vault.jobs.list/get` — so
+ * fixtures can exercise an entire flow without a real vault server.
+ *
+ * Internally, every publish:
+ *   1. is recorded in the per-vault event log (powers `stream(ctx).events.list`);
+ *   2. is routed through the {@link EventRuntime} to subscribed agents;
+ *   3. is broadcast to any open `subscribe()` async iterators.
+ *
+ * The vault exposes a small `_terminate` back-channel used by `ctx.close()`
+ * inside the runtime. It's prefixed with `_` to mark it as platform-internal,
+ * not part of the public vault-sdk surface.
+ */
+export function createVault(opts) {
+    const { vaultId, defaultScope: _defaultScope = "default", defaultContext = "default", eventRuntime, orchestrator, clock, resolveAgent, cubbies, events, } = opts;
+    const connections = new Map();
+    /** Open `subscribe()` async iterators on this user's vault, keyed by scope name. */
+    const subscribers = new Map();
+    function makeScope(scopeName) {
+        return {
+            async publish(eventType, payload, publishOpts) {
+                const event = {
+                    id: `evt-${randomHex(8)}`,
+                    type: eventType,
+                    ts: clock(),
+                    from: publishOpts?.from ?? "app",
+                    payload,
+                    vaultId,
+                    scope: scopeName,
+                    context: publishOpts?.context ?? defaultContext,
+                };
+                events.push(event);
+                // Notify async-iterator subscribers first so `for await` consumers
+                // see the event before any handler-published downstream events.
+                const subs = subscribers.get(scopeName);
+                if (subs) {
+                    for (const s of subs) {
+                        if (!s.contextFilter || s.contextFilter === event.context) {
+                            s.push(event);
+                        }
+                    }
+                }
+                // Route through the orchestrator (sequential per event-runtime).
+                // Only this user's connections receive the event — cross-user
+                // routing is NOT a thing in the simulator.
+                await eventRuntime.publish(event, connections.values());
+                return { eventId: event.id };
+            },
+            subscribe(subOpts) {
+                return makeAsyncIterable(scopeName, subOpts?.context, subscribers);
+            },
+            stream(context) {
+                return {
+                    events: {
+                        list(filter) {
+                            return events.filter((e) => {
+                                // Partition by vaultId so two users on the same scope +
+                                // context see disjoint streams.
+                                if (e.vaultId !== vaultId)
+                                    return false;
+                                if (e.scope !== scopeName)
+                                    return false;
+                                if (e.context !== context)
+                                    return false;
+                                if (filter?.types && !filter.types.includes(e.type)) {
+                                    return false;
+                                }
+                                return true;
+                            });
+                        },
+                    },
+                };
+            },
+        };
+    }
+    const vault = {
+        vaultId,
+        scope: makeScope,
+        agents: {
+            async connect(connectOpts) {
+                if (connections.has(connectOpts.agentId)) {
+                    throw new Error(`[vault] agent "${connectOpts.agentId}" is already connected`);
+                }
+                const resolved = resolveAgent(connectOpts.agentId);
+                if (!resolved) {
+                    throw new Error(`[vault] unknown agentId "${connectOpts.agentId}" — register it via testPlatform({ agents: ... })`);
+                }
+                if (!cubbies.has(connectOpts.agentId)) {
+                    cubbies.set(connectOpts.agentId, new Map());
+                }
+                const conn = {
+                    agentId: connectOpts.agentId,
+                    manifest: resolved.manifest,
+                    engagementInstances: resolved.engagementInstances,
+                    cubbies: cubbies.get(connectOpts.agentId),
+                    settings: connectOpts.settings ?? {},
+                };
+                connections.set(connectOpts.agentId, conn);
+                return conn;
+            },
+            async disconnect(agentId) {
+                connections.delete(agentId);
+                // Job state is preserved (terminal jobs stay queryable for
+                // assertions). Production would tear them down on disconnect; the
+                // simulator deliberately keeps history accessible.
+            },
+            get(agentId) {
+                return connections.get(agentId);
+            },
+            list() {
+                return [...connections.values()];
+            },
+        },
+        jobs: {
+            list: (f) => orchestrator.list({ ...f, vaultId }),
+            get: (id) => {
+                const job = orchestrator.get(id);
+                // Per-user `vault.jobs.get(id)` only sees this user's jobs.
+                return job && job.vaultId === vaultId ? job : undefined;
+            },
+        },
+        async _terminate(jobId, reason, connection) {
+            await orchestrator.terminate(jobId, reason, connection);
+        },
+    };
+    return vault;
+}
+/* -------------------------------------------------------------------------- */
+/* Helpers                                                                    */
+/* -------------------------------------------------------------------------- */
+/**
+ * Build a push-driven async iterable for `subscribe()`. New events arriving
+ * via `push(event)` resolve the next `for await` step; `end()` ends the
+ * stream. Backpressure is unbounded — fine for tests.
+ */
+function makeAsyncIterable(scopeName, contextFilter, registry) {
+    return {
+        [Symbol.asyncIterator]() {
+            const queue = [];
+            let resolveNext;
+            let ended = false;
+            const sub = {
+                contextFilter,
+                push(event) {
+                    if (resolveNext) {
+                        const r = resolveNext;
+                        resolveNext = undefined;
+                        r({ value: event, done: false });
+                    }
+                    else {
+                        queue.push(event);
+                    }
+                },
+                end() {
+                    ended = true;
+                    if (resolveNext) {
+                        const r = resolveNext;
+                        resolveNext = undefined;
+                        r({ value: undefined, done: true });
+                    }
+                },
+            };
+            let set = registry.get(scopeName);
+            if (!set) {
+                set = new Set();
+                registry.set(scopeName, set);
+            }
+            set.add(sub);
+            return {
+                async next() {
+                    if (queue.length > 0) {
+                        return { value: queue.shift(), done: false };
+                    }
+                    if (ended) {
+                        return { value: undefined, done: true };
+                    }
+                    return new Promise((resolve) => {
+                        resolveNext = resolve;
+                    });
+                },
+                async return() {
+                    set.delete(sub);
+                    ended = true;
+                    return { value: undefined, done: true };
+                },
+            };
+        },
+    };
+}
+function randomHex(bytes) {
+    const buf = new Uint8Array(bytes);
+    globalThis.crypto.getRandomValues(buf);
+    return Array.from(buf, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+//# sourceMappingURL=vault.js.map

package/dist/platform/vault.js.map

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

package/dist/test-agent.d.ts

@@ -0,0 +1,137 @@
+/**
+ * `testAgent` — the single-agent simulator-mode harness.
+ *
+ * Wires together the pieces in `./harness/*` to produce a deterministic,
+ * in-process environment for an agent class:
+ *
+ *   - dispatch a single event and capture its publishes;
+ *   - drive `@OnStart` / `@OnClose` lifecycle hooks;
+ *   - back `ctx.cubby` with per-alias in-memory SQLite (with optional
+ *     migration directories);
+ *   - back `ctx.fetch` with a URL-pattern mock;
+ *   - back `ctx.models[alias]` with stubs or expectation builders;
+ *   - thread an injectable clock through everything timestamp-related.
+ *
+ * Public surface mirrors `agent-sdk.md` §9. Two `close` concerns are
+ * separated: `harness.close(reason)` is the lifecycle hook, while
+ * `harness.dispose()` releases test resources (SQLite handles).
+ *
+ * Per ADR-019 H4 the harness is engagement-aware:
+ *   - single-class shorthand `testAgent(SomeClass, opts)` produces one
+ *     engagement with id `"default"` (or `meta.id` from `@Engagement` if set)
+ *     — equivalent to the pre-H4 behaviour for back-compat;
+ *   - multi-engagement form `testAgent({ engagements: [...], targeting? }, opts)`
+ *     accepts multiple source classes plus a targeting decision table; the
+ *     harness evaluates targeting on first dispatch (or first start/close),
+ *     pins the chosen engagement for the harness's life, and routes to that
+ *     engagement's instance.
+ */
+import { type CubbyHandle, type ModelHandle, type OnCloseReason, type Targeting } from "@cef-ai/agent-sdk";
+import type Database from "better-sqlite3";
+import { type PublishedEvent } from "./harness/publish.js";
+import { type FetchMock } from "./harness/fetch-mock.js";
+import { type ModelMockHandle } from "./harness/model-mock.js";
+import { type HarnessSnapshot } from "./harness/snapshot.js";
+import { type ReplayResult } from "./harness/replay.js";
+/**
+ * Spec for a cubby alias. The plain-string form is shorthand for
+ * `{ alias }` with no migrations — handy for tests that drive schema
+ * via raw `harness.cubby(alias).exec(...)` calls.
+ */
+export type CubbySpec = string | {
+    alias: string;
+    migrations?: string;
+};
+export interface TestHarnessOptions {
+    /** Seed `ctx.settings`. Frozen on installation. */
+    settings?: Record<string, unknown>;
+    /** Per-alias SQLite cubbies to make available via `ctx.cubby`. */
+    cubbies?: CubbySpec[];
+    /** Seed `ctx.models[alias]`. Accepts plain stubs or `createModelMock()` handles. */
+    models?: Record<string, ModelHandle | ModelMockHandle>;
+    /** Initial wall-clock time in unix-millis. Defaults to `Date.now()`. */
+    clock?: {
+        now?: number;
+    };
+}
+/**
+ * Result published during a `dispatch()` call (or any other ctx.publish
+ * invocation, e.g. from start/close hooks).
+ */
+export type { PublishedEvent };
+export type { HarnessSnapshot, ReplayResult };
+/** Agent class with `@OnEvent` / `@OnStart` / `@OnClose` decorators. */
+export type AgentCtor = new (...args: unknown[]) => Record<string, unknown>;
+/** Multi-engagement form for `testAgent({ engagements: [...] }, opts)`. */
+export interface TestAgentMultiSpec {
+    engagements: Array<{
+        id: string;
+        source: AgentCtor;
+        goal?: string;
+    }>;
+    /** Targeting decision table; defaults to `{ rules: [], default: <first id> }`. */
+    targeting?: Targeting;
+}
+export interface TestHarness {
+    /** Drive a single event through the agent. Returns publishes from this call only. */
+    dispatch(input: {
+        type: string;
+        payload?: unknown;
+        from?: string;
+    }): Promise<PublishedEvent[]>;
+    /** All publishes captured since harness construction. */
+    published: PublishedEvent[];
+    /** Look up a cubby by alias. Throws if the alias was not declared. */
+    cubby(alias: string): CubbyHandle;
+    /**
+     * Run `fn` with both the public {@link CubbyHandle} surface and the
+     * underlying `better-sqlite3` database. Useful for tests that need
+     * synchronous, prepared-statement-style assertions without the async
+     * `query` indirection.
+     */
+    runInCubby<T>(alias: string, fn: (handle: CubbyHandle, raw: Database.Database) => T | Promise<T>): Promise<T>;
+    /** Snapshot every cubby + the published log + the clock. See {@link HarnessSnapshot}. */
+    snapshot(): HarnessSnapshot;
+    /** Restore a previously captured snapshot. Mutates in place. */
+    restore(snap: HarnessSnapshot): void;
+    /**
+     * Replay a JSONL fixture of platform events through the harness. Each
+     * line must be a JSON object with at least a `type` field; `payload` and
+     * `from` are forwarded.
+     */
+    replay(jsonlPath: string): Promise<ReplayResult>;
+    /** Run the agent's `@OnStart` hook, transitioning to `started`. */
+    start(): Promise<void>;
+    /** Run the agent's `@OnClose` hook with `reason`, transitioning to `closed`. */
+    close(reason?: OnCloseReason | string): Promise<void>;
+    /** Externally observable lifecycle state. */
+    lifecycle: {
+        state: "idle" | "started" | "closed";
+        terminalReason?: OnCloseReason | string;
+    };
+    /**
+     * The engagement id this harness is bound to. For single-class harnesses
+     * this is set at construction (matching the class's `@Engagement(id)` or
+     * `"default"`). For multi-engagement harnesses this is `undefined` until
+     * the first dispatch / start / close, when targeting picks one.
+     */
+    engagement: string | undefined;
+    /** Move the harness clock forward by `ms`. */
+    advanceTime(ms: number): void;
+    /** Read the current harness clock. */
+    now(): number;
+    /** URL-pattern fetch mock attached to `ctx.fetch`. */
+    fetchMock(): FetchMock;
+    /** Map of model handles attached to `ctx.models`. */
+    models: Record<string, ModelHandle | ModelMockHandle>;
+    /** Release SQLite handles and other test resources. Idempotent. */
+    dispose(): void;
+}
+/**
+ * Build a `testAgent` harness for either a single agent class or a
+ * multi-engagement spec. The two overloads share the same {@link TestHarness}
+ * surface.
+ */
+export declare function testAgent(AgentClass: AgentCtor, opts?: TestHarnessOptions): TestHarness;
+export declare function testAgent(spec: TestAgentMultiSpec, opts?: TestHarnessOptions): TestHarness;
+//# sourceMappingURL=test-agent.d.ts.map

package/dist/test-agent.d.ts.map

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