@holokai/neuron-sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1022 @@
+import { z } from 'zod';
+import { EventEmitter } from 'eventemitter3';
+import { ErrorObject } from 'ajv';
+
+/** Opaque JSON Schema; runtime structure handled by ajv at the gateway. */
+type JsonSchema = unknown;
+
+declare const CapabilitySchema: z.ZodObject<{
+    type: z.ZodString;
+    scope: z.ZodUnion<[z.ZodLiteral<"any">, z.ZodObject<{
+        onBehalfOf: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        onBehalfOf: string;
+    }, {
+        onBehalfOf: string;
+    }>]>;
+    concurrency: z.ZodNumber;
+}, "strict", z.ZodTypeAny, {
+    type: string;
+    scope: "any" | {
+        onBehalfOf: string;
+    };
+    concurrency: number;
+}, {
+    type: string;
+    scope: "any" | {
+        onBehalfOf: string;
+    };
+    concurrency: number;
+}>;
+type Capability = z.infer<typeof CapabilitySchema>;
+
+declare const TaskPayloadSchema: z.ZodObject<{
+    taskId: z.ZodString;
+    workflowId: z.ZodString;
+    capability: z.ZodString;
+    onBehalfOf: z.ZodOptional<z.ZodString>;
+    input: z.ZodUnknown;
+    attempt: z.ZodNumber;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strict", z.ZodTypeAny, {
+    taskId: string;
+    workflowId: string;
+    capability: string;
+    attempt: number;
+    onBehalfOf?: string | undefined;
+    input?: unknown;
+    metadata?: Record<string, unknown> | undefined;
+}, {
+    taskId: string;
+    workflowId: string;
+    capability: string;
+    attempt: number;
+    onBehalfOf?: string | undefined;
+    input?: unknown;
+    metadata?: Record<string, unknown> | undefined;
+}>;
+type TaskPayload = z.infer<typeof TaskPayloadSchema>;
+declare const LeasePayloadSchema: z.ZodObject<{
+    leaseId: z.ZodString;
+    expiresAt: z.ZodString;
+    task: z.ZodObject<{
+        taskId: z.ZodString;
+        workflowId: z.ZodString;
+        capability: z.ZodString;
+        onBehalfOf: z.ZodOptional<z.ZodString>;
+        input: z.ZodUnknown;
+        attempt: z.ZodNumber;
+        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strict", z.ZodTypeAny, {
+        taskId: string;
+        workflowId: string;
+        capability: string;
+        attempt: number;
+        onBehalfOf?: string | undefined;
+        input?: unknown;
+        metadata?: Record<string, unknown> | undefined;
+    }, {
+        taskId: string;
+        workflowId: string;
+        capability: string;
+        attempt: number;
+        onBehalfOf?: string | undefined;
+        input?: unknown;
+        metadata?: Record<string, unknown> | undefined;
+    }>;
+    inputSchema: z.ZodUnknown;
+    outputSchema: z.ZodUnknown;
+}, "strict", z.ZodTypeAny, {
+    leaseId: string;
+    expiresAt: string;
+    task: {
+        taskId: string;
+        workflowId: string;
+        capability: string;
+        attempt: number;
+        onBehalfOf?: string | undefined;
+        input?: unknown;
+        metadata?: Record<string, unknown> | undefined;
+    };
+    inputSchema?: unknown;
+    outputSchema?: unknown;
+}, {
+    leaseId: string;
+    expiresAt: string;
+    task: {
+        taskId: string;
+        workflowId: string;
+        capability: string;
+        attempt: number;
+        onBehalfOf?: string | undefined;
+        input?: unknown;
+        metadata?: Record<string, unknown> | undefined;
+    };
+    inputSchema?: unknown;
+    outputSchema?: unknown;
+}>;
+type LeasePayload = z.infer<typeof LeasePayloadSchema>;
+
+declare const RegisterFrameSchema: z.ZodObject<{
+    type: z.ZodLiteral<"register">;
+    neuronId: z.ZodString;
+    protocolVersion: z.ZodString;
+    capabilities: z.ZodEffects<z.ZodArray<z.ZodObject<{
+        type: z.ZodString;
+        scope: z.ZodUnion<[z.ZodLiteral<"any">, z.ZodObject<{
+            onBehalfOf: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            onBehalfOf: string;
+        }, {
+            onBehalfOf: string;
+        }>]>;
+        concurrency: z.ZodNumber;
+    }, "strict", z.ZodTypeAny, {
+        type: string;
+        scope: "any" | {
+            onBehalfOf: string;
+        };
+        concurrency: number;
+    }, {
+        type: string;
+        scope: "any" | {
+            onBehalfOf: string;
+        };
+        concurrency: number;
+    }>, "many">, {
+        type: string;
+        scope: "any" | {
+            onBehalfOf: string;
+        };
+        concurrency: number;
+    }[], {
+        type: string;
+        scope: "any" | {
+            onBehalfOf: string;
+        };
+        concurrency: number;
+    }[]>;
+}, "strict", z.ZodTypeAny, {
+    type: "register";
+    neuronId: string;
+    protocolVersion: string;
+    capabilities: {
+        type: string;
+        scope: "any" | {
+            onBehalfOf: string;
+        };
+        concurrency: number;
+    }[];
+}, {
+    type: "register";
+    neuronId: string;
+    protocolVersion: string;
+    capabilities: {
+        type: string;
+        scope: "any" | {
+            onBehalfOf: string;
+        };
+        concurrency: number;
+    }[];
+}>;
+type RegisterFrame = z.infer<typeof RegisterFrameSchema>;
+declare const UpdateCapabilityFrameSchema: z.ZodObject<{
+    type: z.ZodLiteral<"update-capability">;
+    neuronId: z.ZodString;
+    capability: z.ZodObject<{
+        type: z.ZodString;
+        scope: z.ZodUnion<[z.ZodLiteral<"any">, z.ZodObject<{
+            onBehalfOf: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            onBehalfOf: string;
+        }, {
+            onBehalfOf: string;
+        }>]>;
+        concurrency: z.ZodNumber;
+    }, "strict", z.ZodTypeAny, {
+        type: string;
+        scope: "any" | {
+            onBehalfOf: string;
+        };
+        concurrency: number;
+    }, {
+        type: string;
+        scope: "any" | {
+            onBehalfOf: string;
+        };
+        concurrency: number;
+    }>;
+}, "strict", z.ZodTypeAny, {
+    type: "update-capability";
+    capability: {
+        type: string;
+        scope: "any" | {
+            onBehalfOf: string;
+        };
+        concurrency: number;
+    };
+    neuronId: string;
+}, {
+    type: "update-capability";
+    capability: {
+        type: string;
+        scope: "any" | {
+            onBehalfOf: string;
+        };
+        concurrency: number;
+    };
+    neuronId: string;
+}>;
+type UpdateCapabilityFrame = z.infer<typeof UpdateCapabilityFrameSchema>;
+declare const HeartbeatInFlightEntrySchema: z.ZodObject<{
+    leaseId: z.ZodString;
+    taskId: z.ZodString;
+    startedAt: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    taskId: string;
+    leaseId: string;
+    startedAt: string;
+}, {
+    taskId: string;
+    leaseId: string;
+    startedAt: string;
+}>;
+type HeartbeatInFlightEntry = z.infer<typeof HeartbeatInFlightEntrySchema>;
+declare const HeartbeatFrameSchema: z.ZodObject<{
+    type: z.ZodLiteral<"heartbeat">;
+    neuronId: z.ZodString;
+    inFlight: z.ZodArray<z.ZodObject<{
+        leaseId: z.ZodString;
+        taskId: z.ZodString;
+        startedAt: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        taskId: string;
+        leaseId: string;
+        startedAt: string;
+    }, {
+        taskId: string;
+        leaseId: string;
+        startedAt: string;
+    }>, "many">;
+    sentAt: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    type: "heartbeat";
+    neuronId: string;
+    inFlight: {
+        taskId: string;
+        leaseId: string;
+        startedAt: string;
+    }[];
+    sentAt: string;
+}, {
+    type: "heartbeat";
+    neuronId: string;
+    inFlight: {
+        taskId: string;
+        leaseId: string;
+        startedAt: string;
+    }[];
+    sentAt: string;
+}>;
+type HeartbeatFrame = z.infer<typeof HeartbeatFrameSchema>;
+declare const AckFrameSchema: z.ZodObject<{
+    type: z.ZodLiteral<"ack">;
+    leaseId: z.ZodString;
+    output: z.ZodUnknown;
+    completedAt: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    type: "ack";
+    leaseId: string;
+    completedAt: string;
+    output?: unknown;
+}, {
+    type: "ack";
+    leaseId: string;
+    completedAt: string;
+    output?: unknown;
+}>;
+type AckFrame = z.infer<typeof AckFrameSchema>;
+declare const NackFrameSchema: z.ZodObject<{
+    type: z.ZodLiteral<"nack">;
+    leaseId: z.ZodString;
+    kind: z.ZodEnum<["retryable", "terminal", "schema-mismatch", "cancelled"]>;
+    reason: z.ZodString;
+    code: z.ZodOptional<z.ZodString>;
+    details: z.ZodOptional<z.ZodUnknown>;
+    failedAt: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    type: "nack";
+    leaseId: string;
+    kind: "retryable" | "terminal" | "schema-mismatch" | "cancelled";
+    reason: string;
+    failedAt: string;
+    code?: string | undefined;
+    details?: unknown;
+}, {
+    type: "nack";
+    leaseId: string;
+    kind: "retryable" | "terminal" | "schema-mismatch" | "cancelled";
+    reason: string;
+    failedAt: string;
+    code?: string | undefined;
+    details?: unknown;
+}>;
+type NackFrame = z.infer<typeof NackFrameSchema>;
+declare const ProgressFrameSchema: z.ZodObject<{
+    type: z.ZodLiteral<"progress">;
+    leaseId: z.ZodString;
+    percent: z.ZodOptional<z.ZodNumber>;
+    message: z.ZodOptional<z.ZodString>;
+    data: z.ZodOptional<z.ZodUnknown>;
+    sentAt: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    type: "progress";
+    leaseId: string;
+    sentAt: string;
+    message?: string | undefined;
+    percent?: number | undefined;
+    data?: unknown;
+}, {
+    type: "progress";
+    leaseId: string;
+    sentAt: string;
+    message?: string | undefined;
+    percent?: number | undefined;
+    data?: unknown;
+}>;
+type ProgressFrame = z.infer<typeof ProgressFrameSchema>;
+declare const ServerToNeuronFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+    type: z.ZodLiteral<"registered">;
+    sessionId: z.ZodString;
+    capabilities: z.ZodArray<z.ZodObject<{
+        type: z.ZodString;
+        scope: z.ZodUnion<[z.ZodLiteral<"any">, z.ZodObject<{
+            onBehalfOf: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            onBehalfOf: string;
+        }, {
+            onBehalfOf: string;
+        }>]>;
+        concurrency: z.ZodNumber;
+    }, "strict", z.ZodTypeAny, {
+        type: string;
+        scope: "any" | {
+            onBehalfOf: string;
+        };
+        concurrency: number;
+    }, {
+        type: string;
+        scope: "any" | {
+            onBehalfOf: string;
+        };
+        concurrency: number;
+    }>, "many">;
+    acceptedAt: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    type: "registered";
+    capabilities: {
+        type: string;
+        scope: "any" | {
+            onBehalfOf: string;
+        };
+        concurrency: number;
+    }[];
+    sessionId: string;
+    acceptedAt: string;
+}, {
+    type: "registered";
+    capabilities: {
+        type: string;
+        scope: "any" | {
+            onBehalfOf: string;
+        };
+        concurrency: number;
+    }[];
+    sessionId: string;
+    acceptedAt: string;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"lease">;
+    lease: z.ZodObject<{
+        leaseId: z.ZodString;
+        expiresAt: z.ZodString;
+        task: z.ZodObject<{
+            taskId: z.ZodString;
+            workflowId: z.ZodString;
+            capability: z.ZodString;
+            onBehalfOf: z.ZodOptional<z.ZodString>;
+            input: z.ZodUnknown;
+            attempt: z.ZodNumber;
+            metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, "strict", z.ZodTypeAny, {
+            taskId: string;
+            workflowId: string;
+            capability: string;
+            attempt: number;
+            onBehalfOf?: string | undefined;
+            input?: unknown;
+            metadata?: Record<string, unknown> | undefined;
+        }, {
+            taskId: string;
+            workflowId: string;
+            capability: string;
+            attempt: number;
+            onBehalfOf?: string | undefined;
+            input?: unknown;
+            metadata?: Record<string, unknown> | undefined;
+        }>;
+        inputSchema: z.ZodUnknown;
+        outputSchema: z.ZodUnknown;
+    }, "strict", z.ZodTypeAny, {
+        leaseId: string;
+        expiresAt: string;
+        task: {
+            taskId: string;
+            workflowId: string;
+            capability: string;
+            attempt: number;
+            onBehalfOf?: string | undefined;
+            input?: unknown;
+            metadata?: Record<string, unknown> | undefined;
+        };
+        inputSchema?: unknown;
+        outputSchema?: unknown;
+    }, {
+        leaseId: string;
+        expiresAt: string;
+        task: {
+            taskId: string;
+            workflowId: string;
+            capability: string;
+            attempt: number;
+            onBehalfOf?: string | undefined;
+            input?: unknown;
+            metadata?: Record<string, unknown> | undefined;
+        };
+        inputSchema?: unknown;
+        outputSchema?: unknown;
+    }>;
+    sentAt: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    type: "lease";
+    sentAt: string;
+    lease: {
+        leaseId: string;
+        expiresAt: string;
+        task: {
+            taskId: string;
+            workflowId: string;
+            capability: string;
+            attempt: number;
+            onBehalfOf?: string | undefined;
+            input?: unknown;
+            metadata?: Record<string, unknown> | undefined;
+        };
+        inputSchema?: unknown;
+        outputSchema?: unknown;
+    };
+}, {
+    type: "lease";
+    sentAt: string;
+    lease: {
+        leaseId: string;
+        expiresAt: string;
+        task: {
+            taskId: string;
+            workflowId: string;
+            capability: string;
+            attempt: number;
+            onBehalfOf?: string | undefined;
+            input?: unknown;
+            metadata?: Record<string, unknown> | undefined;
+        };
+        inputSchema?: unknown;
+        outputSchema?: unknown;
+    };
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"cancel">;
+    leaseId: z.ZodString;
+    reason: z.ZodString;
+    cancelledAt: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    type: "cancel";
+    leaseId: string;
+    reason: string;
+    cancelledAt: string;
+}, {
+    type: "cancel";
+    leaseId: string;
+    reason: string;
+    cancelledAt: string;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"capability-revoked">;
+    capability: z.ZodString;
+    reason: z.ZodString;
+    revokedAt: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    type: "capability-revoked";
+    capability: string;
+    reason: string;
+    revokedAt: string;
+}, {
+    type: "capability-revoked";
+    capability: string;
+    reason: string;
+    revokedAt: string;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"disconnect">;
+    reason: z.ZodString;
+    code: z.ZodOptional<z.ZodString>;
+    reconnectable: z.ZodBoolean;
+    sentAt: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    type: "disconnect";
+    sentAt: string;
+    reason: string;
+    reconnectable: boolean;
+    code?: string | undefined;
+}, {
+    type: "disconnect";
+    sentAt: string;
+    reason: string;
+    reconnectable: boolean;
+    code?: string | undefined;
+}>]>;
+type ServerToNeuronFrame = z.infer<typeof ServerToNeuronFrameSchema>;
+
+declare const POST_PATH: {
+    readonly register: "/neuron/register";
+    readonly updateCapability: "/neuron/update-capability";
+    readonly heartbeat: "/neuron/heartbeat";
+    readonly ack: "/neuron/ack";
+    readonly nack: "/neuron/nack";
+    readonly progress: "/neuron/progress";
+};
+type PostPath = (typeof POST_PATH)[keyof typeof POST_PATH];
+
+/** Function returning the current bearer JWT. Called on each POST and SSE
+ *  open; can refresh tokens internally. The SDK retries once on 401, so
+ *  refreshing on 401 inside the callback is the right place to do it. */
+type AuthCallback = () => Promise<string> | string;
+/** Logger surface — minimal shape so consumers can plug in pino, console,
+ *  etc. without an interface mismatch. */
+interface NeuronLogger {
+    debug(meta: Record<string, unknown>, msg?: string): void;
+    info(meta: Record<string, unknown>, msg?: string): void;
+    warn(meta: Record<string, unknown>, msg?: string): void;
+    error(meta: Record<string, unknown>, msg?: string): void;
+}
+/** Per-handler context passed to `neuron.handle(...)` callbacks. */
+interface HandlerContext {
+    /** Lease metadata for this delivery. */
+    task: TaskPayload;
+    /** UUID identifying the lease the gateway holds for this task. */
+    leaseId: string;
+    /**
+     * AbortSignal that fires when the gateway sends a `cancel` frame for
+     * this lease (workflow cancellation) or the SDK is shutting down.
+     * Handlers that wrap fetch/HTTP calls should pass this signal through.
+     */
+    signal: AbortSignal;
+    /** Logger scoped to this lease. */
+    log: NeuronLogger;
+    /**
+     * Send a `progress` frame to the gateway. Non-blocking; safe to call
+     * many times during a long-running handler.
+     */
+    progress(update: {
+        percent?: number;
+        message?: string;
+        data?: unknown;
+    }): void;
+    /**
+     * Terminal failure — short-circuits the handler with a non-retryable
+     * nack containing the given reason. Throws an internal error to bail
+     * out of the handler; do not catch it.
+     */
+    fail(reason: string, opts?: {
+        code?: string;
+    }): never;
+}
+/**
+ * Low-level capability registration: type + scope + concurrency + optional
+ * schemas. Most users go through `defineCapability` + `neuron.handle(def,
+ * fn)` instead, but this shape is still accepted by `neuron.handle` for
+ * cases where a zod schema isn't on hand (or for the legacy worker path).
+ */
+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. */
+    inputSchema?: JsonSchema;
+    /** JSON Schema validated against the handler's return value. Mismatch
+     *  produces a `schema-mismatch` nack and the gateway publishes a failed
+     *  TaskResult. */
+    outputSchema?: JsonSchema;
+}
+/**
+ * Per-deployment options when registering a `CapabilityDef` with a neuron.
+ * Both fields override the corresponding defaults on the def. If neither
+ * the def nor these options provide `scope`/`concurrency`, registration
+ * throws at start time (intentional fail-fast).
+ */
+interface CapabilityHandleOptions {
+    scope?: Capability['scope'];
+    concurrency?: number;
+}
+/** Handler signature: receives the resolved input and a context, returns
+ *  the output. Throwing nacks the lease (retryable by default; ctx.fail
+ *  for terminal). */
+type Handler<TInput = unknown, TOutput = unknown> = (input: TInput, ctx: HandlerContext) => Promise<TOutput> | TOutput;
+/** Internal: the wire frames the SDK emits. */
+type ClientFrame = RegisterFrame | UpdateCapabilityFrame | HeartbeatFrame | AckFrame | NackFrame | ProgressFrame;
+
+/**
+ * `defineCapability` — single source of truth for a capability's contract.
+ *
+ * One object carries everything a neuron and a planner need to know about a
+ * capability: namespaced type, human-readable description, typed input and
+ * output schemas, and (optionally) deployment defaults like scope and
+ * concurrency. The SDK serializes only the fields each endpoint cares
+ * about — plan-time gets the contract, registration gets the deployment.
+ *
+ * Why one object: users don't have to juggle a "plan-time def" vs a
+ * "registration-time def". Defaults set on the def can still be overridden
+ * at `neuron.handle(...)` time per deployment (e.g., desktop vs server).
+ */
+
+interface CapabilityDefInit<TIn extends z.ZodTypeAny, TOut extends z.ZodTypeAny> {
+    /** Namespaced capability type, e.g. `core/script.python`. */
+    type: string;
+    /**
+     * Plain-language description shown to the planner LLM. Required at
+     * plan-time so the model can choose this capability appropriately.
+     */
+    description: string;
+    /** Zod schema for the capability's input payload. */
+    input: TIn;
+    /** Zod schema for the capability's output payload. */
+    output: TOut;
+    /**
+     * Optional deployment defaults. Both can be overridden at
+     * `neuron.handle(def, opts, fn)` time.
+     */
+    scope?: Capability['scope'];
+    concurrency?: number;
+}
+/**
+ * A typed capability definition. The phantom `_input` / `_output` fields
+ * carry the inferred TS types so `neuron.handle(def, fn)` can constrain
+ * `fn`'s argument and return type.
+ *
+ * Internal serializers (`toPlanShape`, `toRegistrationCapability`) keep the
+ * "send only what the endpoint needs" rule in one place — endpoints get
+ * the right subset and never accidentally see the wrong fields.
+ */
+interface CapabilityDef<TIn = unknown, TOut = unknown> {
+    readonly type: string;
+    readonly description: string;
+    /** Compiled JSON Schema — derived once at definition time. */
+    readonly inputSchema: JsonSchema;
+    readonly outputSchema: JsonSchema;
+    readonly scope?: Capability['scope'];
+    readonly concurrency?: number;
+    /** Original zod schemas — kept for runtime validation in handlers if needed. */
+    readonly _zod: {
+        input: z.ZodType<TIn>;
+        output: z.ZodType<TOut>;
+    };
+    /** Phantom type carriers — never read at runtime. */
+    readonly _input?: TIn;
+    readonly _output?: TOut;
+}
+/**
+ * Plan-request shape: `{ type, description, input, output }`. Scope and
+ * concurrency are intentionally dropped — they're per-deployment and
+ * don't belong in the planner's catalog.
+ */
+interface CapabilityPlanShape {
+    type: string;
+    description: string;
+    input: JsonSchema;
+    output: JsonSchema;
+}
+declare function defineCapability<TIn extends z.ZodTypeAny, TOut extends z.ZodTypeAny>(init: CapabilityDefInit<TIn, TOut>): CapabilityDef<z.infer<TIn>, z.infer<TOut>>;
+/** Render the def for inclusion in a `POST /plan` catalog. */
+declare function toPlanShape(def: CapabilityDef): CapabilityPlanShape;
+/**
+ * Render the registration `Capability` frame for the gateway. `opts`
+ * overrides any defaults set on the def. `scope` and `concurrency` are
+ * required at registration time — if neither the def nor `opts` provides
+ * them, this throws so the misconfiguration surfaces at start time
+ * rather than as a confusing wire-validation error.
+ */
+declare function toRegistrationCapability(def: CapabilityDef, opts?: CapabilityHandleOptions): Capability;
+
+/**
+ * Public event surface. The `Neuron` class extends `EventEmitter<NeuronEvents>`
+ * from `eventemitter3` so consumers can subscribe with the familiar
+ * `.on() / .once() / .off()` API:
+ *
+ *   neuron.on('frame', (frame) => log.append(frame));
+ *   neuron.once('connection:registered', ({ sessionId }) => mountUI(sessionId));
+ *   const off = neuron.on('error', captureError);
+ *   off();
+ *
+ * Two flavors:
+ *
+ *   - `frame` — a pass-through of the gateway's `/neuron/events` SSE stream.
+ *     Fires for every parsed `ServerToNeuronFrame`, including ones for
+ *     which no handler is registered. Useful for live event logs,
+ *     observability, and the neuron-tester debug UI.
+ *
+ *   - `connection:*` and `error` — synthetic, SDK-generated. Mirror the
+ *     transport's lifecycle (SSE handshake, register acceptance, close,
+ *     reconnect scheduling).
+ *
+ * Adding new events is intentionally cheap — extend `NeuronEvents` and emit
+ * from inside the class. Future entries (e.g. `'workflow:task-completed'`
+ * for sibling-neuron notifications) slot in without breaking subscribers.
+ */
+interface NeuronEvents {
+    /** Fired after the SSE handshake succeeds, before register is posted. */
+    'connection:open': () => void;
+    /** Fired after the gateway accepts the register frame. */
+    'connection:registered': (info: {
+        sessionId: string;
+        capabilities: number;
+    }) => void;
+    /** Fired when the SSE stream closes — clean shutdown or transient error. */
+    'connection:close': (reason: string) => void;
+    /** Fired when a reconnect is scheduled, before the backoff delay elapses. */
+    'connection:reconnecting': (info: {
+        attempt: number;
+        delayMs: number;
+        reason: string;
+    }) => void;
+    /** Fired on transport / parse errors. Reconnect handling is automatic. */
+    error: (err: Error) => void;
+    /** Pass-through of every parsed inbound SSE frame. */
+    frame: (frame: ServerToNeuronFrame) => void;
+}
+interface NeuronOptions {
+    /** Base URL of the gateway, e.g. `https://api.holokai.dev`. */
+    gatewayUrl: string;
+    /**
+     * Stable per-process identifier. Reused across reconnects so the
+     * gateway can correlate the new session with the same neuron. SDK does
+     * NOT generate one for you — pick something stable per device/process
+     * (UUID stored on disk for desktop, hostname+pid for server).
+     */
+    neuronId: string;
+    /** Token provider — see `AuthCallback` for refresh semantics. */
+    auth: AuthCallback;
+    /** Logger; defaults to a silent no-op. */
+    logger?: NeuronLogger;
+    /** Heartbeat interval (ms). Default 10s. */
+    heartbeatIntervalMs?: number;
+    /** Initial reconnect delay (ms). Default 500ms. */
+    initialReconnectDelayMs?: number;
+    /** Max reconnect delay (ms). Default 30s. */
+    maxReconnectDelayMs?: number;
+    /** Override `fetch`; mainly for tests. */
+    fetch?: typeof fetch;
+}
+/**
+ * Public SDK class. Compose:
+ *
+ *   const neuron = new Neuron({ gatewayUrl, neuronId, auth: () => token });
+ *   neuron.handle({ type: 'core/script.python', scope: 'any', concurrency: 4 }, handler);
+ *   neuron.on('connection:registered', ({ sessionId }) => log(sessionId));
+ *   await neuron.start();
+ *   ...
+ *   await neuron.stop({ drain: true, timeoutMs: 30_000 });
+ *
+ * See `NeuronEvents` for the full set of subscribable events.
+ */
+declare class Neuron extends EventEmitter<NeuronEvents> {
+    private readonly transport;
+    private readonly handlers;
+    private readonly inFlightLeases;
+    /**
+     * Leases admitted by `dispatchLease` but still waiting for a worker-pool
+     * slot. Tracked separately from `inFlightLeases` so the heartbeat snapshot
+     * doesn't lie — only running leases extend the gateway's lease TTL.
+     */
+    private readonly queuedLeases;
+    private readonly heartbeat;
+    private readonly validator;
+    private readonly logger;
+    private readonly opts;
+    private started;
+    private stopping;
+    private hasOpenedOnce;
+    constructor(opts: NeuronOptions);
+    /**
+     * Register a handler for a capability. Must be called before `start()`;
+     * the gateway expects the full capability list in the register frame.
+     *
+     * Three call shapes:
+     *
+     *   neuron.handle(capDef, fn)               // typed via defineCapability defaults
+     *   neuron.handle(capDef, opts, fn)         // typed; override scope/concurrency
+     *   neuron.handle(capabilityRegistration, fn) // legacy/low-level: explicit JSON Schemas
+     *
+     * If called twice for the same capability before start, the second call
+     * replaces the first. After start, use `updateCapability` to adjust
+     * concurrency at runtime.
+     */
+    handle<TIn, TOut>(def: CapabilityDef<TIn, TOut>, handler: Handler<TIn, TOut>): void;
+    handle<TIn, TOut>(def: CapabilityDef<TIn, TOut>, opts: CapabilityHandleOptions, handler: Handler<TIn, TOut>): void;
+    handle(reg: CapabilityRegistration, handler: Handler): void;
+    /**
+     * Adjust an already-registered capability's concurrency at runtime and
+     * notify the gateway via an `update-capability` frame so prefetch can be
+     * tuned. Schema and handler are not replaced — re-register before start
+     * if those need to change.
+     */
+    updateCapability(reg: Pick<CapabilityRegistration, 'type' | 'concurrency'>): Promise<void>;
+    /**
+     * Open the SSE stream, post register with all advertised capabilities,
+     * and start the heartbeat loop. Resolves once the gateway accepts the
+     * register frame.
+     */
+    start(): Promise<void>;
+    /**
+     * Refuse new leases, drain in-flight handlers up to `timeoutMs`, then
+     * tear down the connection. Pending leases (queued but not started)
+     * are abandoned — the gateway's lease TTL will reclaim them.
+     */
+    stop(opts?: {
+        drain?: boolean;
+        timeoutMs?: number;
+    }): Promise<void>;
+    private snapshotInFlight;
+    private handleConnectionOpen;
+    private handleConnectionClose;
+    private postRegister;
+    private handleFrame;
+    private dispatchLease;
+    private handleCancel;
+}
+/** SSE event names re-exported for tests / consumers that want to match
+ *  by name without importing the protocol package. */
+declare const SSE_EVENT_NAMES: {
+    readonly registered: "registered";
+    readonly lease: "lease";
+    readonly cancel: "cancel";
+    readonly capabilityRevoked: "capability-revoked";
+    readonly disconnect: "disconnect";
+};
+
+/**
+ * Internal callback surface — the `Neuron` that owns a `Transport` is the
+ * single subscriber. There's no broadcast or late-subscription use case
+ * here, so a callbacks-on-options shape is simpler than an emitter and
+ * keeps the transport free of any event-library dependency.
+ */
+interface TransportCallbacks {
+    /** Fired after the SSE handshake succeeds. */
+    onOpen?: () => void;
+    /** Fired when the SSE stream ends — clean close or error. */
+    onClose?: (reason: string) => void;
+    /** Fired on every parsed server frame. */
+    onFrame?: (frame: ServerToNeuronFrame) => void;
+    /** Fired on connection or parse error; transport will reconnect unless stopped. */
+    onError?: (err: Error) => void;
+    /** Fired when a reconnect is scheduled, before the backoff delay elapses. */
+    onReconnecting?: (info: {
+        attempt: number;
+        delayMs: number;
+        reason: string;
+    }) => void;
+}
+interface TransportOptions extends TransportCallbacks {
+    /** Base URL of the gateway (e.g. `https://api.holokai.dev`). */
+    gatewayUrl: string;
+    /** Stable per-process identifier sent as `?neuronId=` on the SSE GET. */
+    neuronId: string;
+    /** Token provider — called on every POST and SSE open; called again on 401 retry. */
+    auth: AuthCallback;
+    /** Logger; defaults to a silent no-op. */
+    logger?: NeuronLogger;
+    /**
+     * Initial reconnect delay in ms. Doubles on each consecutive failure
+     * up to `maxReconnectDelayMs`. Defaults: 500ms initial, 30s ceiling.
+     */
+    initialReconnectDelayMs?: number;
+    maxReconnectDelayMs?: number;
+    /** Override `fetch`. Defaults to global fetch (Node 20+ undici). */
+    fetch?: typeof fetch;
+}
+/**
+ * Wire-level transport. Holds a single SSE stream open against the
+ * gateway, parses inbound frames, exposes a typed `post(...)` for
+ * outbound frames, and reconnects on disconnect with exponential backoff.
+ *
+ * Lifecycle:
+ *   - `start()` opens the SSE stream and resolves once the connection is
+ *     established. Reconnect logic kicks in if the stream drops.
+ *   - `post(path, frame)` sends an outbound frame; refreshes the token via
+ *     the auth callback on 401 and retries once.
+ *   - `stop()` aborts the SSE stream and prevents further reconnects.
+ *
+ * Note: `Transport` does NOT call `register` itself — that's the Neuron
+ * class's job, since register requires the SSE stream to already exist
+ * (the gateway matches identity+neuronId between SSE pending stream and
+ * register POST).
+ */
+declare class Transport {
+    private readonly opts;
+    private readonly callbacks;
+    private abortController;
+    private stopped;
+    private connected;
+    private reconnectAttempts;
+    private reconnectTimer;
+    constructor(opts: TransportOptions);
+    isConnected(): boolean;
+    /** Open the SSE stream. Resolves after the connection is established. */
+    start(): Promise<void>;
+    /** Tear down the SSE stream and prevent further reconnect attempts. */
+    stop(): Promise<void>;
+    /**
+     * POST a client frame to the gateway. Refreshes the token via the auth
+     * callback and retries once on 401 — that's the contract: callers
+     * implement refresh inside their callback.
+     */
+    post<T extends ClientFrame>(path: PostPath, frame: T): Promise<unknown>;
+    private postRaw;
+    private openStream;
+    private consumeStream;
+    private handleStreamEnd;
+    private scheduleReconnect;
+}
+declare class TransportError extends Error {
+    readonly statusCode: number;
+    constructor(message: string, statusCode: number);
+}
+
+/**
+ * Per-capability concurrency limiter. Bounds the number of in-flight
+ * handler invocations locally even if the gateway overshoots prefetch — a
+ * misbehaving gateway should never push past the contract.
+ *
+ * Pools are created per (neuron, capability) and live for the duration of
+ * the SDK's session. Drain support (used by `neuron.stop({ drain: true })`)
+ * resolves once all in-flight tasks have completed; new submissions during
+ * drain are rejected with `ShutdownError`.
+ */
+declare class WorkerPool {
+    private maxConcurrency;
+    private inFlight;
+    private queue;
+    private draining;
+    private drained;
+    constructor(maxConcurrency: number);
+    /** Currently-running task count. */
+    size(): number;
+    /** Tasks waiting for a slot. */
+    pending(): number;
+    /**
+     * Run `fn` once a concurrency slot is available. Resolves with the
+     * function's return value (or rejects with its error). Throws
+     * ShutdownError if the pool is already draining.
+     */
+    run<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Update the max concurrency. Lowering doesn't kill in-flight tasks —
+     * they finish naturally — but it does prevent new ones from starting
+     * until the in-flight count drops below the new limit.
+     */
+    setConcurrency(newMax: number): void;
+    /**
+     * Stop accepting new submissions. Returns a promise that resolves once
+     * every in-flight AND queued task has finished — queued waiters from
+     * before drain are released as in-flight slots free, run normally, and
+     * are awaited as part of drain. Only fresh `run()` calls received after
+     * `drain()` reject with ShutdownError. Callers that need a hard stop
+     * should race this promise against a timeout and abort handlers.
+     */
+    drain(): Promise<void>;
+}
+declare class ShutdownError extends Error {
+    constructor(message: string);
+}
+
+/**
+ * Compiles JSON Schemas once and caches by reference. Mirror of the
+ * gateway-side OutputValidator — both ends of the wire validate against
+ * the same schemas so a misbehaving party can't sneak by either side.
+ */
+declare class SchemaValidator {
+    private readonly ajv;
+    private readonly cache;
+    constructor();
+    /**
+     * Returns null if the value matches the schema (or no schema given);
+     * otherwise an array of structured errors.
+     */
+    validate(schema: JsonSchema | undefined, data: unknown): ErrorObject[] | null;
+}
+
+export { type AuthCallback, type Capability, type CapabilityDef, type CapabilityDefInit, type CapabilityHandleOptions, type CapabilityPlanShape, type CapabilityRegistration, type Handler, type HandlerContext, type HeartbeatInFlightEntry, type LeasePayload, Neuron, type NeuronEvents, type NeuronLogger, type NeuronOptions, SSE_EVENT_NAMES, SchemaValidator, type ServerToNeuronFrame, ShutdownError, type TaskPayload, Transport, type TransportCallbacks, TransportError, type TransportOptions, WorkerPool, defineCapability, toPlanShape, toRegistrationCapability };