@holokai/neuron-sdk 0.2.0 → 0.4.0

package/dist/index.mjs

@@ -10,6 +10,7 @@ var CapabilityTypeSchema = z.string().min(1).regex(
   "capability type must be namespaced: {owner}/{package}[/{name}][.{variant}]"
 );
 var UserIdSchema = z.string().min(1);
+var JsonSchemaSchema = z.unknown();
 var CapabilityScopeSchema = z.union([
   z.literal("any"),
   z.object({ onBehalfOf: UserIdSchema }).strict()
@@ -18,6 +19,36 @@ var CapabilitySchema = z.object({
   type: CapabilityTypeSchema,
   scope: CapabilityScopeSchema,
   concurrency: 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: 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
@@ -33,7 +64,6 @@ var CapabilitySchema = z.object({
    */
   leaseTtlMs: z.number().int().min(1e3).max(60 * 60 * 1e3).optional()
 }).strict();
-var JsonSchemaSchema = z.unknown();
 var LeaseIdSchema = z.string().min(1);
 var TaskPayloadSchema = z.object({
   taskId: z.string().min(1),
@@ -55,9 +85,10 @@ var NeuronIdSchema = z.string().min(1);
 var RegisterFrameSchema = z.object({
   type: 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: z.string().min(1),
   capabilities: z.array(CapabilitySchema).min(1).refine(
     (caps) => new Set(caps.map((c) => c.type)).size === caps.length,
@@ -171,7 +202,7 @@ 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",
@@ -226,6 +257,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 } : {}
   };
 }
@@ -245,7 +282,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) {
@@ -496,9 +532,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 {
@@ -530,8 +563,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,
@@ -593,7 +637,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,
@@ -660,32 +704,39 @@ function scopedLogger(logger, lease) {
 var Ajv = AjvDefault.default ?? AjvDefault;
 var addFormats = addFormatsDefault.default ?? addFormatsDefault;
 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);
     }
@@ -818,7 +869,9 @@ var Neuron = class extends 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,
@@ -890,7 +943,15 @@ var Neuron = class extends 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;
     }
@@ -1001,7 +1062,15 @@ var Neuron = class extends 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) {
@@ -1078,6 +1147,8 @@ var Neuron = class extends 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,