@holokai/neuron-sdk 0.5.1 → 0.7.0

package/README.md

@@ -21,7 +21,7 @@ pnpm add @holokai/neuron-sdk
 
 Runs in **Node 20+** (uses the global `fetch` and `ReadableStream`) and **modern browsers** (Chromium, Firefox, Safari latest). The package has no `node:*` imports — Holokai Desktop / Electron and the in-browser neuron-tester both consume the same SDK build.
 
-> **Gateway compatibility (protocol 1.1.0, HOL-2926).** Since protocol
+> **Gateway compatibility (protocol 1.2.0; HOL-2926, HOL-4326).** Since protocol
 > 1.1.0 the SDK advertises each capability's contract (`description` +
 > input/output JSON Schemas) on the register frame. The gateway validates
 > register frames **strictly**, so a gateway older than HOL-2926 rejects
@@ -114,6 +114,29 @@ Examples:
 - `desktop/mcp/drive.read` — user's Google Drive, scoped to that user
 - `org/01HBQ8ZK/custom-tool` — org-specific capability
 
+### Composing capabilities (`composes`)
+
+A capability namespaced `skill/<name>/<id>` may declare `composes`: the other
+capability types it draws on to carry out one recurring job. Set it on
+`defineCapability(...)`, on `neuron.handle(def, opts, fn)`'s `opts`, or on the
+legacy registration object — it is only valid on a `skill/*` type, must name
+1 to 64 distinct capability types, and none of them may itself be `skill/*`.
+
+```ts
+const weeklyReport = defineCapability({
+  type: 'skill/weekly-report/01',
+  description: 'Pulls last week\'s issues and writes a summary.',
+  input: z.object({}),
+  output: z.object({ summary: z.string() }),
+  composes: ['mcp/linear/list_issues', 'holo/37bfe871'],
+});
+```
+
+`composes` is carried on the register frame's capability object (gateway
+protocol 1.2.0, HOL-4326) — **the gateway must be running 1.2.0 or later
+before deploying an SDK version that sends it**, or the gateway rejects the
+register frame outright.
+
 ### Namespace authorization
 
 The gateway enforces which identities may advertise which namespaces:

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { J as JsonSchema, C as Capability, a as CapabilityHandleOptions, S as ServerToNeuronFrame, N as NeuronLogger, T as Transport, A as AuthCallback, H as Handler, b as CapabilityRegistration, c as TransportCallbacks, d as ClientFrame, P as PostPath } from './transport-Ckcwj-Do.mjs';
-export { e as HandlerContext, f as HeartbeatInFlightEntry, L as LeasePayload, g as TaskPayload } from './transport-Ckcwj-Do.mjs';
+import { J as JsonSchema, C as Capability, a as CapabilityHandleOptions, S as ServerToNeuronFrame, N as NeuronLogger, T as Transport, A as AuthCallback, H as Handler, b as CapabilityRegistration, c as TransportCallbacks, d as ClientFrame, P as PostPath } from './transport-BhFVHvR7.mjs';
+export { e as HandlerContext, f as HandlerFailureOptions, g as HeartbeatInFlightEntry, L as LeasePayload, h as TaskPayload } from './transport-BhFVHvR7.mjs';
 import { EventEmitter } from 'eventemitter3';
 import { z } from 'zod';
 import { ErrorObject } from 'ajv';
@@ -48,6 +48,12 @@ interface CapabilityDefInit<TIn extends z.ZodTypeAny, TOut extends z.ZodTypeAny>
      * Bounded `[1_000, 3_600_000]` (1s..1h) by `CapabilitySchema`.
      */
     leaseTtlMs?: number;
+    /**
+     * Capability types this `skill/*` capability composes (HOL-4326). Only
+     * valid when `type` is namespaced `skill/*` — enforced by
+     * `CapabilitySchema` on the gateway.
+     */
+    composes?: readonly string[];
 }
 /**
  * A typed capability definition. The phantom `_input` / `_output` fields
@@ -68,6 +74,8 @@ interface CapabilityDef<TIn = unknown, TOut = unknown> {
     readonly concurrency?: number;
     /** See {@link CapabilityDefInit.leaseTtlMs}. */
     readonly leaseTtlMs?: number;
+    /** See {@link CapabilityDefInit.composes}. */
+    readonly composes?: readonly string[];
     /** Original zod schemas — kept for runtime validation in handlers if needed. */
     readonly _zod: {
         input: z.ZodType<TIn>;
@@ -418,4 +426,18 @@ declare class SchemaValidator {
     validate(schema: JsonSchema | undefined, data: unknown): ErrorObject[] | null;
 }
 
-export { AuthCallback, Capability, type CapabilityDef, type CapabilityDefInit, CapabilityHandleOptions, type CapabilityPlanShape, CapabilityRegistration, Handler, HttpTransport, type HttpTransportOptions, Neuron, type NeuronEvents, NeuronLogger, type NeuronOptions, SSE_EVENT_NAMES, SchemaValidator, ServerToNeuronFrame, ShutdownError, Transport, TransportCallbacks, TransportError, WorkerPool, defineCapability, toPlanShape, toRegistrationCapability };
+/**
+ * The exception `ctx.fail()` throws to short-circuit the handler with a
+ * nack. Caught by the runner; consumers should not catch it. Exported so a
+ * wrapper around a handler can raise one for a refusal the handler answered
+ * as data.
+ */
+declare class HandlerFailure extends Error {
+    readonly reason: string;
+    readonly code?: string | undefined;
+    readonly details?: unknown | undefined;
+    readonly kind: 'terminal' | 'retryable';
+    constructor(reason: string, code?: string | undefined, details?: unknown | undefined, kind?: 'terminal' | 'retryable');
+}
+
+export { AuthCallback, Capability, type CapabilityDef, type CapabilityDefInit, CapabilityHandleOptions, type CapabilityPlanShape, CapabilityRegistration, Handler, HandlerFailure, HttpTransport, type HttpTransportOptions, Neuron, type NeuronEvents, NeuronLogger, type NeuronOptions, SSE_EVENT_NAMES, SchemaValidator, ServerToNeuronFrame, ShutdownError, Transport, TransportCallbacks, TransportError, WorkerPool, defineCapability, toPlanShape, toRegistrationCapability };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { J as JsonSchema, C as Capability, a as CapabilityHandleOptions, S as ServerToNeuronFrame, N as NeuronLogger, T as Transport, A as AuthCallback, H as Handler, b as CapabilityRegistration, c as TransportCallbacks, d as ClientFrame, P as PostPath } from './transport-Ckcwj-Do.js';
-export { e as HandlerContext, f as HeartbeatInFlightEntry, L as LeasePayload, g as TaskPayload } from './transport-Ckcwj-Do.js';
+import { J as JsonSchema, C as Capability, a as CapabilityHandleOptions, S as ServerToNeuronFrame, N as NeuronLogger, T as Transport, A as AuthCallback, H as Handler, b as CapabilityRegistration, c as TransportCallbacks, d as ClientFrame, P as PostPath } from './transport-BhFVHvR7.js';
+export { e as HandlerContext, f as HandlerFailureOptions, g as HeartbeatInFlightEntry, L as LeasePayload, h as TaskPayload } from './transport-BhFVHvR7.js';
 import { EventEmitter } from 'eventemitter3';
 import { z } from 'zod';
 import { ErrorObject } from 'ajv';
@@ -48,6 +48,12 @@ interface CapabilityDefInit<TIn extends z.ZodTypeAny, TOut extends z.ZodTypeAny>
      * Bounded `[1_000, 3_600_000]` (1s..1h) by `CapabilitySchema`.
      */
     leaseTtlMs?: number;
+    /**
+     * Capability types this `skill/*` capability composes (HOL-4326). Only
+     * valid when `type` is namespaced `skill/*` — enforced by
+     * `CapabilitySchema` on the gateway.
+     */
+    composes?: readonly string[];
 }
 /**
  * A typed capability definition. The phantom `_input` / `_output` fields
@@ -68,6 +74,8 @@ interface CapabilityDef<TIn = unknown, TOut = unknown> {
     readonly concurrency?: number;
     /** See {@link CapabilityDefInit.leaseTtlMs}. */
     readonly leaseTtlMs?: number;
+    /** See {@link CapabilityDefInit.composes}. */
+    readonly composes?: readonly string[];
     /** Original zod schemas — kept for runtime validation in handlers if needed. */
     readonly _zod: {
         input: z.ZodType<TIn>;
@@ -418,4 +426,18 @@ declare class SchemaValidator {
     validate(schema: JsonSchema | undefined, data: unknown): ErrorObject[] | null;
 }
 
-export { AuthCallback, Capability, type CapabilityDef, type CapabilityDefInit, CapabilityHandleOptions, type CapabilityPlanShape, CapabilityRegistration, Handler, HttpTransport, type HttpTransportOptions, Neuron, type NeuronEvents, NeuronLogger, type NeuronOptions, SSE_EVENT_NAMES, SchemaValidator, ServerToNeuronFrame, ShutdownError, Transport, TransportCallbacks, TransportError, WorkerPool, defineCapability, toPlanShape, toRegistrationCapability };
+/**
+ * The exception `ctx.fail()` throws to short-circuit the handler with a
+ * nack. Caught by the runner; consumers should not catch it. Exported so a
+ * wrapper around a handler can raise one for a refusal the handler answered
+ * as data.
+ */
+declare class HandlerFailure extends Error {
+    readonly reason: string;
+    readonly code?: string | undefined;
+    readonly details?: unknown | undefined;
+    readonly kind: 'terminal' | 'retryable';
+    constructor(reason: string, code?: string | undefined, details?: unknown | undefined, kind?: 'terminal' | 'retryable');
+}
+
+export { AuthCallback, Capability, type CapabilityDef, type CapabilityDefInit, CapabilityHandleOptions, type CapabilityPlanShape, CapabilityRegistration, Handler, HandlerFailure, HttpTransport, type HttpTransportOptions, Neuron, type NeuronEvents, NeuronLogger, type NeuronOptions, SSE_EVENT_NAMES, SchemaValidator, ServerToNeuronFrame, ShutdownError, Transport, TransportCallbacks, TransportError, WorkerPool, defineCapability, toPlanShape, toRegistrationCapability };

package/dist/index.js

@@ -17,6 +17,11 @@ var CapabilityTypeSchema = zod.z.string().min(1).regex(
   "capability type must be namespaced: {owner}/{package}[/{name}][.{variant}]"
 );
 var UserIdSchema = zod.z.string().min(1);
+var SKILL_CAPABILITY_PREFIX = "skill/";
+function isSkillCapabilityType(type) {
+  return type.startsWith(SKILL_CAPABILITY_PREFIX);
+}
+var MAX_COMPOSED_CAPABILITIES = 64;
 var JsonSchemaSchema = zod.z.unknown();
 var CapabilityScopeSchema = zod.z.union([
   zod.z.literal("any"),
@@ -69,8 +74,29 @@ var CapabilitySchema = zod.z.object({
    * heartbeat budget should be the limiter, not a single
    * capability).
    */
-  leaseTtlMs: zod.z.number().int().min(1e3).max(60 * 60 * 1e3).optional()
-}).strict();
+  leaseTtlMs: zod.z.number().int().min(1e3).max(60 * 60 * 1e3).optional(),
+  /**
+   * Capability types this `skill/*` capability composes (HOL-4326).
+   * Only valid on a `skill/*` type — enforced below, since a non-skill
+   * type carrying `composes` is a modeling error the gateway should
+   * reject rather than silently ignore.
+   */
+  composes: zod.z.array(CapabilityTypeSchema).min(1).max(MAX_COMPOSED_CAPABILITIES).refine(
+    (types) => new Set(types).size === types.length,
+    "composes must not contain duplicate capability types"
+  ).refine(
+    (types) => types.every((t) => !isSkillCapabilityType(t)),
+    "composes must not contain skill/* capability types"
+  ).optional()
+}).strict().superRefine((cap, ctx) => {
+  if (cap.composes !== void 0 && !isSkillCapabilityType(cap.type)) {
+    ctx.addIssue({
+      code: zod.z.ZodIssueCode.custom,
+      message: "composes is only valid on a skill/* capability type",
+      path: ["composes"]
+    });
+  }
+});
 var LeaseIdSchema = zod.z.string().min(1);
 var TaskPayloadSchema = zod.z.object({
   taskId: zod.z.string().min(1),
@@ -209,7 +235,7 @@ zod.z.discriminatedUnion("type", [
 ]);
 
 // ../neuron-protocol/src/transport.ts
-var PROTOCOL_VERSION = "1.1.0";
+var PROTOCOL_VERSION = "1.2.0";
 var SSE_PATH = "/neuron/events";
 var SSE_EVENT = {
   registered: "registered",
@@ -235,6 +261,7 @@ function defineCapability(init) {
     scope: init.scope,
     concurrency: init.concurrency,
     leaseTtlMs: init.leaseTtlMs,
+    composes: init.composes,
     _zod: { input: init.input, output: init.output }
   };
 }
@@ -260,6 +287,7 @@ function toRegistrationCapability(def, opts) {
     );
   }
   const leaseTtlMs = opts?.leaseTtlMs ?? def.leaseTtlMs;
+  const composes = opts?.composes ?? def.composes;
   return {
     type: def.type,
     scope,
@@ -270,7 +298,8 @@ function toRegistrationCapability(def, opts) {
     description: opts?.description ?? def.description,
     inputSchema: def.inputSchema,
     outputSchema: def.outputSchema,
-    ...typeof leaseTtlMs === "number" ? { leaseTtlMs } : {}
+    ...typeof leaseTtlMs === "number" ? { leaseTtlMs } : {},
+    ...composes !== void 0 ? { composes: [...composes] } : {}
   };
 }
 
@@ -550,13 +579,16 @@ var TransportError = class extends Error {
 };
 
 // src/lease-runner.ts
-var TerminalFailure = class extends Error {
-  constructor(reason, code) {
+var HandlerFailure = class extends Error {
+  constructor(reason, code, details, kind = "terminal") {
     super(reason);
     this.reason = reason;
     this.code = code;
-    this.name = "TerminalFailure";
+    this.details = details;
+    this.name = "HandlerFailure";
+    this.kind = kind;
   }
+  kind;
 };
 var DEFAULT_PROGRESS_TIMEOUT_MS = 5e3;
 function validateInput(zod, validator, jsonSchema, data) {
@@ -564,10 +596,7 @@ function validateInput(zod, validator, jsonSchema, data) {
     const result = zod.safeParse(data);
     return result.success ? { ok: true, value: result.data } : { ok: false, errors: result.error.issues };
   }
-  const errors = validator.validate(
-    jsonSchema,
-    data
-  );
+  const errors = validator.validate(jsonSchema, data);
   return errors === null ? { ok: true, value: data } : { ok: false, errors };
 }
 async function runLease(opts) {
@@ -597,7 +626,13 @@ async function runLease(opts) {
     return;
   }
   const parsedInput = inputCheck.value;
-  const reporter = makeProgressReporter(transport, lease.leaseId, logger, signal, progressTimeoutMs);
+  const reporter = makeProgressReporter(
+    transport,
+    lease.leaseId,
+    logger,
+    signal,
+    progressTimeoutMs
+  );
   const ctx = {
     task: lease.task,
     leaseId: lease.leaseId,
@@ -605,7 +640,7 @@ async function runLease(opts) {
     log: scopedLogger(logger, lease),
     progress: reporter.progress,
     fail: (reason, opts2) => {
-      throw new TerminalFailure(reason, opts2?.code);
+      throw new HandlerFailure(reason, opts2?.code, opts2?.details, opts2?.kind);
     }
   };
   let output;
@@ -625,13 +660,16 @@ async function runLease(opts) {
       );
       return;
     }
-    if (err instanceof TerminalFailure) {
+    if (err instanceof HandlerFailure) {
       await sendNack(
         transport,
         lease.leaseId,
-        "terminal",
+        err.kind,
         err.reason,
-        { code: err.code ?? "HANDLER_TERMINAL" },
+        {
+          code: err.code ?? (err.kind === "terminal" ? "HANDLER_TERMINAL" : "HANDLER_RETRYABLE"),
+          ...err.details !== void 0 ? { details: err.details } : {}
+        },
         logger
       );
       return;
@@ -979,7 +1017,8 @@ var Neuron = class extends eventemitter3.EventEmitter {
         ...reg.description !== void 0 ? { description: reg.description } : {},
         ...reg.inputSchema !== void 0 ? { inputSchema: reg.inputSchema } : {},
         ...reg.outputSchema !== void 0 ? { outputSchema: reg.outputSchema } : {},
-        ...typeof reg.leaseTtlMs === "number" ? { leaseTtlMs: reg.leaseTtlMs } : {}
+        ...typeof reg.leaseTtlMs === "number" ? { leaseTtlMs: reg.leaseTtlMs } : {},
+        ...reg.composes !== void 0 ? { composes: reg.composes } : {}
       };
       inputSchema = reg.inputSchema;
       outputSchema = reg.outputSchema;
@@ -1221,6 +1260,7 @@ var Neuron = class extends eventemitter3.EventEmitter {
 };
 var SSE_EVENT_NAMES = SSE_EVENT;
 
+exports.HandlerFailure = HandlerFailure;
 exports.HttpTransport = HttpTransport;
 exports.Neuron = Neuron;
 exports.SSE_EVENT_NAMES = SSE_EVENT_NAMES;