@holokai/neuron-sdk 0.5.1 → 0.7.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 (12) hide show
  1. package/README.md +24 -1
  2. package/dist/index.d.mts +25 -3
  3. package/dist/index.d.ts +25 -3
  4. package/dist/index.js +57 -17
  5. package/dist/index.js.map +1 -1
  6. package/dist/index.mjs +57 -18
  7. package/dist/index.mjs.map +1 -1
  8. package/dist/ipc.d.mts +1 -1
  9. package/dist/ipc.d.ts +1 -1
  10. package/dist/{transport-Ckcwj-Do.d.mts → transport-BhFVHvR7.d.mts} +138 -11
  11. package/dist/{transport-Ckcwj-Do.d.ts → transport-BhFVHvR7.d.ts} +138 -11
  12. package/package.json +1 -1
package/dist/{transport-Ckcwj-Do.d.mts → transport-BhFVHvR7.d.mts} RENAMED
@@ -3,7 +3,7 @@ import { z } from 'zod';
3
3
  /** Opaque JSON Schema; runtime structure handled by ajv at the gateway. */
4
4
  type JsonSchema = unknown;
5
5
 
6
- declare const CapabilitySchema: z.ZodObject<{
6
+ declare const CapabilitySchema: z.ZodEffects<z.ZodObject<{
7
7
  type: z.ZodString;
8
8
  scope: z.ZodUnion<[z.ZodLiteral<"any">, z.ZodObject<{
9
9
  onBehalfOf: z.ZodString;
@@ -48,6 +48,13 @@ declare const CapabilitySchema: z.ZodObject<{
48
48
  * capability).
49
49
  */
50
50
  leaseTtlMs: z.ZodOptional<z.ZodNumber>;
51
+ /**
52
+ * Capability types this `skill/*` capability composes (HOL-4326).
53
+ * Only valid on a `skill/*` type — enforced below, since a non-skill
54
+ * type carrying `composes` is a modeling error the gateway should
55
+ * reject rather than silently ignore.
56
+ */
57
+ composes: z.ZodOptional<z.ZodEffects<z.ZodEffects<z.ZodArray<z.ZodString, "many">, string[], string[]>, string[], string[]>>;
51
58
  }, "strict", z.ZodTypeAny, {
52
59
  type: string;
53
60
  scope: "any" | {
@@ -58,6 +65,29 @@ declare const CapabilitySchema: z.ZodObject<{
58
65
  inputSchema?: unknown;
59
66
  outputSchema?: unknown;
60
67
  leaseTtlMs?: number | undefined;
68
+ composes?: string[] | undefined;
69
+ }, {
70
+ type: string;
71
+ scope: "any" | {
72
+ onBehalfOf: string;
73
+ };
74
+ concurrency: number;
75
+ description?: string | undefined;
76
+ inputSchema?: unknown;
77
+ outputSchema?: unknown;
78
+ leaseTtlMs?: number | undefined;
79
+ composes?: string[] | undefined;
80
+ }>, {
81
+ type: string;
82
+ scope: "any" | {
83
+ onBehalfOf: string;
84
+ };
85
+ concurrency: number;
86
+ description?: string | undefined;
87
+ inputSchema?: unknown;
88
+ outputSchema?: unknown;
89
+ leaseTtlMs?: number | undefined;
90
+ composes?: string[] | undefined;
61
91
  }, {
62
92
  type: string;
63
93
  scope: "any" | {
@@ -68,6 +98,7 @@ declare const CapabilitySchema: z.ZodObject<{
68
98
  inputSchema?: unknown;
69
99
  outputSchema?: unknown;
70
100
  leaseTtlMs?: number | undefined;
101
+ composes?: string[] | undefined;
71
102
  }>;
72
103
  type Capability = z.infer<typeof CapabilitySchema>;
73
104
 
@@ -162,7 +193,7 @@ declare const RegisterFrameSchema: z.ZodObject<{
162
193
  type: z.ZodLiteral<"register">;
163
194
  neuronId: z.ZodString;
164
195
  protocolVersion: z.ZodString;
165
- capabilities: z.ZodEffects<z.ZodArray<z.ZodObject<{
196
+ capabilities: z.ZodEffects<z.ZodArray<z.ZodEffects<z.ZodObject<{
166
197
  type: z.ZodString;
167
198
  scope: z.ZodUnion<[z.ZodLiteral<"any">, z.ZodObject<{
168
199
  onBehalfOf: z.ZodString;
@@ -176,6 +207,7 @@ declare const RegisterFrameSchema: z.ZodObject<{
176
207
  inputSchema: z.ZodOptional<z.ZodEffects<z.ZodUnknown, unknown, unknown>>;
177
208
  outputSchema: z.ZodOptional<z.ZodEffects<z.ZodUnknown, unknown, unknown>>;
178
209
  leaseTtlMs: z.ZodOptional<z.ZodNumber>;
210
+ composes: z.ZodOptional<z.ZodEffects<z.ZodEffects<z.ZodArray<z.ZodString, "many">, string[], string[]>, string[], string[]>>;
179
211
  }, "strict", z.ZodTypeAny, {
180
212
  type: string;
181
213
  scope: "any" | {
@@ -186,6 +218,7 @@ declare const RegisterFrameSchema: z.ZodObject<{
186
218
  inputSchema?: unknown;
187
219
  outputSchema?: unknown;
188
220
  leaseTtlMs?: number | undefined;
221
+ composes?: string[] | undefined;
189
222
  }, {
190
223
  type: string;
191
224
  scope: "any" | {
@@ -196,6 +229,29 @@ declare const RegisterFrameSchema: z.ZodObject<{
196
229
  inputSchema?: unknown;
197
230
  outputSchema?: unknown;
198
231
  leaseTtlMs?: number | undefined;
232
+ composes?: string[] | undefined;
233
+ }>, {
234
+ type: string;
235
+ scope: "any" | {
236
+ onBehalfOf: string;
237
+ };
238
+ concurrency: number;
239
+ description?: string | undefined;
240
+ inputSchema?: unknown;
241
+ outputSchema?: unknown;
242
+ leaseTtlMs?: number | undefined;
243
+ composes?: string[] | undefined;
244
+ }, {
245
+ type: string;
246
+ scope: "any" | {
247
+ onBehalfOf: string;
248
+ };
249
+ concurrency: number;
250
+ description?: string | undefined;
251
+ inputSchema?: unknown;
252
+ outputSchema?: unknown;
253
+ leaseTtlMs?: number | undefined;
254
+ composes?: string[] | undefined;
199
255
  }>, "many">, {
200
256
  type: string;
201
257
  scope: "any" | {
@@ -206,6 +262,7 @@ declare const RegisterFrameSchema: z.ZodObject<{
206
262
  inputSchema?: unknown;
207
263
  outputSchema?: unknown;
208
264
  leaseTtlMs?: number | undefined;
265
+ composes?: string[] | undefined;
209
266
  }[], {
210
267
  type: string;
211
268
  scope: "any" | {
@@ -216,6 +273,7 @@ declare const RegisterFrameSchema: z.ZodObject<{
216
273
  inputSchema?: unknown;
217
274
  outputSchema?: unknown;
218
275
  leaseTtlMs?: number | undefined;
276
+ composes?: string[] | undefined;
219
277
  }[]>;
220
278
  }, "strict", z.ZodTypeAny, {
221
279
  type: "register";
@@ -231,6 +289,7 @@ declare const RegisterFrameSchema: z.ZodObject<{
231
289
  inputSchema?: unknown;
232
290
  outputSchema?: unknown;
233
291
  leaseTtlMs?: number | undefined;
292
+ composes?: string[] | undefined;
234
293
  }[];
235
294
  }, {
236
295
  type: "register";
@@ -246,13 +305,14 @@ declare const RegisterFrameSchema: z.ZodObject<{
246
305
  inputSchema?: unknown;
247
306
  outputSchema?: unknown;
248
307
  leaseTtlMs?: number | undefined;
308
+ composes?: string[] | undefined;
249
309
  }[];
250
310
  }>;
251
311
  type RegisterFrame = z.infer<typeof RegisterFrameSchema>;
252
312
  declare const UpdateCapabilityFrameSchema: z.ZodObject<{
253
313
  type: z.ZodLiteral<"update-capability">;
254
314
  neuronId: z.ZodString;
255
- capability: z.ZodObject<{
315
+ capability: z.ZodEffects<z.ZodObject<{
256
316
  type: z.ZodString;
257
317
  scope: z.ZodUnion<[z.ZodLiteral<"any">, z.ZodObject<{
258
318
  onBehalfOf: z.ZodString;
@@ -266,6 +326,7 @@ declare const UpdateCapabilityFrameSchema: z.ZodObject<{
266
326
  inputSchema: z.ZodOptional<z.ZodEffects<z.ZodUnknown, unknown, unknown>>;
267
327
  outputSchema: z.ZodOptional<z.ZodEffects<z.ZodUnknown, unknown, unknown>>;
268
328
  leaseTtlMs: z.ZodOptional<z.ZodNumber>;
329
+ composes: z.ZodOptional<z.ZodEffects<z.ZodEffects<z.ZodArray<z.ZodString, "many">, string[], string[]>, string[], string[]>>;
269
330
  }, "strict", z.ZodTypeAny, {
270
331
  type: string;
271
332
  scope: "any" | {
@@ -276,6 +337,29 @@ declare const UpdateCapabilityFrameSchema: z.ZodObject<{
276
337
  inputSchema?: unknown;
277
338
  outputSchema?: unknown;
278
339
  leaseTtlMs?: number | undefined;
340
+ composes?: string[] | undefined;
341
+ }, {
342
+ type: string;
343
+ scope: "any" | {
344
+ onBehalfOf: string;
345
+ };
346
+ concurrency: number;
347
+ description?: string | undefined;
348
+ inputSchema?: unknown;
349
+ outputSchema?: unknown;
350
+ leaseTtlMs?: number | undefined;
351
+ composes?: string[] | undefined;
352
+ }>, {
353
+ type: string;
354
+ scope: "any" | {
355
+ onBehalfOf: string;
356
+ };
357
+ concurrency: number;
358
+ description?: string | undefined;
359
+ inputSchema?: unknown;
360
+ outputSchema?: unknown;
361
+ leaseTtlMs?: number | undefined;
362
+ composes?: string[] | undefined;
279
363
  }, {
280
364
  type: string;
281
365
  scope: "any" | {
@@ -286,6 +370,7 @@ declare const UpdateCapabilityFrameSchema: z.ZodObject<{
286
370
  inputSchema?: unknown;
287
371
  outputSchema?: unknown;
288
372
  leaseTtlMs?: number | undefined;
373
+ composes?: string[] | undefined;
289
374
  }>;
290
375
  }, "strict", z.ZodTypeAny, {
291
376
  type: "update-capability";
@@ -299,6 +384,7 @@ declare const UpdateCapabilityFrameSchema: z.ZodObject<{
299
384
  inputSchema?: unknown;
300
385
  outputSchema?: unknown;
301
386
  leaseTtlMs?: number | undefined;
387
+ composes?: string[] | undefined;
302
388
  };
303
389
  neuronId: string;
304
390
  }, {
@@ -313,6 +399,7 @@ declare const UpdateCapabilityFrameSchema: z.ZodObject<{
313
399
  inputSchema?: unknown;
314
400
  outputSchema?: unknown;
315
401
  leaseTtlMs?: number | undefined;
402
+ composes?: string[] | undefined;
316
403
  };
317
404
  neuronId: string;
318
405
  }>;
@@ -437,7 +524,7 @@ type ProgressFrame = z.infer<typeof ProgressFrameSchema>;
437
524
  declare const ServerToNeuronFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
438
525
  type: z.ZodLiteral<"registered">;
439
526
  sessionId: z.ZodString;
440
- capabilities: z.ZodArray<z.ZodObject<{
527
+ capabilities: z.ZodArray<z.ZodEffects<z.ZodObject<{
441
528
  type: z.ZodString;
442
529
  scope: z.ZodUnion<[z.ZodLiteral<"any">, z.ZodObject<{
443
530
  onBehalfOf: z.ZodString;
@@ -451,6 +538,7 @@ declare const ServerToNeuronFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
451
538
  inputSchema: z.ZodOptional<z.ZodEffects<z.ZodUnknown, unknown, unknown>>;
452
539
  outputSchema: z.ZodOptional<z.ZodEffects<z.ZodUnknown, unknown, unknown>>;
453
540
  leaseTtlMs: z.ZodOptional<z.ZodNumber>;
541
+ composes: z.ZodOptional<z.ZodEffects<z.ZodEffects<z.ZodArray<z.ZodString, "many">, string[], string[]>, string[], string[]>>;
454
542
  }, "strict", z.ZodTypeAny, {
455
543
  type: string;
456
544
  scope: "any" | {
@@ -461,6 +549,7 @@ declare const ServerToNeuronFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
461
549
  inputSchema?: unknown;
462
550
  outputSchema?: unknown;
463
551
  leaseTtlMs?: number | undefined;
552
+ composes?: string[] | undefined;
464
553
  }, {
465
554
  type: string;
466
555
  scope: "any" | {
@@ -471,6 +560,29 @@ declare const ServerToNeuronFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
471
560
  inputSchema?: unknown;
472
561
  outputSchema?: unknown;
473
562
  leaseTtlMs?: number | undefined;
563
+ composes?: string[] | undefined;
564
+ }>, {
565
+ type: string;
566
+ scope: "any" | {
567
+ onBehalfOf: string;
568
+ };
569
+ concurrency: number;
570
+ description?: string | undefined;
571
+ inputSchema?: unknown;
572
+ outputSchema?: unknown;
573
+ leaseTtlMs?: number | undefined;
574
+ composes?: string[] | undefined;
575
+ }, {
576
+ type: string;
577
+ scope: "any" | {
578
+ onBehalfOf: string;
579
+ };
580
+ concurrency: number;
581
+ description?: string | undefined;
582
+ inputSchema?: unknown;
583
+ outputSchema?: unknown;
584
+ leaseTtlMs?: number | undefined;
585
+ composes?: string[] | undefined;
474
586
  }>, "many">;
475
587
  acceptedAt: z.ZodString;
476
588
  }, "strict", z.ZodTypeAny, {
@@ -485,6 +597,7 @@ declare const ServerToNeuronFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
485
597
  inputSchema?: unknown;
486
598
  outputSchema?: unknown;
487
599
  leaseTtlMs?: number | undefined;
600
+ composes?: string[] | undefined;
488
601
  }[];
489
602
  sessionId: string;
490
603
  acceptedAt: string;
@@ -500,6 +613,7 @@ declare const ServerToNeuronFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
500
613
  inputSchema?: unknown;
501
614
  outputSchema?: unknown;
502
615
  leaseTtlMs?: number | undefined;
616
+ composes?: string[] | undefined;
503
617
  }[];
504
618
  sessionId: string;
505
619
  acceptedAt: string;
@@ -674,6 +788,12 @@ interface NeuronLogger {
674
788
  warn(meta: Record<string, unknown>, msg?: string): void;
675
789
  error(meta: Record<string, unknown>, msg?: string): void;
676
790
  }
791
+ /** What a handler states when it fails a lease; see {@link HandlerContext.fail}. */
792
+ interface HandlerFailureOptions {
793
+ code?: string;
794
+ details?: unknown;
795
+ kind?: 'terminal' | 'retryable';
796
+ }
677
797
  /** Per-handler context passed to `neuron.handle(...)` callbacks. */
678
798
  interface HandlerContext {
679
799
  /** Lease metadata for this delivery. */
@@ -701,13 +821,13 @@ interface HandlerContext {
701
821
  data?: unknown;
702
822
  }): void;
703
823
  /**
704
- * Terminal failure — short-circuits the handler with a non-retryable
705
- * nack containing the given reason. Throws an internal error to bail
706
- * out of the handler; do not catch it.
824
+ * Fail the lease with a nack and bail out of the handler; do not catch the
825
+ * throw. `reason` is the sentence a reader sees; `code` names the failure;
826
+ * `details` carries any structured facts (never required to understand the
827
+ * reason). `kind` defaults to `terminal` (the same input will not succeed);
828
+ * `retryable` says the same input may succeed later.
707
829
  */
708
- fail(reason: string, opts?: {
709
- code?: string;
710
- }): never;
830
+ fail(reason: string, opts?: HandlerFailureOptions): never;
711
831
  }
712
832
  /**
713
833
  * Low-level capability registration: type + scope + concurrency + optional
@@ -751,6 +871,13 @@ interface CapabilityHandleOptions {
751
871
  * bounded `[1_000, 3_600_000]` (1s..1h) by `CapabilitySchema`.
752
872
  */
753
873
  leaseTtlMs?: number;
874
+ /**
875
+ * Capability types this `skill/*` capability composes (HOL-4326).
876
+ * Wins over the same field on the def. Only valid when the
877
+ * capability's type is namespaced `skill/*` — enforced by
878
+ * `CapabilitySchema` on the gateway. Requires gateway protocol 1.2.0.
879
+ */
880
+ composes?: readonly string[];
754
881
  }
755
882
  /** Handler signature: receives the resolved input and a context, returns
756
883
  * the output. Throwing nacks the lease (retryable by default; ctx.fail
@@ -831,4 +958,4 @@ interface TransportCallbacks {
831
958
  }) => void;
832
959
  }
833
960
 
834
- export type { AuthCallback as A, Capability as C, Handler as H, JsonSchema as J, LeasePayload as L, NeuronLogger as N, PostPath as P, ServerToNeuronFrame as S, Transport as T, CapabilityHandleOptions as a, CapabilityRegistration as b, TransportCallbacks as c, ClientFrame as d, HandlerContext as e, HeartbeatInFlightEntry as f, TaskPayload as g };
961
+ export type { AuthCallback as A, Capability as C, Handler as H, JsonSchema as J, LeasePayload as L, NeuronLogger as N, PostPath as P, ServerToNeuronFrame as S, Transport as T, CapabilityHandleOptions as a, CapabilityRegistration as b, TransportCallbacks as c, ClientFrame as d, HandlerContext as e, HandlerFailureOptions as f, HeartbeatInFlightEntry as g, TaskPayload as h };
package/dist/{transport-Ckcwj-Do.d.ts → transport-BhFVHvR7.d.ts} RENAMED
@@ -3,7 +3,7 @@ import { z } from 'zod';
3
3
  /** Opaque JSON Schema; runtime structure handled by ajv at the gateway. */
4
4
  type JsonSchema = unknown;
5
5
 
6
- declare const CapabilitySchema: z.ZodObject<{
6
+ declare const CapabilitySchema: z.ZodEffects<z.ZodObject<{
7
7
  type: z.ZodString;
8
8
  scope: z.ZodUnion<[z.ZodLiteral<"any">, z.ZodObject<{
9
9
  onBehalfOf: z.ZodString;
@@ -48,6 +48,13 @@ declare const CapabilitySchema: z.ZodObject<{
48
48
  * capability).
49
49
  */
50
50
  leaseTtlMs: z.ZodOptional<z.ZodNumber>;
51
+ /**
52
+ * Capability types this `skill/*` capability composes (HOL-4326).
53
+ * Only valid on a `skill/*` type — enforced below, since a non-skill
54
+ * type carrying `composes` is a modeling error the gateway should
55
+ * reject rather than silently ignore.
56
+ */
57
+ composes: z.ZodOptional<z.ZodEffects<z.ZodEffects<z.ZodArray<z.ZodString, "many">, string[], string[]>, string[], string[]>>;
51
58
  }, "strict", z.ZodTypeAny, {
52
59
  type: string;
53
60
  scope: "any" | {
@@ -58,6 +65,29 @@ declare const CapabilitySchema: z.ZodObject<{
58
65
  inputSchema?: unknown;
59
66
  outputSchema?: unknown;
60
67
  leaseTtlMs?: number | undefined;
68
+ composes?: string[] | undefined;
69
+ }, {
70
+ type: string;
71
+ scope: "any" | {
72
+ onBehalfOf: string;
73
+ };
74
+ concurrency: number;
75
+ description?: string | undefined;
76
+ inputSchema?: unknown;
77
+ outputSchema?: unknown;
78
+ leaseTtlMs?: number | undefined;
79
+ composes?: string[] | undefined;
80
+ }>, {
81
+ type: string;
82
+ scope: "any" | {
83
+ onBehalfOf: string;
84
+ };
85
+ concurrency: number;
86
+ description?: string | undefined;
87
+ inputSchema?: unknown;
88
+ outputSchema?: unknown;
89
+ leaseTtlMs?: number | undefined;
90
+ composes?: string[] | undefined;
61
91
  }, {
62
92
  type: string;
63
93
  scope: "any" | {
@@ -68,6 +98,7 @@ declare const CapabilitySchema: z.ZodObject<{
68
98
  inputSchema?: unknown;
69
99
  outputSchema?: unknown;
70
100
  leaseTtlMs?: number | undefined;
101
+ composes?: string[] | undefined;
71
102
  }>;
72
103
  type Capability = z.infer<typeof CapabilitySchema>;
73
104
 
@@ -162,7 +193,7 @@ declare const RegisterFrameSchema: z.ZodObject<{
162
193
  type: z.ZodLiteral<"register">;
163
194
  neuronId: z.ZodString;
164
195
  protocolVersion: z.ZodString;
165
- capabilities: z.ZodEffects<z.ZodArray<z.ZodObject<{
196
+ capabilities: z.ZodEffects<z.ZodArray<z.ZodEffects<z.ZodObject<{
166
197
  type: z.ZodString;
167
198
  scope: z.ZodUnion<[z.ZodLiteral<"any">, z.ZodObject<{
168
199
  onBehalfOf: z.ZodString;
@@ -176,6 +207,7 @@ declare const RegisterFrameSchema: z.ZodObject<{
176
207
  inputSchema: z.ZodOptional<z.ZodEffects<z.ZodUnknown, unknown, unknown>>;
177
208
  outputSchema: z.ZodOptional<z.ZodEffects<z.ZodUnknown, unknown, unknown>>;
178
209
  leaseTtlMs: z.ZodOptional<z.ZodNumber>;
210
+ composes: z.ZodOptional<z.ZodEffects<z.ZodEffects<z.ZodArray<z.ZodString, "many">, string[], string[]>, string[], string[]>>;
179
211
  }, "strict", z.ZodTypeAny, {
180
212
  type: string;
181
213
  scope: "any" | {
@@ -186,6 +218,7 @@ declare const RegisterFrameSchema: z.ZodObject<{
186
218
  inputSchema?: unknown;
187
219
  outputSchema?: unknown;
188
220
  leaseTtlMs?: number | undefined;
221
+ composes?: string[] | undefined;
189
222
  }, {
190
223
  type: string;
191
224
  scope: "any" | {
@@ -196,6 +229,29 @@ declare const RegisterFrameSchema: z.ZodObject<{
196
229
  inputSchema?: unknown;
197
230
  outputSchema?: unknown;
198
231
  leaseTtlMs?: number | undefined;
232
+ composes?: string[] | undefined;
233
+ }>, {
234
+ type: string;
235
+ scope: "any" | {
236
+ onBehalfOf: string;
237
+ };
238
+ concurrency: number;
239
+ description?: string | undefined;
240
+ inputSchema?: unknown;
241
+ outputSchema?: unknown;
242
+ leaseTtlMs?: number | undefined;
243
+ composes?: string[] | undefined;
244
+ }, {
245
+ type: string;
246
+ scope: "any" | {
247
+ onBehalfOf: string;
248
+ };
249
+ concurrency: number;
250
+ description?: string | undefined;
251
+ inputSchema?: unknown;
252
+ outputSchema?: unknown;
253
+ leaseTtlMs?: number | undefined;
254
+ composes?: string[] | undefined;
199
255
  }>, "many">, {
200
256
  type: string;
201
257
  scope: "any" | {
@@ -206,6 +262,7 @@ declare const RegisterFrameSchema: z.ZodObject<{
206
262
  inputSchema?: unknown;
207
263
  outputSchema?: unknown;
208
264
  leaseTtlMs?: number | undefined;
265
+ composes?: string[] | undefined;
209
266
  }[], {
210
267
  type: string;
211
268
  scope: "any" | {
@@ -216,6 +273,7 @@ declare const RegisterFrameSchema: z.ZodObject<{
216
273
  inputSchema?: unknown;
217
274
  outputSchema?: unknown;
218
275
  leaseTtlMs?: number | undefined;
276
+ composes?: string[] | undefined;
219
277
  }[]>;
220
278
  }, "strict", z.ZodTypeAny, {
221
279
  type: "register";
@@ -231,6 +289,7 @@ declare const RegisterFrameSchema: z.ZodObject<{
231
289
  inputSchema?: unknown;
232
290
  outputSchema?: unknown;
233
291
  leaseTtlMs?: number | undefined;
292
+ composes?: string[] | undefined;
234
293
  }[];
235
294
  }, {
236
295
  type: "register";
@@ -246,13 +305,14 @@ declare const RegisterFrameSchema: z.ZodObject<{
246
305
  inputSchema?: unknown;
247
306
  outputSchema?: unknown;
248
307
  leaseTtlMs?: number | undefined;
308
+ composes?: string[] | undefined;
249
309
  }[];
250
310
  }>;
251
311
  type RegisterFrame = z.infer<typeof RegisterFrameSchema>;
252
312
  declare const UpdateCapabilityFrameSchema: z.ZodObject<{
253
313
  type: z.ZodLiteral<"update-capability">;
254
314
  neuronId: z.ZodString;
255
- capability: z.ZodObject<{
315
+ capability: z.ZodEffects<z.ZodObject<{
256
316
  type: z.ZodString;
257
317
  scope: z.ZodUnion<[z.ZodLiteral<"any">, z.ZodObject<{
258
318
  onBehalfOf: z.ZodString;
@@ -266,6 +326,7 @@ declare const UpdateCapabilityFrameSchema: z.ZodObject<{
266
326
  inputSchema: z.ZodOptional<z.ZodEffects<z.ZodUnknown, unknown, unknown>>;
267
327
  outputSchema: z.ZodOptional<z.ZodEffects<z.ZodUnknown, unknown, unknown>>;
268
328
  leaseTtlMs: z.ZodOptional<z.ZodNumber>;
329
+ composes: z.ZodOptional<z.ZodEffects<z.ZodEffects<z.ZodArray<z.ZodString, "many">, string[], string[]>, string[], string[]>>;
269
330
  }, "strict", z.ZodTypeAny, {
270
331
  type: string;
271
332
  scope: "any" | {
@@ -276,6 +337,29 @@ declare const UpdateCapabilityFrameSchema: z.ZodObject<{
276
337
  inputSchema?: unknown;
277
338
  outputSchema?: unknown;
278
339
  leaseTtlMs?: number | undefined;
340
+ composes?: string[] | undefined;
341
+ }, {
342
+ type: string;
343
+ scope: "any" | {
344
+ onBehalfOf: string;
345
+ };
346
+ concurrency: number;
347
+ description?: string | undefined;
348
+ inputSchema?: unknown;
349
+ outputSchema?: unknown;
350
+ leaseTtlMs?: number | undefined;
351
+ composes?: string[] | undefined;
352
+ }>, {
353
+ type: string;
354
+ scope: "any" | {
355
+ onBehalfOf: string;
356
+ };
357
+ concurrency: number;
358
+ description?: string | undefined;
359
+ inputSchema?: unknown;
360
+ outputSchema?: unknown;
361
+ leaseTtlMs?: number | undefined;
362
+ composes?: string[] | undefined;
279
363
  }, {
280
364
  type: string;
281
365
  scope: "any" | {
@@ -286,6 +370,7 @@ declare const UpdateCapabilityFrameSchema: z.ZodObject<{
286
370
  inputSchema?: unknown;
287
371
  outputSchema?: unknown;
288
372
  leaseTtlMs?: number | undefined;
373
+ composes?: string[] | undefined;
289
374
  }>;
290
375
  }, "strict", z.ZodTypeAny, {
291
376
  type: "update-capability";
@@ -299,6 +384,7 @@ declare const UpdateCapabilityFrameSchema: z.ZodObject<{
299
384
  inputSchema?: unknown;
300
385
  outputSchema?: unknown;
301
386
  leaseTtlMs?: number | undefined;
387
+ composes?: string[] | undefined;
302
388
  };
303
389
  neuronId: string;
304
390
  }, {
@@ -313,6 +399,7 @@ declare const UpdateCapabilityFrameSchema: z.ZodObject<{
313
399
  inputSchema?: unknown;
314
400
  outputSchema?: unknown;
315
401
  leaseTtlMs?: number | undefined;
402
+ composes?: string[] | undefined;
316
403
  };
317
404
  neuronId: string;
318
405
  }>;
@@ -437,7 +524,7 @@ type ProgressFrame = z.infer<typeof ProgressFrameSchema>;
437
524
  declare const ServerToNeuronFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
438
525
  type: z.ZodLiteral<"registered">;
439
526
  sessionId: z.ZodString;
440
- capabilities: z.ZodArray<z.ZodObject<{
527
+ capabilities: z.ZodArray<z.ZodEffects<z.ZodObject<{
441
528
  type: z.ZodString;
442
529
  scope: z.ZodUnion<[z.ZodLiteral<"any">, z.ZodObject<{
443
530
  onBehalfOf: z.ZodString;
@@ -451,6 +538,7 @@ declare const ServerToNeuronFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
451
538
  inputSchema: z.ZodOptional<z.ZodEffects<z.ZodUnknown, unknown, unknown>>;
452
539
  outputSchema: z.ZodOptional<z.ZodEffects<z.ZodUnknown, unknown, unknown>>;
453
540
  leaseTtlMs: z.ZodOptional<z.ZodNumber>;
541
+ composes: z.ZodOptional<z.ZodEffects<z.ZodEffects<z.ZodArray<z.ZodString, "many">, string[], string[]>, string[], string[]>>;
454
542
  }, "strict", z.ZodTypeAny, {
455
543
  type: string;
456
544
  scope: "any" | {
@@ -461,6 +549,7 @@ declare const ServerToNeuronFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
461
549
  inputSchema?: unknown;
462
550
  outputSchema?: unknown;
463
551
  leaseTtlMs?: number | undefined;
552
+ composes?: string[] | undefined;
464
553
  }, {
465
554
  type: string;
466
555
  scope: "any" | {
@@ -471,6 +560,29 @@ declare const ServerToNeuronFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
471
560
  inputSchema?: unknown;
472
561
  outputSchema?: unknown;
473
562
  leaseTtlMs?: number | undefined;
563
+ composes?: string[] | undefined;
564
+ }>, {
565
+ type: string;
566
+ scope: "any" | {
567
+ onBehalfOf: string;
568
+ };
569
+ concurrency: number;
570
+ description?: string | undefined;
571
+ inputSchema?: unknown;
572
+ outputSchema?: unknown;
573
+ leaseTtlMs?: number | undefined;
574
+ composes?: string[] | undefined;
575
+ }, {
576
+ type: string;
577
+ scope: "any" | {
578
+ onBehalfOf: string;
579
+ };
580
+ concurrency: number;
581
+ description?: string | undefined;
582
+ inputSchema?: unknown;
583
+ outputSchema?: unknown;
584
+ leaseTtlMs?: number | undefined;
585
+ composes?: string[] | undefined;
474
586
  }>, "many">;
475
587
  acceptedAt: z.ZodString;
476
588
  }, "strict", z.ZodTypeAny, {
@@ -485,6 +597,7 @@ declare const ServerToNeuronFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
485
597
  inputSchema?: unknown;
486
598
  outputSchema?: unknown;
487
599
  leaseTtlMs?: number | undefined;
600
+ composes?: string[] | undefined;
488
601
  }[];
489
602
  sessionId: string;
490
603
  acceptedAt: string;
@@ -500,6 +613,7 @@ declare const ServerToNeuronFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
500
613
  inputSchema?: unknown;
501
614
  outputSchema?: unknown;
502
615
  leaseTtlMs?: number | undefined;
616
+ composes?: string[] | undefined;
503
617
  }[];
504
618
  sessionId: string;
505
619
  acceptedAt: string;
@@ -674,6 +788,12 @@ interface NeuronLogger {
674
788
  warn(meta: Record<string, unknown>, msg?: string): void;
675
789
  error(meta: Record<string, unknown>, msg?: string): void;
676
790
  }
791
+ /** What a handler states when it fails a lease; see {@link HandlerContext.fail}. */
792
+ interface HandlerFailureOptions {
793
+ code?: string;
794
+ details?: unknown;
795
+ kind?: 'terminal' | 'retryable';
796
+ }
677
797
  /** Per-handler context passed to `neuron.handle(...)` callbacks. */
678
798
  interface HandlerContext {
679
799
  /** Lease metadata for this delivery. */
@@ -701,13 +821,13 @@ interface HandlerContext {
701
821
  data?: unknown;
702
822
  }): void;
703
823
  /**
704
- * Terminal failure — short-circuits the handler with a non-retryable
705
- * nack containing the given reason. Throws an internal error to bail
706
- * out of the handler; do not catch it.
824
+ * Fail the lease with a nack and bail out of the handler; do not catch the
825
+ * throw. `reason` is the sentence a reader sees; `code` names the failure;
826
+ * `details` carries any structured facts (never required to understand the
827
+ * reason). `kind` defaults to `terminal` (the same input will not succeed);
828
+ * `retryable` says the same input may succeed later.
707
829
  */
708
- fail(reason: string, opts?: {
709
- code?: string;
710
- }): never;
830
+ fail(reason: string, opts?: HandlerFailureOptions): never;
711
831
  }
712
832
  /**
713
833
  * Low-level capability registration: type + scope + concurrency + optional
@@ -751,6 +871,13 @@ interface CapabilityHandleOptions {
751
871
  * bounded `[1_000, 3_600_000]` (1s..1h) by `CapabilitySchema`.
752
872
  */
753
873
  leaseTtlMs?: number;
874
+ /**
875
+ * Capability types this `skill/*` capability composes (HOL-4326).
876
+ * Wins over the same field on the def. Only valid when the
877
+ * capability's type is namespaced `skill/*` — enforced by
878
+ * `CapabilitySchema` on the gateway. Requires gateway protocol 1.2.0.
879
+ */
880
+ composes?: readonly string[];
754
881
  }
755
882
  /** Handler signature: receives the resolved input and a context, returns
756
883
  * the output. Throwing nacks the lease (retryable by default; ctx.fail
@@ -831,4 +958,4 @@ interface TransportCallbacks {
831
958
  }) => void;
832
959
  }
833
960
 
834
- export type { AuthCallback as A, Capability as C, Handler as H, JsonSchema as J, LeasePayload as L, NeuronLogger as N, PostPath as P, ServerToNeuronFrame as S, Transport as T, CapabilityHandleOptions as a, CapabilityRegistration as b, TransportCallbacks as c, ClientFrame as d, HandlerContext as e, HeartbeatInFlightEntry as f, TaskPayload as g };
961
+ export type { AuthCallback as A, Capability as C, Handler as H, JsonSchema as J, LeasePayload as L, NeuronLogger as N, PostPath as P, ServerToNeuronFrame as S, Transport as T, CapabilityHandleOptions as a, CapabilityRegistration as b, TransportCallbacks as c, ClientFrame as d, HandlerContext as e, HandlerFailureOptions as f, HeartbeatInFlightEntry as g, TaskPayload as h };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@holokai/neuron-sdk",
3
- "version": "0.5.1",
3
+ "version": "0.7.0",
4
4
  "description": "SDK for building Holokai neurons — connect to a BigBrain gateway over HTTP+SSE or Electron IPC and execute capability-typed tasks.",
5
5
  "license": "MIT",
6
6
  "author": "Holokai",