@holokai/neuron-sdk 0.6.0 → 0.7.0

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-Va7tTRVO.mjs';
-export { e as HandlerContext, f as HeartbeatInFlightEntry, L as LeasePayload, g as TaskPayload } from './transport-Va7tTRVO.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-BhFVHvR7.mjs';
+export { e as HandlerContext, f as HandlerFailureOptions, g as HeartbeatInFlightEntry, L as LeasePayload, h as TaskPayload } from './transport-BhFVHvR7.mjs';
 import { EventEmitter } from 'eventemitter3';
 import { z } from 'zod';
 import { ErrorObject } from 'ajv';
@@ -426,4 +426,18 @@ declare class SchemaValidator {
     validate(schema: JsonSchema | undefined, data: unknown): ErrorObject[] | null;
 }
 
-export { AuthCallback, Capability, type CapabilityDef, type CapabilityDefInit, CapabilityHandleOptions, type CapabilityPlanShape, CapabilityRegistration, Handler, HttpTransport, type HttpTransportOptions, Neuron, type NeuronEvents, NeuronLogger, type NeuronOptions, SSE_EVENT_NAMES, SchemaValidator, ServerToNeuronFrame, ShutdownError, Transport, TransportCallbacks, TransportError, WorkerPool, defineCapability, toPlanShape, toRegistrationCapability };
+/**
+ * The exception `ctx.fail()` throws to short-circuit the handler with a
+ * nack. Caught by the runner; consumers should not catch it. Exported so a
+ * wrapper around a handler can raise one for a refusal the handler answered
+ * as data.
+ */
+declare class HandlerFailure extends Error {
+    readonly reason: string;
+    readonly code?: string | undefined;
+    readonly details?: unknown | undefined;
+    readonly kind: 'terminal' | 'retryable';
+    constructor(reason: string, code?: string | undefined, details?: unknown | undefined, kind?: 'terminal' | 'retryable');
+}
+
+export { AuthCallback, Capability, type CapabilityDef, type CapabilityDefInit, CapabilityHandleOptions, type CapabilityPlanShape, CapabilityRegistration, Handler, HandlerFailure, HttpTransport, type HttpTransportOptions, Neuron, type NeuronEvents, NeuronLogger, type NeuronOptions, SSE_EVENT_NAMES, SchemaValidator, ServerToNeuronFrame, ShutdownError, Transport, TransportCallbacks, TransportError, WorkerPool, defineCapability, toPlanShape, toRegistrationCapability };

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-Va7tTRVO.js';
-export { e as HandlerContext, f as HeartbeatInFlightEntry, L as LeasePayload, g as TaskPayload } from './transport-Va7tTRVO.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-BhFVHvR7.js';
+export { e as HandlerContext, f as HandlerFailureOptions, g as HeartbeatInFlightEntry, L as LeasePayload, h as TaskPayload } from './transport-BhFVHvR7.js';
 import { EventEmitter } from 'eventemitter3';
 import { z } from 'zod';
 import { ErrorObject } from 'ajv';
@@ -426,4 +426,18 @@ declare class SchemaValidator {
     validate(schema: JsonSchema | undefined, data: unknown): ErrorObject[] | null;
 }
 
-export { AuthCallback, Capability, type CapabilityDef, type CapabilityDefInit, CapabilityHandleOptions, type CapabilityPlanShape, CapabilityRegistration, Handler, HttpTransport, type HttpTransportOptions, Neuron, type NeuronEvents, NeuronLogger, type NeuronOptions, SSE_EVENT_NAMES, SchemaValidator, ServerToNeuronFrame, ShutdownError, Transport, TransportCallbacks, TransportError, WorkerPool, defineCapability, toPlanShape, toRegistrationCapability };
+/**
+ * The exception `ctx.fail()` throws to short-circuit the handler with a
+ * nack. Caught by the runner; consumers should not catch it. Exported so a
+ * wrapper around a handler can raise one for a refusal the handler answered
+ * as data.
+ */
+declare class HandlerFailure extends Error {
+    readonly reason: string;
+    readonly code?: string | undefined;
+    readonly details?: unknown | undefined;
+    readonly kind: 'terminal' | 'retryable';
+    constructor(reason: string, code?: string | undefined, details?: unknown | undefined, kind?: 'terminal' | 'retryable');
+}
+
+export { AuthCallback, Capability, type CapabilityDef, type CapabilityDefInit, CapabilityHandleOptions, type CapabilityPlanShape, CapabilityRegistration, Handler, HandlerFailure, HttpTransport, type HttpTransportOptions, Neuron, type NeuronEvents, NeuronLogger, type NeuronOptions, SSE_EVENT_NAMES, SchemaValidator, ServerToNeuronFrame, ShutdownError, Transport, TransportCallbacks, TransportError, WorkerPool, defineCapability, toPlanShape, toRegistrationCapability };

package/dist/index.js

@@ -579,13 +579,16 @@ var TransportError = class extends Error {
 };
 
 // src/lease-runner.ts
-var TerminalFailure = class extends Error {
-  constructor(reason, code) {
+var HandlerFailure = class extends Error {
+  constructor(reason, code, details, kind = "terminal") {
     super(reason);
     this.reason = reason;
     this.code = code;
-    this.name = "TerminalFailure";
+    this.details = details;
+    this.name = "HandlerFailure";
+    this.kind = kind;
   }
+  kind;
 };
 var DEFAULT_PROGRESS_TIMEOUT_MS = 5e3;
 function validateInput(zod, validator, jsonSchema, data) {
@@ -593,10 +596,7 @@ function validateInput(zod, validator, jsonSchema, data) {
     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
-  );
+  const errors = validator.validate(jsonSchema, data);
   return errors === null ? { ok: true, value: data } : { ok: false, errors };
 }
 async function runLease(opts) {
@@ -626,7 +626,13 @@ async function runLease(opts) {
     return;
   }
   const parsedInput = inputCheck.value;
-  const reporter = makeProgressReporter(transport, lease.leaseId, logger, signal, progressTimeoutMs);
+  const reporter = makeProgressReporter(
+    transport,
+    lease.leaseId,
+    logger,
+    signal,
+    progressTimeoutMs
+  );
   const ctx = {
     task: lease.task,
     leaseId: lease.leaseId,
@@ -634,7 +640,7 @@ async function runLease(opts) {
     log: scopedLogger(logger, lease),
     progress: reporter.progress,
     fail: (reason, opts2) => {
-      throw new TerminalFailure(reason, opts2?.code);
+      throw new HandlerFailure(reason, opts2?.code, opts2?.details, opts2?.kind);
     }
   };
   let output;
@@ -654,13 +660,16 @@ async function runLease(opts) {
       );
       return;
     }
-    if (err instanceof TerminalFailure) {
+    if (err instanceof HandlerFailure) {
       await sendNack(
         transport,
         lease.leaseId,
-        "terminal",
+        err.kind,
         err.reason,
-        { code: err.code ?? "HANDLER_TERMINAL" },
+        {
+          code: err.code ?? (err.kind === "terminal" ? "HANDLER_TERMINAL" : "HANDLER_RETRYABLE"),
+          ...err.details !== void 0 ? { details: err.details } : {}
+        },
         logger
       );
       return;
@@ -1251,6 +1260,7 @@ var Neuron = class extends eventemitter3.EventEmitter {
 };
 var SSE_EVENT_NAMES = SSE_EVENT;
 
+exports.HandlerFailure = HandlerFailure;
 exports.HttpTransport = HttpTransport;
 exports.Neuron = Neuron;
 exports.SSE_EVENT_NAMES = SSE_EVENT_NAMES;