@holokai/neuron-sdk 0.3.0 → 0.5.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 {
@@ -518,6 +551,7 @@ var TerminalFailure = class extends Error {
     this.name = "TerminalFailure";
   }
 };
+var DEFAULT_PROGRESS_TIMEOUT_MS = 5e3;
 function validateInput(zod, validator, jsonSchema, data) {
   if (zod) {
     const result = zod.safeParse(data);
@@ -530,8 +564,20 @@ 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,
+    progressTimeoutMs = DEFAULT_PROGRESS_TIMEOUT_MS
+  } = opts;
+  const inputCheck = validateInput(zodInput, validator, inputSchema, lease.task.input);
   if (!inputCheck.ok) {
     await sendNack(
       transport,
@@ -544,13 +590,13 @@ async function runLease(opts) {
     return;
   }
   const parsedInput = inputCheck.value;
-  const progressFn = makeProgressFn(transport, lease.leaseId, logger);
+  const reporter = makeProgressReporter(transport, lease.leaseId, logger, signal, progressTimeoutMs);
   const ctx = {
     task: lease.task,
     leaseId: lease.leaseId,
     signal,
     log: scopedLogger(logger, lease),
-    progress: progressFn,
+    progress: reporter.progress,
     fail: (reason, opts2) => {
       throw new TerminalFailure(reason, opts2?.code);
     }
@@ -559,7 +605,9 @@ async function runLease(opts) {
   try {
     output = await handler(parsedInput, ctx);
   } catch (err) {
-    if (signal.aborted || err.name === "AbortError") {
+    const cancelled = signal.aborted || err.name === "AbortError";
+    if (!cancelled) await reporter.drained();
+    if (cancelled) {
       await sendNack(
         transport,
         lease.leaseId,
@@ -593,7 +641,8 @@ async function runLease(opts) {
     );
     return;
   }
-  const outputCheck = validateInput(zodOutput, validator, lease.outputSchema, output);
+  await reporter.drained();
+  const outputCheck = validateInput(zodOutput, validator, outputSchema, output);
   if (!outputCheck.ok) {
     await sendNack(
       transport,
@@ -634,20 +683,37 @@ async function sendNack(transport, leaseId, kind, reason, extras = {}, logger) {
     );
   });
 }
-function makeProgressFn(transport, leaseId, logger) {
-  return (update) => {
-    void transport.post(POST_PATH.progress, {
-      type: "progress",
-      leaseId,
-      percent: update.percent,
-      message: update.message,
-      data: update.data,
-      sentAt: (/* @__PURE__ */ new Date()).toISOString()
-    }).catch((err) => {
-      logger.warn({ err, leaseId }, "progress POST failed; continuing");
-    });
+function makeProgressReporter(transport, leaseId, logger, signal, timeoutMs) {
+  let tail = Promise.resolve();
+  return {
+    progress: (update) => {
+      const frame = {
+        type: "progress",
+        leaseId,
+        percent: update.percent,
+        message: update.message,
+        data: update.data,
+        sentAt: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      tail = tail.then(async () => {
+        if (signal.aborted) return;
+        try {
+          await withTimeout(transport.post(POST_PATH.progress, frame), timeoutMs);
+        } catch (err) {
+          logger.warn({ err, leaseId }, "progress POST failed; continuing");
+        }
+      });
+    },
+    drained: () => tail
   };
 }
+function withTimeout(work, ms) {
+  let timer;
+  const timeout = new Promise((_resolve, reject) => {
+    timer = setTimeout(() => reject(new Error(`timed out after ${ms}ms`)), ms);
+  });
+  return Promise.race([work, timeout]).finally(() => clearTimeout(timer));
+}
 function scopedLogger(logger, lease) {
   const scope = { leaseId: lease.leaseId, taskId: lease.task.taskId };
   return {
@@ -660,32 +726,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 +891,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 +965,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 +1084,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 +1169,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,