@holokai/neuron-sdk 0.1.0 → 0.2.0

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
 
@@ -626,3 +778,83 @@ Heartbeats aren't reaching the gateway, so the reaper hasn't reclaimed them. Che
 ### Auth 401 on every request
 
 The `auth` callback isn't returning a valid token. If using a refresh flow, ensure the callback fetches a fresh token on each call (the SDK caches nothing — it's your callback's job).
+
+---
+
+## Releasing (maintainers)
+
+`@holokai/neuron-sdk` is published to public npm. Releases are cut from a
+monorepo-scoped git tag, and CI does the publish — there is no npm token on
+anyone's laptop and none stored in the repo.
+
+### Cut a release
+
+1. **Bump the version** in `packages/neuron-sdk/package.json`
+   (`version`). Follow semver:
+   - Pilot phase, we are in **`0.x`**. Because the protocol is still absorbing
+     pilot-developer feedback, a **breaking** change bumps the **minor**
+     (`0.2.0` → `0.3.0`); a backward-compatible change or fix bumps the
+     **patch** (`0.2.0` → `0.2.1`). This is the standard `0.x` convention and
+     is what buys us room to break things on feedback without a major bump.
+   - Hold **`1.0.0`** until the public API has survived pilot feedback and we're
+     ready to commit to "breaking changes bump the major." Jumping to `1.0.0`
+     is a stability promise, not a milestone — don't spend it early.
+2. **Commit** the bump (reference the Linear ticket) and merge to `main`.
+3. **Tag and push** from `main`:
+   ```sh
+   git tag neuron-sdk-v0.2.0        # must equal the package.json version
+   git push origin neuron-sdk-v0.2.0
+   ```
+   The tag is prefixed `neuron-sdk-v` (the Python SDK uses
+   `neuron-sdk-python-v`) so the two never collide.
+4. **`publish-neuron-sdk.yml`** fires on the tag: it asserts the tag version
+   matches `package.json`, runs the `prepublish` gate (`build` + `test`), and
+   publishes to npm. The `npm` GitHub Environment gates the publish behind a
+   **required-reviewer approval** — approve the run under Actions, and on success
+   the new version is live at
+   [`@holokai/neuron-sdk`](https://www.npmjs.com/package/@holokai/neuron-sdk).
+
+   > No `--provenance`: bigbrain is a private repo, so npm's provenance
+   > attestation (a public transparency-log link back to the source) adds little
+   > and has historically errored from private repos. Trusted-publishing auth is
+   > unaffected. Add the flag back if bigbrain ever goes public.
+
+The tag→`package.json` assertion means a mismatched tag fails **before** the
+registry is touched — npm refuses to re-upload an existing version, so there's
+no half-published state to clean up.
+
+### Publish auth: npm Trusted Publishing (one-time setup)
+
+CI authenticates to npm via **OIDC trusted publishing** — GitHub Actions
+exchanges a short-lived OIDC token for publish rights, so no long-lived
+`NPM_TOKEN` exists to leak. This mirrors the Python SDK's PyPI trusted
+publishing. It requires two one-time setups:
+
+1. **On npmjs.com** (a package admin, once): open the
+   [`@holokai/neuron-sdk`](https://www.npmjs.com/package/@holokai/neuron-sdk)
+   package → **Settings → Trusted Publisher → GitHub Actions**, and register:
+   - Organization / repository: `holok-ai/bigbrain`
+   - Workflow filename: `publish-neuron-sdk.yml`
+   - Environment: `npm`
+2. **In this repo** (once): create the **`npm`** GitHub Environment
+   (Settings → Environments). Add reviewers/branch protection here if you want a
+   manual approval gate before each publish.
+
+Until the trusted publisher is registered, the `npm publish` step fails with an
+auth error — that's the expected "not set up yet" signal, not a code bug.
+
+### Manual publish (fallback / first bootstrap)
+
+The tag flow is the norm. If you ever need to publish by hand (e.g. to bootstrap
+the very first version before trusted publishing is configured):
+
+```sh
+cd packages/neuron-sdk
+pnpm run publish:npm:dry   # inspect the tarball + files list
+pnpm run publish:npm       # runs the prepublishOnly build+test gate, then publishes
+```
+
+This uses your own `npm login` credentials and skips the CI approval gate —
+prefer the tag flow for anything a developer will consume.
+
+<!-- ci: force full build on the self-hosted runner (HOL-2028 verify); safe to remove -->