@ixo/oracle-runtime 0.0.1

package/dist/bootstrap/ambient-factory.d.ts

@@ -0,0 +1,32 @@
+import type { INestApplication } from '@nestjs/common';
+import type { Logger as PluginLogger, OracleIdentity } from '../plugin-api/types.js';
+import type { AmbientServices } from '../runtime-context/ambient.js';
+export interface BuildAmbientOptions {
+    /** The booted Nest app — used to resolve DI-managed services. */
+    nestApp: INestApplication;
+    /** The merged + validated environment config. */
+    config: Record<string, unknown>;
+    /** Identity declared by the host in `createOracleApp`. */
+    identity: OracleIdentity;
+    /** Names of plugins that successfully loaded. */
+    availablePlugins: ReadonlySet<string>;
+    /** Boot-time logger; reused across adapters that don't get their own. */
+    logger: PluginLogger;
+}
+/**
+ * Build the `AmbientServices` bag — the bundle of adapters every
+ * `buildRuntimeContext` call needs. Each adapter is a thin wrapper around
+ * an existing Tier-0 service or library singleton:
+ *
+ *   - **UcanAdapter** → `UcanService` (DI-resolved from `nestApp`)
+ *   - **MatrixAdapter** → `MatrixManager.getInstance()` (library singleton)
+ *   - **SecretsAdapter** → `SecretsService.getInstance()` (lifted singleton)
+ *   - **LlmAdapter** → `getProviderChatModel` (provider-aware factory)
+ *   - **EmitAdapter** → `wsEmitter` (cross-module event bus → WS gateway)
+ *
+ * The adapter interfaces (`runtime-context/ambient.ts`) are intentionally
+ * narrow so plugins don't reach for service internals. This factory is the
+ * only place where the wide-shape services get bound to the narrow shape.
+ */
+export declare function buildAmbientServices(opts: BuildAmbientOptions): AmbientServices;
+//# sourceMappingURL=ambient-factory.d.ts.map

package/dist/bootstrap/ambient-factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ambient-factory.d.ts","sourceRoot":"","sources":["../../src/bootstrap/ambient-factory.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAMvD,OAAO,KAAK,EACV,MAAM,IAAI,YAAY,EAEtB,cAAc,EAGf,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EACV,eAAe,EAOhB,MAAM,+BAA+B,CAAC;AAEvC,MAAM,WAAW,mBAAmB;IAClC,iEAAiE;IACjE,OAAO,EAAE,gBAAgB,CAAC;IAC1B,iDAAiD;IACjD,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,0DAA0D;IAC1D,QAAQ,EAAE,cAAc,CAAC;IACzB,iDAAiD;IACjD,gBAAgB,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACtC,yEAAyE;IACzE,MAAM,EAAE,YAAY,CAAC;CACtB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,mBAAmB,GACxB,eAAe,CA6JjB"}

package/dist/bootstrap/ambient-factory.js

@@ -0,0 +1,128 @@
+import { MatrixManager } from '@ixo/matrix';
+import { getProviderChatModel } from '../llm/llm-provider.js';
+import { BlobStoreService } from '../modules/blob-store/blob-store.service.js';
+import { SecretsService } from '../modules/secrets/secrets.service.js';
+import { UcanService } from '../modules/ucan/ucan.service.js';
+import { wsEmitter } from '../modules/ws/emitter.js';
+/**
+ * Build the `AmbientServices` bag — the bundle of adapters every
+ * `buildRuntimeContext` call needs. Each adapter is a thin wrapper around
+ * an existing Tier-0 service or library singleton:
+ *
+ *   - **UcanAdapter** → `UcanService` (DI-resolved from `nestApp`)
+ *   - **MatrixAdapter** → `MatrixManager.getInstance()` (library singleton)
+ *   - **SecretsAdapter** → `SecretsService.getInstance()` (lifted singleton)
+ *   - **LlmAdapter** → `getProviderChatModel` (provider-aware factory)
+ *   - **EmitAdapter** → `wsEmitter` (cross-module event bus → WS gateway)
+ *
+ * The adapter interfaces (`runtime-context/ambient.ts`) are intentionally
+ * narrow so plugins don't reach for service internals. This factory is the
+ * only place where the wide-shape services get bound to the narrow shape.
+ */
+export function buildAmbientServices(opts) {
+    const ucanService = opts.nestApp.get(UcanService);
+    const blobStoreService = opts.nestApp.get(BlobStoreService);
+    const secretsService = SecretsService.getInstance();
+    const ucanAdapter = {
+        hasCapability(delegation, resource, action) {
+            return Boolean(delegation?.capabilities?.some((cap) => cap.resource === resource && cap.action === action));
+        },
+        requireCapability(delegation, resource, action) {
+            const ok = Boolean(delegation?.capabilities?.some((cap) => cap.resource === resource && cap.action === action));
+            if (!ok) {
+                throw new Error(`UCAN capability missing: '${action}' on '${resource}'.`);
+            }
+        },
+        async mintInvocation(userDid, target, opts) {
+            const result = await ucanService.mintInvocationForServiceDid(userDid, target.did, target.capability, opts);
+            if (!result) {
+                throw new Error(`UCAN invocation mint returned null for user='${userDid}' service='${target.did}' capability='${target.capability}'. ` +
+                    `Likely cause: no signing key loaded, no cached delegation, or service DID unreachable.`);
+            }
+            return result;
+        },
+        async resolveServiceDid(serviceUrl) {
+            return ucanService.resolveServiceDid(serviceUrl);
+        },
+        hasSigningKey() {
+            return ucanService.hasSigningKey();
+        },
+        createInvocationFromDelegation(delegationCar, serviceUrl, capability, opts) {
+            return ucanService.createInvocationFromDelegation(delegationCar, serviceUrl, capability, opts);
+        },
+    };
+    const matrixAdapter = {
+        async postToRoom(roomId, content) {
+            // Treat caller-supplied content as a Matrix event body. Plugins decide
+            // the event shape (most send `{ msgtype: 'm.text', body: '...' }`).
+            return MatrixManager.getInstance().sendMatrixEvent(roomId, 'm.room.message', content);
+        },
+        async getRoomState(roomId) {
+            const client = MatrixManager.getInstance().getClient();
+            if (!client) {
+                throw new Error('MatrixAdapter.getRoomState: Matrix client not initialized.');
+            }
+            const state = await client.mxClient.getRoomState(roomId);
+            return { roomId, state };
+        },
+        async getEventById(roomId, eventId) {
+            const evt = await MatrixManager.getInstance().getEventById(roomId, eventId);
+            const raw = evt;
+            return {
+                eventId: raw.event_id ?? eventId,
+                type: raw.type ?? 'unknown',
+                content: raw.content ?? null,
+                senderId: raw.sender,
+                originServerTs: raw.origin_server_ts,
+            };
+        },
+    };
+    const llmAdapter = {
+        get(role, params) {
+            return getProviderChatModel(role, params);
+        },
+    };
+    const blobStoreAdapter = {
+        put: (params) => blobStoreService.put(params),
+        get: (params) => blobStoreService.get(params),
+        isValidBlobId: (value) => blobStoreService.isValidBlobId(value),
+    };
+    const secretsAdapter = {
+        async getIndex(roomId) {
+            const entries = await secretsService.getSecretIndex(roomId);
+            const index = {};
+            for (const entry of entries) {
+                index[entry.name] = { key: entry.name };
+            }
+            return index;
+        },
+        async getValues(roomId, keys) {
+            const requested = new Set(keys);
+            const index = await secretsService.getSecretIndex(roomId);
+            const filtered = index.filter((entry) => requested.has(entry.name));
+            return secretsService.loadSecretValues(roomId, filtered);
+        },
+    };
+    const emitAdapter = {
+        emit(eventName, payload) {
+            // The scoped emitter has already attached session/request ids to the
+            // payload. The cross-module `wsEmitter` expects `(sessionId, event)`
+            // where the event carries its own `type` discriminator.
+            const sessionId = typeof payload?.sessionId === 'string' ? payload.sessionId : 'unknown';
+            const event = { type: eventName, ...payload };
+            wsEmitter.emit(sessionId, event);
+        },
+    };
+    return {
+        config: opts.config,
+        identity: opts.identity,
+        availablePlugins: opts.availablePlugins,
+        secrets: secretsAdapter,
+        blobStore: blobStoreAdapter,
+        matrix: matrixAdapter,
+        llm: llmAdapter,
+        emit: emitAdapter,
+        ucan: ucanAdapter,
+        logger: opts.logger,
+    };
+}

package/dist/bootstrap/create-oracle-app.d.ts

@@ -0,0 +1,112 @@
+import { type DynamicModule, type INestApplication, type Type } from '@nestjs/common';
+import type { MainAgentHooks } from '../graph/main-agent-types.js';
+import type { OraclePlugin } from '../plugin-api/oracle-plugin.js';
+import type { AuthExcludedRoute, OracleConfig, Logger as PluginLogger } from '../plugin-api/types.js';
+import { BUNDLED_PLUGINS } from '../plugins/index.js';
+import type { AmbientServices } from '../runtime-context/ambient.js';
+import { type FeatureToggle } from './plugin-loader.js';
+/**
+ * Names of bundled plugins shipped by `@ixo/oracle-runtime`. Derived from
+ * `BUNDLED_PLUGINS` so forks get suggestion-grade typing on `features`
+ * without having to keep a parallel list in sync.
+ */
+export type BundledFeatureName = (typeof BUNDLED_PLUGINS)[number]['name'];
+export interface CreateOracleAppOptions {
+    /**
+     * Inline oracle config. `entityDid` is sourced from `ORACLE_ENTITY_DID` env
+     * — do not put it here. The runtime merges this with env-derived fields to
+     * build the internal `OracleIdentity`.
+     */
+    config: OracleConfig;
+    features?: Partial<Record<BundledFeatureName | (string & {}), FeatureToggle>>;
+    plugins?: OraclePlugin[];
+    /** Developer's own NestJS modules. Spread into `RuntimeAppModule.imports`. */
+    nestModules?: Array<Type | DynamicModule>;
+    /**
+     * Host-declared routes that must NOT pass through `AuthHeaderMiddleware`.
+     * Use for routes contributed by `nestModules` (e.g. webhooks, OAuth
+     * callbacks, public probes). Symmetric with the plugin-side
+     * `OraclePlugin.getAuthExcludedRoutes()` hook — both lists merge onto
+     * the runtime's built-in exclusions (`/health`, `/docs`, etc.).
+     */
+    authExcludedRoutes?: AuthExcludedRoute[];
+    /**
+     * Optional override of the bundled plugin set. Provided primarily for tests
+     * so the harness can spin up `createOracleApp` without dragging in the full
+     * bundled catalog. Production callers should leave this unset.
+     */
+    bundledPlugins?: OraclePlugin[];
+    /** Override `process.env`. Tests use this to inject a clean env. */
+    env?: NodeJS.ProcessEnv;
+    /**
+     * Skip starting the Matrix background init. Tests set this so the factory
+     * resolves without touching real Matrix.
+     */
+    skipMatrixInit?: boolean;
+    /**
+     * Skip registering the SIGTERM/SIGINT shutdown handler. Tests set this
+     * so the harness does not leak process-level listeners.
+     */
+    skipGracefulShutdown?: boolean;
+    /** Override the bootstrap logger. Falls back to NestJS `Logger`. */
+    logger?: PluginLogger;
+    /**
+     * Optional overrides for the agent-build hooks (checkpointer, model
+     * resolver, prompt section snippets). Merged on top of the runtime's
+     * defaults — host hooks WIN. The runtime supplies a per-user SQLite
+     * checkpointer by default; pass `{ checkpointerForUser: ... }` here to
+     * swap it for an alternate implementation.
+     */
+    hooks?: MainAgentHooks;
+}
+export interface PluginStatusReport {
+    loaded: string[];
+    excluded: Array<{
+        plugin: string;
+        reason: string;
+    }>;
+    softDepGaps: Array<{
+        plugin: string;
+        missing: string;
+    }>;
+}
+export interface PluginStatusChangeEvent {
+    plugin: string;
+    from: 'pending' | 'loaded' | 'failed';
+    to: 'pending' | 'loaded' | 'failed';
+    reason?: string;
+}
+export interface OracleApp {
+    /** The underlying `INestApplication`. Use for direct customization. */
+    getNestApp(): INestApplication;
+    /**
+     * The production `AmbientServices` bag — used by `MessagesController` to
+     * build per-request `RuntimeContext`s before invoking `createMainAgent`.
+     * Forks normally don't touch this directly.
+     */
+    ambient: AmbientServices;
+    /** Snapshot of loader/exclusion/soft-dep state. */
+    plugins: {
+        status(): PluginStatusReport;
+    };
+    /** Pre-listen hook (before HTTP starts accepting). */
+    beforeListen(fn: (nestApp: INestApplication) => Promise<void> | void): void;
+    /** Boot-time error subscriber (Matrix init + lifecycle errors). */
+    onError(handler: (err: Error, source: string) => void): void;
+    /** Subscribe to plugin lifecycle changes (e.g. Matrix coming online). */
+    onPluginStatusChange(handler: (event: PluginStatusChangeEvent) => void): void;
+    /** Start the HTTP server. Honours `beforeListen` callbacks first. */
+    listen(port?: number): Promise<void>;
+}
+/**
+ * Resolve plugins, validate env, populate registries, build the dynamic
+ * `RuntimeAppModule`, bootstrap NestJS (without listening) and return an
+ * `OracleApp` whose `listen()` runs `beforeListen` callbacks then starts
+ * the HTTP server.
+ *
+ * Matrix initialization runs in the background — the returned promise
+ * resolves as soon as Nest is built. Status flips via
+ * `onPluginStatusChange`.
+ */
+export declare function createOracleApp(opts: CreateOracleAppOptions): Promise<OracleApp>;
+//# sourceMappingURL=create-oracle-app.d.ts.map

package/dist/bootstrap/create-oracle-app.d.ts.map

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