@holokai/neuron-sdk 0.3.0 → 0.4.0

package/README.md

@@ -21,6 +21,16 @@ 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
+> 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
+> them with `INVALID_FRAME` — **deploy the gateway before publishing or
+> rolling out any 1.1.0-protocol SDK (including neuron-tester OTA)**. A
+> rejected registration leaves the SSE stream open but the neuron
+> lease-less; the SDK surfaces it via the `error` event
+> (`registration rejected by gateway: ...`) so apps can react.
+
 ---
 
 ## Quick start
@@ -29,7 +39,7 @@ Runs in **Node 20+** (uses the global `fetch` and `ReadableStream`) and **modern
 import { Neuron } from '@holokai/neuron-sdk';
 
 const neuron = new Neuron({
-  gatewayUrl: 'https://api.example.com',
+  gatewayUrl: 'https://bigbrain.holokai.dev',
   neuronId: 'my-worker-001',            // stable per process/device
   auth: () => process.env.GATEWAY_TOKEN!, // or an async refresh function
 });
@@ -75,7 +85,7 @@ import { Neuron } from '@holokai/neuron-sdk';
 import { createClientCredentialsAuth, defaultCredentialPath } from '@holokai/neuron-sdk/auth';
 
 const neuron = new Neuron({
-  gatewayUrl: 'https://api.example.com',
+  gatewayUrl: 'https://bigbrain.holokai.dev',
   neuronId: 'warehouse-connector-001',
   auth: createClientCredentialsAuth(defaultCredentialPath()),
 });
@@ -83,7 +93,7 @@ const neuron = new Neuron({
 
 `createClientCredentialsAuth` mints `aud=bigbrain` tokens via the OAuth2 `client_credentials` grant, caches them against the response's `expires_in` (proactive refresh, single-flight), and re-reads the credential file on `invalid_client` so an operator-rotated secret is picked up without a restart. If the credential was revoked in Moku it throws `CredentialRevokedError` — re-enroll to recover.
 
-> `@holokai/neuron-sdk/auth` is **Node-only** (it reads the credential file); the root and `./ipc` entries remain browser-clean. Python SDK parity for enrollment/minting is a planned follow-up in `holokai-neuron-sdk` — until then, Python neurons keep using an externally supplied token.
+> `@holokai/neuron-sdk/auth` is **Node-only** (it reads the credential file); the root and `./ipc` entries remain browser-clean. Python SDK parity ships in `holokai-neuron-sdk` ≥ 0.2.0 (`holokai_neuron_sdk.auth`: `holokai-neuron-sdk enroll` + `create_client_credentials_auth`) — same credential file, interchangeable across both SDKs.
 
 ---
 
@@ -170,7 +180,7 @@ interface NeuronCommonOptions {
 
 // Convenience: SDK builds an HttpTransport for you. Most common path.
 interface NeuronOptionsWithHttp extends NeuronCommonOptions {
-  gatewayUrl: string;           // Base URL, e.g. 'https://api.example.com'
+  gatewayUrl: string;           // Base URL, e.g. 'https://bigbrain.holokai.dev'
   auth: AuthCallback;           // Token provider (see below)
   initialReconnectDelayMs?: number; // Default 500ms
   maxReconnectDelayMs?: number;     // Default 30_000 (30s)
@@ -213,6 +223,19 @@ type Handler<TInput = unknown, TOutput = unknown> = (
 
 If `inputSchema` is provided and the lease input fails validation, the handler is never called — the SDK sends a `schema-mismatch` nack automatically. Same for `outputSchema` on the return value.
 
+**Schema precedence.** For each of input and output the SDK picks exactly one validator:
+
+1. The zod schema from `defineCapability`, when the capability was registered that way. JSON Schema can't express `.refine()`, `.transform()`, or `.preprocess()`, so the zod contract stays authoritative and its transforms are what the handler sees and what goes on the wire.
+2. Otherwise the JSON Schema passed here on `CapabilityRegistration`.
+
+A capability registered with neither is not validated client-side — its handler runs on whatever arrives.
+
+The `inputSchema` / `outputSchema` that ride on the lease frame are **not** consulted. They can only ever be your own schemas handed back to you — the register frame carries no schemas, so the server's only source is the `POST /plan` handler catalog the client supplies. And the planner doesn't persist those onto task rows, so on real workflow tasks the lease frame's schemas are absent entirely; the only case where they arrive populated is the dev-only `/__dev__/inject-task` route used by neuron-tester, which echoes back what the capability registered.
+
+> **This is the only validation that runs.** The gateway's ack-time check validates against that same (empty) `lease.outputSchema`, so it does not currently catch anything. If a capability declares no schema here, its input and output are unchecked end to end.
+
+> **Note:** the Go and Python SDKs currently prefer the lease frame's schema and fall back to the registered one. TypeScript deliberately diverges here; the other two are expected to follow.
+
 ---
 
 ### `neuron.start()`
@@ -450,7 +473,7 @@ Default transport. SSE for inbound, HTTPS POST for outbound. Reconnects with exp
 import { Neuron, HttpTransport } from '@holokai/neuron-sdk';
 
 const transport = new HttpTransport({
-  gatewayUrl: 'https://api.example.com',
+  gatewayUrl: 'https://bigbrain.holokai.dev',
   neuronId: 'my-worker-001',
   auth: () => process.env.GATEWAY_TOKEN!,
   // optional:

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-QqkooS7K.mjs';
-export { e as HandlerContext, f as HeartbeatInFlightEntry, L as LeasePayload, g as TaskPayload } from './transport-QqkooS7K.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-Cs5tY2IO.mjs';
+export { e as HandlerContext, f as HeartbeatInFlightEntry, L as LeasePayload, g as TaskPayload } from './transport-Cs5tY2IO.mjs';
 import { EventEmitter } from 'eventemitter3';
 import { z } from 'zod';
 import { ErrorObject } from 'ajv';
@@ -97,6 +97,11 @@ declare function toPlanShape(def: CapabilityDef): CapabilityPlanShape;
  * required at registration time — if neither the def nor `opts` provides
  * them, this throws so the misconfiguration surfaces at start time
  * rather than as a confusing wire-validation error.
+ *
+ * Since HOL-2926 the frame also carries the contract (`description` +
+ * compiled JSON Schemas): the gateway forwards it to Moku's capability
+ * catalog so registry-sourced capabilities render with a real contract
+ * in the supervisor catalog instead of type-only stubs.
  */
 declare function toRegistrationCapability(def: CapabilityDef, opts?: CapabilityHandleOptions): Capability;
 
@@ -141,7 +146,12 @@ interface NeuronEvents {
         delayMs: number;
         reason: string;
     }) => void;
-    /** Fired on transport / parse errors. Reconnect handling is automatic. */
+    /**
+     * Fired on transport / parse errors (reconnect handling is automatic)
+     * and on register rejection (HOL-2926 — NOT automatically recovered:
+     * the SSE stream stays open, so the neuron sits connected but
+     * lease-less until the app reacts, e.g. by calling `stop()`).
+     */
     error: (err: Error) => void;
     /** Pass-through of every parsed inbound SSE frame. */
     frame: (frame: ServerToNeuronFrame) => void;
@@ -176,7 +186,7 @@ interface NeuronOptionsWithTransport extends NeuronCommonOptions {
  * surface so existing call sites keep compiling unchanged.
  */
 interface NeuronOptionsWithHttp extends NeuronCommonOptions {
-    /** Base URL of the gateway, e.g. `https://api.holokai.dev`. */
+    /** Base URL of the gateway, e.g. `https://bigbrain.holokai.dev`. */
     gatewayUrl: string;
     /** Token provider — see `AuthCallback` for refresh semantics. */
     auth: AuthCallback;
@@ -276,7 +286,7 @@ declare const SSE_EVENT_NAMES: {
 };
 
 interface HttpTransportOptions {
-    /** Base URL of the gateway (e.g. `https://api.holokai.dev`). */
+    /** Base URL of the gateway (e.g. `https://bigbrain.holokai.dev`). */
     gatewayUrl: string;
     /** Stable per-process identifier sent as `?neuronId=` on the SSE GET. */
     neuronId: string;
@@ -395,12 +405,15 @@ declare class ShutdownError extends Error {
  * the same schemas so a misbehaving party can't sneak by either side.
  */
 declare class SchemaValidator {
+    private readonly onCompileError?;
     private readonly ajv;
     private readonly cache;
-    constructor();
+    private readonly uncompilable;
+    constructor(onCompileError?: ((message: string) => void) | undefined);
     /**
-     * Returns null if the value matches the schema (or no schema given);
-     * otherwise an array of structured errors.
+     * Returns null if the value matches the schema, no schema was given, or
+     * the schema cannot be compiled in this runtime (fail-open — the gateway
+     * remains the enforcement point); otherwise an array of structured errors.
      */
     validate(schema: JsonSchema | undefined, data: unknown): ErrorObject[] | null;
 }

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-QqkooS7K.js';
-export { e as HandlerContext, f as HeartbeatInFlightEntry, L as LeasePayload, g as TaskPayload } from './transport-QqkooS7K.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-Cs5tY2IO.js';
+export { e as HandlerContext, f as HeartbeatInFlightEntry, L as LeasePayload, g as TaskPayload } from './transport-Cs5tY2IO.js';
 import { EventEmitter } from 'eventemitter3';
 import { z } from 'zod';
 import { ErrorObject } from 'ajv';
@@ -97,6 +97,11 @@ declare function toPlanShape(def: CapabilityDef): CapabilityPlanShape;
  * required at registration time — if neither the def nor `opts` provides
  * them, this throws so the misconfiguration surfaces at start time
  * rather than as a confusing wire-validation error.
+ *
+ * Since HOL-2926 the frame also carries the contract (`description` +
+ * compiled JSON Schemas): the gateway forwards it to Moku's capability
+ * catalog so registry-sourced capabilities render with a real contract
+ * in the supervisor catalog instead of type-only stubs.
  */
 declare function toRegistrationCapability(def: CapabilityDef, opts?: CapabilityHandleOptions): Capability;
 
@@ -141,7 +146,12 @@ interface NeuronEvents {
         delayMs: number;
         reason: string;
     }) => void;
-    /** Fired on transport / parse errors. Reconnect handling is automatic. */
+    /**
+     * Fired on transport / parse errors (reconnect handling is automatic)
+     * and on register rejection (HOL-2926 — NOT automatically recovered:
+     * the SSE stream stays open, so the neuron sits connected but
+     * lease-less until the app reacts, e.g. by calling `stop()`).
+     */
     error: (err: Error) => void;
     /** Pass-through of every parsed inbound SSE frame. */
     frame: (frame: ServerToNeuronFrame) => void;
@@ -176,7 +186,7 @@ interface NeuronOptionsWithTransport extends NeuronCommonOptions {
  * surface so existing call sites keep compiling unchanged.
  */
 interface NeuronOptionsWithHttp extends NeuronCommonOptions {
-    /** Base URL of the gateway, e.g. `https://api.holokai.dev`. */
+    /** Base URL of the gateway, e.g. `https://bigbrain.holokai.dev`. */
     gatewayUrl: string;
     /** Token provider — see `AuthCallback` for refresh semantics. */
     auth: AuthCallback;
@@ -276,7 +286,7 @@ declare const SSE_EVENT_NAMES: {
 };
 
 interface HttpTransportOptions {
-    /** Base URL of the gateway (e.g. `https://api.holokai.dev`). */
+    /** Base URL of the gateway (e.g. `https://bigbrain.holokai.dev`). */
     gatewayUrl: string;
     /** Stable per-process identifier sent as `?neuronId=` on the SSE GET. */
     neuronId: string;
@@ -395,12 +405,15 @@ declare class ShutdownError extends Error {
  * the same schemas so a misbehaving party can't sneak by either side.
  */
 declare class SchemaValidator {
+    private readonly onCompileError?;
     private readonly ajv;
     private readonly cache;
-    constructor();
+    private readonly uncompilable;
+    constructor(onCompileError?: ((message: string) => void) | undefined);
     /**
-     * Returns null if the value matches the schema (or no schema given);
-     * otherwise an array of structured errors.
+     * Returns null if the value matches the schema, no schema was given, or
+     * the schema cannot be compiled in this runtime (fail-open — the gateway
+     * remains the enforcement point); otherwise an array of structured errors.
      */
     validate(schema: JsonSchema | undefined, data: unknown): ErrorObject[] | null;
 }

package/dist/index.js

@@ -17,6 +17,7 @@ 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 JsonSchemaSchema = zod.z.unknown();
 var CapabilityScopeSchema = zod.z.union([
   zod.z.literal("any"),
   zod.z.object({ onBehalfOf: UserIdSchema }).strict()
@@ -25,6 +26,36 @@ var CapabilitySchema = zod.z.object({
   type: CapabilityTypeSchema,
   scope: CapabilityScopeSchema,
   concurrency: zod.z.number().int().positive(),
+  /**
+   * Plain-language contract advertisement (HOL-2926). All three fields
+   * are optional and additive: older neurons keep sending
+   * `{ type, scope, concurrency }` and the gateway accepts both shapes.
+   * When present they flow (fire-and-forget) to Moku's
+   * `capability_catalog` so registry-sourced capabilities render with a
+   * real contract in the supervisor catalog instead of type-only stubs.
+   *
+   * Omit rather than null — the fields are `.optional()`, not
+   * `.nullable()`, and a `null` description fails validation.
+   */
+  description: zod.z.string().optional(),
+  /**
+   * JSON Schema for the capability's input payload — opaque on the wire,
+   * but `null` is rejected: the reconcile push to Moku is last-writer-wins
+   * per present key, so a null here could wipe a stored schema.
+   * (`description` already rejects null via `z.string()`.)
+   */
+  // The `: boolean` return annotations stop TS (5.5+) from inferring the
+  // lambdas as type predicates, which would narrow the field from
+  // `unknown` to `{}` and ripple into every consumer.
+  inputSchema: JsonSchemaSchema.refine(
+    (v) => v !== null,
+    "omit inputSchema instead of sending null"
+  ).optional(),
+  /** JSON Schema for the capability's output payload — same rules as inputSchema. */
+  outputSchema: JsonSchemaSchema.refine(
+    (v) => v !== null,
+    "omit outputSchema instead of sending null"
+  ).optional(),
   /**
    * Per-capability lease TTL override in milliseconds (HOL-356).
    * The gateway uses this when minting a lease's `expiresAt`; absent
@@ -40,7 +71,6 @@ var CapabilitySchema = zod.z.object({
    */
   leaseTtlMs: zod.z.number().int().min(1e3).max(60 * 60 * 1e3).optional()
 }).strict();
-var JsonSchemaSchema = zod.z.unknown();
 var LeaseIdSchema = zod.z.string().min(1);
 var TaskPayloadSchema = zod.z.object({
   taskId: zod.z.string().min(1),
@@ -62,9 +92,10 @@ var NeuronIdSchema = zod.z.string().min(1);
 var RegisterFrameSchema = zod.z.object({
   type: zod.z.literal("register"),
   neuronId: NeuronIdSchema,
-  // Free-form by design — the gateway negotiates compatibility against its
-  // own PROTOCOL_VERSION (semver), so a v1.1 server can still accept a v1.0
-  // neuron. Do not pin this to the exported constant.
+  // Free-form by design — the gateway records this verbatim and performs
+  // no version negotiation; compatibility comes from additive-only frame
+  // evolution (see PROTOCOL_VERSION in transport.ts). Do not pin this to
+  // the exported constant.
   protocolVersion: zod.z.string().min(1),
   capabilities: zod.z.array(CapabilitySchema).min(1).refine(
     (caps) => new Set(caps.map((c) => c.type)).size === caps.length,
@@ -178,7 +209,7 @@ zod.z.discriminatedUnion("type", [
 ]);
 
 // ../neuron-protocol/src/transport.ts
-var PROTOCOL_VERSION = "1.0.0";
+var PROTOCOL_VERSION = "1.1.0";
 var SSE_PATH = "/neuron/events";
 var SSE_EVENT = {
   registered: "registered",
@@ -233,6 +264,12 @@ function toRegistrationCapability(def, opts) {
     type: def.type,
     scope,
     concurrency,
+    // Contract advertisement (HOL-2926). `description` is required on the
+    // def, so it is always present here; `opts.description` lets a
+    // deployment reword it without redefining the capability.
+    description: opts?.description ?? def.description,
+    inputSchema: def.inputSchema,
+    outputSchema: def.outputSchema,
     ...typeof leaseTtlMs === "number" ? { leaseTtlMs } : {}
   };
 }
@@ -252,7 +289,6 @@ var HeartbeatLoop = class {
     this.timer = setInterval(() => {
       void this.tick();
     }, this.intervalMs);
-    if (typeof this.timer.unref === "function") this.timer.unref();
   }
   stop() {
     if (this.timer) {
@@ -503,9 +539,6 @@ var HttpTransport = class {
       this.reconnectTimer = null;
       void this.openStream();
     }, delay);
-    if (typeof this.reconnectTimer === "object" && this.reconnectTimer !== null && "unref" in this.reconnectTimer && typeof this.reconnectTimer.unref === "function") {
-      this.reconnectTimer.unref();
-    }
   }
 };
 var TransportError = class extends Error {
@@ -537,8 +570,19 @@ function validateInput(zod, validator, jsonSchema, data) {
   return errors === null ? { ok: true, value: data } : { ok: false, errors };
 }
 async function runLease(opts) {
-  const { lease, handler, zodInput, zodOutput, transport, validator, logger, signal } = opts;
-  const inputCheck = validateInput(zodInput, validator, lease.inputSchema, lease.task.input);
+  const {
+    lease,
+    handler,
+    zodInput,
+    zodOutput,
+    inputSchema,
+    outputSchema,
+    transport,
+    validator,
+    logger,
+    signal
+  } = opts;
+  const inputCheck = validateInput(zodInput, validator, inputSchema, lease.task.input);
   if (!inputCheck.ok) {
     await sendNack(
       transport,
@@ -600,7 +644,7 @@ async function runLease(opts) {
     );
     return;
   }
-  const outputCheck = validateInput(zodOutput, validator, lease.outputSchema, output);
+  const outputCheck = validateInput(zodOutput, validator, outputSchema, output);
   if (!outputCheck.ok) {
     await sendNack(
       transport,
@@ -667,32 +711,39 @@ function scopedLogger(logger, lease) {
 var Ajv = AjvDefault__default.default.default ?? AjvDefault__default.default;
 var addFormats = addFormatsDefault__default.default.default ?? addFormatsDefault__default.default;
 var SchemaValidator = class {
-  ajv;
-  cache = /* @__PURE__ */ new WeakMap();
-  constructor() {
+  constructor(onCompileError) {
+    this.onCompileError = onCompileError;
     this.ajv = new Ajv({ allErrors: true, strict: false });
     addFormats(this.ajv);
   }
+  ajv;
+  cache = /* @__PURE__ */ new WeakMap();
+  // Schemas whose compilation threw. Cannot-compile is an environment or
+  // schema-authoring problem, not evidence about the data — so validate()
+  // FAILS OPEN for these (returns null) instead of reporting a mismatch.
+  // Nacking on compile failure turned every lease into an
+  // INPUT_SCHEMA_MISMATCH retry loop on runtimes where ajv's codegen is
+  // unavailable (Electron renderers with CSP `script-src 'self'` block
+  // `new Function`) — HOL-2937.
+  uncompilable = /* @__PURE__ */ new WeakSet();
   /**
-   * Returns null if the value matches the schema (or no schema given);
-   * otherwise an array of structured errors.
+   * Returns null if the value matches the schema, no schema was given, or
+   * the schema cannot be compiled in this runtime (fail-open — the gateway
+   * remains the enforcement point); otherwise an array of structured errors.
    */
   validate(schema, data) {
     if (!schema || typeof schema !== "object") return null;
+    if (this.uncompilable.has(schema)) return null;
     let validator = this.cache.get(schema);
     if (!validator) {
       try {
         validator = this.ajv.compile(schema);
       } catch (err) {
-        return [
-          {
-            instancePath: "",
-            schemaPath: "",
-            keyword: "schema",
-            params: {},
-            message: `schema failed to compile: ${err instanceof Error ? err.message : String(err)}`
-          }
-        ];
+        this.uncompilable.add(schema);
+        this.onCompileError?.(
+          `schema failed to compile \u2014 skipping SDK-side validation for this schema: ${err instanceof Error ? err.message : String(err)}`
+        );
+        return null;
       }
       this.cache.set(schema, validator);
     }
@@ -825,7 +876,9 @@ var Neuron = class extends eventemitter3.EventEmitter {
     super();
     this.logger = opts.logger ?? noopLogger;
     this.neuronId = opts.neuronId;
-    this.validator = new SchemaValidator();
+    this.validator = new SchemaValidator(
+      (message) => this.logger.warn({ neuronId: this.neuronId }, message)
+    );
     this.transport = isWithTransport(opts) ? opts.transport : new HttpTransport({
       gatewayUrl: opts.gatewayUrl,
       neuronId: opts.neuronId,
@@ -897,7 +950,15 @@ var Neuron = class extends eventemitter3.EventEmitter {
         );
       }
       handler = optsOrHandler;
-      capability = { type: reg.type, scope: reg.scope, concurrency: reg.concurrency };
+      capability = {
+        type: reg.type,
+        scope: reg.scope,
+        concurrency: reg.concurrency,
+        ...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 } : {}
+      };
       inputSchema = reg.inputSchema;
       outputSchema = reg.outputSchema;
     }
@@ -1008,7 +1069,15 @@ var Neuron = class extends eventemitter3.EventEmitter {
       this.hasOpenedOnce = true;
       this.heartbeat.start();
     } catch (err) {
-      this.logger.error({ err }, "register POST failed; transport will retry on reconnect");
+      const cause = err instanceof Error ? err : new Error(String(err));
+      this.logger.error(
+        { err: cause },
+        "register POST rejected; SSE is open but the neuron is NOT registered and will receive no leases"
+      );
+      this.emit(
+        "error",
+        new Error(`registration rejected by gateway: ${cause.message}`, { cause })
+      );
     }
   }
   handleConnectionClose(reason) {
@@ -1085,6 +1154,8 @@ var Neuron = class extends eventemitter3.EventEmitter {
             handler: handler.handler,
             zodInput: handler.zodInput,
             zodOutput: handler.zodOutput,
+            inputSchema: handler.inputSchema,
+            outputSchema: handler.outputSchema,
             transport: this.transport,
             validator: this.validator,
             logger: this.logger,