@holokai/neuron-sdk 0.1.0 → 0.2.0

package/dist/transport-QqkooS7K.d.ts

@@ -0,0 +1,742 @@
+import { z } from 'zod';
+
+/** 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;
+    /**
+     * Per-capability lease TTL override in milliseconds (HOL-356).
+     * The gateway uses this when minting a lease's `expiresAt`; absent
+     * → falls back to the gateway's default (`leaseTtlMs` on the
+     * dispatcher). Lets a slow capability (e.g. a scripted run with a
+     * 10-minute deadline) declare a longer TTL without tuning the
+     * whole gateway.
+     *
+     * Bounded by reasonable extremes: at least 1s (anything shorter
+     * than a heartbeat is meaningless) and at most 1h (the reaper +
+     * heartbeat budget should be the limiter, not a single
+     * capability).
+     */
+    leaseTtlMs: z.ZodOptional<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    type: string;
+    scope: "any" | {
+        onBehalfOf: string;
+    };
+    concurrency: number;
+    leaseTtlMs?: number | undefined;
+}, {
+    type: string;
+    scope: "any" | {
+        onBehalfOf: string;
+    };
+    concurrency: number;
+    leaseTtlMs?: number | undefined;
+}>;
+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;
+        leaseTtlMs: z.ZodOptional<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        type: string;
+        scope: "any" | {
+            onBehalfOf: string;
+        };
+        concurrency: number;
+        leaseTtlMs?: number | undefined;
+    }, {
+        type: string;
+        scope: "any" | {
+            onBehalfOf: string;
+        };
+        concurrency: number;
+        leaseTtlMs?: number | undefined;
+    }>, "many">, {
+        type: string;
+        scope: "any" | {
+            onBehalfOf: string;
+        };
+        concurrency: number;
+        leaseTtlMs?: number | undefined;
+    }[], {
+        type: string;
+        scope: "any" | {
+            onBehalfOf: string;
+        };
+        concurrency: number;
+        leaseTtlMs?: number | undefined;
+    }[]>;
+}, "strict", z.ZodTypeAny, {
+    type: "register";
+    neuronId: string;
+    protocolVersion: string;
+    capabilities: {
+        type: string;
+        scope: "any" | {
+            onBehalfOf: string;
+        };
+        concurrency: number;
+        leaseTtlMs?: number | undefined;
+    }[];
+}, {
+    type: "register";
+    neuronId: string;
+    protocolVersion: string;
+    capabilities: {
+        type: string;
+        scope: "any" | {
+            onBehalfOf: string;
+        };
+        concurrency: number;
+        leaseTtlMs?: number | undefined;
+    }[];
+}>;
+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;
+        leaseTtlMs: z.ZodOptional<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        type: string;
+        scope: "any" | {
+            onBehalfOf: string;
+        };
+        concurrency: number;
+        leaseTtlMs?: number | undefined;
+    }, {
+        type: string;
+        scope: "any" | {
+            onBehalfOf: string;
+        };
+        concurrency: number;
+        leaseTtlMs?: number | undefined;
+    }>;
+}, "strict", z.ZodTypeAny, {
+    type: "update-capability";
+    capability: {
+        type: string;
+        scope: "any" | {
+            onBehalfOf: string;
+        };
+        concurrency: number;
+        leaseTtlMs?: number | undefined;
+    };
+    neuronId: string;
+}, {
+    type: "update-capability";
+    capability: {
+        type: string;
+        scope: "any" | {
+            onBehalfOf: string;
+        };
+        concurrency: number;
+        leaseTtlMs?: number | undefined;
+    };
+    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;
+        leaseTtlMs: z.ZodOptional<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        type: string;
+        scope: "any" | {
+            onBehalfOf: string;
+        };
+        concurrency: number;
+        leaseTtlMs?: number | undefined;
+    }, {
+        type: string;
+        scope: "any" | {
+            onBehalfOf: string;
+        };
+        concurrency: number;
+        leaseTtlMs?: number | undefined;
+    }>, "many">;
+    acceptedAt: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    type: "registered";
+    capabilities: {
+        type: string;
+        scope: "any" | {
+            onBehalfOf: string;
+        };
+        concurrency: number;
+        leaseTtlMs?: number | undefined;
+    }[];
+    sessionId: string;
+    acceptedAt: string;
+}, {
+    type: "registered";
+    capabilities: {
+        type: string;
+        scope: "any" | {
+            onBehalfOf: string;
+        };
+        concurrency: number;
+        leaseTtlMs?: number | undefined;
+    }[];
+    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;
+    /**
+     * Per-capability lease TTL override (HOL-356). Wins over the same
+     * field on the def. See `CapabilityDefInit.leaseTtlMs` for shape;
+     * bounded `[1_000, 3_600_000]` (1s..1h) by `CapabilitySchema`.
+     */
+    leaseTtlMs?: 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;
+
+/**
+ * The wire-level abstraction the rest of the SDK builds on. A `Transport`
+ * is whatever can carry typed frames in both directions:
+ *
+ *   - outbound: typed POSTs of `ClientFrame`s (register, heartbeat, ack,
+ *     nack, progress, update-capability),
+ *   - inbound: a stream of `ServerToNeuronFrame`s delivered via the
+ *     callback shape on the constructor / factory of the implementation.
+ *
+ * The default implementation is `HttpTransport` (SSE + HTTPS POST). An
+ * `IpcTransport` exists for renderer-process neurons running inside an
+ * Electron app that hosts BigBrain in main.
+ *
+ * Implementations are responsible for:
+ *
+ *   - establishing the inbound channel during `start()` and tearing it
+ *     down during `stop()`,
+ *   - delivering parsed inbound frames via the callbacks supplied at
+ *     construction (see `TransportCallbacks`),
+ *   - reporting connection state via `isConnected()`,
+ *   - any reconnect / retry strategy that makes sense for the underlying
+ *     wire (HTTP reconnects with backoff; IPC has no transient socket).
+ *
+ * The SDK never reaches past these four methods — `Neuron`,
+ * `HeartbeatLoop`, `runLease`, etc. all treat `Transport` as a black box.
+ * Adding a new transport means implementing this interface, nothing else.
+ */
+interface Transport {
+    /**
+     * Bind the lifecycle callbacks. Single-subscriber model — calling this
+     * a second time replaces any prior subscription. Must be called before
+     * `start()`; the owning `Neuron` does this in its constructor so the
+     * transport can deliver inbound frames as soon as the channel opens.
+     */
+    subscribe(callbacks: TransportCallbacks): void;
+    /** Open the inbound channel. Resolves once the connection is established. */
+    start(): Promise<void>;
+    /** Close the inbound channel and prevent any further reconnect attempts. */
+    stop(): Promise<void>;
+    /** Send a typed client frame outbound. Resolves with the parsed body. */
+    post<T extends ClientFrame>(path: PostPath, frame: T): Promise<unknown>;
+    /** Whether the inbound channel is currently live. */
+    isConnected(): boolean;
+}
+/**
+ * Lifecycle callbacks fired by a `Transport` implementation. Single
+ * subscriber (the owning `Neuron`); a callbacks-on-options shape is
+ * simpler than an emitter and keeps transport implementations free of
+ * any event-library dependency.
+ */
+interface TransportCallbacks {
+    /** Fired once the inbound channel is established. */
+    onOpen?: () => void;
+    /** Fired when the inbound channel ends — clean close or error. */
+    onClose?: (reason: string) => void;
+    /** Fired on every parsed server frame. */
+    onFrame?: (frame: ServerToNeuronFrame) => void;
+    /** Fired on transport-level errors (connect, parse, IPC dispatch). */
+    onError?: (err: Error) => void;
+    /**
+     * Fired when an implementation has decided to reconnect, before the
+     * delay elapses. HTTP transport schedules these on disconnect with
+     * exponential backoff; IPC transport never fires this (no transient
+     * socket).
+     */
+    onReconnecting?: (info: {
+        attempt: number;
+        delayMs: number;
+        reason: string;
+    }) => void;
+}
+
+export type { AuthCallback as A, Capability as C, Handler as H, JsonSchema as J, LeasePayload as L, NeuronLogger as N, PostPath as P, ServerToNeuronFrame as S, Transport as T, CapabilityHandleOptions as a, CapabilityRegistration as b, TransportCallbacks as c, ClientFrame as d, HandlerContext as e, HeartbeatInFlightEntry as f, TaskPayload as g };