@cef-ai/testing 0.1.0

package/dist/test-agent.js

@@ -0,0 +1,223 @@
+/**
+ * `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 { ENGAGEMENT_METADATA, } from "@cef-ai/agent-sdk";
+import { createClock } from "./harness/clock.js";
+import { createCubby } from "./harness/cubby.js";
+import { createPublishCollector, } from "./harness/publish.js";
+import { createLifecycle } from "./harness/lifecycle.js";
+import { createFetchMock } from "./harness/fetch-mock.js";
+import { isModelHandle, } from "./harness/model-mock.js";
+import { dispatchEvent, makeEvent } from "./harness/dispatch.js";
+import { captureSnapshot, restoreSnapshot, } from "./harness/snapshot.js";
+import { runReplay } from "./harness/replay.js";
+import { evaluateTargeting } from "./platform/targeting.js";
+export function testAgent(arg, opts = {}) {
+    // ---- Normalise the input into a uniform engagement table ---------------
+    const engagements = normaliseEngagements(arg);
+    // ---- Wire harness primitives -------------------------------------------
+    const clock = createClock(opts.clock?.now);
+    const collector = createPublishCollector(clock.now);
+    const lifecycle = createLifecycle();
+    const fetchMock = createFetchMock();
+    // ---- Build cubbies ------------------------------------------------------
+    const cubbies = new Map();
+    for (const spec of opts.cubbies ?? []) {
+        const s = typeof spec === "string" ? { alias: spec } : spec;
+        if (cubbies.has(s.alias)) {
+            throw new Error(`[testAgent] duplicate cubby alias "${s.alias}" in opts.cubbies`);
+        }
+        cubbies.set(s.alias, createCubby(s.alias, s.migrations));
+    }
+    // ---- Validate / surface model handles ----------------------------------
+    // We accept both expectation-style mocks and plain `{ infer, stream }`
+    // stubs; `isModelHandle` enforces the shape so a typo'd handle fails
+    // loud at construction rather than mid-dispatch.
+    const models = {};
+    for (const [alias, handle] of Object.entries(opts.models ?? {})) {
+        if (!isModelHandle(handle)) {
+            throw new Error(`[testAgent] models["${alias}"] is not a ModelHandle (missing infer())`);
+        }
+        models[alias] = handle;
+    }
+    // ---- Frozen settings ----------------------------------------------------
+    const settings = Object.freeze({ ...(opts.settings ?? {}) });
+    // ---- Pin the engagement -------------------------------------------------
+    // For single-engagement harnesses we pin immediately. For multi-engagement
+    // harnesses we defer until first dispatch/start/close — at which point we
+    // evaluate targeting against `settings`.
+    let pinnedEngagementId = engagements.kind === "single" ? engagements.entry.id : undefined;
+    function pickEngagement() {
+        if (!pinnedEngagementId) {
+            pinnedEngagementId = evaluateTargeting(engagements.targeting, settings);
+        }
+        const entry = engagements.byId.get(pinnedEngagementId);
+        if (!entry) {
+            throw new Error(`[testAgent] targeting resolved engagement "${pinnedEngagementId}" but no such engagement was declared`);
+        }
+        return entry;
+    }
+    // ---- Build the ctx visible to the agent --------------------------------
+    // ctx is rebuilt per pickEngagement to thread the right instance into
+    // ctx.close(). For dispatch we just close over `pickEngagement()` to look
+    // up the chosen instance dynamically; this keeps the ctx shape stable.
+    const ctx = {
+        cubby(alias) {
+            const c = cubbies.get(alias);
+            if (!c) {
+                throw new Error(`[testAgent] cubby "${alias}" not declared in opts.cubbies`);
+            }
+            return { query: c.query.bind(c), exec: c.exec.bind(c) };
+        },
+        models: models,
+        fetch: fetchMock.fetch,
+        publish: collector.publish,
+        settings,
+        async close(reason) {
+            const picked = pickEngagement();
+            await lifecycle.close(picked.instance, ctx, picked.meta, reason ?? "closed_by_agent");
+        },
+        log: {
+            info() { },
+            warn() { },
+            error() { },
+            debug() { },
+        },
+    };
+    // ---- Public harness ----------------------------------------------------
+    const harness = {
+        published: collector.events,
+        cubby(alias) {
+            const c = cubbies.get(alias);
+            if (!c) {
+                throw new Error(`[testAgent] cubby "${alias}" not declared in opts.cubbies`);
+            }
+            return { query: c.query.bind(c), exec: c.exec.bind(c) };
+        },
+        async start() {
+            const picked = pickEngagement();
+            await lifecycle.start(picked.instance, ctx, picked.meta);
+        },
+        async close(reason) {
+            const picked = pickEngagement();
+            await lifecycle.close(picked.instance, ctx, picked.meta, reason ?? "closed_by_agent");
+        },
+        get lifecycle() {
+            return {
+                state: lifecycle.state,
+                terminalReason: lifecycle.terminalReason,
+            };
+        },
+        get engagement() {
+            return pinnedEngagementId;
+        },
+        advanceTime: clock.advanceTime,
+        now: clock.now,
+        fetchMock: () => fetchMock,
+        models,
+        async dispatch(input) {
+            const before = collector.events.length;
+            const event = makeEvent(input.type, input.payload, {
+                now: clock.now,
+                from: input.from,
+            });
+            const picked = pickEngagement();
+            await dispatchEvent(picked.instance, picked.meta, event, ctx);
+            return collector.events.slice(before);
+        },
+        async runInCubby(alias, fn) {
+            const c = cubbies.get(alias);
+            if (!c) {
+                throw new Error(`[testAgent] cubby "${alias}" not declared in opts.cubbies`);
+            }
+            return await fn({ query: c.query.bind(c), exec: c.exec.bind(c) }, c.raw);
+        },
+        snapshot() {
+            return captureSnapshot(cubbies, collector.events, clock.now());
+        },
+        restore(snap) {
+            restoreSnapshot(cubbies, collector.events, clock.setNow, snap);
+        },
+        replay(jsonlPath) {
+            return runReplay(harness, jsonlPath, cubbies);
+        },
+        dispose() {
+            for (const c of cubbies.values())
+                c.close();
+        },
+    };
+    return harness;
+}
+function normaliseEngagements(arg) {
+    if (typeof arg === "function") {
+        // Single class shorthand.
+        const meta = readMeta(arg);
+        const id = meta.id ?? "default";
+        const entry = { id, instance: new arg(), meta };
+        const byId = new Map([[id, entry]]);
+        return {
+            kind: "single",
+            entry,
+            byId,
+            targeting: { engagements: [{ id, rules: [] }] },
+        };
+    }
+    // Multi-engagement spec.
+    if (!Array.isArray(arg.engagements) || arg.engagements.length === 0) {
+        throw new Error("[testAgent] multi-engagement spec requires a non-empty engagements[]");
+    }
+    const byId = new Map();
+    for (const e of arg.engagements) {
+        if (!e.id) {
+            throw new Error("[testAgent] engagement entry has no id");
+        }
+        if (byId.has(e.id)) {
+            throw new Error(`[testAgent] duplicate engagement id "${e.id}"`);
+        }
+        const meta = readMeta(e.source);
+        byId.set(e.id, { id: e.id, instance: new e.source(), meta });
+    }
+    const firstId = arg.engagements[0].id;
+    const targeting = arg.targeting ?? {
+        engagements: [{ id: firstId, rules: [] }],
+    };
+    for (const entry of targeting.engagements) {
+        if (!byId.has(entry.id)) {
+            throw new Error(`[testAgent] targeting references unknown engagement "${entry.id}"`);
+        }
+    }
+    return { kind: "multi", byId, targeting };
+}
+function readMeta(ctor) {
+    const meta = ctor[ENGAGEMENT_METADATA];
+    if (!meta) {
+        throw new Error("[testAgent] class has no @OnEvent/@OnStart/@OnClose decorators (missing ENGAGEMENT_METADATA)");
+    }
+    return meta;
+}
+//# sourceMappingURL=test-agent.js.map

package/dist/test-agent.js.map

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

package/dist/test-platform.d.ts

@@ -0,0 +1,167 @@
+/**
+ * `testPlatform({...})` — multi-agent + vault simulator harness.
+ *
+ * Wires the `./platform/*` pieces together so a test can:
+ *   - spin up multiple peer agents (typed `Agent` classes or `mockAgent({...})`);
+ *   - publish to a shared in-memory vault and watch events route between agents;
+ *   - inspect jobs / activities created by the orchestrator;
+ *   - run cubby-level assertions per agent via {@link TestPlatform.runInCubby}.
+ *
+ * Per ADR-019 H4 the simulator is engagement-aware: each registered agent has
+ * one or more engagements; targeting picks one at Job creation; the chosen
+ * engagement is pinned for the Job's life. Single-class registrations remain
+ * equivalent to one engagement with id `"default"` for back-compat.
+ *
+ * Public surface mirrors `agent-sdk.md` §10 and the contract docs so app-side
+ * test code uses the same vault API it would in production.
+ */
+import { type CubbyHandle, type ModelHandle, type Targeting } from "@cef-ai/agent-sdk";
+import type Database from "better-sqlite3";
+import { type TestClock } from "./harness/clock.js";
+import { type FetchMock } from "./harness/fetch-mock.js";
+import { type ModelMockHandle } from "./harness/model-mock.js";
+import { type MockAgentDescriptor, type MockSettingSpec } from "./peers/mock-agent.js";
+import { type Job, type JobsFilter } from "./platform/orchestrator.js";
+import { type UserAccessor, type Vault } from "./platform/vault.js";
+/** Agent class with `@OnEvent` / `@OnStart` / `@OnClose` (and optionally `@Engagement`). */
+export type AgentClass = new (...args: unknown[]) => object;
+/** Multi-engagement source-class registration (ADR-019 H4). */
+export interface MultiEngagementSpec {
+    /**
+     * One source class per engagement. Each class is independently
+     * instantiated; its metadata supplies handler + lifecycle method names.
+     */
+    engagements: Array<{
+        id: string;
+        source: AgentClass;
+        goal?: string;
+    }>;
+    /** Cubby aliases provisioned at the agent level (shared across engagements). */
+    cubbies?: PlatformCubbySpec[];
+    /** Default settings record (overridable at connect time). */
+    settings?: Record<string, unknown>;
+    /** Targeting decision table; defaults to `{ rules: [], default: <first id> }`. */
+    targeting?: Targeting;
+    /** Settings schema (forward-looking; simulator does not enforce). */
+    settingsSchema?: MockSettingSpec[];
+}
+/**
+ * What may be passed for each entry of `testPlatform({ agents })`.
+ *
+ *   - A class with `@OnEvent` / `@OnStart` / `@OnClose` decorators
+ *     (introspected via `ENGAGEMENT_METADATA`); single-engagement shorthand,
+ *     id `"default"`.
+ *   - A `mockAgent({...})` descriptor for stunt-double peers.
+ *   - A long-form single-class registration (existing) for cubbies / settings.
+ *   - A multi-engagement registration `{ engagements: [...], targeting?, ... }`.
+ */
+export type AgentSource = AgentClass | MockAgentDescriptor;
+/** Per-agent cubby spec (mirrors {@link CubbySpec} from `testAgent`). */
+export type PlatformCubbySpec = string | {
+    alias: string;
+    migrations?: string;
+};
+/** Long-form single-class registration. */
+export interface SingleAgentRegistration {
+    /** The class or mock descriptor backing this agent. */
+    source: AgentSource;
+    /** Optional cubby aliases (with optional migration dirs) to provision. */
+    cubbies?: PlatformCubbySpec[];
+    /** Optional per-agent settings record (frozen and exposed via `ctx.settings`). */
+    settings?: Record<string, unknown>;
+}
+/** Anything accepted in the `agents` map. */
+export type AgentRegistration = AgentSource | SingleAgentRegistration | MultiEngagementSpec;
+/** Wallet stub passed via `users[id].wallet`. ADR-019 H5. */
+export interface TestWallet {
+    publicKey: string;
+}
+/**
+ * Per-user spec passed via `testPlatform({ users })`. The wallet is a stub
+ * today (the simulator only reads `publicKey` for diagnostics) but is
+ * accepted so test code mirrors the production shape.
+ */
+export interface TestUser {
+    wallet?: TestWallet;
+}
+/**
+ * Convenience wallet stub — `testWallet("alice")` produces a deterministic
+ * `{ publicKey: "wallet-alice" }`. The simulator does not verify signatures.
+ */
+export declare function testWallet(id: string): TestWallet;
+export interface TestPlatformOptions {
+    /**
+     * Map of user id → user spec. Each entry gets a dedicated per-user vault
+     * accessible via `platform.user(id)` (ADR-019 H5). When omitted, the
+     * platform creates a single implicit user (id `"default"`) so legacy
+     * `platform.vault.scope(...)` keeps working.
+     */
+    users?: Record<string, TestUser>;
+    /**
+     * Implicit-user id when `users` is empty. Defaults to `"default"`. Kept
+     * for back-compat with v0.1.0 testPlatform fixtures that pre-date the
+     * `users` map.
+     */
+    vaultId?: string;
+    /** Default scope used when callers omit `vault.scope(...)` arguments. */
+    scope?: string;
+    /** Default context applied to publishes that omit `opts.context`. */
+    context?: string;
+    /**
+     * Map of `agentId` → registration. Plain classes / mock descriptors are
+     * single-engagement shorthand; the long-form variants are for cubbies,
+     * settings, and multi-engagement targeting.
+     */
+    agents: Record<string, AgentRegistration>;
+    /** Shared model handles across every agent's `ctx.models`. */
+    models?: Record<string, ModelHandle | ModelMockHandle>;
+    /** Optional initial unix-millis. */
+    clock?: {
+        now?: number;
+    };
+}
+export interface TestPlatform {
+    /**
+     * Back-compat shorthand: when 0 or 1 users are declared, returns the
+     * single user's vault. Throws when 2+ users are declared — callers must
+     * disambiguate via `platform.user(id).vault` (ADR-019 H5).
+     */
+    vault: Vault;
+    /**
+     * Per-user accessor. The id must appear in `users` or be the implicit
+     * default user when `users` is omitted.
+     */
+    user(id: string): UserAccessor;
+    /**
+     * Read-only view of jobs across ALL users (mirror of the orchestrator).
+     * For per-user views, use `platform.user(id).vault.jobs`.
+     */
+    orchestrator: {
+        jobs: Map<string, Job>;
+        list(filter?: JobsFilter): Job[];
+        get(jobId: string): Job | undefined;
+    };
+    /** Shared monotonic clock. */
+    clock: TestClock;
+    /** Shared fetch mock. */
+    fetchMock(): FetchMock;
+    /** Shared model handle map. */
+    models: Record<string, ModelHandle | ModelMockHandle>;
+    /**
+     * Run `fn` against an agent's cubby. Same shape as
+     * `testAgent.runInCubby(alias, fn)` but threaded through the multi-agent
+     * platform via `agentId`. The optional `userId` selects which user's
+     * cubby to inspect (ADR-019 H5); defaults to the single implicit user
+     * when 0 or 1 users are declared, throws when ambiguous.
+     */
+    runInCubby<T>(agentId: string, alias: string, fn: (handle: CubbyHandle, raw: Database.Database) => T | Promise<T>, userId?: string): Promise<T>;
+    /** Release SQLite handles across all agents. Idempotent. */
+    dispose(): void;
+}
+export declare function testPlatform(opts: TestPlatformOptions): TestPlatform;
+export { mockAgent } from "./peers/mock-agent.js";
+export type { MockAgentDescriptor, MockAgentSpec, MockAgentSingleSpec, MockAgentMultiEngagementSpec, MockEngagementSpec, MockEngagementDescriptor, MockSettingSpec, } from "./peers/mock-agent.js";
+export { fromMarketplace } from "./peers/from-marketplace.js";
+export type { AgentConnection, ConnectionEngagement, ConnectionManifest, UserAccessor, Vault, VaultEvent, VaultScope, VaultStream, } from "./platform/vault.js";
+export type { Activity, ActivityStatus, Job, JobsFilter, JobState, } from "./platform/orchestrator.js";
+//# sourceMappingURL=test-platform.d.ts.map

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

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