synabun 1.3.0

package/mcp-server/src/services/file-checksums.ts

@@ -0,0 +1,33 @@
+import { createHash } from 'crypto';
+import { readFileSync } from 'fs';
+import { resolve } from 'path';
+
+/**
+ * Compute SHA-256 hash of a file's content.
+ * Absolute paths are used as-is. Relative paths resolve from process.cwd()
+ * (which is the project root when invoked by Claude Code).
+ * Returns null if the file doesn't exist or can't be read.
+ */
+export function hashFile(filePath: string): string | null {
+  try {
+    const absPath = resolve(filePath);
+    const content = readFileSync(absPath);
+    return createHash('sha256').update(content).digest('hex');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Compute checksums for an array of related file paths.
+ * Returns a Record mapping each file path to its SHA-256 hash.
+ * Files that can't be read are omitted from the result.
+ */
+export function computeChecksums(filePaths: string[]): Record<string, string> {
+  const checksums: Record<string, string> = {};
+  for (const fp of filePaths) {
+    const hash = hashFile(fp);
+    if (hash) checksums[fp] = hash;
+  }
+  return checksums;
+}

package/mcp-server/src/services/local-embeddings.ts

@@ -0,0 +1,77 @@
+/**
+ * Local embedding generation using Transformers.js (ONNX runtime).
+ * Drop-in replacement for embeddings.ts — same exported function signatures.
+ * Uses all-MiniLM-L6-v2 (384 dimensions, ~23MB quantized model).
+ * No API key, no internet required after first model download.
+ */
+
+import type { FeatureExtractionPipeline } from '@huggingface/transformers';
+
+const MODEL_NAME = 'Xenova/all-MiniLM-L6-v2';
+export const EMBEDDING_DIMENSIONS = 384;
+
+let extractor: FeatureExtractionPipeline | null = null;
+let initPromise: Promise<FeatureExtractionPipeline> | null = null;
+
+/**
+ * Lazy-loads the embedding pipeline. First call downloads the model (~23MB)
+ * and caches it permanently in ~/.cache/huggingface/. Subsequent calls reuse
+ * the cached model with no network access needed.
+ */
+async function getExtractor(): Promise<FeatureExtractionPipeline> {
+  if (extractor) return extractor;
+
+  // Prevent concurrent initialization (multiple tools calling at once)
+  if (initPromise) return initPromise;
+
+  initPromise = (async () => {
+    // Dynamic import to avoid blocking module load
+    const { pipeline } = await import('@huggingface/transformers');
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    extractor = await (pipeline as any)('feature-extraction', MODEL_NAME, {
+      dtype: 'fp32',
+    }) as FeatureExtractionPipeline;
+    return extractor;
+  })();
+
+  try {
+    return await initPromise;
+  } finally {
+    initPromise = null;
+  }
+}
+
+/**
+ * Generate a single embedding vector for the given text.
+ * Returns a 384-dimensional normalized vector (unit length).
+ */
+export async function generateEmbedding(text: string): Promise<number[]> {
+  const ext = await getExtractor();
+  const output = await ext(text, { pooling: 'mean', normalize: true });
+  return Array.from(output.data as Float32Array);
+}
+
+/**
+ * Generate embeddings for multiple texts.
+ * Processes sequentially to avoid memory spikes on large batches.
+ */
+export async function generateEmbeddingBatch(texts: string[]): Promise<number[][]> {
+  if (texts.length === 0) return [];
+  if (texts.length === 1) return [await generateEmbedding(texts[0])];
+
+  const ext = await getExtractor();
+  const results: number[][] = [];
+  for (const text of texts) {
+    const output = await ext(text, { pooling: 'mean', normalize: true });
+    results.push(Array.from(output.data as Float32Array));
+  }
+  return results;
+}
+
+/**
+ * Trigger model download/warmup without generating an actual embedding.
+ * Call this at server startup for faster first-use latency.
+ */
+export async function warmupEmbeddings(): Promise<void> {
+  await getExtractor();
+}

package/mcp-server/src/services/neural-interface.ts

@@ -0,0 +1,344 @@
+/**
+ * HTTP client for communicating with the Neural Interface Express server.
+ * The MCP server delegates all browser operations to the Neural Interface
+ * which manages Playwright sessions, CDP screencast, stealth, etc.
+ */
+
+const BASE_URL = process.env.NEURAL_INTERFACE_URL
+  || `http://localhost:${process.env.NEURAL_PORT || '3344'}`;
+const DEFAULT_TIMEOUT = 10_000;
+const LONG_TIMEOUT = 30_000;
+
+export interface BrowserSessionInfo {
+  id: string;
+  url: string;
+  title: string;
+  createdAt: number;
+  clients: number;
+}
+
+interface NiResponse {
+  ok?: boolean;
+  error?: string;
+  [key: string]: unknown;
+}
+
+async function request(
+  method: string,
+  path: string,
+  body?: Record<string, unknown>,
+  timeout = DEFAULT_TIMEOUT
+): Promise<NiResponse> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeout);
+
+  try {
+    const opts: RequestInit = {
+      method,
+      headers: { 'Content-Type': 'application/json' },
+      signal: controller.signal,
+    };
+    if (body && method !== 'GET') {
+      opts.body = JSON.stringify(body);
+    }
+    const res = await fetch(`${BASE_URL}${path}`, opts);
+    const data = await res.json() as NiResponse;
+    if (!res.ok && !data.error) {
+      data.error = `HTTP ${res.status}`;
+    }
+    return data;
+  } catch (err: unknown) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (msg.includes('abort')) {
+      return { error: `Request timed out after ${timeout}ms` };
+    }
+    return { error: `Neural Interface unreachable: ${msg}. Is the Neural Interface server running?` };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Resolve which session ID to use.
+ * - If sessionId provided, return it immediately (server returns 404 if invalid).
+ * - If 1 session exists, auto-select it.
+ * - If 0 sessions exist and autoCreate is true, create one.
+ * - If multiple sessions and no ID, return error listing them.
+ */
+export async function resolveSession(
+  sessionId?: string,
+  autoCreate?: { url?: string }
+): Promise<{ sessionId: string } | { error: string }> {
+  // Agent-scoped browser session — set by the agent orchestrator to pin
+  // this MCP instance to a specific browser session (multi-agent isolation).
+  const pinnedSession = process.env.SYNABUN_BROWSER_SESSION;
+  if (pinnedSession && !sessionId) {
+    return { sessionId: pinnedSession };
+  }
+
+  if (sessionId) {
+    // Trust the server — it will 404 if the session doesn't exist.
+    // Skipping the extra GET /api/browser/sessions verification call saves a full round-trip.
+    return { sessionId };
+  }
+
+  // List sessions
+  const data = await request('GET', '/api/browser/sessions');
+  if (data.error) return { error: data.error };
+  const sessions = (data.sessions || []) as BrowserSessionInfo[];
+
+  if (sessions.length === 1) {
+    return { sessionId: sessions[0].id };
+  }
+
+  if (sessions.length === 0) {
+    if (autoCreate) {
+      const created = await request('POST', '/api/browser/sessions', {
+        url: autoCreate.url || 'about:blank',
+      });
+      if (created.error) return { error: `Failed to auto-create session: ${created.error}` };
+      return { sessionId: created.sessionId as string };
+    }
+    return { error: 'No browser sessions open. Use browser_session to create one first, or use browser_navigate with a URL to auto-create.' };
+  }
+
+  // Multiple sessions — require explicit ID
+  const list = sessions.map(s => `  ${s.id} — ${s.title || s.url}`).join('\n');
+  return { error: `Multiple browser sessions open. Specify sessionId:\n${list}` };
+}
+
+// ── Cache invalidation ──
+
+export async function invalidateCache(reason: string): Promise<void> {
+  try {
+    await request('POST', '/api/cache/invalidate', { reason });
+  } catch {
+    // Fire-and-forget — don't block MCP tools if Neural Interface is down
+  }
+}
+
+// ── Session management ──
+
+export async function listSessions(): Promise<NiResponse> {
+  return request('GET', '/api/browser/sessions');
+}
+
+export async function createSession(url?: string): Promise<NiResponse> {
+  return request('POST', '/api/browser/sessions', {
+    url: url || 'about:blank',
+  });
+}
+
+export async function closeSession(sessionId: string): Promise<NiResponse> {
+  return request('DELETE', `/api/browser/sessions/${sessionId}`);
+}
+
+// ── Navigation ──
+
+export async function navigate(sessionId: string, url: string): Promise<NiResponse> {
+  return request('POST', `/api/browser/sessions/${sessionId}/navigate`, { url }, LONG_TIMEOUT);
+}
+
+export async function goBack(sessionId: string): Promise<NiResponse> {
+  return request('POST', `/api/browser/sessions/${sessionId}/back`);
+}
+
+export async function goForward(sessionId: string): Promise<NiResponse> {
+  return request('POST', `/api/browser/sessions/${sessionId}/forward`);
+}
+
+export async function reload(sessionId: string): Promise<NiResponse> {
+  return request('POST', `/api/browser/sessions/${sessionId}/reload`, undefined, LONG_TIMEOUT);
+}
+
+// ── Interaction (selector-based) ──
+
+export async function click(sessionId: string, selector: string, nthMatch?: number): Promise<NiResponse> {
+  return request('POST', `/api/browser/sessions/${sessionId}/click`, { selector, ...(nthMatch !== undefined && { nthMatch }) });
+}
+
+export async function fill(sessionId: string, selector: string, value: string, nthMatch?: number): Promise<NiResponse> {
+  return request('POST', `/api/browser/sessions/${sessionId}/fill`, { selector, value, ...(nthMatch !== undefined && { nthMatch }) });
+}
+
+export async function type(sessionId: string, selector: string | null, text: string, nthMatch?: number): Promise<NiResponse> {
+  return request('POST', `/api/browser/sessions/${sessionId}/type`, { selector, text, ...(nthMatch !== undefined && { nthMatch }) });
+}
+
+export async function hover(sessionId: string, selector: string, nthMatch?: number): Promise<NiResponse> {
+  return request('POST', `/api/browser/sessions/${sessionId}/hover`, { selector, ...(nthMatch !== undefined && { nthMatch }) });
+}
+
+export async function selectOption(sessionId: string, selector: string, value: string, nthMatch?: number): Promise<NiResponse> {
+  return request('POST', `/api/browser/sessions/${sessionId}/select`, { selector, value, ...(nthMatch !== undefined && { nthMatch }) });
+}
+
+export async function pressKey(sessionId: string, key: string): Promise<NiResponse> {
+  return request('POST', `/api/browser/sessions/${sessionId}/press`, { key });
+}
+
+export async function scroll(
+  sessionId: string,
+  opts: { direction: string; distance?: number; selector?: string }
+): Promise<NiResponse> {
+  return request('POST', `/api/browser/sessions/${sessionId}/scroll`, opts as Record<string, unknown>);
+}
+
+export async function upload(
+  sessionId: string,
+  selector: string,
+  filePaths: string[],
+  nthMatch?: number
+): Promise<NiResponse> {
+  return request('POST', `/api/browser/sessions/${sessionId}/upload`, { selector, filePaths, ...(nthMatch !== undefined && { nthMatch }) }, LONG_TIMEOUT);
+}
+
+// ── Observation ──
+
+export async function snapshot(sessionId: string, selector?: string): Promise<NiResponse> {
+  if (selector) return request('POST', `/api/browser/sessions/${sessionId}/snapshot`, { selector });
+  return request('GET', `/api/browser/sessions/${sessionId}/snapshot`);
+}
+
+export async function getContent(sessionId: string): Promise<NiResponse> {
+  return request('GET', `/api/browser/sessions/${sessionId}/content`);
+}
+
+export async function getMarkdown(sessionId: string): Promise<NiResponse> {
+  return request('GET', `/api/browser/sessions/${sessionId}/markdown`, undefined, LONG_TIMEOUT);
+}
+
+export async function fetchMarkdown(url: string, timeout?: number): Promise<NiResponse> {
+  return request('POST', '/api/fetch-markdown', { url, timeout }, LONG_TIMEOUT);
+}
+
+export async function screenshot(sessionId: string): Promise<NiResponse> {
+  return request('GET', `/api/browser/sessions/${sessionId}/screenshot-base64`);
+}
+
+// ── Advanced ──
+
+export async function evaluate(sessionId: string, script: string): Promise<NiResponse> {
+  return request('POST', `/api/browser/sessions/${sessionId}/evaluate`, { script }, LONG_TIMEOUT);
+}
+
+export async function waitFor(
+  sessionId: string,
+  opts: { selector?: string; state?: string; loadState?: string; timeout?: number }
+): Promise<NiResponse> {
+  return request('POST', `/api/browser/sessions/${sessionId}/wait`, opts, LONG_TIMEOUT);
+}
+
+// ── Whiteboard ──
+
+export async function getWhiteboard(): Promise<NiResponse> {
+  return request('GET', '/api/whiteboard');
+}
+
+export async function addWhiteboardElements(
+  elements: Record<string, unknown>[],
+  coordMode?: string,
+  layout?: string
+): Promise<NiResponse> {
+  return request('POST', '/api/whiteboard/elements', { elements, coordMode, layout } as Record<string, unknown>);
+}
+
+export async function updateWhiteboardElement(
+  id: string,
+  updates: Record<string, unknown>,
+  coordMode?: string
+): Promise<NiResponse> {
+  return request('PUT', `/api/whiteboard/elements/${id}`, { updates, coordMode } as Record<string, unknown>);
+}
+
+export async function removeWhiteboardElement(id: string): Promise<NiResponse> {
+  return request('DELETE', `/api/whiteboard/elements/${id}`);
+}
+
+export async function clearWhiteboard(): Promise<NiResponse> {
+  return request('POST', '/api/whiteboard/clear');
+}
+
+export async function whiteboardScreenshot(): Promise<NiResponse> {
+  return request('GET', '/api/whiteboard/screenshot', undefined, 15_000);
+}
+
+// ── Cards (Memory Card MCP integration) ──
+
+export async function getCards(): Promise<NiResponse> {
+  return request('GET', '/api/cards');
+}
+
+export async function openCard(
+  memoryId: string,
+  opts?: { left?: number; top?: number; compact?: boolean; coordMode?: string }
+): Promise<NiResponse> {
+  return request('POST', '/api/cards/open', { memoryId, ...opts } as Record<string, unknown>);
+}
+
+export async function closeCard(memoryId?: string): Promise<NiResponse> {
+  return request('POST', '/api/cards/close', memoryId ? { memoryId } : {} as Record<string, unknown>);
+}
+
+export async function updateCard(
+  memoryId: string,
+  updates: Record<string, unknown>,
+  coordMode?: string
+): Promise<NiResponse> {
+  return request('PUT', `/api/cards/${memoryId}`, { ...updates, coordMode } as Record<string, unknown>);
+}
+
+export async function cardsScreenshot(): Promise<NiResponse> {
+  return request('GET', '/api/cards/screenshot', undefined, 15_000);
+}
+
+// ── TicTacToe ──
+
+export async function tictactoeStart(piece?: string): Promise<NiResponse> {
+  return request('POST', '/api/games/tictactoe/start', { piece } as Record<string, unknown>);
+}
+
+export async function tictactoeMove(cell: number): Promise<NiResponse> {
+  return request('POST', '/api/games/tictactoe/move', { cell } as Record<string, unknown>);
+}
+
+export async function tictactoeState(): Promise<NiResponse> {
+  return request('GET', '/api/games/tictactoe/state');
+}
+
+export async function tictactoeEnd(): Promise<NiResponse> {
+  return request('POST', '/api/games/tictactoe/end');
+}
+
+// ── Git ──
+
+export async function gitStatus(path: string): Promise<NiResponse> {
+  return request('GET', `/api/git/status?path=${encodeURIComponent(path)}`);
+}
+
+export async function gitDiff(path: string, maxLines?: number): Promise<NiResponse> {
+  const qs = `path=${encodeURIComponent(path)}${maxLines ? `&maxLines=${maxLines}` : ''}`;
+  return request('GET', `/api/git/diff?${qs}`, undefined, LONG_TIMEOUT);
+}
+
+export async function gitCommit(path: string, message: string, files?: string[]): Promise<NiResponse> {
+  return request('POST', '/api/git/commit', { path, message, files } as Record<string, unknown>);
+}
+
+export async function gitLog(path: string, count?: number): Promise<NiResponse> {
+  return request('GET', `/api/git/log?path=${encodeURIComponent(path)}&count=${count || 10}`);
+}
+
+export async function gitBranches(path: string): Promise<NiResponse> {
+  return request('GET', `/api/terminal/branches?path=${encodeURIComponent(path)}`);
+}
+
+// ── Image store ──
+
+export async function listImages(): Promise<NiResponse> {
+  return request('GET', '/api/images');
+}
+
+export async function deleteImage(filename: string): Promise<NiResponse> {
+  return request('DELETE', `/api/images/${encodeURIComponent(filename)}`);
+}