@holokai/neuron-sdk 0.1.0 → 0.2.0

package/dist/index.js

@@ -24,7 +24,21 @@ var CapabilityScopeSchema = zod.z.union([
 var CapabilitySchema = zod.z.object({
   type: CapabilityTypeSchema,
   scope: CapabilityScopeSchema,
-  concurrency: zod.z.number().int().positive()
+  concurrency: zod.z.number().int().positive(),
+  /**
+   * Per-capability lease TTL override in milliseconds (HOL-356).
+   * The gateway uses this when minting a lease's `expiresAt`; absent
+   * → falls back to the gateway's default (`leaseTtlMs` on the
+   * dispatcher). Lets a slow capability (e.g. a scripted run with a
+   * 10-minute deadline) declare a longer TTL without tuning the
+   * whole gateway.
+   *
+   * Bounded by reasonable extremes: at least 1s (anything shorter
+   * than a heartbeat is meaningless) and at most 1h (the reaper +
+   * heartbeat budget should be the limiter, not a single
+   * capability).
+   */
+  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);
@@ -189,6 +203,7 @@ function defineCapability(init) {
     outputSchema: zodToJsonSchema.zodToJsonSchema(init.output, { $refStrategy: "none" }),
     scope: init.scope,
     concurrency: init.concurrency,
+    leaseTtlMs: init.leaseTtlMs,
     _zod: { input: init.input, output: init.output }
   };
 }
@@ -213,7 +228,13 @@ function toRegistrationCapability(def, opts) {
       `capability ${def.type}: concurrency is required for registration \u2014 set it on defineCapability(...) or at neuron.handle(def, { concurrency }, fn)`
     );
   }
-  return { type: def.type, scope, concurrency };
+  const leaseTtlMs = opts?.leaseTtlMs ?? def.leaseTtlMs;
+  return {
+    type: def.type,
+    scope,
+    concurrency,
+    ...typeof leaseTtlMs === "number" ? { leaseTtlMs } : {}
+  };
 }
 
 // src/heartbeat.ts
@@ -259,155 +280,6 @@ var HeartbeatLoop = class {
   }
 };
 
-// src/lease-runner.ts
-var TerminalFailure = class extends Error {
-  constructor(reason, code) {
-    super(reason);
-    this.reason = reason;
-    this.code = code;
-    this.name = "TerminalFailure";
-  }
-};
-function validateInput(zod, validator, jsonSchema, data) {
-  if (zod) {
-    const result = zod.safeParse(data);
-    return result.success ? { ok: true, value: result.data } : { ok: false, errors: result.error.issues };
-  }
-  const errors = validator.validate(
-    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);
-  if (!inputCheck.ok) {
-    await sendNack(
-      transport,
-      lease.leaseId,
-      "schema-mismatch",
-      "lease input does not match inputSchema",
-      { code: "INPUT_SCHEMA_MISMATCH", details: { errors: inputCheck.errors } },
-      logger
-    );
-    return;
-  }
-  const parsedInput = inputCheck.value;
-  const progressFn = makeProgressFn(transport, lease.leaseId, logger);
-  const ctx = {
-    task: lease.task,
-    leaseId: lease.leaseId,
-    signal,
-    log: scopedLogger(logger, lease),
-    progress: progressFn,
-    fail: (reason, opts2) => {
-      throw new TerminalFailure(reason, opts2?.code);
-    }
-  };
-  let output;
-  try {
-    output = await handler(parsedInput, ctx);
-  } catch (err) {
-    if (signal.aborted || err.name === "AbortError") {
-      await sendNack(
-        transport,
-        lease.leaseId,
-        "cancelled",
-        "handler aborted",
-        { code: "CANCELLED" },
-        logger
-      );
-      return;
-    }
-    if (err instanceof TerminalFailure) {
-      await sendNack(
-        transport,
-        lease.leaseId,
-        "terminal",
-        err.reason,
-        { code: err.code ?? "HANDLER_TERMINAL" },
-        logger
-      );
-      return;
-    }
-    const message = err instanceof Error ? err.message : String(err);
-    logger.error({ err, leaseId: lease.leaseId }, "handler threw; nacking retryable");
-    await sendNack(
-      transport,
-      lease.leaseId,
-      "retryable",
-      message,
-      { code: "HANDLER_THREW" },
-      logger
-    );
-    return;
-  }
-  const outputCheck = validateInput(zodOutput, validator, lease.outputSchema, output);
-  if (!outputCheck.ok) {
-    await sendNack(
-      transport,
-      lease.leaseId,
-      "schema-mismatch",
-      "handler output does not match outputSchema",
-      { code: "OUTPUT_SCHEMA_MISMATCH", details: { errors: outputCheck.errors } },
-      logger
-    );
-    return;
-  }
-  const parsedOutput = outputCheck.value;
-  await transport.post(POST_PATH.ack, {
-    type: "ack",
-    leaseId: lease.leaseId,
-    output: parsedOutput,
-    completedAt: (/* @__PURE__ */ new Date()).toISOString()
-  }).catch((err) => {
-    logger.warn(
-      { err, leaseId: lease.leaseId },
-      "ack POST rejected by gateway; lease will be reclaimed by reaper"
-    );
-  });
-}
-async function sendNack(transport, leaseId, kind, reason, extras = {}, logger) {
-  await transport.post(POST_PATH.nack, {
-    type: "nack",
-    leaseId,
-    kind,
-    reason,
-    code: extras.code,
-    details: extras.details,
-    failedAt: (/* @__PURE__ */ new Date()).toISOString()
-  }).catch((err) => {
-    logger?.warn(
-      { err, leaseId, kind },
-      "nack POST rejected by gateway; lease will be reclaimed by reaper"
-    );
-  });
-}
-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 scopedLogger(logger, lease) {
-  const scope = { leaseId: lease.leaseId, taskId: lease.task.taskId };
-  return {
-    debug: (meta, msg) => logger.debug({ ...scope, ...meta }, msg),
-    info: (meta, msg) => logger.info({ ...scope, ...meta }, msg),
-    warn: (meta, msg) => logger.warn({ ...scope, ...meta }, msg),
-    error: (meta, msg) => logger.error({ ...scope, ...meta }, msg)
-  };
-}
-
 // src/logger.ts
 var noopLogger = {
   debug() {
@@ -419,43 +291,6 @@ var noopLogger = {
   error() {
   }
 };
-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() {
-    this.ajv = new Ajv({ allErrors: true, strict: false });
-    addFormats(this.ajv);
-  }
-  /**
-   * Returns null if the value matches the schema (or no schema given);
-   * otherwise an array of structured errors.
-   */
-  validate(schema, data) {
-    if (!schema || typeof schema !== "object") 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.cache.set(schema, validator);
-    }
-    const v = validator;
-    const ok = v(data);
-    return ok ? null : v.errors ?? [];
-  }
-};
 
 // src/sse-parser.ts
 async function* parseSSEStream(stream, signal) {
@@ -505,10 +340,10 @@ function parseBlock(block) {
   return { event, data: dataLines.join("\n") };
 }
 
-// src/transport.ts
-var Transport = class {
+// src/http-transport.ts
+var HttpTransport = class {
   opts;
-  callbacks;
+  callbacks = {};
   abortController = null;
   stopped = false;
   connected = false;
@@ -524,13 +359,9 @@ var Transport = class {
       logger: opts.logger ?? noopLogger,
       fetch: opts.fetch ?? globalThis.fetch.bind(globalThis)
     };
-    this.callbacks = {
-      onOpen: opts.onOpen,
-      onClose: opts.onClose,
-      onFrame: opts.onFrame,
-      onError: opts.onError,
-      onReconnecting: opts.onReconnecting
-    };
+  }
+  subscribe(callbacks) {
+    this.callbacks = callbacks;
   }
   isConnected() {
     return this.connected;
@@ -685,6 +516,192 @@ var TransportError = class extends Error {
   }
 };
 
+// src/lease-runner.ts
+var TerminalFailure = class extends Error {
+  constructor(reason, code) {
+    super(reason);
+    this.reason = reason;
+    this.code = code;
+    this.name = "TerminalFailure";
+  }
+};
+function validateInput(zod, validator, jsonSchema, data) {
+  if (zod) {
+    const result = zod.safeParse(data);
+    return result.success ? { ok: true, value: result.data } : { ok: false, errors: result.error.issues };
+  }
+  const errors = validator.validate(
+    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);
+  if (!inputCheck.ok) {
+    await sendNack(
+      transport,
+      lease.leaseId,
+      "schema-mismatch",
+      "lease input does not match inputSchema",
+      { code: "INPUT_SCHEMA_MISMATCH", details: { errors: inputCheck.errors } },
+      logger
+    );
+    return;
+  }
+  const parsedInput = inputCheck.value;
+  const progressFn = makeProgressFn(transport, lease.leaseId, logger);
+  const ctx = {
+    task: lease.task,
+    leaseId: lease.leaseId,
+    signal,
+    log: scopedLogger(logger, lease),
+    progress: progressFn,
+    fail: (reason, opts2) => {
+      throw new TerminalFailure(reason, opts2?.code);
+    }
+  };
+  let output;
+  try {
+    output = await handler(parsedInput, ctx);
+  } catch (err) {
+    if (signal.aborted || err.name === "AbortError") {
+      await sendNack(
+        transport,
+        lease.leaseId,
+        "cancelled",
+        "handler aborted",
+        { code: "CANCELLED" },
+        logger
+      );
+      return;
+    }
+    if (err instanceof TerminalFailure) {
+      await sendNack(
+        transport,
+        lease.leaseId,
+        "terminal",
+        err.reason,
+        { code: err.code ?? "HANDLER_TERMINAL" },
+        logger
+      );
+      return;
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    logger.error({ err, leaseId: lease.leaseId }, "handler threw; nacking retryable");
+    await sendNack(
+      transport,
+      lease.leaseId,
+      "retryable",
+      message,
+      { code: "HANDLER_THREW" },
+      logger
+    );
+    return;
+  }
+  const outputCheck = validateInput(zodOutput, validator, lease.outputSchema, output);
+  if (!outputCheck.ok) {
+    await sendNack(
+      transport,
+      lease.leaseId,
+      "schema-mismatch",
+      "handler output does not match outputSchema",
+      { code: "OUTPUT_SCHEMA_MISMATCH", details: { errors: outputCheck.errors } },
+      logger
+    );
+    return;
+  }
+  const parsedOutput = outputCheck.value;
+  await transport.post(POST_PATH.ack, {
+    type: "ack",
+    leaseId: lease.leaseId,
+    output: parsedOutput,
+    completedAt: (/* @__PURE__ */ new Date()).toISOString()
+  }).catch((err) => {
+    logger.warn(
+      { err, leaseId: lease.leaseId },
+      "ack POST rejected by gateway; lease will be reclaimed by reaper"
+    );
+  });
+}
+async function sendNack(transport, leaseId, kind, reason, extras = {}, logger) {
+  await transport.post(POST_PATH.nack, {
+    type: "nack",
+    leaseId,
+    kind,
+    reason,
+    code: extras.code,
+    details: extras.details,
+    failedAt: (/* @__PURE__ */ new Date()).toISOString()
+  }).catch((err) => {
+    logger?.warn(
+      { err, leaseId, kind },
+      "nack POST rejected by gateway; lease will be reclaimed by reaper"
+    );
+  });
+}
+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 scopedLogger(logger, lease) {
+  const scope = { leaseId: lease.leaseId, taskId: lease.task.taskId };
+  return {
+    debug: (meta, msg) => logger.debug({ ...scope, ...meta }, msg),
+    info: (meta, msg) => logger.info({ ...scope, ...meta }, msg),
+    warn: (meta, msg) => logger.warn({ ...scope, ...meta }, msg),
+    error: (meta, msg) => logger.error({ ...scope, ...meta }, msg)
+  };
+}
+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() {
+    this.ajv = new Ajv({ allErrors: true, strict: false });
+    addFormats(this.ajv);
+  }
+  /**
+   * Returns null if the value matches the schema (or no schema given);
+   * otherwise an array of structured errors.
+   */
+  validate(schema, data) {
+    if (!schema || typeof schema !== "object") 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.cache.set(schema, validator);
+    }
+    const v = validator;
+    const ok = v(data);
+    return ok ? null : v.errors ?? [];
+  }
+};
+
 // src/worker-pool.ts
 var WorkerPool = class {
   constructor(maxConcurrency) {
@@ -784,6 +801,9 @@ var ShutdownError = class extends Error {
 };
 
 // src/neuron.ts
+function isWithTransport(opts) {
+  return "transport" in opts && opts.transport !== void 0;
+}
 var Neuron = class extends eventemitter3.EventEmitter {
   transport;
   handlers = /* @__PURE__ */ new Map();
@@ -797,27 +817,25 @@ var Neuron = class extends eventemitter3.EventEmitter {
   heartbeat;
   validator;
   logger;
-  opts;
+  neuronId;
   started = false;
   stopping = false;
   hasOpenedOnce = false;
   constructor(opts) {
     super();
-    this.opts = opts;
     this.logger = opts.logger ?? noopLogger;
+    this.neuronId = opts.neuronId;
     this.validator = new SchemaValidator();
-    this.transport = new Transport({
+    this.transport = isWithTransport(opts) ? opts.transport : new HttpTransport({
       gatewayUrl: opts.gatewayUrl,
       neuronId: opts.neuronId,
       auth: opts.auth,
       logger: this.logger,
       initialReconnectDelayMs: opts.initialReconnectDelayMs,
       maxReconnectDelayMs: opts.maxReconnectDelayMs,
-      fetch: opts.fetch,
-      // Internal callbacks — Transport has a single subscriber (this
-      // Neuron) so a callbacks-on-options surface is simpler than an
-      // event emitter. The Neuron is the one that re-publishes lifecycle
-      // signals to its own consumers via the public emitter.
+      fetch: opts.fetch
+    });
+    this.transport.subscribe({
       onOpen: () => {
         this.emit("connection:open");
         void this.handleConnectionOpen();
@@ -911,7 +929,7 @@ var Neuron = class extends eventemitter3.EventEmitter {
     if (this.started && this.transport.isConnected()) {
       await this.transport.post(POST_PATH.updateCapability, {
         type: "update-capability",
-        neuronId: this.opts.neuronId,
+        neuronId: this.neuronId,
         capability: entry.capability
       }).catch((err) => {
         this.logger.warn(
@@ -1000,7 +1018,7 @@ var Neuron = class extends eventemitter3.EventEmitter {
   async postRegister() {
     await this.transport.post(POST_PATH.register, {
       type: "register",
-      neuronId: this.opts.neuronId,
+      neuronId: this.neuronId,
       protocolVersion: PROTOCOL_VERSION,
       capabilities: Array.from(this.handlers.values()).map((h) => h.capability)
     });
@@ -1110,11 +1128,11 @@ var Neuron = class extends eventemitter3.EventEmitter {
 };
 var SSE_EVENT_NAMES = SSE_EVENT;
 
+exports.HttpTransport = HttpTransport;
 exports.Neuron = Neuron;
 exports.SSE_EVENT_NAMES = SSE_EVENT_NAMES;
 exports.SchemaValidator = SchemaValidator;
 exports.ShutdownError = ShutdownError;
-exports.Transport = Transport;
 exports.TransportError = TransportError;
 exports.WorkerPool = WorkerPool;
 exports.defineCapability = defineCapability;