@holokai/neuron-sdk 0.2.0 → 0.4.0

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,