@holokai/neuron-sdk 0.1.0 → 0.1.1

package/dist/index.d.mts

@@ -1,635 +1,9 @@
-import { z } from 'zod';
+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-QqkooS7K.mjs';
+export { e as HandlerContext, f as HeartbeatInFlightEntry, L as LeasePayload, g as TaskPayload } from './transport-QqkooS7K.mjs';
 import { EventEmitter } from 'eventemitter3';
+import { z } from 'zod';
 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.
  *
@@ -657,11 +31,23 @@ interface CapabilityDefInit<TIn extends z.ZodTypeAny, TOut extends z.ZodTypeAny>
     /** Zod schema for the capability's output payload. */
     output: TOut;
     /**
-     * Optional deployment defaults. Both can be overridden at
+     * Optional deployment defaults. All can be overridden at
      * `neuron.handle(def, opts, fn)` time.
      */
     scope?: Capability['scope'];
     concurrency?: number;
+    /**
+     * Per-capability lease TTL override in milliseconds (HOL-356).
+     * Flows through the register frame to the gateway, which uses it
+     * when minting a lease's `expiresAt` for this capability instead of
+     * its own default. Useful when one capability runs much longer than
+     * the rest of a neuron's repertoire (e.g. a sandboxed Python script
+     * with a 10-minute deadline) — set this rather than tuning the
+     * gateway-wide default for everyone.
+     *
+     * Bounded `[1_000, 3_600_000]` (1s..1h) by `CapabilitySchema`.
+     */
+    leaseTtlMs?: number;
 }
 /**
  * A typed capability definition. The phantom `_input` / `_output` fields
@@ -680,6 +66,8 @@ interface CapabilityDef<TIn = unknown, TOut = unknown> {
     readonly outputSchema: JsonSchema;
     readonly scope?: Capability['scope'];
     readonly concurrency?: number;
+    /** See {@link CapabilityDefInit.leaseTtlMs}. */
+    readonly leaseTtlMs?: number;
     /** Original zod schemas — kept for runtime validation in handlers if needed. */
     readonly _zod: {
         input: z.ZodType<TIn>;
@@ -758,9 +146,10 @@ interface NeuronEvents {
     /** 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;
+/**
+ * Options shared by both `NeuronOptions` shapes.
+ */
+interface NeuronCommonOptions {
     /**
      * Stable per-process identifier. Reused across reconnects so the
      * gateway can correlate the new session with the same neuron. SDK does
@@ -768,12 +157,29 @@ interface NeuronOptions {
      * (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;
+}
+/**
+ * Power-user shape — bring your own `Transport`. Used when the default
+ * HTTP+SSE transport doesn't fit, e.g. a renderer-process neuron in
+ * Electron embedding BigBrain in main, where leases arrive over IPC.
+ */
+interface NeuronOptionsWithTransport extends NeuronCommonOptions {
+    transport: Transport;
+}
+/**
+ * Convenience shape — provide gateway URL + auth, the SDK builds an
+ * `HttpTransport` for you. The most common path; matches the v1 SDK
+ * surface so existing call sites keep compiling unchanged.
+ */
+interface NeuronOptionsWithHttp extends NeuronCommonOptions {
+    /** Base URL of the gateway, e.g. `https://api.holokai.dev`. */
+    gatewayUrl: string;
+    /** Token provider — see `AuthCallback` for refresh semantics. */
+    auth: AuthCallback;
     /** Initial reconnect delay (ms). Default 500ms. */
     initialReconnectDelayMs?: number;
     /** Max reconnect delay (ms). Default 30s. */
@@ -781,6 +187,7 @@ interface NeuronOptions {
     /** Override `fetch`; mainly for tests. */
     fetch?: typeof fetch;
 }
+type NeuronOptions = NeuronOptionsWithTransport | NeuronOptionsWithHttp;
 /**
  * Public SDK class. Compose:
  *
@@ -806,7 +213,7 @@ declare class Neuron extends EventEmitter<NeuronEvents> {
     private readonly heartbeat;
     private readonly validator;
     private readonly logger;
-    private readonly opts;
+    private readonly neuronId;
     private started;
     private stopping;
     private hasOpenedOnce;
@@ -868,29 +275,7 @@ declare const SSE_EVENT_NAMES: {
     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 {
+interface HttpTransportOptions {
     /** Base URL of the gateway (e.g. `https://api.holokai.dev`). */
     gatewayUrl: string;
     /** Stable per-process identifier sent as `?neuronId=` on the SSE GET. */
@@ -909,7 +294,7 @@ interface TransportOptions extends TransportCallbacks {
     fetch?: typeof fetch;
 }
 /**
- * Wire-level transport. Holds a single SSE stream open against the
+ * HTTP+SSE 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.
  *
@@ -920,20 +305,21 @@ interface TransportOptions extends TransportCallbacks {
  *     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).
+ * Note: `HttpTransport` 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 {
+declare class HttpTransport implements Transport {
     private readonly opts;
-    private readonly callbacks;
+    private callbacks;
     private abortController;
     private stopped;
     private connected;
     private reconnectAttempts;
     private reconnectTimer;
-    constructor(opts: TransportOptions);
+    constructor(opts: HttpTransportOptions);
+    subscribe(callbacks: TransportCallbacks): void;
     isConnected(): boolean;
     /** Open the SSE stream. Resolves after the connection is established. */
     start(): Promise<void>;
@@ -1019,4 +405,4 @@ declare class SchemaValidator {
     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 };
+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 };