flint-agent 1.14.0

package/src/logging/logger.js

@@ -0,0 +1,112 @@
+// Structured logger with levels: debug, info, warn, error
+// Level from .env AGENT_LOG_LEVEL (default: "info")
+// All levels >= configured write to sessions/<sessionId>.log
+// warn+ also goes to stderr
+
+import "dotenv/config"; // ensure .env is loaded before anything else
+import { appendFileSync, mkdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+const LEVELS = { debug: 0, info: 1, warn: 2, error: 3, silent: 4 };
+const LEVEL_NAMES = Object.fromEntries(Object.entries(LEVELS).map(([k, v]) => [v, k]));
+
+const _rawLevel = process.env.AGENT_LOG_LEVEL;
+const _level = LEVELS[(_rawLevel || "info").trim()] ?? LEVELS.info;
+let _logFile = null;
+let _buffer = []; // buffer messages before initLogger sets the file
+let _inkActive = false; // suppress stderr when Ink TUI is rendering
+
+/**
+ * Initialize logger with session info. Call once after session is created.
+ * @param {{ sessionsDir: string, sessionId: string }} opts
+ */
+export function initLogger(opts = {}) {
+  if (opts.sessionsDir && opts.sessionId && _level < LEVELS.silent) {
+    try {
+      mkdirSync(opts.sessionsDir, { recursive: true });
+      _logFile = path.join(opts.sessionsDir, `${opts.sessionId}.log`);
+      // Flush buffered messages
+      if (_buffer.length > 0) {
+        writeFileSync(_logFile, _buffer.join("\n") + "\n");
+        _buffer = [];
+      }
+    } catch {}
+  }
+}
+
+/**
+ * Set log level at runtime.
+ * @param {"debug"|"info"|"warn"|"error"|"silent"} level
+ */
+export function setLogLevel(level) {
+  // Note: can't reassign const, but we can use this for future dynamic level
+}
+
+/**
+ * Suppress stderr output when Ink TUI is active.
+ * stderr.write during Ink rendering corrupts terminal layout.
+ */
+export function setInkActive(active) {
+  _inkActive = active;
+}
+
+/** @returns {"debug"|"info"|"warn"|"error"|"silent"} */
+export function getLogLevel() {
+  return LEVEL_NAMES[_level] || "info";
+}
+
+function formatMsg(level, module, msg, data) {
+  const d = new Date();
+  const ts = `${String(d.getHours()).padStart(2,"0")}:${String(d.getMinutes()).padStart(2,"0")}:${String(d.getSeconds()).padStart(2,"0")}.${String(d.getMilliseconds()).padStart(3,"0")}`;
+  const prefix = `[${ts}] [${level.toUpperCase()}] [${module}]`;
+  let line = `${prefix} ${msg}`;
+  if (data !== undefined) {
+    const extra = typeof data === "string" ? data : JSON.stringify(data);
+    line += ` ${extra}`;
+  }
+  return line;
+}
+
+function emit(levelNum, level, module, msg, data) {
+  if (levelNum < _level) return;
+
+  const line = formatMsg(level, module, msg, data);
+
+  // Write to log file (or buffer if file not ready yet)
+  if (_logFile) {
+    try { appendFileSync(_logFile, line + "\n"); } catch {}
+  } else {
+    _buffer.push(line);
+  }
+
+  // Write to stderr for warn+ ONLY when Ink TUI is NOT active
+  // stderr.write during Ink rendering breaks cursor positioning and causes UI duplication
+  if (levelNum >= LEVELS.warn && !_inkActive) {
+    process.stderr.write(line + "\n");
+  }
+}
+
+/**
+ * Create a scoped logger for a module.
+ * @param {string} module - Module name (e.g. "server", "pairing", "heartbeat")
+ * @returns {{ debug, info, warn, error }}
+ */
+export function createLogger(module) {
+  return {
+    debug: (msg, data) => emit(LEVELS.debug, "debug", module, msg, data),
+    info: (msg, data) => emit(LEVELS.info, "info", module, msg, data),
+    warn: (msg, data) => emit(LEVELS.warn, "warn", module, msg, data),
+    error: (msg, data) => emit(LEVELS.error, "error", module, msg, data),
+  };
+}
+
+// Log boot immediately
+const _bootLog = createLogger("boot");
+_bootLog.info("Logger initialized", {
+  level: LEVEL_NAMES[_level],
+  cwd: process.cwd(),
+  argv: process.argv.slice(2).join(" "),
+  AGENT_PORT: process.env.AGENT_PORT || "(default)",
+  AGENT_PARENT_PORT: process.env.AGENT_PARENT_PORT || "(none)",
+  pid: process.pid,
+});

package/src/logging/tool-log.js

@@ -0,0 +1,20 @@
+import { appendFileSync } from "node:fs";
+import { config } from "../config.js";
+import path from "node:path";
+
+export function logToolResult(sessionId, { toolCallId, name, args, result }) {
+  if (!sessionId) return;
+  const file = path.join(config.sessionsDir, `${sessionId}.tools.log`);
+  const ts = new Date().toISOString().slice(11, 19);
+  const argsStr = Object.entries(args)
+    .map(([k, v]) => {
+      const s = typeof v === "string" && v.length > 100 ? v.slice(0, 100) + "..." : String(v);
+      return `${k}=${s}`;
+    })
+    .join(" ");
+  const header = `[${ts}] ${name}(${argsStr})`;
+  const sep = "-".repeat(60);
+  try {
+    appendFileSync(file, `${sep}\n${header}\n${sep}\n${result}\n\n`);
+  } catch {}
+}

package/src/mcp-client.js

@@ -0,0 +1,314 @@
+/**
+ * MCP client -- connects to MCP servers, discovers tools, and creates
+ * OpenAI-compatible tool definitions + handler functions.
+ *
+ * Config via MCP_SERVERS env var:
+ *   MCP_SERVERS=name1|transport|url,name2|transport|url
+ *   transport: "sse" (legacy), "http" (Streamable HTTP), or "stdio" (subprocess)
+ *   Examples: screenbox|sse|http://localhost:8080/sse
+ *             memory|stdio|~/agent-memory/agent-memory mcp
+ */
+
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { createLogger } from "./logging/logger.js";
+import { resolveContent } from "./agent/content-resolver.js";
+const log = createLogger("mcp-client");
+
+// Abort signal for MCP calls — set by agent loop, used by handlers
+let _abortSignal = null;
+export function setMcpAbortSignal(signal) { _abortSignal = signal; }
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+const _flintVersion = (() => { try { return JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf-8")).version; } catch { return "?"; } })();
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { detectBase64Content, validateContentType } from "./security/content-validator.js";
+
+// Active MCP client connections
+const clients = new Map(); // name -> { client, transport, url, transportType }
+
+// Allowed MCP URL schemes — only localhost HTTP for now
+const ALLOWED_SCHEMES = new Set(["http:", "https:"]);
+
+function validateMcpUrl(url) {
+  try {
+    const parsed = new URL(url);
+    if (!ALLOWED_SCHEMES.has(parsed.protocol)) {
+      throw new Error(`Unsupported MCP URL scheme: ${parsed.protocol} (allowed: http, https)`);
+    }
+    return parsed;
+  } catch (err) {
+    if (err.message.includes("Unsupported MCP URL")) throw err;
+    throw new Error(`Invalid MCP URL: ${url}`);
+  }
+}
+
+/**
+ * Parse MCP_SERVERS env string into server configs.
+ * Format: "name|transport|url,name2|transport|url2"
+ *
+ * Also takes an array of configs already parsed, as mcpJsonServers returns
+ * them from a Claude-style .mcp.json.
+ */
+export function parseServerConfig(envStr) {
+  if (!envStr) return [];
+  if (Array.isArray(envStr)) return envStr.filter((s) => s && s.name);
+  return envStr.split(",").map((entry) => {
+    const [name, transport, ...urlParts] = entry.trim().split("|");
+    return { name: name.trim(), transport: transport.trim(), url: urlParts.join("|").trim() };
+  }).filter((s) => s.name && s.url);
+}
+
+/**
+ * Server configs from a .mcp.json (the common mcpServers format), the file a host
+ * may give every agent ({"mcpServers": {name: {type, url, headers} or
+ * {command, args, env}}}). The file is the operator's own configuration, so
+ * a stdio command may be a bare name found on PATH.
+ */
+export function mcpJsonServers(json) {
+  const servers = json?.mcpServers || {};
+  return Object.entries(servers).map(([name, s]) => {
+    const transport = s.type || (s.command ? "stdio" : "http");
+    if (transport === "stdio") {
+      const args = Array.isArray(s.args) ? s.args.map(String) : [];
+      return { name, transport, command: s.command, args, env: s.env || null, url: [s.command, ...args].join(" "), fromFile: true };
+    }
+    return { name, transport, url: s.url, headers: s.headers || null, fromFile: true };
+  }).filter((s) => s.name && (s.url || s.command));
+}
+
+/**
+ * Connect to a single MCP server and return its tools + handlers.
+ */
+async function connectServer(serverConfig) {
+  const { name, transport: transportType, url } = serverConfig;
+  const requestInit = serverConfig.headers ? { headers: serverConfig.headers } : undefined;
+
+  let transport;
+  if (transportType === "stdio") {
+    const parts = url.split(/\s+/);
+    const command = serverConfig.command || parts[0];
+    const args = serverConfig.command ? (serverConfig.args || []) : parts.slice(1);
+    // SEC-01: Validate stdio command is an absolute path to prevent command
+    // injection. A .mcp.json is the operator's own file and may name a
+    // command on PATH.
+    const isAbsolute = command.startsWith("/") || /^[a-zA-Z]:[\\/]/.test(command) || command.startsWith("~");
+    if (!isAbsolute && !serverConfig.fromFile) {
+      throw new Error(`MCP stdio command must be an absolute path, got: "${command}"`);
+    }
+    // Sanitize server name to alphanumeric + underscore/dash
+    if (!/^[a-zA-Z0-9_-]+$/.test(name)) {
+      throw new Error(`MCP server name must be alphanumeric (got: "${name}")`);
+    }
+    // The SDK's default hands the server a minimal environment. A server from
+    // a .mcp.json gets ours plus its own env (a host's
+    // servers may read their agent's identity from it).
+    const env = serverConfig.fromFile ? { ...process.env, ...(serverConfig.env || {}) } : undefined;
+    transport = new StdioClientTransport({ command, args, ...(env ? { env } : {}) });
+  } else if (transportType === "sse") {
+    const parsedUrl = validateMcpUrl(url);
+    transport = new SSEClientTransport(parsedUrl, requestInit ? { requestInit } : undefined);
+  } else if (transportType === "http") {
+    const parsedUrl = validateMcpUrl(url);
+    transport = new StreamableHTTPClientTransport(parsedUrl, requestInit ? { requestInit } : undefined);
+  } else {
+    throw new Error(`Unsupported MCP transport: ${transportType} (supported: "sse", "http", "stdio")`);
+  }
+
+  const client = new Client(
+    { name: "flint", version: _flintVersion },
+    { capabilities: {} },
+  );
+
+  await client.connect(transport);
+
+  // Discover tools
+  const { tools: mcpTools } = await client.listTools();
+
+  clients.set(name, { client, transport, url, transportType, command: transportType === "stdio" ? url : undefined });
+
+  // Convert MCP tools -> OpenAI function calling format + handlers
+  const tools = [];
+  const handlers = {};
+
+  for (const tool of mcpTools) {
+    const toolName = `mcp_${name}_${tool.name}`;
+
+    // OpenAI function calling format — prefixed to avoid collisions
+    tools.push({
+      type: "function",
+      function: {
+        name: toolName,
+        description: tool.description || "",
+        parameters: tool.inputSchema || { type: "object", properties: {} },
+      },
+    });
+
+    // Handler that proxies to MCP server (use original name for callTool)
+    const originalName = tool.name;
+    handlers[toolName] = async (args) => {
+      // Timeout wrapper: MCP calls must complete within 60s
+      const MCP_TIMEOUT = 60000;
+      const timeoutController = new AbortController();
+      const timer = setTimeout(() => timeoutController.abort(), MCP_TIMEOUT);
+      // Combine agent abort signal with timeout
+      const combinedSignal = _abortSignal
+        ? AbortSignal.any([_abortSignal, timeoutController.signal])
+        : timeoutController.signal;
+      let result;
+      try {
+        result = await client.callTool(
+          { name: originalName, arguments: args },
+          undefined,
+          { signal: combinedSignal }
+        );
+      } catch (err) {
+        clearTimeout(timer);
+        if (timeoutController.signal.aborted && !_abortSignal?.aborted) {
+          log.warn("mcp-tool-timeout", { tool: toolName, timeout: MCP_TIMEOUT });
+          return `Error: MCP tool call timed out after ${MCP_TIMEOUT / 1000}s. The MCP server may be unresponsive. Try again.`;
+        }
+        throw err;
+      }
+      clearTimeout(timer);
+
+      // Debug: log raw MCP content block types for diagnostics
+      if (result.content?.length) {
+        const blockTypes = result.content.map(b => `${b.type}${b.mimeType ? `(${b.mimeType})` : ""}${b.data ? `[${b.data.length}b]` : ""}`);
+        log.debug("mcp-result-blocks", { tool: toolName, blocks: blockTypes });
+      }
+
+      if (result.isError) {
+        const errText = result.content
+          ?.map((c) => c.text || "")
+          .filter(Boolean)
+          .join("\n") || "MCP tool error";
+        return `Error: ${errText}`;
+      }
+
+      // Resolve content type from raw MCP blocks — no hardcoded type checks
+      const resolved = resolveContent(result.content);
+
+      // Security: validate binary data
+      if (resolved.data) {
+        const { isBinary, detected } = detectBase64Content(resolved.data);
+        if (isBinary && detected?.type === "executable") {
+          return `[Security: MCP server returned executable disguised as ${resolved.type} — blocked]`;
+        }
+      }
+
+      // Media types (image, audio, video) → _image format for agent.js perception
+      if (["image", "audio", "video"].includes(resolved.type)) {
+        const format = (resolved.mimeType || "application/octet-stream").split("/")[1] || "bin";
+        return {
+          _image: true, // generic flag for "needs perception" — not just images
+          data: resolved.data,
+          format,
+          meta: `mcp:${toolName}`,
+          text: resolved.text || undefined,
+          mediaType: resolved.type,
+        };
+      }
+
+      // Mixed content with media → extract media, attach text
+      if (resolved.type === "mixed" && resolved.parts) {
+        const mediaPart = resolved.parts.find(p => ["image", "audio", "video"].includes(p.type));
+        if (mediaPart) {
+          const textParts = resolved.parts.filter(p => p.type === "text").map(p => p.text).filter(Boolean);
+          const format = (mediaPart.mimeType || "application/octet-stream").split("/")[1] || "bin";
+          return {
+            _image: true,
+            data: mediaPart.data,
+            format,
+            meta: `mcp:${toolName}`,
+            text: textParts.join("\n") || undefined,
+            mediaType: mediaPart.type,
+          };
+        }
+      }
+
+      // Text/document/binary — return as string (strip binary data from fallback)
+      if (resolved.text) return resolved.text;
+      const { data: _data, ...safeResolved } = resolved;
+      return JSON.stringify(safeResolved) || "OK";
+    };
+  }
+
+  return { tools, handlers, serverName: name, toolCount: mcpTools.length };
+}
+
+/**
+ * Connect to all configured MCP servers and return combined tools + handlers.
+ */
+export async function connectMcpServers(serversEnv) {
+  const configs = parseServerConfig(serversEnv);
+  if (!configs.length) return { tools: [], handlers: {} };
+
+  const allTools = [];
+  const allHandlers = {};
+  const results = [];
+
+  for (const config of configs) {
+    try {
+      const result = await connectServer(config);
+      allTools.push(...result.tools);
+      Object.assign(allHandlers, result.handlers);
+      results.push({ name: config.name, tools: result.toolCount, ok: true });
+    } catch (err) {
+      results.push({ name: config.name, tools: 0, ok: false, error: err.message });
+    }
+  }
+
+  return { tools: allTools, handlers: allHandlers, results };
+}
+
+/**
+ * Disconnect all MCP clients.
+ */
+export async function disconnectAll() {
+  for (const [name, { client }] of clients) {
+    try {
+      await client.close();
+    } catch {}
+  }
+  clients.clear();
+}
+
+/**
+ * Disconnect a single MCP server by name.
+ */
+export async function disconnectServer(name) {
+  const entry = clients.get(name);
+  if (!entry) return false;
+  try {
+    await entry.client.close();
+  } catch {}
+  clients.delete(name);
+  return true;
+}
+
+/**
+ * Reconnect a single MCP server by name (re-reads config from env).
+ */
+export async function reconnectServer(name, serversEnv) {
+  // Disconnect if already connected
+  await disconnectServer(name);
+  const configs = parseServerConfig(serversEnv);
+  const cfg = configs.find((c) => c.name === name);
+  if (!cfg) throw new Error(`Server "${name}" not found in MCP_SERVERS config`);
+  return connectServer(cfg);
+}
+
+/**
+ * Get list of configured server names (from env) and their connection status.
+ */
+export function getServerStatus(serversEnv) {
+  const configs = parseServerConfig(serversEnv);
+  return configs.map((cfg) => ({
+    name: cfg.name,
+    url: cfg.url,
+    transport: cfg.transport,
+    connected: clients.has(cfg.name),
+  }));
+}

package/src/memory/conversation-digest.js

@@ -0,0 +1,113 @@
+// Conversation Digest — deterministic per-turn log for context retention
+// Stored in sessions/{sessionId}.digest.jsonl
+// Zero LLM cost, zero latency — built from data we already have
+// Injected into system prompt so model can recall previous turns
+
+import { readFileSync, writeFileSync, appendFileSync, existsSync, mkdirSync } from "node:fs";
+import { createHmac } from "node:crypto";
+import path from "node:path";
+import { config } from "../config.js";
+
+function digestPath(sessionId) {
+  return path.join(config.sessionsDir, `${sessionId}.digest.jsonl`);
+}
+
+function hmacPath(sessionId) {
+  return path.join(config.sessionsDir, `${sessionId}.digest.hmac`);
+}
+
+function getHmacKey() {
+  if (process.env.AGENT_MEMORY_HMAC_KEY) return process.env.AGENT_MEMORY_HMAC_KEY;
+  const keyFile = path.join(config.sessionsDir, ".hmac-key");
+  if (existsSync(keyFile)) return readFileSync(keyFile, "utf-8").trim();
+  return "default"; // key file created by session-facts.js
+}
+
+function updateHmac(sessionId) {
+  const fp = digestPath(sessionId);
+  if (!existsSync(fp)) return;
+  const data = readFileSync(fp, "utf-8");
+  const hmac = createHmac("sha256", getHmacKey()).update(data, "utf-8").digest("hex");
+  writeFileSync(hmacPath(sessionId), hmac, "utf-8");
+}
+
+function verifyHmac(sessionId, data) {
+  const hp = hmacPath(sessionId);
+  if (!existsSync(hp)) return true; // no HMAC yet — allow (migration)
+  const stored = readFileSync(hp, "utf-8").trim();
+  const computed = createHmac("sha256", getHmacKey()).update(data, "utf-8").digest("hex");
+  return stored === computed;
+}
+
+/**
+ * Append a digest entry after a completed turn.
+ * @param {string} sessionId
+ * @param {{ userMessage: string, assistantResponse: string, toolsUsed?: string[] }} entry
+ */
+export function appendDigestEntry(sessionId, entry) {
+  if (!sessionId || !entry) return;
+  mkdirSync(config.sessionsDir, { recursive: true });
+
+  const fp = digestPath(sessionId);
+  const existing = existsSync(fp) ? readFileSync(fp, "utf-8").split("\n").filter(Boolean).length : 0;
+
+  const record = {
+    turn: existing + 1,
+    ts: new Date().toISOString(),
+    user: truncate(typeof entry.userMessage === "string" ? entry.userMessage : "[multimodal]", 200),
+    assistant: truncate(entry.assistantResponse || "", 200),
+    tools: entry.toolsUsed || [],
+  };
+
+  appendFileSync(fp, JSON.stringify(record) + "\n", "utf-8");
+  updateHmac(sessionId);
+}
+
+/**
+ * Load all digest entries for a session.
+ */
+export function loadDigest(sessionId) {
+  if (!sessionId) return [];
+  const fp = digestPath(sessionId);
+  if (!existsSync(fp)) return [];
+  const raw = readFileSync(fp, "utf-8");
+  if (!verifyHmac(sessionId, raw)) return [];
+  return raw.split("\n").filter(Boolean).map((line) => {
+    try { return JSON.parse(line); } catch { return null; }
+  }).filter(Boolean);
+}
+
+/**
+ * Format digest for injection into system prompt.
+ * Returns compact text summary of recent turns.
+ * @param {string} sessionId
+ * @param {number} maxEntries - max turns to include (newest)
+ */
+export function getDigestForPrompt(sessionId, maxEntries = 25) {
+  const entries = loadDigest(sessionId);
+  if (!entries.length) return "";
+
+  const recent = entries.slice(-maxEntries);
+  const lines = recent.map((e) => {
+    const tools = e.tools.length ? ` [${e.tools.join(", ")}]` : "";
+    return `Turn ${e.turn}: "${e.user}" → ${e.assistant}${tools}`;
+  });
+
+  return `Conversation digest (${entries.length} turns, showing last ${recent.length}):\n${lines.join("\n")}`;
+}
+
+/**
+ * Clear digest for a session (used by /clear and /new).
+ */
+export function clearDigest(sessionId) {
+  const fp = digestPath(sessionId);
+  if (existsSync(fp)) writeFileSync(fp, "", "utf-8");
+  const hp = hmacPath(sessionId);
+  if (existsSync(hp)) writeFileSync(hp, "", "utf-8");
+}
+
+function truncate(text, maxLen) {
+  if (!text) return "";
+  const clean = text.replace(/\n/g, " ").trim();
+  return clean.length > maxLen ? clean.slice(0, maxLen) + "..." : clean;
+}

package/src/memory/extract-facts.js

@@ -0,0 +1,98 @@
+// Extract key facts from messages being compressed
+// Uses the same OpenRouter API with a cheap/fast model
+
+import { stripTimeStamp } from "../agent/time-stamp.js";
+import { config } from "../config.js";
+import { chatCompletion } from "../api/client.js";
+
+const EXTRACTION_PROMPT = `You are a fact extractor. Given a conversation fragment, extract KEY FACTS that should be remembered.
+
+Rules:
+- Extract only important, reusable facts (not chit-chat)
+- Categories: project (project details), tech (technologies, versions), decision (decisions made), preference (user preferences), bug (bugs found), person (people mentioned), env (environment details)
+- Each fact = one short sentence in the SAME language as the conversation
+- Max 10 facts per fragment
+- Skip trivial things (greetings, confirmations, "ok", "done")
+- If nothing important — return empty array
+
+Return ONLY valid JSON array:
+[{"content": "fact text", "category": "tech"}, ...]`;
+
+// Use a fast cheap model for extraction — don't waste main model tokens
+const EXTRACTION_MODEL = config.extractionModel;
+
+export async function extractFacts(messages) {
+  if (!messages?.length) return [];
+
+  // Build a text representation of messages to analyze
+  const fragments = [];
+  for (const m of messages) {
+    if (m.role === "system") continue;
+    if (m.role === "user") {
+      const text = typeof m.content === "string" ? stripTimeStamp(m.content) : "[multimodal]";
+      fragments.push(`User: ${text}`);
+    } else if (m.role === "assistant") {
+      const text = m.content || "";
+      if (m.tool_calls?.length) {
+        for (const tc of m.tool_calls) {
+          fragments.push(`Agent called: ${tc.function.name}(${tc.function.arguments?.slice(0, 200)})`);
+        }
+      }
+      if (text) fragments.push(`Agent: ${text.slice(0, 500)}`);
+    } else if (m.role === "tool") {
+      const preview = (m.content || "").slice(0, 300);
+      fragments.push(`Tool ${m._toolName || "?"}: ${preview}`);
+    }
+  }
+
+  if (!fragments.length) return [];
+
+  // Limit to ~4000 chars to keep extraction cheap
+  const conversationText = fragments.join("\n").slice(0, 4000);
+
+  try {
+    // Through the one door to the provider. agent.js fires this per user message,
+    // fire-and-forget, so a late reply lands in the NEXT turn's drain rather
+    // than this one's. That is a lag in the session total, not a hole in it; a
+    // reply that arrives after the run ends is lost, which is why the number
+    // can still be a shade low.
+    //
+    // The door refuses when the budget is spent, and that refusal arrives here
+    // as a throw, which the catch below turns into "no facts this time". A
+    // memory that skips a fragment is a smaller problem than a memory that
+    // spends past the ceiling the operator set.
+    const { message } = await chatCompletion(
+      [
+        { role: "system", content: EXTRACTION_PROMPT },
+        { role: "user", content: conversationText },
+      ],
+      [],
+      null,
+      {
+        source: "facts",
+        model: EXTRACTION_MODEL,
+        maxTokens: 1024,
+        temperature: 0,
+        stream: false,
+      },
+    );
+    const text = message?.content || "";
+
+    // Parse JSON from response (handle markdown code blocks)
+    const jsonMatch = text.match(/\[[\s\S]*\]/);
+    if (!jsonMatch) return [];
+
+    const facts = JSON.parse(jsonMatch[0]);
+    if (!Array.isArray(facts)) return [];
+
+    // Validate and clean
+    return facts
+      .filter((f) => f.content && typeof f.content === "string" && f.content.length > 3)
+      .map((f) => ({
+        content: f.content.slice(0, 500),
+        category: f.category || "auto",
+      }));
+  } catch {
+    return [];
+  }
+}