@geravant/sinain 1.15.5 → 1.18.1

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/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 ──