@holokai/neuron-sdk 0.3.0 → 0.5.0

package/dist/{transport-QqkooS7K.d.mts → transport-Ckcwj-Do.d.mts}

@@ -13,6 +13,27 @@ declare const CapabilitySchema: z.ZodObject<{
         onBehalfOf: string;
     }>]>;
     concurrency: z.ZodNumber;
+    /**
+     * 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.ZodOptional<z.ZodString>;
+    /**
+     * 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()`.)
+     */
+    inputSchema: z.ZodOptional<z.ZodEffects<z.ZodUnknown, unknown, unknown>>;
+    /** JSON Schema for the capability's output payload — same rules as inputSchema. */
+    outputSchema: z.ZodOptional<z.ZodEffects<z.ZodUnknown, unknown, unknown>>;
     /**
      * Per-capability lease TTL override in milliseconds (HOL-356).
      * The gateway uses this when minting a lease's `expiresAt`; absent
@@ -33,6 +54,9 @@ declare const CapabilitySchema: z.ZodObject<{
         onBehalfOf: string;
     };
     concurrency: number;
+    description?: string | undefined;
+    inputSchema?: unknown;
+    outputSchema?: unknown;
     leaseTtlMs?: number | undefined;
 }, {
     type: string;
@@ -40,6 +64,9 @@ declare const CapabilitySchema: z.ZodObject<{
         onBehalfOf: string;
     };
     concurrency: number;
+    description?: string | undefined;
+    inputSchema?: unknown;
+    outputSchema?: unknown;
     leaseTtlMs?: number | undefined;
 }>;
 type Capability = z.infer<typeof CapabilitySchema>;
@@ -145,6 +172,9 @@ declare const RegisterFrameSchema: z.ZodObject<{
             onBehalfOf: string;
         }>]>;
         concurrency: z.ZodNumber;
+        description: z.ZodOptional<z.ZodString>;
+        inputSchema: z.ZodOptional<z.ZodEffects<z.ZodUnknown, unknown, unknown>>;
+        outputSchema: z.ZodOptional<z.ZodEffects<z.ZodUnknown, unknown, unknown>>;
         leaseTtlMs: z.ZodOptional<z.ZodNumber>;
     }, "strict", z.ZodTypeAny, {
         type: string;
@@ -152,6 +182,9 @@ declare const RegisterFrameSchema: z.ZodObject<{
             onBehalfOf: string;
         };
         concurrency: number;
+        description?: string | undefined;
+        inputSchema?: unknown;
+        outputSchema?: unknown;
         leaseTtlMs?: number | undefined;
     }, {
         type: string;
@@ -159,6 +192,9 @@ declare const RegisterFrameSchema: z.ZodObject<{
             onBehalfOf: string;
         };
         concurrency: number;
+        description?: string | undefined;
+        inputSchema?: unknown;
+        outputSchema?: unknown;
         leaseTtlMs?: number | undefined;
     }>, "many">, {
         type: string;
@@ -166,6 +202,9 @@ declare const RegisterFrameSchema: z.ZodObject<{
             onBehalfOf: string;
         };
         concurrency: number;
+        description?: string | undefined;
+        inputSchema?: unknown;
+        outputSchema?: unknown;
         leaseTtlMs?: number | undefined;
     }[], {
         type: string;
@@ -173,6 +212,9 @@ declare const RegisterFrameSchema: z.ZodObject<{
             onBehalfOf: string;
         };
         concurrency: number;
+        description?: string | undefined;
+        inputSchema?: unknown;
+        outputSchema?: unknown;
         leaseTtlMs?: number | undefined;
     }[]>;
 }, "strict", z.ZodTypeAny, {
@@ -185,6 +227,9 @@ declare const RegisterFrameSchema: z.ZodObject<{
             onBehalfOf: string;
         };
         concurrency: number;
+        description?: string | undefined;
+        inputSchema?: unknown;
+        outputSchema?: unknown;
         leaseTtlMs?: number | undefined;
     }[];
 }, {
@@ -197,6 +242,9 @@ declare const RegisterFrameSchema: z.ZodObject<{
             onBehalfOf: string;
         };
         concurrency: number;
+        description?: string | undefined;
+        inputSchema?: unknown;
+        outputSchema?: unknown;
         leaseTtlMs?: number | undefined;
     }[];
 }>;
@@ -214,6 +262,9 @@ declare const UpdateCapabilityFrameSchema: z.ZodObject<{
             onBehalfOf: string;
         }>]>;
         concurrency: z.ZodNumber;
+        description: z.ZodOptional<z.ZodString>;
+        inputSchema: z.ZodOptional<z.ZodEffects<z.ZodUnknown, unknown, unknown>>;
+        outputSchema: z.ZodOptional<z.ZodEffects<z.ZodUnknown, unknown, unknown>>;
         leaseTtlMs: z.ZodOptional<z.ZodNumber>;
     }, "strict", z.ZodTypeAny, {
         type: string;
@@ -221,6 +272,9 @@ declare const UpdateCapabilityFrameSchema: z.ZodObject<{
             onBehalfOf: string;
         };
         concurrency: number;
+        description?: string | undefined;
+        inputSchema?: unknown;
+        outputSchema?: unknown;
         leaseTtlMs?: number | undefined;
     }, {
         type: string;
@@ -228,6 +282,9 @@ declare const UpdateCapabilityFrameSchema: z.ZodObject<{
             onBehalfOf: string;
         };
         concurrency: number;
+        description?: string | undefined;
+        inputSchema?: unknown;
+        outputSchema?: unknown;
         leaseTtlMs?: number | undefined;
     }>;
 }, "strict", z.ZodTypeAny, {
@@ -238,6 +295,9 @@ declare const UpdateCapabilityFrameSchema: z.ZodObject<{
             onBehalfOf: string;
         };
         concurrency: number;
+        description?: string | undefined;
+        inputSchema?: unknown;
+        outputSchema?: unknown;
         leaseTtlMs?: number | undefined;
     };
     neuronId: string;
@@ -249,6 +309,9 @@ declare const UpdateCapabilityFrameSchema: z.ZodObject<{
             onBehalfOf: string;
         };
         concurrency: number;
+        description?: string | undefined;
+        inputSchema?: unknown;
+        outputSchema?: unknown;
         leaseTtlMs?: number | undefined;
     };
     neuronId: string;
@@ -384,6 +447,9 @@ declare const ServerToNeuronFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             onBehalfOf: string;
         }>]>;
         concurrency: z.ZodNumber;
+        description: z.ZodOptional<z.ZodString>;
+        inputSchema: z.ZodOptional<z.ZodEffects<z.ZodUnknown, unknown, unknown>>;
+        outputSchema: z.ZodOptional<z.ZodEffects<z.ZodUnknown, unknown, unknown>>;
         leaseTtlMs: z.ZodOptional<z.ZodNumber>;
     }, "strict", z.ZodTypeAny, {
         type: string;
@@ -391,6 +457,9 @@ declare const ServerToNeuronFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             onBehalfOf: string;
         };
         concurrency: number;
+        description?: string | undefined;
+        inputSchema?: unknown;
+        outputSchema?: unknown;
         leaseTtlMs?: number | undefined;
     }, {
         type: string;
@@ -398,6 +467,9 @@ declare const ServerToNeuronFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             onBehalfOf: string;
         };
         concurrency: number;
+        description?: string | undefined;
+        inputSchema?: unknown;
+        outputSchema?: unknown;
         leaseTtlMs?: number | undefined;
     }>, "many">;
     acceptedAt: z.ZodString;
@@ -409,6 +481,9 @@ declare const ServerToNeuronFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             onBehalfOf: string;
         };
         concurrency: number;
+        description?: string | undefined;
+        inputSchema?: unknown;
+        outputSchema?: unknown;
         leaseTtlMs?: number | undefined;
     }[];
     sessionId: string;
@@ -421,6 +496,9 @@ declare const ServerToNeuronFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             onBehalfOf: string;
         };
         concurrency: number;
+        description?: string | undefined;
+        inputSchema?: unknown;
+        outputSchema?: unknown;
         leaseTtlMs?: number | undefined;
     }[];
     sessionId: string;
@@ -612,7 +690,10 @@ interface HandlerContext {
     log: NeuronLogger;
     /**
      * Send a `progress` frame to the gateway. Non-blocking; safe to call
-     * many times during a long-running handler.
+     * many times during a long-running handler. Frames are sent one at a time
+     * in call order, each bounded by a timeout, and the lease's ack or nack
+     * waits until they have gone. A cancelled lease drops the frames it has
+     * not started sending and nacks at once.
      */
     progress(update: {
         percent?: number;
@@ -637,11 +718,16 @@ interface HandlerContext {
 interface CapabilityRegistration extends Capability {
     /** JSON Schema validated against the lease input before invoking the
      *  handler. Mismatch produces a `schema-mismatch` nack and the handler
-     *  is never called. */
+     *  is never called. This is the authority for inbound validation — the
+     *  `inputSchema` on the lease frame is ignored (HOL-2913). Omit it and
+     *  input is not validated client-side at all. Also advertised on the
+     *  register frame (HOL-2926) so the capability catalog knows the
+     *  contract. */
     inputSchema?: JsonSchema;
     /** JSON Schema validated against the handler's return value. Mismatch
      *  produces a `schema-mismatch` nack and the gateway publishes a failed
-     *  TaskResult. */
+     *  TaskResult. Same authority as `inputSchema`; note the gateway also
+     *  validates ack output against its own schema regardless. */
     outputSchema?: JsonSchema;
 }
 /**
@@ -653,6 +739,12 @@ interface CapabilityRegistration extends Capability {
 interface CapabilityHandleOptions {
     scope?: Capability['scope'];
     concurrency?: number;
+    /**
+     * Overrides the def's `description` in the advertised contract
+     * (HOL-2926) — e.g. a deployment-specific wording. Rarely needed; the
+     * def's description is used when absent.
+     */
+    description?: string;
     /**
      * Per-capability lease TTL override (HOL-356). Wins over the same
      * field on the def. See `CapabilityDefInit.leaseTtlMs` for shape;

package/dist/{transport-QqkooS7K.d.ts → transport-Ckcwj-Do.d.ts}

@@ -13,6 +13,27 @@ declare const CapabilitySchema: z.ZodObject<{
         onBehalfOf: string;
     }>]>;
     concurrency: z.ZodNumber;
+    /**
+     * 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.ZodOptional<z.ZodString>;
+    /**
+     * 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()`.)
+     */
+    inputSchema: z.ZodOptional<z.ZodEffects<z.ZodUnknown, unknown, unknown>>;
+    /** JSON Schema for the capability's output payload — same rules as inputSchema. */
+    outputSchema: z.ZodOptional<z.ZodEffects<z.ZodUnknown, unknown, unknown>>;
     /**
      * Per-capability lease TTL override in milliseconds (HOL-356).
      * The gateway uses this when minting a lease's `expiresAt`; absent
@@ -33,6 +54,9 @@ declare const CapabilitySchema: z.ZodObject<{
         onBehalfOf: string;
     };
     concurrency: number;
+    description?: string | undefined;
+    inputSchema?: unknown;
+    outputSchema?: unknown;
     leaseTtlMs?: number | undefined;
 }, {
     type: string;
@@ -40,6 +64,9 @@ declare const CapabilitySchema: z.ZodObject<{
         onBehalfOf: string;
     };
     concurrency: number;
+    description?: string | undefined;
+    inputSchema?: unknown;
+    outputSchema?: unknown;
     leaseTtlMs?: number | undefined;
 }>;
 type Capability = z.infer<typeof CapabilitySchema>;
@@ -145,6 +172,9 @@ declare const RegisterFrameSchema: z.ZodObject<{
             onBehalfOf: string;
         }>]>;
         concurrency: z.ZodNumber;
+        description: z.ZodOptional<z.ZodString>;
+        inputSchema: z.ZodOptional<z.ZodEffects<z.ZodUnknown, unknown, unknown>>;
+        outputSchema: z.ZodOptional<z.ZodEffects<z.ZodUnknown, unknown, unknown>>;
         leaseTtlMs: z.ZodOptional<z.ZodNumber>;
     }, "strict", z.ZodTypeAny, {
         type: string;
@@ -152,6 +182,9 @@ declare const RegisterFrameSchema: z.ZodObject<{
             onBehalfOf: string;
         };
         concurrency: number;
+        description?: string | undefined;
+        inputSchema?: unknown;
+        outputSchema?: unknown;
         leaseTtlMs?: number | undefined;
     }, {
         type: string;
@@ -159,6 +192,9 @@ declare const RegisterFrameSchema: z.ZodObject<{
             onBehalfOf: string;
         };
         concurrency: number;
+        description?: string | undefined;
+        inputSchema?: unknown;
+        outputSchema?: unknown;
         leaseTtlMs?: number | undefined;
     }>, "many">, {
         type: string;
@@ -166,6 +202,9 @@ declare const RegisterFrameSchema: z.ZodObject<{
             onBehalfOf: string;
         };
         concurrency: number;
+        description?: string | undefined;
+        inputSchema?: unknown;
+        outputSchema?: unknown;
         leaseTtlMs?: number | undefined;
     }[], {
         type: string;
@@ -173,6 +212,9 @@ declare const RegisterFrameSchema: z.ZodObject<{
             onBehalfOf: string;
         };
         concurrency: number;
+        description?: string | undefined;
+        inputSchema?: unknown;
+        outputSchema?: unknown;
         leaseTtlMs?: number | undefined;
     }[]>;
 }, "strict", z.ZodTypeAny, {
@@ -185,6 +227,9 @@ declare const RegisterFrameSchema: z.ZodObject<{
             onBehalfOf: string;
         };
         concurrency: number;
+        description?: string | undefined;
+        inputSchema?: unknown;
+        outputSchema?: unknown;
         leaseTtlMs?: number | undefined;
     }[];
 }, {
@@ -197,6 +242,9 @@ declare const RegisterFrameSchema: z.ZodObject<{
             onBehalfOf: string;
         };
         concurrency: number;
+        description?: string | undefined;
+        inputSchema?: unknown;
+        outputSchema?: unknown;
         leaseTtlMs?: number | undefined;
     }[];
 }>;
@@ -214,6 +262,9 @@ declare const UpdateCapabilityFrameSchema: z.ZodObject<{
             onBehalfOf: string;
         }>]>;
         concurrency: z.ZodNumber;
+        description: z.ZodOptional<z.ZodString>;
+        inputSchema: z.ZodOptional<z.ZodEffects<z.ZodUnknown, unknown, unknown>>;
+        outputSchema: z.ZodOptional<z.ZodEffects<z.ZodUnknown, unknown, unknown>>;
         leaseTtlMs: z.ZodOptional<z.ZodNumber>;
     }, "strict", z.ZodTypeAny, {
         type: string;
@@ -221,6 +272,9 @@ declare const UpdateCapabilityFrameSchema: z.ZodObject<{
             onBehalfOf: string;
         };
         concurrency: number;
+        description?: string | undefined;
+        inputSchema?: unknown;
+        outputSchema?: unknown;
         leaseTtlMs?: number | undefined;
     }, {
         type: string;
@@ -228,6 +282,9 @@ declare const UpdateCapabilityFrameSchema: z.ZodObject<{
             onBehalfOf: string;
         };
         concurrency: number;
+        description?: string | undefined;
+        inputSchema?: unknown;
+        outputSchema?: unknown;
         leaseTtlMs?: number | undefined;
     }>;
 }, "strict", z.ZodTypeAny, {
@@ -238,6 +295,9 @@ declare const UpdateCapabilityFrameSchema: z.ZodObject<{
             onBehalfOf: string;
         };
         concurrency: number;
+        description?: string | undefined;
+        inputSchema?: unknown;
+        outputSchema?: unknown;
         leaseTtlMs?: number | undefined;
     };
     neuronId: string;
@@ -249,6 +309,9 @@ declare const UpdateCapabilityFrameSchema: z.ZodObject<{
             onBehalfOf: string;
         };
         concurrency: number;
+        description?: string | undefined;
+        inputSchema?: unknown;
+        outputSchema?: unknown;
         leaseTtlMs?: number | undefined;
     };
     neuronId: string;
@@ -384,6 +447,9 @@ declare const ServerToNeuronFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             onBehalfOf: string;
         }>]>;
         concurrency: z.ZodNumber;
+        description: z.ZodOptional<z.ZodString>;
+        inputSchema: z.ZodOptional<z.ZodEffects<z.ZodUnknown, unknown, unknown>>;
+        outputSchema: z.ZodOptional<z.ZodEffects<z.ZodUnknown, unknown, unknown>>;
         leaseTtlMs: z.ZodOptional<z.ZodNumber>;
     }, "strict", z.ZodTypeAny, {
         type: string;
@@ -391,6 +457,9 @@ declare const ServerToNeuronFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             onBehalfOf: string;
         };
         concurrency: number;
+        description?: string | undefined;
+        inputSchema?: unknown;
+        outputSchema?: unknown;
         leaseTtlMs?: number | undefined;
     }, {
         type: string;
@@ -398,6 +467,9 @@ declare const ServerToNeuronFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             onBehalfOf: string;
         };
         concurrency: number;
+        description?: string | undefined;
+        inputSchema?: unknown;
+        outputSchema?: unknown;
         leaseTtlMs?: number | undefined;
     }>, "many">;
     acceptedAt: z.ZodString;
@@ -409,6 +481,9 @@ declare const ServerToNeuronFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             onBehalfOf: string;
         };
         concurrency: number;
+        description?: string | undefined;
+        inputSchema?: unknown;
+        outputSchema?: unknown;
         leaseTtlMs?: number | undefined;
     }[];
     sessionId: string;
@@ -421,6 +496,9 @@ declare const ServerToNeuronFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             onBehalfOf: string;
         };
         concurrency: number;
+        description?: string | undefined;
+        inputSchema?: unknown;
+        outputSchema?: unknown;
         leaseTtlMs?: number | undefined;
     }[];
     sessionId: string;
@@ -612,7 +690,10 @@ interface HandlerContext {
     log: NeuronLogger;
     /**
      * Send a `progress` frame to the gateway. Non-blocking; safe to call
-     * many times during a long-running handler.
+     * many times during a long-running handler. Frames are sent one at a time
+     * in call order, each bounded by a timeout, and the lease's ack or nack
+     * waits until they have gone. A cancelled lease drops the frames it has
+     * not started sending and nacks at once.
      */
     progress(update: {
         percent?: number;
@@ -637,11 +718,16 @@ interface HandlerContext {
 interface CapabilityRegistration extends Capability {
     /** JSON Schema validated against the lease input before invoking the
      *  handler. Mismatch produces a `schema-mismatch` nack and the handler
-     *  is never called. */
+     *  is never called. This is the authority for inbound validation — the
+     *  `inputSchema` on the lease frame is ignored (HOL-2913). Omit it and
+     *  input is not validated client-side at all. Also advertised on the
+     *  register frame (HOL-2926) so the capability catalog knows the
+     *  contract. */
     inputSchema?: JsonSchema;
     /** JSON Schema validated against the handler's return value. Mismatch
      *  produces a `schema-mismatch` nack and the gateway publishes a failed
-     *  TaskResult. */
+     *  TaskResult. Same authority as `inputSchema`; note the gateway also
+     *  validates ack output against its own schema regardless. */
     outputSchema?: JsonSchema;
 }
 /**
@@ -653,6 +739,12 @@ interface CapabilityRegistration extends Capability {
 interface CapabilityHandleOptions {
     scope?: Capability['scope'];
     concurrency?: number;
+    /**
+     * Overrides the def's `description` in the advertised contract
+     * (HOL-2926) — e.g. a deployment-specific wording. Rarely needed; the
+     * def's description is used when absent.
+     */
+    description?: string;
     /**
      * Per-capability lease TTL override (HOL-356). Wins over the same
      * field on the def. See `CapabilityDefInit.leaseTtlMs` for shape;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holokai/neuron-sdk",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "SDK for building Holokai neurons — connect to a BigBrain gateway over HTTP+SSE or Electron IPC and execute capability-typed tasks.",
   "license": "MIT",
   "author": "Holokai",
@@ -61,8 +61,8 @@
     "clean": "rm -rf dist",
     "test": "vitest run && pnpm run check:browser && pnpm run check:no-workspace",
     "test:watch": "vitest",
-    "check:browser": "pnpm run build && node scripts/check-browser-build.mjs",
-    "check:no-workspace": "pnpm run build && node scripts/check-no-workspace-imports.mjs",
+    "check:browser": "node scripts/check-browser-build.mjs",
+    "check:no-workspace": "node scripts/check-no-workspace-imports.mjs",
     "lint": "eslint src",
     "lint:fix": "eslint src --fix",
     "typecheck": "tsc --noEmit",