@frontmcp/sdk 0.2.5 → 0.3.0

package/src/tool/flows/tools-list.flow.js

@@ -0,0 +1,149 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+// tools/flows/list-tools.flow.ts
+const common_1 = require("../../common");
+require("reflect-metadata");
+const zod_1 = require("zod");
+const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+const zod_to_json_schema_1 = require("zod-to-json-schema");
+const inputSchema = zod_1.z.object({
+    request: types_js_1.ListToolsRequestSchema,
+    ctx: zod_1.z.any(),
+});
+const outputSchema = types_js_1.ListToolsResultSchema;
+const stateSchema = zod_1.z.object({
+    cursor: zod_1.z.string().optional(),
+    tools: zod_1.z.array(zod_1.z.object({
+        appName: zod_1.z.string(),
+        tool: zod_1.z.instanceof(common_1.ToolEntry),
+    })),
+    resolvedTools: zod_1.z.array(zod_1.z.object({
+        appName: zod_1.z.string(),
+        tool: zod_1.z.instanceof(common_1.ToolEntry),
+        finalName: zod_1.z.string(),
+    })),
+});
+// TODO: add support for pagination
+// TODO: add support for session based tools
+const plan = {
+    pre: ['parseInput'],
+    execute: ['findTools', 'resolveConflicts'],
+    post: ['parseTools'],
+};
+const name = 'tools:list-tools';
+const { Stage } = (0, common_1.FlowHooksOf)('tools:list-tools');
+let ToolsListFlow = class ToolsListFlow extends common_1.FlowBase {
+    logger = this.scopeLogger.child('ToolsListFlow');
+    sample(arr, n = 5) {
+        return arr.slice(0, n);
+    }
+    async parseInput() {
+        this.logger.verbose('parseInput:start');
+        const { request: { method, params }, } = inputSchema.parse(this.rawInput);
+        if (method !== 'tools/list') {
+            this.logger.warn(`parseInput: invalid method "${method}"`);
+            throw new Error('Invalid method');
+        }
+        const cursor = params?.cursor;
+        if (cursor)
+            this.logger.verbose(`parseInput: cursor=${cursor}`);
+        this.state.set('cursor', cursor);
+        this.logger.verbose('parseInput:done');
+    }
+    async findTools() {
+        this.logger.info('findTools:start');
+        const apps = this.scope.apps.getApps();
+        this.logger.info(`findTools: discovered ${apps.length} app(s)`);
+        const tools = [];
+        const scopeTools = this.scope.tools.getTools();
+        this.logger.verbose(`findTools: scope tools=${scopeTools.length}`);
+        for (const tool of scopeTools) {
+            tools.push({ appName: tool.owner.id, tool });
+        }
+        this.logger.info(`findTools: total tools collected=${tools.length}`);
+        if (tools.length === 0) {
+            this.logger.warn('findTools: no tools found across apps');
+        }
+        this.state.set('tools', tools);
+        this.logger.verbose('findTools:done');
+    }
+    async resolveConflicts() {
+        this.logger.verbose('resolveConflicts:start');
+        const found = this.state.required.tools;
+        const counts = new Map();
+        for (const { tool } of found) {
+            const baseName = tool.metadata.id ?? tool.metadata.name;
+            counts.set(baseName, (counts.get(baseName) ?? 0) + 1);
+        }
+        const conflicts = new Set([...counts.entries()].filter(([, n]) => n > 1).map(([k]) => k));
+        if (conflicts.size > 0) {
+            const preview = this.sample(Array.from(conflicts)).join(', ');
+            const extra = conflicts.size > 5 ? `, +${conflicts.size - 5} more` : '';
+            this.logger.warn(`resolveConflicts: ${conflicts.size} name conflict(s) detected: ${preview}${extra}`);
+        }
+        else {
+            this.logger.info('resolveConflicts: no name conflicts detected');
+        }
+        const resolved = found.map(({ appName, tool }) => {
+            const baseName = tool.metadata.id ?? tool.metadata.name;
+            const finalName = conflicts.has(baseName) ? `${appName}:${baseName}` : baseName;
+            return { appName, tool, finalName };
+        });
+        this.state.set('resolvedTools', resolved);
+        this.logger.verbose('resolveConflicts:done');
+    }
+    async parseTools() {
+        this.logger.verbose('parseTools:start');
+        const resolved = this.state.required.resolvedTools;
+        const tools = resolved.map(({ finalName, tool }) => ({
+            name: finalName,
+            title: tool.metadata.name,
+            description: tool.metadata.description,
+            annotations: tool.metadata.annotations,
+            inputSchema: tool.metadata.rawInputSchema ??
+                (0, zod_to_json_schema_1.zodToJsonSchema)(zod_1.z.object(tool.metadata.inputSchema)),
+        }));
+        const preview = this.sample(tools.map(t => t.name)).join(', ');
+        const extra = tools.length > 5 ? `, +${tools.length - 5} more` : '';
+        this.logger.info(`parseTools: prepared ${tools.length} tool descriptor(s): ${preview}${extra}`);
+        this.respond({ tools });
+        this.logger.info('parseTools: response sent');
+        this.logger.verbose('parseTools:done');
+    }
+};
+tslib_1.__decorate([
+    Stage('parseInput'),
+    tslib_1.__metadata("design:type", Function),
+    tslib_1.__metadata("design:paramtypes", []),
+    tslib_1.__metadata("design:returntype", Promise)
+], ToolsListFlow.prototype, "parseInput", null);
+tslib_1.__decorate([
+    Stage('findTools'),
+    tslib_1.__metadata("design:type", Function),
+    tslib_1.__metadata("design:paramtypes", []),
+    tslib_1.__metadata("design:returntype", Promise)
+], ToolsListFlow.prototype, "findTools", null);
+tslib_1.__decorate([
+    Stage('resolveConflicts'),
+    tslib_1.__metadata("design:type", Function),
+    tslib_1.__metadata("design:paramtypes", []),
+    tslib_1.__metadata("design:returntype", Promise)
+], ToolsListFlow.prototype, "resolveConflicts", null);
+tslib_1.__decorate([
+    Stage('parseTools'),
+    tslib_1.__metadata("design:type", Function),
+    tslib_1.__metadata("design:paramtypes", []),
+    tslib_1.__metadata("design:returntype", Promise)
+], ToolsListFlow.prototype, "parseTools", null);
+ToolsListFlow = tslib_1.__decorate([
+    (0, common_1.Flow)({
+        name,
+        plan,
+        inputSchema,
+        outputSchema,
+        access: 'authorized',
+    })
+], ToolsListFlow);
+exports.default = ToolsListFlow;
+//# sourceMappingURL=tools-list.flow.js.map

package/src/tool/flows/tools-list.flow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools-list.flow.js","sourceRoot":"","sources":["../../../../src/tool/flows/tools-list.flow.ts"],"names":[],"mappings":"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","sourcesContent":["// tools/flows/list-tools.flow.ts\nimport {Flow, FlowBase, FlowHooksOf, FlowPlan, FlowRunOptions, ToolEntry} from '../../common';\nimport 'reflect-metadata';\nimport {z} from 'zod';\nimport {ListToolsRequestSchema, ListToolsResultSchema} from '@modelcontextprotocol/sdk/types.js';\nimport {zodToJsonSchema} from 'zod-to-json-schema';\n\nconst inputSchema = z.object({\n  request: ListToolsRequestSchema,\n  ctx: z.any(),\n});\n\nconst outputSchema = ListToolsResultSchema;\n\nconst stateSchema = z.object({\n  cursor: z.string().optional(),\n  tools: z.array(\n    z.object({\n      appName: z.string(),\n      tool: z.instanceof(ToolEntry),\n    })\n  ),\n  resolvedTools: z.array(\n    z.object({\n      appName: z.string(),\n      tool: z.instanceof(ToolEntry),\n      finalName: z.string(),\n    })\n  ),\n});\n\ntype ResponseToolItem = z.infer<typeof outputSchema>['tools'][number];\n\n// TODO: add support for pagination\n// TODO: add support for session based tools\nconst plan = {\n  pre: ['parseInput'],\n  execute: ['findTools', 'resolveConflicts'],\n  post: ['parseTools'],\n} as const satisfies FlowPlan<string>;\n\ndeclare global {\n    interface ExtendFlows {\n      'tools:list-tools': FlowRunOptions<\n        ToolsListFlow,\n        typeof plan,\n        typeof inputSchema,\n        typeof outputSchema,\n        typeof stateSchema\n      >;\n    }\n}\n\nconst name = 'tools:list-tools' as const;\nconst {Stage} = FlowHooksOf('tools:list-tools');\n\n@Flow({\n  name,\n  plan,\n  inputSchema,\n  outputSchema,\n  access: 'authorized',\n})\nexport default class ToolsListFlow extends FlowBase<typeof name> {\n  logger = this.scopeLogger.child('ToolsListFlow');\n\n  private sample<T>(arr: T[], n = 5): T[] {\n    return arr.slice(0, n);\n  }\n\n  @Stage('parseInput')\n  async parseInput() {\n    this.logger.verbose('parseInput:start');\n    const {\n      request: {method, params},\n    } = inputSchema.parse(this.rawInput);\n\n    if (method !== 'tools/list') {\n      this.logger.warn(`parseInput: invalid method \"${method}\"`);\n      throw new Error('Invalid method');\n    }\n\n    const cursor = params?.cursor;\n    if (cursor) this.logger.verbose(`parseInput: cursor=${cursor}`);\n    this.state.set('cursor', cursor);\n    this.logger.verbose('parseInput:done');\n  }\n\n  @Stage('findTools')\n  async findTools() {\n    this.logger.info('findTools:start');\n    const apps = this.scope.apps.getApps();\n    this.logger.info(`findTools: discovered ${apps.length} app(s)`);\n\n    const tools: Array<{ appName: string; tool: ToolEntry }> = [];\n\n    const scopeTools = this.scope.tools.getTools();\n    this.logger.verbose(`findTools: scope tools=${scopeTools.length}`);\n\n    for (const tool of scopeTools) {\n      tools.push({appName: tool.owner.id, tool});\n    }\n    this.logger.info(`findTools: total tools collected=${tools.length}`);\n    if (tools.length === 0) {\n      this.logger.warn('findTools: no tools found across apps');\n    }\n\n    this.state.set('tools', tools);\n    this.logger.verbose('findTools:done');\n  }\n\n  @Stage('resolveConflicts')\n  async resolveConflicts() {\n    this.logger.verbose('resolveConflicts:start');\n    const found = this.state.required.tools;\n\n    const counts = new Map<string, number>();\n    for (const {tool} of found) {\n      const baseName = tool.metadata.id ?? tool.metadata.name;\n      counts.set(baseName, (counts.get(baseName) ?? 0) + 1);\n    }\n\n    const conflicts = new Set<string>(\n      [...counts.entries()].filter(([, n]) => n > 1).map(([k]) => k)\n    );\n\n    if (conflicts.size > 0) {\n      const preview = this.sample(Array.from(conflicts)).join(', ');\n      const extra = conflicts.size > 5 ? `, +${conflicts.size - 5} more` : '';\n      this.logger.warn(`resolveConflicts: ${conflicts.size} name conflict(s) detected: ${preview}${extra}`);\n    } else {\n      this.logger.info('resolveConflicts: no name conflicts detected');\n    }\n\n    const resolved = found.map(({appName, tool}) => {\n      const baseName = tool.metadata.id ?? tool.metadata.name;\n      const finalName = conflicts.has(baseName) ? `${appName}:${baseName}` : baseName;\n      return {appName, tool, finalName};\n    });\n\n    this.state.set('resolvedTools', resolved);\n    this.logger.verbose('resolveConflicts:done');\n  }\n\n  @Stage('parseTools')\n  async parseTools() {\n    this.logger.verbose('parseTools:start');\n    const resolved = this.state.required.resolvedTools;\n\n    const tools: ResponseToolItem[] = resolved.map(({finalName, tool}) => ({\n      name: finalName,\n      title: tool.metadata.name,\n      description: tool.metadata.description,\n      annotations: tool.metadata.annotations,\n      inputSchema:\n        (tool.metadata as any).rawInputSchema ??\n        (zodToJsonSchema(z.object(tool.metadata.inputSchema) as any) as any),\n    }));\n\n    const preview = this.sample(tools.map(t => t.name)).join(', ');\n    const extra = tools.length > 5 ? `, +${tools.length - 5} more` : '';\n    this.logger.info(`parseTools: prepared ${tools.length} tool descriptor(s): ${preview}${extra}`);\n\n    this.respond({tools});\n    this.logger.info('parseTools: response sent');\n    this.logger.verbose('parseTools:done');\n\n  }\n}\n"]}

package/src/tool/tool.events.d.ts

@@ -0,0 +1,17 @@
+import { ToolInstance } from './tool.instance';
+export type ToolChangeKind = 'added' | 'updated' | 'removed' | 'reset';
+export type ToolChangeEvent = {
+    kind: ToolChangeKind;
+    scope: 'global' | 'session';
+    sessionId?: string;
+    relatedRequestId?: string;
+    version: number;
+    snapshot: readonly ToolInstance[];
+};
+type Listener = (e: ToolChangeEvent) => void;
+export declare class ToolEmitter {
+    private listeners;
+    on(l: Listener): () => void;
+    emit(e: ToolChangeEvent): void;
+}
+export {};

package/src/tool/tool.events.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ToolEmitter = void 0;
+class ToolEmitter {
+    listeners = new Set();
+    on(l) {
+        this.listeners.add(l);
+        return () => this.listeners.delete(l);
+    }
+    emit(e) {
+        for (const l of [...this.listeners])
+            l(e);
+    }
+}
+exports.ToolEmitter = ToolEmitter;
+//# sourceMappingURL=tool.events.js.map

package/src/tool/tool.events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.events.js","sourceRoot":"","sources":["../../../src/tool/tool.events.ts"],"names":[],"mappings":";;;AAcA,MAAa,WAAW;IACd,SAAS,GAAG,IAAI,GAAG,EAAY,CAAC;IAExC,EAAE,CAAC,CAAW;QACZ,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACtB,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IACxC,CAAC;IAED,IAAI,CAAC,CAAkB;QACrB,KAAK,MAAM,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC;YAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAC5C,CAAC;CACF;AAXD,kCAWC","sourcesContent":["import { ToolInstance } from './tool.instance';\n\nexport type ToolChangeKind = 'added' | 'updated' | 'removed' | 'reset';\nexport type ToolChangeEvent = {\n  kind: ToolChangeKind;\n  scope: 'global' | 'session';\n  sessionId?: string;\n  relatedRequestId?: string;\n  version: number;\n  snapshot: readonly ToolInstance[];\n};\n\ntype Listener = (e: ToolChangeEvent) => void;\n\nexport class ToolEmitter {\n  private listeners = new Set<Listener>();\n\n  on(l: Listener): () => void {\n    this.listeners.add(l);\n    return () => this.listeners.delete(l);\n  }\n\n  emit(e: ToolChangeEvent) {\n    for (const l of [...this.listeners]) l(e);\n  }\n}\n"]}

package/src/tool/tool.instance.d.ts

@@ -0,0 +1,15 @@
+import { EntryOwnerRef, ToolCallArgs, ToolCallExtra, ToolContext, ToolEntry, ToolRecord } from '../common';
+import ProviderRegistry from '../provider/provider.registry';
+import { z } from "zod";
+import HookRegistry from "../hooks/hook.registry";
+import { Scope } from "../scope";
+export declare class ToolInstance<In extends object = any, Out extends object = any> extends ToolEntry<In, Out> {
+    private readonly providers;
+    readonly name: string;
+    readonly scope: Scope;
+    readonly hooks: HookRegistry;
+    constructor(record: ToolRecord, providers: ProviderRegistry, owner: EntryOwnerRef);
+    protected initialize(): Promise<void>;
+    getMetadata(): import("../common").ToolMetadata<z.ZodRawShape, z.ZodRawShape>;
+    create(input: ToolCallArgs, ctx: ToolCallExtra): ToolContext<In, Out>;
+}

package/src/tool/tool.instance.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ToolInstance = void 0;
+const common_1 = require("../common");
+const zod_1 = require("zod");
+const hooks_utils_1 = require("../hooks/hooks.utils");
+class ToolInstance extends common_1.ToolEntry {
+    providers;
+    name;
+    scope;
+    hooks;
+    constructor(record, providers, owner) {
+        super(record);
+        this.owner = owner;
+        this.providers = providers;
+        this.name = record.metadata.id || record.metadata.name;
+        this.scope = this.providers.getActiveScope();
+        this.hooks = this.scope.providers.getHooksRegistry();
+        const schema = record.metadata.inputSchema;
+        this.inputSchema = typeof schema.parse === 'function' ? schema : zod_1.z.object(schema);
+        this.rawInputSchema = record.metadata.rawInputSchema;
+        this.outputSchema = record.metadata.outputSchema ? zod_1.z.object(record.metadata.outputSchema) : zod_1.z.object({}).passthrough();
+        this.ready = this.initialize();
+    }
+    async initialize() {
+        const hooks = (0, hooks_utils_1.normalizeHooksFromCls)(this.record.provide)
+            .filter(hook => hook.metadata.flow === 'tools:call-tool' || hook.metadata.flow === 'tools:list-tools');
+        if (hooks.length > 0) {
+            await this.hooks.registerHooks(true, ...hooks);
+        }
+        return Promise.resolve();
+    }
+    getMetadata() {
+        return this.record.metadata;
+    }
+    create(input, ctx) {
+        const metadata = this.metadata;
+        const providers = this.providers;
+        const scope = this.providers.getActiveScope();
+        const logger = scope.logger;
+        const authInfo = ctx.authInfo;
+        const toolCtorArgs = {
+            metadata,
+            input: input,
+            providers,
+            logger,
+            authInfo,
+        };
+        switch (this.record.kind) {
+            case common_1.ToolKind.CLASS_TOKEN:
+                return new this.record.provide(toolCtorArgs);
+            case common_1.ToolKind.FUNCTION:
+                return new FunctionToolContext(this.record, toolCtorArgs);
+        }
+    }
+}
+exports.ToolInstance = ToolInstance;
+class FunctionToolContext extends common_1.ToolContext {
+    record;
+    constructor(record, args) {
+        super(args);
+        this.record = record;
+    }
+    execute(input) {
+        return this.record.provide(input, this);
+    }
+}
+//# sourceMappingURL=tool.instance.js.map

package/src/tool/tool.instance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.instance.js","sourceRoot":"","sources":["../../../src/tool/tool.instance.ts"],"names":[],"mappings":";;;AAAA,sCAGmB;AAEnB,6BAAsB;AAGtB,sDAA2D;AAG3D,MAAa,YAAgE,SAAQ,kBAAkB;IACpF,SAAS,CAAmB;IACpC,IAAI,CAAS;IACb,KAAK,CAAQ;IACb,KAAK,CAAe;IAE7B,YAAY,MAAkB,EAAE,SAA2B,EAAE,KAAoB;QAC/E,KAAK,CAAC,MAAM,CAAC,CAAC;QACd,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC,QAAQ,CAAC,EAAE,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC;QACvD,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC,cAAc,EAAE,CAAA;QAC5C,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,gBAAgB,EAAE,CAAC;QAErD,MAAM,MAAM,GAAQ,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAA;QAC/C,IAAI,CAAC,WAAW,GAAG,OAAO,MAAM,CAAC,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAClF,IAAI,CAAC,cAAc,GAAG,MAAM,CAAC,QAAQ,CAAC,cAAqB,CAAC;QAC5D,IAAI,CAAC,YAAY,GAAG,MAAM,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC,CAAC,OAAC,CAAC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,OAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;QACvH,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;IACjC,CAAC;IAES,KAAK,CAAC,UAAU;QACxB,MAAM,KAAK,GAAG,IAAA,mCAAqB,EAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC;aACrD,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,KAAK,iBAAiB,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,KAAK,kBAAkB,CAAC,CAAA;QACxG,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACrB,MAAM,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,IAAI,EAAE,GAAG,KAAK,CAAC,CAAA;QAChD,CAAC;QACD,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;IAC3B,CAAC;IAED,WAAW;QACT,OAAO,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC;IAC9B,CAAC;IAEQ,MAAM,CAAC,KAAmB,EAAE,GAAkB;QACrD,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;QAC/B,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;QACjC,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC,cAAc,EAAE,CAAC;QAC9C,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;QAC5B,MAAM,QAAQ,GAAG,GAAG,CAAC,QAAQ,CAAC;QAE9B,MAAM,YAAY,GAAqB;YACrC,QAAQ;YACR,KAAK,EAAE,KAAW;YAClB,SAAS;YACT,MAAM;YACN,QAAQ;SACT,CAAA;QACD,QAAQ,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;YACzB,KAAK,iBAAQ,CAAC,WAAW;gBACvB,OAAO,IAAI,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;YAC/C,KAAK,iBAAQ,CAAC,QAAQ;gBACpB,OAAO,IAAI,mBAAmB,CAAU,IAAI,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;QACvE,CAAC;IACH,CAAC;CACF;AAvDD,oCAuDC;AAED,MAAM,mBAAuE,SAAQ,oBAAoB;IAEpF;IADnB,YACmB,MAA+B,EAChD,IAAsB;QAEtB,KAAK,CAAC,IAAI,CAAC,CAAC;QAHK,WAAM,GAAN,MAAM,CAAyB;IAIlD,CAAC;IAED,OAAO,CAAC,KAAS;QACf,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IAC1C,CAAC;CACF","sourcesContent":["import {\n  EntryOwnerRef, ToolCallArgs, ToolCallExtra, ToolContext,\n  ToolCtorArgs, ToolEntry, ToolFunctionTokenRecord, ToolKind, ToolRecord\n} from '../common';\nimport ProviderRegistry from '../provider/provider.registry';\nimport {z} from \"zod\";\nimport HookRegistry from \"../hooks/hook.registry\";\nimport {Scope} from \"../scope\";\nimport {normalizeHooksFromCls} from \"../hooks/hooks.utils\";\n\n\nexport class ToolInstance<In extends object = any, Out extends object = any> extends ToolEntry<In, Out> {\n  private readonly providers: ProviderRegistry;\n  readonly name: string;\n  readonly scope: Scope;\n  readonly hooks: HookRegistry;\n\n  constructor(record: ToolRecord, providers: ProviderRegistry, owner: EntryOwnerRef) {\n    super(record);\n    this.owner = owner;\n    this.providers = providers;\n    this.name = record.metadata.id || record.metadata.name;\n    this.scope = this.providers.getActiveScope()\n    this.hooks = this.scope.providers.getHooksRegistry();\n\n    const schema: any = record.metadata.inputSchema\n    this.inputSchema = typeof schema.parse === 'function' ? schema : z.object(schema);\n    this.rawInputSchema = record.metadata.rawInputSchema as any;\n    this.outputSchema = record.metadata.outputSchema ? z.object(record.metadata.outputSchema) : z.object({}).passthrough();\n    this.ready = this.initialize();\n  }\n\n  protected async initialize() {\n    const hooks = normalizeHooksFromCls(this.record.provide)\n      .filter(hook => hook.metadata.flow === 'tools:call-tool' || hook.metadata.flow === 'tools:list-tools')\n    if (hooks.length > 0) {\n      await this.hooks.registerHooks(true, ...hooks)\n    }\n    return Promise.resolve();\n  }\n\n  getMetadata() {\n    return this.record.metadata;\n  }\n\n  override create(input: ToolCallArgs, ctx: ToolCallExtra): ToolContext<In, Out> {\n    const metadata = this.metadata;\n    const providers = this.providers;\n    const scope = this.providers.getActiveScope();\n    const logger = scope.logger;\n    const authInfo = ctx.authInfo;\n\n    const toolCtorArgs: ToolCtorArgs<In> = {\n      metadata,\n      input: input as In,\n      providers,\n      logger,\n      authInfo,\n    }\n    switch (this.record.kind) {\n      case ToolKind.CLASS_TOKEN:\n        return new this.record.provide(toolCtorArgs);\n      case ToolKind.FUNCTION:\n        return new FunctionToolContext<In, Out>(this.record, toolCtorArgs);\n    }\n  }\n}\n\nclass FunctionToolContext<In extends object = any, Out extends object = any> extends ToolContext<In, Out> {\n  constructor(\n    private readonly record: ToolFunctionTokenRecord,\n    args: ToolCtorArgs<In>\n  ) {\n    super(args);\n  }\n\n  execute(input: In): Promise<Out> {\n    return this.record.provide(input, this);\n  }\n}\n\n"]}

package/src/tool/tool.registry.d.ts

@@ -0,0 +1,72 @@
+import { EntryOwnerRef, ToolEntry, ToolRecord, ToolRegistryInterface, ToolType } from '../common';
+import { ToolChangeEvent } from './tool.events';
+import ProviderRegistry from '../provider/provider.registry';
+import { RegistryAbstract, RegistryBuildMapResult } from '../regsitry';
+import { ToolInstance } from './tool.instance';
+import { ExportNameOptions } from "./tool.types";
+export default class ToolRegistry extends RegistryAbstract<ToolInstance, // IMPORTANT: instances map holds ToolInstance (not the interface)
+ToolRecord, ToolType[]> implements ToolRegistryInterface {
+    /** Who owns this registry (used for provenance). Optional. */
+    owner: EntryOwnerRef;
+    /** Tools truly owned/constructed by THIS registry (with lineage applied) */
+    private localRows;
+    /** Adopted tool rows from each child registry (references to the same instances) */
+    private adopted;
+    /** Children registries that we track */
+    private children;
+    private byQualifiedId;
+    private byName;
+    private byOwnerAndName;
+    private byProviderAndName;
+    private byOwner;
+    private version;
+    private emitter;
+    constructor(providers: ProviderRegistry, list: ToolType[], owner: EntryOwnerRef);
+    protected buildMap(list: ToolType[]): RegistryBuildMapResult<ToolRecord>;
+    protected buildGraph(): void;
+    protected initialize(): Promise<void>;
+    /**
+     * Adopt tools from a child registry. Parent runs after children are ready.
+     * We *reference* the child's tool instances; no duplicates are created.
+     *
+     * IMPORTANT:
+     * - Child rows already include the child's own lineage (e.g., adapter:openapi).
+     * - Here we only prepend the **parent's** owner, to avoid double-prefixing the child.
+     */
+    adoptFromChild(child: ToolRegistry, _childOwner: EntryOwnerRef): void;
+    getTools(includeHidden?: boolean): ToolEntry<any, any>[];
+    getInlineTools(): ToolEntry<any, any>[];
+    /** Internal snapshot of effective indexed rows (locals + adopted). */
+    private listAllIndexed;
+    private reindex;
+    /** List all instances (locals + adopted). */
+    listAllInstances(): readonly ToolInstance[];
+    /** List instances by owner path (e.g. "app:Portal/plugin:Okta") */
+    listByOwner(ownerPath: string): readonly ToolInstance[];
+    /**
+     * Produce unique, MCP-valid exported names.
+     * - Base (standardized) = metadata.name cased (snake/camel/kebab/dot)
+     * - If conflicting:
+     *    - Locals keep bare base (unless >1 locals conflict → they get owner prefixes)
+     *    - Children with same base get prefixed by providerId (or owner path)
+     */
+    exportResolvedNames(opts?: ExportNameOptions): Array<{
+        name: string;
+        instance: ToolInstance;
+    }>;
+    /** Lookup by the exported (resolved) name. */
+    getExported(name: string, opts?: ExportNameOptions): ToolInstance | undefined;
+    subscribe(opts: {
+        immediate?: boolean;
+        filter?: (i: ToolInstance) => boolean;
+    }, cb: (evt: ToolChangeEvent) => void): () => void;
+    private bump;
+    /** Build an IndexedTool row */
+    private makeRow;
+    /** Clone a child row and prepend lineage (with adjacent de-dup to avoid double prefixes). */
+    private relineage;
+    /** Best-effort provider id used for prefixing (inspects class metadata if present). */
+    private providerIdOf;
+    /** True if this registry (or adopted children) has any tools. */
+    hasAny(): boolean;
+}