@holokai/neuron-sdk 0.5.0 → 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:
@@ -843,69 +866,75 @@ The `auth` callback isn't returning a valid token. If using a refresh flow, ensu
 
 ## Releasing (maintainers)
 
-`@holokai/neuron-sdk` is published to public npm. Releases are cut from a
-monorepo-scoped git tag, and CI does the publish — there is no npm token on
-anyone's laptop and none stored in the repo.
+`@holokai/neuron-sdk` is published to public npm by BigBrain's Release
+workflow (`.github/workflows/release.yml`). There is no npm token on anyone's
+laptop and none stored in the repo, and pushing a tag publishes nothing.
+
+### Pick the version
+
+Follow semver:
+
+- Pilot phase, we are in **`0.x`**. Because the protocol is still absorbing
+  pilot-developer feedback, a **breaking** change bumps the **minor**
+  (`0.2.0` to `0.3.0`); a backward-compatible change or fix bumps the
+  **patch** (`0.2.0` to `0.2.1`). This is the standard `0.x` convention and
+  is what buys us room to break things on feedback without a major bump.
+- Hold **`1.0.0`** until the public API has survived pilot feedback and we're
+  ready to commit to "breaking changes bump the major." Jumping to `1.0.0`
+  is a stability promise, not a milestone. Don't spend it early.
 
 ### Cut a release
 
-1. **Bump the version** in `packages/neuron-sdk/package.json`
-   (`version`). Follow semver:
-   - Pilot phase, we are in **`0.x`**. Because the protocol is still absorbing
-     pilot-developer feedback, a **breaking** change bumps the **minor**
-     (`0.2.0` → `0.3.0`); a backward-compatible change or fix bumps the
-     **patch** (`0.2.0` → `0.2.1`). This is the standard `0.x` convention and
-     is what buys us room to break things on feedback without a major bump.
-   - Hold **`1.0.0`** until the public API has survived pilot feedback and we're
-     ready to commit to "breaking changes bump the major." Jumping to `1.0.0`
-     is a stability promise, not a milestone — don't spend it early.
-2. **Commit** the bump (reference the Linear ticket) and merge to `main`.
-3. **Tag and push** from `main`:
-   ```sh
-   git tag neuron-sdk-v0.2.0        # must equal the package.json version
-   git push origin neuron-sdk-v0.2.0
-   ```
-   The tag is prefixed `neuron-sdk-v` (the Python SDK uses
-   `neuron-sdk-python-v`) so the two never collide.
-4. **`publish-neuron-sdk.yml`** fires on the tag: it asserts the tag version
-   matches `package.json`, runs the `prepublish` gate (`build` + `test`), and
-   publishes to npm. The `npm` GitHub Environment gates the publish behind a
-   **required-reviewer approval** — approve the run under Actions, and on success
-   the new version is live at
+1. Open **Actions, Release, Run workflow** on branch `main`.
+2. Fill **neuron-sdk** with the new version (`X.Y.Z`). Leave the other lines
+   (base, embedded, synapse) empty unless they are being released too; an
+   empty line is not touched. Tick **plan only** to read the plan without
+   cutting anything.
+3. The plan job checks the version (shaped `X.Y.Z`, not older than
+   `packages/neuron-sdk/package.json`, tag `neuron-sdk-vX.Y.Z` not taken) and
+   writes the plan to the run summary.
+4. A reviewer of the `release` environment approves the run. That is the only
+   approval.
+5. The cut writes the version into `packages/neuron-sdk/package.json`,
+   commits it to `main`, tags `neuron-sdk-vX.Y.Z` and pushes both. If the file
+   already carries the version (a bump merged by pull request), it only tags.
+6. From the commit the cut pushed, the run builds and tests the SDK (the
+   `prepublish` turbo task), packs it, and publishes the tarball to npm from a
+   GitHub-hosted runner. On success the new version is live at
    [`@holokai/neuron-sdk`](https://www.npmjs.com/package/@holokai/neuron-sdk).
 
-   > No `--provenance`: bigbrain is a private repo, so npm's provenance
-   > attestation (a public transparency-log link back to the source) adds little
-   > and has historically errored from private repos. Trusted-publishing auth is
-   > unaffected. Add the flag back if bigbrain ever goes public.
+The tag is prefixed `neuron-sdk-v` (the Python SDK uses `neuron-sdk-python-v`)
+so the two never collide. The workflow file's header comments describe every
+job and how to recover a failed run.
 
-The tag→`package.json` assertion means a mismatched tag fails **before** the
-registry is touched — npm refuses to re-upload an existing version, so there's
-no half-published state to clean up.
+> No `--provenance`: bigbrain is a private repo, so npm's provenance
+> attestation (a public transparency-log link back to the source) adds little
+> and has historically errored from private repos. Trusted-publishing auth is
+> unaffected. Add the flag back if bigbrain ever goes public.
 
 ### Publish auth: npm Trusted Publishing (one-time setup)
 
-CI authenticates to npm via **OIDC trusted publishing** — GitHub Actions
+CI authenticates to npm via **OIDC trusted publishing**: GitHub Actions
 exchanges a short-lived OIDC token for publish rights, so no long-lived
-`NPM_TOKEN` exists to leak. This mirrors the Python SDK's PyPI trusted
-publishing. It requires two one-time setups:
+`NPM_TOKEN` exists to leak. It requires two one-time setups:
 
 1. **On npmjs.com** (a package admin, once): open the
    [`@holokai/neuron-sdk`](https://www.npmjs.com/package/@holokai/neuron-sdk)
-   package → **Settings → Trusted Publisher → GitHub Actions**, and register:
+   package, **Settings, Trusted Publisher, GitHub Actions**, and register:
    - Organization / repository: `holok-ai/bigbrain`
-   - Workflow filename: `publish-neuron-sdk.yml`
+   - Workflow filename: `release.yml`
    - Environment: `npm`
-2. **In this repo** (once): create the **`npm`** GitHub Environment
-   (Settings → Environments). Add reviewers/branch protection here if you want a
-   manual approval gate before each publish.
+2. **In this repo** (once): the **`npm`** GitHub Environment (Settings,
+   Environments) with no required reviewer, because the Release run's one
+   approval is on its cut, and a deployment branch rule of `main` only, so a
+   copy of `release.yml` on another branch cannot publish to npm.
 
 Until the trusted publisher is registered, the `npm publish` step fails with an
-auth error — that's the expected "not set up yet" signal, not a code bug.
+auth error. That is the expected "not set up yet" signal, not a code bug.
 
 ### Manual publish (fallback / first bootstrap)
 
-The tag flow is the norm. If you ever need to publish by hand (e.g. to bootstrap
+The Release workflow is the norm. If you ever need to publish by hand (e.g. to bootstrap
 the very first version before trusted publishing is configured):
 
 ```sh
@@ -915,6 +944,6 @@ pnpm run publish:npm       # runs the prepublishOnly build+test gate, then publi
 ```
 
 This uses your own `npm login` credentials and skips the CI approval gate —
-prefer the tag flow for anything a developer will consume.
+prefer the Release workflow for anything a developer will consume.
 
 <!-- ci: force full build on the self-hosted runner (HOL-2028 verify); safe to remove -->

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;