@geravant/sinain 1.22.8 → 1.23.1

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

@@ -31,6 +31,12 @@ export interface AgentLoopDeps {
   profiler?: Profiler;
   /** Called after each successful SITUATION.md write with the content string. */
   onSituationUpdate?: (content: string) => void;
+  /** Predicate to skip SITUATION.md writes entirely when no consumer is
+   *  listening. Today only the openclaw module reads SITUATION.md, so when
+   *  no gateway-typed agent is selected this returns false and the disk
+   *  write is skipped on every tick. Defaults to "always write" if absent
+   *  (preserves prior behavior for callers that don't pass the predicate). */
+  shouldWriteSituation?: () => boolean;
   /** Optional: path to sinain-knowledge.md for startup recap. */
   getKnowledgeDocPath?: () => string | null;
   /** Optional: feedback store for startup recap context. */
@@ -376,9 +382,14 @@ export class AgentLoop extends EventEmitter {
       // Calculate escalation score for both SITUATION.md and escalation check
       const escalationScore = calculateEscalationScore(digest, contextWindow);
 
-      // Write SITUATION.md (enhanced with escalation context and recorder status)
-      const situationContent = writeSituationMd(this.deps.situationMdPath, contextWindow, digest, entry, escalationScore, recorderStatus);
-      this.deps.onSituationUpdate?.(situationContent);
+      // Write SITUATION.md only when something consumes it (today: an openclaw
+      // gateway lane is selected). Without a consumer, skip the disk write to
+      // avoid pinning ~/.openclaw/workspace/SITUATION.md on every tick of users
+      // who chose claude/openclaude/etc as both lanes.
+      if (this.deps.shouldWriteSituation?.() ?? true) {
+        const situationContent = writeSituationMd(this.deps.situationMdPath, contextWindow, digest, entry, escalationScore, recorderStatus);
+        this.deps.onSituationUpdate?.(situationContent);
+      }
 
       // Notify for escalation check
       traceCtx?.startSpan("escalation-check");

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

@@ -170,17 +170,38 @@ export class Escalator {
     log(TAG, `user command set: "${preview}"`);
   }
 
+  /** True iff a gateway-typed profile is the active agent on at least one
+   *  lane. WS-bearing operations (connect, reset, situation push) are gated
+   *  on this so a user with a configured-but-unselected gateway pays no
+   *  reconnect tax. */
+  private isGatewayLaneSelected(): boolean {
+    const isGw = this.deps.isGatewayAgent;
+    if (!isGw) return false;
+    const esc = this.deps.getEscalationAgent?.() ?? "";
+    const spawn = this.deps.getSpawnAgent?.() ?? "";
+    return isGw(esc) || isGw(spawn);
+  }
+
+  /** Public predicate so the agent loop / index.ts can ask "should I do
+   *  openclaw-only side-effects on this tick?" without depending on the
+   *  internals. Mirrors isGatewayLaneSelected. */
+  shouldDriveGateway(): boolean {
+    const wsConfigured = !!this.deps.openclawConfig.gatewayWsUrl;
+    return wsConfigured && this.isGatewayLaneSelected();
+  }
+
   /** Start the WS connection to OpenClaw.
    *
-   * Connects whenever the gateway URL is configured AND escalation isn't
-   * fully off. WS is the transport for the openclaw lane — the user selects
-   * it via the overlay's agent picker, and dispatch routes accordingly.
-   * Removing the openclaw profile from agents.json (and unsetting the env
-   * vars) leaves gatewayWsUrl empty → no connect attempt.
+   * Connects whenever the gateway URL is configured AND a gateway-typed
+   * profile is selected on a lane AND escalation isn't fully off. WS is
+   * the transport for the openclaw lane — the user selects it via the
+   * overlay's agent picker, and dispatch routes accordingly. Removing the
+   * openclaw profile from agents.json (and unsetting the env vars) leaves
+   * gatewayWsUrl empty → no connect attempt. Likewise, if the profile
+   * exists but no lane selects it, no connect attempt.
    */
   start(): void {
-    const wsConfigured = !!this.deps.openclawConfig.gatewayWsUrl;
-    if (this.deps.escalationConfig.mode !== "off" && wsConfigured) {
+    if (this.deps.escalationConfig.mode !== "off" && this.shouldDriveGateway()) {
       this.wsClient.connect();
       const tokenHash = this.deps.openclawConfig.gatewayToken
         ? createHash("sha256").update(this.deps.openclawConfig.gatewayToken).digest("hex").slice(0, 12)
@@ -194,11 +215,26 @@ export class Escalator {
     this.wsClient.disconnect();
   }
 
+  /** Re-evaluate WS lifecycle after lane selection changes. Connects when a
+   *  gateway lane just got selected; disconnects when the user moved off
+   *  every gateway lane. Called from the set_agent overlay handler. */
+  evaluateGatewayLifecycle(): void {
+    const shouldConnect =
+      this.deps.escalationConfig.mode !== "off" && this.shouldDriveGateway();
+    if (shouldConnect && !this.wsClient.isConnected) {
+      log(TAG, "lane switched to gateway — connecting WS");
+      this.wsClient.resetConnection();
+    } else if (!shouldConnect && this.wsClient.isConnected) {
+      log(TAG, "lane switched off gateway — disconnecting WS");
+      this.wsClient.disconnect();
+    }
+  }
+
   /** Update escalation mode at runtime. */
   setMode(mode: EscalatorDeps["escalationConfig"]["mode"]): void {
     const wasOff = this.deps.escalationConfig.mode === "off";
     this.deps.escalationConfig.mode = mode;
-    if (mode !== "off" && !this.wsClient.isConnected) {
+    if (mode !== "off" && !this.wsClient.isConnected && this.shouldDriveGateway()) {
       this.wsClient.resetConnection();
     }
     if (mode === "off") {

package/sinain-core/src/index.ts

@@ -743,6 +743,11 @@ async function main() {
     onSituationUpdate: (content) => {
       escalator.pushSituationMd(content);
     },
+    // Gate SITUATION.md writes (and the subsequent push) on a gateway lane
+    // being active — see escalator.shouldDriveGateway. Users with no openclaw
+    // profile, or with the profile but no lane selecting it, pay zero disk
+    // I/O on every tick.
+    shouldWriteSituation: () => escalator.shouldDriveGateway(),
     onHudUpdate: (text) => {
       wsHandler.broadcastRaw({ type: "thinking", active: false } as any);
       wsHandler.broadcast(text, "normal", "stream");
@@ -1241,6 +1246,12 @@ async function main() {
         // Spawn "off" just means run.sh won't poll /spawn/pending; no
         // server-side state to flip. Queued spawn tasks TTL out naturally.
       }
+      // Re-evaluate WS lifecycle: connect when a gateway lane just got
+      // selected (zero attempts before this point), disconnect when the user
+      // moved off every gateway lane. This is what makes the "no resources
+      // when not in use" guarantee hold across runtime selection changes,
+      // not just startup config.
+      escalator.evaluateGatewayLifecycle();
       // Rebroadcast state so the overlay sees the switch immediately, and
       // the bare agent sees it on its next poll-response config piggyback.
       // `escalation` field reflects the current escalator mode so the flash

package/sinain-core/src/server.ts

@@ -942,14 +942,16 @@ function setupSearch() {
     const q = input.value.trim();
     if (!q) { dropdown.classList.remove("open"); dropdown.innerHTML = ""; return; }
     const result = await api("/knowledge/search?q=" + encodeURIComponent(q) + "&limit=15");
+    // Always show "Search: query" as first option → topic page with combined recall
+    const topicLink = \`
+      <div class="search-result" onclick="navigate('/knowledge/ui/topic/' + encodeURIComponent('\${esc(q)}'))" style="border-bottom:1px solid rgba(255,255,255,0.1)">
+        <div class="entity">🔍 Search: \${esc(q)}</div>
+        <div class="snippet">Combined query — find facts across multiple entities</div>
+      </div>\`;
     if (!result.results || result.results.length === 0) {
-      dropdown.innerHTML = \`
-        <div class="search-result" onclick="navigate('/knowledge/ui/topic/' + encodeURIComponent('\${esc(q)}'))">
-          <div class="entity">View as topic page</div>
-          <div class="snippet">No matching entities — synthesize from search hits.</div>
-        </div>\`;
+      dropdown.innerHTML = topicLink;
     } else {
-      dropdown.innerHTML = result.results.map(r => \`
+      dropdown.innerHTML = topicLink + result.results.map(r => \`
         <div class="search-result" onclick="navigate('/knowledge/ui/entity/' + encodeURIComponent('\${esc(r.entity)}'))">
           <div class="entity">\${esc(r.entity)}</div>
           <div class="meta">\${esc(r.type)} · \${r.fact_count} fact\${r.fact_count === 1 ? "" : "s"}</div>
@@ -960,6 +962,12 @@ function setupSearch() {
   }, 220);
   input.addEventListener("input", handleQuery);
   input.addEventListener("focus", () => { if (input.value) handleQuery(); });
+  input.addEventListener("keydown", (e) => {
+    if (e.key === "Enter" && input.value.trim()) {
+      dropdown.classList.remove("open");
+      navigate("/knowledge/ui/topic/" + encodeURIComponent(input.value.trim()));
+    }
+  });
   document.addEventListener("click", (e) => {
     if (!e.target.closest(".search-wrap")) dropdown.classList.remove("open");
   });
@@ -1339,25 +1347,109 @@ function renderMissingConcept(entity, root) {
 
 // ── Topic page (simple, v1) ───────────────────────────────────────────────
 async function renderTopicPage(q) {
-  document.title = "Topic: " + q;
+  document.title = "Topic: " + q + " · Sinain";
   const root = $("#root");
-  root.innerHTML = \`
-    <h1>Topic: \${esc(q)}</h1>
-    <div class="loading-block"><span class="spinner"></span> Searching…</div>\`;
-  const r = await api("/knowledge/search?q=" + encodeURIComponent(q) + "&limit=50");
-  if (!r.results || r.results.length === 0) {
-    root.innerHTML = \`<h1>Topic: \${esc(q)}</h1>
+  root.innerHTML = \`<div class="loading-block"><span class="spinner"></span> Searching…</div>\`;
+
+  // Parallel: get combined facts + matching entities
+  const [qr, sr] = await Promise.all([
+    api("/knowledge/query?q=" + encodeURIComponent(q) + "&max=30"),
+    api("/knowledge/search?q=" + encodeURIComponent(q) + "&limit=10"),
+  ]);
+  const factsText = qr.facts_text || "";
+  const entities = sr.results || [];
+
+  if (!factsText && entities.length === 0) {
+    root.innerHTML = \`
+      <div class="page-header"><div class="title">Topic: \${esc(q)}</div></div>
       <div class="error-block">No matching facts.</div>\`;
     return;
   }
+
+  // Parse compact facts into structured items, group by entity
+  const factItems = factsText ? factsText.split("; ").filter(Boolean) : [];
+  const grouped = {};
+  const ungrouped = [];
+  for (const f of factItems) {
+    const m = f.match(/^([^:]*?):\\s*(.+?)\\s*\\(([^)]+)\\)$/);
+    if (m) {
+      const ent = m[1].trim() || "general";
+      (grouped[ent] = grouped[ent] || []).push({text: m[2], meta: m[3], raw: f});
+    } else {
+      ungrouped.push({text: f, meta: "", raw: f});
+    }
+  }
+
+  // Build summary from top entities
+  const topEnts = Object.keys(grouped).slice(0, 5).join(", ");
+  const summary = factItems.length > 0
+    ? \`\${factItems.length} facts retrieved across \${Object.keys(grouped).length} entities\${topEnts ? ": " + topEnts : ""}\`
+    : "No facts found for this query.";
+
   root.innerHTML = \`
-    <h1>Topic: \${esc(q)}</h1>
-    <div class="summary">Top \${r.results.length} matches across the knowledge graph.</div>
-    \${r.results.map(rr => \`
-      <div class="bullet" onclick="navigate('/knowledge/ui/entity/' + encodeURIComponent('\${esc(rr.entity)}'))" style="cursor:pointer">
-        <span class="text"><strong>\${esc(rr.entity)}</strong> — \${esc(rr.snippet || "")}</span>
-        <span class="conf">\${rr.fact_count} fact\${rr.fact_count === 1 ? "" : "s"}</span>
-      </div>\`).join("")}\`;
+    <div class="page-header">
+      <div class="title">Topic: \${esc(q)}</div>
+      <div class="badges">
+        <span class="badge">\${factItems.length} fact\${factItems.length === 1 ? "" : "s"}</span>
+        <span class="badge">\${Object.keys(grouped).length} entit\${Object.keys(grouped).length === 1 ? "y" : "ies"}</span>
+      </div>
+      <div class="page-actions">
+        <button id="topicCopyLink" class="icon" title="Copy topic URL">🔗</button>
+        <button id="topicShare" class="icon" title="Share topic (auto-imports for recipient)">📤</button>
+      </div>
+    </div>
+    <div class="summary">\${esc(summary)}</div>
+    <div id="topicSections">
+      \${Object.entries(grouped).map(([ent, facts], i) => \`
+        <div class="section" id="sec-\${i}">
+          <div class="section-heading" onclick="this.parentElement.classList.toggle('collapsed')">
+            \${esc(ent)}
+            <span style="opacity:0.5;font-size:0.85em;margin-left:8px">\${facts.length} fact\${facts.length === 1 ? "" : "s"}</span>
+          </div>
+          <ul class="bullets">\${facts.map(f => \`
+            <li class="bullet">
+              <span class="text">\${esc(f.text)}</span>
+              <span class="conf">\${esc(f.meta)}</span>
+            </li>\`).join("")}</ul>
+        </div>\`).join("")}
+      \${ungrouped.length > 0 ? \`
+        <div class="section">
+          <div class="section-heading">Other</div>
+          <ul class="bullets">\${ungrouped.map(f => \`
+            <li class="bullet"><span class="text">\${esc(f.text)}</span></li>\`).join("")}</ul>
+        </div>\` : ""}
+    </div>
+    \${entities.length > 0 ? \`
+      <div class="section" style="margin-top:16px">
+        <div class="section-heading" onclick="this.parentElement.classList.toggle('collapsed')">
+          Related Entities
+        </div>
+        <ul class="bullets">\${entities.map(rr => \`
+          <li class="bullet" onclick="navigate('/knowledge/ui/entity/' + encodeURIComponent('\${esc(rr.entity)}'))" style="cursor:pointer">
+            <span class="text"><strong>\${esc(rr.entity)}</strong> — \${esc(rr.snippet || "")}</span>
+            <span class="conf">\${rr.fact_count} fact\${rr.fact_count === 1 ? "" : "s"}</span>
+          </li>\`).join("")}</ul>
+      </div>\` : ""}\`;
+
+  // Wire actions
+  $("#topicCopyLink").onclick = () => {
+    const url = location.origin + "/knowledge/ui/topic/" + encodeURIComponent(q);
+    navigator.clipboard.writeText(url);
+    showToast("✓ Link copied");
+  };
+  $("#topicShare").onclick = async () => {
+    // Share all entities mentioned in the query
+    const ents = (qr.entities || q.split(/[\\s,+]+/)).filter(Boolean);
+    if (ents.length === 0) { showToast("No entities to share"); return; }
+    showToast('<span class="spinner"></span> Preparing share…', 30_000);
+    try {
+      for (const ent of ents.slice(0, 3)) {
+        await ShareManager.createShare(ent);
+      }
+    } catch (e) {
+      showToast("Share failed: " + (e && e.message ? e.message : String(e)));
+    }
+  };
 }
 
 // ── Dropzone wiring (shared) ──────────────────────────────────────────────
@@ -1816,6 +1908,30 @@ export function createAppServer(deps: ServerDeps) {
         return;
       }
 
+      // ── /knowledge/query ── (combined entity recall — used by topic page) ──
+      if (req.method === "GET" && url.pathname === "/knowledge/query") {
+        const q = url.searchParams.get("q") || "";
+        const maxFacts = Math.min(parseInt(url.searchParams.get("max") || "20"), 50);
+        if (!q.trim()) {
+          res.writeHead(400);
+          res.end(JSON.stringify({ ok: false, error: "q parameter required" }));
+          return;
+        }
+        // Split query into entity keywords for queryKnowledgeFacts
+        const entities = q.trim().split(/[\s,+]+/).filter(Boolean);
+        if (deps.queryKnowledgeFacts) {
+          try {
+            const factsText = await deps.queryKnowledgeFacts(entities, maxFacts);
+            res.end(JSON.stringify({ ok: true, query: q, facts_text: factsText, entities }));
+          } catch (err) {
+            res.end(JSON.stringify({ ok: false, error: String(err) }));
+          }
+        } else {
+          res.end(JSON.stringify({ ok: true, query: q, facts_text: "", entities }));
+        }
+        return;
+      }
+
       // ── /knowledge/search ── (entity-prioritized) ──
       if (req.method === "GET" && url.pathname === "/knowledge/search") {
         const q = url.searchParams.get("q") || "";

package/sinain-core/src/util/event-bus.ts

@@ -0,0 +1,69 @@
+import { EventEmitter } from "node:events";
+import type { AgentEntry, ContextWindow } from "../types.js";
+
+/**
+ * Domain-generic events emitted by sinain-core. Optional agent modules
+ * (currently just openclaw, future bridges to other gateways) subscribe
+ * to these instead of being wired directly into Escalator. The contract
+ * here is the only stable surface modules can rely on.
+ */
+export interface CoreEvents {
+  /** An escalation has been routed to an agent. Modules whose roster
+   *  matches `agent` should run their delivery (WS, HTTP, etc). */
+  "escalation:dispatched": {
+    entry: AgentEntry;
+    contextWindow: ContextWindow;
+    message: string;
+    agent: string;
+  };
+
+  /** User typed a direct message in the overlay command input. */
+  "user:direct": { text: string; ts: number };
+
+  /** Periodic feedback summary ready for forwarding to long-running agents. */
+  "feedback:periodic": { summary: string; lastNTicks: number };
+
+  /** Agent loop completed an analysis tick. Used by SITUATION.md writers
+   *  and other context consumers. */
+  "tick:complete": { entry: AgentEntry };
+}
+
+export interface CoreEventBus {
+  on<K extends keyof CoreEvents>(
+    event: K,
+    listener: (payload: CoreEvents[K]) => void,
+  ): () => void;
+  emit<K extends keyof CoreEvents>(event: K, payload: CoreEvents[K]): void;
+  removeAllListeners(): void;
+}
+
+class TypedEventBus implements CoreEventBus {
+  private readonly emitter = new EventEmitter();
+
+  constructor() {
+    // Default Node limit (10) is too low for a long-running bus with many
+    // subscribers across the lifetime of the process. Disable the warning;
+    // we control the listener set internally.
+    this.emitter.setMaxListeners(0);
+  }
+
+  on<K extends keyof CoreEvents>(
+    event: K,
+    listener: (payload: CoreEvents[K]) => void,
+  ): () => void {
+    this.emitter.on(event, listener as (...args: unknown[]) => void);
+    return () => this.emitter.off(event, listener as (...args: unknown[]) => void);
+  }
+
+  emit<K extends keyof CoreEvents>(event: K, payload: CoreEvents[K]): void {
+    this.emitter.emit(event, payload);
+  }
+
+  removeAllListeners(): void {
+    this.emitter.removeAllListeners();
+  }
+}
+
+export function createCoreEventBus(): CoreEventBus {
+  return new TypedEventBus();
+}