@ixo/oracle-runtime 0.0.1

package/dist/modules/ws/ws.gateway.js

@@ -0,0 +1,241 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var WsGateway_1;
+import { GraphEventEmitter, rootEventEmitter } from '@ixo/oracles-events';
+import { Logger, Optional } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { ApiOperation, ApiResponse } from '@nestjs/swagger';
+import { ConnectedSocket, MessageBody, SubscribeMessage, WebSocketGateway, WebSocketServer, } from '@nestjs/websockets';
+import { Server, Socket } from 'socket.io';
+import { validateUcanDelegation } from '../auth/validate-ucan-delegation.js';
+import { UcanService } from '../ucan/ucan.service.js';
+import { WsService } from './ws.service.js';
+let WsGateway = WsGateway_1 = class WsGateway {
+    wsService;
+    configService;
+    ucanService;
+    server;
+    logger = new Logger(WsGateway_1.name);
+    constructor(wsService, configService, ucanService) {
+        this.wsService = wsService;
+        this.configService = configService;
+        this.ucanService = ucanService;
+    }
+    afterInit() {
+        this.logger.log('WebSocket gateway initialized');
+        GraphEventEmitter.registerEventHandlers(this.server);
+    }
+    async handleConnection(client) {
+        const sessionId = client.handshake.query.sessionId;
+        if (!sessionId || typeof sessionId !== 'string') {
+            this.logger.error(`WebSocket connection attempt without sessionId from ${client.id}`);
+            client.disconnect();
+            return;
+        }
+        // Authenticate the handshake the same way HTTP requests are authenticated:
+        // a valid UCAN delegation is required, and the user identity is the
+        // *validated invoker* — never the `userDid` the client put in the query.
+        // Trusting the query (the previous behaviour) let any client impersonate
+        // another user and poison the per-DID delegation cache.
+        const ucanDelegation = client.handshake.auth?.ucanDelegation;
+        if (!ucanDelegation) {
+            this.logger.warn(`WebSocket connection rejected for session ${sessionId}: missing UCAN delegation (client: ${client.id})`);
+            client.disconnect();
+            return;
+        }
+        const oracleDid = this.configService.get('ORACLE_DID');
+        if (!oracleDid) {
+            this.logger.error('WebSocket auth unavailable: ORACLE_DID not configured — rejecting connection');
+            client.disconnect();
+            return;
+        }
+        const blocksyncUri = this.configService.getOrThrow('BLOCKSYNC_GRAPHQL_URL');
+        const outcome = await validateUcanDelegation(ucanDelegation, {
+            oracleDid,
+            blocksyncUri,
+        });
+        if (!outcome.ok) {
+            this.logger.warn(`WebSocket connection rejected for session ${sessionId}: ${outcome.error} (client: ${client.id})`);
+            client.disconnect();
+            return;
+        }
+        const userDid = outcome.result.userDid;
+        // Stash the validated identity on the socket so disconnect-time history
+        // processing reads the authenticated DID rather than the untrusted query.
+        client.data.userDid = userDid;
+        this.logger.log(`WebSocket connection established for session: ${sessionId}, did: ${userDid}, client: ${client.id}`);
+        // Cache the (now-validated) delegation for downstream invocations, keyed
+        // by the validated invoker DID and bounded by the delegation's lifetime.
+        if (this.ucanService) {
+            await this.ucanService.cacheDelegation(userDid, ucanDelegation, outcome.result.delegation.expiration);
+        }
+        // Join the sessionId room (channel) — this is the key integration!
+        await client.join(sessionId);
+        this.wsService.addClientConnection(sessionId, client);
+        client.emit('connected', {
+            message: 'Connected successfully',
+            sessionId,
+            timestamp: new Date().toISOString(),
+        });
+    }
+    handleDisconnect(client) {
+        const sessionId = client.handshake.query.sessionId;
+        if (sessionId) {
+            this.logger.log(`WebSocket connection closed for session: ${sessionId}, client: ${client.id}`);
+            void this.wsService.removeClientConnection(sessionId, client);
+        }
+        else {
+            this.logger.warn(`WebSocket disconnected without sessionId: ${client.id}`);
+        }
+    }
+    handlePing(client) {
+        client.emit('pong', {
+            timestamp: new Date().toISOString(),
+            sessionId: client.handshake.query.sessionId,
+        });
+    }
+    handleStatus(client) {
+        client.emit('status', {
+            connected: true,
+            sessionId: client.handshake.query.sessionId,
+            activeSessions: this.wsService.getActiveSessionsCount(),
+            totalConnections: this.wsService.getTotalConnectionsCount(),
+            timestamp: new Date().toISOString(),
+        });
+    }
+    /**
+     * Forward a tool/action result back to LangGraph via the root event emitter.
+     */
+    handleFrontendToolResult(client, data, eventType) {
+        const sessionId = client.handshake.query.sessionId;
+        const toolId = data.toolCallId;
+        this.logger.log(`${eventType} received for session: ${sessionId}, toolId: ${toolId}`);
+        rootEventEmitter.emit(eventType, {
+            sessionId,
+            ...data,
+            timestamp: new Date().toISOString(),
+        });
+    }
+    handleToolResult(client, data) {
+        this.handleFrontendToolResult(client, data, 'browser_tool_result');
+    }
+    handleActionCallResult(client, data) {
+        this.handleFrontendToolResult(client, data, 'action_call_result');
+    }
+    handleListEvents(client) {
+        client.emit('available-events', {
+            clientEvents: [
+                'ping',
+                'status',
+                'subscribe',
+                'list-events',
+                'tool_result',
+                'action_call_result',
+            ],
+            serverEvents: [
+                'connected',
+                'pong',
+                'status',
+                'subscribed',
+                'available-events',
+                // LangGraph events
+                'render_component',
+                'tool_call',
+                'action_call',
+                'browser_tool_call',
+                'router_update',
+                'message_cache_invalidation',
+            ],
+            sessionId: client.handshake.query.sessionId,
+            timestamp: new Date().toISOString(),
+        });
+    }
+};
+__decorate([
+    WebSocketServer(),
+    __metadata("design:type", Server)
+], WsGateway.prototype, "server", void 0);
+__decorate([
+    SubscribeMessage('ping'),
+    __param(0, ConnectedSocket()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Socket]),
+    __metadata("design:returntype", void 0)
+], WsGateway.prototype, "handlePing", null);
+__decorate([
+    SubscribeMessage('status'),
+    __param(0, ConnectedSocket()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Socket]),
+    __metadata("design:returntype", void 0)
+], WsGateway.prototype, "handleStatus", null);
+__decorate([
+    SubscribeMessage('tool_result'),
+    ApiOperation({
+        summary: 'Handle Tool Result',
+        description: 'Receive tool execution result from client and forward to LangGraph',
+    }),
+    ApiResponse({
+        status: 200,
+        description: 'Tool result received successfully',
+    }),
+    __param(0, ConnectedSocket()),
+    __param(1, MessageBody()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Socket, Object]),
+    __metadata("design:returntype", void 0)
+], WsGateway.prototype, "handleToolResult", null);
+__decorate([
+    SubscribeMessage('action_call_result'),
+    ApiOperation({
+        summary: 'Handle AG-UI Action Result',
+        description: 'Receive AG-UI action execution result from client and forward to LangGraph',
+    }),
+    ApiResponse({
+        status: 200,
+        description: 'Action result received successfully',
+    }),
+    __param(0, ConnectedSocket()),
+    __param(1, MessageBody()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Socket, Object]),
+    __metadata("design:returntype", void 0)
+], WsGateway.prototype, "handleActionCallResult", null);
+__decorate([
+    SubscribeMessage('list-events'),
+    ApiOperation({
+        summary: 'List Available Events',
+        description: 'Get a list of all available WebSocket events',
+    }),
+    ApiResponse({
+        status: 200,
+        description: 'List of available events',
+    }),
+    __param(0, ConnectedSocket()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Socket]),
+    __metadata("design:returntype", void 0)
+], WsGateway.prototype, "handleListEvents", null);
+WsGateway = WsGateway_1 = __decorate([
+    WebSocketGateway({
+        cors: {
+            origin: '*',
+        },
+        namespace: '/',
+    }),
+    __param(2, Optional()),
+    __metadata("design:paramtypes", [WsService,
+        ConfigService,
+        UcanService])
+], WsGateway);
+export { WsGateway };

package/dist/modules/ws/ws.module.d.ts

@@ -0,0 +1,3 @@
+export declare class WsModule {
+}
+//# sourceMappingURL=ws.module.d.ts.map

package/dist/modules/ws/ws.module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws.module.d.ts","sourceRoot":"","sources":["../../../src/modules/ws/ws.module.ts"],"names":[],"mappings":"AAKA,qBAMa,QAAQ;CAAG"}

package/dist/modules/ws/ws.module.js

@@ -0,0 +1,21 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { Global, Module } from '@nestjs/common';
+import { SessionsModule } from '../sessions/sessions.module.js';
+import { WsGateway } from './ws.gateway.js';
+import { WsService } from './ws.service.js';
+let WsModule = class WsModule {
+};
+WsModule = __decorate([
+    Global(),
+    Module({
+        imports: [SessionsModule],
+        providers: [WsService, WsGateway],
+        exports: [WsService],
+    })
+], WsModule);
+export { WsModule };

package/dist/modules/ws/ws.service.d.ts

@@ -0,0 +1,25 @@
+import { type AllEvents } from '@ixo/oracles-events';
+import { type OnModuleDestroy, type OnModuleInit } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { type Socket } from 'socket.io';
+import { SessionHistoryProcessor } from '../sessions/session-history-processor.service.js';
+export declare class WsService implements OnModuleInit, OnModuleDestroy {
+    private readonly sessionHistoryProcessor;
+    private readonly configService;
+    private readonly logger;
+    private readonly sessionConnections;
+    constructor(sessionHistoryProcessor: SessionHistoryProcessor, configService: ConfigService);
+    /** Add a WebSocket connection for a specific session. */
+    addClientConnection(sessionId: string, socket: Socket): void;
+    /** Publish an event to all connections in a specific session. */
+    publishToSession(sessionId: string, event: AllEvents): void;
+    /** Remove a client connection on disconnect. */
+    removeClientConnection(sessionId: string, socket: Socket): Promise<void>;
+    /** Active sessions count for monitoring. */
+    getActiveSessionsCount(): number;
+    /** Total connections count for monitoring. */
+    getTotalConnectionsCount(): number;
+    onModuleInit(): void;
+    onModuleDestroy(): void;
+}
+//# sourceMappingURL=ws.service.d.ts.map

package/dist/modules/ws/ws.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws.service.d.ts","sourceRoot":"","sources":["../../../src/modules/ws/ws.service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,YAAY,EAClB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,uBAAuB,EAAE,MAAM,kDAAkD,CAAC;AAG3F,qBACa,SAAU,YAAW,YAAY,EAAE,eAAe;IAK3D,OAAO,CAAC,QAAQ,CAAC,uBAAuB;IACxC,OAAO,CAAC,QAAQ,CAAC,aAAa;IALhC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA8B;IACrD,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAkC;gBAGlD,uBAAuB,EAAE,uBAAuB,EAChD,aAAa,EAAE,aAAa;IAG/C,yDAAyD;IACzD,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAa5D,iEAAiE;IACjE,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,IAAI;IAoB3D,gDAAgD;IAC1C,sBAAsB,CAC1B,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC;IAyChB,4CAA4C;IAC5C,sBAAsB,IAAI,MAAM;IAIhC,8CAA8C;IAC9C,wBAAwB,IAAI,MAAM;IAQlC,YAAY,IAAI,IAAI;IAOpB,eAAe,IAAI,IAAI;CASxB"}

package/dist/modules/ws/ws.service.js

@@ -0,0 +1,113 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var WsService_1;
+import { Injectable, Logger, } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { SessionHistoryProcessor } from '../sessions/session-history-processor.service.js';
+import { WS_SERVICE_EVENT_NAME, wsEmitter } from './emitter.js';
+let WsService = WsService_1 = class WsService {
+    sessionHistoryProcessor;
+    configService;
+    logger = new Logger(WsService_1.name);
+    sessionConnections = new Map();
+    constructor(sessionHistoryProcessor, configService) {
+        this.sessionHistoryProcessor = sessionHistoryProcessor;
+        this.configService = configService;
+    }
+    /** Add a WebSocket connection for a specific session. */
+    addClientConnection(sessionId, socket) {
+        if (!this.sessionConnections.has(sessionId)) {
+            this.logger.log(`Creating new session for: ${sessionId}`);
+            this.sessionConnections.set(sessionId, new Set());
+        }
+        const connections = this.sessionConnections.get(sessionId);
+        connections?.add(socket);
+        this.logger.log(`Added connection to session: ${sessionId}, total connections: ${connections?.size}`);
+    }
+    /** Publish an event to all connections in a specific session. */
+    publishToSession(sessionId, event) {
+        const connections = this.sessionConnections.get(sessionId);
+        if (connections && connections.size > 0) {
+            this.logger.log(`Publishing event to session: ${sessionId}, connections: ${connections.size}`);
+            connections.forEach((socket) => {
+                if (socket.connected) {
+                    socket.emit('event', event);
+                }
+                else {
+                    connections.delete(socket);
+                }
+            });
+        }
+        else {
+            this.logger.warn(`Attempted to publish to non-existent session: ${sessionId}`);
+        }
+    }
+    /** Remove a client connection on disconnect. */
+    async removeClientConnection(sessionId, socket) {
+        const connections = this.sessionConnections.get(sessionId);
+        if (connections) {
+            connections.delete(socket);
+            this.logger.log(`Removed connection from session: ${sessionId}, remaining: ${connections.size}`);
+            if (connections.size === 0) {
+                this.sessionConnections.delete(sessionId);
+                this.logger.log(`Cleaned up empty session: ${sessionId}`);
+                const oracleEntityDid = this.configService.getOrThrow('ORACLE_ENTITY_DID');
+                // Use the DID validated at handshake time (stashed on `socket.data`),
+                // never the untrusted `handshake.query.userDid`.
+                const did = socket.data?.userDid;
+                if (!did) {
+                    this.logger.warn(`User DID not found for session ${sessionId}, skipping processing on disconnect`);
+                    return;
+                }
+                // Process session history when last client disconnects
+                this.sessionHistoryProcessor
+                    .processSessionHistory({
+                    sessionId,
+                    did,
+                    oracleEntityDid,
+                })
+                    .catch((err) => this.logger.error(`Failed to process session ${sessionId} on disconnect:`, err));
+            }
+        }
+    }
+    /** Active sessions count for monitoring. */
+    getActiveSessionsCount() {
+        return this.sessionConnections.size;
+    }
+    /** Total connections count for monitoring. */
+    getTotalConnectionsCount() {
+        let total = 0;
+        this.sessionConnections.forEach((connections) => {
+            total += connections.size;
+        });
+        return total;
+    }
+    onModuleInit() {
+        this.logger.log('WebSocket service initialized');
+        wsEmitter.on(WS_SERVICE_EVENT_NAME, (event) => {
+            this.publishToSession(event.payload.sessionId, event);
+        });
+    }
+    onModuleDestroy() {
+        this.logger.log('Cleaning up all WebSocket connections');
+        this.sessionConnections.forEach((connections) => {
+            connections.forEach((socket) => {
+                socket.disconnect();
+            });
+        });
+        this.sessionConnections.clear();
+    }
+};
+WsService = WsService_1 = __decorate([
+    Injectable(),
+    __metadata("design:paramtypes", [SessionHistoryProcessor,
+        ConfigService])
+], WsService);
+export { WsService };

package/dist/plugin-api/define-plugin.d.ts

@@ -0,0 +1,19 @@
+import type { OraclePlugin } from './oracle-plugin.js';
+/**
+ * Input shape accepted by `defineOraclePlugin`. The three identity fields
+ * (`name`, `version`, `manifest`) are required; every other plugin method
+ * is optional.
+ */
+export type DefineOraclePluginInput = Partial<OraclePlugin> & Pick<OraclePlugin, 'name' | 'version' | 'manifest'>;
+/**
+ * Identity-style helper for authoring a plugin as a plain object.
+ *
+ * Returns the same object the caller passed in, narrowed to `OraclePlugin`
+ * so type errors surface at the authoring site. The runtime treats the
+ * resulting POJO interchangeably with a class instance extending
+ * `OraclePlugin`.
+ *
+ * @throws TypeError when `name`, `version`, or `manifest` is missing.
+ */
+export declare function defineOraclePlugin(spec: DefineOraclePluginInput): OraclePlugin;
+//# sourceMappingURL=define-plugin.d.ts.map

package/dist/plugin-api/define-plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-plugin.d.ts","sourceRoot":"","sources":["../../src/plugin-api/define-plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD;;;;GAIG;AACH,MAAM,MAAM,uBAAuB,GAAG,OAAO,CAAC,YAAY,CAAC,GACzD,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,GAAG,UAAU,CAAC,CAAC;AAEtD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,uBAAuB,GAC5B,YAAY,CAsBd"}

package/dist/plugin-api/define-plugin.js

@@ -0,0 +1,25 @@
+/**
+ * Identity-style helper for authoring a plugin as a plain object.
+ *
+ * Returns the same object the caller passed in, narrowed to `OraclePlugin`
+ * so type errors surface at the authoring site. The runtime treats the
+ * resulting POJO interchangeably with a class instance extending
+ * `OraclePlugin`.
+ *
+ * @throws TypeError when `name`, `version`, or `manifest` is missing.
+ */
+export function defineOraclePlugin(spec) {
+    if (!spec || typeof spec !== 'object') {
+        throw new TypeError('defineOraclePlugin(spec): `spec` must be a plugin definition object.');
+    }
+    if (!spec.name || typeof spec.name !== 'string') {
+        throw new TypeError('defineOraclePlugin(spec): `name` is required and must be a non-empty string.');
+    }
+    if (!spec.version || typeof spec.version !== 'string') {
+        throw new TypeError('defineOraclePlugin(spec): `version` is required and must be a non-empty string.');
+    }
+    if (!spec.manifest || typeof spec.manifest !== 'object') {
+        throw new TypeError('defineOraclePlugin(spec): `manifest` is required and must be an object.');
+    }
+    return spec;
+}

package/dist/plugin-api/oracle-plugin.d.ts

@@ -0,0 +1,92 @@
+import type { DynamicModule, Type } from '@nestjs/common';
+import type { z } from 'zod';
+import type { AgentMiddleware, AuthExcludedRoute, PluginContext, PluginManifest, PluginSubAgent, PluginTool, RuntimeContext } from './types.js';
+export declare abstract class OraclePlugin {
+    /** Unique plugin identifier (kebab-case by convention). */
+    abstract readonly name: string;
+    /** Plugin version. */
+    abstract readonly version: string;
+    /** The agent's structured interface to this plugin. */
+    abstract readonly manifest: PluginManifest;
+    /** Hard dependencies — boot fails if any is missing. */
+    readonly dependsOn?: string[];
+    /** Soft dependencies — plugin loads either way; branches on availability. */
+    readonly softDependsOn?: string[];
+    /** Plugin-owned env vars. Merged into the runtime's Zod schema at boot. */
+    readonly configSchema?: z.ZodObject<any>;
+    /**
+     * Predicate the loader runs against `process.env` when the plugin is
+     * left at `'auto'` (or has no explicit toggle). Returning `false` skips
+     * the plugin. Plugins without an `autoDetect` are on-by-default.
+     */
+    autoDetect?(env: NodeJS.ProcessEnv): boolean;
+    /**
+     * Human-readable description of what `autoDetect` checks (e.g. the env
+     * var name). Surfaced in boot-error messages so operators see exactly
+     * why the plugin was skipped.
+     */
+    readonly autoDetectHint?: string;
+    /** Tools the main agent can call. Called once per request build. */
+    getTools?(ctx: PluginContext): PluginTool[] | Promise<PluginTool[]>;
+    /** Sub-agents the runtime auto-wraps as tools. */
+    getSubAgents?(ctx: PluginContext): PluginSubAgent[];
+    /**
+     * Request-time tool contributions. Called once per `createMainAgent`
+     * invocation with the full per-request `RuntimeContext`, so the plugin
+     * can decide which tools to expose based on live state (e.g. AG-UI
+     * actions in `state.agActions`).
+     *
+     * Results are merged with `getTools(ctx)` — both can fire on the same
+     * build. Plugins should pick whichever hook fits: boot-time when only
+     * config/identity matters; request-time when state/user/session matters.
+     */
+    getRequestTools?(rtCtx: RuntimeContext): PluginTool[] | Promise<PluginTool[]>;
+    /**
+     * Request-time sub-agent contributions. Same merge semantics as
+     * `getRequestTools` — boot-time `getSubAgents` and request-time
+     * `getRequestSubAgents` outputs are both collected.
+     */
+    getRequestSubAgents?(rtCtx: RuntimeContext): PluginSubAgent[] | Promise<PluginSubAgent[]>;
+    /**
+     * LangChain middlewares inserted after the four always-on middlewares
+     * (tool-validation, retry, page-context, safety-guardrail).
+     */
+    getMiddlewares?(ctx: PluginContext): AgentMiddleware[];
+    /**
+     * Read-only accessors this plugin exposes to other plugins via `ctx.shared`.
+     * Pattern: this plugin computes/owns some derived value from state; others
+     * read it.
+     */
+    getSharedState?(): Record<string, (state: any, runCtx: RuntimeContext) => unknown>;
+    /**
+     * NestJS modules the plugin contributes. Spread into `RuntimeAppModule.imports`,
+     * so the module gets full DI access to Tier-0 services (Sessions, Messages,
+     * Cache, etc.) and can declare its own Controllers, providers, and
+     * `OnModuleInit` / `OnModuleDestroy` lifecycle hooks.
+     *
+     * Returns either plain module classes or `DynamicModule` configs (from
+     * `Module.register(...)` / `forRoot(...)` style helpers).
+     *
+     * Use this for plugins that need a long-lived NestJS service (Slack socket,
+     * BullMQ workers) or HTTP Controllers (Calls REST API).
+     *
+     * `ctx` carries the validated merged config + identity + logger so
+     * module-construction code can read env without going through `process.env`.
+     * The optional arg keeps existing plugins source-compatible —
+     * implementations that ignore it work unchanged.
+     */
+    getNestModules?(ctx?: PluginContext): Array<Type | DynamicModule>;
+    /**
+     * Routes owned by this plugin's `getNestModules()` controllers that MUST NOT
+     * pass through `AuthHeaderMiddleware`. Use for webhooks, OAuth callbacks,
+     * public probes — anything that doesn't authenticate via UCAN. Returning an
+     * empty array (or omitting the method) keeps every plugin route auth-locked.
+     *
+     * The returned `path` is matched against the request URL the same way
+     * `MiddlewareConsumer.exclude(...)` matches — leading slash is optional and
+     * the value should be the full path the controller mounts at (e.g.
+     * `weather/now`, not just `now`).
+     */
+    getAuthExcludedRoutes?(): AuthExcludedRoute[];
+}
+//# sourceMappingURL=oracle-plugin.d.ts.map

package/dist/plugin-api/oracle-plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oracle-plugin.d.ts","sourceRoot":"","sources":["../../src/plugin-api/oracle-plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EACV,eAAe,EACf,iBAAiB,EACjB,aAAa,EACb,cAAc,EACd,cAAc,EACd,UAAU,EACV,cAAc,EACf,MAAM,YAAY,CAAC;AAEpB,8BAAsB,YAAY;IAChC,2DAA2D;IAC3D,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAE/B,sBAAsB;IACtB,QAAQ,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAElC,uDAAuD;IACvD,QAAQ,CAAC,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAE3C,wDAAwD;IACxD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IAE9B,6EAA6E;IAC7E,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IAElC,2EAA2E;IAE3E,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IAEzC;;;;OAIG;IACH,UAAU,CAAC,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,OAAO;IAE5C;;;;OAIG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IAEjC,oEAAoE;IACpE,QAAQ,CAAC,CAAC,GAAG,EAAE,aAAa,GAAG,UAAU,EAAE,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAEnE,kDAAkD;IAClD,YAAY,CAAC,CAAC,GAAG,EAAE,aAAa,GAAG,cAAc,EAAE;IAEnD;;;;;;;;;OASG;IACH,eAAe,CAAC,CAAC,KAAK,EAAE,cAAc,GAAG,UAAU,EAAE,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAE7E;;;;OAIG;IACH,mBAAmB,CAAC,CAClB,KAAK,EAAE,cAAc,GACpB,cAAc,EAAE,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAE/C;;;OAGG;IACH,cAAc,CAAC,CAAC,GAAG,EAAE,aAAa,GAAG,eAAe,EAAE;IAEtD;;;;OAIG;IACH,cAAc,CAAC,IAAI,MAAM,CACvB,MAAM,EAEN,CAAC,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,cAAc,KAAK,OAAO,CAChD;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,cAAc,CAAC,CAAC,GAAG,CAAC,EAAE,aAAa,GAAG,KAAK,CAAC,IAAI,GAAG,aAAa,CAAC;IAEjE;;;;;;;;;;OAUG;IACH,qBAAqB,CAAC,IAAI,iBAAiB,EAAE;CAC9C"}

package/dist/plugin-api/oracle-plugin.js

@@ -0,0 +1,15 @@
+export class OraclePlugin {
+    /** Hard dependencies — boot fails if any is missing. */
+    dependsOn;
+    /** Soft dependencies — plugin loads either way; branches on availability. */
+    softDependsOn;
+    /** Plugin-owned env vars. Merged into the runtime's Zod schema at boot. */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    configSchema;
+    /**
+     * Human-readable description of what `autoDetect` checks (e.g. the env
+     * var name). Surfaced in boot-error messages so operators see exactly
+     * why the plugin was skipped.
+     */
+    autoDetectHint;
+}

package/dist/plugin-api/tool-helper.d.ts

@@ -0,0 +1,33 @@
+import type { z } from 'zod';
+import type { PluginTool, RuntimeContext } from './types.js';
+/**
+ * Authoring options for `tool()`. Mirrors the public surface of `PluginTool`
+ * minus the handler (which is the first positional argument).
+ */
+export interface ToolHelperOptions {
+    /** Tool name shown to the agent. Must be unique within the plugin. */
+    name: string;
+    /** Tool description shown to the agent. */
+    description: string;
+    /** Zod schema validating the tool's input arguments. */
+    schema: z.ZodType;
+    /**
+     * Override visibility — by default the tool inherits the plugin's
+     * `manifest.visibility` setting.
+     */
+    visibility?: PluginTool['visibility'];
+}
+/**
+ * User-facing helper to author a plugin tool.
+ *
+ * The handler receives the validated arguments and a `RuntimeContext` built
+ * fresh per invocation. The runtime is responsible for bridging LangChain's
+ * `(args, runConfig)` calling convention into `(args, ctx)` when it wires
+ * the tool into the agent.
+ *
+ * @param handler - Async function invoked when the agent calls the tool.
+ * @param options - Tool descriptor (name, description, schema, optional visibility).
+ * @returns A `PluginTool` consumable by the runtime's tool registration step.
+ */
+export declare function tool(handler: (args: unknown, ctx: RuntimeContext) => Promise<unknown>, options: ToolHelperOptions): PluginTool;
+//# sourceMappingURL=tool-helper.d.ts.map

package/dist/plugin-api/tool-helper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-helper.d.ts","sourceRoot":"","sources":["../../src/plugin-api/tool-helper.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE7D;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,WAAW,EAAE,MAAM,CAAC;IACpB,wDAAwD;IACxD,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC;IAClB;;;OAGG;IACH,UAAU,CAAC,EAAE,UAAU,CAAC,YAAY,CAAC,CAAC;CACvC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,IAAI,CAClB,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,cAAc,KAAK,OAAO,CAAC,OAAO,CAAC,EACjE,OAAO,EAAE,iBAAiB,GACzB,UAAU,CAoCZ"}

package/dist/plugin-api/tool-helper.js

@@ -0,0 +1,40 @@
+/**
+ * User-facing helper to author a plugin tool.
+ *
+ * The handler receives the validated arguments and a `RuntimeContext` built
+ * fresh per invocation. The runtime is responsible for bridging LangChain's
+ * `(args, runConfig)` calling convention into `(args, ctx)` when it wires
+ * the tool into the agent.
+ *
+ * @param handler - Async function invoked when the agent calls the tool.
+ * @param options - Tool descriptor (name, description, schema, optional visibility).
+ * @returns A `PluginTool` consumable by the runtime's tool registration step.
+ */
+export function tool(handler, options) {
+    if (typeof handler !== 'function') {
+        throw new TypeError('tool(handler, options): `handler` must be a function.');
+    }
+    if (!options || typeof options !== 'object') {
+        throw new TypeError('tool(handler, options): `options` is required.');
+    }
+    const { name, description, schema, visibility } = options;
+    if (!name || typeof name !== 'string') {
+        throw new TypeError('tool(handler, options): `options.name` must be a non-empty string.');
+    }
+    if (!description || typeof description !== 'string') {
+        throw new TypeError('tool(handler, options): `options.description` must be a non-empty string.');
+    }
+    if (!schema) {
+        throw new TypeError('tool(handler, options): `options.schema` (Zod schema) is required.');
+    }
+    const pluginTool = {
+        name,
+        description,
+        schema,
+        handler,
+    };
+    if (visibility !== undefined) {
+        pluginTool.visibility = visibility;
+    }
+    return pluginTool;
+}