@holokai/neuron-sdk 0.1.0 → 0.1.1

package/dist/ipc.d.ts

@@ -0,0 +1,88 @@
+import { T as Transport, S as ServerToNeuronFrame, d as ClientFrame, P as PostPath, N as NeuronLogger, c as TransportCallbacks } from './transport-QqkooS7K.js';
+import 'zod';
+
+/**
+ * Renderer-side bridge to the BigBrain gateway running in the Electron
+ * main process. The SDK does NOT depend on Electron — the renderer's
+ * preload script is responsible for constructing a concrete bridge that
+ * forwards calls over `ipcRenderer.invoke` and `ipcRenderer.on`, then
+ * exposes it via `contextBridge.exposeInMainWorld`.
+ *
+ * The four-method shape mirrors what the gateway needs:
+ *
+ *   - `attach(neuronId)` — open the inbound channel for this neuron.
+ *     Resolves with the per-neuron event channel name the bridge will
+ *     deliver server frames on. Concretely, in Electron main this is
+ *     where the gateway constructs an `IpcSSEWriter` and stores it
+ *     against the session.
+ *   - `subscribe(channel, cb)` — start receiving frames on the channel
+ *     `attach` handed back. Returns an unsubscribe function.
+ *   - `detach(neuronId)` — close the inbound channel; the gateway tears
+ *     down its writer for this neuron.
+ *   - `invoke(path, frame)` — fire a typed POST. In Electron main this
+ *     is `app.inject({ method: 'POST', url: path, payload: frame, headers })`
+ *     so the same Fastify auth/validation chain runs as for HTTP neurons.
+ *
+ * The bridge is responsible for stamping authentication onto outbound
+ * calls — the IPC transport never sees the JWT.
+ */
+interface NeuronIpcBridge {
+    /**
+     * Open the inbound channel for `neuronId`. Returns the per-neuron event
+     * channel that `subscribe` should listen on.
+     */
+    attach(neuronId: string): Promise<{
+        channel: string;
+    }>;
+    /** Close the inbound channel. */
+    detach(neuronId: string): Promise<void>;
+    /** Subscribe to inbound frames on `channel`. Returns an unsubscribe fn. */
+    subscribe(channel: string, cb: (frame: ServerToNeuronFrame) => void): () => void;
+    /** Send a typed client frame outbound. Resolves with the parsed body. */
+    invoke<T extends ClientFrame>(path: PostPath, frame: T): Promise<unknown>;
+}
+interface IpcTransportOptions {
+    /**
+     * Concrete bridge — provided by the renderer's preload script. The SDK
+     * has no opinion on its construction; it only calls the four methods.
+     */
+    bridge: NeuronIpcBridge;
+    /**
+     * Stable per-process identifier. Reused across `start`/`stop` cycles
+     * so the gateway can correlate the new attach with the same neuron.
+     */
+    neuronId: string;
+    /** Logger; defaults to a silent no-op. */
+    logger?: NeuronLogger;
+}
+/**
+ * IPC transport for renderer-process neurons. Differences vs `HttpTransport`:
+ *
+ *   - No reconnect logic — IPC has no transient socket. If the bridge
+ *     throws on `invoke` or `attach`, the failure surfaces via `onError`
+ *     and the consumer (typically a `Neuron`) decides what to do.
+ *   - No auth callback — the renderer never sees the JWT. Main attaches
+ *     `Authorization` headers when it forwards to Fastify via `inject()`.
+ *   - No keep-alive — IPC channels are process-local; nothing in between
+ *     to time out idle connections.
+ *
+ * Same `Transport` contract as `HttpTransport`, so the rest of the SDK
+ * (`Neuron`, `HeartbeatLoop`, `runLease`) works against either without
+ * any conditional branching.
+ */
+declare class IpcTransport implements Transport {
+    private readonly bridge;
+    private readonly neuronId;
+    private readonly logger;
+    private callbacks;
+    private connected;
+    private unsubscribe;
+    constructor(opts: IpcTransportOptions);
+    subscribe(callbacks: TransportCallbacks): void;
+    isConnected(): boolean;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    post<T extends ClientFrame>(path: PostPath, frame: T): Promise<unknown>;
+}
+
+export { IpcTransport, type IpcTransportOptions, type NeuronIpcBridge };

package/dist/ipc.js

@@ -0,0 +1,86 @@
+'use strict';
+
+// src/logger.ts
+var noopLogger = {
+  debug() {
+  },
+  info() {
+  },
+  warn() {
+  },
+  error() {
+  }
+};
+
+// src/ipc-transport.ts
+var IpcTransport = class {
+  bridge;
+  neuronId;
+  logger;
+  callbacks = {};
+  connected = false;
+  unsubscribe = null;
+  constructor(opts) {
+    this.bridge = opts.bridge;
+    this.neuronId = opts.neuronId;
+    this.logger = opts.logger ?? noopLogger;
+  }
+  subscribe(callbacks) {
+    this.callbacks = callbacks;
+  }
+  isConnected() {
+    return this.connected;
+  }
+  async start() {
+    if (this.connected) return;
+    let channel;
+    try {
+      ({ channel } = await this.bridge.attach(this.neuronId));
+    } catch (err) {
+      const wrapped = err instanceof Error ? err : new Error(String(err));
+      this.callbacks.onError?.(wrapped);
+      throw wrapped;
+    }
+    try {
+      this.unsubscribe = this.bridge.subscribe(channel, (frame) => {
+        this.callbacks.onFrame?.(frame);
+      });
+    } catch (err) {
+      const wrapped = err instanceof Error ? err : new Error(String(err));
+      try {
+        await this.bridge.detach(this.neuronId);
+      } catch (detachErr) {
+        this.logger.warn(
+          { err: detachErr, neuronId: this.neuronId },
+          "ipc detach during start-failure unwind also failed; main-side writer may leak"
+        );
+      }
+      this.callbacks.onError?.(wrapped);
+      throw wrapped;
+    }
+    this.connected = true;
+    this.callbacks.onOpen?.();
+  }
+  async stop() {
+    if (!this.connected) return;
+    this.connected = false;
+    this.unsubscribe?.();
+    this.unsubscribe = null;
+    try {
+      await this.bridge.detach(this.neuronId);
+    } catch (err) {
+      this.logger.warn(
+        { err, neuronId: this.neuronId },
+        "ipc detach failed; continuing shutdown"
+      );
+    }
+    this.callbacks.onClose?.("stopped");
+  }
+  async post(path, frame) {
+    return this.bridge.invoke(path, frame);
+  }
+};
+
+exports.IpcTransport = IpcTransport;
+//# sourceMappingURL=ipc.js.map
+//# sourceMappingURL=ipc.js.map

package/dist/ipc.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/logger.ts","../src/ipc-transport.ts"],"names":[],"mappings":"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","file":"ipc.js","sourcesContent":["import type { NeuronLogger } from './types.js';\n\n/**\n * Silent logger used as a default when no consumer provides one. Single\n * shared instance to avoid each module defining its own copy.\n */\nexport const noopLogger: NeuronLogger = {\n  debug() {},\n  info() {},\n  warn() {},\n  error() {},\n};\n","import type { PostPath, ServerToNeuronFrame } from '@workflow/neuron-protocol';\n\nimport { noopLogger } from './logger.js';\nimport type { Transport, TransportCallbacks } from './transport.js';\nimport type { ClientFrame, NeuronLogger } from './types.js';\n\n/**\n * Renderer-side bridge to the BigBrain gateway running in the Electron\n * main process. The SDK does NOT depend on Electron — the renderer's\n * preload script is responsible for constructing a concrete bridge that\n * forwards calls over `ipcRenderer.invoke` and `ipcRenderer.on`, then\n * exposes it via `contextBridge.exposeInMainWorld`.\n *\n * The four-method shape mirrors what the gateway needs:\n *\n *   - `attach(neuronId)` — open the inbound channel for this neuron.\n *     Resolves with the per-neuron event channel name the bridge will\n *     deliver server frames on. Concretely, in Electron main this is\n *     where the gateway constructs an `IpcSSEWriter` and stores it\n *     against the session.\n *   - `subscribe(channel, cb)` — start receiving frames on the channel\n *     `attach` handed back. Returns an unsubscribe function.\n *   - `detach(neuronId)` — close the inbound channel; the gateway tears\n *     down its writer for this neuron.\n *   - `invoke(path, frame)` — fire a typed POST. In Electron main this\n *     is `app.inject({ method: 'POST', url: path, payload: frame, headers })`\n *     so the same Fastify auth/validation chain runs as for HTTP neurons.\n *\n * The bridge is responsible for stamping authentication onto outbound\n * calls — the IPC transport never sees the JWT.\n */\nexport interface NeuronIpcBridge {\n  /**\n   * Open the inbound channel for `neuronId`. Returns the per-neuron event\n   * channel that `subscribe` should listen on.\n   */\n  attach(neuronId: string): Promise<{ channel: string }>;\n  /** Close the inbound channel. */\n  detach(neuronId: string): Promise<void>;\n  /** Subscribe to inbound frames on `channel`. Returns an unsubscribe fn. */\n  subscribe(\n    channel: string,\n    cb: (frame: ServerToNeuronFrame) => void,\n  ): () => void;\n  /** Send a typed client frame outbound. Resolves with the parsed body. */\n  invoke<T extends ClientFrame>(path: PostPath, frame: T): Promise<unknown>;\n}\n\nexport interface IpcTransportOptions {\n  /**\n   * Concrete bridge — provided by the renderer's preload script. The SDK\n   * has no opinion on its construction; it only calls the four methods.\n   */\n  bridge: NeuronIpcBridge;\n  /**\n   * Stable per-process identifier. Reused across `start`/`stop` cycles\n   * so the gateway can correlate the new attach with the same neuron.\n   */\n  neuronId: string;\n  /** Logger; defaults to a silent no-op. */\n  logger?: NeuronLogger;\n}\n\n/**\n * IPC transport for renderer-process neurons. Differences vs `HttpTransport`:\n *\n *   - No reconnect logic — IPC has no transient socket. If the bridge\n *     throws on `invoke` or `attach`, the failure surfaces via `onError`\n *     and the consumer (typically a `Neuron`) decides what to do.\n *   - No auth callback — the renderer never sees the JWT. Main attaches\n *     `Authorization` headers when it forwards to Fastify via `inject()`.\n *   - No keep-alive — IPC channels are process-local; nothing in between\n *     to time out idle connections.\n *\n * Same `Transport` contract as `HttpTransport`, so the rest of the SDK\n * (`Neuron`, `HeartbeatLoop`, `runLease`) works against either without\n * any conditional branching.\n */\nexport class IpcTransport implements Transport {\n  private readonly bridge: NeuronIpcBridge;\n  private readonly neuronId: string;\n  private readonly logger: NeuronLogger;\n  private callbacks: TransportCallbacks = {};\n  private connected = false;\n  private unsubscribe: (() => void) | null = null;\n\n  constructor(opts: IpcTransportOptions) {\n    this.bridge = opts.bridge;\n    this.neuronId = opts.neuronId;\n    this.logger = opts.logger ?? noopLogger;\n  }\n\n  subscribe(callbacks: TransportCallbacks): void {\n    this.callbacks = callbacks;\n  }\n\n  isConnected(): boolean {\n    return this.connected;\n  }\n\n  async start(): Promise<void> {\n    if (this.connected) return;\n    let channel: string;\n    try {\n      ({ channel } = await this.bridge.attach(this.neuronId));\n    } catch (err) {\n      const wrapped = err instanceof Error ? err : new Error(String(err));\n      this.callbacks.onError?.(wrapped);\n      throw wrapped;\n    }\n\n    // `attach` has succeeded — anything that throws past this point must\n    // unwind it, otherwise the main-side writer is registered with no\n    // way to reach it. Wrap subscribe in try/catch and best-effort detach\n    // on failure.\n    try {\n      this.unsubscribe = this.bridge.subscribe(channel, (frame) => {\n        this.callbacks.onFrame?.(frame);\n      });\n    } catch (err) {\n      const wrapped = err instanceof Error ? err : new Error(String(err));\n      try {\n        await this.bridge.detach(this.neuronId);\n      } catch (detachErr) {\n        this.logger.warn(\n          { err: detachErr, neuronId: this.neuronId },\n          'ipc detach during start-failure unwind also failed; main-side writer may leak',\n        );\n      }\n      this.callbacks.onError?.(wrapped);\n      throw wrapped;\n    }\n\n    this.connected = true;\n    this.callbacks.onOpen?.();\n  }\n\n  async stop(): Promise<void> {\n    if (!this.connected) return;\n    this.connected = false;\n    this.unsubscribe?.();\n    this.unsubscribe = null;\n    try {\n      await this.bridge.detach(this.neuronId);\n    } catch (err) {\n      // Detach failure is informational only — the channel is gone from\n      // our side either way. Surface for observability and continue.\n      this.logger.warn(\n        { err, neuronId: this.neuronId },\n        'ipc detach failed; continuing shutdown',\n      );\n    }\n    this.callbacks.onClose?.('stopped');\n  }\n\n  async post<T extends ClientFrame>(path: PostPath, frame: T): Promise<unknown> {\n    return this.bridge.invoke(path, frame);\n  }\n}\n"]}

package/dist/ipc.mjs

@@ -0,0 +1,84 @@
+// src/logger.ts
+var noopLogger = {
+  debug() {
+  },
+  info() {
+  },
+  warn() {
+  },
+  error() {
+  }
+};
+
+// src/ipc-transport.ts
+var IpcTransport = class {
+  bridge;
+  neuronId;
+  logger;
+  callbacks = {};
+  connected = false;
+  unsubscribe = null;
+  constructor(opts) {
+    this.bridge = opts.bridge;
+    this.neuronId = opts.neuronId;
+    this.logger = opts.logger ?? noopLogger;
+  }
+  subscribe(callbacks) {
+    this.callbacks = callbacks;
+  }
+  isConnected() {
+    return this.connected;
+  }
+  async start() {
+    if (this.connected) return;
+    let channel;
+    try {
+      ({ channel } = await this.bridge.attach(this.neuronId));
+    } catch (err) {
+      const wrapped = err instanceof Error ? err : new Error(String(err));
+      this.callbacks.onError?.(wrapped);
+      throw wrapped;
+    }
+    try {
+      this.unsubscribe = this.bridge.subscribe(channel, (frame) => {
+        this.callbacks.onFrame?.(frame);
+      });
+    } catch (err) {
+      const wrapped = err instanceof Error ? err : new Error(String(err));
+      try {
+        await this.bridge.detach(this.neuronId);
+      } catch (detachErr) {
+        this.logger.warn(
+          { err: detachErr, neuronId: this.neuronId },
+          "ipc detach during start-failure unwind also failed; main-side writer may leak"
+        );
+      }
+      this.callbacks.onError?.(wrapped);
+      throw wrapped;
+    }
+    this.connected = true;
+    this.callbacks.onOpen?.();
+  }
+  async stop() {
+    if (!this.connected) return;
+    this.connected = false;
+    this.unsubscribe?.();
+    this.unsubscribe = null;
+    try {
+      await this.bridge.detach(this.neuronId);
+    } catch (err) {
+      this.logger.warn(
+        { err, neuronId: this.neuronId },
+        "ipc detach failed; continuing shutdown"
+      );
+    }
+    this.callbacks.onClose?.("stopped");
+  }
+  async post(path, frame) {
+    return this.bridge.invoke(path, frame);
+  }
+};
+
+export { IpcTransport };
+//# sourceMappingURL=ipc.mjs.map
+//# sourceMappingURL=ipc.mjs.map

package/dist/ipc.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/logger.ts","../src/ipc-transport.ts"],"names":[],"mappings":"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","file":"ipc.mjs","sourcesContent":["import type { NeuronLogger } from './types.js';\n\n/**\n * Silent logger used as a default when no consumer provides one. Single\n * shared instance to avoid each module defining its own copy.\n */\nexport const noopLogger: NeuronLogger = {\n  debug() {},\n  info() {},\n  warn() {},\n  error() {},\n};\n","import type { PostPath, ServerToNeuronFrame } from '@workflow/neuron-protocol';\n\nimport { noopLogger } from './logger.js';\nimport type { Transport, TransportCallbacks } from './transport.js';\nimport type { ClientFrame, NeuronLogger } from './types.js';\n\n/**\n * Renderer-side bridge to the BigBrain gateway running in the Electron\n * main process. The SDK does NOT depend on Electron — the renderer's\n * preload script is responsible for constructing a concrete bridge that\n * forwards calls over `ipcRenderer.invoke` and `ipcRenderer.on`, then\n * exposes it via `contextBridge.exposeInMainWorld`.\n *\n * The four-method shape mirrors what the gateway needs:\n *\n *   - `attach(neuronId)` — open the inbound channel for this neuron.\n *     Resolves with the per-neuron event channel name the bridge will\n *     deliver server frames on. Concretely, in Electron main this is\n *     where the gateway constructs an `IpcSSEWriter` and stores it\n *     against the session.\n *   - `subscribe(channel, cb)` — start receiving frames on the channel\n *     `attach` handed back. Returns an unsubscribe function.\n *   - `detach(neuronId)` — close the inbound channel; the gateway tears\n *     down its writer for this neuron.\n *   - `invoke(path, frame)` — fire a typed POST. In Electron main this\n *     is `app.inject({ method: 'POST', url: path, payload: frame, headers })`\n *     so the same Fastify auth/validation chain runs as for HTTP neurons.\n *\n * The bridge is responsible for stamping authentication onto outbound\n * calls — the IPC transport never sees the JWT.\n */\nexport interface NeuronIpcBridge {\n  /**\n   * Open the inbound channel for `neuronId`. Returns the per-neuron event\n   * channel that `subscribe` should listen on.\n   */\n  attach(neuronId: string): Promise<{ channel: string }>;\n  /** Close the inbound channel. */\n  detach(neuronId: string): Promise<void>;\n  /** Subscribe to inbound frames on `channel`. Returns an unsubscribe fn. */\n  subscribe(\n    channel: string,\n    cb: (frame: ServerToNeuronFrame) => void,\n  ): () => void;\n  /** Send a typed client frame outbound. Resolves with the parsed body. */\n  invoke<T extends ClientFrame>(path: PostPath, frame: T): Promise<unknown>;\n}\n\nexport interface IpcTransportOptions {\n  /**\n   * Concrete bridge — provided by the renderer's preload script. The SDK\n   * has no opinion on its construction; it only calls the four methods.\n   */\n  bridge: NeuronIpcBridge;\n  /**\n   * Stable per-process identifier. Reused across `start`/`stop` cycles\n   * so the gateway can correlate the new attach with the same neuron.\n   */\n  neuronId: string;\n  /** Logger; defaults to a silent no-op. */\n  logger?: NeuronLogger;\n}\n\n/**\n * IPC transport for renderer-process neurons. Differences vs `HttpTransport`:\n *\n *   - No reconnect logic — IPC has no transient socket. If the bridge\n *     throws on `invoke` or `attach`, the failure surfaces via `onError`\n *     and the consumer (typically a `Neuron`) decides what to do.\n *   - No auth callback — the renderer never sees the JWT. Main attaches\n *     `Authorization` headers when it forwards to Fastify via `inject()`.\n *   - No keep-alive — IPC channels are process-local; nothing in between\n *     to time out idle connections.\n *\n * Same `Transport` contract as `HttpTransport`, so the rest of the SDK\n * (`Neuron`, `HeartbeatLoop`, `runLease`) works against either without\n * any conditional branching.\n */\nexport class IpcTransport implements Transport {\n  private readonly bridge: NeuronIpcBridge;\n  private readonly neuronId: string;\n  private readonly logger: NeuronLogger;\n  private callbacks: TransportCallbacks = {};\n  private connected = false;\n  private unsubscribe: (() => void) | null = null;\n\n  constructor(opts: IpcTransportOptions) {\n    this.bridge = opts.bridge;\n    this.neuronId = opts.neuronId;\n    this.logger = opts.logger ?? noopLogger;\n  }\n\n  subscribe(callbacks: TransportCallbacks): void {\n    this.callbacks = callbacks;\n  }\n\n  isConnected(): boolean {\n    return this.connected;\n  }\n\n  async start(): Promise<void> {\n    if (this.connected) return;\n    let channel: string;\n    try {\n      ({ channel } = await this.bridge.attach(this.neuronId));\n    } catch (err) {\n      const wrapped = err instanceof Error ? err : new Error(String(err));\n      this.callbacks.onError?.(wrapped);\n      throw wrapped;\n    }\n\n    // `attach` has succeeded — anything that throws past this point must\n    // unwind it, otherwise the main-side writer is registered with no\n    // way to reach it. Wrap subscribe in try/catch and best-effort detach\n    // on failure.\n    try {\n      this.unsubscribe = this.bridge.subscribe(channel, (frame) => {\n        this.callbacks.onFrame?.(frame);\n      });\n    } catch (err) {\n      const wrapped = err instanceof Error ? err : new Error(String(err));\n      try {\n        await this.bridge.detach(this.neuronId);\n      } catch (detachErr) {\n        this.logger.warn(\n          { err: detachErr, neuronId: this.neuronId },\n          'ipc detach during start-failure unwind also failed; main-side writer may leak',\n        );\n      }\n      this.callbacks.onError?.(wrapped);\n      throw wrapped;\n    }\n\n    this.connected = true;\n    this.callbacks.onOpen?.();\n  }\n\n  async stop(): Promise<void> {\n    if (!this.connected) return;\n    this.connected = false;\n    this.unsubscribe?.();\n    this.unsubscribe = null;\n    try {\n      await this.bridge.detach(this.neuronId);\n    } catch (err) {\n      // Detach failure is informational only — the channel is gone from\n      // our side either way. Surface for observability and continue.\n      this.logger.warn(\n        { err, neuronId: this.neuronId },\n        'ipc detach failed; continuing shutdown',\n      );\n    }\n    this.callbacks.onClose?.('stopped');\n  }\n\n  async post<T extends ClientFrame>(path: PostPath, frame: T): Promise<unknown> {\n    return this.bridge.invoke(path, frame);\n  }\n}\n"]}