@timmeck/brain-core 1.0.0

package/src/ipc/protocol.ts

@@ -0,0 +1,35 @@
+import { Buffer } from 'node:buffer';
+import type { IpcMessage } from '../types/ipc.types.js';
+
+export function encodeMessage(msg: IpcMessage): Buffer {
+  const json = JSON.stringify(msg);
+  const payload = Buffer.from(json, 'utf8');
+  const frame = Buffer.alloc(4 + payload.length);
+  frame.writeUInt32BE(payload.length, 0);
+  payload.copy(frame, 4);
+  return frame;
+}
+
+export class MessageDecoder {
+  private buffer = Buffer.alloc(0);
+
+  feed(chunk: Buffer): IpcMessage[] {
+    this.buffer = Buffer.concat([this.buffer, chunk]);
+    const messages: IpcMessage[] = [];
+
+    while (this.buffer.length >= 4) {
+      const length = this.buffer.readUInt32BE(0);
+      if (this.buffer.length < 4 + length) break;
+
+      const json = this.buffer.subarray(4, 4 + length).toString('utf8');
+      this.buffer = this.buffer.subarray(4 + length);
+      messages.push(JSON.parse(json) as IpcMessage);
+    }
+
+    return messages;
+  }
+
+  reset(): void {
+    this.buffer = Buffer.alloc(0);
+  }
+}

package/src/ipc/server.ts

@@ -0,0 +1,170 @@
+import net from 'node:net';
+import fs from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { getLogger } from '../utils/logger.js';
+import type { IpcMessage } from '../types/ipc.types.js';
+import { encodeMessage, MessageDecoder } from './protocol.js';
+
+export interface IpcRouter {
+  handle(method: string, params: unknown): unknown;
+  listMethods(): string[];
+}
+
+export class IpcServer {
+  private server: net.Server | null = null;
+  private clients = new Map<string, net.Socket>();
+  private logger = getLogger();
+
+  constructor(
+    private router: IpcRouter,
+    private pipeName: string,
+    private daemonName: string = 'brain',
+  ) {}
+
+  start(): void {
+    this.createServer();
+    this.listen();
+  }
+
+  private createServer(): void {
+    this.server = net.createServer((socket) => {
+      const clientId = randomUUID();
+      this.clients.set(clientId, socket);
+      const decoder = new MessageDecoder();
+
+      this.logger.info(`IPC client connected: ${clientId}`);
+
+      socket.on('data', (chunk) => {
+        const messages = decoder.feed(chunk);
+        for (const msg of messages) {
+          this.handleMessage(clientId, msg, socket);
+        }
+      });
+
+      socket.on('close', () => {
+        this.logger.info(`IPC client disconnected: ${clientId}`);
+        this.clients.delete(clientId);
+      });
+
+      socket.on('error', (err) => {
+        this.logger.error(`IPC client ${clientId} error:`, err);
+        this.clients.delete(clientId);
+      });
+    });
+  }
+
+  private listen(retried = false): void {
+    if (!this.server) return;
+
+    this.server.on('error', (err: NodeJS.ErrnoException) => {
+      if (err.code === 'EADDRINUSE' && !retried) {
+        this.logger.warn(`IPC pipe in use, attempting to recover stale pipe: ${this.pipeName}`);
+        this.recoverStalePipe();
+      } else {
+        this.logger.error('IPC server error:', err);
+      }
+    });
+
+    this.server.listen(this.pipeName, () => {
+      this.logger.info(`IPC server listening on ${this.pipeName}`);
+    });
+  }
+
+  private recoverStalePipe(): void {
+    const probe = net.createConnection(this.pipeName);
+
+    probe.on('connect', () => {
+      probe.destroy();
+      this.logger.error(`IPC pipe is held by another running daemon. Stop it first with: ${this.daemonName} stop`);
+    });
+
+    probe.on('error', () => {
+      probe.destroy();
+      this.logger.info('Stale IPC pipe detected, reclaiming...');
+
+      if (process.platform !== 'win32') {
+        try { fs.unlinkSync(this.pipeName); } catch { /* ignore */ }
+      }
+
+      this.createServer();
+      this.server!.on('error', (err) => {
+        this.logger.error('IPC server error after recovery:', err);
+      });
+      this.server!.listen(this.pipeName, () => {
+        this.logger.info(`IPC server recovered and listening on ${this.pipeName}`);
+      });
+    });
+
+    probe.setTimeout(2000, () => {
+      probe.destroy();
+      this.logger.warn('IPC pipe probe timed out, treating as stale');
+      if (process.platform !== 'win32') {
+        try { fs.unlinkSync(this.pipeName); } catch { /* ignore */ }
+      }
+      this.createServer();
+      this.server!.on('error', (err) => {
+        this.logger.error('IPC server error after timeout recovery:', err);
+      });
+      this.server!.listen(this.pipeName, () => {
+        this.logger.info(`IPC server recovered (timeout) and listening on ${this.pipeName}`);
+      });
+    });
+  }
+
+  private handleMessage(_clientId: string, msg: IpcMessage, socket: net.Socket): void {
+    if (msg.type !== 'request' || !msg.method) return;
+
+    try {
+      const result = this.router.handle(msg.method, msg.params);
+      const response: IpcMessage = {
+        id: msg.id,
+        type: 'response',
+        result,
+      };
+      socket.write(encodeMessage(response));
+    } catch (err) {
+      const response: IpcMessage = {
+        id: msg.id,
+        type: 'response',
+        error: { code: -1, message: err instanceof Error ? err.message : String(err) },
+      };
+      socket.write(encodeMessage(response));
+    }
+  }
+
+  notify(clientId: string | null, notification: Omit<IpcMessage, 'id' | 'type'>): void {
+    const msg: IpcMessage = {
+      id: randomUUID(),
+      type: 'notification',
+      ...notification,
+    };
+    const encoded = encodeMessage(msg);
+
+    if (clientId) {
+      const socket = this.clients.get(clientId);
+      if (socket && !socket.destroyed) {
+        socket.write(encoded);
+      }
+    } else {
+      for (const socket of this.clients.values()) {
+        if (!socket.destroyed) {
+          socket.write(encoded);
+        }
+      }
+    }
+  }
+
+  getClientCount(): number {
+    return this.clients.size;
+  }
+
+  stop(): void {
+    for (const socket of this.clients.values()) {
+      socket.destroy();
+    }
+    this.clients.clear();
+    this.server?.close();
+    this.server = null;
+    this.logger.info('IPC server stopped');
+  }
+}

package/src/mcp/http-server.ts

@@ -0,0 +1,148 @@
+import http from 'node:http';
+import { randomUUID } from 'node:crypto';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
+import { getLogger } from '../utils/logger.js';
+import type { IpcRouter } from '../ipc/server.js';
+
+export interface McpHttpServerOptions {
+  /** MCP server name */
+  name: string;
+  /** MCP server version */
+  version: string;
+}
+
+export class McpHttpServer {
+  private server: http.Server | null = null;
+  private transports = new Map<string, SSEServerTransport>();
+  private logger = getLogger();
+
+  constructor(
+    private port: number,
+    private router: IpcRouter,
+    private meta: McpHttpServerOptions,
+    private registerToolsDirect: (server: McpServer, router: IpcRouter) => void,
+  ) {}
+
+  start(): void {
+    this.server = http.createServer((req, res) => {
+      res.setHeader('Access-Control-Allow-Origin', '*');
+      res.setHeader('Access-Control-Allow-Methods', 'GET, POST, DELETE, OPTIONS');
+      res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+
+      if (req.method === 'OPTIONS') {
+        res.writeHead(204);
+        res.end();
+        return;
+      }
+
+      const url = new URL(req.url ?? '/', `http://localhost:${this.port}`);
+
+      if (url.pathname === '/sse' && req.method === 'GET') {
+        this.handleSSE(res);
+        return;
+      }
+
+      if (url.pathname === '/messages' && req.method === 'POST') {
+        this.handleMessage(req, res, url);
+        return;
+      }
+
+      if (url.pathname === '/' && req.method === 'GET') {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+          name: this.meta.name,
+          version: this.meta.version,
+          protocol: 'MCP',
+          transport: 'sse',
+          endpoints: {
+            sse: '/sse',
+            messages: '/messages',
+          },
+          clients: this.transports.size,
+        }));
+        return;
+      }
+
+      res.writeHead(404, { 'Content-Type': 'text/plain' });
+      res.end('Not Found');
+    });
+
+    this.server.listen(this.port, () => {
+      this.logger.info(`MCP HTTP server (SSE) started on http://localhost:${this.port}`);
+    });
+  }
+
+  stop(): void {
+    for (const transport of this.transports.values()) {
+      try { transport.close?.(); } catch { /* ignore */ }
+    }
+    this.transports.clear();
+    this.server?.close();
+    this.server = null;
+    this.logger.info('MCP HTTP server stopped');
+  }
+
+  getClientCount(): number {
+    return this.transports.size;
+  }
+
+  private async handleSSE(res: http.ServerResponse): Promise<void> {
+    try {
+      const transport = new SSEServerTransport('/messages', res);
+      const sessionId = transport.sessionId ?? randomUUID();
+      this.transports.set(sessionId, transport);
+
+      const server = new McpServer({
+        name: this.meta.name,
+        version: this.meta.version,
+      });
+
+      this.registerToolsDirect(server, this.router);
+
+      res.on('close', () => {
+        this.transports.delete(sessionId);
+        this.logger.debug(`MCP SSE client disconnected: ${sessionId}`);
+      });
+
+      await server.connect(transport);
+      this.logger.info(`MCP SSE client connected: ${sessionId}`);
+    } catch (err) {
+      this.logger.error('MCP SSE connection error:', err);
+      if (!res.headersSent) {
+        res.writeHead(500, { 'Content-Type': 'text/plain' });
+        res.end('Internal Server Error');
+      }
+    }
+  }
+
+  private async handleMessage(
+    req: http.IncomingMessage,
+    res: http.ServerResponse,
+    url: URL,
+  ): Promise<void> {
+    try {
+      const sessionId = url.searchParams.get('sessionId');
+      if (!sessionId) {
+        res.writeHead(400, { 'Content-Type': 'text/plain' });
+        res.end('Missing sessionId parameter');
+        return;
+      }
+
+      const transport = this.transports.get(sessionId);
+      if (!transport) {
+        res.writeHead(404, { 'Content-Type': 'text/plain' });
+        res.end('Session not found. Connect to /sse first.');
+        return;
+      }
+
+      await transport.handlePostMessage(req, res);
+    } catch (err) {
+      this.logger.error('MCP message error:', err);
+      if (!res.headersSent) {
+        res.writeHead(500, { 'Content-Type': 'text/plain' });
+        res.end('Internal Server Error');
+      }
+    }
+  }
+}

package/src/mcp/server.ts

@@ -0,0 +1,84 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import { IpcClient } from '../ipc/client.js';
+import { getPipeName } from '../utils/paths.js';
+
+export interface McpServerOptions {
+  /** MCP server name (e.g. 'brain', 'trading-brain') */
+  name: string;
+  /** MCP server version */
+  version: string;
+  /** Pipe name for IPC connection */
+  pipeName?: string;
+  /** Path to the CLI entry point for auto-starting the daemon */
+  entryPoint: string;
+  /** Register MCP tools on the server */
+  registerTools: (server: McpServer, ipc: IpcClient) => void;
+}
+
+function spawnDaemon(opts: McpServerOptions): void {
+  const child = spawn(process.execPath, [
+    '--import', 'tsx',
+    opts.entryPoint, 'daemon',
+  ], {
+    detached: true,
+    stdio: 'ignore',
+    cwd: path.resolve(path.dirname(opts.entryPoint), '..'),
+  });
+  child.unref();
+  process.stderr.write(`${opts.name}: Auto-started daemon (PID: ${child.pid})\n`);
+}
+
+async function connectWithRetry(ipc: IpcClient, retries: number, delayMs: number): Promise<void> {
+  for (let i = 0; i < retries; i++) {
+    try {
+      await ipc.connect();
+      return;
+    } catch {
+      if (i < retries - 1) {
+        await new Promise(r => setTimeout(r, delayMs));
+      }
+    }
+  }
+  throw new Error('Could not connect to daemon after retries');
+}
+
+export async function startMcpServer(opts: McpServerOptions): Promise<void> {
+  const server = new McpServer({
+    name: opts.name,
+    version: opts.version,
+  });
+
+  const pipeName = opts.pipeName ?? getPipeName(opts.name);
+  const ipc = new IpcClient(pipeName);
+
+  try {
+    await ipc.connect();
+  } catch {
+    process.stderr.write(`${opts.name}: Daemon not running, starting automatically...\n`);
+    spawnDaemon(opts);
+    try {
+      await connectWithRetry(ipc, 10, 500);
+    } catch {
+      process.stderr.write(`${opts.name}: Could not connect to daemon after auto-start. Check logs.\n`);
+      process.exit(1);
+    }
+  }
+
+  opts.registerTools(server, ipc);
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+
+  process.on('SIGINT', () => {
+    ipc.disconnect();
+    process.exit(0);
+  });
+
+  process.on('SIGTERM', () => {
+    ipc.disconnect();
+    process.exit(0);
+  });
+}

package/src/types/ipc.types.ts

@@ -0,0 +1,8 @@
+export interface IpcMessage {
+  id: string;
+  type: 'request' | 'response' | 'notification';
+  method?: string;
+  params?: unknown;
+  result?: unknown;
+  error?: { code: number; message: string };
+}

package/src/utils/events.ts

@@ -0,0 +1,30 @@
+import { EventEmitter } from 'node:events';
+
+/**
+ * Generic typed event bus. Each brain defines its own events interface:
+ *
+ * ```ts
+ * interface MyEvents {
+ *   'trade:recorded': { tradeId: number; win: boolean };
+ *   'rule:learned': { ruleId: number; pattern: string };
+ * }
+ * const bus = new TypedEventBus<MyEvents>();
+ * ```
+ */
+export class TypedEventBus<T extends Record<string, unknown>> extends EventEmitter {
+  emit<K extends keyof T & string>(event: K, data: T[K]): boolean {
+    return super.emit(event, data);
+  }
+
+  on<K extends keyof T & string>(event: K, listener: (data: T[K]) => void): this {
+    return super.on(event, listener);
+  }
+
+  once<K extends keyof T & string>(event: K, listener: (data: T[K]) => void): this {
+    return super.once(event, listener);
+  }
+
+  off<K extends keyof T & string>(event: K, listener: (data: T[K]) => void): this {
+    return super.off(event, listener);
+  }
+}

package/src/utils/hash.ts

@@ -0,0 +1,5 @@
+import { createHash } from 'node:crypto';
+
+export function sha256(input: string): string {
+  return createHash('sha256').update(input).digest('hex');
+}

package/src/utils/logger.ts

@@ -0,0 +1,67 @@
+import winston from 'winston';
+import path from 'node:path';
+
+const { combine, timestamp, printf, colorize } = winston.format;
+
+const logFormat = printf(({ level, message, timestamp, ...meta }) => {
+  const metaStr = Object.keys(meta).length ? ` ${JSON.stringify(meta)}` : '';
+  return `${timestamp} [${level}]${metaStr} ${message}`;
+});
+
+let loggerInstance: winston.Logger | null = null;
+
+export interface LoggerOptions {
+  level?: string;
+  file?: string;
+  maxSize?: number;
+  maxFiles?: number;
+  /** Environment variable name for log level override (e.g. 'BRAIN_LOG_LEVEL') */
+  envVar?: string;
+  /** Default log filename when no file is specified (e.g. 'brain.log') */
+  defaultFilename?: string;
+  /** Data directory to place the log file in */
+  dataDir?: string;
+}
+
+export function createLogger(opts?: LoggerOptions): winston.Logger {
+  if (loggerInstance) return loggerInstance;
+
+  const envVar = opts?.envVar ?? 'BRAIN_LOG_LEVEL';
+  const defaultFilename = opts?.defaultFilename ?? 'brain.log';
+
+  const level = opts?.level ?? process.env[envVar] ?? 'info';
+  const logFile = opts?.file ?? (opts?.dataDir ? path.join(opts.dataDir, defaultFilename) : defaultFilename);
+  const maxSize = opts?.maxSize ?? 10 * 1024 * 1024; // 10MB
+  const maxFiles = opts?.maxFiles ?? 3;
+
+  const transports: winston.transport[] = [
+    new winston.transports.File({
+      filename: logFile,
+      maxsize: maxSize,
+      maxFiles,
+      format: combine(timestamp(), logFormat),
+    }),
+  ];
+
+  if (process.env['NODE_ENV'] !== 'production') {
+    transports.push(
+      new winston.transports.Console({
+        format: combine(colorize(), timestamp(), logFormat),
+      })
+    );
+  }
+
+  loggerInstance = winston.createLogger({ level, transports });
+  return loggerInstance;
+}
+
+export function getLogger(): winston.Logger {
+  if (!loggerInstance) {
+    return createLogger();
+  }
+  return loggerInstance;
+}
+
+export function resetLogger(): void {
+  loggerInstance = null;
+}

package/src/utils/paths.ts

@@ -0,0 +1,24 @@
+import path from 'node:path';
+import os from 'node:os';
+
+export function normalizePath(filePath: string): string {
+  return filePath.replace(/\\/g, '/');
+}
+
+/**
+ * Get the data directory for a brain instance.
+ * @param envVar - Environment variable name (e.g. 'BRAIN_DATA_DIR')
+ * @param defaultDir - Default directory name in home (e.g. '.brain')
+ */
+export function getDataDir(envVar: string = 'BRAIN_DATA_DIR', defaultDir: string = '.brain'): string {
+  const envDirValue = process.env[envVar];
+  if (envDirValue) return path.resolve(envDirValue);
+  return path.join(os.homedir(), defaultDir);
+}
+
+export function getPipeName(name: string = 'brain'): string {
+  if (process.platform === 'win32') {
+    return `\\\\.\\pipe\\${name}`;
+  }
+  return path.join(os.tmpdir(), `${name}.sock`);
+}

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true,
+    "sourceMap": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}