@ixo/oracle-runtime 0.0.1

package/dist/plugins/user-preferences/service/user-preferences.service.js

@@ -0,0 +1,105 @@
+import { MatrixError, MatrixManager } from '@ixo/matrix';
+import { Logger } from '@nestjs/common';
+import { z } from 'zod';
+export const USER_PREFS_STATE_KEY = 'user_prefs';
+export const UserPreferencesSchema = z.object({
+    agentName: z.string().max(80).optional(),
+    userName: z.string().max(80).optional(),
+    language: z.string().max(20).optional(), // BCP-47-ish, free-form
+    tone: z.string().optional(), // e.g. "casual", "playful"
+    formality: z
+        .enum([
+        'casual',
+        'friendly',
+        'neutral',
+        'semi-formal',
+        'professional',
+        'formal',
+        'technical',
+        'academic',
+    ])
+        .optional(),
+    customInstructions: z.string().max(2000).optional(),
+    updatedAt: z.iso.datetime().optional(), // service sets on every write
+});
+const SIXTY_SECONDS_MS = 60 * 1000;
+/**
+ * Stores per-room user preferences in Matrix room state, with an optional
+ * in-memory cache. The singleton is consumed by the user-preferences
+ * middleware which loads prefs into `state.userPreferences` on every request.
+ */
+export class UserPreferencesService {
+    static instance;
+    cacheManager = null;
+    constructor() { }
+    static getInstance() {
+        if (!UserPreferencesService.instance) {
+            UserPreferencesService.instance = new UserPreferencesService();
+        }
+        return UserPreferencesService.instance;
+    }
+    setCacheManager(cache) {
+        this.cacheManager = cache;
+    }
+    cacheKey(roomId) {
+        return `user-prefs:${roomId}`;
+    }
+    /**
+     * Read user preferences for a given room.
+     * Returns undefined if no preferences have been set, or if anything goes wrong
+     * (we never want missing prefs to break a chat session).
+     */
+    async get(roomId) {
+        const key = this.cacheKey(roomId);
+        const cached = await this.cacheManager?.get(key);
+        if (cached) {
+            return cached;
+        }
+        let raw;
+        try {
+            const stateManager = MatrixManager.getInstance().stateManager;
+            raw = await stateManager.getState(roomId, USER_PREFS_STATE_KEY);
+        }
+        catch (error) {
+            if (error instanceof MatrixError && error.errcode === 'M_NOT_FOUND') {
+                return undefined;
+            }
+            Logger.warn(`[UserPreferencesService] Failed to load prefs for room ${roomId}: ${error instanceof Error ? error.message : String(error)}`);
+            return undefined;
+        }
+        const parsed = UserPreferencesSchema.safeParse(raw);
+        if (!parsed.success) {
+            Logger.warn(`[UserPreferencesService] Invalid prefs payload for room ${roomId}: ${parsed.error.message}`);
+            return undefined;
+        }
+        await this.cacheManager?.set(key, parsed.data, SIXTY_SECONDS_MS);
+        return parsed.data;
+    }
+    /**
+     * Merge `partial` into the existing preferences, write to Matrix room state,
+     * invalidate the cache, and return the merged result.
+     * `updatedAt` is always set by this service.
+     */
+    async set(roomId, partial) {
+        const current = (await this.get(roomId)) ?? {};
+        if (Object.keys(partial).length === 0 && !partial.updatedAt) {
+            return current;
+        }
+        const merged = UserPreferencesSchema.parse({
+            ...current,
+            ...partial,
+            updatedAt: new Date().toISOString(),
+        });
+        const stateManager = MatrixManager.getInstance().stateManager;
+        await stateManager.setState({
+            roomId,
+            stateKey: USER_PREFS_STATE_KEY,
+            data: merged,
+        });
+        await this.invalidate(roomId);
+        return merged;
+    }
+    async invalidate(roomId) {
+        await this.cacheManager?.del(this.cacheKey(roomId));
+    }
+}

package/dist/plugins/user-preferences/user-preferences-http.module.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Plugin-owned HTTP surface. Returned from `UserPreferencesPlugin.getNestModules()`
+ * so the `GET /user-preferences` endpoint only exists when the plugin is
+ * loaded. Reads via `UserPreferencesService.getInstance()` — the same
+ * singleton the plugin's middleware + tool consume, so the controller
+ * shares state with the agent path.
+ */
+export declare class UserPreferencesHttpModule {
+}
+//# sourceMappingURL=user-preferences-http.module.d.ts.map

package/dist/plugins/user-preferences/user-preferences-http.module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-preferences-http.module.d.ts","sourceRoot":"","sources":["../../../src/plugins/user-preferences/user-preferences-http.module.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;AACH,qBAGa,yBAAyB;CAAG"}

package/dist/plugins/user-preferences/user-preferences-http.module.js

@@ -0,0 +1,23 @@
+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 { Module } from '@nestjs/common';
+import { UserPreferencesController } from './user-preferences.controller.js';
+/**
+ * Plugin-owned HTTP surface. Returned from `UserPreferencesPlugin.getNestModules()`
+ * so the `GET /user-preferences` endpoint only exists when the plugin is
+ * loaded. Reads via `UserPreferencesService.getInstance()` — the same
+ * singleton the plugin's middleware + tool consume, so the controller
+ * shares state with the agent path.
+ */
+let UserPreferencesHttpModule = class UserPreferencesHttpModule {
+};
+UserPreferencesHttpModule = __decorate([
+    Module({
+        controllers: [UserPreferencesController],
+    })
+], UserPreferencesHttpModule);
+export { UserPreferencesHttpModule };

package/dist/plugins/user-preferences/user-preferences-tool.d.ts

@@ -0,0 +1,22 @@
+import type { Logger, PluginTool } from '../../plugin-api/types.js';
+import type { UserPreferencesWriter } from './service/user-preferences.service.js';
+export interface CreateSetUserPreferencesToolOptions {
+    /** Service the tool delegates writes to (typically the singleton). */
+    service: UserPreferencesWriter;
+    /** Optional logger; defaults to a no-op. */
+    logger?: Logger;
+}
+/**
+ * Builds the `set_user_preferences` plugin tool. The tool merges the supplied
+ * partial preferences into the user's stored preferences for the active room;
+ * only the fields provided are updated.
+ *
+ * The active `roomId` is read off `ctx.session.roomId` per invocation. Tools
+ * called from clients without a room (e.g. some non-Matrix flows) get a
+ * descriptive error string back rather than throwing — the agent can recover.
+ *
+ * Note: changes take effect from the user's NEXT message — the system prompt
+ * for the current turn has already been built.
+ */
+export declare function createSetUserPreferencesTool(options: CreateSetUserPreferencesToolOptions): PluginTool;
+//# sourceMappingURL=user-preferences-tool.d.ts.map

package/dist/plugins/user-preferences/user-preferences-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-preferences-tool.d.ts","sourceRoot":"","sources":["../../../src/plugins/user-preferences/user-preferences-tool.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,MAAM,EACN,UAAU,EAEX,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uCAAuC,CAAC;AAmFnF,MAAM,WAAW,mCAAmC;IAClD,sEAAsE;IACtE,OAAO,EAAE,qBAAqB,CAAC;IAC/B,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,mCAAmC,GAC3C,UAAU,CA0BZ"}

package/dist/plugins/user-preferences/user-preferences-tool.js

@@ -0,0 +1,103 @@
+import { z } from 'zod';
+import { tool } from '../../plugin-api/tool-helper.js';
+const NOOP_LOGGER = {
+    log: () => undefined,
+    warn: () => undefined,
+    error: () => undefined,
+};
+const setUserPreferencesSchema = z.object({
+    agentName: z
+        .string()
+        .max(80)
+        .optional()
+        .describe("What the user wants you (the agent) to be called (e.g. 'Companion'). Use exactly the form the user asked for. Max 80 characters."),
+    userName: z
+        .string()
+        .max(80)
+        .optional()
+        .describe("What the user wants you to call them (e.g. 'Yousef'). Use exactly the form the user asked for. Max 80 characters."),
+    language: z
+        .string()
+        .max(20)
+        .optional()
+        .describe("Preferred reply language as a free-form code or name (e.g. 'en', 'ar', 'Arabic', 'Egyptian Arabic'). " +
+        'Be precise — if the user specified a dialect or variant, capture that. Max 20 characters.'),
+    tone: z
+        .string()
+        .optional()
+        .describe("Short tone label your future self will see at the top of every prompt (e.g. 'playful and warm', " +
+        "'concise and dry', 'patient teacher'). Pick descriptive words, not vague ones."),
+    formality: z
+        .enum([
+        'casual',
+        'friendly',
+        'neutral',
+        'semi-formal',
+        'professional',
+        'formal',
+        'technical',
+        'academic',
+    ])
+        .optional()
+        .describe('How formal the replies should be. Pick the value closest to what the user actually wants, ' +
+        'not what the request literally said.'),
+    customInstructions: z
+        .string()
+        .max(2000)
+        .optional()
+        .describe('Free-form custom instructions your FUTURE SELF will read every turn. Treat this like writing ' +
+        'a system prompt: be specific, complete, and unambiguous. Include the WHY when it matters ' +
+        "(e.g. 'User has dyslexia — keep sentences short and avoid long lists'). " +
+        'When updating, MERGE with existing instructions rather than replacing — read what is already ' +
+        'there (visible in your current system prompt under "User Preferences") and write the full new ' +
+        'instruction set, preserving anything still relevant. Max 2000 characters.'),
+});
+const SET_USER_PREFERENCES_DESCRIPTION = "Update the user's preferences. Call this whenever the user asks you to change how you behave " +
+    "(e.g. 'call me Yousef', 'reply in Arabic', 'be more casual').\n\n" +
+    'IMPORTANT — you are writing instructions for your FUTURE SELF. ' +
+    'On every later turn this exact text will be injected back into your system prompt and you will read it cold, ' +
+    'with no memory of this conversation or why the user asked. So:\n' +
+    "  • Be specific and self-contained. Don't write 'be more casual' — write 'Use casual, conversational " +
+    "tone. Avoid corporate phrasing. Use contractions. Drop filler words.'\n" +
+    "  • Capture intent, not just the literal request. If the user says 'stop being so formal', infer the " +
+    'positive form: what should you do instead?\n' +
+    '  • Preserve existing instructions when adding new ones — only overwrite the fields you mean to change. ' +
+    'Other fields are kept as-is.\n' +
+    "  • If unsure between two interpretations, pick the more specific one — your future self can't ask back.\n\n" +
+    "Note: changes apply from the user's NEXT message (the current turn's prompt is already built).";
+/**
+ * Builds the `set_user_preferences` plugin tool. The tool merges the supplied
+ * partial preferences into the user's stored preferences for the active room;
+ * only the fields provided are updated.
+ *
+ * The active `roomId` is read off `ctx.session.roomId` per invocation. Tools
+ * called from clients without a room (e.g. some non-Matrix flows) get a
+ * descriptive error string back rather than throwing — the agent can recover.
+ *
+ * Note: changes take effect from the user's NEXT message — the system prompt
+ * for the current turn has already been built.
+ */
+export function createSetUserPreferencesTool(options) {
+    const logger = options.logger ?? NOOP_LOGGER;
+    const { service } = options;
+    return tool(async (rawArgs, ctx) => {
+        const args = setUserPreferencesSchema.parse(rawArgs);
+        const roomId = ctx.session.roomId;
+        if (!roomId) {
+            return '[Error updating user preferences: no active room on this session]';
+        }
+        try {
+            const merged = await service.set(roomId, args);
+            return `Updated. New preferences: ${JSON.stringify(merged, null, 2)}`;
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            logger.error(`set_user_preferences error: ${msg}`);
+            return `[Error updating user preferences: ${msg}]`;
+        }
+    }, {
+        name: 'set_user_preferences',
+        description: SET_USER_PREFERENCES_DESCRIPTION,
+        schema: setUserPreferencesSchema,
+    });
+}

package/dist/plugins/user-preferences/user-preferences.controller.d.ts

@@ -0,0 +1,18 @@
+import { ConfigService } from '@nestjs/config';
+import type { Request } from 'express';
+import { type UserPreferences } from './service/user-preferences.service.js';
+/**
+ * Exposes the per-room user preferences read endpoint. Lives inside the
+ * plugin (not the runtime core) — the plugin's `getNestModules()` wires
+ * this controller into Nest only when the plugin is loaded.
+ *
+ * Writes happen via the agent's `set_user_preferences` tool (the
+ * plugin-supplied LLM tool), not over HTTP — keeping the surface narrow.
+ */
+export declare class UserPreferencesController {
+    private readonly configService;
+    private readonly logger;
+    constructor(configService: ConfigService);
+    getPreferences(req: Request): Promise<UserPreferences | null>;
+}
+//# sourceMappingURL=user-preferences.controller.d.ts.map

package/dist/plugins/user-preferences/user-preferences.controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-preferences.controller.d.ts","sourceRoot":"","sources":["../../../src/plugins/user-preferences/user-preferences.controller.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE/C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAEL,KAAK,eAAe,EACrB,MAAM,uCAAuC,CAAC;AAE/C;;;;;;;GAOG;AACH,qBAEa,yBAAyB;IAGxB,OAAO,CAAC,QAAQ,CAAC,aAAa;IAF1C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA8C;gBAExC,aAAa,EAAE,aAAa;IAYnD,cAAc,CAAQ,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;CA2B3E"}

package/dist/plugins/user-preferences/user-preferences.controller.js

@@ -0,0 +1,72 @@
+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 UserPreferencesController_1;
+import { MatrixManager } from '@ixo/matrix';
+import { getMatrixHomeServerCroppedForDid } from '@ixo/oracles-chain-client';
+import { Controller, Get, Logger, Req } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { ApiOperation, ApiResponse, ApiTags } from '@nestjs/swagger';
+import { UserPreferencesService, } from './service/user-preferences.service.js';
+/**
+ * Exposes the per-room user preferences read endpoint. Lives inside the
+ * plugin (not the runtime core) — the plugin's `getNestModules()` wires
+ * this controller into Nest only when the plugin is loaded.
+ *
+ * Writes happen via the agent's `set_user_preferences` tool (the
+ * plugin-supplied LLM tool), not over HTTP — keeping the surface narrow.
+ */
+let UserPreferencesController = UserPreferencesController_1 = class UserPreferencesController {
+    configService;
+    logger = new Logger(UserPreferencesController_1.name);
+    constructor(configService) {
+        this.configService = configService;
+    }
+    async getPreferences(req) {
+        const { did } = req.authData;
+        const oracleEntityDid = this.configService.getOrThrow('ORACLE_ENTITY_DID');
+        const userHomeServer = await getMatrixHomeServerCroppedForDid(did);
+        const { roomId } = await MatrixManager.getInstance().getOracleRoomIdWithHomeServer({
+            userDid: did,
+            oracleEntityDid,
+            userHomeServer,
+        });
+        if (!roomId) {
+            this.logger.warn(`Could not resolve user↔oracle room for userDid=${did}, oracleEntityDid=${oracleEntityDid}, userHomeServer=${userHomeServer}`);
+            return null;
+        }
+        const prefs = await UserPreferencesService.getInstance().get(roomId);
+        this.logger.log(`Fetched user preferences for userDid=${did}, roomId=${roomId}: ${prefs ? 'Found' : 'null'}`);
+        return prefs ?? null;
+    }
+};
+__decorate([
+    Get(),
+    ApiOperation({
+        summary: 'Get user preferences for the user↔oracle Matrix room.',
+    }),
+    ApiResponse({
+        status: 200,
+        description: 'Preferences object, or null when no preferences have been set yet.',
+    }),
+    ApiResponse({ status: 401, description: 'Missing or invalid auth token.' }),
+    __param(0, Req()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], UserPreferencesController.prototype, "getPreferences", null);
+UserPreferencesController = UserPreferencesController_1 = __decorate([
+    ApiTags('user-preferences'),
+    Controller('user-preferences'),
+    __metadata("design:paramtypes", [ConfigService])
+], UserPreferencesController);
+export { UserPreferencesController };

package/dist/plugins/user-preferences/user-preferences.plugin.d.ts

@@ -0,0 +1,27 @@
+import type { DynamicModule, Type } from '@nestjs/common';
+import { OraclePlugin } from '../../plugin-api/oracle-plugin.js';
+import type { PluginContext, PluginManifest, PluginTool } from '../../plugin-api/types.js';
+import { type UserPreferencesReader, type UserPreferencesWriter } from './service/user-preferences.service.js';
+/** Service contract the plugin needs: read for the middleware, write for the tool. */
+export type UserPreferencesPluginService = UserPreferencesReader & UserPreferencesWriter;
+/**
+ * Per-room user preferences plugin.
+ *
+ * - `state.userPreferences` is hydrated by `AgentBuilder` (via
+ *   `UserPreferencesService.getInstance().get(roomId)`) BEFORE the agent is
+ *   compiled so the system prompt sees the value on turn 1.
+ * - Exposes a `set_user_preferences` tool the agent calls when the user
+ *   asks to change behavioral preferences (tone, language, formality,
+ *   what to call the agent).
+ * - Ships `GET /user-preferences` via `getNestModules`.
+ */
+export declare class UserPreferencesPlugin extends OraclePlugin {
+    readonly name = "user-preferences";
+    readonly version = "1.0.0";
+    readonly manifest: PluginManifest;
+    private readonly service;
+    constructor(service?: UserPreferencesPluginService);
+    getTools(ctx: PluginContext): PluginTool[];
+    getNestModules(): Array<Type | DynamicModule>;
+}
+//# sourceMappingURL=user-preferences.plugin.d.ts.map

package/dist/plugins/user-preferences/user-preferences.plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-preferences.plugin.d.ts","sourceRoot":"","sources":["../../../src/plugins/user-preferences/user-preferences.plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AACjE,OAAO,KAAK,EACV,aAAa,EACb,cAAc,EACd,UAAU,EACX,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAEL,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC3B,MAAM,uCAAuC,CAAC;AAI/C,sFAAsF;AACtF,MAAM,MAAM,4BAA4B,GAAG,qBAAqB,GAC9D,qBAAqB,CAAC;AAExB;;;;;;;;;;GAUG;AACH,qBAAa,qBAAsB,SAAQ,YAAY;IACrD,QAAQ,CAAC,IAAI,sBAAsB;IAEnC,QAAQ,CAAC,OAAO,WAAW;IAE3B,QAAQ,CAAC,QAAQ,EAAE,cAAc,CA+B/B;IAEF,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA+B;gBAGrD,OAAO,GAAE,4BAAmE;IAMrE,QAAQ,CAAC,GAAG,EAAE,aAAa,GAAG,UAAU,EAAE;IAS1C,cAAc,IAAI,KAAK,CAAC,IAAI,GAAG,aAAa,CAAC;CAIvD"}

package/dist/plugins/user-preferences/user-preferences.plugin.js

@@ -0,0 +1,66 @@
+import { OraclePlugin } from '../../plugin-api/oracle-plugin.js';
+import { UserPreferencesService, } from './service/user-preferences.service.js';
+import { UserPreferencesHttpModule } from './user-preferences-http.module.js';
+import { createSetUserPreferencesTool } from './user-preferences-tool.js';
+/**
+ * Per-room user preferences plugin.
+ *
+ * - `state.userPreferences` is hydrated by `AgentBuilder` (via
+ *   `UserPreferencesService.getInstance().get(roomId)`) BEFORE the agent is
+ *   compiled so the system prompt sees the value on turn 1.
+ * - Exposes a `set_user_preferences` tool the agent calls when the user
+ *   asks to change behavioral preferences (tone, language, formality,
+ *   what to call the agent).
+ * - Ships `GET /user-preferences` via `getNestModules`.
+ */
+export class UserPreferencesPlugin extends OraclePlugin {
+    name = 'user-preferences';
+    version = '1.0.0';
+    manifest = {
+        title: 'User Preferences',
+        summary: 'Behavioral preferences — how the user wants you to respond (tone, language, formality, what to call you).',
+        whenToUse: [
+            'User states how they want you to behave: "be more terse", "respond in Spanish", "call me Alex", "stop using emojis".',
+            'User asks to change the voice, formality, or language of your replies — save it so it persists across sessions, not just this turn.',
+        ],
+        whenNotToUse: [
+            'Facts about who the user is (name, role, project) — those go to memory, not preferences.',
+            'Artifacts you have produced or how the user reacted to them — also memory, not preferences.',
+            'One-turn formatting requests ("just for this answer, use bullets") — adapt locally without saving.',
+        ],
+        examples: [
+            {
+                user: 'From now on, please respond in Spanish.',
+                thought: 'Behavioral preference about language — save it so it persists.',
+                tool: 'set_user_preferences',
+                args: { language: 'Spanish' },
+            },
+            {
+                user: 'Be more concise — drop the explanations.',
+                thought: 'Preference about tone/length, not a single-turn request.',
+                tool: 'set_user_preferences',
+                args: { tone: 'concise' },
+            },
+        ],
+        visibility: 'always',
+        stability: 'stable',
+        category: 'core',
+    };
+    service;
+    constructor(service = UserPreferencesService.getInstance()) {
+        super();
+        this.service = service;
+    }
+    getTools(ctx) {
+        return [
+            createSetUserPreferencesTool({
+                service: this.service,
+                logger: ctx.logger,
+            }),
+        ];
+    }
+    getNestModules() {
+        // Ships `GET /user-preferences` only when this plugin is loaded.
+        return [UserPreferencesHttpModule];
+    }
+}

package/dist/registries/config-schema-registry.d.ts

@@ -0,0 +1,24 @@
+import type { z } from 'zod';
+import type { OraclePlugin } from '../plugin-api/oracle-plugin.js';
+/** A collected configSchema tagged with the plugin that contributed it. */
+export interface RegisteredConfigSchema {
+    pluginName: string;
+    schema: z.ZodObject<any>;
+}
+/**
+ * Stores plugin-owned `configSchema` objects in registration order. The
+ * actual Zod merge — collision detection, plugin-ownership tracking, env
+ * validation — lives in `bootstrap/schema-composer.ts` via
+ * `composeEnvSchema()` so the merge logic exists in exactly one place.
+ */
+export declare class ConfigSchemaRegistry {
+    private readonly entries;
+    register(plugin: OraclePlugin): void;
+    collect(): RegisteredConfigSchema[];
+    /**
+     * Config keys may collide intentionally (later wins, with warning), so
+     * collision is not fatal. Provided for a uniform registry surface.
+     */
+    assertNoCollisions(): void;
+}
+//# sourceMappingURL=config-schema-registry.d.ts.map

package/dist/registries/config-schema-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-schema-registry.d.ts","sourceRoot":"","sources":["../../src/registries/config-schema-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC;AAEnE,2EAA2E;AAC3E,MAAM,WAAW,sBAAsB;IACrC,UAAU,EAAE,MAAM,CAAC;IAEnB,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;CAC1B;AAED;;;;;GAKG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgC;IAExD,QAAQ,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI;IAQpC,OAAO,IAAI,sBAAsB,EAAE;IAInC;;;OAGG;IACH,kBAAkB,IAAI,IAAI;CAG3B"}

package/dist/registries/config-schema-registry.js

@@ -0,0 +1,27 @@
+/**
+ * Stores plugin-owned `configSchema` objects in registration order. The
+ * actual Zod merge — collision detection, plugin-ownership tracking, env
+ * validation — lives in `bootstrap/schema-composer.ts` via
+ * `composeEnvSchema()` so the merge logic exists in exactly one place.
+ */
+export class ConfigSchemaRegistry {
+    entries = [];
+    register(plugin) {
+        if (!plugin.configSchema)
+            return;
+        this.entries.push({
+            pluginName: plugin.name,
+            schema: plugin.configSchema,
+        });
+    }
+    collect() {
+        return [...this.entries];
+    }
+    /**
+     * Config keys may collide intentionally (later wins, with warning), so
+     * collision is not fatal. Provided for a uniform registry surface.
+     */
+    assertNoCollisions() {
+        // intentional no-op
+    }
+}

package/dist/registries/index.d.ts

@@ -0,0 +1,13 @@
+export { ToolRegistry } from './tool-registry.js';
+export type { RegisteredTool } from './tool-registry.js';
+export { SubAgentRegistry } from './subagent-registry.js';
+export type { RegisteredSubAgent } from './subagent-registry.js';
+export { MiddlewareRegistry } from './middleware-registry.js';
+export type { RegisteredMiddleware } from './middleware-registry.js';
+export { ManifestRegistry } from './manifest-registry.js';
+export type { RegisteredManifest, ManifestCrossCheckResult, } from './manifest-registry.js';
+export { ConfigSchemaRegistry } from './config-schema-registry.js';
+export type { RegisteredConfigSchema } from './config-schema-registry.js';
+export { SharedStateRegistry } from './shared-state-registry.js';
+export type { RegisteredSharedAccessor } from './shared-state-registry.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/registries/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/registries/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,YAAY,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,YAAY,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAEjE,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,YAAY,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAErE,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,YAAY,EACV,kBAAkB,EAClB,wBAAwB,GACzB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,YAAY,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAE1E,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,YAAY,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAC"}

package/dist/registries/index.js

@@ -0,0 +1,6 @@
+export { ToolRegistry } from './tool-registry.js';
+export { SubAgentRegistry } from './subagent-registry.js';
+export { MiddlewareRegistry } from './middleware-registry.js';
+export { ManifestRegistry } from './manifest-registry.js';
+export { ConfigSchemaRegistry } from './config-schema-registry.js';
+export { SharedStateRegistry } from './shared-state-registry.js';

package/dist/registries/manifest-registry.d.ts

@@ -0,0 +1,49 @@
+import type { OraclePlugin } from '../plugin-api/oracle-plugin.js';
+import type { PluginManifest } from '../plugin-api/types.js';
+import type { SubAgentRegistry } from './subagent-registry.js';
+import type { ToolRegistry } from './tool-registry.js';
+/** A collected manifest tagged with the plugin that contributed it. */
+export interface RegisteredManifest {
+    pluginName: string;
+    manifest: PluginManifest;
+}
+/** Result of cross-checking every plugin's example tools against a ToolRegistry. */
+export interface ManifestCrossCheckResult {
+    errors: string[];
+}
+/**
+ * Stores plugin manifests and wires the cross-tool-reference check that can
+ * only run once tool registration is complete.
+ *
+ * Manifest titles can collide (display only); the registry does not block on
+ * title duplication.
+ */
+export declare class ManifestRegistry {
+    private readonly entries;
+    /** Record a plugin's manifest. */
+    register(plugin: OraclePlugin): void;
+    /**
+     * Plain-pass collect — returns the registered manifests in registration
+     * order. Manifests are eagerly available on the plugin, so this method
+     * accepts no context but matches the registry shape used elsewhere.
+     */
+    collect(): RegisteredManifest[];
+    /**
+     * For each registered manifest, validate that every `examples[].tool`
+     * reference exists in the supplied registries. Sub-agents are first-class
+     * tools to the agent — they get wrapped as `call_<name>` StructuredTools —
+     * so the validator unions tool names with sub-agent wrapped names. Both
+     * registries MUST have been collected and asserted before calling this.
+     *
+     * Returns the union of all per-plugin error strings — each entry is
+     * prefixed with the plugin name and field path (delegated to
+     * `validateExamplesAgainstTools`).
+     */
+    validateAgainstTools(toolRegistry: ToolRegistry, subAgentRegistry: SubAgentRegistry): ManifestCrossCheckResult;
+    /**
+     * Manifest title collisions are display-only, so this is a no-op. Provided
+     * for a uniform registry surface.
+     */
+    assertNoCollisions(): void;
+}
+//# sourceMappingURL=manifest-registry.d.ts.map

package/dist/registries/manifest-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest-registry.d.ts","sourceRoot":"","sources":["../../src/registries/manifest-registry.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC;AACnE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,uEAAuE;AACvE,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,cAAc,CAAC;CAC1B;AAED,oFAAoF;AACpF,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;;GAMG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4B;IAEpD,kCAAkC;IAClC,QAAQ,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI;IAIpC;;;;OAIG;IACH,OAAO,IAAI,kBAAkB,EAAE;IAI/B;;;;;;;;;;OAUG;IACH,oBAAoB,CAClB,YAAY,EAAE,YAAY,EAC1B,gBAAgB,EAAE,gBAAgB,GACjC,wBAAwB;IAiB3B;;;OAGG;IACH,kBAAkB,IAAI,IAAI;CAG3B"}