@kadi.build/core 0.0.1-alpha.1 → 0.0.1-alpha.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (199) hide show
  1. package/README.md +361 -230
  2. package/dist/abilities/AbilityCache.d.ts +242 -0
  3. package/dist/abilities/AbilityCache.d.ts.map +1 -0
  4. package/dist/abilities/AbilityCache.js +285 -0
  5. package/dist/abilities/AbilityCache.js.map +1 -0
  6. package/dist/abilities/AbilityContext.d.ts +215 -0
  7. package/dist/abilities/AbilityContext.d.ts.map +1 -0
  8. package/dist/abilities/AbilityContext.js +36 -0
  9. package/dist/abilities/AbilityContext.js.map +1 -0
  10. package/dist/abilities/AbilityLoader.d.ts +203 -0
  11. package/dist/abilities/AbilityLoader.d.ts.map +1 -0
  12. package/dist/abilities/AbilityLoader.js +343 -0
  13. package/dist/abilities/AbilityLoader.js.map +1 -0
  14. package/dist/abilities/AbilityProxy.d.ts +496 -0
  15. package/dist/abilities/AbilityProxy.d.ts.map +1 -0
  16. package/dist/abilities/AbilityProxy.js +551 -0
  17. package/dist/abilities/AbilityProxy.js.map +1 -0
  18. package/dist/abilities/AbilityValidator.d.ts +172 -0
  19. package/dist/abilities/AbilityValidator.d.ts.map +1 -0
  20. package/dist/abilities/AbilityValidator.js +253 -0
  21. package/dist/abilities/AbilityValidator.js.map +1 -0
  22. package/dist/abilities/index.d.ts +26 -0
  23. package/dist/abilities/index.d.ts.map +1 -0
  24. package/dist/abilities/index.js +23 -0
  25. package/dist/abilities/index.js.map +1 -0
  26. package/dist/abilities/types.d.ts +223 -0
  27. package/dist/abilities/types.d.ts.map +1 -0
  28. package/dist/abilities/types.js +10 -0
  29. package/dist/abilities/types.js.map +1 -0
  30. package/dist/api/index.d.ts +92 -0
  31. package/dist/api/index.d.ts.map +1 -0
  32. package/dist/api/index.js +124 -0
  33. package/dist/api/index.js.map +1 -0
  34. package/dist/broker/BrokerConnection.d.ts +253 -0
  35. package/dist/broker/BrokerConnection.d.ts.map +1 -0
  36. package/dist/broker/BrokerConnection.js +434 -0
  37. package/dist/broker/BrokerConnection.js.map +1 -0
  38. package/dist/broker/BrokerConnectionManager.d.ts +216 -0
  39. package/dist/broker/BrokerConnectionManager.d.ts.map +1 -0
  40. package/dist/broker/BrokerConnectionManager.js +305 -0
  41. package/dist/broker/BrokerConnectionManager.js.map +1 -0
  42. package/dist/broker/BrokerProtocol.d.ts +280 -0
  43. package/dist/broker/BrokerProtocol.d.ts.map +1 -0
  44. package/dist/broker/BrokerProtocol.js +466 -0
  45. package/dist/broker/BrokerProtocol.js.map +1 -0
  46. package/dist/broker/index.d.ts +9 -0
  47. package/dist/broker/index.d.ts.map +1 -0
  48. package/dist/broker/index.js +9 -0
  49. package/dist/broker/index.js.map +1 -0
  50. package/dist/client/KadiClient.d.ts +459 -0
  51. package/dist/client/KadiClient.d.ts.map +1 -0
  52. package/dist/client/KadiClient.js +902 -0
  53. package/dist/client/KadiClient.js.map +1 -0
  54. package/dist/client/index.d.ts +7 -0
  55. package/dist/client/index.d.ts.map +1 -0
  56. package/dist/client/index.js +7 -0
  57. package/dist/client/index.js.map +1 -0
  58. package/dist/config/ConfigLoader.d.ts +138 -0
  59. package/dist/config/ConfigLoader.d.ts.map +1 -0
  60. package/dist/config/ConfigLoader.js +226 -0
  61. package/dist/config/ConfigLoader.js.map +1 -0
  62. package/dist/config/ConfigResolver.d.ts +135 -0
  63. package/dist/config/ConfigResolver.d.ts.map +1 -0
  64. package/dist/config/ConfigResolver.js +282 -0
  65. package/dist/config/ConfigResolver.js.map +1 -0
  66. package/dist/config/index.d.ts +8 -0
  67. package/dist/config/index.d.ts.map +1 -0
  68. package/dist/config/index.js +8 -0
  69. package/dist/config/index.js.map +1 -0
  70. package/dist/errors/index.d.ts +9 -0
  71. package/dist/errors/index.d.ts.map +1 -0
  72. package/dist/errors/index.js +8 -0
  73. package/dist/errors/index.js.map +1 -0
  74. package/dist/events/EventHub.d.ts +172 -0
  75. package/dist/events/EventHub.d.ts.map +1 -0
  76. package/dist/events/EventHub.js +333 -0
  77. package/dist/events/EventHub.js.map +1 -0
  78. package/dist/events/index.d.ts +7 -0
  79. package/dist/events/index.d.ts.map +1 -0
  80. package/dist/events/index.js +7 -0
  81. package/dist/events/index.js.map +1 -0
  82. package/dist/index.d.ts +50 -0
  83. package/dist/index.d.ts.map +1 -0
  84. package/dist/index.js +67 -0
  85. package/dist/index.js.map +1 -0
  86. package/dist/messages/index.d.ts +33 -0
  87. package/dist/messages/index.d.ts.map +1 -0
  88. package/dist/messages/index.js +33 -0
  89. package/dist/messages/index.js.map +1 -0
  90. package/dist/schemas/index.d.ts +22 -0
  91. package/dist/schemas/index.d.ts.map +1 -0
  92. package/dist/schemas/index.js +27 -0
  93. package/dist/schemas/index.js.map +1 -0
  94. package/dist/schemas/kadi-extensions.d.ts +231 -0
  95. package/dist/schemas/kadi-extensions.d.ts.map +1 -0
  96. package/dist/schemas/kadi-extensions.js +14 -0
  97. package/dist/schemas/kadi-extensions.js.map +1 -0
  98. package/dist/schemas/mcp/schema.d.ts +1399 -0
  99. package/dist/schemas/mcp/schema.d.ts.map +1 -0
  100. package/dist/schemas/mcp/schema.js +53 -0
  101. package/dist/schemas/mcp/schema.js.map +1 -0
  102. package/dist/schemas/mcp/version.d.ts +37 -0
  103. package/dist/schemas/mcp/version.d.ts.map +1 -0
  104. package/dist/schemas/mcp/version.js +39 -0
  105. package/dist/schemas/mcp/version.js.map +1 -0
  106. package/dist/schemas/schema-builders.d.ts +178 -0
  107. package/dist/schemas/schema-builders.d.ts.map +1 -0
  108. package/dist/schemas/schema-builders.js +258 -0
  109. package/dist/schemas/schema-builders.js.map +1 -0
  110. package/dist/schemas/zod-helpers.d.ts +129 -0
  111. package/dist/schemas/zod-helpers.d.ts.map +1 -0
  112. package/dist/schemas/zod-helpers.js +225 -0
  113. package/dist/schemas/zod-helpers.js.map +1 -0
  114. package/dist/schemas/zod-to-json-schema.d.ts +159 -0
  115. package/dist/schemas/zod-to-json-schema.d.ts.map +1 -0
  116. package/dist/schemas/zod-to-json-schema.js +154 -0
  117. package/dist/schemas/zod-to-json-schema.js.map +1 -0
  118. package/dist/tools/ToolRegistry.d.ts +256 -0
  119. package/dist/tools/ToolRegistry.d.ts.map +1 -0
  120. package/dist/tools/ToolRegistry.js +340 -0
  121. package/dist/tools/ToolRegistry.js.map +1 -0
  122. package/dist/tools/index.d.ts +7 -0
  123. package/dist/tools/index.d.ts.map +1 -0
  124. package/dist/tools/index.js +7 -0
  125. package/dist/tools/index.js.map +1 -0
  126. package/dist/transports/BrokerTransport.d.ts +151 -0
  127. package/dist/transports/BrokerTransport.d.ts.map +1 -0
  128. package/dist/transports/BrokerTransport.js +261 -0
  129. package/dist/transports/BrokerTransport.js.map +1 -0
  130. package/dist/transports/NativeTransport.d.ts +178 -0
  131. package/dist/transports/NativeTransport.d.ts.map +1 -0
  132. package/dist/transports/NativeTransport.js +397 -0
  133. package/dist/transports/NativeTransport.js.map +1 -0
  134. package/dist/transports/StdioTransport.d.ts +250 -0
  135. package/dist/transports/StdioTransport.d.ts.map +1 -0
  136. package/dist/transports/StdioTransport.js +487 -0
  137. package/dist/transports/StdioTransport.js.map +1 -0
  138. package/dist/transports/index.d.ts +10 -0
  139. package/dist/transports/index.d.ts.map +1 -0
  140. package/dist/transports/index.js +9 -0
  141. package/dist/transports/index.js.map +1 -0
  142. package/dist/types/broker.d.ts +279 -0
  143. package/dist/types/broker.d.ts.map +1 -0
  144. package/dist/types/broker.js +19 -0
  145. package/dist/types/broker.js.map +1 -0
  146. package/dist/types/config.d.ts +325 -0
  147. package/dist/types/config.d.ts.map +1 -0
  148. package/dist/types/config.js +17 -0
  149. package/dist/types/config.js.map +1 -0
  150. package/dist/types/errors.d.ts +178 -0
  151. package/dist/types/errors.d.ts.map +1 -0
  152. package/dist/types/errors.js +165 -0
  153. package/dist/types/errors.js.map +1 -0
  154. package/dist/types/events.d.ts +210 -0
  155. package/dist/types/events.d.ts.map +1 -0
  156. package/dist/types/events.js +8 -0
  157. package/dist/types/events.js.map +1 -0
  158. package/dist/types/index.d.ts +34 -0
  159. package/dist/types/index.d.ts.map +1 -0
  160. package/dist/types/index.js +21 -0
  161. package/dist/types/index.js.map +1 -0
  162. package/dist/types/protocol.d.ts +48 -0
  163. package/dist/types/protocol.d.ts.map +1 -0
  164. package/dist/types/protocol.js +11 -0
  165. package/dist/types/protocol.js.map +1 -0
  166. package/dist/types/tools.d.ts +67 -0
  167. package/dist/types/tools.d.ts.map +1 -0
  168. package/dist/types/tools.js +16 -0
  169. package/dist/types/tools.js.map +1 -0
  170. package/dist/types/transport.d.ts +250 -0
  171. package/dist/types/transport.d.ts.map +1 -0
  172. package/dist/types/transport.js +18 -0
  173. package/dist/types/transport.js.map +1 -0
  174. package/dist/types/zod-tools.d.ts +198 -0
  175. package/dist/types/zod-tools.d.ts.map +1 -0
  176. package/dist/types/zod-tools.js +14 -0
  177. package/dist/types/zod-tools.js.map +1 -0
  178. package/dist/utils/StdioMessageReader.d.ts +122 -0
  179. package/dist/utils/StdioMessageReader.d.ts.map +1 -0
  180. package/dist/utils/StdioMessageReader.js +209 -0
  181. package/dist/utils/StdioMessageReader.js.map +1 -0
  182. package/dist/utils/StdioMessageWriter.d.ts +104 -0
  183. package/dist/utils/StdioMessageWriter.d.ts.map +1 -0
  184. package/dist/utils/StdioMessageWriter.js +162 -0
  185. package/dist/utils/StdioMessageWriter.js.map +1 -0
  186. package/dist/validation/SchemaValidator.d.ts +208 -0
  187. package/dist/validation/SchemaValidator.d.ts.map +1 -0
  188. package/dist/validation/SchemaValidator.js +411 -0
  189. package/dist/validation/SchemaValidator.js.map +1 -0
  190. package/dist/validation/index.d.ts +11 -0
  191. package/dist/validation/index.d.ts.map +1 -0
  192. package/dist/validation/index.js +10 -0
  193. package/dist/validation/index.js.map +1 -0
  194. package/package.json +70 -5
  195. package/agent.json +0 -18
  196. package/broker.js +0 -214
  197. package/index.js +0 -370
  198. package/ipc.js +0 -220
  199. package/ipcInterfaces/pythonAbilityIPC.py +0 -177
@@ -0,0 +1,256 @@
1
+ /**
2
+ * Tool Registry (MCP-Based)
3
+ * ===========================
4
+ *
5
+ * Manages registration and retrieval of tools using Model Context Protocol (MCP)
6
+ * JSON Schemas for validation.
7
+ *
8
+ * **Breaking Change (v2.0.0)**:
9
+ * - Replaced Zod schemas with MCP JSON Schemas
10
+ * - Uses AJV for schema validation
11
+ * - Tools now use KadiTool interface
12
+ *
13
+ * @module tools/ToolRegistry
14
+ */
15
+ import type { ToolHandler, RegisteredTool, ToolDefinition, KadiTool } from '../types/index.js';
16
+ import { SchemaValidator } from '../validation/index.js';
17
+ /**
18
+ * Tool Registry
19
+ * ==============
20
+ *
21
+ * Single responsibility: Manage tool registration and retrieval.
22
+ * Does NOT handle:
23
+ * - Tool invocation (that's the transport's job)
24
+ * - Broker communication (that's BrokerProtocol's job)
25
+ * - Events (that's EventHub's job)
26
+ *
27
+ * **Features**:
28
+ * - MCP-compliant tool definitions
29
+ * - AJV schema validation (global cache for performance)
30
+ * - KADI extensions (version, tags, networks)
31
+ *
32
+ * @example
33
+ * ```typescript
34
+ * const registry = new ToolRegistry();
35
+ *
36
+ * // Register a tool with MCP schema
37
+ * registry.register({
38
+ * name: 'add',
39
+ * description: 'Add two numbers',
40
+ * version: '1.0.0',
41
+ * tags: ['math'],
42
+ * inputSchema: {
43
+ * type: 'object',
44
+ * properties: {
45
+ * a: { type: 'number' },
46
+ * b: { type: 'number' }
47
+ * },
48
+ * required: ['a', 'b']
49
+ * },
50
+ * outputSchema: {
51
+ * type: 'object',
52
+ * properties: {
53
+ * result: { type: 'number' }
54
+ * }
55
+ * }
56
+ * }, async ({ a, b }) => ({ result: a + b }));
57
+ *
58
+ * // Retrieve a tool
59
+ * const tool = registry.get('add');
60
+ * if (tool) {
61
+ * const result = await tool.handler({ a: 5, b: 3 });
62
+ * }
63
+ * ```
64
+ */
65
+ export declare class ToolRegistry {
66
+ /**
67
+ * Internal storage for registered tools
68
+ */
69
+ private readonly tools;
70
+ /**
71
+ * Schema validator (uses global cache for performance)
72
+ */
73
+ private readonly validator;
74
+ /**
75
+ * Register a new tool
76
+ *
77
+ * @template TInput - Tool input type
78
+ * @template TOutput - Tool output type
79
+ *
80
+ * @param definition - MCP-compliant tool definition
81
+ * @param handler - Function that implements the tool
82
+ *
83
+ * @throws {KadiError} If name is invalid, tool already exists, or schema is invalid
84
+ *
85
+ * @example
86
+ * ```typescript
87
+ * registry.register({
88
+ * name: 'greet',
89
+ * description: 'Greet a user',
90
+ * inputSchema: {
91
+ * type: 'object',
92
+ * properties: {
93
+ * name: { type: 'string' }
94
+ * },
95
+ * required: ['name']
96
+ * },
97
+ * outputSchema: {
98
+ * type: 'object',
99
+ * properties: {
100
+ * message: { type: 'string' }
101
+ * }
102
+ * }
103
+ * }, async ({ name }) => ({ message: `Hello, ${name}!` }));
104
+ * ```
105
+ */
106
+ register<TInput = unknown, TOutput = unknown>(definition: KadiTool, handler: ToolHandler<TInput, TOutput>): void;
107
+ /**
108
+ * Get a registered tool by name
109
+ *
110
+ * @param name - Tool identifier
111
+ * @returns The registered tool or undefined if not found
112
+ *
113
+ * @example
114
+ * ```typescript
115
+ * const tool = registry.get('add');
116
+ * if (tool) {
117
+ * const result = await tool.handler({ a: 1, b: 2 });
118
+ * }
119
+ * ```
120
+ */
121
+ get(name: string): RegisteredTool | undefined;
122
+ /**
123
+ * Get handler function for a tool
124
+ *
125
+ * @param name - Tool identifier
126
+ * @returns Tool handler function or undefined if not found
127
+ *
128
+ * @example
129
+ * ```typescript
130
+ * const handler = registry.getHandler('add');
131
+ * if (handler) {
132
+ * const result = await handler({ a: 5, b: 3 });
133
+ * }
134
+ * ```
135
+ */
136
+ getHandler<TInput = unknown, TOutput = unknown>(name: string): ToolHandler<TInput, TOutput> | undefined;
137
+ /**
138
+ * Get all registered tools
139
+ *
140
+ * @returns Array of all registered tools
141
+ *
142
+ * @example
143
+ * ```typescript
144
+ * const allTools = registry.getAll();
145
+ * console.log('Available tools:', allTools.map(t => t.definition.name));
146
+ * ```
147
+ */
148
+ getAll(): RegisteredTool[];
149
+ /**
150
+ * Check if a tool is registered
151
+ *
152
+ * @param name - Tool identifier
153
+ * @returns true if tool exists, false otherwise
154
+ *
155
+ * @example
156
+ * ```typescript
157
+ * if (registry.has('add')) {
158
+ * // Tool is available
159
+ * }
160
+ * ```
161
+ */
162
+ has(name: string): boolean;
163
+ /**
164
+ * Unregister a tool
165
+ *
166
+ * @param name - Tool identifier to remove
167
+ * @returns true if tool was removed, false if it didn't exist
168
+ *
169
+ * @example
170
+ * ```typescript
171
+ * registry.unregister('old-tool');
172
+ * ```
173
+ */
174
+ unregister(name: string): boolean;
175
+ /**
176
+ * Clear all registered tools
177
+ *
178
+ * @example
179
+ * ```typescript
180
+ * registry.clear();
181
+ * ```
182
+ */
183
+ clear(): void;
184
+ /**
185
+ * Get the number of registered tools
186
+ *
187
+ * @example
188
+ * ```typescript
189
+ * console.log(`${registry.size} tools registered`);
190
+ * ```
191
+ */
192
+ get size(): number;
193
+ /**
194
+ * Extract tool definitions for broker registration
195
+ *
196
+ * Converts registered tools into MCP-compliant format for sending to the broker.
197
+ *
198
+ * @returns Array of MCP tool definitions
199
+ *
200
+ * @example
201
+ * ```typescript
202
+ * const definitions = registry.extractDefinitions();
203
+ * await broker.registerCapabilities({ tools: definitions });
204
+ * ```
205
+ */
206
+ extractDefinitions(): ToolDefinition[];
207
+ /**
208
+ * Validate input against a tool's schema
209
+ *
210
+ * @param toolName - Tool name
211
+ * @param input - Input data to validate
212
+ * @returns Validation result
213
+ *
214
+ * @example
215
+ * ```typescript
216
+ * const result = registry.validateInput('add', { a: 5, b: 3 });
217
+ * if (!result.valid) {
218
+ * console.error('Invalid input:', result.errors);
219
+ * }
220
+ * ```
221
+ */
222
+ validateInput(toolName: string, input: unknown): import("../validation/SchemaValidator.js").ValidationResult;
223
+ /**
224
+ * Validate output against a tool's schema
225
+ *
226
+ * @param toolName - Tool name
227
+ * @param output - Output data to validate
228
+ * @returns Validation result
229
+ *
230
+ * @example
231
+ * ```typescript
232
+ * const result = registry.validateOutput('add', { result: 8 });
233
+ * if (!result.valid) {
234
+ * console.error('Invalid output:', result.errors);
235
+ * }
236
+ * ```
237
+ */
238
+ validateOutput(toolName: string, output: unknown): import("../validation/SchemaValidator.js").ValidationResult;
239
+ /**
240
+ * Get schema validator instance
241
+ *
242
+ * Useful for advanced schema operations.
243
+ *
244
+ * @returns Schema validator
245
+ */
246
+ getValidator(): SchemaValidator;
247
+ /**
248
+ * Get global schema cache statistics
249
+ *
250
+ * @returns Cache statistics
251
+ */
252
+ static getCacheStats(): {
253
+ cachedSchemas: number;
254
+ };
255
+ }
256
+ //# sourceMappingURL=ToolRegistry.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"ToolRegistry.d.ts","sourceRoot":"","sources":["../../src/tools/ToolRegistry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EACV,WAAW,EACX,cAAc,EACd,cAAc,EACd,QAAQ,EACT,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAEzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,qBAAa,YAAY;IACvB;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqC;IAE3D;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAyB;IAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,QAAQ,CAAC,MAAM,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,EAC1C,UAAU,EAAE,QAAQ,EACpB,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,GACpC,IAAI;IAmGP;;;;;;;;;;;;;OAaG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAI7C;;;;;;;;;;;;;OAaG;IACH,UAAU,CAAC,MAAM,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,EAC5C,IAAI,EAAE,MAAM,GACX,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS;IAK3C;;;;;;;;;;OAUG;IACH,MAAM,IAAI,cAAc,EAAE;IAI1B;;;;;;;;;;;;OAYG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B;;;;;;;;;;OAUG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAMjC;;;;;;;OAOG;IACH,KAAK,IAAI,IAAI;IAQb;;;;;;;OAOG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;;;;;;;;;;OAYG;IACH,kBAAkB,IAAI,cAAc,EAAE;IAetC;;;;;;;;;;;;;;OAcG;IACH,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO;IAI9C;;;;;;;;;;;;;;OAcG;IACH,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO;IAIhD;;;;;;OAMG;IACH,YAAY,IAAI,eAAe;IAI/B;;;;OAIG;IACH,MAAM,CAAC,aAAa,IAAI;QAAE,aAAa,EAAE,MAAM,CAAA;KAAE;CAGlD"}
@@ -0,0 +1,340 @@
1
+ /**
2
+ * Tool Registry (MCP-Based)
3
+ * ===========================
4
+ *
5
+ * Manages registration and retrieval of tools using Model Context Protocol (MCP)
6
+ * JSON Schemas for validation.
7
+ *
8
+ * **Breaking Change (v2.0.0)**:
9
+ * - Replaced Zod schemas with MCP JSON Schemas
10
+ * - Uses AJV for schema validation
11
+ * - Tools now use KadiTool interface
12
+ *
13
+ * @module tools/ToolRegistry
14
+ */
15
+ import { KadiError, ErrorCode } from '../types/index.js';
16
+ import { SchemaValidator } from '../validation/index.js';
17
+ /**
18
+ * Tool Registry
19
+ * ==============
20
+ *
21
+ * Single responsibility: Manage tool registration and retrieval.
22
+ * Does NOT handle:
23
+ * - Tool invocation (that's the transport's job)
24
+ * - Broker communication (that's BrokerProtocol's job)
25
+ * - Events (that's EventHub's job)
26
+ *
27
+ * **Features**:
28
+ * - MCP-compliant tool definitions
29
+ * - AJV schema validation (global cache for performance)
30
+ * - KADI extensions (version, tags, networks)
31
+ *
32
+ * @example
33
+ * ```typescript
34
+ * const registry = new ToolRegistry();
35
+ *
36
+ * // Register a tool with MCP schema
37
+ * registry.register({
38
+ * name: 'add',
39
+ * description: 'Add two numbers',
40
+ * version: '1.0.0',
41
+ * tags: ['math'],
42
+ * inputSchema: {
43
+ * type: 'object',
44
+ * properties: {
45
+ * a: { type: 'number' },
46
+ * b: { type: 'number' }
47
+ * },
48
+ * required: ['a', 'b']
49
+ * },
50
+ * outputSchema: {
51
+ * type: 'object',
52
+ * properties: {
53
+ * result: { type: 'number' }
54
+ * }
55
+ * }
56
+ * }, async ({ a, b }) => ({ result: a + b }));
57
+ *
58
+ * // Retrieve a tool
59
+ * const tool = registry.get('add');
60
+ * if (tool) {
61
+ * const result = await tool.handler({ a: 5, b: 3 });
62
+ * }
63
+ * ```
64
+ */
65
+ export class ToolRegistry {
66
+ /**
67
+ * Internal storage for registered tools
68
+ */
69
+ tools = new Map();
70
+ /**
71
+ * Schema validator (uses global cache for performance)
72
+ */
73
+ validator = new SchemaValidator();
74
+ /**
75
+ * Register a new tool
76
+ *
77
+ * @template TInput - Tool input type
78
+ * @template TOutput - Tool output type
79
+ *
80
+ * @param definition - MCP-compliant tool definition
81
+ * @param handler - Function that implements the tool
82
+ *
83
+ * @throws {KadiError} If name is invalid, tool already exists, or schema is invalid
84
+ *
85
+ * @example
86
+ * ```typescript
87
+ * registry.register({
88
+ * name: 'greet',
89
+ * description: 'Greet a user',
90
+ * inputSchema: {
91
+ * type: 'object',
92
+ * properties: {
93
+ * name: { type: 'string' }
94
+ * },
95
+ * required: ['name']
96
+ * },
97
+ * outputSchema: {
98
+ * type: 'object',
99
+ * properties: {
100
+ * message: { type: 'string' }
101
+ * }
102
+ * }
103
+ * }, async ({ name }) => ({ message: `Hello, ${name}!` }));
104
+ * ```
105
+ */
106
+ register(definition, handler) {
107
+ // Validate tool name
108
+ if (!definition.name || typeof definition.name !== 'string' || definition.name.trim().length === 0) {
109
+ throw new KadiError('Tool name must be a non-empty string', ErrorCode.INVALID_INPUT, 400, { definition });
110
+ }
111
+ // Check for duplicates
112
+ if (this.tools.has(definition.name)) {
113
+ throw new KadiError(`Tool '${definition.name}' is already registered`, ErrorCode.TOOL_ALREADY_REGISTERED, 409, { name: definition.name });
114
+ }
115
+ // Validate handler
116
+ if (typeof handler !== 'function') {
117
+ throw new KadiError('Tool handler must be a function', ErrorCode.INVALID_INPUT, 400, { name: definition.name, handlerType: typeof handler });
118
+ }
119
+ // Validate inputSchema (required in MCP)
120
+ if (!definition.inputSchema) {
121
+ throw new KadiError(`Tool '${definition.name}' must have an inputSchema`, ErrorCode.SCHEMA_VALIDATION_FAILED, 400, { name: definition.name });
122
+ }
123
+ // MCP requires inputSchema.type === 'object'
124
+ if (definition.inputSchema.type !== 'object') {
125
+ throw new KadiError(`Tool '${definition.name}' inputSchema must be type 'object' (MCP requirement)`, ErrorCode.SCHEMA_VALIDATION_FAILED, 400, { name: definition.name, schemaType: definition.inputSchema.type });
126
+ }
127
+ // Validate inputSchema is valid JSON Schema
128
+ const inputValidation = this.validator.validateSchemaDefinition(definition.inputSchema);
129
+ if (!inputValidation.valid) {
130
+ throw new KadiError(`Invalid inputSchema for tool '${definition.name}': ${inputValidation.errors.join(', ')}`, ErrorCode.SCHEMA_VALIDATION_FAILED, 400, { name: definition.name, errors: inputValidation.errors });
131
+ }
132
+ // Validate outputSchema if provided (optional in MCP, but we validate if present)
133
+ if (definition.outputSchema) {
134
+ if (definition.outputSchema.type !== 'object') {
135
+ throw new KadiError(`Tool '${definition.name}' outputSchema must be type 'object' (MCP requirement)`, ErrorCode.SCHEMA_VALIDATION_FAILED, 400, { name: definition.name, schemaType: definition.outputSchema.type });
136
+ }
137
+ const outputValidation = this.validator.validateSchemaDefinition(definition.outputSchema);
138
+ if (!outputValidation.valid) {
139
+ throw new KadiError(`Invalid outputSchema for tool '${definition.name}': ${outputValidation.errors.join(', ')}`, ErrorCode.SCHEMA_VALIDATION_FAILED, 400, { name: definition.name, errors: outputValidation.errors });
140
+ }
141
+ }
142
+ // Register schemas with validator for runtime validation
143
+ this.validator.registerTool(definition.name, definition.inputSchema, definition.outputSchema);
144
+ // Register the tool
145
+ this.tools.set(definition.name, {
146
+ definition,
147
+ handler: handler,
148
+ registeredAt: Date.now()
149
+ });
150
+ }
151
+ /**
152
+ * Get a registered tool by name
153
+ *
154
+ * @param name - Tool identifier
155
+ * @returns The registered tool or undefined if not found
156
+ *
157
+ * @example
158
+ * ```typescript
159
+ * const tool = registry.get('add');
160
+ * if (tool) {
161
+ * const result = await tool.handler({ a: 1, b: 2 });
162
+ * }
163
+ * ```
164
+ */
165
+ get(name) {
166
+ return this.tools.get(name);
167
+ }
168
+ /**
169
+ * Get handler function for a tool
170
+ *
171
+ * @param name - Tool identifier
172
+ * @returns Tool handler function or undefined if not found
173
+ *
174
+ * @example
175
+ * ```typescript
176
+ * const handler = registry.getHandler('add');
177
+ * if (handler) {
178
+ * const result = await handler({ a: 5, b: 3 });
179
+ * }
180
+ * ```
181
+ */
182
+ getHandler(name) {
183
+ const tool = this.tools.get(name);
184
+ return tool?.handler;
185
+ }
186
+ /**
187
+ * Get all registered tools
188
+ *
189
+ * @returns Array of all registered tools
190
+ *
191
+ * @example
192
+ * ```typescript
193
+ * const allTools = registry.getAll();
194
+ * console.log('Available tools:', allTools.map(t => t.definition.name));
195
+ * ```
196
+ */
197
+ getAll() {
198
+ return Array.from(this.tools.values());
199
+ }
200
+ /**
201
+ * Check if a tool is registered
202
+ *
203
+ * @param name - Tool identifier
204
+ * @returns true if tool exists, false otherwise
205
+ *
206
+ * @example
207
+ * ```typescript
208
+ * if (registry.has('add')) {
209
+ * // Tool is available
210
+ * }
211
+ * ```
212
+ */
213
+ has(name) {
214
+ return this.tools.has(name);
215
+ }
216
+ /**
217
+ * Unregister a tool
218
+ *
219
+ * @param name - Tool identifier to remove
220
+ * @returns true if tool was removed, false if it didn't exist
221
+ *
222
+ * @example
223
+ * ```typescript
224
+ * registry.unregister('old-tool');
225
+ * ```
226
+ */
227
+ unregister(name) {
228
+ // Remove from validator as well
229
+ this.validator.unregisterTool(name);
230
+ return this.tools.delete(name);
231
+ }
232
+ /**
233
+ * Clear all registered tools
234
+ *
235
+ * @example
236
+ * ```typescript
237
+ * registry.clear();
238
+ * ```
239
+ */
240
+ clear() {
241
+ // Clear validator registrations
242
+ for (const name of this.tools.keys()) {
243
+ this.validator.unregisterTool(name);
244
+ }
245
+ this.tools.clear();
246
+ }
247
+ /**
248
+ * Get the number of registered tools
249
+ *
250
+ * @example
251
+ * ```typescript
252
+ * console.log(`${registry.size} tools registered`);
253
+ * ```
254
+ */
255
+ get size() {
256
+ return this.tools.size;
257
+ }
258
+ /**
259
+ * Extract tool definitions for broker registration
260
+ *
261
+ * Converts registered tools into MCP-compliant format for sending to the broker.
262
+ *
263
+ * @returns Array of MCP tool definitions
264
+ *
265
+ * @example
266
+ * ```typescript
267
+ * const definitions = registry.extractDefinitions();
268
+ * await broker.registerCapabilities({ tools: definitions });
269
+ * ```
270
+ */
271
+ extractDefinitions() {
272
+ return this.getAll().map(tool => ({
273
+ name: tool.definition.name,
274
+ title: tool.definition.title,
275
+ description: tool.definition.description,
276
+ version: tool.definition.version,
277
+ tags: tool.definition.tags,
278
+ networks: tool.definition.networks,
279
+ inputSchema: tool.definition.inputSchema,
280
+ outputSchema: tool.definition.outputSchema,
281
+ annotations: tool.definition.annotations,
282
+ _meta: tool.definition._meta
283
+ }));
284
+ }
285
+ /**
286
+ * Validate input against a tool's schema
287
+ *
288
+ * @param toolName - Tool name
289
+ * @param input - Input data to validate
290
+ * @returns Validation result
291
+ *
292
+ * @example
293
+ * ```typescript
294
+ * const result = registry.validateInput('add', { a: 5, b: 3 });
295
+ * if (!result.valid) {
296
+ * console.error('Invalid input:', result.errors);
297
+ * }
298
+ * ```
299
+ */
300
+ validateInput(toolName, input) {
301
+ return this.validator.validateInput(toolName, input);
302
+ }
303
+ /**
304
+ * Validate output against a tool's schema
305
+ *
306
+ * @param toolName - Tool name
307
+ * @param output - Output data to validate
308
+ * @returns Validation result
309
+ *
310
+ * @example
311
+ * ```typescript
312
+ * const result = registry.validateOutput('add', { result: 8 });
313
+ * if (!result.valid) {
314
+ * console.error('Invalid output:', result.errors);
315
+ * }
316
+ * ```
317
+ */
318
+ validateOutput(toolName, output) {
319
+ return this.validator.validateOutput(toolName, output);
320
+ }
321
+ /**
322
+ * Get schema validator instance
323
+ *
324
+ * Useful for advanced schema operations.
325
+ *
326
+ * @returns Schema validator
327
+ */
328
+ getValidator() {
329
+ return this.validator;
330
+ }
331
+ /**
332
+ * Get global schema cache statistics
333
+ *
334
+ * @returns Cache statistics
335
+ */
336
+ static getCacheStats() {
337
+ return SchemaValidator.getCacheStats();
338
+ }
339
+ }
340
+ //# sourceMappingURL=ToolRegistry.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"ToolRegistry.js","sourceRoot":"","sources":["../../src/tools/ToolRegistry.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,7 @@
1
+ /**
2
+ * Tools Module
3
+ *
4
+ * Exports for tool registration and management.
5
+ */
6
+ export { ToolRegistry } from './ToolRegistry.js';
7
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC"}
@@ -0,0 +1,7 @@
1
+ /**
2
+ * Tools Module
3
+ *
4
+ * Exports for tool registration and management.
5
+ */
6
+ export { ToolRegistry } from './ToolRegistry.js';
7
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC"}