@ixo/oracle-runtime 0.0.1

package/dist/testing/integration/sse-parser.js

@@ -0,0 +1,125 @@
+/* eslint-disable no-console */
+/**
+ * SSE event types + stream parser for integration tests.
+ *
+ * **MIRROR of `packages/oracles-client-sdk/src/utils/sse-parser.ts`.**
+ * Keep both files in sync. The SSE wire format is the contract between
+ * the runtime (server) and the client SDK (frontend) — tests need to
+ * parse it exactly the way real clients do, with the same typed event
+ * union, or they'll drift from production behavior.
+ *
+ * Cross-package import was rejected because `oracles-client-sdk` is a
+ * React-tagged package (`"use client"`) and importing into a Node test
+ * harness creates an awkward dependency direction. Duplication of a
+ * shared wire contract is the lesser evil. If this file ever changes,
+ * update its twin in the client SDK at the same time.
+ */
+function isValidSSEEventType(eventType) {
+    const validEventTypes = [
+        'message',
+        'tool_call',
+        'action_call',
+        'error',
+        'done',
+        'router.update',
+        'render_component',
+        'browser_tool_call',
+        'message_cache_invalidation',
+        'reasoning',
+    ];
+    return validEventTypes.includes(eventType);
+}
+/**
+ * Parse SSE stream from a ReadableStream reader. Yields typed `SSEEvent`s.
+ * Handles buffer management across chunk boundaries, JSON parse errors,
+ * and graceful abort behavior.
+ */
+export async function* parseSSEStream(reader) {
+    const decoder = new TextDecoder();
+    let buffer = '';
+    try {
+        while (true) {
+            let readResult;
+            try {
+                readResult = await reader.read();
+            }
+            catch (readError) {
+                if (readError instanceof Error &&
+                    (readError.name === 'AbortError' ||
+                        (readError instanceof DOMException &&
+                            readError.name === 'AbortError'))) {
+                    break;
+                }
+                throw readError;
+            }
+            const { done, value } = readResult;
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            const lines = buffer.split('\n');
+            buffer = lines.pop() || '';
+            let event = '';
+            let data = '';
+            for (const line of lines) {
+                const trimmedLine = line.trim();
+                if (trimmedLine === '' || trimmedLine.startsWith(':')) {
+                    if (event && data) {
+                        try {
+                            const parsedData = JSON.parse(data);
+                            if (isValidSSEEventType(event)) {
+                                yield { event, data: parsedData };
+                            }
+                        }
+                        catch (parseError) {
+                            console.warn('Failed to parse SSE data:', data, parseError);
+                        }
+                        event = '';
+                        data = '';
+                    }
+                    continue;
+                }
+                if (trimmedLine.startsWith('event:')) {
+                    event = trimmedLine.slice(6).trim();
+                }
+                else if (trimmedLine.startsWith('data:')) {
+                    data = trimmedLine.slice(5).trim();
+                }
+            }
+        }
+        // Flush any trailing event left in the buffer.
+        if (buffer.trim()) {
+            const lines = buffer.split('\n');
+            let event = '';
+            let data = '';
+            for (const line of lines) {
+                const trimmedLine = line.trim();
+                if (trimmedLine.startsWith('event:')) {
+                    event = trimmedLine.slice(6).trim();
+                }
+                else if (trimmedLine.startsWith('data:')) {
+                    data = trimmedLine.slice(5).trim();
+                }
+            }
+            if (event && data) {
+                try {
+                    const parsedData = JSON.parse(data);
+                    if (isValidSSEEventType(event)) {
+                        yield { event, data: parsedData };
+                    }
+                }
+                catch (parseError) {
+                    console.warn('Failed to parse final SSE data:', data, parseError);
+                }
+            }
+        }
+    }
+    catch (error) {
+        if (error instanceof Error &&
+            (error.name === 'AbortError' ||
+                (error instanceof DOMException && error.name === 'AbortError'))) {
+            return;
+        }
+        console.error('Error parsing SSE stream:', error);
+        throw error;
+    }
+}

package/dist/testing/integration/ucan.d.ts

@@ -0,0 +1,74 @@
+/**
+ * UCAN delegation minting for integration tests.
+ *
+ * Wraps `@ixo/ucan`'s `signerFromMnemonic` + `createDelegation` +
+ * `serializeDelegation` pipeline into one call. The result is a base64
+ * CAR-encoded delegation string suitable for the `x-ucan-delegation`
+ * request header — what the runtime's `AuthHeaderMiddleware` validates.
+ *
+ * Capability constants below match the strings the runtime / plugins
+ * already expect. **Composio routes through the sandbox capability** —
+ * there is no separate `composioCap` and tests that exercise composio
+ * must include `sandboxCap` in their capability set.
+ */
+import { type Capability } from '@ixo/ucan';
+/** Memory plugin capability — read/write user memories. */
+export declare const memoryCap: Capability;
+/**
+ * Sandbox capability — covers the sandbox plugin AND Composio (composio
+ * routes through the sandbox infra). There is intentionally no
+ * `composioCap`; tests that need composio access list `sandboxCap`.
+ */
+export declare const sandboxCap: Capability;
+/** Skills plugin capability — search/list/run skill capsules. */
+export declare const skillsCap: Capability;
+/** Subscriptions read capability — covers the credits middleware lookup. */
+export declare const subscriptionsReadCap: Capability;
+/** Convenience: the full capability bundle for "no-friction" tests. */
+export declare const allCaps: Capability[];
+/** Options accepted by `mintUserDelegation`. */
+export interface MintUserDelegationOptions {
+    /**
+     * BIP39 mnemonic for the test user. Stored in `.env.integration` as
+     * `TEST_USER_MNEMONIC`. Test files normally pass
+     * `process.env.TEST_USER_MNEMONIC!`.
+     */
+    userMnemonic: string;
+    /**
+     * The oracle's DID — the delegation's audience. Tests normally pass
+     * `process.env.ORACLE_DID!`. Matches the `serverDid` the runtime's
+     * UCAN validator boots with.
+     */
+    oracleDid: string;
+    /**
+     * The test user's DID. Defaults to the DID derived from the mnemonic
+     * by `signerFromMnemonic`. Pass `process.env.TEST_USER_DID!` when the
+     * user has an on-chain Ed25519 verification method so the issuer string
+     * matches what the chain-aware validator resolves.
+     */
+    userDid?: string;
+    /**
+     * Capabilities granted by the delegation. Tests that exercise UCAN
+     * failure modes pass a narrower set (e.g. `[memoryCap]` to a sandbox
+     * test to assert a clean auth error).
+     */
+    capabilities: Capability[];
+    /**
+     * Time-to-live, in **seconds** (not ms — `@ixo/ucan` uses Unix seconds
+     * for expiration). Defaults to 7 days.
+     */
+    ttlSec?: number;
+}
+/**
+ * Mint a real Ed25519-signed UCAN delegation string for the test user.
+ *
+ * Pipeline (verbatim per the integration-testing spec §6/§8 Phase 0.6):
+ *
+ *   `signerFromMnemonic(userMnemonic, userDid?)` → `createDelegation({
+ *      issuer, audience: oracleDid, capabilities, expiration: now+ttl })` →
+ *   `serializeDelegation()`
+ *
+ * `expiration` is Unix **seconds**, not milliseconds — a frequent footgun.
+ */
+export declare function mintUserDelegation(opts: MintUserDelegationOptions): Promise<string>;
+//# sourceMappingURL=ucan.d.ts.map

package/dist/testing/integration/ucan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ucan.d.ts","sourceRoot":"","sources":["../../../src/testing/integration/ucan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAIL,KAAK,UAAU,EAChB,MAAM,WAAW,CAAC;AAkCnB,2DAA2D;AAC3D,eAAO,MAAM,SAAS,EAAE,UAGvB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,UAAU,EAAE,UAGxB,CAAC;AAEF,iEAAiE;AACjE,eAAO,MAAM,SAAS,EAAE,UAGvB,CAAC;AAEF,4EAA4E;AAC5E,eAAO,MAAM,oBAAoB,EAAE,UAGlC,CAAC;AAEF,uEAAuE;AACvE,eAAO,MAAM,OAAO,EAAE,UAAU,EAK/B,CAAC;AAEF,gDAAgD;AAChD,MAAM,WAAW,yBAAyB;IACxC;;;;OAIG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,YAAY,EAAE,UAAU,EAAE,CAAC;IAC3B;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,yBAAyB,GAC9B,OAAO,CAAC,MAAM,CAAC,CAiBjB"}

package/dist/testing/integration/ucan.js

@@ -0,0 +1,95 @@
+/**
+ * UCAN delegation minting for integration tests.
+ *
+ * Wraps `@ixo/ucan`'s `signerFromMnemonic` + `createDelegation` +
+ * `serializeDelegation` pipeline into one call. The result is a base64
+ * CAR-encoded delegation string suitable for the `x-ucan-delegation`
+ * request header — what the runtime's `AuthHeaderMiddleware` validates.
+ *
+ * Capability constants below match the strings the runtime / plugins
+ * already expect. **Composio routes through the sandbox capability** —
+ * there is no separate `composioCap` and tests that exercise composio
+ * must include `sandboxCap` in their capability set.
+ */
+import { createDelegation, serializeDelegation, signerFromMnemonic, } from '@ixo/ucan';
+/** Type predicate: tag a string as the `did:ixo:` brand `@ixo/ucan` accepts. */
+function isIxoDid(did) {
+    return did.startsWith('did:ixo:');
+}
+/** Type predicate: tag a string as the `did:key:` brand `@ixo/ucan` accepts. */
+function isKeyDid(did) {
+    return did.startsWith('did:key:');
+}
+/**
+ * Narrow a string DID to one of the brands the UCAN library accepts. Returns
+ * `undefined` for `undefined` input (so the caller can fall through to the
+ * signer's auto-derived `did:key:` identity); throws for unsupported methods
+ * so a typo in `.env.integration` fails loudly.
+ */
+function toSupportedDid(did) {
+    if (did === undefined)
+        return undefined;
+    if (isIxoDid(did))
+        return did;
+    if (isKeyDid(did))
+        return did;
+    const prefix = did.split(':').slice(0, 2).join(':');
+    throw new Error(`[mintUserDelegation] Unsupported DID method '${prefix}' — ` +
+        `only did:ixo: and did:key: are accepted. Got: ${did}`);
+}
+/** One week in seconds — default TTL for a test delegation. */
+const ONE_WEEK_SECONDS = 7 * 24 * 60 * 60;
+/** Memory plugin capability — read/write user memories. */
+export const memoryCap = {
+    can: 'memory/*',
+    with: 'ixo:memory',
+};
+/**
+ * Sandbox capability — covers the sandbox plugin AND Composio (composio
+ * routes through the sandbox infra). There is intentionally no
+ * `composioCap`; tests that need composio access list `sandboxCap`.
+ */
+export const sandboxCap = {
+    can: 'sandbox/*',
+    with: 'ixo:sandbox',
+};
+/** Skills plugin capability — search/list/run skill capsules. */
+export const skillsCap = {
+    can: 'skills/*',
+    with: 'ixo:skills',
+};
+/** Subscriptions read capability — covers the credits middleware lookup. */
+export const subscriptionsReadCap = {
+    can: 'subscriptions/read',
+    with: 'ixo:subscriptions',
+};
+/** Convenience: the full capability bundle for "no-friction" tests. */
+export const allCaps = [
+    memoryCap,
+    sandboxCap,
+    skillsCap,
+    subscriptionsReadCap,
+];
+/**
+ * Mint a real Ed25519-signed UCAN delegation string for the test user.
+ *
+ * Pipeline (verbatim per the integration-testing spec §6/§8 Phase 0.6):
+ *
+ *   `signerFromMnemonic(userMnemonic, userDid?)` → `createDelegation({
+ *      issuer, audience: oracleDid, capabilities, expiration: now+ttl })` →
+ *   `serializeDelegation()`
+ *
+ * `expiration` is Unix **seconds**, not milliseconds — a frequent footgun.
+ */
+export async function mintUserDelegation(opts) {
+    const ttlSec = opts.ttlSec ?? ONE_WEEK_SECONDS;
+    const expiration = Math.floor(Date.now() / 1000) + ttlSec;
+    const { signer } = await signerFromMnemonic(opts.userMnemonic, toSupportedDid(opts.userDid));
+    const delegation = await createDelegation({
+        issuer: signer,
+        audience: opts.oracleDid,
+        capabilities: opts.capabilities,
+        expiration,
+    });
+    return serializeDelegation(delegation);
+}

package/dist/testing/integration/wait-for-matrix-loaded.d.ts

@@ -0,0 +1,19 @@
+import { type IntegrationOracle } from './harness.js';
+/**
+ * Block until the booted oracle reports `matrix:loaded`. Many downstream
+ * code paths depend on the Matrix-side signing identity (loaded after init
+ * completes):
+ *
+ *   - `UcanService.mintInvocation` returns null until the signing mnemonic
+ *     is wired, so plugin Tier-A direct invocations fail.
+ *   - `SubscriptionMiddleware` rejects authenticated requests with
+ *     "UCAN signing key not configured" before the key lands.
+ *   - `RequestPreparer` resolves the user's encrypted Matrix room id from
+ *     the Matrix client when the session row doesn't carry one, which
+ *     requires Matrix to be initialized.
+ *
+ * Throws when `matrix:failed` is emitted (boot is broken — fail loudly,
+ * not after 60s of polling) or when the deadline elapses.
+ */
+export declare function waitForMatrixLoaded(oracle: IntegrationOracle, timeoutMs?: number): Promise<void>;
+//# sourceMappingURL=wait-for-matrix-loaded.d.ts.map

package/dist/testing/integration/wait-for-matrix-loaded.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wait-for-matrix-loaded.d.ts","sourceRoot":"","sources":["../../../src/testing/integration/wait-for-matrix-loaded.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEtD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,iBAAiB,EACzB,SAAS,SAAS,GACjB,OAAO,CAAC,IAAI,CAAC,CAqBf"}

package/dist/testing/integration/wait-for-matrix-loaded.js

@@ -0,0 +1,31 @@
+/**
+ * Block until the booted oracle reports `matrix:loaded`. Many downstream
+ * code paths depend on the Matrix-side signing identity (loaded after init
+ * completes):
+ *
+ *   - `UcanService.mintInvocation` returns null until the signing mnemonic
+ *     is wired, so plugin Tier-A direct invocations fail.
+ *   - `SubscriptionMiddleware` rejects authenticated requests with
+ *     "UCAN signing key not configured" before the key lands.
+ *   - `RequestPreparer` resolves the user's encrypted Matrix room id from
+ *     the Matrix client when the session row doesn't carry one, which
+ *     requires Matrix to be initialized.
+ *
+ * Throws when `matrix:failed` is emitted (boot is broken — fail loudly,
+ * not after 60s of polling) or when the deadline elapses.
+ */
+export async function waitForMatrixLoaded(oracle, timeoutMs = 60_000) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        const loaded = oracle.events.statusChanges.find((e) => e.plugin === 'matrix' && e.to === 'loaded');
+        if (loaded)
+            return;
+        const failed = oracle.events.statusChanges.find((e) => e.plugin === 'matrix' && e.to === 'failed');
+        if (failed) {
+            throw new Error(`Matrix init failed during boot: ${failed.reason ?? 'no reason given'}`);
+        }
+        await new Promise((r) => setTimeout(r, 250));
+    }
+    throw new Error(`Matrix did not reach 'loaded' within ${timeoutMs}ms — last events: ` +
+        JSON.stringify(oracle.events.statusChanges.slice(-5)));
+}

package/dist/testing/mocks.d.ts

@@ -0,0 +1,64 @@
+import type { BlobStoreAdapter, EmitAdapter, LlmAdapter, MatrixAdapter, SecretsAdapter, UcanAdapter } from '../runtime-context/ambient.js';
+import type { Logger } from '../plugin-api/types.js';
+/** Minimal `Response`-like envelope returned from `mockResponse`. */
+export interface MockResponseLike {
+    status: number;
+    ok: boolean;
+    headers: Record<string, string>;
+    json: () => Promise<unknown>;
+    text: () => Promise<string>;
+}
+/** Init options accepted by `mockResponse`. */
+export interface MockResponseInit {
+    status?: number;
+    headers?: Record<string, string>;
+}
+/**
+ * Build a minimal `Response`-shaped object suitable for `mocks.fetch`
+ * handlers. Plugins typically call `response.json()` or `response.text()` —
+ * both are covered. Non-2xx statuses set `ok: false`.
+ */
+export declare function mockResponse(body: unknown, init?: MockResponseInit): MockResponseLike;
+/** Overrides accepted by `mockMatrix`. Any unspecified method gets a no-op stub. */
+export type MockMatrixOverrides = Partial<MatrixAdapter>;
+/**
+ * Build a `MatrixAdapter` whose default methods are `vi.fn()` stubs.
+ * Overrides shadow defaults; the rest keep recorded-no-op behaviour so tests
+ * can `expect(matrix.postToRoom).toHaveBeenCalled()`.
+ */
+export declare function mockMatrix(overrides?: MockMatrixOverrides): MatrixAdapter;
+/** Options accepted by `mockLlm`. */
+export interface MockLlmOptions {
+    /** A single string or list of strings the fake model returns in order. */
+    respondWith?: string | string[];
+}
+/**
+ * Build an `LlmAdapter` backed by LangChain's official `fakeModel()` helper.
+ * The fake model exposes `.calls` and `.callCount` so plugin authors can
+ * assert on the message trajectory, plus `.respondWithTools(...)` to script
+ * tool-call sequences when needed.
+ *
+ * Docs: https://docs.langchain.com/oss/javascript/langchain/test/unit-testing
+ */
+export declare function mockLlm(opts?: MockLlmOptions): LlmAdapter;
+/**
+ * Build a `SecretsAdapter` whose `getValues` returns the supplied record
+ * (filtered to the requested keys). `getIndex` reflects the same record as
+ * `{ key: { key } }` entries.
+ */
+export declare function mockSecrets(record?: Record<string, string>): SecretsAdapter;
+/** A no-op event sink that swallows every emit (record-only via `vi.fn`). */
+export declare function mockEmit(): EmitAdapter;
+/**
+ * Build a `BlobStoreAdapter` backed by an in-memory Map. The same
+ * user-DID-namespaced behaviour as `BlobStoreService` — cross-user reads
+ * miss, malformed ids are rejected — without touching `cache-manager`.
+ */
+export declare function mockBlobStore(): BlobStoreAdapter;
+/** A permissive UCAN adapter — every check passes; mintInvocation returns a stub cid. */
+export declare function mockUcan(): UcanAdapter;
+/** A no-op logger suitable for tests. */
+export declare function mockLogger(): Logger;
+/** Public type re-export so authors can type their fetch handlers. */
+export type FetchHandler = (url: string, init?: RequestInit) => unknown | Promise<unknown>;
+//# sourceMappingURL=mocks.d.ts.map

package/dist/testing/mocks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mocks.d.ts","sourceRoot":"","sources":["../../src/testing/mocks.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,gBAAgB,EAChB,WAAW,EACX,UAAU,EACV,aAAa,EACb,cAAc,EACd,WAAW,EACZ,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EACV,MAAM,EAGP,MAAM,wBAAwB,CAAC;AAEhC,qEAAqE;AACrE,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,OAAO,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7B,IAAI,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;CAC7B;AAED,+CAA+C;AAC/C,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,OAAO,EACb,IAAI,GAAE,gBAAqB,GAC1B,gBAAgB,CAWlB;AAED,oFAAoF;AACpF,MAAM,MAAM,mBAAmB,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;AAEzD;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,SAAS,GAAE,mBAAwB,GAAG,aAAa,CAkB7E;AAED,qCAAqC;AACrC,MAAM,WAAW,cAAc;IAC7B,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;CACjC;AAED;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,IAAI,GAAE,cAAmB,GAAG,UAAU,CAc7D;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GAClC,cAAc,CAehB;AAED,6EAA6E;AAC7E,wBAAgB,QAAQ,IAAI,WAAW,CAEtC;AAED;;;;GAIG;AACH,wBAAgB,aAAa,IAAI,gBAAgB,CAsBhD;AAED,yFAAyF;AACzF,wBAAgB,QAAQ,IAAI,WAAW,CAWtC;AAED,yCAAyC;AACzC,wBAAgB,UAAU,IAAI,MAAM,CAMnC;AAED,sEAAsE;AACtE,MAAM,MAAM,YAAY,GAAG,CACzB,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,WAAW,KACf,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC"}

package/dist/testing/mocks.js

@@ -0,0 +1,141 @@
+import { vi } from 'vitest';
+import { AIMessage } from '@langchain/core/messages';
+import { fakeModel } from 'langchain';
+/**
+ * Build a minimal `Response`-shaped object suitable for `mocks.fetch`
+ * handlers. Plugins typically call `response.json()` or `response.text()` —
+ * both are covered. Non-2xx statuses set `ok: false`.
+ */
+export function mockResponse(body, init = {}) {
+    const status = init.status ?? 200;
+    const headers = init.headers ?? {};
+    const text = typeof body === 'string' ? body : JSON.stringify(body ?? null);
+    return {
+        status,
+        ok: status >= 200 && status < 300,
+        headers,
+        json: async () => (typeof body === 'string' ? JSON.parse(body) : body),
+        text: async () => text,
+    };
+}
+/**
+ * Build a `MatrixAdapter` whose default methods are `vi.fn()` stubs.
+ * Overrides shadow defaults; the rest keep recorded-no-op behaviour so tests
+ * can `expect(matrix.postToRoom).toHaveBeenCalled()`.
+ */
+export function mockMatrix(overrides = {}) {
+    const defaults = {
+        postToRoom: vi.fn(async () => 'mock-event-id'),
+        getRoomState: vi.fn(async (roomId) => ({
+            roomId,
+            state: [],
+        })),
+        getEventById: vi.fn(async (_roomId, eventId) => ({
+            eventId,
+            type: 'm.room.message',
+            content: {},
+        })),
+    };
+    return { ...defaults, ...overrides };
+}
+/**
+ * Build an `LlmAdapter` backed by LangChain's official `fakeModel()` helper.
+ * The fake model exposes `.calls` and `.callCount` so plugin authors can
+ * assert on the message trajectory, plus `.respondWithTools(...)` to script
+ * tool-call sequences when needed.
+ *
+ * Docs: https://docs.langchain.com/oss/javascript/langchain/test/unit-testing
+ */
+export function mockLlm(opts = {}) {
+    const responses = opts.respondWith === undefined
+        ? ['ok']
+        : Array.isArray(opts.respondWith)
+            ? opts.respondWith
+            : [opts.respondWith];
+    return {
+        get: () => {
+            const m = fakeModel();
+            for (const r of responses)
+                m.respond(new AIMessage(r));
+            return m;
+        },
+    };
+}
+/**
+ * Build a `SecretsAdapter` whose `getValues` returns the supplied record
+ * (filtered to the requested keys). `getIndex` reflects the same record as
+ * `{ key: { key } }` entries.
+ */
+export function mockSecrets(record = {}) {
+    return {
+        getIndex: async () => {
+            const out = {};
+            for (const k of Object.keys(record))
+                out[k] = { key: k };
+            return out;
+        },
+        getValues: async (_roomId, keys) => {
+            const out = {};
+            for (const k of keys) {
+                if (k in record)
+                    out[k] = record[k];
+            }
+            return out;
+        },
+    };
+}
+/** A no-op event sink that swallows every emit (record-only via `vi.fn`). */
+export function mockEmit() {
+    return { emit: vi.fn() };
+}
+/**
+ * Build a `BlobStoreAdapter` backed by an in-memory Map. The same
+ * user-DID-namespaced behaviour as `BlobStoreService` — cross-user reads
+ * miss, malformed ids are rejected — without touching `cache-manager`.
+ */
+export function mockBlobStore() {
+    const ID_PATTERN = /^blob_[0-9a-f]{16}$/;
+    const store = new Map();
+    let counter = 0;
+    return {
+        put: vi.fn(async ({ userDid, name, value }) => {
+            if (!userDid)
+                throw new Error('BlobStore.put: userDid is required');
+            if (typeof value !== 'string' || value.length === 0) {
+                throw new Error('BlobStore.put: value must be a non-empty string');
+            }
+            const id = `blob_${(counter++).toString(16).padStart(16, '0')}`;
+            store.set(`blob:${userDid}:${id}`, { name, value });
+            return id;
+        }),
+        get: vi.fn(async ({ userDid, blobId }) => {
+            if (!userDid)
+                return null;
+            if (typeof blobId !== 'string' || !ID_PATTERN.test(blobId))
+                return null;
+            return store.get(`blob:${userDid}:${blobId}`) ?? null;
+        }),
+        isValidBlobId: (value) => typeof value === 'string' && ID_PATTERN.test(value),
+    };
+}
+/** A permissive UCAN adapter — every check passes; mintInvocation returns a stub cid. */
+export function mockUcan() {
+    return {
+        hasCapability: vi.fn(() => true),
+        requireCapability: vi.fn(),
+        mintInvocation: vi.fn(async () => 'mock-invocation-cid'),
+        resolveServiceDid: vi.fn(async () => 'did:web:example.com'),
+        hasSigningKey: vi.fn(() => true),
+        createInvocationFromDelegation: vi.fn(async () => ({
+            invocation: 'mock-invocation-car',
+        })),
+    };
+}
+/** A no-op logger suitable for tests. */
+export function mockLogger() {
+    return {
+        log: vi.fn(),
+        error: vi.fn(),
+        warn: vi.fn(),
+    };
+}

package/dist/testing/nest-doubles.d.ts

@@ -0,0 +1,10 @@
+import type { ConfigService } from '@nestjs/config';
+/**
+ * Typed `ConfigService` double for NestJS module tests. `get` returns the
+ * value or undefined; `getOrThrow` throws when the key is absent. The
+ * `as unknown as ConfigService` lives at the boundary because the real
+ * service exposes additional internal methods (`changes`, `internalConfig`,
+ * etc.) that no SUT in this repo consumes.
+ */
+export declare function makeConfig(values?: Record<string, unknown>): ConfigService;
+//# sourceMappingURL=nest-doubles.d.ts.map

package/dist/testing/nest-doubles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nest-doubles.d.ts","sourceRoot":"","sources":["../../src/testing/nest-doubles.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAGpD;;;;;;GAMG;AACH,wBAAgB,UAAU,CACxB,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACnC,aAAa,CAUf"}

package/dist/testing/nest-doubles.js

@@ -0,0 +1,19 @@
+import { vi } from 'vitest';
+/**
+ * Typed `ConfigService` double for NestJS module tests. `get` returns the
+ * value or undefined; `getOrThrow` throws when the key is absent. The
+ * `as unknown as ConfigService` lives at the boundary because the real
+ * service exposes additional internal methods (`changes`, `internalConfig`,
+ * etc.) that no SUT in this repo consumes.
+ */
+export function makeConfig(values = {}) {
+    return {
+        get: vi.fn((key) => values[key]),
+        getOrThrow: vi.fn((key) => {
+            if (!(key in values)) {
+                throw new Error(`Config "${key}" missing`);
+            }
+            return values[key];
+        }),
+    };
+}

package/dist/utils/emoji.d.ts

@@ -0,0 +1,3 @@
+export declare function emojify(input: unknown): string;
+export declare function unemojify(input: unknown): string;
+//# sourceMappingURL=emoji.d.ts.map

package/dist/utils/emoji.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emoji.d.ts","sourceRoot":"","sources":["../../src/utils/emoji.ts"],"names":[],"mappings":"AAcA,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAmB9C;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAYhD"}

package/dist/utils/emoji.js

@@ -0,0 +1,36 @@
+import { Logger } from '@nestjs/common';
+import { emojify as nodeEmojify, unemojify as nodeUnemojify } from 'node-emoji';
+const logger = new Logger('Emoji');
+function toStringSafe(input) {
+    if (typeof input === 'string')
+        return input;
+    try {
+        return JSON.stringify(input);
+    }
+    catch {
+        return String(input);
+    }
+}
+export function emojify(input) {
+    if (typeof input !== 'string') {
+        logger.debug('emojify received non-string input; returning input as-is.', input);
+    }
+    try {
+        return nodeEmojify(String(input));
+    }
+    catch (err) {
+        const str = toStringSafe(input);
+        logger.debug(`emojify failed (${err instanceof Error ? err.message : String(err)}); returning input as-is. input=${str}`, input, err);
+        return str;
+    }
+}
+export function unemojify(input) {
+    try {
+        return nodeUnemojify(input);
+    }
+    catch (err) {
+        const str = toStringSafe(input);
+        logger.debug(`unemojify failed (${err instanceof Error ? err.message : String(err)}); returning input as-is. input=${str}`, input, err);
+        return str;
+    }
+}