@ixo/oracle-runtime 0.0.1

package/dist/testing/integration/harness.js

@@ -0,0 +1,461 @@
+/**
+ * Integration test harness — real ambient services + real Nest boot.
+ *
+ *  - `createIntegrationOracle()` boots the full Nest app on an ephemeral
+ *    port. Tier B tests drive it via `ChatClient`. This is the sibling of
+ *    `createOracleApp()` — same boot path, same Matrix init, same graceful
+ *    shutdown. The only differences are: ephemeral port (`port: 0`) and
+ *    captured lifecycle events. There are intentionally no
+ *    `skipMatrixInit` / `skipGracefulShutdown` flags — integration tests
+ *    boot the same stack production does. If Matrix is unreachable, the
+ *    test fails; that failure IS the signal (spec §6, §11 #10).
+ *
+ *  - `createIntegrationRuntime()` builds a real `RuntimeContext` against
+ *    real ambient services and lets a test invoke a plugin's tool / sub-
+ *    agent / middleware directly — no Nest, no HTTP, no model. This is
+ *    the sibling of `createTestRuntime()`, with `mockLlm`/`mockMatrix`
+ *    swapped for the production adapters.
+ *
+ * Both surfaces deliberately reuse `resolvePlugins` / registry population
+ * from the unit-test runtime so they validate the same wiring code that
+ * production goes through.
+ */
+import { HumanMessage } from '@langchain/core/messages';
+import { createOracleApp, } from '../../bootstrap/create-oracle-app.js';
+import { resolvePlugins, } from '../../bootstrap/plugin-loader.js';
+import { getProviderChatModel } from '../../llm/llm-provider.js';
+import { buildMetaTools } from '../../meta-tools/index.js';
+import { ConfigSchemaRegistry, ManifestRegistry, MiddlewareRegistry, SharedStateRegistry, SubAgentRegistry, ToolRegistry, } from '../../registries/index.js';
+import { mockBlobStore } from '../mocks.js';
+import { buildPluginContext } from '../../runtime-context/build-plugin.js';
+import { buildRuntimeContext, } from '../../runtime-context/build-runtime.js';
+/**
+ * Default test model overrides (spec §7 PR-tier).
+ *
+ *   - `main`     → `moonshotai/kimi-k2.5` (production *subagent* model — proven
+ *                  to call tools in this codebase; cheaper than the production
+ *                  `main` model `kimi-k2.6`)
+ *   - `subagent` → `openai/gpt-oss-120b` (cheaper sub-agent for tests)
+ *
+ * Roles not in this map fall through to `getProviderChatModel(role)` — the
+ * production resolver — so `routing`, `guard`, `session-title`, `vision`,
+ * `skills`, etc. all behave exactly like production.
+ */
+const TEST_MODEL_OVERRIDES = {
+    main: 'moonshotai/kimi-k2.6',
+    subagent: 'openai/gpt-oss-120b',
+};
+/**
+ * Build the default `resolveModel` hook installed by `createIntegrationOracle`.
+ *
+ * Honors the test model overrides above for the roles the spec calls out;
+ * everything else falls through to `getProviderChatModel(role, params)`
+ * unchanged.
+ */
+function buildTestResolveModel() {
+    return (role, params) => {
+        const override = TEST_MODEL_OVERRIDES[role];
+        if (override === undefined) {
+            return getProviderChatModel(role, params);
+        }
+        return getProviderChatModel(role, { ...(params ?? {}), model: override });
+    };
+}
+/** Minimum config baseline that satisfies `createOracleApp`'s validator. */
+const IDENTITY_DEFAULTS = {
+    name: 'IXO Active Agent',
+    org: 'IXO',
+    description: 'A proactive, agentic personal assistant who autonomously engages, anticipates needs, and takes initiative to help users accomplish goals with minimal explicit direction.',
+    prompt: {
+        opening: "You are IXO, a proactive, agentic personal assistant. Your mission is to anticipate the user's needs, take initiative to suggest helpful actions or insights, and continuously engage to drive progress even when the user is passive. Don't wait for direct instructions—foresee tasks, flag important developments, and collaborate actively as an empowered agent.",
+        capabilities: '- Autonomously identify relevant tasks, reminders, or information the user may need\n- Propose helpful actions or follow-ups without waiting for user prompts\n- Summarize ongoing context and progress\n- Take initiative to drive productivity and keep the user informed',
+        communicationStyle: "Friendly, proactive, and collaborative. Confidently suggest next steps and actively check in with the user. Use plain language, but don't hesitate to lead conversations or propose actions.",
+    },
+};
+/**
+ * Boot the runtime on an ephemeral port with real ambient services. Wraps
+ * `createOracleApp` identically to production — Matrix init still runs in
+ * the background, graceful shutdown still registers. The only test-time
+ * concessions are the ephemeral `port: 0` default and the captured
+ * lifecycle-event buffers exposed on `result.events`.
+ */
+export async function createIntegrationOracle(opts = {}) {
+    const events = {
+        statusChanges: [],
+        errors: [],
+    };
+    const logger = opts.logger ?? {
+        log: () => undefined,
+        warn: () => undefined,
+        error: () => undefined,
+        debug: () => undefined,
+    };
+    // Default `resolveModel` swaps the production main/subagent models for the
+    // PR-tier test pair (spec §7). Caller-supplied hooks merge on top — any
+    // key the caller sets wins. `resolveModel` itself is overridable for tests
+    // that need a deterministic fake (e.g. trajectory recording).
+    const mergedHooks = {
+        resolveModel: buildTestResolveModel(),
+        ...opts.hooks,
+    };
+    const app = await createOracleApp({
+        config: opts.config ?? IDENTITY_DEFAULTS,
+        plugins: opts.plugins ?? [],
+        bundledPlugins: opts.bundledPlugins,
+        features: opts.features,
+        nestModules: opts.nestModules,
+        authExcludedRoutes: opts.authExcludedRoutes,
+        env: opts.env,
+        logger,
+        hooks: mergedHooks,
+    });
+    app.onPluginStatusChange((event) => {
+        events.statusChanges.push(event);
+    });
+    app.onError((err, source) => {
+        events.errors.push({ err, source });
+    });
+    const portOpt = opts.port ?? 0;
+    await app.listen(portOpt);
+    // Resolve the actual bound port. NestJS wraps express; `getHttpServer()`
+    // returns the underlying HTTP server, whose `address()` exposes the port
+    // when bound. Falls back to `portOpt` for environments where the
+    // introspection isn't available (lightweight test runtimes that stub
+    // `NestFactory.create`).
+    const baseUrl = resolveBaseUrl(app, portOpt);
+    let closed = false;
+    const close = async () => {
+        if (closed)
+            return;
+        closed = true;
+        const nestApp = app.getNestApp();
+        if (typeof nestApp.close === 'function') {
+            await nestApp.close();
+        }
+    };
+    return {
+        baseUrl,
+        app,
+        events,
+        status: () => app.plugins.status(),
+        close,
+    };
+}
+/** Resolve the bound `http://host:port` for a started `OracleApp`. */
+function resolveBaseUrl(app, fallbackPort) {
+    const nestApp = app.getNestApp();
+    const getServer = nestApp.getHttpServer;
+    if (typeof getServer === 'function') {
+        const server = getServer.call(nestApp);
+        if (server && typeof server.address === 'function') {
+            const addr = server.address();
+            if (addr && typeof addr === 'object' && typeof addr.port === 'number') {
+                return `http://127.0.0.1:${addr.port}`;
+            }
+        }
+    }
+    return `http://127.0.0.1:${fallbackPort}`;
+}
+/**
+ * Build a Tier A runtime backed by real ambient services. The harness:
+ *
+ *  1. Resolves the plugin list via the production loader (same `autoDetect`
+ *     gates a real boot would run).
+ *  2. Populates the six registries.
+ *  3. Wires real adapters for `llm`, `secrets`, `matrix`, `ucan`, `emit`
+ *     (in-memory no-ops for Matrix and secrets — the harness doesn't need
+ *     a live homeserver to call a plugin tool that doesn't depend on one).
+ *  4. Builds a fresh `RuntimeContext` per invocation using the test
+ *     user/session/delegation.
+ *
+ * Use this when you want to call a tool *directly* against the real upstream
+ * (Memory Engine, Sandbox, Skills, Composio, Firecrawl, …) without a model.
+ */
+export async function createIntegrationRuntime(opts) {
+    const logger = opts.logger ?? {
+        log: () => undefined,
+        warn: () => undefined,
+        error: () => undefined,
+        debug: () => undefined,
+    };
+    const config = opts.config ?? process.env;
+    // Stringify the config for plugin-loader autoDetect probes — `process.env`
+    // values are strings, so the test config must look the same to keep the
+    // boot path consistent.
+    const envForLoader = {};
+    for (const [k, v] of Object.entries(config)) {
+        if (v === undefined || v === null)
+            continue;
+        envForLoader[k] = typeof v === 'string' ? v : String(v);
+    }
+    const resolved = resolvePlugins({
+        bundled: opts.plugins,
+        features: opts.features,
+        env: envForLoader,
+        logger,
+    });
+    const loadedPluginNames = new Set(resolved.loaded.map((p) => p.name));
+    const tools = new ToolRegistry();
+    const subAgents = new SubAgentRegistry();
+    const middlewares = new MiddlewareRegistry();
+    const manifests = new ManifestRegistry();
+    const configSchemas = new ConfigSchemaRegistry();
+    const sharedState = new SharedStateRegistry();
+    for (const plugin of resolved.loaded) {
+        tools.register(plugin);
+        subAgents.register(plugin);
+        middlewares.register(plugin);
+        manifests.register(plugin);
+        configSchemas.register(plugin);
+        sharedState.register(plugin);
+    }
+    const identity = {
+        name: 'IntegrationTestOracle',
+        org: 'IXO',
+        description: 'createIntegrationRuntime',
+        entityDid: typeof config.ORACLE_ENTITY_DID === 'string'
+            ? config.ORACLE_ENTITY_DID
+            : 'did:ixo:test',
+        ...opts.identity,
+    };
+    // Real LLM adapter — production-grade provider.
+    const llmAdapter = {
+        get(role, params) {
+            return getProviderChatModel(role, params);
+        },
+    };
+    // Matrix / secrets stay in-memory by default. Tests that need a live
+    // Matrix surface should boot via `createIntegrationOracle()` instead —
+    // a Tier A test that depends on Matrix is mis-tiered.
+    const matrixAdapter = {
+        async postToRoom() {
+            return 'integration-noop-event-id';
+        },
+        async getRoomState(roomId) {
+            return { roomId, state: [] };
+        },
+        async getEventById(_roomId, eventId) {
+            return { eventId, type: 'm.room.message', content: {} };
+        },
+    };
+    const secretsAdapter = {
+        async getIndex() {
+            return {};
+        },
+        async getValues() {
+            return {};
+        },
+    };
+    // UCAN adapter — honors the parsed capability list, matching production.
+    // Callers can swap in a real adapter via `opts.ucan` when the plugin under
+    // test needs to mint downstream invocations (memory / sandbox / skills /
+    // composio). Typical pattern: boot an oracle via `createIntegrationOracle`
+    // and pass `bootedOracle.app.ambient.ucan` here.
+    const ucanCapabilities = opts.capabilities ?? [];
+    const ucanAdapter = opts.ucan ?? {
+        hasCapability(delegation, resource, action) {
+            const caps = delegation?.capabilities ?? ucanCapabilities;
+            return Boolean(caps.some((cap) => cap.resource === resource && cap.action === action));
+        },
+        requireCapability(delegation, resource, action) {
+            const caps = delegation?.capabilities ?? ucanCapabilities;
+            const ok = caps.some((cap) => cap.resource === resource && cap.action === action);
+            if (!ok) {
+                throw new Error(`UCAN capability missing: '${action}' on '${resource}'.`);
+            }
+        },
+        async mintInvocation() {
+            throw new Error('createIntegrationRuntime: mintInvocation is not wired. Pass ' +
+                '`ucan: bootedOracle.app.ambient.ucan` from a `createIntegrationOracle()` ' +
+                'boot if your test needs downstream service invocations.');
+        },
+        async resolveServiceDid() {
+            return null;
+        },
+        hasSigningKey() {
+            return false;
+        },
+        async createInvocationFromDelegation() {
+            throw new Error('createIntegrationRuntime: createInvocationFromDelegation is not wired. Pass ' +
+                '`ucan: bootedOracle.app.ambient.ucan` from a `createIntegrationOracle()` ' +
+                'boot if your test needs CAR-driven invocation minting.');
+        },
+    };
+    const emitAdapter = {
+        emit() {
+            // Silent — tests that need to assert on events should use
+            // createIntegrationOracle().events instead.
+        },
+    };
+    const blobStoreAdapter = mockBlobStore();
+    const ambient = {
+        config,
+        identity,
+        availablePlugins: loadedPluginNames,
+        secrets: secretsAdapter,
+        blobStore: blobStoreAdapter,
+        matrix: matrixAdapter,
+        llm: llmAdapter,
+        emit: emitAdapter,
+        ucan: ucanAdapter,
+        logger,
+    };
+    const buildCtxFor = (pluginName) => buildPluginContext({
+        config,
+        identity,
+        availablePlugins: loadedPluginNames,
+        logger,
+        pluginName,
+    });
+    const sharedBuildCtx = buildCtxFor('__integration__');
+    const pluginCollectedTools = await tools.collect(sharedBuildCtx);
+    const collectedSubAgents = await subAgents.collect(sharedBuildCtx);
+    const collectedMiddlewares = middlewares.collect(sharedBuildCtx);
+    // Meta-tools (`list_capabilities`, `load_capability`) are registered by
+    // the runtime at agent-build time in production — not by plugins. The
+    // Tier A harness wires them in here so direct `invokeTool` can reach
+    // them; same instance the agent would see at runtime.
+    const metaToolEntries = buildMetaTools({
+        manifestRegistry: manifests,
+        toolRegistry: tools,
+    }).map((tool) => ({ pluginName: '__meta__', tool }));
+    const collectedTools = [...pluginCollectedTools, ...metaToolEntries];
+    const delegation = {
+        raw: opts.delegation ?? '',
+        issuer: opts.user.did,
+        audience: identity.entityDid,
+        capabilities: ucanCapabilities,
+    };
+    const buildRtCtx = () => {
+        const runConfig = {
+            context: {
+                user: {
+                    did: opts.user.did,
+                    matrixUserId: opts.user.matrixUserId ??
+                        `@${opts.user.did.replaceAll(':', '-')}:test-host`,
+                    ucanDelegation: delegation,
+                },
+                session: {
+                    id: opts.session?.id ?? `integration-session-${Date.now()}`,
+                    client: opts.session?.client ?? 'portal',
+                    requestId: opts.session?.requestId ?? `integration-req-${Date.now()}`,
+                    ...(opts.session ?? {}),
+                },
+            },
+        };
+        const stateInput = {
+            messages: [],
+            // Default: pre-load every resolved plugin so Tier A direct-invoke
+            // tests don't need to call `load_capability` before reaching the
+            // plugin's tools. Tests that exercise the on-demand-load flow itself
+            // (`list_capabilities`, `load_capability`) override this with
+            // `state: { loadedPlugins: new Set() }` for an empty-start scenario.
+            loadedPlugins: loadedPluginNames,
+            ...(opts.state ?? {}),
+        };
+        return buildRuntimeContext(runConfig, ambient, stateInput);
+    };
+    // If the caller asked for a custom fetch, install it for the duration of
+    // the runtime. We restore on close() so parallel tests don't poison each
+    // other's globalThis.fetch.
+    const originalFetch = globalThis.fetch;
+    if (opts.fetch) {
+        globalThis.fetch = opts.fetch;
+    }
+    return {
+        async invokeTool(name, args) {
+            const rtCtx = buildRtCtx();
+            // First check boot tools (collected once at harness construction).
+            let entry = collectedTools.find((t) => t.tool.name === name);
+            if (!entry) {
+                // Fall through to per-request tools — `getRequestTools(rtCtx)` reads
+                // the live runtime context (timezone, ucan delegation, etc.) so it
+                // must be collected per-invocation rather than at harness build time.
+                const requestTools = await tools.collectRequest(rtCtx);
+                entry = requestTools.find((t) => t.tool.name === name);
+            }
+            if (!entry) {
+                const available = [
+                    ...collectedTools.map((t) => t.tool.name),
+                    ...(await tools.collectRequest(rtCtx)).map((t) => t.tool.name),
+                ].join(', ');
+                throw new Error(`Tool "${name}" not found. Registered tools: ${available || '(none)'}.`);
+            }
+            return entry.tool.handler(args, rtCtx);
+        },
+        async invokeMiddleware(nameOrIndex, state, runtimeArg) {
+            const middleware = findMiddleware(collectedMiddlewares, nameOrIndex);
+            const runtimeCtx = runtimeArg ?? { context: {} };
+            const out = {};
+            // LangChain v1.x middleware hooks have rich generic types; at the
+            // harness boundary they all collapse to `(state, runtime) => result`.
+            // The same shape `create-test-runtime.ts` uses.
+            const hookBag = middleware;
+            const before1 = await runHook(hookBag.beforeAgent, state, runtimeCtx);
+            if (before1 !== undefined)
+                out.before = before1;
+            const before2 = await runHook(hookBag.beforeModel, state, runtimeCtx);
+            if (before2 !== undefined)
+                out.before = before2;
+            const after1 = await runHook(hookBag.afterModel, state, runtimeCtx);
+            if (after1 !== undefined)
+                out.after = after1;
+            const after2 = await runHook(hookBag.afterAgent, state, runtimeCtx);
+            if (after2 !== undefined)
+                out.after = after2;
+            return out;
+        },
+        async invokeSubAgent(name, task) {
+            const entry = collectedSubAgents.find((s) => s.subAgent.name === name);
+            if (!entry) {
+                throw new Error(`Sub-agent "${name}" not found. Registered: ${collectedSubAgents.map((s) => s.subAgent.name).join(', ') ||
+                    '(none)'}.`);
+            }
+            const sub = entry.subAgent;
+            const buildCtx = buildCtxFor(entry.pluginName);
+            const subTools = typeof sub.tools === 'function' ? sub.tools(buildCtx) : sub.tools;
+            const systemPrompt = typeof sub.systemPrompt === 'function'
+                ? sub.systemPrompt(buildCtx)
+                : sub.systemPrompt;
+            const model = ambient.llm.get(sub.model ?? 'subagent');
+            const reply = await model.invoke([new HumanMessage(task)]);
+            const replyText = typeof reply.content === 'string'
+                ? reply.content
+                : JSON.stringify(reply.content);
+            return JSON.stringify({
+                subAgent: sub.name,
+                plugin: entry.pluginName,
+                task,
+                systemPromptPreview: systemPrompt.slice(0, 80),
+                toolNames: subTools.map((t) => t.name),
+                reply: replyText,
+            });
+        },
+        ambient,
+        async close() {
+            if (opts.fetch) {
+                globalThis.fetch = originalFetch;
+            }
+        },
+    };
+}
+async function runHook(entry, state, runtime) {
+    if (!entry)
+        return undefined;
+    const fn = typeof entry === 'function' ? entry : entry.hook;
+    return fn(state, runtime);
+}
+function findMiddleware(collected, nameOrIndex) {
+    if (typeof nameOrIndex === 'number') {
+        const found = collected[nameOrIndex];
+        if (!found) {
+            throw new Error(`Middleware index ${nameOrIndex} out of range (0..${collected.length - 1}).`);
+        }
+        return found.middleware;
+    }
+    const direct = collected.find((m) => m.middleware.name === nameOrIndex);
+    if (direct)
+        return direct.middleware;
+    const names = collected.map((m) => m.middleware.name).join(', ');
+    throw new Error(`Middleware "${nameOrIndex}" not found. Registered: ${names || '(none)'}.`);
+}

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

@@ -0,0 +1,14 @@
+/**
+ * Public surface for `@ixo/oracle-runtime/testing/integration`.
+ *
+ * Five exports total — anything else would be over-abstraction (see spec §6).
+ * Tests skip via `test.skipIf(!process.env.X)`, sequence steps via plain
+ * `await`s, and lean on the matchers `expect.extend(langchainMatchers)` adds
+ * inside `setup.ts`. No DSLs.
+ */
+export { createIntegrationOracle, createIntegrationRuntime, type CreateIntegrationOracleOptions, type CreateIntegrationRuntimeOptions, type IntegrationOracle, type IntegrationRuntime, type IntegrationCapability, } from './harness.js';
+export { ChatClient, type ChatClientOptions, type SendOptions, type SendResult, type StreamOptions, type StreamFinal, } from './chat-client.js';
+export { mintUserDelegation, memoryCap, sandboxCap, skillsCap, subscriptionsReadCap, allCaps, type MintUserDelegationOptions, } from './ucan.js';
+export { waitForMatrixLoaded } from './wait-for-matrix-loaded.js';
+export { parseSSEStream, type SSEEvent, type SSEMessageEventData, type SSEToolCallEventData, type SSEActionCallEventData, type SSEErrorEventData, type SSEDoneEventData, type SSERouterUpdateEventData, type SSERenderComponentEventData, type SSEBrowserToolCallEventData, type SSEMessageCacheInvalidationEventData, type SSEReasoningEventData, } from './sse-parser.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/testing/integration/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EACL,uBAAuB,EACvB,wBAAwB,EACxB,KAAK,8BAA8B,EACnC,KAAK,+BAA+B,EACpC,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,GAC3B,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,UAAU,EACV,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,KAAK,WAAW,GACjB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,kBAAkB,EAClB,SAAS,EACT,UAAU,EACV,SAAS,EACT,oBAAoB,EACpB,OAAO,EACP,KAAK,yBAAyB,GAC/B,MAAM,WAAW,CAAC;AAEnB,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAOlE,OAAO,EACL,cAAc,EACd,KAAK,QAAQ,EACb,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,EAC3B,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,wBAAwB,EAC7B,KAAK,2BAA2B,EAChC,KAAK,2BAA2B,EAChC,KAAK,oCAAoC,EACzC,KAAK,qBAAqB,GAC3B,MAAM,iBAAiB,CAAC"}

package/dist/testing/integration/index.js

@@ -0,0 +1,18 @@
+/**
+ * Public surface for `@ixo/oracle-runtime/testing/integration`.
+ *
+ * Five exports total — anything else would be over-abstraction (see spec §6).
+ * Tests skip via `test.skipIf(!process.env.X)`, sequence steps via plain
+ * `await`s, and lean on the matchers `expect.extend(langchainMatchers)` adds
+ * inside `setup.ts`. No DSLs.
+ */
+export { createIntegrationOracle, createIntegrationRuntime, } from './harness.js';
+export { ChatClient, } from './chat-client.js';
+export { mintUserDelegation, memoryCap, sandboxCap, skillsCap, subscriptionsReadCap, allCaps, } from './ucan.js';
+export { waitForMatrixLoaded } from './wait-for-matrix-loaded.js';
+// Typed SSE events — mirror of `packages/oracles-client-sdk/src/utils/sse-parser.ts`.
+// Tests use these to type-narrow when asserting on streamed events:
+//   for await (const evt of client.stream(sessionId, msg)) {
+//     if (evt.event === 'tool_call') { evt.data.toolName }  // typed
+//   }
+export { parseSSEStream, } from './sse-parser.js';

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

@@ -0,0 +1,2 @@
+import 'reflect-metadata';
+//# sourceMappingURL=setup.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../../src/testing/integration/setup.ts"],"names":[],"mappings":"AAqBA,OAAO,kBAAkB,CAAC"}

package/dist/testing/integration/setup.js

@@ -0,0 +1,41 @@
+/**
+ * Vitest setupFile for integration tests.
+ *
+ * Loads env from the package-local `.env.integration` only. Deliberately
+ * does NOT reach into a sibling package's `.env` — that coupling would
+ * break for any consumer who forks @ixo/oracle-runtime to build their
+ * own oracle without an `apps/qiforge-example/` directory next door.
+ *
+ * Consumers writing tests against @ixo/oracle-runtime/testing/integration
+ * configure their own vitest setupFile in their own package; this file
+ * is the runtime package's own setup.
+ *
+ * Setup is intentionally minimal: dotenv + langchainMatchers. Spec §6
+ * bans `env-loader`, `requires()`, `runScenario`, custom matchers
+ * modules, and failure-diagnostics modules — use vitest as-is.
+ */
+import { langchainMatchers } from '@langchain/core/testing';
+import { Logger } from '@nestjs/common';
+import { config as dotenvConfig } from 'dotenv';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import 'reflect-metadata';
+import { expect } from 'vitest';
+// Resolve package root relative to this setup file. This file lives at
+// `src/testing/integration/setup.ts`; package root is three directories up.
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const packageRoot = resolve(__dirname, '../../..');
+// Single env file owned by the package. Self-contained — no cross-package
+// reads. Missing file is silently tolerated (CI provides env via secrets).
+dotenvConfig({ path: resolve(packageRoot, '.env.integration') });
+// Silence @ixo/logger (winston) info/debug spam in integration runs. The
+// logger is a singleton that reads LOG_LEVEL at construction, so this must
+// land before any test module imports it. Honors a caller-provided value.
+process.env.LOG_LEVEL ??= 'warn';
+// Silence NestJS internal logs (route mappings, module init, etc.) — the
+// harness already passes a no-op `PluginLogger` to `createOracleApp`, but
+// Nest core instantiates its own `Logger` singletons that write to stdout
+// independently. `error` + `warn` stay on so real failures surface.
+Logger.overrideLogger(['error', 'warn']);
+expect.extend(langchainMatchers);

package/dist/testing/integration/sse-parser.d.ts

@@ -0,0 +1,99 @@
+/**
+ * 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.
+ */
+export interface BaseSSEEvent<TEvent extends string, TData> {
+    event: TEvent;
+    data: TData;
+}
+export interface SSEMessageEventData {
+    content: string;
+    timestamp: string;
+}
+export interface SSEToolCallEventData {
+    sessionId: string;
+    requestId: string;
+    toolName: string;
+    args: Record<string, unknown>;
+    status: 'isRunning' | 'done';
+    output?: string;
+    eventId?: string;
+}
+export interface SSEErrorEventData {
+    error: string;
+    timestamp: string;
+}
+export interface SSEDoneEventData {
+    timestamp?: string;
+}
+export interface SSERouterUpdateEventData {
+    step: string;
+    sessionId: string;
+    requestId: string;
+    eventId?: string;
+}
+export interface SSERenderComponentEventData {
+    componentName: string;
+    args?: Record<string, unknown>;
+    status?: 'isRunning' | 'done';
+    sessionId: string;
+    requestId: string;
+    eventId?: string;
+}
+export interface SSEBrowserToolCallEventData {
+    toolName: string;
+    args?: Record<string, unknown>;
+    status?: 'isRunning' | 'done';
+    sessionId: string;
+    requestId: string;
+    eventId?: string;
+}
+export interface SSEActionCallEventData {
+    sessionId: string;
+    requestId: string;
+    toolName: string;
+    args?: Record<string, unknown>;
+    status?: 'isRunning' | 'done' | 'error';
+    output?: string;
+    toolCallId?: string;
+    error?: string;
+}
+export interface SSEMessageCacheInvalidationEventData {
+    status?: 'isRunning' | 'done';
+    sessionId: string;
+    requestId: string;
+    eventId?: string;
+}
+export interface SSEReasoningEventData {
+    sessionId: string;
+    requestId: string;
+    reasoning: string;
+    reasoningDetails?: Array<{
+        type: string;
+        text: string;
+        format: string;
+        index: number;
+    }>;
+    isComplete?: boolean;
+    timestamp?: string;
+    eventId?: string;
+}
+export type SSEEvent = BaseSSEEvent<'message', SSEMessageEventData> | BaseSSEEvent<'tool_call', SSEToolCallEventData> | BaseSSEEvent<'action_call', SSEActionCallEventData> | BaseSSEEvent<'error', SSEErrorEventData> | BaseSSEEvent<'done', SSEDoneEventData> | BaseSSEEvent<'router.update', SSERouterUpdateEventData> | BaseSSEEvent<'render_component', SSERenderComponentEventData> | BaseSSEEvent<'browser_tool_call', SSEBrowserToolCallEventData> | BaseSSEEvent<'message_cache_invalidation', SSEMessageCacheInvalidationEventData> | BaseSSEEvent<'reasoning', SSEReasoningEventData>;
+/**
+ * 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 declare function parseSSEStream(reader: ReadableStreamDefaultReader<Uint8Array>): AsyncGenerator<SSEEvent>;
+//# sourceMappingURL=sse-parser.d.ts.map

package/dist/testing/integration/sse-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse-parser.d.ts","sourceRoot":"","sources":["../../../src/testing/integration/sse-parser.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;GAcG;AAGH,MAAM,WAAW,YAAY,CAAC,MAAM,SAAS,MAAM,EAAE,KAAK;IACxD,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,KAAK,CAAC;CACb;AAGD,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,MAAM,EAAE,WAAW,GAAG,MAAM,CAAC;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,2BAA2B;IAC1C,aAAa,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,MAAM,CAAC,EAAE,WAAW,GAAG,MAAM,CAAC;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,MAAM,CAAC,EAAE,WAAW,GAAG,MAAM,CAAC;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,sBAAsB;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,MAAM,CAAC,EAAE,WAAW,GAAG,MAAM,GAAG,OAAO,CAAC;IACxC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,oCAAoC;IACnD,MAAM,CAAC,EAAE,WAAW,GAAG,MAAM,CAAC;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,CAAC,EAAE,KAAK,CAAC;QACvB,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,EAAE,MAAM,CAAC;KACf,CAAC,CAAC;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAGD,MAAM,MAAM,QAAQ,GAChB,YAAY,CAAC,SAAS,EAAE,mBAAmB,CAAC,GAC5C,YAAY,CAAC,WAAW,EAAE,oBAAoB,CAAC,GAC/C,YAAY,CAAC,aAAa,EAAE,sBAAsB,CAAC,GACnD,YAAY,CAAC,OAAO,EAAE,iBAAiB,CAAC,GACxC,YAAY,CAAC,MAAM,EAAE,gBAAgB,CAAC,GACtC,YAAY,CAAC,eAAe,EAAE,wBAAwB,CAAC,GACvD,YAAY,CAAC,kBAAkB,EAAE,2BAA2B,CAAC,GAC7D,YAAY,CAAC,mBAAmB,EAAE,2BAA2B,CAAC,GAC9D,YAAY,CACV,4BAA4B,EAC5B,oCAAoC,CACrC,GACD,YAAY,CAAC,WAAW,EAAE,qBAAqB,CAAC,CAAC;AAoBrD;;;;GAIG;AACH,wBAAuB,cAAc,CACnC,MAAM,EAAE,2BAA2B,CAAC,UAAU,CAAC,GAC9C,cAAc,CAAC,QAAQ,CAAC,CA6F1B"}