@geravant/sinain 1.0.19 → 1.1.0

package/sinain-core/src/overlay/ws-handler.ts

@@ -0,0 +1,267 @@
+import { WebSocket } from "ws";
+import type { IncomingMessage } from "node:http";
+import type {
+  BridgeState,
+  OutboundMessage,
+  InboundMessage,
+  FeedMessage,
+  StatusMessage,
+  SpawnTaskMessage,
+  Priority,
+  FeedChannel,
+} from "../types.js";
+import { log, warn } from "../log.js";
+
+const TAG = "ws";
+const HEARTBEAT_INTERVAL_MS = 10_000;
+const MAX_REPLAY = 20;
+const SPAWN_TASK_TTL_MS = 120_000; // prune terminal tasks after 120s
+
+type MessageHandler = (msg: InboundMessage, client: WebSocket) => void;
+type ProfilingHandler = (msg: any) => void;
+
+/**
+ * WebSocket handler for overlay connections.
+ * Manages connected clients, heartbeat pings, replay buffer, and message routing.
+ * Ported from bridge/ws-server.ts — now runs on the same port as HTTP via the shared http.Server.
+ */
+export class WsHandler {
+  private clients: Set<WebSocket> = new Set();
+  private heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+  private onMessage: MessageHandler | null = null;
+  private onProfilingCb: ProfilingHandler | null = null;
+  private state: BridgeState = {
+    audio: "muted",
+    mic: "muted",
+    screen: "off",
+    connection: "disconnected",
+  };
+  private replayBuffer: FeedMessage[] = [];
+  private spawnTaskBuffer: Map<string, SpawnTaskMessage> = new Map();
+
+  constructor() {
+    this.startHeartbeat();
+  }
+
+  /** Register handler for incoming overlay messages. */
+  onIncoming(handler: MessageHandler): void {
+    this.onMessage = handler;
+  }
+
+  /** Register handler for profiling messages from overlay. */
+  onProfiling(handler: ProfilingHandler): void {
+    this.onProfilingCb = handler;
+  }
+
+  /** Handle a new WS connection (called from server.ts wss.on('connection')). */
+  handleConnection(ws: WebSocket, req: IncomingMessage): void {
+    const addr = req.socket.remoteAddress ?? "unknown";
+    log(TAG, `client connected from ${addr}`);
+    this.clients.add(ws);
+    this.updateConnection("connected");
+
+    (ws as any).__alive = true;
+
+    // Send current status on connect
+    this.sendTo(ws, {
+      type: "status",
+      audio: this.state.audio,
+      mic: this.state.mic,
+      screen: this.state.screen,
+      connection: this.state.connection,
+    });
+
+    // Replay recent feed messages for late-joining clients
+    for (const msg of this.replayBuffer) {
+      this.sendTo(ws, msg);
+    }
+    if (this.replayBuffer.length > 0) {
+      log(TAG, `replayed ${this.replayBuffer.length} buffered messages to new client`);
+    }
+
+    // Replay spawn task state for late-joining clients
+    this.pruneSpawnTasks();
+    for (const msg of this.spawnTaskBuffer.values()) {
+      this.sendTo(ws, msg);
+    }
+    if (this.spawnTaskBuffer.size > 0) {
+      log(TAG, `replayed ${this.spawnTaskBuffer.size} spawn tasks to new client`);
+    }
+
+    ws.on("message", (raw) => {
+      try {
+        const data = JSON.parse(raw.toString()) as InboundMessage;
+        this.handleIncoming(data, ws);
+      } catch {
+        warn(TAG, "bad message from client:", raw.toString().slice(0, 200));
+      }
+    });
+
+    ws.on("pong", () => {
+      (ws as any).__alive = true;
+    });
+
+    ws.on("close", (code, reason) => {
+      log(TAG, `client disconnected: ${code} ${reason?.toString() ?? ""}`);
+      this.clients.delete(ws);
+      ws.removeAllListeners();
+      if (this.clients.size === 0) {
+        this.updateConnection("disconnected");
+      }
+    });
+
+    ws.on("error", (err) => {
+      warn(TAG, "client error:", err.message);
+      this.clients.delete(ws);
+      ws.removeAllListeners();
+    });
+  }
+
+  /** Broadcast a feed message to all connected overlays. */
+  broadcast(text: string, priority: Priority = "normal", channel: FeedChannel = "stream"): void {
+    const msg: FeedMessage = {
+      type: "feed",
+      text,
+      priority,
+      ts: Date.now(),
+      channel,
+    };
+    this.replayBuffer.push(msg);
+    if (this.replayBuffer.length > MAX_REPLAY) {
+      this.replayBuffer.shift();
+    }
+    this.broadcastMessage(msg);
+  }
+
+  /** Send a status update to all connected overlays. */
+  broadcastStatus(): void {
+    const msg: StatusMessage = {
+      type: "status",
+      audio: this.state.audio,
+      mic: this.state.mic,
+      screen: this.state.screen,
+      connection: this.state.connection,
+    };
+    this.broadcastMessage(msg);
+  }
+
+  /** Broadcast any outbound message (used by escalator for spawn_task events). */
+  broadcastRaw(msg: OutboundMessage): void {
+    if (msg.type === "spawn_task") {
+      const taskMsg = msg as SpawnTaskMessage;
+      this.spawnTaskBuffer.set(taskMsg.taskId, taskMsg);
+      this.pruneSpawnTasks();
+      log(TAG, `spawn_task buffered: taskId=${taskMsg.taskId}, status=${taskMsg.status}, buffer=${this.spawnTaskBuffer.size}, clients=${this.clients.size}`);
+    }
+    this.broadcastMessage(msg);
+  }
+
+  /** Update internal state and broadcast. */
+  updateState(partial: Partial<BridgeState>): void {
+    Object.assign(this.state, partial);
+    this.broadcastStatus();
+  }
+
+  /** Get current state. */
+  getState(): Readonly<BridgeState> {
+    return { ...this.state };
+  }
+
+  /** Number of connected clients. */
+  get clientCount(): number {
+    return this.clients.size;
+  }
+
+  /** Graceful shutdown. */
+  destroy(): void {
+    this.stopHeartbeat();
+    for (const ws of this.clients) {
+      ws.close(1001, "server shutting down");
+    }
+    this.clients.clear();
+  }
+
+  // ── Private ──
+
+  private handleIncoming(msg: InboundMessage, ws: WebSocket): void {
+    switch (msg.type) {
+      case "pong":
+        (ws as any).__alive = true;
+        return;
+      case "message":
+        log(TAG, `\u2190 user message: ${msg.text.slice(0, 100)}`);
+        break;
+      case "command":
+        log(TAG, `\u2190 command: ${msg.action}`);
+        break;
+      case "profiling":
+        if (this.onProfilingCb) this.onProfilingCb(msg);
+        return;
+      default:
+        warn(TAG, `unknown message type: ${(msg as any).type}`);
+        return;
+    }
+    if (this.onMessage) {
+      this.onMessage(msg, ws);
+    }
+  }
+
+  private sendTo(ws: WebSocket, msg: OutboundMessage): void {
+    if (ws.readyState === WebSocket.OPEN) {
+      ws.send(JSON.stringify(msg));
+    }
+  }
+
+  private broadcastMessage(msg: OutboundMessage): void {
+    const payload = JSON.stringify(msg);
+    for (const ws of this.clients) {
+      if (ws.readyState === WebSocket.OPEN) {
+        ws.send(payload);
+      }
+    }
+  }
+
+  private pruneSpawnTasks(): void {
+    const now = Date.now();
+    const terminal = new Set(["completed", "failed", "timeout"]);
+    for (const [id, msg] of this.spawnTaskBuffer) {
+      if (terminal.has(msg.status) && msg.completedAt && now - msg.completedAt > SPAWN_TASK_TTL_MS) {
+        this.spawnTaskBuffer.delete(id);
+      }
+    }
+  }
+
+  private updateConnection(status: BridgeState["connection"]): void {
+    this.state.connection = status;
+    if (this.clients.size > 0) {
+      this.broadcastStatus();
+    }
+  }
+
+  private startHeartbeat(): void {
+    this.heartbeatTimer = setInterval(() => {
+      for (const ws of this.clients) {
+        if ((ws as any).__alive === false) {
+          log(TAG, "client failed heartbeat \u2014 closing");
+          ws.close(4000, "heartbeat timeout");
+          this.clients.delete(ws);
+          if (this.clients.size === 0) {
+            this.updateConnection("disconnected");
+          }
+          continue;
+        }
+        (ws as any).__alive = false;
+        ws.ping();
+        // App-level ping for Flutter clients that don't handle protocol pings
+        this.sendTo(ws, { type: "ping", ts: Date.now() });
+      }
+    }, HEARTBEAT_INTERVAL_MS);
+  }
+
+  private stopHeartbeat(): void {
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+  }
+}

package/sinain-core/src/privacy/index.ts

@@ -0,0 +1,18 @@
+import type { PrivacyConfig, PrivacyMatrix, PrivacyDest, PrivacyLevel } from "../types.js";
+
+let _privacy: PrivacyConfig | undefined;
+
+export function initPrivacy(cfg: PrivacyConfig): void {
+  _privacy = cfg;
+}
+
+export function getPrivacy(): PrivacyConfig {
+  if (!_privacy) throw new Error("Privacy not initialized — call initPrivacy() first");
+  return _privacy;
+}
+
+export function levelFor(dataType: keyof PrivacyMatrix, dest: PrivacyDest): PrivacyLevel {
+  return getPrivacy().matrix[dataType][dest];
+}
+
+export { applyLevel, redactText, summarizeAudio, summarizeOcr } from "./redact.js";

package/sinain-core/src/privacy/presets.ts

@@ -0,0 +1,40 @@
+import type { PrivacyMatrix } from "../types.js";
+
+const FULL_ROW = { local_buffer: "full" as const, local_llm: "full" as const, triple_store: "full" as const, openrouter: "full" as const, agent_gateway: "full" as const };
+
+const ALL_FULL: PrivacyMatrix = {
+  audio_transcript: { ...FULL_ROW },
+  screen_ocr:       { ...FULL_ROW },
+  screen_images:    { ...FULL_ROW },
+  window_titles:    { ...FULL_ROW },
+  credentials:      { ...FULL_ROW },
+  metadata:         { ...FULL_ROW },
+};
+
+export const PRESETS: Record<string, PrivacyMatrix> = {
+  off: ALL_FULL,
+  standard: {
+    audio_transcript: { local_buffer: "full",    local_llm: "redacted", triple_store: "redacted", openrouter: "redacted", agent_gateway: "redacted" },
+    screen_ocr:       { local_buffer: "redacted", local_llm: "redacted", triple_store: "redacted", openrouter: "redacted", agent_gateway: "redacted" },
+    screen_images:    { local_buffer: "full",     local_llm: "none",     triple_store: "none",     openrouter: "none",     agent_gateway: "none"     },
+    window_titles:    { local_buffer: "full",     local_llm: "summary",  triple_store: "summary",  openrouter: "summary",  agent_gateway: "none"     },
+    credentials:      { local_buffer: "none",     local_llm: "none",     triple_store: "none",     openrouter: "none",     agent_gateway: "none"     },
+    metadata:         { local_buffer: "full",     local_llm: "full",     triple_store: "full",     openrouter: "summary",  agent_gateway: "summary"  },
+  },
+  strict: {
+    audio_transcript: { local_buffer: "redacted", local_llm: "summary",  triple_store: "summary",  openrouter: "summary",  agent_gateway: "none"     },
+    screen_ocr:       { local_buffer: "redacted", local_llm: "summary",  triple_store: "none",     openrouter: "summary",  agent_gateway: "none"     },
+    screen_images:    { local_buffer: "none",     local_llm: "none",     triple_store: "none",     openrouter: "none",     agent_gateway: "none"     },
+    window_titles:    { local_buffer: "summary",  local_llm: "summary",  triple_store: "none",     openrouter: "none",     agent_gateway: "none"     },
+    credentials:      { local_buffer: "none",     local_llm: "none",     triple_store: "none",     openrouter: "none",     agent_gateway: "none"     },
+    metadata:         { local_buffer: "full",     local_llm: "summary",  triple_store: "summary",  openrouter: "none",     agent_gateway: "none"     },
+  },
+  paranoid: {
+    audio_transcript: { local_buffer: "redacted", local_llm: "none",     triple_store: "none",     openrouter: "none",     agent_gateway: "none"     },
+    screen_ocr:       { local_buffer: "redacted", local_llm: "none",     triple_store: "none",     openrouter: "none",     agent_gateway: "none"     },
+    screen_images:    { local_buffer: "none",     local_llm: "none",     triple_store: "none",     openrouter: "none",     agent_gateway: "none"     },
+    window_titles:    { local_buffer: "none",     local_llm: "none",     triple_store: "none",     openrouter: "none",     agent_gateway: "none"     },
+    credentials:      { local_buffer: "none",     local_llm: "none",     triple_store: "none",     openrouter: "none",     agent_gateway: "none"     },
+    metadata:         { local_buffer: "summary",  local_llm: "none",     triple_store: "none",     openrouter: "none",     agent_gateway: "none"     },
+  },
+};

package/sinain-core/src/privacy/redact.ts

@@ -0,0 +1,92 @@
+import type { PrivacyLevel } from "../types.js";
+
+// ── Pattern library ──────────────────────────────────────────────────────────
+
+// AUTH_CREDENTIALS
+const AUTH_CREDENTIALS = [
+  /\bpassword\s*[:=]\s*\S+/gi,
+  /\bpasswd\s*[:=]\s*\S+/gi,
+  /\bsecret\s*[:=]\s*\S+/gi,
+  /\bpwd\s*[:=]\s*\S+/gi,
+  /\bpin\s*[:=]\s*\d{4,8}\b/gi,
+];
+
+// API_TOKENS
+const API_TOKENS = [
+  /\bBearer\s+[A-Za-z0-9\-._~+/]+=*/gi,
+  /\bsk-[A-Za-z0-9]{20,}/g,
+  /\bghp_[A-Za-z0-9]{36}/g,
+  /\bghs_[A-Za-z0-9]{36}/g,
+  /\b(AKIA|ASIA)[A-Z0-9]{16}\b/g,
+  /\bxox[bpoa]-[0-9A-Za-z-]+/g,
+  /\bya29\.[0-9A-Za-z-_]+/g,
+  /\beyJ[A-Za-z0-9-_]+\.[A-Za-z0-9-_]+\.[A-Za-z0-9-_]+/g,
+  /\bapi[_-]?key\s*[:=]\s*\S+/gi,
+];
+
+// FINANCIAL
+const FINANCIAL = [
+  // Luhn-matching card numbers (16 digits with optional separators)
+  /\b(?:\d{4}[-\s]?){3}\d{4}\b/g,
+  /\bCVV\s*[:=]?\s*\d{3,4}\b/gi,
+  /\bIBAN\s*[:=]?\s*[A-Z]{2}\d{2}[\dA-Z]{4,30}\b/gi,
+  /\b\d{3}-\d{2}-\d{4}\b/g, // SSN
+];
+
+// PII_CONTACT
+const PII_CONTACT = [
+  /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g,
+  /\+?1?\s?\(?\d{3}\)?[\s.-]?\d{3}[\s.-]?\d{4}\b/g, // US phone
+  /\+\d{1,3}\s\d{1,4}[\s.-]\d{3,4}[\s.-]\d{4,9}/g, // international phone
+];
+
+// HEALTH
+const HEALTH = [
+  /\bMRN\s*[:=]?\s*\d{6,10}\b/gi,
+  /\b(diagnosis|prescription|patient ID)\s*[:=]\s*\S+/gi,
+];
+
+const ALL_PATTERNS: RegExp[] = [
+  ...AUTH_CREDENTIALS,
+  ...API_TOKENS,
+  ...FINANCIAL,
+  ...PII_CONTACT,
+  ...HEALTH,
+];
+
+export function redactText(text: string): string {
+  let result = text;
+  for (const pattern of ALL_PATTERNS) {
+    result = result.replace(pattern, "[REDACTED]");
+  }
+  return result;
+}
+
+export function summarizeAudio(text: string): string {
+  const wordCount = text.trim().split(/\s+/).filter(Boolean).length;
+  return `[AUDIO: ${wordCount} words]`;
+}
+
+export function summarizeOcr(text: string): string {
+  return `[SCREEN: ${text.length} chars]`;
+}
+
+export function applyLevel(
+  text: string,
+  level: PrivacyLevel,
+  dataType: "audio" | "ocr" | "titles" = "ocr"
+): string {
+  switch (level) {
+    case "full":
+      return text;
+    case "redacted":
+      return redactText(text);
+    case "summary":
+      if (dataType === "audio") return summarizeAudio(text);
+      return summarizeOcr(text);
+    case "none":
+      return "";
+    default:
+      return text;
+  }
+}

package/sinain-core/src/profiler.ts

@@ -0,0 +1,181 @@
+/**
+ * Central metrics collector for all HUD processes.
+ * Subsystems report gauges and timers; external processes (sense, overlay)
+ * push snapshots via HTTP/WS. `/health` returns everything in one call.
+ */
+
+import { monitorEventLoopDelay, PerformanceObserver } from "node:perf_hooks";
+import type { IntervalHistogram } from "node:perf_hooks";
+
+export interface ProcessSnapshot {
+  rssMb: number;
+  heapUsedMb?: number;
+  heapTotalMb?: number;
+  cpuUserMs?: number;
+  cpuSystemMs?: number;
+  uptimeS: number;
+  ts: number;
+  extra?: Record<string, number>;
+}
+
+interface TimerStats {
+  count: number;
+  totalMs: number;
+  lastMs: number;
+  maxMs: number;
+}
+
+export interface ProfilingSnapshot {
+  core: ProcessSnapshot & {
+    gauges: Record<string, number>;
+    timers: Record<string, TimerStats>;
+  };
+  sense: ProcessSnapshot | null;
+  overlay: ProcessSnapshot | null;
+  sampledAt: number;
+}
+
+export class Profiler {
+  private gauges: Record<string, number> = {};
+  private timers: Record<string, TimerStats> = {};
+  private coreSnapshot: ProcessSnapshot | null = null;
+  private senseSnapshot: ProcessSnapshot | null = null;
+  private overlaySnapshot: ProcessSnapshot | null = null;
+  private interval: ReturnType<typeof setInterval> | null = null;
+  private startTs = Date.now();
+
+  // Event loop lag tracking
+  private elHistogram: IntervalHistogram | null = null;
+  private elMaxLagMs = 0;
+
+  // GC pause tracking
+  private gcObserver: PerformanceObserver | null = null;
+  private gcStats = { totalPauseMs: 0, count: 0, lastPauseMs: 0, maxPauseMs: 0 };
+
+  /** Set a named gauge value. */
+  gauge(name: string, value: number): void {
+    this.gauges[name] = value;
+  }
+
+  /** Record a timing measurement. */
+  timerRecord(name: string, durationMs: number): void {
+    const existing = this.timers[name];
+    if (existing) {
+      existing.count++;
+      existing.totalMs += durationMs;
+      existing.lastMs = durationMs;
+      if (durationMs > existing.maxMs) existing.maxMs = durationMs;
+    } else {
+      this.timers[name] = { count: 1, totalMs: durationMs, lastMs: durationMs, maxMs: durationMs };
+    }
+  }
+
+  /** Wrap an async call with automatic timing. */
+  async timeAsync<T>(name: string, fn: () => Promise<T>): Promise<T> {
+    const start = Date.now();
+    try {
+      return await fn();
+    } finally {
+      this.timerRecord(name, Date.now() - start);
+    }
+  }
+
+  /** Store the latest sense_client process snapshot. */
+  reportSense(snapshot: ProcessSnapshot): void {
+    this.senseSnapshot = snapshot;
+  }
+
+  /** Store the latest overlay process snapshot. */
+  reportOverlay(snapshot: ProcessSnapshot): void {
+    this.overlaySnapshot = snapshot;
+  }
+
+  /** Returns the full profiling payload for /health. */
+  getSnapshot(): ProfilingSnapshot {
+    return {
+      core: {
+        ...(this.coreSnapshot ?? this.sampleCore()),
+        gauges: { ...this.gauges },
+        timers: { ...this.timers },
+      },
+      sense: this.senseSnapshot,
+      overlay: this.overlaySnapshot,
+      sampledAt: Date.now(),
+    };
+  }
+
+  /** Start periodic core process sampling (every 10s). */
+  start(): void {
+    this.startTs = Date.now();
+    this.sampleCore();
+    this.interval = setInterval(() => this.sampleCore(), 10_000);
+
+    // Event loop lag histogram (20ms resolution)
+    this.elHistogram = monitorEventLoopDelay({ resolution: 20 });
+    this.elHistogram.enable();
+
+    // GC pause observer
+    try {
+      this.gcObserver = new PerformanceObserver((list) => {
+        for (const entry of list.getEntries()) {
+          const pauseMs = entry.duration;
+          this.gcStats.count++;
+          this.gcStats.totalPauseMs += pauseMs;
+          this.gcStats.lastPauseMs = pauseMs;
+          if (pauseMs > this.gcStats.maxPauseMs) this.gcStats.maxPauseMs = pauseMs;
+        }
+      });
+      this.gcObserver.observe({ entryTypes: ["gc"] });
+    } catch {
+      // GC observation may not be available in all environments
+    }
+  }
+
+  /** Stop periodic sampling. */
+  stop(): void {
+    if (this.interval) {
+      clearInterval(this.interval);
+      this.interval = null;
+    }
+    if (this.elHistogram) {
+      this.elHistogram.disable();
+      this.elHistogram = null;
+    }
+    if (this.gcObserver) {
+      this.gcObserver.disconnect();
+      this.gcObserver = null;
+    }
+  }
+
+  private sampleCore(): ProcessSnapshot {
+    const mem = process.memoryUsage();
+    const cpu = process.cpuUsage();
+    const snap: ProcessSnapshot = {
+      rssMb: Math.round((mem.rss / 1048576) * 10) / 10,
+      heapUsedMb: Math.round((mem.heapUsed / 1048576) * 10) / 10,
+      heapTotalMb: Math.round((mem.heapTotal / 1048576) * 10) / 10,
+      cpuUserMs: Math.round(cpu.user / 1000),
+      cpuSystemMs: Math.round(cpu.system / 1000),
+      uptimeS: Math.round((Date.now() - this.startTs) / 1000),
+      ts: Date.now(),
+    };
+    this.coreSnapshot = snap;
+
+    // Event loop lag gauges
+    if (this.elHistogram) {
+      const meanLagMs = this.elHistogram.mean / 1e6; // ns → ms
+      if (meanLagMs > this.elMaxLagMs) this.elMaxLagMs = meanLagMs;
+      this.gauges["eventLoop.lagMs"] = Math.round(meanLagMs * 100) / 100;
+      this.gauges["eventLoop.maxLagMs"] = Math.round(this.elMaxLagMs * 100) / 100;
+      this.elHistogram.reset();
+    }
+
+    // GC gauges
+    this.gauges["gc.totalPauseMs"] = Math.round(this.gcStats.totalPauseMs * 100) / 100;
+    this.gauges["gc.count"] = this.gcStats.count;
+    this.gauges["gc.lastPauseMs"] = Math.round(this.gcStats.lastPauseMs * 100) / 100;
+    this.gauges["gc.maxPauseMs"] = Math.round(this.gcStats.maxPauseMs * 100) / 100;
+
+    return snap;
+  }
+}