@holokai/neuron-sdk 0.5.1 → 0.6.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-Va7tTRVO.mjs';
+export { e as HandlerContext, f as HeartbeatInFlightEntry, L as LeasePayload, g as TaskPayload } from './transport-Va7tTRVO.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>;

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-Va7tTRVO.js';
+export { e as HandlerContext, f as HeartbeatInFlightEntry, L as LeasePayload, g as TaskPayload } from './transport-Va7tTRVO.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>;

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] } : {}
   };
 }
 
@@ -979,7 +1008,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;