@holokai/neuron-sdk 0.1.0 → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Holokai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -2,7 +2,12 @@
 
 SDK for building neurons — processes that connect to the BigBrain gateway and execute tasks on behalf of workflows.
 
-A neuron advertises one or more **capabilities** (typed task handlers), opens a persistent connection to the gateway, and receives work via SSE. The gateway routes tasks to the right neuron based on capability type and scope. The built-in `apps/worker` uses this SDK; so will any external neuron (desktop app, on-prem agent, custom integration).
+A neuron advertises one or more **capabilities** (typed task handlers), opens a persistent connection to the gateway, and receives work via a pluggable `Transport`. Two transports ship in the SDK:
+
+- **`HttpTransport`** — SSE for inbound, HTTPS POST for outbound. The default for any neuron talking to a remote BigBrain gateway. Re-exported from the package root.
+- **`IpcTransport`** — Electron renderer ↔ main IPC. For neurons running inside an app that embeds BigBrain in main; no network hop, no JWT in the renderer. Imported from the `/ipc` subpath.
+
+The gateway routes tasks to the right neuron based on capability type and scope. The built-in `apps/worker` uses this SDK over HTTP; the in-process Holokai Desktop renderer uses it over IPC; both share the same `Neuron` class and handler API.
 
 ---
 
@@ -115,19 +120,35 @@ neuronId: await readOrCreateStoredId('/var/lib/myapp/neuron-id')
 
 ### `new Neuron(opts: NeuronOptions)`
 
+`NeuronOptions` is a discriminated union — pick the convenience shape (HTTP) or pass a transport explicitly.
+
 ```ts
-interface NeuronOptions {
-  gatewayUrl: string;           // Base URL, e.g. 'https://api.example.com'
+type NeuronOptions = NeuronOptionsWithHttp | NeuronOptionsWithTransport;
+
+interface NeuronCommonOptions {
   neuronId: string;             // Stable per process/device
-  auth: AuthCallback;           // Token provider (see below)
   logger?: NeuronLogger;        // Plug in pino, console, etc. Default: silent
   heartbeatIntervalMs?: number; // Default 10_000 (10s)
+}
+
+// Convenience: SDK builds an HttpTransport for you. Most common path.
+interface NeuronOptionsWithHttp extends NeuronCommonOptions {
+  gatewayUrl: string;           // Base URL, e.g. 'https://api.example.com'
+  auth: AuthCallback;           // Token provider (see below)
   initialReconnectDelayMs?: number; // Default 500ms
   maxReconnectDelayMs?: number;     // Default 30_000 (30s)
   fetch?: typeof fetch;         // Override for tests
 }
+
+// Power-user: bring your own Transport. Used for IpcTransport, custom
+// transports, or HttpTransport instances built explicitly.
+interface NeuronOptionsWithTransport extends NeuronCommonOptions {
+  transport: Transport;
+}
 ```
 
+See the [Transports](#transports) section for `HttpTransport`, `IpcTransport`, and the `Transport` interface.
+
 ---
 
 ### `neuron.handle(reg, handler)`
@@ -358,6 +379,128 @@ The event surface is designed to grow — future entries (e.g. `'workflow:task-c
 
 ---
 
+## Transports
+
+A `Transport` is the wire-level abstraction the rest of the SDK builds on. It carries typed frames in both directions: inbound `ServerToNeuronFrame`s via callbacks, outbound `ClientFrame`s via `post(...)`. The `Neuron` class only ever talks to a `Transport` — adding a new transport (e.g. WebSocket, native messaging) means implementing one interface.
+
+```ts
+interface Transport {
+  subscribe(callbacks: TransportCallbacks): void;
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  post<T extends ClientFrame>(path: PostPath, frame: T): Promise<unknown>;
+  isConnected(): boolean;
+}
+
+interface TransportCallbacks {
+  onOpen?: () => void;
+  onClose?: (reason: string) => void;
+  onFrame?: (frame: ServerToNeuronFrame) => void;
+  onError?: (err: Error) => void;
+  onReconnecting?: (info: { attempt: number; delayMs: number; reason: string }) => void;
+}
+```
+
+Both `Transport` and `TransportCallbacks` are exported from the package root.
+
+---
+
+### `HttpTransport`
+
+Default transport. SSE for inbound, HTTPS POST for outbound. Reconnects with exponential backoff (default: 500ms → 30s ceiling). Refreshes the auth token via your `AuthCallback` and retries once on 401.
+
+```ts
+import { Neuron, HttpTransport } from '@holokai/neuron-sdk';
+
+const transport = new HttpTransport({
+  gatewayUrl: 'https://api.example.com',
+  neuronId: 'my-worker-001',
+  auth: () => process.env.GATEWAY_TOKEN!,
+  // optional:
+  initialReconnectDelayMs: 500,
+  maxReconnectDelayMs: 30_000,
+});
+
+const neuron = new Neuron({ neuronId: 'my-worker-001', transport });
+```
+
+In practice you rarely construct `HttpTransport` directly — passing `gatewayUrl` + `auth` to `Neuron` builds it for you. Construct explicitly when you want to share a fetch implementation, swap the auth strategy, or instrument the transport in tests.
+
+```ts
+interface HttpTransportOptions {
+  gatewayUrl: string;
+  neuronId: string;
+  auth: AuthCallback;
+  logger?: NeuronLogger;
+  initialReconnectDelayMs?: number; // default 500ms
+  maxReconnectDelayMs?: number;     // default 30_000ms
+  fetch?: typeof fetch;
+}
+```
+
+---
+
+### `IpcTransport`
+
+For renderer-process neurons running inside an Electron app that hosts BigBrain in the main process. Leases arrive over Electron IPC, not over the network. Imported from the `/ipc` subpath so non-Electron consumers don't pay for it:
+
+```ts
+import { Neuron } from '@holokai/neuron-sdk';
+import { IpcTransport } from '@holokai/neuron-sdk/ipc';
+
+// `bridge` comes from the renderer's preload — see below.
+const transport = new IpcTransport({ bridge: window.bigbrainNeuron, neuronId });
+const neuron = new Neuron({ neuronId, transport });
+
+neuron.handle({ type: 'desktop/local-tool', scope: { onBehalfOf: userId }, concurrency: 1 }, handler);
+await neuron.start();
+```
+
+Differences from `HttpTransport`:
+
+- **No reconnect logic** — IPC has no transient socket. If the bridge throws, the failure surfaces via `onError` and the consumer decides what to do.
+- **No auth callback** — the renderer never sees the JWT. The Electron main process attaches `Authorization` headers when it forwards POSTs to the embedded Fastify gateway.
+- **No keep-alive** — IPC channels are process-local; nothing to time out.
+
+The SDK does **not** depend on Electron. The renderer's preload script is responsible for constructing a concrete bridge that satisfies the `NeuronIpcBridge` shape and exposing it via `contextBridge`:
+
+```ts
+interface NeuronIpcBridge {
+  attach(neuronId: string): Promise<{ channel: string }>;
+  detach(neuronId: string): Promise<void>;
+  subscribe(channel: string, cb: (frame: ServerToNeuronFrame) => void): () => void;
+  invoke<T extends ClientFrame>(path: PostPath, frame: T): Promise<unknown>;
+}
+```
+
+Typical preload wiring (Electron-side, app code — not part of the SDK):
+
+```ts
+// preload.ts
+import { contextBridge, ipcRenderer } from 'electron';
+
+contextBridge.exposeInMainWorld('bigbrainNeuron', {
+  attach: (neuronId) => ipcRenderer.invoke('bigbrain:attach', neuronId),
+  detach: (neuronId) => ipcRenderer.invoke('bigbrain:detach', neuronId),
+  subscribe: (channel, cb) => {
+    const listener = (_e, frame) => cb(frame);
+    ipcRenderer.on(channel, listener);
+    return () => ipcRenderer.off(channel, listener);
+  },
+  invoke: (path, frame) => ipcRenderer.invoke('bigbrain:post', path, frame),
+});
+```
+
+```ts
+interface IpcTransportOptions {
+  bridge: NeuronIpcBridge;
+  neuronId: string;
+  logger?: NeuronLogger;
+}
+```
+
+---
+
 ## Examples
 
 ### Simple any-scoped capability
@@ -493,15 +636,17 @@ powerMonitor.on('on-battery', async () => {
 
 ## Configuration reference
 
-| Option | Default | Notes |
-|---|---|---|
-| `gatewayUrl` | — | Base URL, no trailing slash |
-| `neuronId` | — | Stable per device/process; reused on reconnect |
-| `auth` | — | Called on every POST + SSE open |
-| `logger` | silent no-op | Plug in pino or console |
-| `heartbeatIntervalMs` | `10_000` | Sent every 10s; renews lease expiries |
-| `initialReconnectDelayMs` | `500` | First reconnect delay |
-| `maxReconnectDelayMs` | `30_000` | Reconnect delay ceiling (exponential backoff) |
+| Option | Default | Applies to | Notes |
+|---|---|---|---|
+| `neuronId` | — | both | Stable per device/process; reused on reconnect |
+| `logger` | silent no-op | both | Plug in pino or console |
+| `heartbeatIntervalMs` | `10_000` | both | Sent every 10s; renews lease expiries |
+| `transport` | — | with-transport shape | Pre-built `Transport` (e.g. `IpcTransport` or a custom `HttpTransport`) |
+| `gatewayUrl` | — | with-http shape | Base URL, no trailing slash |
+| `auth` | — | with-http shape | Called on every POST + SSE open |
+| `initialReconnectDelayMs` | `500` | with-http shape | First reconnect delay (HTTP only — IPC doesn't reconnect) |
+| `maxReconnectDelayMs` | `30_000` | with-http shape | Reconnect delay ceiling (exponential backoff) |
+| `fetch` | global `fetch` | with-http shape | Override for tests |
 
 ---
 
@@ -511,10 +656,17 @@ This section covers enough to debug; the wire-level frame schemas are bundled in
 
 ### Transport
 
+The SDK abstracts the wire as a `Transport` (see [Transports](#transports) above). The frame types below are the same regardless of transport — only the carrier differs.
+
+**`HttpTransport` (default):**
 - **Server → Neuron**: SSE stream at `GET /neuron/events?neuronId={id}`
 - **Neuron → Server**: HTTPS POST endpoints (one per frame type)
+- No WebSockets — SSE + HTTPS POST traverses enterprise proxies cleanly.
 
-No WebSockets — SSE + HTTPS POST traverses enterprise proxies cleanly.
+**`IpcTransport` (Electron renderer):**
+- **Server → Neuron**: per-neuron Electron IPC channel obtained from `bridge.attach()`.
+- **Neuron → Server**: `bridge.invoke(path, frame)`, which the main process forwards to the embedded Fastify gateway via `app.inject(...)` — same auth and validation chain as HTTP.
+- No reconnect, no auth callback, no keep-alive.
 
 ### Frame types