@geravant/sinain 1.0.19 → 1.2.0

package/sense_client/tests/test_stream1_optimizations.py

@@ -0,0 +1,234 @@
+"""Tests for Stream 1 optimizations: adaptive cooldown, adaptive SSIM,
+parallel OCR, skip image for text events, latency instrumentation."""
+
+import time
+import unittest
+from unittest.mock import MagicMock, patch
+
+from sense_client.change_detector import ChangeDetector, ChangeResult
+from sense_client.config import load_config, DEFAULTS
+from sense_client.gate import DecisionGate, SenseEvent, SenseMeta
+from sense_client.ocr import OCRResult
+from sense_client.sender import SenseSender
+
+
+class TestConfig(unittest.TestCase):
+    """Test that adaptiveCooldownMs is present in defaults."""
+
+    def test_defaults_has_adaptive_cooldown(self):
+        config = load_config(None)
+        self.assertIn("adaptiveCooldownMs", config["gate"])
+        self.assertEqual(config["gate"]["adaptiveCooldownMs"], 2000)
+
+    def test_defaults_cooldown_unchanged(self):
+        config = load_config(None)
+        self.assertEqual(config["gate"]["cooldownMs"], 5000)
+
+
+class TestChangeDetectorSetThreshold(unittest.TestCase):
+    """Test dynamic SSIM threshold adjustment."""
+
+    def test_set_threshold(self):
+        det = ChangeDetector(threshold=0.92)
+        self.assertEqual(det.threshold, 0.92)
+        det.set_threshold(0.85)
+        self.assertEqual(det.threshold, 0.85)
+        det.set_threshold(0.95)
+        self.assertEqual(det.threshold, 0.95)
+
+
+class TestAdaptiveCooldown(unittest.TestCase):
+    """Test that DecisionGate uses shorter cooldown after app switch."""
+
+    def _make_change(self, ssim=0.80):
+        return ChangeResult(
+            ssim_score=ssim,
+            diff_image=MagicMock(),
+            contours=[],
+            bbox=(0, 0, 100, 100),
+        )
+
+    def _make_ocr(self, text=""):
+        return OCRResult(text=text, confidence=90, word_count=len(text.split()))
+
+    def test_init_has_adaptive_params(self):
+        gate = DecisionGate(adaptive_cooldown_ms=2000)
+        self.assertEqual(gate.adaptive_cooldown_ms, 2000)
+        self.assertEqual(gate.last_app_change_ts, 0)
+
+    def test_app_change_sets_timestamp(self):
+        gate = DecisionGate(cooldown_ms=5000, adaptive_cooldown_ms=2000,
+                            context_cooldown_ms=0)
+        change = self._make_change()
+        ocr = self._make_ocr()
+
+        # First call with app_changed — should set last_app_change_ts
+        event = gate.classify(change, ocr, app_changed=True)
+        self.assertIsNotNone(event)
+        self.assertEqual(event.type, "context")
+        self.assertGreater(gate.last_app_change_ts, 0)
+
+    def test_adaptive_cooldown_shorter_after_app_switch(self):
+        gate = DecisionGate(cooldown_ms=5000, adaptive_cooldown_ms=2000,
+                            context_cooldown_ms=0)
+        long_text = "This is a sufficiently long OCR text for testing purposes here"
+        change = self._make_change(ssim=0.80)
+        ocr = self._make_ocr(long_text)
+
+        # Trigger app change to set last_app_change_ts
+        gate.classify(change, ocr, app_changed=True)
+
+        # Immediately after: should use 2s adaptive cooldown
+        # Within 2s window, should be gated
+        event = gate.classify(change, ocr, app_changed=False)
+        self.assertIsNone(event)  # within 2s cooldown
+
+        # Simulate 2.1s passing by adjusting timestamps
+        gate.last_send_ts -= 2100  # pretend 2.1s have passed
+        gate.last_app_change_ts = time.time() * 1000 - 1000  # app change 1s ago (within 10s)
+
+        event = gate.classify(change, self._make_ocr(long_text + " extra"), app_changed=False)
+        self.assertIsNotNone(event)
+        self.assertEqual(event.type, "text")
+
+    def test_normal_cooldown_when_no_recent_app_change(self):
+        gate = DecisionGate(cooldown_ms=5000, adaptive_cooldown_ms=2000,
+                            context_cooldown_ms=10000)
+        long_text = "This is a sufficiently long OCR text for testing purposes here"
+        change = self._make_change(ssim=0.80)
+        ocr = self._make_ocr(long_text)
+
+        # No app change ever — last_app_change_ts is 0
+        # Send an initial event
+        event = gate.classify(change, ocr, app_changed=False)
+        self.assertIsNotNone(event)
+
+        # Try again after 3s (> adaptive but < normal cooldown)
+        gate.last_send_ts -= 3000
+        event = gate.classify(change, self._make_ocr(long_text + " more"), app_changed=False)
+        # Should be gated because no recent app change → uses 5s cooldown
+        self.assertIsNone(event)
+
+
+class TestSkipImageForTextEvents(unittest.TestCase):
+    """Verify that text events don't get image data packaged."""
+
+    def test_text_event_has_no_roi(self):
+        """Simulate what __main__.py does: text events skip package_roi."""
+        event = SenseEvent(type="text", ts=time.time() * 1000, ocr="some text")
+        # The logic in __main__.py:
+        # if event.type == "context": package_full_frame
+        # elif event.type == "visual" and rois: package_roi
+        # text events: nothing
+        if event.type == "context":
+            event.roi = {"data": "base64..."}
+        elif event.type == "visual":
+            event.roi = {"data": "base64..."}
+        # text: no roi set
+        self.assertIsNone(event.roi)
+
+    def test_visual_event_gets_roi(self):
+        event = SenseEvent(type="visual", ts=time.time() * 1000, ocr="")
+        rois = [MagicMock()]
+        if event.type == "visual" and rois:
+            event.roi = {"data": "base64...", "bbox": [0, 0, 100, 100]}
+        self.assertIsNotNone(event.roi)
+
+
+class TestSenderLatencyTracking(unittest.TestCase):
+    """Test that SenseSender tracks send latencies."""
+
+    def test_init_has_latency_fields(self):
+        sender = SenseSender()
+        self.assertIsInstance(sender._latencies, list)
+        self.assertEqual(len(sender._latencies), 0)
+        self.assertIsInstance(sender._last_stats_ts, float)
+
+    @patch("sense_client.sender.requests.post")
+    def test_send_tracks_latency(self, mock_post):
+        mock_resp = MagicMock()
+        mock_resp.status_code = 200
+        mock_post.return_value = mock_resp
+
+        sender = SenseSender(url="http://localhost:18791")
+        event = SenseEvent(type="text", ts=time.time() * 1000, ocr="test",
+                           meta=SenseMeta(ssim=0.9, app="test"))
+
+        ok = sender.send(event)
+        self.assertTrue(ok)
+        self.assertEqual(len(sender._latencies), 1)
+        self.assertGreater(sender._latencies[0], 0)
+
+    @patch("sense_client.sender.requests.post")
+    def test_stats_logged_after_interval(self, mock_post):
+        mock_resp = MagicMock()
+        mock_resp.status_code = 200
+        mock_post.return_value = mock_resp
+
+        sender = SenseSender(url="http://localhost:18791")
+        sender._last_stats_ts = time.time() - 61  # pretend 61s ago
+
+        event = SenseEvent(type="text", ts=time.time() * 1000, ocr="test",
+                           meta=SenseMeta(ssim=0.9, app="test"))
+
+        with patch("builtins.print") as mock_print:
+            sender.send(event)
+            # Should have logged stats
+            calls = [str(c) for c in mock_print.call_args_list]
+            stats_logged = any("[sender] relay latency" in c for c in calls)
+            self.assertTrue(stats_logged, f"Expected latency stats log, got: {calls}")
+
+    @patch("sense_client.sender.requests.post")
+    def test_stats_not_logged_before_interval(self, mock_post):
+        mock_resp = MagicMock()
+        mock_resp.status_code = 200
+        mock_post.return_value = mock_resp
+
+        sender = SenseSender(url="http://localhost:18791")
+        # _last_stats_ts defaults to now, so interval not elapsed
+
+        event = SenseEvent(type="text", ts=time.time() * 1000, ocr="test",
+                           meta=SenseMeta(ssim=0.9, app="test"))
+
+        with patch("builtins.print") as mock_print:
+            sender.send(event)
+            calls = [str(c) for c in mock_print.call_args_list]
+            stats_logged = any("[sender] relay latency" in c for c in calls)
+            self.assertFalse(stats_logged)
+
+
+class TestParallelOCR(unittest.TestCase):
+    """Test parallel OCR logic from __main__.py."""
+
+    def test_single_roi_no_threadpool(self):
+        """With 1 ROI, OCR is called directly (no ThreadPoolExecutor)."""
+        mock_ocr = MagicMock()
+        mock_ocr.extract.return_value = OCRResult(text="hello world test text here", confidence=90, word_count=5)
+
+        roi = MagicMock()
+        rois = [roi]
+
+        # Simulate single-ROI path
+        if len(rois) == 1:
+            result = mock_ocr.extract(rois[0].image)
+        else:
+            result = None
+
+        self.assertIsNotNone(result)
+        self.assertEqual(result.text, "hello world test text here")
+        mock_ocr.extract.assert_called_once()
+
+    def test_multiple_rois_picks_best(self):
+        """With multiple ROIs, pick the result with most text."""
+        results = [
+            OCRResult(text="short", confidence=90, word_count=1),
+            OCRResult(text="this is the longest text result here", confidence=85, word_count=7),
+            OCRResult(text="medium text", confidence=88, word_count=2),
+        ]
+
+        best = max(results, key=lambda r: len(r.text))
+        self.assertEqual(best.text, "this is the longest text result here")
+
+
+if __name__ == "__main__":
+    unittest.main()

package/setup-overlay.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+// sinain setup-overlay — clone and build the Flutter overlay app
+
+import { execSync } from "child_process";
+import fs from "fs";
+import path from "path";
+import os from "os";
+
+const HOME = os.homedir();
+const SINAIN_DIR = path.join(HOME, ".sinain");
+const REPO_DIR = path.join(SINAIN_DIR, "overlay-repo");
+const OVERLAY_LINK = path.join(SINAIN_DIR, "overlay");
+
+const BOLD  = "\x1b[1m";
+const GREEN = "\x1b[32m";
+const RED   = "\x1b[31m";
+const RESET = "\x1b[0m";
+
+function log(msg) { console.log(`${BOLD}[setup-overlay]${RESET} ${msg}`); }
+function ok(msg)  { console.log(`${BOLD}[setup-overlay]${RESET} ${GREEN}✓${RESET} ${msg}`); }
+function fail(msg) { console.error(`${BOLD}[setup-overlay]${RESET} ${RED}✗${RESET} ${msg}`); process.exit(1); }
+
+// Check flutter
+try {
+  execSync("which flutter", { stdio: "pipe" });
+} catch {
+  fail("flutter not found. Install it: https://docs.flutter.dev/get-started/install");
+}
+
+const flutterVer = execSync("flutter --version 2>&1", { encoding: "utf-8" }).split("\n")[0];
+ok(`flutter: ${flutterVer}`);
+
+fs.mkdirSync(SINAIN_DIR, { recursive: true });
+
+// Clone or update
+if (fs.existsSync(path.join(REPO_DIR, ".git"))) {
+  log("Updating existing overlay repo...");
+  execSync("git pull --ff-only", { cwd: REPO_DIR, stdio: "inherit" });
+  ok("Repository updated");
+} else {
+  log("Cloning overlay (sparse checkout — only overlay/ directory)...");
+  if (fs.existsSync(REPO_DIR)) {
+    fs.rmSync(REPO_DIR, { recursive: true, force: true });
+  }
+  execSync(
+    `git clone --depth 1 --filter=blob:none --sparse https://github.com/anthillnet/sinain-hud.git "${REPO_DIR}"`,
+    { stdio: "inherit" }
+  );
+  execSync("git sparse-checkout set overlay", { cwd: REPO_DIR, stdio: "inherit" });
+  ok("Repository cloned");
+}
+
+// Build
+const overlayDir = path.join(REPO_DIR, "overlay");
+if (!fs.existsSync(path.join(overlayDir, "pubspec.yaml"))) {
+  fail("overlay/pubspec.yaml not found — sparse checkout may have failed");
+}
+
+log("Installing Flutter dependencies...");
+execSync("flutter pub get", { cwd: overlayDir, stdio: "inherit" });
+
+log("Building overlay (this may take a few minutes)...");
+execSync("flutter build macos", { cwd: overlayDir, stdio: "inherit" });
+ok("Overlay built successfully");
+
+// Symlink ~/.sinain/overlay → the overlay source dir
+try {
+  if (fs.existsSync(OVERLAY_LINK)) {
+    fs.unlinkSync(OVERLAY_LINK);
+  }
+  fs.symlinkSync(overlayDir, OVERLAY_LINK);
+  ok(`Symlinked: ${OVERLAY_LINK} → ${overlayDir}`);
+} catch (e) {
+  // Symlink may fail on some systems — fall back to just noting the path
+  log(`Overlay built at: ${overlayDir}`);
+}
+
+console.log(`
+${GREEN}✓${RESET} Overlay setup complete!
+  The overlay will auto-start with: ${BOLD}sinain start${RESET}
+  Or run manually: cd ${overlayDir} && flutter run -d macos
+`);

package/sinain-agent/.env.example

@@ -0,0 +1,17 @@
+# sinain-agent configuration
+# Copy to .env and customize:  cp .env.example .env
+
+# ── Agent ──
+SINAIN_AGENT=claude                # claude | codex | junie | goose | aider | <custom command>
+                                   # MCP agents (claude, codex, junie, goose) call sinain tools directly
+                                   # Pipe agents (aider, custom) receive escalation text on stdin
+
+# ── Core connection ──
+SINAIN_CORE_URL=http://localhost:9500
+
+# ── Timing ──
+SINAIN_POLL_INTERVAL=5             # seconds between escalation polls
+SINAIN_HEARTBEAT_INTERVAL=900      # seconds between heartbeat ticks (15 min)
+
+# ── Workspace ──
+SINAIN_WORKSPACE=~/.openclaw/workspace  # knowledge files, curation scripts, playbook

package/sinain-agent/CLAUDE.md

@@ -0,0 +1,87 @@
+# Sinain HUD Agent
+
+You are a coding assistant connected to sinain-hud, a privacy-first AI overlay for macOS. You observe the user's screen and audio context via the HUD system and provide real-time advice displayed on an invisible overlay.
+
+## Your Tools
+
+You have MCP tools from `sinain-mcp-server`:
+- `sinain_get_escalation` — poll for pending escalation (call every 3-5 seconds in your main loop)
+- `sinain_respond` — submit your response to an escalation (appears on user's HUD)
+- `sinain_get_context` — get the full context window (screen OCR, audio transcripts, app history)
+- `sinain_get_digest` — get the current agent analysis summary
+- `sinain_get_feedback` — get feedback signals from recent escalations
+- `sinain_post_feed` — push an arbitrary message to the HUD
+- `sinain_health` — check system health
+- `sinain_get_knowledge` — get the portable knowledge document (playbook + long-term facts + sessions)
+- `sinain_knowledge_query` — query the knowledge graph for facts about specific entities/domains
+- `sinain_distill_session` — explicitly distill the current session into knowledge updates
+- `sinain_heartbeat_tick` — run the heartbeat pipeline (git backup, signals, distillation, insights)
+- `sinain_module_guidance` — get active module guidance
+
+## Main Loop
+
+Your primary job is an escalation response loop:
+
+1. Call `sinain_get_escalation` to check for pending escalations
+2. If an escalation is present:
+   a. Read the escalation message carefully — it contains screen OCR, audio transcripts, app context, and the local agent's digest
+   b. Optionally call `sinain_get_knowledge` to read the knowledge document, or `sinain_knowledge_query` with specific entities to enrich your response
+   c. Optionally call `sinain_module_guidance` to get active module instructions
+   d. Craft a response and call `sinain_respond` with the escalation ID and your response
+3. If no escalation is pending, wait a few seconds and poll again
+4. Every 15 minutes, run `sinain_heartbeat_tick` for curation maintenance
+
+## Response Guidelines
+
+When responding to escalations:
+
+- **5-10 sentences** — concise but substantive
+- **Address errors first** — if the context shows errors, stack traces, or failures, diagnose and suggest fixes
+- **Reference specific context** — quote screen text or audio when relevant ("I see you have a TypeError on line 42...")
+- **Coding context** — if the user is in an IDE or coding platform, focus on code-level help (fixes, patterns, suggestions). Max 4000 chars.
+- **Non-coding context** — share insights, connections, tips relevant to what's on screen. Max 3000 chars.
+- **Never NO_REPLY** — always provide value. If context is minimal, share a relevant insight or tech joke.
+- **Never describe what the user is doing** — they can see their own screen. Add value, don't narrate.
+
+## Heartbeat Cycle (every 15 minutes)
+
+1. Call `sinain_heartbeat_tick` with a brief session summary
+2. The tool runs the full pipeline automatically:
+   - Git backup of memory directory
+   - Signal analysis (detects opportunities from session patterns)
+   - **Session distillation** — fetches new feed items from sinain-core, distills patterns/learnings
+   - **Knowledge integration** — updates playbook (working memory) and knowledge graph (long-term memory)
+   - Insight synthesis (generates suggestions from accumulated patterns)
+3. If the result contains a suggestion or insight, post it to the HUD via `sinain_post_feed`
+4. Optionally call `sinain_get_knowledge` to review the portable knowledge document
+5. Optionally call `sinain_get_feedback` to review recent escalation scores
+
+## Spawning Background Tasks
+
+When an escalation suggests deeper research would help:
+
+1. **Respond first** — the user sees your immediate HUD response
+2. Spawn a background research task (use your native subprocess/agent capabilities)
+3. On next escalation or heartbeat, check for completed task results
+4. Integrate findings into your response or playbook
+
+Rules:
+- Max 2 spawns per hour
+- Never duplicate a recent task
+- Keep spawned tasks focused and time-bounded
+
+## Files You Manage
+
+Your working memory lives at `~/.openclaw/workspace/memory/`:
+- `sinain-playbook.md` — your effective playbook (working memory, updated by knowledge integrator)
+- `knowledge-graph.db` — long-term knowledge graph (SQLite, curated facts with confidence tracking)
+- `sinain-knowledge.md` — portable knowledge document (<8KB, playbook + top graph facts + recent sessions)
+- `session-digests.jsonl` — session distillation history
+- `distill-state.json` — watermark for what's been distilled
+- `playbook-logs/YYYY-MM-DD.jsonl` — decision logs
+
+## Privacy
+
+The HUD overlay is invisible to screen capture. All content you receive has already been privacy-stripped by sinain-core. Your responses appear only on the ghost overlay — they are never captured in screenshots or recordings.
+
+Never include `<private>` tagged content in your responses — it will be stripped automatically, but avoid echoing it.

package/sinain-agent/mcp-config.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "sinain": {
+      "command": "../sinain-core/node_modules/.bin/tsx",
+      "args": ["../sinain-mcp-server/index.ts"],
+      "env": {
+        "SINAIN_CORE_URL": "http://localhost:9500",
+        "SINAIN_WORKSPACE": "~/.openclaw/workspace"
+      }
+    }
+  }
+}

package/sinain-agent/run.sh

@@ -0,0 +1,248 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Load .env if present (does not override existing env vars)
+if [ -f "$SCRIPT_DIR/.env" ]; then
+  set -a
+  # shellcheck source=/dev/null
+  . "$SCRIPT_DIR/.env"
+  set +a
+fi
+
+MCP_CONFIG="${MCP_CONFIG:-$SCRIPT_DIR/mcp-config.json}"
+CORE_URL="${SINAIN_CORE_URL:-http://localhost:9500}"
+POLL_INTERVAL="${SINAIN_POLL_INTERVAL:-5}"
+HEARTBEAT_INTERVAL="${SINAIN_HEARTBEAT_INTERVAL:-900}" # 15 minutes
+AGENT="${SINAIN_AGENT:-claude}"
+WORKSPACE="${SINAIN_WORKSPACE:-$HOME/.openclaw/workspace}"
+
+# --- Agent profiles ---
+
+# Returns 0 if the selected agent supports MCP tools natively.
+# Junie support is detected at startup (JUNIE_HAS_MCP flag).
+JUNIE_HAS_MCP=false  # set during startup checks
+agent_has_mcp() {
+  case "$AGENT" in
+    claude|codex|goose) return 0 ;;
+    junie) $JUNIE_HAS_MCP ;;
+    *) return 1 ;;
+  esac
+}
+
+# Invoke the selected agent with a prompt. MCP-capable agents get the config
+# so they can call sinain tools directly. Returns text on stdout.
+# Exit code 1 means "agent doesn't support MCP — use pipe mode instead".
+invoke_agent() {
+  local prompt="$1"
+  case "$AGENT" in
+    claude)
+      claude --dangerously-skip-permissions \
+        --mcp-config "$MCP_CONFIG" \
+        --max-turns 5 --output-format text \
+        -p "$prompt" 2>/dev/null
+      ;;
+    codex)
+      codex exec -s danger-full-access \
+        "$prompt" 2>/dev/null
+      ;;
+    junie)
+      if $JUNIE_HAS_MCP; then
+        junie --output-format text \
+          --mcp-location "$JUNIE_MCP_DIR" \
+          --task "$prompt" 2>/dev/null
+      else
+        return 1
+      fi
+      ;;
+    goose)
+      goose run --text "$prompt" \
+        --output-format text \
+        --max-turns 10 2>/dev/null
+      ;;
+    aider)
+      # No MCP support — signal pipe mode
+      return 1
+      ;;
+    *)
+      # Generic pipe mode — treat AGENT value as a command
+      return 1
+      ;;
+  esac
+}
+
+# --- Pipe-mode helpers (for agents without MCP) ---
+
+# JSON-encode stdin for use in curl payloads
+json_encode() {
+  python3 -c 'import sys,json; print(json.dumps(sys.stdin.read()))'
+}
+
+# Post an escalation response via HTTP (used in pipe mode)
+post_response() {
+  local esc_id="$1" response="$2"
+  curl -sf -X POST "$CORE_URL/escalation/respond" \
+    -H 'Content-Type: application/json' \
+    -d "{\"id\":\"$esc_id\",\"response\":$(echo "$response" | json_encode)}" >/dev/null
+}
+
+# Invoke a pipe-mode agent with escalation message text.
+# Some agents take the message as an argument, others via stdin.
+invoke_pipe() {
+  local msg="$1"
+  case "$AGENT" in
+    junie)
+      junie --output-format text --task "$msg" 2>/dev/null
+      ;;
+    aider)
+      aider --yes -m "$msg" 2>/dev/null
+      ;;
+    *)
+      # Generic: pipe message to stdin
+      echo "$msg" | $AGENT 2>/dev/null
+      ;;
+  esac
+}
+
+# --- Startup checks ---
+
+# Verify sinain-core is running
+if ! curl -sf "$CORE_URL/health" > /dev/null 2>&1; then
+  echo "ERROR: sinain-core is not running at $CORE_URL"
+  echo "Start it first: cd sinain-core && npm run dev"
+  exit 1
+fi
+
+# Junie: detect --mcp-location support (must run before agent_has_mcp calls)
+JUNIE_MCP_DIR="$SCRIPT_DIR/.junie-mcp"
+if [ "$AGENT" = "junie" ]; then
+  if junie --help 2>&1 | grep -q "mcp-location"; then
+    JUNIE_HAS_MCP=true
+    mkdir -p "$JUNIE_MCP_DIR"
+    cp "$MCP_CONFIG" "$JUNIE_MCP_DIR/mcp.json"
+  else
+    echo "NOTE: junie $(junie --version 2>&1 | grep -oE '[0-9.]+' | head -1) lacks --mcp-location, using pipe mode"
+    echo "  Upgrade junie for MCP support: brew upgrade junie"
+  fi
+fi
+
+# Verify MCP server dependencies (only needed for MCP agents)
+if agent_has_mcp && [ ! -d "$SCRIPT_DIR/../sinain-mcp-server/node_modules" ]; then
+  echo "Installing sinain-mcp-server dependencies..."
+  (cd "$SCRIPT_DIR/../sinain-mcp-server" && npm install)
+fi
+
+# Codex: auto-register sinain MCP server if not already configured
+if [ "$AGENT" = "codex" ]; then
+  TSX_BIN="$SCRIPT_DIR/../sinain-core/node_modules/.bin/tsx"
+  MCP_ENTRY="$SCRIPT_DIR/../sinain-mcp-server/index.ts"
+  if ! codex mcp get sinain >/dev/null 2>&1; then
+    echo "Registering sinain MCP server with codex..."
+    codex mcp add sinain \
+      --env "SINAIN_CORE_URL=$CORE_URL" \
+      --env "SINAIN_WORKSPACE=$WORKSPACE" \
+      -- "$TSX_BIN" "$MCP_ENTRY"
+  fi
+fi
+
+# Agent mode label
+if agent_has_mcp; then
+  AGENT_MODE="MCP"
+else
+  AGENT_MODE="pipe"
+fi
+
+echo "sinain bare agent started"
+echo "  Agent: $AGENT ($AGENT_MODE)"
+echo "  Core: $CORE_URL"
+echo "  Poll: every ${POLL_INTERVAL}s"
+echo "  Heartbeat: every ${HEARTBEAT_INTERVAL}s"
+echo "  Press Ctrl+C to stop"
+echo ""
+
+LAST_HEARTBEAT=$(date +%s)
+ESCALATION_COUNT=0
+
+cleanup() {
+  echo ""
+  echo "Agent stopped. Escalations handled: $ESCALATION_COUNT"
+  exit 0
+}
+trap cleanup INT TERM
+
+# --- Prompt templates ---
+
+ESC_PROMPT_TEMPLATE='You are the sinain HUD agent. An escalation is pending with ID=%s.
+
+Call sinain_get_escalation to see the full context, then call sinain_respond with the ID and your response.
+
+Response guidelines: 5-10 sentences, address errors first, reference specific screen/audio context, never NO_REPLY. Max 4000 chars for coding context, 3000 otherwise.'
+
+HEARTBEAT_PROMPT='You are the sinain HUD agent. Run the heartbeat cycle:
+1. Call sinain_heartbeat_tick with a brief session summary
+2. If the result contains a suggestion, post it to HUD via sinain_post_feed
+3. Call sinain_get_feedback to review recent scores'
+
+# --- Main loop ---
+
+while true; do
+  # Poll for pending escalation
+  ESC=$(curl -sf "$CORE_URL/escalation/pending" 2>/dev/null || echo '{"ok":false}')
+  ESC_ID=$(echo "$ESC" | python3 -c "import sys,json; d=json.load(sys.stdin); e=d.get('escalation'); print(e['id'] if e else '')" 2>/dev/null || true)
+
+  if [ -n "$ESC_ID" ]; then
+    ESC_MSG=$(echo "$ESC" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['escalation']['message'])" 2>/dev/null)
+    ESC_SCORE=$(echo "$ESC" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['escalation'].get('score','?'))" 2>/dev/null)
+    ESC_CODING=$(echo "$ESC" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['escalation'].get('codingContext',False))" 2>/dev/null)
+
+    echo "[$(date +%H:%M:%S)] Escalation $ESC_ID (score=$ESC_SCORE, coding=$ESC_CODING)"
+
+    if agent_has_mcp; then
+      # MCP path: agent calls sinain tools directly
+      PROMPT=$(printf "$ESC_PROMPT_TEMPLATE" "$ESC_ID")
+      RESPONSE=$(invoke_agent "$PROMPT" || echo "ERROR: $AGENT invocation failed")
+    else
+      # Pipe path: bash handles HTTP, agent just generates text
+      RESPONSE=$(invoke_pipe "$ESC_MSG" || true)
+      if [ -n "$RESPONSE" ]; then
+        post_response "$ESC_ID" "$RESPONSE"
+      else
+        echo "[$(date +%H:%M:%S)] WARNING: $AGENT returned empty response"
+      fi
+    fi
+
+    ESCALATION_COUNT=$((ESCALATION_COUNT + 1))
+    echo "[$(date +%H:%M:%S)] Responded ($ESCALATION_COUNT total): ${RESPONSE:0:120}..."
+    echo ""
+  fi
+
+  # Heartbeat check
+  NOW=$(date +%s)
+  ELAPSED=$((NOW - LAST_HEARTBEAT))
+  if [ "$ELAPSED" -ge "$HEARTBEAT_INTERVAL" ]; then
+    echo "[$(date +%H:%M:%S)] Running heartbeat tick..."
+
+    if agent_has_mcp; then
+      # MCP path: agent runs heartbeat tools
+      invoke_agent "$HEARTBEAT_PROMPT" || true
+    else
+      # Pipe path: run curation scripts directly
+      SCRIPTS_DIR="$WORKSPACE/sinain-memory"
+      MEMORY_DIR="$WORKSPACE/memory"
+      if [ -d "$SCRIPTS_DIR" ]; then
+        python3 "$SCRIPTS_DIR/signal_analyzer.py" --memory-dir "$MEMORY_DIR" 2>/dev/null || true
+        python3 "$SCRIPTS_DIR/playbook_curator.py" --memory-dir "$MEMORY_DIR" 2>/dev/null || true
+        echo "[$(date +%H:%M:%S)] Heartbeat: ran signal_analyzer + playbook_curator"
+      else
+        echo "[$(date +%H:%M:%S)] Heartbeat: skipped (no scripts at $SCRIPTS_DIR)"
+      fi
+    fi
+
+    LAST_HEARTBEAT=$NOW
+    echo "[$(date +%H:%M:%S)] Heartbeat complete"
+    echo ""
+  fi
+
+  sleep "$POLL_INTERVAL"
+done