@geravant/sinain 1.0.19 → 1.2.0

package/sinain-core/src/trace/trace-store.ts

@@ -0,0 +1,73 @@
+import fs from "node:fs";
+import path from "node:path";
+import type { Trace } from "../types.js";
+import { log, error } from "../log.js";
+
+const TAG = "trace-store";
+
+/**
+ * Persistent JSONL trace log.
+ * Each day gets its own file: ~/.sinain-core/traces/2025-02-03.jsonl
+ *
+ * Format enables:
+ *   cat traces/2025-02-03.jsonl | jq '.metrics.totalLatencyMs'
+ *   Replay in eval harness
+ *   Import into dashboards
+ */
+export class TraceStore {
+  private dir: string;
+  private currentDate = "";
+  private currentStream: fs.WriteStream | null = null;
+
+  constructor(dir: string) {
+    this.dir = dir;
+    try {
+      fs.mkdirSync(dir, { recursive: true });
+    } catch (err: any) {
+      if (err.code !== "EEXIST") {
+        error(TAG, "failed to create trace dir:", err.message);
+      }
+    }
+  }
+
+  /** Append a trace to today's JSONL file. */
+  append(trace: Trace): void {
+    const date = new Date().toISOString().slice(0, 10);
+
+    // Rotate file on date change
+    if (date !== this.currentDate) {
+      if (this.currentStream) {
+        this.currentStream.end();
+      }
+      const filePath = path.join(this.dir, `${date}.jsonl`);
+      this.currentStream = fs.createWriteStream(filePath, { flags: "a" });
+      this.currentDate = date;
+      log(TAG, `writing to ${filePath}`);
+    }
+
+    if (this.currentStream) {
+      this.currentStream.write(JSON.stringify(trace) + "\n");
+    }
+  }
+
+  /** Read all traces for a given date. */
+  queryDay(date: string): Trace[] {
+    const filePath = path.join(this.dir, `${date}.jsonl`);
+    try {
+      const content = fs.readFileSync(filePath, "utf-8");
+      return content.split("\n")
+        .filter(line => line.trim())
+        .map(line => JSON.parse(line) as Trace);
+    } catch {
+      return [];
+    }
+  }
+
+  /** Close the write stream. */
+  destroy(): void {
+    if (this.currentStream) {
+      this.currentStream.end();
+      this.currentStream = null;
+    }
+  }
+}

package/sinain-core/src/trace/tracer.ts

@@ -0,0 +1,94 @@
+import crypto from "node:crypto";
+import type { Trace, Span, TraceMetrics, MetricsSummary } from "../types.js";
+import type { TraceContext } from "../agent/loop.js";
+
+/**
+ * Structured trace recording for every agent tick.
+ * Each tick produces a Trace with nested Spans and aggregated TraceMetrics.
+ *
+ * Traces are kept in a rolling buffer (max 500) and exposed via GET /traces.
+ * Optionally persisted to JSONL via TraceStore.
+ */
+export class Tracer {
+  private traces: Trace[] = [];
+  private maxTraces = 500;
+
+  /** Start a new trace for a tick. Returns a TraceContext for recording spans. */
+  startTrace(tickId: number): TraceContext {
+    const trace: Trace = {
+      traceId: crypto.randomUUID(),
+      tickId,
+      ts: Date.now(),
+      spans: [],
+      metrics: {} as TraceMetrics,
+    };
+
+    let currentSpanStart = 0;
+    let currentSpanName = "";
+
+    const ctx: TraceContext = {
+      startSpan(name: string): void {
+        currentSpanName = name;
+        currentSpanStart = Date.now();
+      },
+
+      endSpan(attrs?: Record<string, unknown>): void {
+        if (!currentSpanName) return;
+        const span: Span = {
+          name: currentSpanName,
+          startTs: currentSpanStart,
+          endTs: Date.now(),
+          attributes: attrs || {},
+          status: attrs?.status === "error" ? "error" : "ok",
+          error: attrs?.error as string | undefined,
+        };
+        trace.spans.push(span);
+        currentSpanName = "";
+      },
+
+      finish(metrics: Record<string, unknown>): void {
+        trace.metrics = metrics as unknown as TraceMetrics;
+        this._commit();
+      },
+
+      _commit: () => {
+        this.traces.push(trace);
+        if (this.traces.length > this.maxTraces) {
+          this.traces.shift();
+        }
+      },
+    } as TraceContext & { _commit: () => void };
+
+    return ctx;
+  }
+
+  /** Get traces after a given tickId, with limit. */
+  getTraces(afterTickId = 0, limit = 50): Trace[] {
+    return this.traces
+      .filter(t => t.tickId > afterTickId)
+      .slice(-limit);
+  }
+
+  /** Compute summary metrics over all stored traces. */
+  getMetricsSummary(): MetricsSummary {
+    if (this.traces.length === 0) {
+      return { count: 0, latencyP50: 0, latencyP95: 0, avgCostPerTick: 0, totalCost: 0 };
+    }
+
+    const latencies = this.traces
+      .map(t => t.metrics.totalLatencyMs)
+      .filter(l => l > 0)
+      .sort((a, b) => a - b);
+
+    const costs = this.traces.map(t => t.metrics.llmCost);
+    const totalCost = costs.reduce((a, b) => a + b, 0);
+
+    return {
+      count: this.traces.length,
+      latencyP50: latencies[Math.floor(latencies.length / 2)] || 0,
+      latencyP95: latencies[Math.floor(latencies.length * 0.95)] || 0,
+      avgCostPerTick: totalCost / this.traces.length,
+      totalCost,
+    };
+  }
+}

package/sinain-core/src/types.ts

@@ -0,0 +1,427 @@
+// ── Wire protocol types (overlay ↔ sinain-core) ──
+
+export type Priority = "normal" | "high" | "urgent";
+export type FeedChannel = "stream" | "agent";
+
+/** sinain-core → Overlay: feed item */
+export interface FeedMessage {
+  type: "feed";
+  text: string;
+  priority: Priority;
+  ts: number;
+  channel: FeedChannel;
+}
+
+/** sinain-core → Overlay: status update */
+export interface StatusMessage {
+  type: "status";
+  audio: string;
+  mic: string;
+  screen: string;
+  connection: string;
+}
+
+/** sinain-core → Overlay: heartbeat ping */
+export interface PingMessage {
+  type: "ping";
+  ts: number;
+}
+
+/** sinain-core → Overlay: spawn task lifecycle update */
+export type SpawnTaskStatus = "spawned" | "polling" | "completed" | "failed" | "timeout";
+
+export interface SpawnTaskMessage {
+  type: "spawn_task";
+  taskId: string;
+  label: string;
+  status: SpawnTaskStatus;
+  startedAt: number;
+  completedAt?: number;
+  resultPreview?: string;
+}
+
+/** Overlay → sinain-core: user typed a message */
+export interface UserMessage {
+  type: "message";
+  text: string;
+}
+
+/** Overlay → sinain-core: command (toggle_audio, toggle_screen, etc.) */
+export interface CommandMessage {
+  type: "command";
+  action: string;
+}
+
+/** Overlay → sinain-core: heartbeat pong */
+export interface PongMessage {
+  type: "pong";
+  ts: number;
+}
+
+/** Overlay → sinain-core: process profiling metrics */
+export interface ProfilingMessage {
+  type: "profiling";
+  rssMb: number;
+  uptimeS: number;
+  ts: number;
+}
+
+export type OutboundMessage = FeedMessage | StatusMessage | PingMessage | SpawnTaskMessage;
+export type InboundMessage = UserMessage | CommandMessage | PongMessage | ProfilingMessage;
+
+// ── Feed buffer types ──
+
+export interface FeedItem {
+  id: number;
+  text: string;
+  priority: Priority;
+  ts: number;
+  source: "audio" | "sense" | "agent" | "openclaw" | "system";
+  channel: FeedChannel;
+  audioSource?: AudioSourceTag;
+}
+
+// ── Sense buffer types ──
+
+export interface SenseEvent {
+  id: number;
+  type: "text" | "visual" | "context";
+  ts: number;
+  ocr: string;
+  imageData?: string;   // base64 JPEG thumbnail (stripped from older events)
+  imageBbox?: number[]; // [x, y, w, h] of the captured region
+  meta: {
+    ssim: number;
+    app: string;
+    windowTitle?: string;
+    screen: number;
+  };
+  receivedAt: number;
+}
+
+// ── Audio pipeline types ──
+
+export type AudioSourceTag = "system" | "mic";
+
+export interface AudioPipelineConfig {
+  device: string;
+  sampleRate: number;
+  channels: number;
+  chunkDurationMs: number;
+  vadEnabled: boolean;
+  vadThreshold: number;
+  captureCommand: "sox" | "ffmpeg" | "screencapturekit";
+  autoStart: boolean;
+  gainDb: number;
+}
+
+export interface TraitConfig {
+  enabled: boolean;
+  configPath: string;   // path to ~/.sinain/traits.json
+  entropyHigh: boolean; // Phase 2: boosts entropy roll to 15%
+  logDir: string;       // path to ~/.sinain-core/traits/
+}
+
+export interface TraitLogEntry {
+  ts: string;
+  tickId: number;
+  enabled: boolean;
+  voice: string;
+  voice_stat: number;
+  voice_confidence: number;
+  activation_scores: Record<string, number>;
+  context_app: string;
+  hud_length: number;
+  synthesis: boolean;
+}
+
+
+export interface AudioChunk {
+  buffer: Buffer;
+  source: string;
+  ts: number;
+  durationMs: number;
+  energy: number;
+  audioSource: AudioSourceTag;
+}
+
+// ── Transcription types ──
+
+export type TranscriptionBackend = "openrouter" | "local";
+
+export interface TranscriptionConfig {
+  backend: TranscriptionBackend;
+  openrouterApiKey: string;
+  geminiModel: string;
+  language: string;
+  /** Local whisper-cpp settings (only used when backend=local) */
+  local: {
+    bin: string;
+    modelPath: string;
+    language: string;
+    timeoutMs: number;
+  };
+}
+
+export interface TranscriptResult {
+  text: string;
+  source: "openrouter" | "whisper";
+  refined: boolean;
+  confidence: number;
+  ts: number;
+  audioSource: AudioSourceTag;
+}
+
+// ── Recorder types ──
+
+export interface RecordCommand {
+  command: "start" | "stop";
+  label?: string;
+}
+
+export interface RecorderStatus {
+  recording: boolean;
+  label: string | null;
+  startedAt: number | null;
+  segments: number;
+  durationMs: number;
+}
+
+export interface StopResult {
+  title: string;
+  transcript: string;
+  segments: number;
+  durationS: number;
+}
+
+// ── Agent types ──
+
+export type EscalationMode = "off" | "selective" | "focus" | "rich";
+export type ContextRichness = "lean" | "standard" | "rich";
+
+export interface AgentConfig {
+  enabled: boolean;
+  model: string;
+  visionModel: string;
+  visionEnabled: boolean;
+  openrouterApiKey: string;
+  maxTokens: number;
+  temperature: number;
+  pushToFeed: boolean;
+  debounceMs: number;
+  maxIntervalMs: number;
+  cooldownMs: number;
+  maxAgeMs: number;
+  fallbackModels: string[];
+  /** Maximum entries to keep in agent history buffer (default: 50) */
+  historyLimit: number;
+}
+
+export interface AgentResult {
+  hud: string;
+  digest: string;
+  record?: RecordCommand;
+  task?: string;
+  latencyMs: number;
+  tokensIn: number;
+  tokensOut: number;
+  model: string;
+  parsedOk: boolean;
+  voice?: string;
+  voice_stat?: number;
+  voice_confidence?: number;
+}
+
+export interface AgentEntry extends AgentResult {
+  id: number;
+  ts: number;
+  pushed: boolean;
+  contextFreshnessMs: number | null;
+  context: {
+    currentApp: string;
+    appHistory: string[];
+    audioCount: number;
+    screenCount: number;
+  };
+}
+
+// ── Context window ──
+
+export interface RichnessPreset {
+  maxScreenEvents: number;
+  maxAudioEntries: number;
+  maxOcrChars: number;
+  maxTranscriptChars: number;
+  maxImages: number;
+}
+
+export interface ContextWindow {
+  audio: FeedItem[];
+  screen: SenseEvent[];
+  images?: { data: string; app: string; ts: number }[];
+  currentApp: string;
+  appHistory: { app: string; ts: number }[];
+  audioCount: number;
+  screenCount: number;
+  windowMs: number;
+  newestEventTs: number;
+  preset: RichnessPreset;
+}
+
+// ── Escalation types ──
+
+export type EscalationTransport = "ws" | "http" | "auto";
+
+export interface EscalationConfig {
+  mode: EscalationMode;
+  cooldownMs: number;
+  staleMs: number;  // force escalation after this many ms of silence (0 = disabled)
+  transport: EscalationTransport;
+}
+
+export interface OpenClawConfig {
+  gatewayWsUrl: string;
+  gatewayToken: string;
+  hookUrl: string;
+  hookToken: string;
+  sessionKey: string;
+  phase1TimeoutMs: number;   // default: 30_000
+  phase2TimeoutMs: number;   // default: 120_000
+  pingIntervalMs: number;    // default: 30_000
+}
+
+// ── Trace types ──
+
+export interface Trace {
+  traceId: string;
+  tickId: number;
+  ts: number;
+  spans: Span[];
+  metrics: TraceMetrics;
+}
+
+export interface Span {
+  name: string;
+  startTs: number;
+  endTs: number;
+  attributes: Record<string, unknown>;
+  status: "ok" | "error";
+  error?: string;
+}
+
+export interface TraceMetrics {
+  totalLatencyMs: number;
+  llmLatencyMs: number;
+  llmInputTokens: number;
+  llmOutputTokens: number;
+  llmCost: number;
+  escalated: boolean;
+  escalationScore: number;
+  escalationLatencyMs?: number;
+  contextScreenEvents: number;
+  contextAudioEntries: number;
+  contextRichness: ContextRichness;
+  digestLength: number;
+  hudChanged: boolean;
+}
+
+export interface MetricsSummary {
+  count: number;
+  latencyP50: number;
+  latencyP95: number;
+  avgCostPerTick: number;
+  totalCost: number;
+}
+
+// ── Bridge state (overlay connection) ──
+
+export interface BridgeState {
+  audio: "active" | "muted";
+  mic: "active" | "muted";
+  screen: "active" | "off";
+  traits?: "active" | "off";
+  connection: "connected" | "disconnected" | "connecting";
+}
+
+// ── Learning / feedback types ──
+
+export interface FeedbackSignals {
+  errorCleared: boolean | null;
+  noReEscalation: boolean | null;
+  dwellTimeMs: number | null;
+  quickAppSwitch: boolean | null;
+  compositeScore: number;           // -1.0 to 1.0
+}
+
+export interface FeedbackRecord {
+  id: string;                        // UUID
+  ts: number;
+  tickId: number;
+  // Input
+  digest: string;
+  hud: string;
+  currentApp: string;
+  escalationScore: number;
+  escalationReasons: string[];
+  codingContext: boolean;
+  // Output
+  escalationMessage: string;         // trimmed to 2KB
+  openclawResponse: string;          // trimmed to 2KB
+  responseLatencyMs: number;
+  // Feedback signals (filled async)
+  signals: FeedbackSignals;
+  tags: string[];
+}
+
+export interface LearningConfig {
+  enabled: boolean;
+  feedbackDir: string;
+  retentionDays: number;
+}
+
+// ── Privacy matrix types ──
+
+export type PrivacyLevel = "full" | "redacted" | "summary" | "none";
+export type PrivacyDest = "local_buffer" | "local_llm" | "triple_store" | "openrouter" | "agent_gateway";
+
+export interface PrivacyRow {
+  local_buffer: PrivacyLevel;
+  local_llm: PrivacyLevel;
+  triple_store: PrivacyLevel;
+  openrouter: PrivacyLevel;
+  agent_gateway: PrivacyLevel;
+}
+
+export interface PrivacyMatrix {
+  audio_transcript: PrivacyRow;
+  screen_ocr: PrivacyRow;
+  screen_images: PrivacyRow;
+  window_titles: PrivacyRow;
+  credentials: PrivacyRow;
+  metadata: PrivacyRow;
+}
+
+export interface PrivacyConfig {
+  mode: string;   // "off" | "standard" | "strict" | "paranoid" | "custom"
+  matrix: PrivacyMatrix;
+}
+
+// ── Full core config ──
+
+export interface CoreConfig {
+  port: number;
+  audioConfig: AudioPipelineConfig;
+  audioAltDevice: string;
+  micConfig: AudioPipelineConfig;
+  micEnabled: boolean;
+  transcriptionConfig: TranscriptionConfig;
+  agentConfig: AgentConfig;
+  escalationConfig: EscalationConfig;
+  openclawConfig: OpenClawConfig;
+  situationMdPath: string;
+  traceEnabled: boolean;
+  traceDir: string;
+  learningConfig: LearningConfig;
+  traitConfig: TraitConfig;
+  privacyConfig: PrivacyConfig;
+}

package/sinain-core/src/util/dedup.ts

@@ -0,0 +1,48 @@
+/**
+ * Bigram-based text deduplication for audio transcripts.
+ * Prevents repetitive audio (music, TV, looping sounds) from
+ * filling the context buffer with near-identical entries.
+ */
+
+/** Extract character bigrams from text, lowercased. */
+function bigrams(text: string): Set<string> {
+  const s = text.toLowerCase().trim();
+  const set = new Set<string>();
+  for (let i = 0; i < s.length - 1; i++) {
+    set.add(s.slice(i, i + 2));
+  }
+  return set;
+}
+
+/** Dice coefficient similarity between two strings (0.0–1.0). */
+export function bigramSimilarity(a: string, b: string): number {
+  if (a === b) return 1.0;
+  const ba = bigrams(a);
+  const bb = bigrams(b);
+  if (ba.size === 0 && bb.size === 0) return 1.0;
+  if (ba.size === 0 || bb.size === 0) return 0.0;
+  let intersection = 0;
+  for (const bg of ba) {
+    if (bb.has(bg)) intersection++;
+  }
+  return (2 * intersection) / (ba.size + bb.size);
+}
+
+/**
+ * Check if a transcript is a near-duplicate of recent transcripts.
+ * Returns true if similarity > threshold against any of the recent entries.
+ */
+export function isDuplicateTranscript(
+  text: string,
+  recentTexts: string[],
+  threshold = 0.80,
+): boolean {
+  const trimmed = text.trim();
+  if (trimmed.length < 5) return false; // Don't dedup very short text
+  for (const recent of recentTexts) {
+    if (bigramSimilarity(trimmed, recent) > threshold) {
+      return true;
+    }
+  }
+  return false;
+}