@cef-ai/testing 0.1.0

package/dist/peers/mock-agent.js

@@ -0,0 +1,113 @@
+/**
+ * `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.
+ */
+/* -------------------------------------------------------------------------- */
+/* Construction                                                               */
+/* -------------------------------------------------------------------------- */
+function isMultiEngagementSpec(spec) {
+    return Array.isArray(spec.engagements);
+}
+/**
+ * Synthesise an `(instance, meta)` pair from a single-engagement-style entry.
+ * Method names are stable per-engagement (`on_<type>` / `onStart` / `onClose`)
+ * so multiple engagements within one mock can each have their own instance.
+ */
+function buildEngagementShape(id, goal, on, onStart, onClose) {
+    const events = {};
+    const instance = {};
+    for (const [type, handler] of Object.entries(on ?? {})) {
+        const name = `on_${type}`;
+        events[type] = name;
+        instance[name] = handler;
+    }
+    const lifecycle = {};
+    if (onStart) {
+        lifecycle.start = "onStart";
+        instance.onStart = onStart;
+    }
+    if (onClose) {
+        lifecycle.close = "onClose";
+        instance.onClose = onClose;
+    }
+    const meta = { id, goal, events, lifecycle };
+    return { id, goal, instance, meta };
+}
+/**
+ * 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 function mockAgent(spec) {
+    if (!spec.agentId) {
+        throw new Error("[mockAgent] spec.agentId is required");
+    }
+    if (!isMultiEngagementSpec(spec)) {
+        const engagement = buildEngagementShape("default", undefined, spec.on, spec.onStart, spec.onClose);
+        return {
+            __mockAgent: true,
+            agentId: spec.agentId,
+            engagements: [engagement],
+            targeting: { engagements: [{ id: "default", rules: [] }] },
+        };
+    }
+    if (spec.engagements.length === 0) {
+        throw new Error(`[mockAgent] agent "${spec.agentId}" has empty engagements[]`);
+    }
+    const seen = new Set();
+    const engagements = [];
+    for (const e of spec.engagements) {
+        if (!e.id) {
+            throw new Error(`[mockAgent] agent "${spec.agentId}" has an engagement with no id`);
+        }
+        if (seen.has(e.id)) {
+            throw new Error(`[mockAgent] agent "${spec.agentId}" has duplicate engagement id "${e.id}"`);
+        }
+        seen.add(e.id);
+        engagements.push(buildEngagementShape(e.id, e.goal, e.on, e.onStart, e.onClose));
+    }
+    const targeting = spec.targeting ?? {
+        engagements: [{ id: engagements[0].id, rules: [] }],
+    };
+    for (const entry of targeting.engagements) {
+        if (!seen.has(entry.id)) {
+            throw new Error(`[mockAgent] agent "${spec.agentId}" targeting references unknown engagement "${entry.id}"`);
+        }
+    }
+    return {
+        __mockAgent: true,
+        agentId: spec.agentId,
+        engagements,
+        targeting,
+        settings: spec.settings,
+    };
+}
+/** Type-guard used by `testPlatform` to dispatch on source kind. */
+export function isMockAgentDescriptor(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        value.__mockAgent === true);
+}
+//# sourceMappingURL=mock-agent.js.map

package/dist/peers/mock-agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-agent.js","sourceRoot":"","sources":["../../src/peers/mock-agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAgGH,gFAAgF;AAChF,gFAAgF;AAChF,gFAAgF;AAEhF,SAAS,qBAAqB,CAC5B,IAAmB;IAEnB,OAAO,KAAK,CAAC,OAAO,CACjB,IAAqC,CAAC,WAAW,CACnD,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,SAAS,oBAAoB,CAC3B,EAAU,EACV,IAAwB,EACxB,EAAgD,EAChD,OAAyC,EACzC,OAAyC;IAEzC,MAAM,MAAM,GAA2B,EAAE,CAAC;IAC1C,MAAM,QAAQ,GAA4B,EAAE,CAAC;IAE7C,KAAK,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;QACvD,MAAM,IAAI,GAAG,MAAM,IAAI,EAAE,CAAC;QAC1B,MAAM,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;QACpB,QAAQ,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC;IAC3B,CAAC;IAED,MAAM,SAAS,GAAgC,EAAE,CAAC;IAClD,IAAI,OAAO,EAAE,CAAC;QACZ,SAAS,CAAC,KAAK,GAAG,SAAS,CAAC;QAC5B,QAAQ,CAAC,OAAO,GAAG,OAAO,CAAC;IAC7B,CAAC;IACD,IAAI,OAAO,EAAE,CAAC;QACZ,SAAS,CAAC,KAAK,GAAG,SAAS,CAAC;QAC5B,QAAQ,CAAC,OAAO,GAAG,OAAO,CAAC;IAC7B,CAAC;IAED,MAAM,IAAI,GAAmB,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;IAC7D,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;AACtC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,SAAS,CAAC,IAAmB;IAC3C,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;QAClB,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC;IAC1D,CAAC;IAED,IAAI,CAAC,qBAAqB,CAAC,IAAI,CAAC,EAAE,CAAC;QACjC,MAAM,UAAU,GAAG,oBAAoB,CACrC,SAAS,EACT,SAAS,EACT,IAAI,CAAC,EAAE,EACP,IAAI,CAAC,OAAO,EACZ,IAAI,CAAC,OAAO,CACb,CAAC;QACF,OAAO;YACL,WAAW,EAAE,IAAI;YACjB,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,WAAW,EAAE,CAAC,UAAU,CAAC;YACzB,SAAS,EAAE,EAAE,WAAW,EAAE,CAAC,EAAE,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,EAAE;SAC3D,CAAC;IACJ,CAAC;IAED,IAAI,IAAI,CAAC,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAClC,MAAM,IAAI,KAAK,CACb,sBAAsB,IAAI,CAAC,OAAO,2BAA2B,CAC9D,CAAC;IACJ,CAAC;IAED,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,WAAW,GAA+B,EAAE,CAAC;IACnD,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;QACjC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;YACV,MAAM,IAAI,KAAK,CACb,sBAAsB,IAAI,CAAC,OAAO,gCAAgC,CACnE,CAAC;QACJ,CAAC;QACD,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;YACnB,MAAM,IAAI,KAAK,CACb,sBAAsB,IAAI,CAAC,OAAO,kCAAkC,CAAC,CAAC,EAAE,GAAG,CAC5E,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACf,WAAW,CAAC,IAAI,CACd,oBAAoB,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,CAC/D,CAAC;IACJ,CAAC;IAED,MAAM,SAAS,GAAc,IAAI,CAAC,SAAS,IAAI;QAC7C,WAAW,EAAE,CAAC,EAAE,EAAE,EAAE,WAAW,CAAC,CAAC,CAAE,CAAC,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;KACrD,CAAC;IACF,KAAK,MAAM,KAAK,IAAI,SAAS,CAAC,WAAW,EAAE,CAAC;QAC1C,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CACb,sBAAsB,IAAI,CAAC,OAAO,8CAA8C,KAAK,CAAC,EAAE,GAAG,CAC5F,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO;QACL,WAAW,EAAE,IAAI;QACjB,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,WAAW;QACX,SAAS;QACT,QAAQ,EAAE,IAAI,CAAC,QAAQ;KACxB,CAAC;AACJ,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,qBAAqB,CACnC,KAAc;IAEd,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACb,KAAmC,CAAC,WAAW,KAAK,IAAI,CAC1D,CAAC;AACJ,CAAC"}

package/dist/platform/event-runtime.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Event router for the multi-agent simulator.
+ *
+ * Partitions events by `(vaultId, scope, context)` (per contract §6) and
+ * fans them out to every connected agent whose manifest's `events` map
+ * names the event type. The actual invocation is delegated to the
+ * orchestrator so each delivery becomes a tracked Job/Activity.
+ *
+ * Determinism note: deliveries are awaited sequentially in connection-order
+ * (`Map` insertion order). Tests then see a stable causal ordering:
+ *   user publishes E1 → agent A handles E1, publishes E2 → agent B handles
+ *   E2 → … with each `await vault.scope().publish(...)` returning only
+ *   after the entire chain settles.
+ */
+import type { AgentConnection, VaultEvent } from "./vault.js";
+import type { Orchestrator } from "./orchestrator.js";
+export interface EventRuntime {
+    /**
+     * Deliver `event` to every connection in `connections` whose manifest
+     * declares a handler for `event.type`. Awaits all deliveries (one
+     * orchestrator dispatch per connection) before resolving.
+     */
+    publish(event: VaultEvent, connections: Iterable<AgentConnection>): Promise<void>;
+}
+export declare function createEventRuntime(opts: {
+    orchestrator: Orchestrator;
+}): EventRuntime;
+//# sourceMappingURL=event-runtime.d.ts.map

package/dist/platform/event-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-runtime.d.ts","sourceRoot":"","sources":["../../src/platform/event-runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtD,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,OAAO,CACL,KAAK,EAAE,UAAU,EACjB,WAAW,EAAE,QAAQ,CAAC,eAAe,CAAC,GACrC,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE;IACvC,YAAY,EAAE,YAAY,CAAC;CAC5B,GAAG,YAAY,CAuBf"}

package/dist/platform/event-runtime.js

@@ -0,0 +1,38 @@
+/**
+ * Event router for the multi-agent simulator.
+ *
+ * Partitions events by `(vaultId, scope, context)` (per contract §6) and
+ * fans them out to every connected agent whose manifest's `events` map
+ * names the event type. The actual invocation is delegated to the
+ * orchestrator so each delivery becomes a tracked Job/Activity.
+ *
+ * Determinism note: deliveries are awaited sequentially in connection-order
+ * (`Map` insertion order). Tests then see a stable causal ordering:
+ *   user publishes E1 → agent A handles E1, publishes E2 → agent B handles
+ *   E2 → … with each `await vault.scope().publish(...)` returning only
+ *   after the entire chain settles.
+ */
+export function createEventRuntime(opts) {
+    const { orchestrator } = opts;
+    return {
+        async publish(event, connections) {
+            // Collect first so we don't observe mutation mid-iteration if a
+            // handler reaches back into the vault to connect/disconnect agents.
+            // Routing matches if ANY engagement on the connection declares a
+            // handler for this event type — the orchestrator picks the right
+            // engagement per Job from `manifest.targeting`. (ADR-019 H4)
+            const targets = [];
+            for (const c of connections) {
+                const handles = c.manifest.engagements.some((e) => event.type in e.events);
+                if (handles)
+                    targets.push(c);
+            }
+            // Sequential ordering keeps the simulator deterministic. Production
+            // can fan out concurrently — the simulator does not.
+            for (const c of targets) {
+                await orchestrator.dispatch(c, event);
+            }
+        },
+    };
+}
+//# sourceMappingURL=event-runtime.js.map

package/dist/platform/event-runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-runtime.js","sourceRoot":"","sources":["../../src/platform/event-runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAiBH,MAAM,UAAU,kBAAkB,CAAC,IAElC;IACC,MAAM,EAAE,YAAY,EAAE,GAAG,IAAI,CAAC;IAC9B,OAAO;QACL,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,WAAW;YAC9B,gEAAgE;YAChE,oEAAoE;YACpE,iEAAiE;YACjE,iEAAiE;YACjE,6DAA6D;YAC7D,MAAM,OAAO,GAAsB,EAAE,CAAC;YACtC,KAAK,MAAM,CAAC,IAAI,WAAW,EAAE,CAAC;gBAC5B,MAAM,OAAO,GAAG,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,CACzC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,CAAC,MAAM,CAC9B,CAAC;gBACF,IAAI,OAAO;oBAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAC/B,CAAC;YACD,oEAAoE;YACpE,qDAAqD;YACrD,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;gBACxB,MAAM,YAAY,CAAC,QAAQ,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;YACxC,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/platform/orchestrator.d.ts

@@ -0,0 +1,86 @@
+/**
+ * In-memory Job/Activity store for the multi-agent simulator.
+ *
+ * Maps the contract §4 state machine onto plain TypeScript records:
+ * `Job` partitioned by `(vaultId, scope, context, agentId)`, lifetime
+ * `active` → `terminal`, with a synthetic `__start__` Activity inserted on
+ * first dispatch (per contract §6.1) and a synthetic `__close__` Activity
+ * inserted on terminal transition.
+ *
+ * This is not a persistent store — everything lives in two `Map`s and the
+ * simulator wipes them when the platform is disposed. The shape is
+ * deliberately faithful to the production orchestrator so app-side test
+ * code (`vault.jobs.list(...)`) reads the same fields.
+ */
+import type { AgentConnection, VaultEvent } from "./vault.js";
+import type { Runtime } from "./runtime.js";
+export type JobState = "active" | "terminal";
+export type ActivityStatus = "pending" | "running" | "completed" | "failed";
+export interface Activity {
+    activityId: string;
+    jobId: string;
+    /**
+     * Either a real event type (e.g. `"user_message"`) or a synthetic
+     * lifecycle marker (`"__start__"` / `"__close__"`).
+     */
+    eventType: string;
+    status: ActivityStatus;
+    startedAt?: number;
+    completedAt?: number;
+    result?: unknown;
+    error?: string;
+    attemptNumber: number;
+}
+export interface Job {
+    jobId: string;
+    agentId: string;
+    vaultId: string;
+    scope: string;
+    context: string;
+    /**
+     * The engagement this Job is pinned to. Decided once at Job creation by
+     * evaluating the agent's `manifest.targeting` against the connection's
+     * `settings` — fixed for the Job's life (ADR-019).
+     */
+    engagementId: string;
+    state: JobState;
+    terminalReason?: string;
+    activities: Activity[];
+    createdAt: number;
+}
+export interface JobsFilter {
+    agentId?: string;
+    state?: JobState;
+    /**
+     * Restrict to jobs owned by this user (ADR-019 H5). Per-user vaults pass
+     * their own `vaultId` automatically; callers reaching the orchestrator
+     * directly can opt into a cross-user view by omitting this field.
+     */
+    vaultId?: string;
+}
+export interface Orchestrator {
+    /**
+     * Route a `(connection, event)` pair through the simulator: ensure a Job
+     * exists, fire the synthetic `__start__` activity if newly created, then
+     * run the real handler activity via the {@link Runtime}.
+     */
+    dispatch(connection: AgentConnection, event: VaultEvent): Promise<void>;
+    /**
+     * Mark a Job terminal. Synthesises a `__close__` Activity (if the
+     * connection's manifest declares an `onClose` / `@OnClose` hook) before
+     * flipping state.
+     */
+    terminate(jobId: string, reason: string, connection?: AgentConnection): Promise<void>;
+    /** Filter the in-memory job store. */
+    list(filter?: JobsFilter): Job[];
+    /** Direct lookup by `jobId`. */
+    get(jobId: string): Job | undefined;
+    /** Underlying map — exposed so the platform can clear it on `dispose()`. */
+    jobs: Map<string, Job>;
+}
+export interface OrchestratorOptions {
+    clock: () => number;
+    runtime: Runtime;
+}
+export declare function createOrchestrator(opts: OrchestratorOptions): Orchestrator;
+//# sourceMappingURL=orchestrator.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrator.d.ts","sourceRoot":"","sources":["../../src/platform/orchestrator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC9D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAO5C,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,UAAU,CAAC;AAC7C,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,CAAC;AAE5E,MAAM,WAAW,QAAQ;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,cAAc,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,GAAG;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,QAAQ,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,QAAQ,EAAE,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,eAAe,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAExE;;;;OAIG;IACH,SAAS,CACP,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,UAAU,CAAC,EAAE,eAAe,GAC3B,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB,sCAAsC;IACtC,IAAI,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,GAAG,EAAE,CAAC;IAEjC,gCAAgC;IAChC,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,GAAG,SAAS,CAAC;IAEpC,4EAA4E;IAC5E,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CACxB;AAMD,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,MAAM,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,mBAAmB,GAAG,YAAY,CAiL1E"}

package/dist/platform/orchestrator.js

@@ -0,0 +1,164 @@
+/**
+ * In-memory Job/Activity store for the multi-agent simulator.
+ *
+ * Maps the contract §4 state machine onto plain TypeScript records:
+ * `Job` partitioned by `(vaultId, scope, context, agentId)`, lifetime
+ * `active` → `terminal`, with a synthetic `__start__` Activity inserted on
+ * first dispatch (per contract §6.1) and a synthetic `__close__` Activity
+ * inserted on terminal transition.
+ *
+ * This is not a persistent store — everything lives in two `Map`s and the
+ * simulator wipes them when the platform is disposed. The shape is
+ * deliberately faithful to the production orchestrator so app-side test
+ * code (`vault.jobs.list(...)`) reads the same fields.
+ */
+import { evaluateTargeting } from "./targeting.js";
+export function createOrchestrator(opts) {
+    const { clock, runtime } = opts;
+    const jobs = new Map();
+    /**
+     * Composite-key index for dedup on `(vaultId, scope, context, agentId)`.
+     * ADR-019 H5: `vaultId` is the user identity, so two users connecting the
+     * same agent on the same scope + context get independent Jobs.
+     */
+    const jobByKey = new Map();
+    const partitionKey = (vaultId, scope, context, agentId) => `${vaultId}::${scope}::${context}::${agentId}`;
+    const orchestrator = {
+        jobs,
+        list(filter) {
+            const out = [];
+            for (const job of jobs.values()) {
+                if (filter?.agentId && job.agentId !== filter.agentId)
+                    continue;
+                if (filter?.state && job.state !== filter.state)
+                    continue;
+                if (filter?.vaultId && job.vaultId !== filter.vaultId)
+                    continue;
+                out.push(job);
+            }
+            return out;
+        },
+        get(jobId) {
+            return jobs.get(jobId);
+        },
+        async dispatch(connection, event) {
+            const key = partitionKey(event.vaultId, event.scope, event.context, connection.agentId);
+            let jobId = jobByKey.get(key);
+            let job = jobId ? jobs.get(jobId) : undefined;
+            let isNew = false;
+            if (!job) {
+                // ADR-019 H4: pick the engagement at Job creation by evaluating the
+                // connection's targeting decision table against its settings. The
+                // chosen engagement id is pinned for the Job's life.
+                const engagementId = evaluateTargeting(connection.manifest.targeting, connection.settings);
+                // Targeting must resolve to a declared engagement; otherwise the
+                // configuration is broken and we'd silently misroute.
+                const engagement = connection.manifest.engagements.find((e) => e.id === engagementId);
+                if (!engagement) {
+                    throw new Error(`[orchestrator] targeting resolved engagement "${engagementId}" but agent "${connection.agentId}" has no such engagement`);
+                }
+                jobId = `job-${randomHex(8)}`;
+                job = {
+                    jobId,
+                    agentId: connection.agentId,
+                    // ADR-019 H5: vaultId comes from the event (= publishing user id).
+                    vaultId: event.vaultId,
+                    scope: event.scope,
+                    context: event.context,
+                    engagementId,
+                    state: "active",
+                    activities: [],
+                    createdAt: clock(),
+                };
+                jobs.set(jobId, job);
+                jobByKey.set(key, jobId);
+                isNew = true;
+            }
+            // Don't deliver to terminal jobs — match the production orchestrator's
+            // refusal-to-dispatch behaviour.
+            if (job.state === "terminal")
+                return;
+            const engagement = connection.manifest.engagements.find((e) => e.id === job.engagementId);
+            // Safety: the engagement was resolved at Job creation; if it's gone
+            // from the connection's manifest now, something is badly wrong.
+            if (!engagement) {
+                throw new Error(`[orchestrator] job "${job.jobId}" pinned to engagement "${job.engagementId}" which is no longer declared on agent "${connection.agentId}"`);
+            }
+            // §6.1: first event into a new (vault, scope, context, agent) job
+            // synthesises a __start__ activity that runs before the real handler.
+            // Lifecycle hooks resolve through the pinned engagement, NOT the agent.
+            if (isNew && engagement.lifecycle?.start) {
+                await runActivity(job, "__start__", async () => {
+                    await runtime.invoke(connection, job.engagementId, "__start__", event);
+                });
+            }
+            // If this engagement doesn't handle this event type, drop the event at
+            // the Job level — it never re-routes to a different engagement, since
+            // the Job is pinned (ADR-019).
+            if (!(event.type in engagement.events))
+                return;
+            await runActivity(job, event.type, async () => {
+                await runtime.invoke(connection, job.engagementId, event.type, event);
+            });
+        },
+        async terminate(jobId, reason, connection) {
+            const job = jobs.get(jobId);
+            if (!job || job.state === "terminal")
+                return;
+            if (connection) {
+                const engagement = connection.manifest.engagements.find((e) => e.id === job.engagementId);
+                if (engagement?.lifecycle?.close) {
+                    await runActivity(job, "__close__", async () => {
+                        await runtime.invoke(connection, job.engagementId, "__close__", {
+                            id: `evt-${randomHex(8)}`,
+                            type: "__close__",
+                            ts: clock(),
+                            from: "runtime",
+                            payload: { reason },
+                            vaultId: job.vaultId,
+                            scope: job.scope,
+                            context: job.context,
+                        });
+                    });
+                }
+            }
+            job.state = "terminal";
+            job.terminalReason = reason;
+        },
+    };
+    /**
+     * Wrap `fn` in an Activity record: append with `running`, then mark
+     * `completed` / `failed` based on the outcome. Errors are stored on the
+     * activity (not rethrown) — a handler crashing should not stop other
+     * agents from receiving the same event in the simulator.
+     */
+    async function runActivity(job, eventType, fn) {
+        const activity = {
+            activityId: `act-${randomHex(8)}`,
+            jobId: job.jobId,
+            eventType,
+            status: "running",
+            startedAt: clock(),
+            attemptNumber: 1,
+        };
+        job.activities.push(activity);
+        try {
+            await fn();
+            activity.status = "completed";
+            activity.completedAt = clock();
+        }
+        catch (err) {
+            activity.status = "failed";
+            activity.completedAt = clock();
+            activity.error =
+                err instanceof Error ? `${err.name}: ${err.message}` : String(err);
+        }
+    }
+    return orchestrator;
+}
+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=orchestrator.js.map

package/dist/platform/orchestrator.js.map

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

package/dist/platform/runtime.d.ts

@@ -0,0 +1,66 @@
+/**
+ * In-process runtime for the multi-agent simulator.
+ *
+ * In production, the runtime is responsible for marshalling events into a
+ * sandbox (e.g. v8 isolate) and presenting a `ctx` to user code. In the
+ * simulator we skip the sandbox entirely and call the agent's instance
+ * method directly — same JavaScript process. The `ctx` is built fresh per
+ * invocation and closes over the platform's vault, orchestrator, cubbies
+ * and shared mocks.
+ *
+ * This is what makes app-side `vault.scope(...).publish` and agent-side
+ * `ctx.publish` route through the same in-memory bus.
+ */
+import type { ModelHandle } from "@cef-ai/agent-sdk";
+import type { TestCubby } from "../harness/cubby.js";
+import type { FetchMock } from "../harness/fetch-mock.js";
+import type { ModelMockHandle } from "../harness/model-mock.js";
+import type { AgentConnection, Vault, VaultEvent } from "./vault.js";
+/**
+ * Synthetic lifecycle "events" used to drive `@OnStart` / `@OnClose`
+ * hooks through the same dispatch path as real events.
+ */
+export interface SyntheticLifecycleEvent {
+    /** `"__start__"` or `"__close__"`. */
+    type: "__start__" | "__close__";
+    /** Carries `{ reason }` for close. */
+    payload: unknown;
+    vaultId: string;
+    scope: string;
+    context: string;
+}
+export interface Runtime {
+    /**
+     * Invoke a handler on `connection.engagementInstances[engagementId]`.
+     * `eventTypeOrLifecycle` is either an actual event type (looked up in the
+     * engagement's `events` map) or one of `"__start__"` / `"__close__"`. The
+     * runtime handles ctx construction; callers supply only the event payload,
+     * the chosen engagement, and the routing.
+     */
+    invoke(connection: AgentConnection, engagementId: string, eventTypeOrLifecycle: string, event: VaultEvent | SyntheticLifecycleEvent): Promise<unknown>;
+}
+export interface RuntimeOptions {
+    /**
+     * Resolve the per-user vault by `vaultId`. Vault and runtime form a cycle
+     * (runtime needs vault for `ctx.publish` → `vault.scope().publish`; vault
+     * needs runtime via the orchestrator), so the platform threads a lookup.
+     * ADR-019 H5: with per-user vaults, `ctx.publish` from a handler must
+     * land back in the *publishing user's* vault — the same one the event
+     * arrived on, identified by `event.vaultId`.
+     */
+    vault: (vaultId: string) => Vault;
+    /**
+     * Per-`(user, agent)` cubby map (`vaultId` → `agentId` → `alias` → cubby).
+     * Owned by the platform. Each event's vaultId selects the user's slice
+     * before alias lookup so cubby state stays partitioned.
+     */
+    cubbies: Map<string, Map<string, Map<string, TestCubby>>>;
+    /** Shared fetch mock attached to every agent's `ctx.fetch`. */
+    fetchMock: FetchMock;
+    /** Shared model handles attached to every agent's `ctx.models`. */
+    models: Record<string, ModelHandle | ModelMockHandle>;
+    /** Shared monotonic clock. */
+    clock: () => number;
+}
+export declare function createRuntime(opts: RuntimeOptions): Runtime;
+//# sourceMappingURL=runtime.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/platform/runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAGV,WAAW,EAEZ,MAAM,mBAAmB,CAAC;AAE3B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAErE;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACtC,sCAAsC;IACtC,IAAI,EAAE,WAAW,GAAG,WAAW,CAAC;IAChC,sCAAsC;IACtC,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,OAAO;IACtB;;;;;;OAMG;IACH,MAAM,CACJ,UAAU,EAAE,eAAe,EAC3B,YAAY,EAAE,MAAM,EACpB,oBAAoB,EAAE,MAAM,EAC5B,KAAK,EAAE,UAAU,GAAG,uBAAuB,GAC1C,OAAO,CAAC,OAAO,CAAC,CAAC;CACrB;AAED,MAAM,WAAW,cAAc;IAC7B;;;;;;;OAOG;IACH,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,KAAK,CAAC;IAClC;;;;OAIG;IACH,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC;IAC1D,+DAA+D;IAC/D,SAAS,EAAE,SAAS,CAAC;IACrB,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,GAAG,eAAe,CAAC,CAAC;IACtD,8BAA8B;IAC9B,KAAK,EAAE,MAAM,MAAM,CAAC;CACrB;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAoI3D"}

package/dist/platform/runtime.js

@@ -0,0 +1,116 @@
+/**
+ * In-process runtime for the multi-agent simulator.
+ *
+ * In production, the runtime is responsible for marshalling events into a
+ * sandbox (e.g. v8 isolate) and presenting a `ctx` to user code. In the
+ * simulator we skip the sandbox entirely and call the agent's instance
+ * method directly — same JavaScript process. The `ctx` is built fresh per
+ * invocation and closes over the platform's vault, orchestrator, cubbies
+ * and shared mocks.
+ *
+ * This is what makes app-side `vault.scope(...).publish` and agent-side
+ * `ctx.publish` route through the same in-memory bus.
+ */
+export function createRuntime(opts) {
+    const { vault, cubbies, fetchMock, models } = opts;
+    // `opts.clock` is accepted for symmetry / future use (e.g. ctx-side
+    // telemetry stamps); not consumed by the current ctx surface.
+    void opts.clock;
+    return {
+        async invoke(connection, engagementId, eventTypeOrLifecycle, event) {
+            const engagement = connection.manifest.engagements.find((e) => e.id === engagementId);
+            if (!engagement) {
+                throw new Error(`[runtime] engagement "${engagementId}" is not declared on agent "${connection.agentId}"`);
+            }
+            const instance = connection.engagementInstances[engagementId];
+            if (!instance) {
+                throw new Error(`[runtime] no instance for engagement "${engagementId}" on agent "${connection.agentId}"`);
+            }
+            const ctx = buildCtx(connection, event.vaultId, event.scope, event.context);
+            // Resolve handler name: real events look it up in the engagement's
+            // `events` map; lifecycle events resolve through `lifecycle.start` /
+            // `lifecycle.close`.
+            let handlerName;
+            if (eventTypeOrLifecycle === "__start__") {
+                handlerName = engagement.lifecycle?.start;
+            }
+            else if (eventTypeOrLifecycle === "__close__") {
+                handlerName = engagement.lifecycle?.close;
+            }
+            else {
+                handlerName = engagement.events[eventTypeOrLifecycle];
+            }
+            if (!handlerName)
+                return;
+            const fn = instance[handlerName];
+            if (typeof fn !== "function") {
+                throw new Error(`[runtime] handler "${handlerName}" for "${eventTypeOrLifecycle}" is not a function on agent "${connection.agentId}" engagement "${engagementId}"`);
+            }
+            // `@OnClose` is invoked with `(ctx, reason)` per the SDK contract; all
+            // other handlers receive `(event, ctx)`. Lifecycle start has just `ctx`.
+            if (eventTypeOrLifecycle === "__start__") {
+                return await fn.call(instance, ctx);
+            }
+            if (eventTypeOrLifecycle === "__close__") {
+                const reason = event.payload
+                    ?.reason ?? "closed_by_agent";
+                return await fn.call(instance, ctx, reason);
+            }
+            return await fn.call(instance, event, ctx);
+        },
+    };
+    /**
+     * Build a per-invocation `ctx`. Closes over the vault id + scope/context
+     * the event arrived on — `ctx.publish` re-publishes within the same
+     * (user, scope, context) so peers in that user's scope can pick it up.
+     */
+    function buildCtx(connection, vaultId, scope, context) {
+        const settings = Object.freeze({ ...connection.settings });
+        return {
+            cubby(alias) {
+                // ADR-019 H5: cubbies are per-user — select the publishing user's
+                // slice before alias lookup so two users sharing an agent don't
+                // see each other's cubby state.
+                const userCubbies = cubbies.get(vaultId);
+                const c = userCubbies?.get(connection.agentId)?.get(alias);
+                if (!c) {
+                    throw new Error(`[runtime] cubby "${alias}" not declared for agent "${connection.agentId}"`);
+                }
+                return { query: c.query.bind(c), exec: c.exec.bind(c) };
+            },
+            models: models,
+            fetch: fetchMock.fetch,
+            async publish(type, payload) {
+                // Re-enter the publishing user's vault on the same scope/context
+                // so peers and the app-side stream both observe handler-published
+                // events under the right vaultId.
+                await vault(vaultId)
+                    .scope(scope)
+                    .publish(type, payload, {
+                    context,
+                    from: connection.agentId,
+                });
+            },
+            settings,
+            async close(reason) {
+                // Agent-initiated close terminates the job for this user's
+                // (scope, context, agent) partition. We look up the job via the
+                // user's vault (which carries the orchestrator).
+                const v = vault(vaultId);
+                const job = v.jobs
+                    .list({ agentId: connection.agentId })
+                    .find((j) => j.scope === scope && j.context === context);
+                if (job) {
+                    await v._terminate(job.jobId, reason ?? "closed_by_agent", connection);
+                }
+            },
+            log: {
+                info() { },
+                warn() { },
+                error() { },
+                debug() { },
+            },
+        };
+    }
+}
+//# sourceMappingURL=runtime.js.map