glirastes 0.3.0 → 0.3.2

package/dist/cjs/server/adapters/nestjs/chat/ws-loader.js

@@ -0,0 +1,72 @@
+"use strict";
+// Runtime loader for the optional `ws` peer dependency.
+//
+// `ws` is only needed when the speech-to-text feature is enabled
+// (AiChatModule.attachWebSockets()). A top-level `import { WebSocketServer }
+// from 'ws'` would force every NestJS consumer to install `ws` even when
+// they don't use speech — and crash with `ERR_MODULE_NOT_FOUND` at startup
+// if they don't.
+//
+// We use a plain dynamic `import('ws')` inside a try/catch:
+// - In ESM dist: native dynamic import — Node resolves `ws` only at the
+//   moment `attachWebSockets` is called.
+// - In CJS dist: TypeScript lowers `import('ws')` to a Promise wrapper around
+//   `require('ws')` — same lazy semantics.
+// - Bundlers that bundle the server (esbuild / webpack for serverless deploys)
+//   will still see `ws` as a referenced module. If your deployment bundles,
+//   either install `ws` unconditionally, or mark it as an external in your
+//   bundler config (esbuild `--external:ws`, webpack `externals: { ws: 'commonjs ws' }`).
+//   Standard NestJS deployments don't bundle and are unaffected.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadWs = loadWs;
+let cached;
+async function loadWs() {
+    if (cached)
+        return cached;
+    let mod;
+    try {
+        mod = await Promise.resolve().then(() => __importStar(require('ws')));
+    }
+    catch (err) {
+        throw new Error("[glirastes] The 'ws' package is required for the speech-to-text feature " +
+            '(AiChatModule.attachWebSockets). Install it with: npm install ws', { cause: err });
+    }
+    cached = {
+        WebSocketServer: mod.WebSocketServer ?? mod.default?.WebSocketServer,
+        WebSocket: mod.default ?? mod.WebSocket,
+    };
+    return cached;
+}

package/dist/cjs/server/adapters/nestjs/decorators/ai-module.decorator.d.ts

@@ -0,0 +1,6 @@
+import 'reflect-metadata';
+import type { AiModuleOptions } from '../metadata.js';
+/**
+ * Class decorator that marks a NestJS controller as an AI intent module.
+ */
+export declare function AiModule(options: AiModuleOptions): ClassDecorator;

package/dist/cjs/server/adapters/nestjs/decorators/ai-module.decorator.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AiModule = AiModule;
+require("reflect-metadata");
+const constants_js_1 = require("./constants.js");
+/**
+ * Class decorator that marks a NestJS controller as an AI intent module.
+ */
+function AiModule(options) {
+    return (target) => {
+        Reflect.defineMetadata(constants_js_1.AI_MODULE_METADATA, options, target);
+    };
+}

package/dist/cjs/server/adapters/nestjs/decorators/ai-param.decorator.d.ts

@@ -0,0 +1,5 @@
+import 'reflect-metadata';
+/**
+ * Property decorator that adds an AI-readable description to a DTO property.
+ */
+export declare function AiParam(description: string): PropertyDecorator;

package/dist/cjs/server/adapters/nestjs/decorators/ai-param.decorator.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AiParam = AiParam;
+require("reflect-metadata");
+const constants_js_1 = require("./constants.js");
+/**
+ * Property decorator that adds an AI-readable description to a DTO property.
+ */
+function AiParam(description) {
+    return (target, propertyKey) => {
+        const existing = Reflect.getMetadata(constants_js_1.AI_PARAM_METADATA, target.constructor) ?? [];
+        existing.push({ propertyKey: String(propertyKey), description });
+        Reflect.defineMetadata(constants_js_1.AI_PARAM_METADATA, existing, target.constructor);
+    };
+}

package/dist/cjs/server/adapters/nestjs/decorators/ai-tool.decorator.d.ts

@@ -0,0 +1,6 @@
+import 'reflect-metadata';
+import type { AiToolOptions } from '../metadata.js';
+/**
+ * Method decorator that exposes a controller method as an AI tool.
+ */
+export declare function AiTool(options: AiToolOptions): MethodDecorator;

package/dist/cjs/server/adapters/nestjs/decorators/ai-tool.decorator.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AiTool = AiTool;
+require("reflect-metadata");
+const constants_js_1 = require("./constants.js");
+/**
+ * Method decorator that exposes a controller method as an AI tool.
+ */
+function AiTool(options) {
+    return (target, propertyKey, _descriptor) => {
+        const methodName = String(propertyKey);
+        const meta = { ...options, methodName };
+        // Store per-method metadata
+        Reflect.defineMetadata(constants_js_1.AI_TOOL_METADATA, meta, target, propertyKey);
+        // Maintain array of decorated method names on the class
+        const existingTools = Reflect.getMetadata(constants_js_1.AI_TOOL_METHODS_METADATA, target.constructor) ?? [];
+        if (!existingTools.includes(methodName)) {
+            existingTools.push(methodName);
+        }
+        Reflect.defineMetadata(constants_js_1.AI_TOOL_METHODS_METADATA, existingTools, target.constructor);
+    };
+}

package/dist/cjs/server/adapters/nestjs/decorators/constants.d.ts

@@ -0,0 +1,4 @@
+export declare const AI_MODULE_METADATA: unique symbol;
+export declare const AI_TOOL_METADATA: unique symbol;
+export declare const AI_TOOL_METHODS_METADATA: unique symbol;
+export declare const AI_PARAM_METADATA: unique symbol;

package/dist/cjs/server/adapters/nestjs/decorators/constants.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AI_PARAM_METADATA = exports.AI_TOOL_METHODS_METADATA = exports.AI_TOOL_METADATA = exports.AI_MODULE_METADATA = void 0;
+exports.AI_MODULE_METADATA = Symbol('AI_MODULE_METADATA');
+exports.AI_TOOL_METADATA = Symbol('AI_TOOL_METADATA');
+exports.AI_TOOL_METHODS_METADATA = Symbol('AI_TOOL_METHODS_METADATA');
+exports.AI_PARAM_METADATA = Symbol('AI_PARAM_METADATA');

package/dist/cjs/server/adapters/nestjs/index.d.ts

@@ -0,0 +1,14 @@
+export { AiModule } from './decorators/ai-module.decorator.js';
+export { AiTool } from './decorators/ai-tool.decorator.js';
+export { AiParam } from './decorators/ai-param.decorator.js';
+export { getAiModuleMeta, getAiToolMeta, getAllAiToolNames, getAllAiTools, getAiParamMeta, } from './metadata.js';
+export type { AiModuleOptions, AiToolOptions, AiModuleMeta, AiToolMeta, AiParamDescription, } from './metadata.js';
+export { AiToolsExplorerService } from './module/ai-tools-explorer.service.js';
+export { AiToolsService } from './module/ai-tools.service.js';
+export { createAiToolsProviders, type AiToolsModuleOptions, } from './module/ai-tools.module.js';
+export { scanNestJsControllers, type NestJsScanOptions, type NestJsScanResult, } from './scanner/nestjs-scanner.js';
+export { buildZodSchemaFromDto, hasAiRelevantMeta, extractRouteParams } from './scanner/schema-builder.js';
+export { applyAiExtensions } from './swagger.js';
+export { AiChatModule } from './chat/ai-chat.module.js';
+export type { AiChatModuleOptions, AiChatModuleAsyncOptions, AiChatModuleFeatures } from './chat/ai-chat-module-options.interface.js';
+export { AiChatRequestDto, ChatMessageDto, ChatMessagePartDto } from './chat/dto/index.js';

package/dist/cjs/server/adapters/nestjs/index.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChatMessagePartDto = exports.ChatMessageDto = exports.AiChatRequestDto = exports.AiChatModule = exports.applyAiExtensions = exports.extractRouteParams = exports.hasAiRelevantMeta = exports.buildZodSchemaFromDto = exports.scanNestJsControllers = exports.createAiToolsProviders = exports.AiToolsService = exports.AiToolsExplorerService = exports.getAiParamMeta = exports.getAllAiTools = exports.getAllAiToolNames = exports.getAiToolMeta = exports.getAiModuleMeta = exports.AiParam = exports.AiTool = exports.AiModule = void 0;
+// Decorators
+var ai_module_decorator_js_1 = require("./decorators/ai-module.decorator.js");
+Object.defineProperty(exports, "AiModule", { enumerable: true, get: function () { return ai_module_decorator_js_1.AiModule; } });
+var ai_tool_decorator_js_1 = require("./decorators/ai-tool.decorator.js");
+Object.defineProperty(exports, "AiTool", { enumerable: true, get: function () { return ai_tool_decorator_js_1.AiTool; } });
+var ai_param_decorator_js_1 = require("./decorators/ai-param.decorator.js");
+Object.defineProperty(exports, "AiParam", { enumerable: true, get: function () { return ai_param_decorator_js_1.AiParam; } });
+// Metadata readers
+var metadata_js_1 = require("./metadata.js");
+Object.defineProperty(exports, "getAiModuleMeta", { enumerable: true, get: function () { return metadata_js_1.getAiModuleMeta; } });
+Object.defineProperty(exports, "getAiToolMeta", { enumerable: true, get: function () { return metadata_js_1.getAiToolMeta; } });
+Object.defineProperty(exports, "getAllAiToolNames", { enumerable: true, get: function () { return metadata_js_1.getAllAiToolNames; } });
+Object.defineProperty(exports, "getAllAiTools", { enumerable: true, get: function () { return metadata_js_1.getAllAiTools; } });
+Object.defineProperty(exports, "getAiParamMeta", { enumerable: true, get: function () { return metadata_js_1.getAiParamMeta; } });
+// Module (DI)
+var ai_tools_explorer_service_js_1 = require("./module/ai-tools-explorer.service.js");
+Object.defineProperty(exports, "AiToolsExplorerService", { enumerable: true, get: function () { return ai_tools_explorer_service_js_1.AiToolsExplorerService; } });
+var ai_tools_service_js_1 = require("./module/ai-tools.service.js");
+Object.defineProperty(exports, "AiToolsService", { enumerable: true, get: function () { return ai_tools_service_js_1.AiToolsService; } });
+var ai_tools_module_js_1 = require("./module/ai-tools.module.js");
+Object.defineProperty(exports, "createAiToolsProviders", { enumerable: true, get: function () { return ai_tools_module_js_1.createAiToolsProviders; } });
+// Build-time scanner
+var nestjs_scanner_js_1 = require("./scanner/nestjs-scanner.js");
+Object.defineProperty(exports, "scanNestJsControllers", { enumerable: true, get: function () { return nestjs_scanner_js_1.scanNestJsControllers; } });
+// Schema builder
+var schema_builder_js_1 = require("./scanner/schema-builder.js");
+Object.defineProperty(exports, "buildZodSchemaFromDto", { enumerable: true, get: function () { return schema_builder_js_1.buildZodSchemaFromDto; } });
+Object.defineProperty(exports, "hasAiRelevantMeta", { enumerable: true, get: function () { return schema_builder_js_1.hasAiRelevantMeta; } });
+Object.defineProperty(exports, "extractRouteParams", { enumerable: true, get: function () { return schema_builder_js_1.extractRouteParams; } });
+// Swagger / OpenAPI
+var swagger_js_1 = require("./swagger.js");
+Object.defineProperty(exports, "applyAiExtensions", { enumerable: true, get: function () { return swagger_js_1.applyAiExtensions; } });
+// Chat module
+var ai_chat_module_js_1 = require("./chat/ai-chat.module.js");
+Object.defineProperty(exports, "AiChatModule", { enumerable: true, get: function () { return ai_chat_module_js_1.AiChatModule; } });
+var index_js_1 = require("./chat/dto/index.js");
+Object.defineProperty(exports, "AiChatRequestDto", { enumerable: true, get: function () { return index_js_1.AiChatRequestDto; } });
+Object.defineProperty(exports, "ChatMessageDto", { enumerable: true, get: function () { return index_js_1.ChatMessageDto; } });
+Object.defineProperty(exports, "ChatMessagePartDto", { enumerable: true, get: function () { return index_js_1.ChatMessagePartDto; } });

package/dist/cjs/server/adapters/nestjs/metadata.d.ts

@@ -0,0 +1,39 @@
+import 'reflect-metadata';
+import type { ModuleClassificationConfig, ModuleExecutionConfig, EndpointMethod, UiActionTemplate, UiPattern } from '../../../types.js';
+import type { z } from 'zod';
+export interface AiModuleOptions {
+    intent: string;
+    classification: ModuleClassificationConfig;
+    execution?: Partial<ModuleExecutionConfig>;
+    systemPrompt?: string;
+}
+export interface AiToolOptions {
+    name: string;
+    description: string;
+    needsApproval?: boolean;
+    sharedWith?: string[];
+    uiActionOnSuccess?: UiActionTemplate;
+    uiPattern?: UiPattern;
+    method?: EndpointMethod;
+    path?: string;
+    /**
+     * Optional Zod schema describing the tool's response shape.
+     * When provided, a compact description is auto-appended to the tool description.
+     */
+    outputSchema?: z.ZodTypeAny;
+}
+export interface AiParamDescription {
+    propertyKey: string;
+    description: string;
+}
+export type AiModuleMeta = AiModuleOptions;
+export interface AiToolMeta extends AiToolOptions {
+    methodName: string;
+}
+export declare function getAiModuleMeta(controllerClass: Function): AiModuleMeta | undefined;
+export declare function getAiToolMeta(controllerClass: Function, methodName: string): AiToolMeta | undefined;
+export declare function getAllAiToolNames(controllerClass: Function): string[];
+export declare function getAllAiTools(controllerClass: Function): Array<AiToolMeta & {
+    module?: string;
+}>;
+export declare function getAiParamMeta(dtoClass: Function): AiParamDescription[];

package/dist/cjs/server/adapters/nestjs/metadata.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getAiModuleMeta = getAiModuleMeta;
+exports.getAiToolMeta = getAiToolMeta;
+exports.getAllAiToolNames = getAllAiToolNames;
+exports.getAllAiTools = getAllAiTools;
+exports.getAiParamMeta = getAiParamMeta;
+require("reflect-metadata");
+const constants_js_1 = require("./decorators/constants.js");
+// ---------------------------------------------------------------------------
+// Metadata readers
+// ---------------------------------------------------------------------------
+function getAiModuleMeta(controllerClass) {
+    return Reflect.getMetadata(constants_js_1.AI_MODULE_METADATA, controllerClass);
+}
+function getAiToolMeta(controllerClass, methodName) {
+    return Reflect.getMetadata(constants_js_1.AI_TOOL_METADATA, controllerClass.prototype, methodName);
+}
+function getAllAiToolNames(controllerClass) {
+    return (Reflect.getMetadata(constants_js_1.AI_TOOL_METHODS_METADATA, controllerClass) ?? []);
+}
+function getAllAiTools(controllerClass) {
+    const moduleMeta = getAiModuleMeta(controllerClass);
+    const toolNames = getAllAiToolNames(controllerClass);
+    return toolNames
+        .map((methodName) => {
+        const toolMeta = getAiToolMeta(controllerClass, methodName);
+        if (!toolMeta)
+            return null;
+        return { ...toolMeta, module: moduleMeta?.intent };
+    })
+        .filter((t) => t !== null);
+}
+function getAiParamMeta(dtoClass) {
+    return Reflect.getMetadata(constants_js_1.AI_PARAM_METADATA, dtoClass) ?? [];
+}

package/dist/cjs/server/adapters/nestjs/module/ai-tools-explorer.service.d.ts

@@ -0,0 +1,36 @@
+import 'reflect-metadata';
+import type { AiEndpointToolDefinition, IntentModule } from '../../../../types.js';
+import { type AiModuleMeta, type AiToolMeta } from '../metadata.js';
+interface DiscoveredController {
+    controllerClass: Function;
+    moduleMeta: AiModuleMeta;
+    tools: Array<AiToolMeta & {
+        module: string;
+    }>;
+}
+/**
+ * Discovers AI-decorated controllers at runtime using NestJS DiscoveryService.
+ * Injectable as a NestJS provider.
+ */
+export declare class AiToolsExplorerService {
+    private readonly discoveryService;
+    private readonly reflector;
+    private readonly options?;
+    private readonly discovered;
+    private readonly endpointToolDefs;
+    private readonly intentModules;
+    constructor(discoveryService: unknown, reflector: unknown, options?: {
+        controllers?: Function[];
+    } | undefined);
+    /**
+     * Called during module initialization to scan all controllers.
+     */
+    explore(): void;
+    private scanControllers;
+    private buildToolDefinitions;
+    private buildIntentModules;
+    getEndpointToolDefinitions(): ReadonlyArray<AiEndpointToolDefinition>;
+    getIntentModules(): ReadonlyMap<string, IntentModule>;
+    getDiscoveredControllers(): ReadonlyArray<DiscoveredController>;
+}
+export {};

package/dist/cjs/server/adapters/nestjs/module/ai-tools-explorer.service.js

@@ -0,0 +1,159 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AiToolsExplorerService = void 0;
+require("reflect-metadata");
+const zod_1 = require("zod");
+const metadata_js_1 = require("../metadata.js");
+const schema_builder_js_1 = require("../scanner/schema-builder.js");
+const HTTP_METHOD_MAP = {
+    0: 'GET',
+    1: 'POST',
+    2: 'PUT',
+    3: 'DELETE',
+    4: 'PATCH',
+};
+/**
+ * Discovers AI-decorated controllers at runtime using NestJS DiscoveryService.
+ * Injectable as a NestJS provider.
+ */
+class AiToolsExplorerService {
+    discoveryService;
+    reflector;
+    options;
+    discovered = [];
+    endpointToolDefs = [];
+    intentModules = new Map();
+    constructor(discoveryService, reflector, options) {
+        this.discoveryService = discoveryService;
+        this.reflector = reflector;
+        this.options = options;
+    }
+    /**
+     * Called during module initialization to scan all controllers.
+     */
+    explore() {
+        this.scanControllers();
+        this.buildToolDefinitions();
+        this.buildIntentModules();
+    }
+    scanControllers() {
+        const ds = this.discoveryService;
+        const controllers = ds.getControllers();
+        for (const wrapper of controllers) {
+            const controllerClass = wrapper.metatype;
+            if (!controllerClass)
+                continue;
+            const moduleMeta = (0, metadata_js_1.getAiModuleMeta)(controllerClass);
+            if (!moduleMeta)
+                continue;
+            if (this.options?.controllers &&
+                !this.options.controllers.includes(controllerClass)) {
+                continue;
+            }
+            const tools = (0, metadata_js_1.getAllAiTools)(controllerClass);
+            this.discovered.push({
+                controllerClass,
+                moduleMeta,
+                tools: tools.map((t) => ({
+                    ...t,
+                    module: t.module ?? moduleMeta.intent,
+                })),
+            });
+        }
+    }
+    buildToolDefinitions() {
+        const ref = this.reflector;
+        for (const ctrl of this.discovered) {
+            const controllerPath = ref.get('path', ctrl.controllerClass) ?? '';
+            for (const tool of ctrl.tools) {
+                const httpMethodNum = ref.get('method', ctrl.controllerClass.prototype[tool.methodName]);
+                const httpMethod = tool.method ??
+                    HTTP_METHOD_MAP[httpMethodNum ?? 0] ??
+                    'GET';
+                const methodPath = ref.get('path', ctrl.controllerClass.prototype[tool.methodName]) ?? '';
+                const fullPath = `/api/${controllerPath}/${methodPath}`
+                    .replace(/\/+/g, '/')
+                    .replace(/\/$/, '') || '/';
+                // Resolve DTO
+                const paramTypes = Reflect.getMetadata('design:paramtypes', ctrl.controllerClass.prototype, tool.methodName);
+                let inputSchema = zod_1.z.object({});
+                if (paramTypes) {
+                    for (const pt of paramTypes) {
+                        if (pt && typeof pt === 'function' && (0, schema_builder_js_1.hasAiRelevantMeta)(pt)) {
+                            inputSchema = (0, schema_builder_js_1.buildZodSchemaFromDto)(pt);
+                            break;
+                        }
+                    }
+                }
+                // Merge path parameters into input schema
+                const pathParams = (0, schema_builder_js_1.extractRouteParams)(ctrl.controllerClass, tool.methodName);
+                if (pathParams.length > 0) {
+                    const pathShape = {};
+                    for (const paramName of pathParams) {
+                        if (!(inputSchema instanceof zod_1.z.ZodObject) || !(paramName in inputSchema.shape)) {
+                            pathShape[paramName] = zod_1.z.string().uuid().describe(`Path parameter: ${paramName}`);
+                        }
+                    }
+                    if (Object.keys(pathShape).length > 0) {
+                        inputSchema = inputSchema instanceof zod_1.z.ZodObject
+                            ? inputSchema.extend(pathShape)
+                            : zod_1.z.object(pathShape);
+                    }
+                }
+                this.endpointToolDefs.push({
+                    id: `${ctrl.moduleMeta.intent}.${tool.name}`,
+                    toolName: tool.name,
+                    module: tool.module,
+                    sharedWith: tool.sharedWith,
+                    description: tool.description,
+                    method: httpMethod,
+                    path: fullPath,
+                    inputSchema,
+                    outputSchema: tool.outputSchema,
+                    needsApproval: tool.needsApproval,
+                    uiActionOnSuccess: tool.uiActionOnSuccess,
+                    uiPattern: tool.uiPattern,
+                });
+            }
+        }
+    }
+    buildIntentModules() {
+        for (const ctrl of this.discovered) {
+            const intent = ctrl.moduleMeta.intent;
+            const toolNames = ctrl.tools.map((t) => t.name);
+            const existing = this.intentModules.get(intent);
+            if (existing) {
+                existing.toolNames.push(...toolNames);
+            }
+            else {
+                const meta = {
+                    classification: ctrl.moduleMeta.classification,
+                    execution: ctrl.moduleMeta.execution,
+                    systemPrompt: ctrl.moduleMeta.systemPrompt,
+                };
+                this.intentModules.set(intent, { type: intent, toolNames, meta });
+            }
+        }
+        // Expand sharedWith
+        for (const def of this.endpointToolDefs) {
+            if (!def.sharedWith)
+                continue;
+            for (const sharedModule of def.sharedWith) {
+                const mod = this.intentModules.get(sharedModule);
+                if (mod && !mod.toolNames.includes(def.toolName)) {
+                    mod.toolNames.push(def.toolName);
+                }
+            }
+        }
+    }
+    getEndpointToolDefinitions() {
+        return this.endpointToolDefs;
+    }
+    getIntentModules() {
+        return this.intentModules;
+    }
+    getDiscoveredControllers() {
+        return this.discovered;
+    }
+}
+exports.AiToolsExplorerService = AiToolsExplorerService;

package/dist/cjs/server/adapters/nestjs/module/ai-tools.module.d.ts

@@ -0,0 +1,37 @@
+import { AiToolsExplorerService } from './ai-tools-explorer.service.js';
+import { AiToolsService } from './ai-tools.service.js';
+export interface AiToolsModuleOptions {
+    controllers?: Function[];
+    global?: boolean;
+}
+/**
+ * Configuration factory for NestJS module registration.
+ *
+ * Usage in a NestJS module:
+ * ```ts
+ * import { Module } from '@nestjs/common';
+ * import { DiscoveryModule, DiscoveryService, Reflector } from '@nestjs/core';
+ * import { createAiToolsProviders } from '../index.js';
+ *
+ * @Module({
+ *   imports: [DiscoveryModule],
+ *   providers: [...createAiToolsProviders()],
+ *   exports: [AiToolsService],
+ * })
+ * export class AiToolsModule {}
+ * ```
+ */
+export declare function createAiToolsProviders(options?: AiToolsModuleOptions): {
+    options: AiToolsModuleOptions;
+    ExplorerService: typeof AiToolsExplorerService;
+    ToolsService: typeof AiToolsService;
+    /**
+     * Factory function to create the explorer service with NestJS DI.
+     * Call this in a custom provider factory.
+     */
+    createExplorer(discoveryService: unknown, reflector: unknown): AiToolsExplorerService;
+    /**
+     * Factory function to create the tools service.
+     */
+    createService(explorer: AiToolsExplorerService): AiToolsService;
+};

package/dist/cjs/server/adapters/nestjs/module/ai-tools.module.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAiToolsProviders = createAiToolsProviders;
+const ai_tools_explorer_service_js_1 = require("./ai-tools-explorer.service.js");
+const ai_tools_service_js_1 = require("./ai-tools.service.js");
+/**
+ * Configuration factory for NestJS module registration.
+ *
+ * Usage in a NestJS module:
+ * ```ts
+ * import { Module } from '@nestjs/common';
+ * import { DiscoveryModule, DiscoveryService, Reflector } from '@nestjs/core';
+ * import { createAiToolsProviders } from '../index.js';
+ *
+ * @Module({
+ *   imports: [DiscoveryModule],
+ *   providers: [...createAiToolsProviders()],
+ *   exports: [AiToolsService],
+ * })
+ * export class AiToolsModule {}
+ * ```
+ */
+function createAiToolsProviders(options) {
+    return {
+        options: options ?? {},
+        ExplorerService: ai_tools_explorer_service_js_1.AiToolsExplorerService,
+        ToolsService: ai_tools_service_js_1.AiToolsService,
+        /**
+         * Factory function to create the explorer service with NestJS DI.
+         * Call this in a custom provider factory.
+         */
+        createExplorer(discoveryService, reflector) {
+            const explorer = new ai_tools_explorer_service_js_1.AiToolsExplorerService(discoveryService, reflector, options);
+            explorer.explore();
+            return explorer;
+        },
+        /**
+         * Factory function to create the tools service.
+         */
+        createService(explorer) {
+            return new ai_tools_service_js_1.AiToolsService(explorer);
+        },
+    };
+}

package/dist/cjs/server/adapters/nestjs/module/ai-tools.service.d.ts

@@ -0,0 +1,28 @@
+import type { AiEndpointToolDefinition, IntentModule, ToolContext, ToolRegistry } from '../../../../types.js';
+import { type ToolToAiToolOptions } from '../../../core/index.js';
+import type { AiToolsExplorerService } from './ai-tools-explorer.service.js';
+/**
+ * Injectable service for accessing AI tool definitions at runtime.
+ */
+export declare class AiToolsService {
+    private readonly explorer;
+    constructor(explorer: AiToolsExplorerService);
+    getEndpointTools(): ReadonlyArray<AiEndpointToolDefinition>;
+    getIntentModules(): ReadonlyMap<string, IntentModule>;
+    getToolsForIntent(intent: string): AiEndpointToolDefinition[];
+    buildToolRegistry(): ToolRegistry;
+    buildAiTools(context: ToolContext, options?: ToolToAiToolOptions): Promise<Record<string, {
+        _toolId: string;
+        description: string;
+        parameters: import("zod").ZodType<any, import("zod").ZodTypeDef, any>;
+        needsApproval: ((input: unknown) => Promise<boolean>) | undefined;
+        execute: (input: unknown) => Promise<unknown>;
+    }>>;
+    buildAiToolsForIntent(intent: string, context: ToolContext, options?: ToolToAiToolOptions): Promise<Record<string, {
+        _toolId: string;
+        description: string;
+        parameters: import("zod").ZodType<any, import("zod").ZodTypeDef, any>;
+        needsApproval: ((input: unknown) => Promise<boolean>) | undefined;
+        execute: (input: unknown) => Promise<unknown>;
+    }>>;
+}

package/dist/cjs/server/adapters/nestjs/module/ai-tools.service.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AiToolsService = void 0;
+const index_js_1 = require("../../../core/index.js");
+/**
+ * Injectable service for accessing AI tool definitions at runtime.
+ */
+class AiToolsService {
+    explorer;
+    constructor(explorer) {
+        this.explorer = explorer;
+    }
+    getEndpointTools() {
+        return this.explorer.getEndpointToolDefinitions();
+    }
+    getIntentModules() {
+        return this.explorer.getIntentModules();
+    }
+    getToolsForIntent(intent) {
+        const mod = this.explorer.getIntentModules().get(intent);
+        if (!mod)
+            return [];
+        const toolNameSet = new Set(mod.toolNames);
+        return this.explorer
+            .getEndpointToolDefinitions()
+            .filter((t) => toolNameSet.has(t.toolName));
+    }
+    buildToolRegistry() {
+        return (0, index_js_1.endpointToolsToRegistry)(this.explorer.getEndpointToolDefinitions());
+    }
+    async buildAiTools(context, options) {
+        const registry = this.buildToolRegistry();
+        return (0, index_js_1.toolsToAiTools)(registry, context, options);
+    }
+    async buildAiToolsForIntent(intent, context, options) {
+        const tools = this.getToolsForIntent(intent);
+        const registry = (0, index_js_1.endpointToolsToRegistry)(tools);
+        return (0, index_js_1.toolsToAiTools)(registry, context, options);
+    }
+}
+exports.AiToolsService = AiToolsService;