@kadi.build/core 0.0.1-alpha.8 → 0.1.0

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 (126) hide show
  1. package/README.md +362 -1305
  2. package/dist/client.d.ts +573 -0
  3. package/dist/client.d.ts.map +1 -0
  4. package/dist/client.js +1673 -0
  5. package/dist/client.js.map +1 -0
  6. package/dist/errors.d.ts +107 -0
  7. package/dist/errors.d.ts.map +1 -0
  8. package/dist/errors.js +147 -0
  9. package/dist/errors.js.map +1 -0
  10. package/dist/index.d.ts +37 -14
  11. package/dist/index.d.ts.map +1 -1
  12. package/dist/index.js +40 -23
  13. package/dist/index.js.map +1 -1
  14. package/dist/lockfile.d.ts +190 -0
  15. package/dist/lockfile.d.ts.map +1 -0
  16. package/dist/lockfile.js +373 -0
  17. package/dist/lockfile.js.map +1 -0
  18. package/dist/transports/broker.d.ts +75 -0
  19. package/dist/transports/broker.d.ts.map +1 -0
  20. package/dist/transports/broker.js +383 -0
  21. package/dist/transports/broker.js.map +1 -0
  22. package/dist/transports/native.d.ts +39 -0
  23. package/dist/transports/native.d.ts.map +1 -0
  24. package/dist/transports/native.js +189 -0
  25. package/dist/transports/native.js.map +1 -0
  26. package/dist/transports/stdio.d.ts +46 -0
  27. package/dist/transports/stdio.d.ts.map +1 -0
  28. package/dist/transports/stdio.js +460 -0
  29. package/dist/transports/stdio.js.map +1 -0
  30. package/dist/types.d.ts +664 -0
  31. package/dist/types.d.ts.map +1 -0
  32. package/dist/types.js +16 -0
  33. package/dist/types.js.map +1 -0
  34. package/dist/zod.d.ts +34 -0
  35. package/dist/zod.d.ts.map +1 -0
  36. package/dist/zod.js +60 -0
  37. package/dist/zod.js.map +1 -0
  38. package/package.json +13 -28
  39. package/dist/KadiClient.d.ts +0 -432
  40. package/dist/KadiClient.d.ts.map +0 -1
  41. package/dist/KadiClient.js +0 -1506
  42. package/dist/KadiClient.js.map +0 -1
  43. package/dist/errors/error-codes.d.ts +0 -985
  44. package/dist/errors/error-codes.d.ts.map +0 -1
  45. package/dist/errors/error-codes.js +0 -638
  46. package/dist/errors/error-codes.js.map +0 -1
  47. package/dist/loadAbility.d.ts +0 -105
  48. package/dist/loadAbility.d.ts.map +0 -1
  49. package/dist/loadAbility.js +0 -370
  50. package/dist/loadAbility.js.map +0 -1
  51. package/dist/messages/BrokerMessages.d.ts +0 -84
  52. package/dist/messages/BrokerMessages.d.ts.map +0 -1
  53. package/dist/messages/BrokerMessages.js +0 -125
  54. package/dist/messages/BrokerMessages.js.map +0 -1
  55. package/dist/messages/MessageBuilder.d.ts +0 -83
  56. package/dist/messages/MessageBuilder.d.ts.map +0 -1
  57. package/dist/messages/MessageBuilder.js +0 -144
  58. package/dist/messages/MessageBuilder.js.map +0 -1
  59. package/dist/schemas/events.schemas.d.ts +0 -177
  60. package/dist/schemas/events.schemas.d.ts.map +0 -1
  61. package/dist/schemas/events.schemas.js +0 -265
  62. package/dist/schemas/events.schemas.js.map +0 -1
  63. package/dist/schemas/index.d.ts +0 -3
  64. package/dist/schemas/index.d.ts.map +0 -1
  65. package/dist/schemas/index.js +0 -4
  66. package/dist/schemas/index.js.map +0 -1
  67. package/dist/schemas/kadi.schemas.d.ts +0 -70
  68. package/dist/schemas/kadi.schemas.d.ts.map +0 -1
  69. package/dist/schemas/kadi.schemas.js +0 -120
  70. package/dist/schemas/kadi.schemas.js.map +0 -1
  71. package/dist/transports/BrokerTransport.d.ts +0 -102
  72. package/dist/transports/BrokerTransport.d.ts.map +0 -1
  73. package/dist/transports/BrokerTransport.js +0 -177
  74. package/dist/transports/BrokerTransport.js.map +0 -1
  75. package/dist/transports/NativeTransport.d.ts +0 -82
  76. package/dist/transports/NativeTransport.d.ts.map +0 -1
  77. package/dist/transports/NativeTransport.js +0 -263
  78. package/dist/transports/NativeTransport.js.map +0 -1
  79. package/dist/transports/StdioTransport.d.ts +0 -112
  80. package/dist/transports/StdioTransport.d.ts.map +0 -1
  81. package/dist/transports/StdioTransport.js +0 -450
  82. package/dist/transports/StdioTransport.js.map +0 -1
  83. package/dist/transports/Transport.d.ts +0 -93
  84. package/dist/transports/Transport.d.ts.map +0 -1
  85. package/dist/transports/Transport.js +0 -13
  86. package/dist/transports/Transport.js.map +0 -1
  87. package/dist/types/broker.d.ts +0 -31
  88. package/dist/types/broker.d.ts.map +0 -1
  89. package/dist/types/broker.js +0 -6
  90. package/dist/types/broker.js.map +0 -1
  91. package/dist/types/core.d.ts +0 -139
  92. package/dist/types/core.d.ts.map +0 -1
  93. package/dist/types/core.js +0 -26
  94. package/dist/types/core.js.map +0 -1
  95. package/dist/types/events.d.ts +0 -186
  96. package/dist/types/events.d.ts.map +0 -1
  97. package/dist/types/events.js +0 -16
  98. package/dist/types/events.js.map +0 -1
  99. package/dist/types/index.d.ts +0 -9
  100. package/dist/types/index.d.ts.map +0 -1
  101. package/dist/types/index.js +0 -13
  102. package/dist/types/index.js.map +0 -1
  103. package/dist/types/protocol.d.ts +0 -160
  104. package/dist/types/protocol.d.ts.map +0 -1
  105. package/dist/types/protocol.js +0 -5
  106. package/dist/types/protocol.js.map +0 -1
  107. package/dist/utils/agentUtils.d.ts +0 -187
  108. package/dist/utils/agentUtils.d.ts.map +0 -1
  109. package/dist/utils/agentUtils.js +0 -185
  110. package/dist/utils/agentUtils.js.map +0 -1
  111. package/dist/utils/commandUtils.d.ts +0 -45
  112. package/dist/utils/commandUtils.d.ts.map +0 -1
  113. package/dist/utils/commandUtils.js +0 -145
  114. package/dist/utils/commandUtils.js.map +0 -1
  115. package/dist/utils/configUtils.d.ts +0 -55
  116. package/dist/utils/configUtils.d.ts.map +0 -1
  117. package/dist/utils/configUtils.js +0 -100
  118. package/dist/utils/configUtils.js.map +0 -1
  119. package/dist/utils/logger.d.ts +0 -59
  120. package/dist/utils/logger.d.ts.map +0 -1
  121. package/dist/utils/logger.js +0 -122
  122. package/dist/utils/logger.js.map +0 -1
  123. package/dist/utils/pathUtils.d.ts +0 -48
  124. package/dist/utils/pathUtils.d.ts.map +0 -1
  125. package/dist/utils/pathUtils.js +0 -128
  126. package/dist/utils/pathUtils.js.map +0 -1
package/dist/zod.d.ts ADDED
@@ -0,0 +1,34 @@
1
+ /**
2
+ * Zod utilities for kadi-core v0.1.0
3
+ *
4
+ * Uses Zod 4's built-in JSON Schema conversion.
5
+ * See: https://zod.dev/json-schema
6
+ */
7
+ import { type ZodType } from 'zod';
8
+ import type { JSONSchema } from './types.js';
9
+ /**
10
+ * Check if a value is a Zod schema.
11
+ *
12
+ * Uses duck-typing on the internal `_zod` property rather than `instanceof`
13
+ * to handle cases where prototype chains are broken by bundlers (e.g., esbuild)
14
+ * or when multiple Zod instances exist.
15
+ */
16
+ export declare function isZodSchema(value: unknown): value is ZodType;
17
+ /**
18
+ * Convert a Zod schema to JSON Schema using Zod 4's built-in conversion.
19
+ *
20
+ * @param schema - Zod schema to convert
21
+ * @returns JSON Schema equivalent
22
+ *
23
+ * @example
24
+ * ```typescript
25
+ * const inputSchema = z.object({
26
+ * text: z.string().describe('Text to analyze'),
27
+ * limit: z.number().optional().default(10),
28
+ * });
29
+ *
30
+ * const jsonSchema = zodToJsonSchema(inputSchema);
31
+ * ```
32
+ */
33
+ export declare function zodToJsonSchema(schema: ZodType): JSONSchema;
34
+ //# sourceMappingURL=zod.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"zod.d.ts","sourceRoot":"","sources":["../src/zod.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAK,KAAK,OAAO,EAAE,MAAM,KAAK,CAAC;AACtC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,OAAO,CA+B5D;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,OAAO,GAAG,UAAU,CAE3D"}
package/dist/zod.js ADDED
@@ -0,0 +1,60 @@
1
+ /**
2
+ * Zod utilities for kadi-core v0.1.0
3
+ *
4
+ * Uses Zod 4's built-in JSON Schema conversion.
5
+ * See: https://zod.dev/json-schema
6
+ */
7
+ import { z } from 'zod';
8
+ /**
9
+ * Check if a value is a Zod schema.
10
+ *
11
+ * Uses duck-typing on the internal `_zod` property rather than `instanceof`
12
+ * to handle cases where prototype chains are broken by bundlers (e.g., esbuild)
13
+ * or when multiple Zod instances exist.
14
+ */
15
+ export function isZodSchema(value) {
16
+ if (value === null || typeof value !== 'object') {
17
+ return false;
18
+ }
19
+ // All Zod 4 schemas have an internal _zod property
20
+ if (!('_zod' in value)) {
21
+ return false;
22
+ }
23
+ const zod = value._zod;
24
+ if (zod === null || typeof zod !== 'object') {
25
+ return false;
26
+ }
27
+ // _zod.def holds the schema definition
28
+ if (!('def' in zod)) {
29
+ return false;
30
+ }
31
+ const def = zod.def;
32
+ if (def === null || typeof def !== 'object') {
33
+ return false;
34
+ }
35
+ // def.type is the discriminator (e.g., "string", "object", "array")
36
+ if (!('type' in def)) {
37
+ return false;
38
+ }
39
+ return typeof def.type === 'string';
40
+ }
41
+ /**
42
+ * Convert a Zod schema to JSON Schema using Zod 4's built-in conversion.
43
+ *
44
+ * @param schema - Zod schema to convert
45
+ * @returns JSON Schema equivalent
46
+ *
47
+ * @example
48
+ * ```typescript
49
+ * const inputSchema = z.object({
50
+ * text: z.string().describe('Text to analyze'),
51
+ * limit: z.number().optional().default(10),
52
+ * });
53
+ *
54
+ * const jsonSchema = zodToJsonSchema(inputSchema);
55
+ * ```
56
+ */
57
+ export function zodToJsonSchema(schema) {
58
+ return z.toJSONSchema(schema);
59
+ }
60
+ //# sourceMappingURL=zod.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"zod.js","sourceRoot":"","sources":["../src/zod.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,CAAC,EAAgB,MAAM,KAAK,CAAC;AAGtC;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAChD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,mDAAmD;IACnD,IAAI,CAAC,CAAC,MAAM,IAAI,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,GAAG,GAAI,KAA2B,CAAC,IAAI,CAAC;IAC9C,IAAI,GAAG,KAAK,IAAI,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC5C,OAAO,KAAK,CAAC;IACf,CAAC;IAED,uCAAuC;IACvC,IAAI,CAAC,CAAC,KAAK,IAAI,GAAG,CAAC,EAAE,CAAC;QACpB,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,GAAG,GAAI,GAAwB,CAAC,GAAG,CAAC;IAC1C,IAAI,GAAG,KAAK,IAAI,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC5C,OAAO,KAAK,CAAC;IACf,CAAC;IAED,oEAAoE;IACpE,IAAI,CAAC,CAAC,MAAM,IAAI,GAAG,CAAC,EAAE,CAAC;QACrB,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,OAAQ,GAAyB,CAAC,IAAI,KAAK,QAAQ,CAAC;AAC7D,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,eAAe,CAAC,MAAe;IAC7C,OAAO,CAAC,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;AAChC,CAAC"}
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@kadi.build/core",
3
- "version": "0.0.1-alpha.8",
4
- "description": "A module that is a comprehensive toolkit for developers integrating with the KADI infrastructure.",
3
+ "version": "0.1.0",
4
+ "description": "A lean, readable SDK for building KADI agents.",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",
7
7
  "type": "module",
@@ -9,26 +9,6 @@
9
9
  ".": {
10
10
  "import": "./dist/index.js",
11
11
  "types": "./dist/index.d.ts"
12
- },
13
- "./types": {
14
- "import": "./dist/types/index.js",
15
- "types": "./dist/types/index.d.ts"
16
- },
17
- "./types/protocol": {
18
- "import": "./dist/types/protocol.js",
19
- "types": "./dist/types/protocol.d.ts"
20
- },
21
- "./types/events": {
22
- "import": "./dist/types/events.js",
23
- "types": "./dist/types/events.d.ts"
24
- },
25
- "./schemas": {
26
- "import": "./dist/schemas/index.js",
27
- "types": "./dist/schemas/index.d.ts"
28
- },
29
- "./messages": {
30
- "import": "./dist/messages/BrokerMessages.js",
31
- "types": "./dist/messages/BrokerMessages.d.ts"
32
12
  }
33
13
  },
34
14
  "files": [
@@ -41,6 +21,11 @@
41
21
  "build": "npm run clean && tsc",
42
22
  "build:watch": "tsc --watch",
43
23
  "typecheck": "tsc --noEmit",
24
+ "pretest": "npm run build",
25
+ "test": "vitest run",
26
+ "test:watch": "vitest",
27
+ "test:ui": "vitest --ui",
28
+ "test:coverage": "vitest run --coverage",
44
29
  "lint": "eslint 'src/**/*.{js,ts}'",
45
30
  "lint:fix": "eslint 'src/**/*.{js,ts}' --fix",
46
31
  "format": "prettier --write .",
@@ -56,22 +41,22 @@
56
41
  ],
57
42
  "license": "MIT",
58
43
  "dependencies": {
59
- "chalk": "^5.5.0",
60
- "debug": "^4.4.1",
61
- "events": "^3.3.0",
62
44
  "ws": "^8.16.0",
63
- "zod": "^4.1.5"
45
+ "zod": "^4.1.13"
64
46
  },
65
47
  "devDependencies": {
66
- "@types/debug": "^4.1.12",
67
48
  "@types/node": "^20.19.11",
68
49
  "@types/ws": "^8.18.1",
69
50
  "@typescript-eslint/eslint-plugin": "^7.18.0",
70
51
  "@typescript-eslint/parser": "^7.18.0",
52
+ "@vitest/coverage-v8": "^3.2.4",
53
+ "@vitest/ui": "^3.2.4",
71
54
  "eslint": "^8.57.1",
72
55
  "eslint-config-prettier": "^9.1.2",
73
56
  "eslint-plugin-prettier": "^5.5.4",
74
57
  "prettier": "^3.6.2",
75
- "typescript": "^5.9.2"
58
+ "tsx": "^4.20.6",
59
+ "typescript": "^5.9.2",
60
+ "vitest": "^3.2.4"
76
61
  }
77
62
  }
@@ -1,432 +0,0 @@
1
- import { EventEmitter } from 'events';
2
- import { JSONSchema, BrokerConnection } from './types/core.js';
3
- import type { TransportKind } from './types/core.js';
4
- import { LoadedAbility } from './loadAbility.js';
5
- export interface KadiClientConfig {
6
- /** Agent display name for identification */
7
- name?: string;
8
- /** Agent version string */
9
- version?: string;
10
- /** Human-readable description of the agent */
11
- description?: string;
12
- /** Role when connecting to broker - determines available operations */
13
- role?: 'agent' | 'ability';
14
- /** Transport used when serving requests */
15
- transport?: TransportKind;
16
- /** Primary network segment for message routing - defines which network this client operates in. Used for isolation and access control between different environments. */
17
- network?: string;
18
- /** Additional network identifiers this client belongs to - enables participation in multiple network segments simultaneously */
19
- networks?: string[];
20
- /** Named broker configurations - enables connection to multiple brokers simultaneously */
21
- brokers?: {
22
- [brokerName: string]: string;
23
- };
24
- /** Default broker name for message routing when no specific broker is targeted */
25
- defaultBroker?: string;
26
- /** Maximum buffer size for message handling (primarily for stdio protocol) */
27
- maxBufferSize?: number;
28
- /** Path to ability agent.json configuration file */
29
- abilityAgentJSON?: string;
30
- }
31
- export interface ToolSchema {
32
- name?: string;
33
- description?: string;
34
- inputSchema?: JSONSchema;
35
- outputSchema?: JSONSchema;
36
- }
37
- type ToolHandler = (params: unknown) => Promise<unknown>;
38
- interface RegisteredTool {
39
- name: string;
40
- handler: ToolHandler;
41
- schema?: ToolSchema;
42
- }
43
- /**
44
- * KadiClient - Unified client for KADI protocol
45
- *
46
- * This class combines the functionality of KadiAgent and KadiAbility,
47
- * providing a single interface for:
48
- *
49
- * 1. Registering tools that can be called by others
50
- * 2. Calling remote tools on other services
51
- * 3. Supporting multiple protocols (native, stdio, broker)
52
- * 4. Connecting to broker with configurable role (agent, ability, service)
53
- *
54
- * @example
55
- * ```typescript
56
- * // Create as an ability
57
- * const service = new KadiClient({
58
- * name: 'math-service',
59
- * role: 'ability',
60
- * protocol: 'broker'
61
- * });
62
- *
63
- * // Register tools
64
- * service.registerTool('add', async ({a, b}) => ({result: a + b}));
65
- *
66
- * // With schema
67
- * service.tool('multiply', async ({a, b}) => ({result: a * b}));
68
- *
69
- * // Start serving
70
- * await service.serve();
71
- * ```
72
- */
73
- export declare class KadiClient extends EventEmitter {
74
- readonly name: string;
75
- readonly version: string;
76
- readonly description: string;
77
- readonly role: 'agent' | 'ability';
78
- transport: TransportKind;
79
- readonly network: string;
80
- readonly networks: string[];
81
- readonly brokers: {
82
- [brokerName: string]: string;
83
- };
84
- readonly defaultBroker?: string;
85
- readonly abilityAgentJSON?: string;
86
- private readonly logger;
87
- private transportHandler?;
88
- readonly toolHandlers: Map<string, RegisteredTool>;
89
- private readonly _abilities;
90
- private readonly _brokerConnections;
91
- private _isConnected;
92
- private _agentId;
93
- private _idFactory;
94
- private _pendingResponses;
95
- private _pendingToolCalls;
96
- private _currentBroker?;
97
- /**
98
- * Resolver function for the native protocol serve promise.
99
- * When serve() is called with native protocol, it creates a promise to keep
100
- * the process alive. This resolver allows us to resolve that promise during
101
- * disconnect(), enabling clean shutdown of native abilities.
102
- */
103
- private _nativeServePromiseResolve?;
104
- /**
105
- * Stores all event subscriptions as a Map of pattern → array of callback functions
106
- * Example structure:
107
- * {
108
- * 'user.login' => [handleLogin, logLoginEvent], // 2 functions listening to user.login
109
- * 'payment.*' => [processPayment], // 1 function listening to all payment events
110
- * 'system.shutdown' => [saveState, cleanupResources] // 2 functions for shutdown
111
- * }
112
- * When an event arrives, we check which patterns match and call all their callbacks
113
- */
114
- private _eventSubscriptions;
115
- constructor(options?: KadiClientConfig);
116
- /**
117
- * Get the currently active broker name
118
- */
119
- get currentBroker(): string | undefined;
120
- /**
121
- * Set the currently active broker
122
- * @param brokerName The name of the broker to use
123
- * @throws Error if the broker name doesn't exist in configuration
124
- */
125
- setCurrentBroker(brokerName: string): void;
126
- /**
127
- * Get the current broker's connection (if connected)
128
- */
129
- private getCurrentBrokerConnection;
130
- /**
131
- * Resolve broker configuration with agent.json integration
132
- * Precedence: Code brokers > agent.json brokers > environment defaults
133
- */
134
- private resolveBrokerConfiguration;
135
- /**
136
- * Resolve default broker with fallback logic
137
- * Priority: Explicit defaultBroker > agent.json defaultBroker > 'prod' key > first broker key
138
- */
139
- private resolveDefaultBroker;
140
- /**
141
- * Register a tool for this service
142
- *
143
- * @param name - Tool name
144
- * @param handler - Handler function
145
- * @param schema - Optional schema
146
- * @returns This instance for chaining
147
- */
148
- registerTool(name: string, handler: ToolHandler, schema?: ToolSchema): this;
149
- /**
150
- * Get all registered tool names
151
- */
152
- getToolNames(): string[];
153
- /**
154
- * Get all registered tools (agent compatibility)
155
- */
156
- getTools(): string[];
157
- /**
158
- * Check if a tool is registered
159
- */
160
- hasTool(name: string): boolean;
161
- /**
162
- * Get tool handler
163
- */
164
- getToolHandler(name: string): ToolHandler | undefined;
165
- /**
166
- * Get tool schema
167
- */
168
- getToolSchema(name: string): ToolSchema | undefined;
169
- /**
170
- * Publish an event
171
- */
172
- publishEvent(eventName: string, data?: any): void;
173
- /**
174
- * Connect to all configured brokers (for event subscription and/or broker protocol)
175
- * Always connects to ALL brokers defined in this.brokers for maximum redundancy
176
- */
177
- connectToBrokers(): Promise<void>;
178
- /**
179
- * Check if connected to a specific broker URL
180
- */
181
- isConnectedToBroker(url: string): boolean;
182
- /**
183
- * Connect to a single broker
184
- */
185
- connectToBroker(url: string, brokerName?: string): Promise<void>;
186
- /**
187
- * Perform KADI protocol handshake
188
- */
189
- private performHandshake;
190
- /**
191
- * Start heartbeat to keep broker connection alive
192
- * Sends ping messages at the specified interval to prevent timeout
193
- */
194
- private startHeartbeat;
195
- /**
196
- * Register capabilities with broker
197
- */
198
- private registerCapabilities;
199
- /**
200
- * Send request to broker and wait for response
201
- */
202
- private sendRequest;
203
- /**
204
- * Handle incoming broker messages
205
- */
206
- private handleBrokerMessage;
207
- /**
208
- * Handle tool invocation result from broker
209
- */
210
- private handleToolResult;
211
- /**
212
- * Handle incoming tool invocation request
213
- */
214
- private handleToolInvocation;
215
- /**
216
- * Extract tool definitions for broker registration
217
- */
218
- private extractToolsForBroker;
219
- /**
220
- * Start serving (main entry point)
221
- *
222
- * @param options - Optional serve options
223
- */
224
- serve(): Promise<void>;
225
- /**
226
- * Start the client (alias for serve for agent compatibility)
227
- */
228
- start(): Promise<void>;
229
- /**
230
- * Discover tools available from a remote agent
231
- *
232
- * This function queries the broker to find what tools
233
- * a specific remote agent provides.
234
- *
235
- * @param targetAgent - The name of the agent to discover tools from
236
- * @returns Array of tool names available from the target agent
237
- */
238
- discoverRemoteTools(targetAgent: string): Promise<string[]>;
239
- /**
240
- * Call a tool on a remote agent via the broker
241
- *
242
- * This function sends an RPC call through the broker to invoke
243
- * a specific tool on a remote agent.
244
- *
245
- * @param targetAgent - The name of the agent that has the tool
246
- * @param toolName - The tool name to invoke
247
- * @param params - The parameters to pass to the tool
248
- * @returns The result from the remote tool invocation
249
- */
250
- callTool<TInput = unknown, TOutput = unknown>(targetAgent: string, toolName: string, params?: TInput): Promise<TOutput>;
251
- /**
252
- * Send a request directly to the broker
253
- * Uses the current broker or the specified broker
254
- *
255
- * @param method The RPC method to call (e.g., 'kadi.ability.list')
256
- * @param params The parameters for the method
257
- * @param brokerName Optional broker name to use (overrides current broker)
258
- * @returns The response from the broker
259
- */
260
- sendBrokerRequest(method: string, params?: unknown, brokerName?: string): Promise<unknown>;
261
- /**
262
- * Load an external ability and make its methods available for calling
263
- *
264
- * This is the KadiClient's convenient wrapper for loading abilities. It handles
265
- * broker resolution from your client config and delegates the actual loading
266
- * to the standalone loadAbility() function.
267
- *
268
- * Note: This method delegates to the standalone loadAbility() function after
269
- * resolving broker configurations. If you need more control or don't have a
270
- * KadiClient instance, you can use the standalone loadAbility() function directly.
271
- *
272
- * @param nameOrPath - Which ability to load. Can be:
273
- * - "ability-name" - loads from your installed abilities
274
- * - "/path/to/ability" - loads from a folder path
275
- *
276
- * @param protocol - How to connect to the ability:
277
- * - 'native': Load directly into this process (fastest, same language only)
278
- * - 'stdio': Spawn as child process, communicate via stdin/stdout (any language)
279
- * - 'broker': Connect via broker (ability runs anywhere, most flexible)
280
- *
281
- * @param options - Configuration for how to load the ability:
282
- *
283
- * broker: Which named broker to use (from your KadiClient config). Only for 'broker' protocol.
284
- * Example: 'prod', 'local', 'staging'
285
- * Uses your current/default broker if not specified.
286
- *
287
- * brokerUrl: Direct broker WebSocket URL. Only for 'broker' protocol.
288
- * Example: 'ws://localhost:8080', 'wss://broker.company.com'
289
- * Overrides the 'broker' option if provided.
290
- *
291
- * networks: Which KADI networks to search for the ability. Only for 'broker' protocol.
292
- * Example: ['global', 'team-alpha', 'dev-environment']
293
- * search specific networks to find them. Defaults to ['global'] if not specified.
294
- *
295
- * @returns A proxy object that lets you call the ability's methods directly.
296
- * Example: ability.processData({input: "hello"}) calls the ability's processData method.
297
- *
298
- * @example
299
- * // Load a JavaScript ability in the same process (fastest)
300
- * const mathLib = await client.loadAbility('math-utils', 'native');
301
- * const result = await mathLib.add({a: 5, b: 3}); // Returns 8
302
- *
303
- * @example
304
- * // Load a Go/Python/Rust ability via child process
305
- * const imageProcessor = await client.loadAbility('image-resizer', 'stdio');
306
- * const thumbnail = await imageProcessor.resize({image: buffer, size: '100x100'});
307
- *
308
- * @example
309
- * // Connect to an ability running on a remote broker (using named broker from config)
310
- * const aiService = await client.loadAbility('gpt-analyzer', 'broker', {
311
- * broker: 'prod', // Use the 'prod' broker from KadiClient config
312
- * networks: ['ai-services', 'global'] // Look in these networks
313
- * });
314
- * const analysis = await aiService.analyze({text: "Hello world"});
315
- */
316
- loadAbility(nameOrPath: string, transport?: TransportKind, options?: {
317
- broker?: string;
318
- brokerUrl?: string;
319
- networks?: string[];
320
- }): Promise<LoadedAbility>;
321
- /**
322
- * Disconnect from brokers and cleanup resources
323
- */
324
- disconnect(): Promise<void>;
325
- /**
326
- * Helper to load agent.json exports
327
- */
328
- private _loadAgentJsonExports;
329
- /**
330
- * Find agent.json file
331
- * TODO: Not sure, but maybe this function can be moved to pathUtils.ts?
332
- */
333
- private _findAgentJson;
334
- /**
335
- * Subscribe to events with unified API across all protocols
336
- *
337
- * @param pattern Event pattern - exact string for native/stdio, wildcards supported for broker
338
- * @param callback Function to call when event is received
339
- * @returns Unsubscribe function
340
- */
341
- subscribeToEvent(pattern: string, callback: (data: any) => void): () => void;
342
- /**
343
- * Subscribe to multiple events at once
344
- *
345
- * @param patterns Array of event patterns
346
- * @param callback Function to call when any event is received (receives eventName and data)
347
- * @returns Unsubscribe function that removes all subscriptions
348
- */
349
- subscribeToEvents(patterns: string[], callback: (eventName: string, data: any) => void): () => void;
350
- /**
351
- * Unsubscribe from event pattern
352
- *
353
- * @param pattern Event pattern to unsubscribe from
354
- * @param callback Optional specific callback to remove (if not provided, removes all)
355
- */
356
- unsubscribeFromEvent(pattern: string, callback?: (data: any) => void): void;
357
- /**
358
- * Subscribe to an event only once
359
- *
360
- * @param pattern Event pattern
361
- * @param callback Function to call when event is received (auto-unsubscribes after first call)
362
- */
363
- onceEvent(pattern: string, callback: (data: any) => void): void;
364
- /**
365
- * Setup universal event subscription that works regardless of client protocol
366
- *
367
- * @private
368
- * @param pattern Event pattern to subscribe to
369
- */
370
- /**
371
- * Marker to track if we've already set up the event transport infrastructure
372
- */
373
- private _eventTransportSetup;
374
- /**
375
- * Setup the event transport infrastructure ONCE, then subscribe to specific patterns
376
- * TODO: I do not understand this function very well - better step by step comments
377
- * would be nice.
378
- *
379
- * @private
380
- * @param pattern Event pattern to subscribe to (e.g., 'echo.test-event')
381
- */
382
- private _setupProtocolEventSubscription;
383
- /**
384
- * Subscribe to broker events
385
- *
386
- * @private
387
- * @param pattern Event pattern to subscribe to
388
- */
389
- private _subscribeToBrokerEvent;
390
- /**
391
- * Setup broker event delivery handler
392
- *
393
- * @private
394
- */
395
- private _brokerEventHandlerSetup;
396
- private _setupBrokerEventHandler;
397
- /**
398
- * Clean up protocol-specific event subscription
399
- *
400
- * @private
401
- * @param pattern Event pattern to clean up
402
- */
403
- private _cleanupProtocolEventSubscription;
404
- /**
405
- * Check if event name matches pattern
406
- *
407
- * @private
408
- * @param eventName Event name to check
409
- * @param pattern Pattern to match against (supports wildcards for broker protocol)
410
- * @returns True if matches
411
- */
412
- private _matchesPattern;
413
- /**
414
- * Dispatch event to subscribers - This is the final delivery step
415
- *
416
- * After all the routing through transports and pattern matching,
417
- * this function actually calls the user's callback functions with the event data.
418
- *
419
- * Example: If user did `client.subscribeToEvent('user.login', myFunction)`
420
- * then when 'user.login' event arrives, this calls `myFunction(eventData)`
421
- *
422
- * @private
423
- * @param pattern Pattern that matched (e.g., 'user.login' or 'payment.*')
424
- * @param data Event data to pass to the callbacks
425
- */
426
- private _dispatchEvent;
427
- get isConnected(): boolean;
428
- get agentId(): string;
429
- get broker(): BrokerConnection | undefined;
430
- }
431
- export default KadiClient;
432
- //# sourceMappingURL=KadiClient.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"KadiClient.d.ts","sourceRoot":"","sources":["../src/KadiClient.ts"],"names":[],"mappings":"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"}