@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
@@ -0,0 +1,664 @@
1
+ /**
2
+ * Core type definitions for kadi-core v0.1.0
3
+ *
4
+ * This file contains ALL types used throughout the codebase.
5
+ * Having types in one place makes them easy to find and understand.
6
+ *
7
+ * Organization:
8
+ * 1. Configuration - ClientConfig and related
9
+ * 2. Tools - Tool definitions and handlers
10
+ * 3. Loaded Abilities - The interface for using abilities
11
+ * 4. Broker State - Internal broker connection state
12
+ * 5. JSON-RPC - Protocol message types
13
+ * 6. Lock File - agent-lock.json structure
14
+ */
15
+ import type { ZodType } from 'zod';
16
+ import type { JSONSchema as JSONSchemaTypes } from 'zod/v4/core';
17
+ import type { WebSocket } from 'ws';
18
+ /**
19
+ * JSON Schema type from Zod 4.
20
+ * This is what z.toJSONSchema() returns for a single schema.
21
+ */
22
+ export type JSONSchema = JSONSchemaTypes.JSONSchema;
23
+ /**
24
+ * Configuration options for creating a KadiClient.
25
+ *
26
+ * @example
27
+ * ```typescript
28
+ * const client = new KadiClient({
29
+ * name: 'my-agent',
30
+ * version: '1.0.0',
31
+ * brokers: {
32
+ * prod: 'ws://broker-prod:8080',
33
+ * internal: 'ws://broker-internal:8080',
34
+ * },
35
+ * defaultBroker: 'prod',
36
+ * });
37
+ * ```
38
+ */
39
+ export interface ClientConfig {
40
+ /** Name of this agent (required) */
41
+ name: string;
42
+ /** Version of this agent (default: '1.0.0') */
43
+ version?: string;
44
+ /** Description of what this agent does */
45
+ description?: string;
46
+ /**
47
+ * Named brokers to connect to.
48
+ * Keys are friendly names, values are WebSocket URLs.
49
+ *
50
+ * @example
51
+ * ```typescript
52
+ * brokers: {
53
+ * prod: 'ws://broker-prod:8080',
54
+ * staging: 'ws://broker-staging:8080',
55
+ * }
56
+ * ```
57
+ */
58
+ brokers?: Record<string, string>;
59
+ /**
60
+ * Which broker to use by default for invokeRemote() and loadBroker().
61
+ * Must be a key from the brokers map.
62
+ */
63
+ defaultBroker?: string;
64
+ /**
65
+ * Networks this agent belongs to.
66
+ * Used for filtering when discovering abilities.
67
+ * Default: ['global']
68
+ */
69
+ networks?: string[];
70
+ /**
71
+ * Heartbeat interval in milliseconds.
72
+ * Broker expects heartbeats to stay connected.
73
+ * Default: 25000 (25 seconds)
74
+ */
75
+ heartbeatInterval?: number;
76
+ /**
77
+ * Timeout for remote requests in milliseconds.
78
+ * Default: 30000 (30 seconds)
79
+ */
80
+ requestTimeout?: number;
81
+ /**
82
+ * Automatically reconnect to broker if connection is lost.
83
+ * Uses exponential backoff with jitter to prevent thundering herd.
84
+ * Default: true
85
+ */
86
+ autoReconnect?: boolean;
87
+ /**
88
+ * Maximum delay between reconnection attempts in milliseconds.
89
+ * Backoff doubles each attempt: 1s → 2s → 4s → ... → maxReconnectDelay
90
+ * Default: 30000 (30 seconds)
91
+ */
92
+ maxReconnectDelay?: number;
93
+ }
94
+ /**
95
+ * Resolved configuration with all defaults applied.
96
+ * Internal use - users work with ClientConfig.
97
+ */
98
+ export interface ResolvedConfig {
99
+ name: string;
100
+ version: string;
101
+ description: string;
102
+ brokers: Record<string, string>;
103
+ defaultBroker: string | undefined;
104
+ networks: string[];
105
+ heartbeatInterval: number;
106
+ requestTimeout: number;
107
+ autoReconnect: boolean;
108
+ maxReconnectDelay: number;
109
+ }
110
+ /**
111
+ * Tool definition using JSON Schema (from Zod 4).
112
+ * Prefer ZodToolDefinition for type safety.
113
+ */
114
+ export interface ToolDefinition {
115
+ /** Unique name for this tool */
116
+ name: string;
117
+ /** Human-readable description of what this tool does */
118
+ description: string;
119
+ /** JSON Schema for input parameters (must be type: 'object') */
120
+ inputSchema: JSONSchema;
121
+ /** JSON Schema for output (optional, must be type: 'object' if provided) */
122
+ outputSchema?: JSONSchema;
123
+ }
124
+ /**
125
+ * Tool definition using Zod schemas.
126
+ * Recommended approach - provides type inference.
127
+ *
128
+ * @example
129
+ * ```typescript
130
+ * client.registerTool({
131
+ * name: 'add',
132
+ * description: 'Add two numbers',
133
+ * input: z.object({ a: z.number(), b: z.number() }),
134
+ * output: z.object({ result: z.number() }),
135
+ * }, async ({ a, b }) => ({ result: a + b }));
136
+ * ```
137
+ */
138
+ export interface ZodToolDefinition<TInput, TOutput> {
139
+ /** Unique name for this tool */
140
+ name: string;
141
+ /** Human-readable description of what this tool does */
142
+ description: string;
143
+ /** Zod schema for input parameters */
144
+ input: ZodType<TInput>;
145
+ /** Zod schema for output (optional) */
146
+ output?: ZodType<TOutput>;
147
+ }
148
+ /**
149
+ * Function that handles tool invocation.
150
+ * Receives validated input, returns output.
151
+ */
152
+ export type ToolHandler<TInput = unknown, TOutput = unknown> = (input: TInput) => Promise<TOutput>;
153
+ /**
154
+ * A tool that has been registered with the client.
155
+ * Internal use - tracks registration metadata.
156
+ */
157
+ export interface RegisteredTool {
158
+ /** The tool definition (with JSON Schema, not Zod) */
159
+ definition: ToolDefinition;
160
+ /** The handler function */
161
+ handler: ToolHandler;
162
+ /** When this tool was registered */
163
+ registeredAt: Date;
164
+ /** Which brokers this tool is registered with (empty = all) */
165
+ targetBrokers: string[];
166
+ }
167
+ /**
168
+ * Transport type for loaded abilities.
169
+ * - native: In-process (same Node.js process)
170
+ * - stdio: Child process (JSON-RPC over stdin/stdout)
171
+ * - broker: Remote (via broker WebSocket)
172
+ */
173
+ export type TransportType = 'native' | 'stdio' | 'broker';
174
+ /**
175
+ * A loaded ability that can be invoked.
176
+ * This is the interface you work with after loading an ability.
177
+ *
178
+ * @example
179
+ * ```typescript
180
+ * const calc = await client.loadNative('calculator');
181
+ * const result = await calc.invoke('add', { a: 5, b: 3 });
182
+ * console.log(result); // { result: 8 }
183
+ * ```
184
+ */
185
+ /**
186
+ * Event handler function type.
187
+ */
188
+ export type EventHandler = (data: unknown) => void | Promise<void>;
189
+ export interface LoadedAbility {
190
+ /** Name of the ability */
191
+ readonly name: string;
192
+ /** How this ability is connected */
193
+ readonly transport: TransportType;
194
+ /**
195
+ * Invoke a tool on this ability.
196
+ * This is the main way to call tools.
197
+ *
198
+ * @param toolName - Name of the tool to invoke
199
+ * @param params - Input parameters for the tool
200
+ * @returns The tool's output
201
+ */
202
+ invoke<T = unknown>(toolName: string, params: unknown): Promise<T>;
203
+ /**
204
+ * Get list of tools this ability provides.
205
+ * Useful for discovery and debugging.
206
+ */
207
+ getTools(): ToolDefinition[];
208
+ /**
209
+ * Subscribe to events from this ability.
210
+ *
211
+ * @param event - Event name to listen for
212
+ * @param handler - Function called when event fires
213
+ *
214
+ * @example
215
+ * ```typescript
216
+ * ability.on('file.changed', (data) => {
217
+ * console.log('File changed:', data.path);
218
+ * });
219
+ * ```
220
+ */
221
+ on(event: string, handler: EventHandler): void;
222
+ /**
223
+ * Unsubscribe from events.
224
+ *
225
+ * @param event - Event name to stop listening for
226
+ * @param handler - The handler function to remove
227
+ */
228
+ off(event: string, handler: EventHandler): void;
229
+ /**
230
+ * Disconnect and cleanup.
231
+ * For stdio: kills the child process.
232
+ * For broker: nothing (broker connection managed by client).
233
+ * For native: nothing (shares process).
234
+ */
235
+ disconnect(): Promise<void>;
236
+ }
237
+ /**
238
+ * Connection status for a broker.
239
+ *
240
+ * States:
241
+ * - disconnected: Not connected
242
+ * - connecting: Initial connection in progress
243
+ * - connected: Connected and authenticated
244
+ * - disconnecting: User-initiated disconnect in progress
245
+ * - reconnecting: Auto-reconnecting after unexpected disconnect
246
+ */
247
+ export type BrokerStatus = 'disconnected' | 'connecting' | 'connected' | 'disconnecting' | 'reconnecting';
248
+ /**
249
+ * Internal state for a single broker connection.
250
+ * Managed by KadiClient - not exposed to users.
251
+ */
252
+ export interface BrokerState {
253
+ /** Friendly name for this broker (from config) */
254
+ name: string;
255
+ /** WebSocket URL */
256
+ url: string;
257
+ /** WebSocket connection (null if disconnected) */
258
+ ws: WebSocket | null;
259
+ /** Agent ID assigned by broker after authentication */
260
+ agentId: string;
261
+ /** Ed25519 public key (DER format) */
262
+ publicKey: Buffer;
263
+ /** Ed25519 private key (DER format) */
264
+ privateKey: Buffer;
265
+ /** Heartbeat timer (null if not running) */
266
+ heartbeatTimer: ReturnType<typeof setInterval> | null;
267
+ /**
268
+ * Pending JSON-RPC requests waiting for responses.
269
+ * Keyed by JSON-RPC message id.
270
+ * Used for: hello, authenticate, register, heartbeat.
271
+ */
272
+ pendingRequests: Map<string | number, PendingRequest>;
273
+ /**
274
+ * Pending tool invocations waiting for result notifications.
275
+ * Keyed by requestId (from the "pending" acknowledgment).
276
+ * Used for: invokeRemote() async pattern.
277
+ */
278
+ pendingInvocations: Map<string, PendingInvocation>;
279
+ /** Current connection status */
280
+ status: BrokerStatus;
281
+ /**
282
+ * True if disconnect was intentional (user called disconnect()).
283
+ * When false, unexpected close triggers auto-reconnect.
284
+ */
285
+ intentionalDisconnect: boolean;
286
+ /**
287
+ * Current reconnection attempt number.
288
+ * Reset to 0 on successful connection.
289
+ */
290
+ reconnectAttempts: number;
291
+ /**
292
+ * Timer for scheduled reconnection attempt.
293
+ * Null when not reconnecting.
294
+ */
295
+ reconnectTimer: ReturnType<typeof setTimeout> | null;
296
+ /**
297
+ * Local handlers for each subscribed pattern.
298
+ * Pattern → Set of handler functions.
299
+ *
300
+ * This is CLIENT-SIDE tracking. When we subscribe to 'user.*' on the broker,
301
+ * we store the handlers here so we can dispatch incoming events locally.
302
+ */
303
+ eventHandlers: Map<string, Set<BrokerEventHandler>>;
304
+ /**
305
+ * Patterns that are currently subscribed on the broker.
306
+ * Used to track broker-side subscriptions (separate from local handlers).
307
+ *
308
+ * This exists because multiple handlers can subscribe to the same pattern,
309
+ * but we only need ONE broker subscription per pattern.
310
+ */
311
+ subscribedPatterns: Set<string>;
312
+ }
313
+ /**
314
+ * A request waiting for a response from the broker.
315
+ * Used for JSON-RPC request/response matching (e.g., hello, auth, register).
316
+ */
317
+ export interface PendingRequest {
318
+ /** Resolve the promise with the result */
319
+ resolve: (value: unknown) => void;
320
+ /** Reject the promise with an error */
321
+ reject: (error: Error) => void;
322
+ /** Timeout timer */
323
+ timeout: ReturnType<typeof setTimeout>;
324
+ /** Method name (for error messages) */
325
+ method: string;
326
+ /** When the request was sent */
327
+ sentAt: Date;
328
+ }
329
+ /**
330
+ * A tool invocation waiting for its result notification.
331
+ *
332
+ * This is separate from PendingRequest because tool invocations use
333
+ * a different async pattern:
334
+ *
335
+ * 1. Client sends kadi.ability.request → broker returns { status: 'pending', requestId }
336
+ * 2. Broker forwards to provider → provider executes → sends result back
337
+ * 3. Broker sends kadi.ability.response notification to client with the result
338
+ *
339
+ * The key is requestId (from step 1), not the JSON-RPC message id.
340
+ */
341
+ export interface PendingInvocation {
342
+ /** Resolve the promise with the tool result */
343
+ resolve: (value: unknown) => void;
344
+ /** Reject the promise with an error */
345
+ reject: (error: Error) => void;
346
+ /** Timeout timer */
347
+ timeout: ReturnType<typeof setTimeout>;
348
+ /** Tool name (for error messages) */
349
+ toolName: string;
350
+ /** When the invocation was sent */
351
+ sentAt: Date;
352
+ }
353
+ /**
354
+ * JSON-RPC 2.0 request message.
355
+ * Used for communication with broker and stdio abilities.
356
+ */
357
+ export interface JsonRpcRequest {
358
+ jsonrpc: '2.0';
359
+ id: string | number;
360
+ method: string;
361
+ params?: unknown;
362
+ }
363
+ /**
364
+ * JSON-RPC 2.0 response message.
365
+ */
366
+ export interface JsonRpcResponse {
367
+ jsonrpc: '2.0';
368
+ id: string | number;
369
+ result?: unknown;
370
+ error?: JsonRpcError;
371
+ }
372
+ /**
373
+ * JSON-RPC 2.0 notification (no id, no response expected).
374
+ */
375
+ export interface JsonRpcNotification {
376
+ jsonrpc: '2.0';
377
+ method: string;
378
+ params?: unknown;
379
+ }
380
+ /**
381
+ * JSON-RPC 2.0 error object.
382
+ */
383
+ export interface JsonRpcError {
384
+ code: number;
385
+ message: string;
386
+ data?: unknown;
387
+ }
388
+ /**
389
+ * Any JSON-RPC 2.0 message (request, response, or notification).
390
+ * Useful when parsing incoming messages that could be any type.
391
+ */
392
+ export type JsonRpcMessage = JsonRpcRequest | JsonRpcResponse | JsonRpcNotification;
393
+ /**
394
+ * Structure of agent-lock.json file.
395
+ * Generated by kadi-install, consumed by kadi-core for ability resolution.
396
+ */
397
+ export interface AgentLockFile {
398
+ /** Lock file format version */
399
+ lockfileVersion: number;
400
+ /** Metadata about when/how this was generated */
401
+ metadata: {
402
+ /** ISO 8601 timestamp of generation */
403
+ generated: string;
404
+ /** SHA256 hash of agent.json abilities section (for change detection) */
405
+ metaHash: string;
406
+ /** KADI version that created this lock file */
407
+ kadiVersion?: string;
408
+ };
409
+ /** Info about the agent this lock file belongs to */
410
+ agent?: {
411
+ name: string;
412
+ version: string;
413
+ };
414
+ /** Map of installed abilities (key format: "name@version") */
415
+ abilities: Record<string, AbilityLockEntry>;
416
+ }
417
+ /**
418
+ * Entry for a single ability in the lock file.
419
+ */
420
+ export interface AbilityLockEntry {
421
+ /** Exact installed version */
422
+ version: string;
423
+ /** Type of package */
424
+ type: 'ability' | 'plugin' | 'agent';
425
+ /** Path where installed (relative to project root) */
426
+ resolved: string;
427
+ /** SHA512 integrity hash of installed files */
428
+ integrity: string;
429
+ /** Whether this is a direct dependency (vs transitive) */
430
+ isTopLevel: boolean;
431
+ /** Original version constraint from agent.json (e.g., "^1.0.0") */
432
+ requestedVersion?: string;
433
+ /** Dependencies of this ability */
434
+ dependencies?: Record<string, string>;
435
+ /** Which abilities depend on this one */
436
+ requiredBy?: string[];
437
+ /** Registry URL where this was downloaded from */
438
+ source?: string;
439
+ }
440
+ /**
441
+ * Options for registerTool().
442
+ */
443
+ export interface RegisterToolOptions {
444
+ /**
445
+ * Which brokers to register this tool with.
446
+ * If not specified, registers with ALL connected brokers.
447
+ *
448
+ * @example
449
+ * ```typescript
450
+ * // Register only on internal broker
451
+ * client.registerTool(def, handler, { brokers: ['internal'] });
452
+ * ```
453
+ */
454
+ brokers?: string[];
455
+ }
456
+ /**
457
+ * Options for loadNative().
458
+ */
459
+ export interface LoadNativeOptions {
460
+ /**
461
+ * Explicit path to the ability.
462
+ * If not provided, resolves from agent-lock.json.
463
+ */
464
+ path?: string;
465
+ /**
466
+ * Project root for lock file resolution.
467
+ * Only used when `path` is not provided.
468
+ * Default: auto-detected by walking up from current directory.
469
+ */
470
+ projectRoot?: string;
471
+ }
472
+ /**
473
+ * Options for loadStdio().
474
+ *
475
+ * Three modes of operation:
476
+ *
477
+ * 1. **Explicit mode** — Provide `command` and `args` directly:
478
+ * ```typescript
479
+ * loadStdio('analyzer', { command: 'python3', args: ['./main.py'] })
480
+ * ```
481
+ *
482
+ * 2. **Script selection mode** — Choose which script from ability's agent.json:
483
+ * ```typescript
484
+ * loadStdio('analyzer', { script: 'dev' }) // Uses scripts.dev
485
+ * ```
486
+ *
487
+ * 3. **Default mode** — Uses scripts.start from ability's agent.json:
488
+ * ```typescript
489
+ * loadStdio('analyzer') // Uses scripts.start
490
+ * ```
491
+ *
492
+ * **Priority**: If `command` is provided, `script` is ignored (explicit mode wins).
493
+ */
494
+ export interface LoadStdioOptions {
495
+ /**
496
+ * Explicit command to run.
497
+ * If provided, bypasses agent.json lookup entirely.
498
+ */
499
+ command?: string;
500
+ /**
501
+ * Arguments to pass to the command.
502
+ * Only used when `command` is provided.
503
+ */
504
+ args?: string[];
505
+ /**
506
+ * Which script to use from the ability's agent.json scripts section.
507
+ * Only used when `command` is not provided.
508
+ * Default: 'start'
509
+ *
510
+ * @example
511
+ * If ability's agent.json has:
512
+ * ```json
513
+ * { "scripts": { "start": "python3 main.py", "dev": "python3 main.py --debug" } }
514
+ * ```
515
+ * Then `{ script: 'dev' }` will run: `python3 main.py --debug`
516
+ */
517
+ script?: string;
518
+ /**
519
+ * Project root for lock file resolution.
520
+ * Only used when `command` is not provided.
521
+ * Default: auto-detected by walking up from current directory.
522
+ */
523
+ projectRoot?: string;
524
+ }
525
+ /**
526
+ * Resolved script ready for spawning a child process.
527
+ * Returned by resolveAbilityScript() after parsing an ability's agent.json.
528
+ */
529
+ export interface ResolvedScript {
530
+ /** The command to execute (e.g., 'python3', 'npx') */
531
+ command: string;
532
+ /** Arguments to pass to the command (e.g., ['main.py', '--debug']) */
533
+ args: string[];
534
+ /** Working directory for the child process (the ability's directory) */
535
+ cwd: string;
536
+ }
537
+ /**
538
+ * Options for loadBroker().
539
+ */
540
+ export interface LoadBrokerOptions {
541
+ /**
542
+ * Which broker to use.
543
+ * If not provided, uses defaultBroker from config.
544
+ */
545
+ broker?: string;
546
+ /**
547
+ * Networks to filter by when discovering the ability.
548
+ */
549
+ networks?: string[];
550
+ }
551
+ /**
552
+ * Options for invokeRemote().
553
+ */
554
+ export interface InvokeRemoteOptions {
555
+ /**
556
+ * Which broker to send the request to.
557
+ * If not provided, uses defaultBroker from config.
558
+ */
559
+ broker?: string;
560
+ /**
561
+ * Timeout in milliseconds.
562
+ * If not provided, uses requestTimeout from config.
563
+ */
564
+ timeout?: number;
565
+ }
566
+ /**
567
+ * An event received from the broker's pub/sub system.
568
+ *
569
+ * When you subscribe to a pattern (e.g., 'user.*'), you receive BrokerEvent
570
+ * objects for each matching event published by any agent in the network.
571
+ *
572
+ * @example
573
+ * ```typescript
574
+ * client.subscribe('user.*', (event: BrokerEvent) => {
575
+ * console.log(event.channel); // 'user.login'
576
+ * console.log(event.data); // { userId: '123' }
577
+ * console.log(event.networkId); // 'global'
578
+ * console.log(event.source); // Publisher's session ID
579
+ * });
580
+ * ```
581
+ */
582
+ export interface BrokerEvent {
583
+ /**
584
+ * The channel/topic this event was published to.
585
+ * This is the exact channel name (e.g., 'user.login'), not the pattern
586
+ * you subscribed to (e.g., 'user.*').
587
+ */
588
+ channel: string;
589
+ /**
590
+ * The event payload.
591
+ * Can be any JSON-serializable data the publisher sent.
592
+ */
593
+ data: unknown;
594
+ /**
595
+ * Which network this event was published to.
596
+ * Events are scoped to networks - you only receive events from
597
+ * networks you're a member of.
598
+ */
599
+ networkId: string;
600
+ /**
601
+ * Session ID of the agent that published this event.
602
+ * Useful for filtering out your own events or identifying the source.
603
+ */
604
+ source: string;
605
+ /**
606
+ * Unix timestamp (milliseconds) when the event was published.
607
+ */
608
+ timestamp: number;
609
+ }
610
+ /**
611
+ * Handler function for broker events.
612
+ *
613
+ * @example
614
+ * ```typescript
615
+ * const handler: BrokerEventHandler = (event) => {
616
+ * console.log(`Received ${event.channel} from ${event.source}`);
617
+ * };
618
+ * client.subscribe('chat.*', handler);
619
+ * ```
620
+ */
621
+ export type BrokerEventHandler = (event: BrokerEvent) => void | Promise<void>;
622
+ /**
623
+ * Options for publishing events via the broker.
624
+ */
625
+ export interface PublishOptions {
626
+ /**
627
+ * Which network to publish to.
628
+ * You must be a member of this network to publish to it.
629
+ *
630
+ * If not specified:
631
+ * - Uses the first network from your config.networks array
632
+ * - If you have no networks configured, uses 'global'
633
+ *
634
+ * @example
635
+ * ```typescript
636
+ * // Publish to specific network
637
+ * await client.publish('order.created', data, { network: 'internal' });
638
+ *
639
+ * // Publish to default network
640
+ * await client.publish('order.created', data);
641
+ * ```
642
+ */
643
+ network?: string;
644
+ /**
645
+ * Which broker to publish through.
646
+ * If not specified, uses defaultBroker from config.
647
+ */
648
+ broker?: string;
649
+ }
650
+ /**
651
+ * Options for subscribing to broker events.
652
+ */
653
+ export interface SubscribeOptions {
654
+ /**
655
+ * Which broker to subscribe through.
656
+ * If not specified, uses defaultBroker from config.
657
+ *
658
+ * Note: Subscriptions apply to ALL networks you're a member of on that broker.
659
+ * You cannot subscribe to only specific networks - network filtering is done
660
+ * at the broker level based on your session's network membership.
661
+ */
662
+ broker?: string;
663
+ }
664
+ //# sourceMappingURL=types.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
package/dist/types.js ADDED
@@ -0,0 +1,16 @@
1
+ /**
2
+ * Core type definitions for kadi-core v0.1.0
3
+ *
4
+ * This file contains ALL types used throughout the codebase.
5
+ * Having types in one place makes them easy to find and understand.
6
+ *
7
+ * Organization:
8
+ * 1. Configuration - ClientConfig and related
9
+ * 2. Tools - Tool definitions and handlers
10
+ * 3. Loaded Abilities - The interface for using abilities
11
+ * 4. Broker State - Internal broker connection state
12
+ * 5. JSON-RPC - Protocol message types
13
+ * 6. Lock File - agent-lock.json structure
14
+ */
15
+ export {};
16
+ //# sourceMappingURL=types.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG"}