@geravant/sinain 1.4.0 → 1.5.0

package/cli.js

@@ -162,12 +162,36 @@ async function runSetupWizard() {
   vars.SINAIN_HEARTBEAT_INTERVAL = "900";
   vars.PRIVACY_MODE = "standard";
 
-  // Write
+  // Write — start from .env.example template, patch wizard values in
   fs.mkdirSync(SINAIN_DIR, { recursive: true });
-  const lines = ["# sinain configuration — generated by setup wizard", `# ${new Date().toISOString()}`, ""];
-  for (const [k, v] of Object.entries(vars)) lines.push(`${k}=${v}`);
-  lines.push("");
-  fs.writeFileSync(envPath, lines.join("\n"));
+
+  const PKG_DIR = path.dirname(new URL(import.meta.url).pathname);
+  const examplePath = path.join(PKG_DIR, ".env.example");
+  const siblingExample = path.join(PKG_DIR, "..", ".env.example");
+  let template = "";
+  if (fs.existsSync(examplePath)) {
+    template = fs.readFileSync(examplePath, "utf-8");
+  } else if (fs.existsSync(siblingExample)) {
+    template = fs.readFileSync(siblingExample, "utf-8");
+  }
+
+  if (template) {
+    for (const [k, v] of Object.entries(vars)) {
+      const regex = new RegExp(`^#?\\s*${k}=.*$`, "m");
+      if (regex.test(template)) {
+        template = template.replace(regex, `${k}=${v}`);
+      } else {
+        template += `\n${k}=${v}`;
+      }
+    }
+    template = `# Generated by sinain setup wizard — ${new Date().toISOString()}\n${template}`;
+    fs.writeFileSync(envPath, template);
+  } else {
+    const lines = ["# sinain configuration — generated by setup wizard", `# ${new Date().toISOString()}`, ""];
+    for (const [k, v] of Object.entries(vars)) lines.push(`${k}=${v}`);
+    lines.push("");
+    fs.writeFileSync(envPath, lines.join("\n"));
+  }
 
   rl.close();
   console.log(`\n  ${GREEN}✓${RESET} Config written to ${envPath}\n`);

package/launcher.js

@@ -409,17 +409,48 @@ async function setupWizard(envPath) {
   vars.SINAIN_HEARTBEAT_INTERVAL = "900";
   vars.PRIVACY_MODE = "standard";
 
-  // Write .env
+  // Write .env — start from .env.example template, patch wizard values in
   fs.mkdirSync(path.dirname(envPath), { recursive: true });
-  const lines = [];
-  lines.push("# sinain configuration — generated by setup wizard");
-  lines.push(`# ${new Date().toISOString()}`);
-  lines.push("");
-  for (const [key, val] of Object.entries(vars)) {
-    lines.push(`${key}=${val}`);
-  }
-  lines.push("");
-  fs.writeFileSync(envPath, lines.join("\n"));
+
+  const examplePath = path.join(PKG_DIR, ".env.example");
+  let template = "";
+  if (fs.existsSync(examplePath)) {
+    template = fs.readFileSync(examplePath, "utf-8");
+  } else {
+    // Fallback: try sibling (running from cloned repo)
+    const siblingExample = path.join(PKG_DIR, "..", ".env.example");
+    if (fs.existsSync(siblingExample)) {
+      template = fs.readFileSync(siblingExample, "utf-8");
+    }
+  }
+
+  if (template) {
+    // Patch each wizard var into the template by replacing the KEY=... line
+    for (const [key, val] of Object.entries(vars)) {
+      // Match KEY=anything (possibly commented out with #)
+      const regex = new RegExp(`^#?\\s*${key}=.*$`, "m");
+      if (regex.test(template)) {
+        template = template.replace(regex, `${key}=${val}`);
+      } else {
+        // Key not in template — append it
+        template += `\n${key}=${val}`;
+      }
+    }
+    // Add wizard timestamp header
+    template = `# Generated by sinain setup wizard — ${new Date().toISOString()}\n${template}`;
+    fs.writeFileSync(envPath, template);
+  } else {
+    // No template found — write bare vars (fallback)
+    const lines = [];
+    lines.push("# sinain configuration — generated by setup wizard");
+    lines.push(`# ${new Date().toISOString()}`);
+    lines.push("");
+    for (const [key, val] of Object.entries(vars)) {
+      lines.push(`${key}=${val}`);
+    }
+    lines.push("");
+    fs.writeFileSync(envPath, lines.join("\n"));
+  }
 
   rl.close();
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geravant/sinain",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Ambient AI overlay invisible to screen capture — real-time insights from audio + screen context",
   "type": "module",
   "bin": {
@@ -26,7 +26,7 @@
     "sinain-core/package.json",
     "sinain-core/package-lock.json",
     "sinain-core/tsconfig.json",
-    "sinain-core/.env.example",
+    ".env.example",
     "sinain-mcp-server/index.ts",
     "sinain-mcp-server/package.json",
     "sinain-mcp-server/tsconfig.json",

package/sinain-agent/run.sh

@@ -224,6 +224,37 @@ while true; do
     echo ""
   fi
 
+  # Poll for pending spawn task (queued via HUD Shift+Enter or POST /spawn)
+  SPAWN=$(curl -sf "$CORE_URL/spawn/pending" 2>/dev/null || echo '{"ok":false}')
+  SPAWN_ID=$(echo "$SPAWN" | python3 -c "import sys,json; d=json.load(sys.stdin); t=d.get('task'); print(t['id'] if t else '')" 2>/dev/null || true)
+
+  if [ -n "$SPAWN_ID" ]; then
+    SPAWN_TASK=$(echo "$SPAWN" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['task']['task'])" 2>/dev/null)
+    SPAWN_LABEL=$(echo "$SPAWN" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['task'].get('label','task'))" 2>/dev/null)
+
+    echo "[$(date +%H:%M:%S)] Spawn task $SPAWN_ID ($SPAWN_LABEL)"
+
+    if agent_has_mcp; then
+      # MCP path: agent runs task with sinain tools available
+      SPAWN_PROMPT="You have a background task to complete. Task: $SPAWN_TASK
+
+Complete this task thoroughly. Use sinain_get_knowledge and sinain_knowledge_query if you need context from past sessions. Summarize your findings concisely."
+      SPAWN_RESULT=$(invoke_agent "$SPAWN_PROMPT" || echo "ERROR: agent invocation failed")
+    else
+      # Pipe path: agent gets task text directly
+      SPAWN_RESULT=$(invoke_pipe "Background task: $SPAWN_TASK" || echo "No output")
+    fi
+
+    # Post result back
+    if [ -n "$SPAWN_RESULT" ]; then
+      curl -sf -X POST "$CORE_URL/spawn/respond" \
+        -H 'Content-Type: application/json' \
+        -d "{\"id\":\"$SPAWN_ID\",\"result\":$(echo "$SPAWN_RESULT" | json_encode)}" >/dev/null 2>&1 || true
+      echo "[$(date +%H:%M:%S)] Spawn $SPAWN_ID completed: ${SPAWN_RESULT:0:120}..."
+    fi
+    echo ""
+  fi
+
   # Heartbeat check
   NOW=$(date +%s)
   ELAPSED=$((NOW - LAST_HEARTBEAT))

package/sinain-core/src/escalation/escalator.ts

@@ -78,6 +78,9 @@ export class Escalator {
   private pendingUserCommand: UserCommand | null = null;
   private static readonly USER_COMMAND_EXPIRY_MS = 120_000; // 2 minutes
 
+  // HTTP spawn queue — for bare agents that poll (mirrors httpPending for escalation)
+  private spawnHttpPending: { id: string; task: string; label: string; ts: number } | null = null;
+
   private stats = {
     totalEscalations: 0,
     totalResponses: 0,
@@ -397,6 +400,37 @@ ${recentLines.join("\n")}`;
     return { ok: true };
   }
 
+  /** Return the current HTTP pending spawn task (or null). */
+  getSpawnPending(): { id: string; task: string; label: string; ts: number } | null {
+    return this.spawnHttpPending;
+  }
+
+  /** Respond to a pending spawn task from a bare agent. */
+  respondSpawn(id: string, result: string): { ok: boolean; error?: string } {
+    if (!this.spawnHttpPending) {
+      return { ok: false, error: "no pending spawn task" };
+    }
+    if (this.spawnHttpPending.id !== id) {
+      return { ok: false, error: `id mismatch: expected ${this.spawnHttpPending.id}` };
+    }
+
+    const label = this.spawnHttpPending.label;
+    const startedAt = this.spawnHttpPending.ts;
+
+    // Push result to HUD feed
+    const maxLen = 3000;
+    const text = `[🔧 ${label}] ${result.trim().slice(0, maxLen)}`;
+    this.deps.feedBuffer.push(text, "high", "openclaw", "agent");
+    this.deps.wsHandler.broadcast(text, "high", "agent");
+
+    // Broadcast completion
+    this.broadcastTaskEvent(id, "completed", label, startedAt, result.slice(0, 200));
+
+    log(TAG, `spawn ${id} responded (${result.length} chars)`);
+    this.spawnHttpPending = null;
+    return { ok: true };
+  }
+
   /** Whether the gateway WS client is currently connected. */
   get isGatewayConnected(): boolean {
     return this.wsClient.isConnected;
@@ -468,8 +502,12 @@ ${recentLines.join("\n")}`;
     this.broadcastTaskEvent(taskId, "spawned", label, startedAt);
 
     if (!this.wsClient.isConnected) {
-      warn(TAG, `spawn-task ${taskId}: WS disconnected — cannot dispatch`);
-      this.broadcastTaskEvent(taskId, "failed", label, startedAt);
+      // No OpenClaw gateway — queue for bare agent HTTP polling
+      this.spawnHttpPending = { id: taskId, task, label: label || "background-task", ts: startedAt };
+      const preview = task.length > 60 ? task.slice(0, 60) + "…" : task;
+      this.deps.feedBuffer.push(`🔧 Task queued for agent: ${preview}`, "normal", "system", "stream");
+      this.deps.wsHandler.broadcast(`🔧 Task queued for agent: ${preview}`, "normal");
+      log(TAG, `spawn-task ${taskId}: WS disconnected — queued for bare agent polling`);
       return;
     }
 

package/sinain-core/src/index.ts

@@ -416,6 +416,15 @@ async function main() {
         return execFileSync("python3", args, { timeout: 5000, encoding: "utf-8" });
       } catch { return ""; }
     },
+
+    // Spawn background agent task (from HUD Shift+Enter or bare agent POST /spawn)
+    onSpawnCommand: (text: string) => {
+      escalator.dispatchSpawnTask(text, "user-command").catch((err) => {
+        log("srv", `spawn via HTTP failed: ${err}`);
+      });
+    },
+    getSpawnPending: () => escalator.getSpawnPending(),
+    respondSpawn: (id: string, result: string) => escalator.respondSpawn(id, result),
   });
 
   // ── Wire overlay profiling ──
@@ -435,6 +444,12 @@ async function main() {
     onUserCommand: (text) => {
       escalator.setUserCommand(text);
     },
+    onSpawnCommand: (text) => {
+      escalator.dispatchSpawnTask(text, "user-command").catch((err) => {
+        log("cmd", `spawn command failed: ${err}`);
+        wsHandler.broadcast(`\u26a0 Spawn failed: ${String(err).slice(0, 100)}`, "normal");
+      });
+    },
     onToggleScreen: () => {
       screenActive = !screenActive;
       if (!screenActive) {

package/sinain-core/src/overlay/commands.ts

@@ -15,6 +15,8 @@ export interface CommandDeps {
   onUserMessage: (text: string) => Promise<void>;
   /** Queue a user command to augment the next escalation */
   onUserCommand: (text: string) => void;
+  /** Spawn a background agent task */
+  onSpawnCommand?: (text: string) => void;
   /** Toggle screen capture — returns new state */
   onToggleScreen: () => boolean;
   /** Toggle trait voices — returns new enabled state */
@@ -44,6 +46,17 @@ export function setupCommands(deps: CommandDeps): void {
         deps.onUserCommand(msg.text);
         break;
       }
+      case "spawn_command": {
+        const preview = msg.text.length > 60 ? msg.text.slice(0, 60) + "…" : msg.text;
+        log(TAG, `spawn command received: "${preview}"`);
+        if (deps.onSpawnCommand) {
+          deps.onSpawnCommand(msg.text);
+        } else {
+          log(TAG, `spawn command ignored — no handler configured`);
+          wsHandler.broadcast(`⚠ Spawn not available (no agent gateway connected)`, "normal");
+        }
+        break;
+      }
       case "command": {
         handleCommand(msg.action, deps);
         log(TAG, `command processed: ${msg.action}`);

package/sinain-core/src/server.ts

@@ -39,6 +39,9 @@ export interface ServerDeps {
   respondEscalation?: (id: string, response: string) => any;
   getKnowledgeDocPath?: () => string | null;
   queryKnowledgeFacts?: (entities: string[], maxFacts: number) => Promise<string>;
+  onSpawnCommand?: (text: string) => void;
+  getSpawnPending?: () => { id: string; task: string; label: string; ts: number } | null;
+  respondSpawn?: (id: string, result: string) => { ok: boolean; error?: string };
 }
 
 function readBody(req: IncomingMessage, maxBytes: number): Promise<string> {
@@ -341,6 +344,45 @@ export function createAppServer(deps: ServerDeps) {
         return;
       }
 
+      // ── /spawn ──
+      if (req.method === "POST" && url.pathname === "/spawn") {
+        const body = await readBody(req, 65536);
+        const { text, label } = JSON.parse(body);
+        if (!text) {
+          res.writeHead(400);
+          res.end(JSON.stringify({ ok: false, error: "missing text" }));
+          return;
+        }
+        if (deps.onSpawnCommand) {
+          deps.onSpawnCommand(text);
+          res.end(JSON.stringify({ ok: true, spawned: true }));
+        } else {
+          res.end(JSON.stringify({ ok: false, error: "spawn not configured" }));
+        }
+        return;
+      }
+
+      // ── /spawn/pending (bare agent polls for queued tasks) ──
+      if (req.method === "GET" && url.pathname === "/spawn/pending") {
+        const task = deps.getSpawnPending?.() ?? null;
+        res.end(JSON.stringify({ ok: true, task }));
+        return;
+      }
+
+      // ── /spawn/respond (bare agent returns task result) ──
+      if (req.method === "POST" && url.pathname === "/spawn/respond") {
+        const body = await readBody(req, 65536);
+        const { id, result } = JSON.parse(body);
+        if (!id || !result) {
+          res.writeHead(400);
+          res.end(JSON.stringify({ ok: false, error: "missing id or result" }));
+          return;
+        }
+        const resp = deps.respondSpawn?.(id, result) ?? { ok: false, error: "spawn not configured" };
+        res.end(JSON.stringify(resp));
+        return;
+      }
+
       res.writeHead(404);
       res.end(JSON.stringify({ error: "not found" }));
     } catch (err: any) {

package/sinain-core/src/types.ts

@@ -72,8 +72,14 @@ export interface UserCommandMessage {
   text: string;
 }
 
+/** Overlay → sinain-core: spawn a background agent task */
+export interface SpawnCommandMessage {
+  type: "spawn_command";
+  text: string;
+}
+
 export type OutboundMessage = FeedMessage | StatusMessage | PingMessage | SpawnTaskMessage;
-export type InboundMessage = UserMessage | CommandMessage | PongMessage | ProfilingMessage | UserCommandMessage;
+export type InboundMessage = UserMessage | CommandMessage | PongMessage | ProfilingMessage | UserCommandMessage | SpawnCommandMessage;
 
 /** Abstraction for user commands (text now, voice later). */
 export interface UserCommand {

package/sinain-mcp-server/index.ts

@@ -152,6 +152,24 @@ server.tool(
 );
 
 // 6. sinain_post_feed
+// 6b. sinain_spawn
+server.tool(
+  "sinain_spawn",
+  "Spawn a background agent task via sinain-core",
+  {
+    task: z.string(),
+    label: z.string().optional().default("background-task"),
+  },
+  async ({ task, label }) => {
+    try {
+      const data = await coreRequest("POST", "/spawn", { text: task, label });
+      return textResult(JSON.stringify(data, null, 2));
+    } catch (err: any) {
+      return textResult(`Error spawning task: ${err.message}`);
+    }
+  },
+);
+
 server.tool(
   "sinain_post_feed",
   "Post a message to the sinain-core HUD feed",

package/sinain-core/.env.example

@@ -1,92 +0,0 @@
-# sinain-core configuration
-# Copy to .env and fill in your values:  cp .env.example .env
-
-# ── Server ──
-PORT=9500
-
-# ── System Audio ──
-# Default: ScreenCaptureKit (zero-setup, macOS 13+). Fallback: ffmpeg + BlackHole.
-AUDIO_CAPTURE_CMD=screencapturekit # screencapturekit | sox | ffmpeg
-AUDIO_DEVICE=BlackHole 2ch        # macOS audio device (only used by sox/ffmpeg)
-AUDIO_SAMPLE_RATE=16000
-AUDIO_CHUNK_MS=5000
-AUDIO_VAD_ENABLED=true
-AUDIO_VAD_THRESHOLD=0.003
-AUDIO_AUTO_START=true
-AUDIO_GAIN_DB=20
-
-# ── Microphone (opt-in for privacy) ──
-MIC_ENABLED=false                  # set true to capture user's microphone
-MIC_DEVICE=default                 # "default" = system mic. For specific device: use exact CoreAudio name
-MIC_CAPTURE_CMD=sox                # sox or ffmpeg (mic uses sox by default)
-MIC_SAMPLE_RATE=16000
-MIC_CHUNK_MS=5000
-MIC_VAD_ENABLED=true
-MIC_VAD_THRESHOLD=0.008            # higher threshold (ambient noise)
-MIC_AUTO_START=false
-MIC_GAIN_DB=0
-
-# ── Transcription ──
-OPENROUTER_API_KEY=                # required (unless TRANSCRIPTION_BACKEND=local)
-TRANSCRIPTION_BACKEND=openrouter   # openrouter | local (local = whisper.cpp on-device)
-TRANSCRIPTION_MODEL=google/gemini-2.5-flash
-TRANSCRIPTION_LANGUAGE=en-US
-
-# ── Local Transcription (only when TRANSCRIPTION_BACKEND=local) ──
-# Install: brew install whisper-cpp
-# Models:  https://huggingface.co/ggerganov/whisper.cpp/tree/main
-# LOCAL_WHISPER_BIN=whisper-cli
-# LOCAL_WHISPER_MODEL=~/models/ggml-large-v3-turbo.bin
-# LOCAL_WHISPER_TIMEOUT_MS=15000
-
-# ── Agent ──
-AGENT_ENABLED=true
-AGENT_MODEL=google/gemini-2.5-flash-lite
-# AGENT_FALLBACK_MODELS=google/gemini-2.5-flash,anthropic/claude-3.5-haiku
-AGENT_MAX_TOKENS=300
-AGENT_TEMPERATURE=0.3
-AGENT_PUSH_TO_FEED=true
-AGENT_DEBOUNCE_MS=3000
-AGENT_MAX_INTERVAL_MS=30000
-AGENT_COOLDOWN_MS=10000
-AGENT_MAX_AGE_MS=120000            # context window lookback (2 min)
-
-# ── Escalation ──
-ESCALATION_MODE=selective          # off | selective | focus | rich
-ESCALATION_COOLDOWN_MS=30000
-# ESCALATION_TRANSPORT=auto        # ws | http | auto — use http for bare agent (no gateway)
-                                   # auto = WS when gateway connected, HTTP fallback
-                                   # http = skip gateway entirely, poll via GET /escalation/pending
-                                   # See docs/INSTALL-BARE-AGENT.md for bare agent setup
-
-# ── OpenClaw / NemoClaw Gateway ─────────────────────────────────────────────
-# Run ./setup-nemoclaw.sh to fill these in interactively (recommended).
-#
-# NemoClaw (NVIDIA Brev) quick-start:
-#   1. In Brev dashboard: Expose Port(s) → enter 18789 → TCP → note the IP
-#   2. In Code-Server terminal: npx sinain   (installs plugin, prints token)
-#   3. On Mac: ./setup-nemoclaw.sh           (interactive wizard)
-#
-# URL:   ws://YOUR-IP:18789   (use the IP shown after exposing port 18789)
-# Token: printed by `npx sinain` / visible in Brev dashboard → Gateway Token
-OPENCLAW_WS_URL=ws://localhost:18789
-OPENCLAW_WS_TOKEN=                 # 48-char hex — from gateway config or `npx sinain` output
-OPENCLAW_HTTP_URL=http://localhost:18789/hooks/agent
-OPENCLAW_HTTP_TOKEN=               # same token as WS_TOKEN
-OPENCLAW_SESSION_KEY=agent:main:sinain  # MUST be agent:main:sinain — see README § Session Key
-# OPENCLAW_PHASE1_TIMEOUT_MS=10000    # Phase 1 (delivery) timeout — circuit trips on failure
-# OPENCLAW_PHASE2_TIMEOUT_MS=120000   # Phase 2 (agent response) timeout — no circuit trip
-# OPENCLAW_QUEUE_TTL_MS=300000        # Outbound queue message TTL (5 min)
-# OPENCLAW_QUEUE_MAX_SIZE=10          # Max queued escalations (oldest dropped on overflow)
-# OPENCLAW_PING_INTERVAL_MS=30000     # WS ping keepalive interval
-
-# ── SITUATION.md ──
-SITUATION_MD_PATH=~/.openclaw/workspace/SITUATION.md
-# OPENCLAW_WORKSPACE_DIR=~/.openclaw/workspace
-
-# ── Debug ──
-# DEBUG=true                       # verbose logging (every tick, every chunk)
-
-# ── Tracing ──
-TRACE_ENABLED=true
-TRACE_DIR=~/.sinain-core/traces