@geravant/sinain 1.15.6 → 1.18.2

package/onboard.js

@@ -154,25 +154,54 @@ export async function runOnboard(args = {}) {
   p.log.success("API key saved.");
 
   if (flow === "quickstart") {
-    // QuickStart: sensible defaults. Gateway is opt-in (skip by default);
-    // agent + escalation defaults go to agents.json.
+    // QuickStart: sensible defaults + a single opt-in question for OpenClaw.
+    // Gateway integration is off by default; users who want it run Advanced
+    // (or answer Yes here, which then walks them through stepGateway).
     vars.TRANSCRIPTION_BACKEND = base.TRANSCRIPTION_BACKEND || "openrouter";
     vars.PRIVACY_MODE = base.PRIVACY_MODE || "standard";
     vars.AGENT_MODEL = base.AGENT_MODEL || "google/gemini-2.5-flash-lite";
+
+    // Ask explicitly so first-run installs don't silently inherit a gateway
+    // profile from agents.example.json. Default reflects current state — No
+    // for fresh installs (silences the WS reconnect loop), Yes for re-runs
+    // that already had OpenClaw configured (so we don't surprise-delete it).
+    const hasExistingGateway = (() => {
+      try {
+        const agentsPath = path.join(SINAIN_DIR, "agents.json");
+        if (!fs.existsSync(agentsPath)) return false;
+        const cfg = JSON.parse(fs.readFileSync(agentsPath, "utf-8"));
+        return !!cfg?.profiles?.openclaw;
+      } catch { return false; }
+    })();
+    const enableGateway = guard(await p.confirm({
+      message: "Enable OpenClaw gateway integration?",
+      initialValue: hasExistingGateway,
+    }));
+
     agentsPatch = {
       default: base.SINAIN_AGENT || "claude",
       escalationMode: "off",
-      // Don't touch openclawProfile in quickstart — keeps existing config
-      // intact for re-runs; first-time users get the "skip" state from
-      // agents.example.json bootstrap (no openclaw profile means no gateway).
     };
 
+    if (enableGateway) {
+      // Walk through full gateway setup (URL, tokens, session key) — same
+      // step Advanced uses. Returns { envVars, agentsPatch } we merge in.
+      const gatewayResult = await stepGateway(base, "OpenClaw gateway");
+      Object.assign(vars, gatewayResult.envVars);
+      Object.assign(agentsPatch, gatewayResult.agentsPatch);
+    } else {
+      // Explicitly clear any inherited openclaw profile so the runtime
+      // doesn't auto-register the gateway or attempt WS reconnects.
+      agentsPatch.openclawProfile = null;
+    }
+
     p.note(
       [
         `Transcription: ${vars.TRANSCRIPTION_BACKEND}`,
         `Privacy: ${vars.PRIVACY_MODE}`,
         `Model: ${vars.AGENT_MODEL}`,
-        `Escalation: off (pick a gateway agent in the overlay to enable)`,
+        `OpenClaw gateway: ${enableGateway ? "enabled" : "disabled"}`,
+        `Escalation: ${agentsPatch.escalationMode || "off"}`,
         "",
         `Change later: sinain config`,
       ].join("\n"),
@@ -368,10 +397,9 @@ if (flags.nonInteractive) {
   }
 
   writeEnv(vars);
-  // Default agent + escalation off (no gateway by default for non-interactive).
-  // openclaw profile is left as-is from the example template (or absent
-  // if first run) — gateway is opt-in via the wizard or `sinain config`.
-  writeAgentsConfig({ default: "claude", escalationMode: "off" });
+  // Default agent + escalation off + openclaw explicitly disabled. Gateway is
+  // opt-in via the interactive wizard (`sinain onboard`) or `sinain config`.
+  writeAgentsConfig({ default: "claude", escalationMode: "off", openclawProfile: null });
   console.log(c.green(`  Config written to ${ENV_PATH} + ~/.sinain/agents.json`));
   process.exit(0);
 } else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geravant/sinain",
-  "version": "1.15.6",
+  "version": "1.18.2",
   "description": "Ambient intelligence that sees what you see, hears what you hear, and acts on your behalf",
   "type": "module",
   "bin": {
@@ -43,6 +43,9 @@
     "sinain-agent/agents.example.json",
     "sinain-agent/.env.example",
     "sinain-agent/CLAUDE.md",
+    "sinain-agent/openrouter-proxy.mjs",
+    "sinain-agent/.claude/settings.json",
+    "sinain-agent/hooks/approve-tool.sh",
     "sense_client",
     "HEARTBEAT.md",
     "SKILL.md"

package/sinain-agent/.claude/settings.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./hooks/approve-tool.sh",
+            "timeout": 130
+          }
+        ]
+      }
+    ]
+  }
+}

package/sinain-agent/agents.example.json

@@ -64,7 +64,7 @@
   },
 
   "escalation": {
-    "mode": "rich",
+    "mode": "off",
     "cooldownMs": 30000,
     "staleMs": 90000
   },
@@ -81,8 +81,15 @@
         "OPENAI_API_KEY": "${OPENROUTER_API_KEY}"
       }
     },
+    "codex":      { "type": "codex" },
+    "goose":      { "type": "goose" },
+    "junie":      { "type": "junie" },
+    "aider":      { "type": "aider" }
+  },
+
+  "_examples": {
     "openclaw": {
-      "_comment": "Remote gateway routing. Selecting openclaw for a lane sends that lane's traffic to the OpenClaw gateway via WS RPC instead of the local bare agent. sinain-core reads these fields directly at startup to construct the WS client. Removing this profile disables the gateway path entirely (no WS client, no openclaw chip in the overlay roster).",
+      "_comment": "OpenClaw gateway routing. Move this entry into `profiles` to enable. The wizard's `sinain onboard --advanced` step or `sinain config gateway` populates this section automatically with your gateway URL/tokens. Selecting openclaw for a lane sends that lane's traffic via WS RPC to the gateway instead of the local bare agent. Disabled by default so first-run installs don't attempt WS connections to a gateway that isn't running.",
       "type": "openclaw",
       "wsUrl": "ws://localhost:18789",
       "wsToken": "${OPENCLAW_WS_TOKEN}",
@@ -93,13 +100,6 @@
       "phase2TimeoutMs": 120000,
       "pingIntervalMs": 30000
     },
-    "codex":      { "type": "codex" },
-    "goose":      { "type": "goose" },
-    "junie":      { "type": "junie" },
-    "aider":      { "type": "aider" }
-  },
-
-  "_examples": {
     "pclaude": {
       "_comment": "Personal claude config. `bin` must be a real PATH binary — replicate a shell alias as bin+env (the alias `pclaude=CLAUDE_CONFIG_DIR=$HOME/.claude-personal claude` becomes the entry below).",
       "type": "claude",

package/sinain-agent/hooks/approve-tool.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# PreToolUse hook for sinain-agent (escalation + spawn paths).
+#
+# Forwards every tool-invocation to sinain-core /spawn/approve which:
+#   - auto-approves safe read-only tools (Read, Glob, Grep, Ls, Cat)
+#   - auto-approves all mcp__sinain* tools
+#   - routes everything else to the overlay for Allow/Deny
+#
+# Scoped to sinain-agent via --settings in run.sh: regular openclaude/claude
+# sessions outside this directory don't load this settings.json and aren't
+# affected. Previously this hook early-exited unless SINAIN_SPAWN=1 was set,
+# which broke escalation-path write permissions (agent couldn't Bash/Edit).
+
+CORE_URL="${SINAIN_CORE_URL:-http://localhost:9500}"
+
+# Read hook input from stdin. Claude Code / openclaude typically include
+# session_id per the PreToolUse contract; if missing (or if we want a sinain-
+# native correlation), inject SINAIN_SPAWN_TASK_ID / SINAIN_ESC_TASK_ID as
+# sinainTaskId so the server can still key YOLO on a stable id per invocation.
+HOOK_STDIN=$(cat)
+SINAIN_TASK_ID="${SINAIN_SPAWN_TASK_ID:-${SINAIN_ESC_TASK_ID:-}}"
+if [ -n "$SINAIN_TASK_ID" ] && command -v python3 >/dev/null 2>&1; then
+  HOOK_STDIN=$(printf '%s' "$HOOK_STDIN" | SINAIN_TASK_ID="$SINAIN_TASK_ID" python3 -c '
+import json, os, sys
+try:
+    d = json.load(sys.stdin)
+    if isinstance(d, dict) and not d.get("sinainTaskId"):
+        d["sinainTaskId"] = os.environ["SINAIN_TASK_ID"]
+    print(json.dumps(d))
+except Exception:
+    # On any parse failure, pass original through — server can still work
+    sys.stdout.write(os.environ.get("HOOK_STDIN_FALLBACK", ""))
+')
+fi
+
+RESPONSE=$(printf '%s' "$HOOK_STDIN" | curl -sf -X POST "$CORE_URL/spawn/approve" \
+  -H 'Content-Type: application/json' \
+  --max-time 130 \
+  --data-binary @- 2>/dev/null)
+
+if [ -n "$RESPONSE" ]; then
+  echo "$RESPONSE"
+else
+  # If sinain-core is unreachable, allow by default (don't block the agent)
+  echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow","permissionDecisionReason":"sinain-core unreachable, auto-allowing"}}'
+fi

package/sinain-agent/openrouter-proxy.mjs

@@ -0,0 +1,266 @@
+// OpenRouter injecting proxy for reasoning-model compatibility.
+//
+// Problem it solves:
+//   DeepSeek V4 Flash (and similar thinking models) emit `reasoning` in
+//   responses and REQUIRE `reasoning_content` echoed back in subsequent
+//   assistant-message history. openclaude (Claude-Code-compat CLI) strips
+//   the field when reconstructing history -> DeepSeek 400s on every multi-turn
+//   MCP flow.
+//
+// How it works:
+//   Listens on :11435, forwards to https://openrouter.ai.
+//
+//   MODE=preserve (default): intercepts responses (streaming or not),
+//     extracts reasoning + tool_call ids, caches (tool_call_id -> reasoning).
+//     On subsequent requests, walks messages[] and injects cached
+//     reasoning_content into assistant messages that have tool_calls but no
+//     reasoning_content. Keeps thinking mode on, preserves model quality.
+//
+//   MODE=off: hard-disables thinking by injecting `reasoning:{enabled:false}`
+//     into every /chat/completions body. Legacy behavior; use as an escape
+//     hatch if preserve mode misbehaves.
+//
+//   Fallback: if MODE=preserve but any assistant-with-tool_calls lacks both
+//     reasoning_content AND cache hit, this request disables reasoning for
+//     itself only. Avoids 400 on cache miss (e.g. proxy restart mid-session).
+//
+// Config:
+//   REASONING_MODE=preserve|off   (default: preserve)
+//   OPENROUTER_PROXY_PORT=11435   (default: 11435)
+//   OPENROUTER_PROXY_LOG=/tmp/openrouter-proxy.log
+//
+// Point openclaude at the proxy in .env:
+//   OPENAI_BASE_URL=http://localhost:11435/api/v1
+
+import http from "http";
+import https from "https";
+import { appendFileSync, writeFileSync } from "fs";
+import { fileURLToPath } from "url";
+
+// Exported for testing — default values from env or hardcoded defaults.
+export const DEFAULT_LOG = "/tmp/openrouter-proxy.log";
+export const DEFAULT_UPSTREAM_HOST = "openrouter.ai";
+export const DEFAULT_UPSTREAM_PORT = 443;
+export const DEFAULT_LISTEN_PORT = 11435;
+export const DEFAULT_CACHE_MAX = 1000;
+
+const LOG = process.env.OPENROUTER_PROXY_LOG || DEFAULT_LOG;
+const UPSTREAM_HOST = "openrouter.ai";
+const UPSTREAM_PORT = 443;
+const LISTEN_PORT = parseInt(process.env.OPENROUTER_PROXY_PORT || String(DEFAULT_LISTEN_PORT), 10);
+const MODE = (process.env.REASONING_MODE || "preserve").toLowerCase();
+const CACHE_MAX = parseInt(process.env.OPENROUTER_PROXY_CACHE_MAX || String(DEFAULT_CACHE_MAX), 10);
+
+// tool_call_id -> reasoning_content. Insertion-order Map = simple LRU.
+const cache = new Map();
+
+function cacheSet(id, reasoning) {
+  if (cache.has(id)) cache.delete(id);
+  cache.set(id, reasoning);
+  while (cache.size > CACHE_MAX) {
+    cache.delete(cache.keys().next().value);
+  }
+}
+
+const log = (msg) => appendFileSync(LOG, msg);
+
+writeFileSync(LOG, `# openrouter proxy started ${new Date().toISOString()} mode=${MODE} port=${LISTEN_PORT} cacheMax=${CACHE_MAX}\n`);
+
+// Rewrite outgoing /chat/completions body based on MODE + cache state.
+function rewriteRequest(body) {
+  let json;
+  try { json = JSON.parse(body.toString("utf8")); }
+  catch { return { body, action: "passthrough-parse-fail" }; }
+
+  if (MODE === "off") {
+    if (!json.reasoning) json.reasoning = { enabled: false };
+    return { body: Buffer.from(JSON.stringify(json)), action: "disable-thinking" };
+  }
+
+  // MODE=preserve: walk history, inject cached reasoning_content
+  let injected = 0;
+  let orphaned = 0;
+  if (Array.isArray(json.messages)) {
+    for (const msg of json.messages) {
+      const needsReasoning =
+        msg.role === "assistant" &&
+        Array.isArray(msg.tool_calls) &&
+        msg.tool_calls.length > 0 &&
+        !msg.reasoning_content &&
+        !msg.reasoning;
+      if (!needsReasoning) continue;
+      const firstId = msg.tool_calls[0]?.id;
+      if (firstId && cache.has(firstId)) {
+        msg.reasoning_content = cache.get(firstId);
+        injected++;
+      } else {
+        orphaned++;
+      }
+    }
+  }
+
+  if (orphaned > 0) {
+    // Fallback: cache miss on a turn that needs echo-back. Disable thinking
+    // for THIS request only so DeepSeek doesn't 400. Next response will seed
+    // cache again. Injected assistant messages that WERE recovered stay as-is.
+    json.reasoning = { enabled: false };
+    return {
+      body: Buffer.from(JSON.stringify(json)),
+      action: `fallback-disable (injected=${injected}, orphaned=${orphaned})`,
+    };
+  }
+
+  if (injected > 0) {
+    return { body: Buffer.from(JSON.stringify(json)), action: `preserve (injected=${injected})` };
+  }
+
+  // No assistant-with-tool_calls needing reasoning — first request of a
+  // session, or request with only user messages. Pass through unchanged.
+  return { body, action: "preserve (no-op)" };
+}
+
+// Non-streaming response: extract reasoning + tool_call_ids from one JSON.
+function captureNonStreaming(body) {
+  try {
+    const json = JSON.parse(body.toString("utf8"));
+    const msg = json.choices?.[0]?.message;
+    if (!msg) return 0;
+    const reasoning = msg.reasoning || msg.reasoning_content;
+    const toolCalls = Array.isArray(msg.tool_calls) ? msg.tool_calls : [];
+    if (!reasoning || !toolCalls.length) return 0;
+    for (const tc of toolCalls) if (tc.id) cacheSet(tc.id, reasoning);
+    return toolCalls.length;
+  } catch { return 0; }
+}
+
+// Streaming response: accumulate reasoning text + tool_call ids across SSE chunks.
+// On stream end, associate the full reasoning with every observed tool_call id.
+function parseSSEChunk(chunk, state) {
+  state.buffer += chunk.toString("utf8");
+  const events = state.buffer.split("\n\n");
+  state.buffer = events.pop(); // last may be incomplete, keep for next chunk
+
+  for (const evt of events) {
+    for (const line of evt.split("\n")) {
+      if (!line.startsWith("data: ")) continue;
+      const data = line.slice(6).trim();
+      if (!data || data === "[DONE]") continue;
+      try {
+        const json = JSON.parse(data);
+        const delta = json.choices?.[0]?.delta;
+        if (!delta) continue;
+        if (typeof delta.reasoning === "string") state.reasoning += delta.reasoning;
+        if (typeof delta.reasoning_content === "string") state.reasoning += delta.reasoning_content;
+        if (Array.isArray(delta.tool_calls)) {
+          for (const tc of delta.tool_calls) {
+            if (tc.id && !state.toolCallIds.includes(tc.id)) state.toolCallIds.push(tc.id);
+          }
+        }
+      } catch { /* partial JSON across chunks; next chunk completes it */ }
+    }
+  }
+}
+
+// Exported request handler — pure function, no side effects at module load.
+// Auto-start path at bottom wraps this in http.createServer() when run directly.
+export function handler(clientReq, clientRes) {
+  const ts = new Date().toISOString();
+  let reqBody = Buffer.alloc(0);
+  clientReq.on("data", (c) => { reqBody = Buffer.concat([reqBody, c]); });
+  clientReq.on("end", () => {
+    const isChat = clientReq.url.includes("/chat/completions");
+
+    let outBody = reqBody;
+    let action = "passthrough";
+    if (isChat && reqBody.length > 0) {
+      const r = rewriteRequest(reqBody);
+      outBody = r.body;
+      action = r.action;
+    }
+
+    log(
+      `\n========== ${ts} ${clientReq.method} ${clientReq.url} ` +
+      `(${action}, cache=${cache.size}) ==========\n` +
+      `REQUEST (${outBody.length} bytes):\n${outBody.toString("utf8").slice(0, 4000)}\n` +
+      `---------- RESPONSE ----------\n`
+    );
+
+    const fwdHeaders = { ...clientReq.headers };
+    delete fwdHeaders.host;
+    fwdHeaders["content-length"] = outBody.length;
+
+    const upReq = https.request(
+      {
+        host: UPSTREAM_HOST,
+        port: UPSTREAM_PORT,
+        method: clientReq.method,
+        path: clientReq.url,
+        headers: fwdHeaders,
+      },
+      (upRes) => {
+        clientRes.writeHead(upRes.statusCode, upRes.headers);
+        const ct = upRes.headers["content-type"] || "";
+        const isStream = ct.includes("text/event-stream");
+        const state = { buffer: "", reasoning: "", toolCallIds: [] };
+        let collected = Buffer.alloc(0);
+
+        upRes.on("data", (chunk) => {
+          clientRes.write(chunk);
+          log(chunk.toString("utf8"));
+          if (MODE === "preserve" && isChat) {
+            if (isStream) parseSSEChunk(chunk, state);
+            else collected = Buffer.concat([collected, chunk]);
+          }
+        });
+        upRes.on("end", () => {
+          clientRes.end();
+          if (MODE === "preserve" && isChat) {
+            let cached = 0;
+            if (isStream) {
+              if (state.reasoning && state.toolCallIds.length) {
+                for (const id of state.toolCallIds) cacheSet(id, state.reasoning);
+                cached = state.toolCallIds.length;
+              }
+            } else {
+              cached = captureNonStreaming(collected);
+            }
+            if (cached > 0) {
+              log(`\n[cache] stored reasoning (${state.reasoning.length || "n/a"} chars) for ${cached} tool_call(s)\n`);
+            }
+          }
+          log(`========== END ${upRes.statusCode} (cache size=${cache.size}) ==========\n`);
+        });
+      }
+    );
+    upReq.on("error", (err) => {
+      log(`PROXY ERROR: ${err.message}\n`);
+      clientRes.writeHead(502);
+      clientRes.end("proxy error: " + err.message);
+    });
+    upReq.write(outBody);
+    upReq.end();
+  });
+}
+
+// Test helpers — small, pure, stateful.
+export function getCacheSize() { return cache.size; }
+export function clearCache() { cache.clear(); }
+
+// Core function exports for testing (names only; no `export function` on
+// the actual declarations to avoid duplicate-export errors).
+export {
+  cacheSet,
+  cache,
+  rewriteRequest,
+  captureNonStreaming,
+  parseSSEChunk,
+};
+
+// Only auto-start when run directly, not when imported as a module.
+const isMain = process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1];
+if (isMain) {
+  http.createServer(handler).listen(LISTEN_PORT, () => {
+    console.log(`openrouter proxy: http://localhost:${LISTEN_PORT} → https://${UPSTREAM_HOST} (mode=${MODE})`);
+    console.log(`logs: ${LOG}`);
+  });
+}

package/sinain-core/src/agent/analyzer.ts

@@ -150,6 +150,10 @@ function buildUserPrompt(ctx: ContextWindow, recorderStatus: RecorderStatus | nu
   const hasImages = imagesForPrompt && imagesForPrompt.length > 0;
   const imageNote = hasImages ? `\n\nScreen screenshots (${imagesForPrompt!.length}) are attached below.` : "";
 
+  const knowledgeSection = ctx.knowledgeFacts
+    ? `\n\nRelevant background:\n${ctx.knowledgeFacts}`
+    : "";
+
   return `Active app: ${normalizeAppName(ctx.currentApp)}
 App history: ${appSwitches || "(none)"}${recorderSection}
 
@@ -157,7 +161,7 @@ Screen (OCR text, newest first):
 ${screenLines || "(no screen data)"}
 
 Audio transcript (newest first, \ud83d\udd0a=system, \ud83c\udf99=mic):
-${audioLines || "(silence)"}${imageNote}`;
+${audioLines || "(silence)"}${knowledgeSection}${imageNote}`;
 }
 
 /**

package/sinain-core/src/agent/loop.ts

@@ -37,6 +37,8 @@ export interface AgentLoopDeps {
   feedbackStore?: { queryRecent(n: number): FeedbackRecord[] };
   /** Optional: cost tracker for LLM cost accumulation. */
   costTracker?: CostTracker;
+  /** Optional: entity subscription cache for real-time knowledge injection. */
+  entityCache?: import("../learning/entity-cache.js").EntityCache;
 }
 
 export interface TraceContext {
@@ -265,6 +267,15 @@ export class AgentLoop extends EventEmitter {
     const contextWindow = buildContextWindow(
       feedBuffer, senseBuffer, richness, this.deps.agentConfig.maxAgeMs,
     );
+
+    // Entity subscription: inject cached knowledge facts into context
+    if (this.deps.entityCache) {
+      const recentText = contextWindow.audio.map(a => a.text).join(" ");
+      const entities = this.deps.entityCache.detectEntities(recentText);
+      const facts = this.deps.entityCache.getRelevantFacts(entities, 500);
+      if (facts) contextWindow.knowledgeFacts = facts;
+    }
+
     this.deps.profiler?.timerRecord("agent.contextBuild", Date.now() - ctxStart);
 
     this.running = true;

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

@@ -99,6 +99,12 @@ export class Escalator {
   // Store context from last escalation for response handling
   private lastEscalationContext: ContextWindow | null = null;
 
+  // Knowledge enrichment is skipped on the very first escalation per process
+  // to avoid the 5s fetchKnowledgeFacts() cold-start tax on user-perceived
+  // first-response latency. Each subsequent escalation does its own fetch
+  // independently — no cross-escalation cache, no shared content state.
+  private firstEscalationDone = false;
+
   // User command to inject into the next escalation
   private pendingUserCommand: UserCommand | null = null;
   private static readonly USER_COMMAND_EXPIRY_MS = 120_000; // 2 minutes
@@ -281,8 +287,10 @@ export class Escalator {
     // Clear user command after building the message (consumed once)
     this.pendingUserCommand = null;
 
-    // Enrich with long-term knowledge facts (best-effort, 5s max)
-    if (this.deps.queryKnowledgeFacts) {
+    // Enrich with long-term knowledge facts (best-effort, 5s max).
+    // Skipped on the inaugural escalation per process to eliminate cold-start
+    // latency — the user's first response shouldn't wait for KG warmup.
+    if (this.deps.queryKnowledgeFacts && this.firstEscalationDone) {
       try {
         const knowledgeSection = await fetchKnowledgeFacts(
           contextWindow, entry.digest, this.deps.queryKnowledgeFacts,
@@ -294,7 +302,10 @@ export class Escalator {
       } catch (err) {
         log(TAG, `knowledge enrichment failed: ${String(err)}`);
       }
+    } else if (!this.firstEscalationDone) {
+      log(TAG, `first escalation: skipping knowledge fetch (fast path)`);
     }
+    this.firstEscalationDone = true;
 
     const slotId = createHash("sha256").update(this.deps.openclawConfig.sessionKey + entry.ts).digest("hex").slice(0, 16);
     const slotEntry: SlotEntry = {

package/sinain-core/src/index.ts

@@ -173,6 +173,48 @@ async function listKnowledgeEntitiesMulti(max: number): Promise<string> {
   return JSON.stringify(unique.slice(0, max));
 }
 
+/** Bi-temporal entity query: what did we know about entity X on a given date? */
+async function queryKnowledgeAsOfMulti(entity: string, date: string): Promise<string> {
+  const { execFileSync } = await import("node:child_process");
+  const { dirname } = await import("node:path");
+
+  const localDir = resolveLocalMemoryDir();
+  const workspaceDir = `${resolveWorkspace()}/memory`;
+  const dbPaths = [
+    `${localDir}/knowledge-graph.db`,
+    `${workspaceDir}/knowledge-graph.db`,
+  ];
+
+  const scriptCandidates = [
+    `${dirname(new URL(import.meta.url).pathname)}/../sinain-hud-plugin/sinain-memory`,
+    `${dirname(new URL(import.meta.url).pathname)}/sinain-memory`,
+    `${resolveWorkspace()}/sinain-memory`,
+  ];
+  const scriptsDir = scriptCandidates.find(p => existsSync(`${p}/triplestore.py`)) || scriptCandidates[0];
+
+  for (const dbPath of dbPaths) {
+    if (!existsSync(dbPath)) continue;
+    try {
+      const pyCode = `
+import sys, json; sys.path.insert(0, "${scriptsDir}")
+from datetime import datetime; from triplestore import TripleStore
+store = TripleStore("${dbPath}")
+d = datetime.fromisoformat("${date}")
+# Query both entity:X and fact:X-* patterns
+result = store.entity_as_of("entity:${entity}", d)
+if not result:
+    result = store.entity_as_of("${entity}", d)
+print(json.dumps({k: v for k, v in result.items()}, ensure_ascii=False))
+`;
+      const out = execFileSync("python3", ["-c", pyCode], {
+        timeout: 5000, encoding: "utf-8",
+      }).trim();
+      if (out && out !== "{}") return out;
+    } catch { /* skip */ }
+  }
+  return "{}";
+}
+
 /** Export knowledge facts as a portable JSON module. */
 async function exportKnowledgeMulti(domain: string | null, max: number): Promise<string> {
   const { execFileSync } = await import("node:child_process");
@@ -386,6 +428,13 @@ async function main() {
   setImmediate(() => {
     localCuration.distillPendingSession();
   });
+
+  // ── Entity subscription cache ���─
+  // Detects entity mentions in transcription, prefetches knowledge facts async.
+  // By the time the agent loop runs (3s debounce), cache is warm.
+  const { EntityCache } = await import("./learning/entity-cache.js");
+  const entityCache = new EntityCache(queryKnowledgeFactsMulti);
+  entityCache.loadEntityNames().catch(() => {});
   localCuration.startPeriodicCuration();
 
   // Wire incremental distillation: when feed buffer fills, distill before items are lost
@@ -464,6 +513,7 @@ async function main() {
     },
     feedbackStore: feedbackStore ?? undefined,
     costTracker,
+    entityCache,
   });
 
   // ── Wire learning signal collector (needs agentLoop) ──
@@ -590,6 +640,11 @@ async function main() {
     if (!isSystem) item.audioSource = "mic";
     wsHandler.broadcast(`${tag} ${bufferText}`, "normal");
     recorder.onFeedItem(item); // Collect for recording if active
+
+    // Entity subscription: detect mentions and prefetch knowledge (async, non-blocking)
+    const detectedEntities = entityCache.detectEntities(result.text);
+    if (detectedEntities.length > 0) entityCache.prefetch(detectedEntities);
+
     agentLoop.onNewContext(); // Trigger debounced analysis
   });
 
@@ -817,6 +872,7 @@ async function main() {
     },
     queryKnowledgeFacts: queryKnowledgeFactsMulti,
     listKnowledgeEntities: listKnowledgeEntitiesMulti,
+    queryKnowledgeAsOf: queryKnowledgeAsOfMulti,
     exportKnowledge: exportKnowledgeMulti,
     importKnowledge: importKnowledgeToLocal,
 

package/sinain-core/src/learning/entity-cache.ts

@@ -0,0 +1,180 @@
+/**
+ * Entity subscription cache — detects entity mentions in real-time transcription
+ * and prefetches knowledge facts for injection into the agent prompt.
+ *
+ * Flow: transcript → detectEntities() → prefetch() → getRelevantFacts()
+ * The 3s agent debounce ensures prefetch completes before the next analysis tick.
+ */
+
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { log, warn } from "../log.js";
+
+const TAG = "entity-cache";
+const MAX_ENTRIES = 50;
+const TTL_MS = 5 * 60 * 1000; // 5 minutes
+const JUNK_RE = /^[a-f0-9]{6,}$|^\d+$|^-+$/; // commit hashes, pure numbers, dashes
+
+interface CacheEntry {
+  facts: string;
+  ts: number;
+}
+
+type QueryFn = (entities: string[], maxFacts: number) => Promise<string>;
+
+export class EntityCache {
+  private cache = new Map<string, CacheEntry>();
+  private knownEntities: string[] = [];
+  private pendingQueries = new Set<string>();
+  private queryFn: QueryFn;
+  private evictionOrder: string[] = [];
+
+  constructor(queryFn: QueryFn) {
+    this.queryFn = queryFn;
+  }
+
+  /** Load entity names from the knowledge graph (async, non-blocking). */
+  async loadEntityNames(): Promise<void> {
+    try {
+      const __dir = dirname(fileURLToPath(import.meta.url));
+      const localDir = process.env.SINAIN_MEMORY_DIR
+        || process.env.OPENCLAW_WORKSPACE_DIR
+          ? `${(process.env.OPENCLAW_WORKSPACE_DIR || "").replace(/~/, process.env.HOME || "")}/memory`
+          : `${process.env.HOME}/.sinain/memory`;
+      const workspaceDir = `${(process.env.OPENCLAW_WORKSPACE_DIR || "").replace(/~/, process.env.HOME || "")}/memory`;
+
+      const dbPaths = [
+        `${localDir}/knowledge-graph.db`,
+        `${workspaceDir}/knowledge-graph.db`,
+      ].filter(p => existsSync(p));
+
+      if (dbPaths.length === 0) {
+        log(TAG, "no knowledge-graph.db found — entity detection disabled");
+        return;
+      }
+
+      // Query entity names directly via SQLite
+      const scriptCandidates = [
+        resolve(__dir, "..", "..", "sinain-hud-plugin", "sinain-memory", "graph_query.py"),
+        resolve(__dir, "..", "sinain-memory", "graph_query.py"),
+      ];
+      const scriptPath = scriptCandidates.find(p => existsSync(p));
+      if (!scriptPath) return;
+
+      const names = new Set<string>();
+      for (const dbPath of dbPaths) {
+        try {
+          const out = execFileSync("python3", [
+            "-c",
+            `import sys; sys.path.insert(0, "${dirname(scriptPath)}"); ` +
+            `from triplestore import TripleStore; store = TripleStore("${dbPath}"); ` +
+            `[print(n) for _, n in store.entities_with_attr("name") if _.startswith("entity:")]`,
+          ], { timeout: 5000, encoding: "utf-8" });
+          for (const line of out.split("\n")) {
+            const name = line.trim();
+            if (name.length >= 4 && !JUNK_RE.test(name)) {
+              names.add(name);
+            }
+          }
+        } catch { /* skip */ }
+      }
+
+      this.knownEntities = [...names].sort((a, b) => b.length - a.length); // longest first for greedy match
+      log(TAG, `loaded ${this.knownEntities.length} entity names`);
+    } catch (e: any) {
+      warn(TAG, `loadEntityNames failed: ${e.message?.slice(0, 80)}`);
+    }
+  }
+
+  /**
+   * Detect entity mentions in text. Synchronous, <1ms.
+   * Checks known entity names via substring match + extracts capitalized phrases.
+   */
+  detectEntities(text: string): string[] {
+    const lower = text.toLowerCase();
+    const found = new Set<string>();
+
+    // Known entity substring match (longest first avoids partial matches)
+    for (const name of this.knownEntities) {
+      if (found.size >= 5) break;
+      if (name.length < 5) {
+        // Short names: require word boundary
+        const re = new RegExp(`\\b${name.replace(/-/g, "[- ]?")}\\b`, "i");
+        if (re.test(lower)) found.add(name);
+      } else {
+        // Longer names: simple indexOf (spaces → optional hyphens)
+        const searchable = name.replace(/-/g, " ");
+        if (lower.includes(searchable) || lower.includes(name)) {
+          found.add(name);
+        }
+      }
+    }
+
+    // Capitalized multi-word phrases (catch entities not yet in graph)
+    const caps = text.match(/\b[A-Z][a-z]+(?:\s+[A-Z][a-z]+)+\b/g);
+    if (caps) {
+      for (const phrase of caps.slice(0, 3)) {
+        const normalized = phrase.toLowerCase().replace(/\s+/g, "-");
+        if (normalized.length >= 4 && !found.has(normalized)) {
+          found.add(normalized);
+          if (found.size >= 5) break;
+        }
+      }
+    }
+
+    return [...found];
+  }
+
+  /** Async prefetch: fire-and-forget knowledge queries for cache misses. */
+  prefetch(entities: string[]): void {
+    const toFetch = entities.filter(e => !this.cache.has(e) && !this.pendingQueries.has(e));
+    if (toFetch.length === 0) return;
+
+    for (const entity of toFetch) {
+      this.pendingQueries.add(entity);
+      this.queryFn([entity], 3)
+        .then(facts => {
+          this.cache.set(entity, { facts, ts: Date.now() });
+          this.evictionOrder.push(entity);
+          this.evict();
+        })
+        .catch(() => { /* silent */ })
+        .finally(() => this.pendingQueries.delete(entity));
+    }
+  }
+
+  /** Get cached facts for entities. Synchronous — only reads pre-fetched data. */
+  getRelevantFacts(entities: string[], maxChars: number): string {
+    const parts: string[] = [];
+    let total = 0;
+
+    for (const entity of entities) {
+      const entry = this.cache.get(entity);
+      if (!entry || Date.now() - entry.ts > TTL_MS || !entry.facts) continue;
+      if (total + entry.facts.length + 2 > maxChars) break;
+      parts.push(entry.facts);
+      total += entry.facts.length + 2;
+    }
+
+    return parts.join("; ");
+  }
+
+  /** Number of cached entities. */
+  get size(): number {
+    return this.cache.size;
+  }
+
+  /** Number of known entity names loaded from the graph. */
+  get entityCount(): number {
+    return this.knownEntities.length;
+  }
+
+  private evict(): void {
+    while (this.cache.size > MAX_ENTRIES && this.evictionOrder.length > 0) {
+      const oldest = this.evictionOrder.shift()!;
+      this.cache.delete(oldest);
+    }
+  }
+}

package/sinain-core/src/server.ts

@@ -179,6 +179,7 @@ export interface ServerDeps {
   getKnowledgeDocPath?: () => string | null;
   queryKnowledgeFacts?: (entities: string[], maxFacts: number) => Promise<string>;
   listKnowledgeEntities?: (max: number) => Promise<string>;
+  queryKnowledgeAsOf?: (entity: string, date: string) => Promise<string>;
   exportKnowledge?: (domain: string | null, max: number) => Promise<string>;
   importKnowledge?: (data: string) => Promise<string>;
   onSpawnCommand?: (text: string) => void;
@@ -453,6 +454,28 @@ export function createAppServer(deps: ServerDeps) {
         return;
       }
 
+      // ── /knowledge/as-of — bi-temporal entity query ──
+      if (req.method === "GET" && url.pathname === "/knowledge/as-of") {
+        const entity = url.searchParams.get("entity") || "";
+        const date = url.searchParams.get("date") || "";
+        if (!entity || !date) {
+          res.statusCode = 400;
+          res.end(JSON.stringify({ ok: false, error: "entity and date params required" }));
+          return;
+        }
+        if (deps.queryKnowledgeAsOf) {
+          try {
+            const result = await deps.queryKnowledgeAsOf(entity, date);
+            res.end(JSON.stringify({ ok: true, entity, date, attributes: JSON.parse(result) }));
+          } catch (err) {
+            res.end(JSON.stringify({ ok: false, error: String(err) }));
+          }
+        } else {
+          res.end(JSON.stringify({ ok: false, error: "bi-temporal query not available" }));
+        }
+        return;
+      }
+
       if (req.method === "GET" && url.pathname === "/knowledge/export") {
         // Export knowledge module (filterable by domain)
         const domain = url.searchParams.get("domain") || null;

package/sinain-core/src/types.ts

@@ -328,6 +328,8 @@ export interface ContextWindow {
   windowMs: number;
   newestEventTs: number;
   preset: RichnessPreset;
+  /** Pre-fetched knowledge facts from entity subscription cache. */
+  knowledgeFacts?: string;
 }
 
 // ── Escalation types ──

package/sinain-memory/graph_query.py

@@ -246,6 +246,88 @@ def query_facts_by_entity_graph(
         return []
 
 
+def expand_entity_community(
+    store,
+    entity_name: str,
+    max_related: int = 3,
+    max_facts_per_entity: int = 30,
+) -> list[tuple[str, int]]:
+    """Find related entities by following entity → facts → mentioned entities.
+
+    Returns [(entity_name, co_mention_count), ...] sorted by frequency.
+    """
+    entity_node_id = f"entity:{entity_name.lower().replace(' ', '-')}"
+    if not store.entity(entity_node_id):
+        return []
+
+    # Collect facts linked to this entity (both about and mentions)
+    fact_ids = set()
+    for fact_eid, _ in store.backrefs(entity_node_id, attribute="about")[:max_facts_per_entity]:
+        if fact_eid.startswith("fact:"):
+            fact_ids.add(fact_eid)
+    for fact_eid, _ in store.backrefs(entity_node_id, attribute="mentions")[:max_facts_per_entity]:
+        if fact_eid.startswith("fact:"):
+            fact_ids.add(fact_eid)
+
+    # Follow each fact's outgoing refs to find other entity nodes
+    related_counts: dict[str, int] = {}
+    for fact_eid in fact_ids:
+        attrs = store.entity(fact_eid)
+        for ref_attr in ("about", "mentions"):
+            targets = attrs.get(ref_attr, [])
+            if not isinstance(targets, list):
+                targets = [targets]
+            for target in targets:
+                if isinstance(target, str) and target.startswith("entity:") and target != entity_node_id:
+                    name = target[len("entity:"):]
+                    related_counts[name] = related_counts.get(name, 0) + 1
+
+    # Sort by frequency, return top N
+    ranked = sorted(related_counts.items(), key=lambda x: -x[1])
+    return ranked[:max_related]
+
+
+def _cooccurring_entities(
+    store,
+    fact_ids: set[str],
+    max_entities: int = 3,
+) -> list[str]:
+    """Find entities that co-occur in the same distillation pass (shared first_seen timestamp)."""
+    if not fact_ids:
+        return []
+
+    # Get first_seen timestamps for the input facts
+    timestamps = set()
+    for fid in list(fact_ids)[:20]:  # cap to avoid huge queries
+        attrs = store.entity(fid)
+        fs = attrs.get("first_seen", [])
+        if isinstance(fs, list) and fs:
+            timestamps.add(fs[0])
+        elif isinstance(fs, str):
+            timestamps.add(fs)
+
+    if not timestamps:
+        return []
+
+    # Find other facts with same timestamps and extract their entity names
+    placeholders = ",".join("?" for _ in timestamps)
+    rows = store._conn.execute(
+        f"SELECT DISTINCT t2.value FROM triples t1 "
+        f"JOIN triples t2 ON t2.entity_id = t1.entity_id AND t2.attribute = 'entity' AND t2.retracted = 0 "
+        f"WHERE t1.attribute = 'first_seen' AND t1.value IN ({placeholders}) "
+        f"AND t1.retracted = 0 AND t1.entity_id LIKE 'fact:%' "
+        f"AND t1.entity_id NOT IN ({','.join('?' for _ in fact_ids)})",
+        list(timestamps) + list(fact_ids),
+    ).fetchall()
+
+    # Count co-occurrence per entity name
+    counts: dict[str, int] = {}
+    for (name,) in rows:
+        counts[name] = counts.get(name, 0) + 1
+    ranked = sorted(counts, key=lambda x: -counts[x])
+    return ranked[:max_entities]
+
+
 def query_facts_hybrid(
     db_path: str,
     query: str,
@@ -257,17 +339,45 @@ def query_facts_hybrid(
     expands top results with 1-hop graph neighbors.
     """
     import re
+    import time
     keywords = [w.lower() for w in re.findall(r"[a-zA-Z][a-zA-Z0-9-]+", query) if len(w) > 2]
 
     # Entity graph pre-filter: find facts linked to mentioned entities via backrefs.
     # Used to BOOST relevant facts in RRF, not as a separate tier (avoids dilution).
     graph_fact_ids: set[str] = set()
+    community_fact_ids: set[str] = set()
     for kw in keywords:
         for f in query_facts_by_entity_graph(db_path, kw, max_facts=50):
             eid = f.get("entity_id", "")
             if eid:
                 graph_fact_ids.add(eid)
 
+    # Community expansion: follow mentions edges to find related entities
+    t0 = time.monotonic()
+    try:
+        from triplestore import TripleStore
+        store = TripleStore(db_path)
+
+        matched_entities = set()
+        for kw in keywords:
+            node_id = f"entity:{kw}"
+            if store.entity(node_id):
+                matched_entities.add(kw)
+
+        for ent in matched_entities:
+            if time.monotonic() - t0 > 0.5:
+                break  # timing guard
+            community = expand_entity_community(store, ent, max_related=3)
+            for related_name, _count in community:
+                for f in query_facts_by_entity_graph(db_path, related_name, max_facts=20):
+                    eid = f.get("entity_id", "")
+                    if eid and eid not in graph_fact_ids:
+                        community_fact_ids.add(eid)
+
+        store.close()
+    except Exception:
+        pass
+
     # Run three retrieval methods independently
     candidate_limit = max_facts * 3
     fts_results = query_facts_fts(db_path, query, max_facts=candidate_limit)
@@ -296,11 +406,31 @@ def query_facts_hybrid(
         for rank, eid in enumerate(ranked_list):
             rrf_scores[eid] = rrf_scores.get(eid, 0.0) + 1.0 / (K + rank)
 
+    # Co-occurrence boost: use FTS/tag results to find temporally related entities
+    import time as _time
+    _t_cooccur = _time.monotonic()
+    query_matched_ids = {f.get("entity_id", "") for f in fts_results + tag_results if f.get("entity_id")}
+    if query_matched_ids and _time.monotonic() - _t_cooccur < 0.3:
+        try:
+            from triplestore import TripleStore
+            _store = TripleStore(db_path)
+            cooccur = _cooccurring_entities(_store, query_matched_ids, max_entities=5)
+            for ent_name in cooccur:
+                for f in query_facts_by_entity_graph(db_path, ent_name, max_facts=10):
+                    eid = f.get("entity_id", "")
+                    if eid and eid not in graph_fact_ids:
+                        community_fact_ids.add(eid)
+            _store.close()
+        except Exception:
+            pass
+
     # Graph boost: facts linked to mentioned entities via backrefs get priority
-    if graph_fact_ids:
+    if graph_fact_ids or community_fact_ids:
         for eid in rrf_scores:
             if eid in graph_fact_ids:
-                rrf_scores[eid] += 0.02  # significant boost — graph-linked facts rank higher
+                rrf_scores[eid] += 0.02  # direct graph-linked facts
+            elif eid in community_fact_ids:
+                rrf_scores[eid] += 0.01  # community-expanded facts (half weight)
 
     # Apply confidence decay as secondary signal (fresh facts rank above stale ones)
     from triplestore import decayed_confidence