flint-agent 1.14.0

package/src/security/safety-constants.js

@@ -0,0 +1,34 @@
+// Hardcoded safety constants — NEVER overridable via config or env vars.
+// These are the absolute minimum safety guarantees of the system.
+// Changing these requires a code change and code review.
+
+// Max tool result size in bytes (1 MB) — prevents context flooding
+export const MAX_RESULT_BYTES = 1_048_576;
+
+// Max agent spawn depth — prevents recursive agent chain attacks
+export const MAX_AGENT_DEPTH = 5;
+
+// Max content length for memory entries
+export const MAX_MEMORY_CONTENT = 10_000;
+
+// HMAC algorithm — always SHA-256
+export const HMAC_ALGORITHM = "sha256";
+
+// HMAC key length in bytes
+export const HMAC_KEY_BYTES = 32;
+
+// Security module cannot be disabled in production
+export const ALLOW_SECURITY_DISABLE = process.env.NODE_ENV === "test";
+
+// Minimum security policy — can't go below "normal" in production
+export const MIN_SECURITY_POLICY = "normal";
+
+// These injection patterns are always checked, regardless of config
+export const CORE_INJECTION_PATTERNS = [
+  /\bignore\s+(all\s+)?previous\s+instructions?\b/i,
+  /\byou\s+are\s+now\b.*\bassistant\b/i,
+  /\bforget\s+(everything|all)\b/i,
+  /<\/?system>/i,
+  /\bjailbreak\b/i,
+  /\boverride\s+safety\b/i,
+];

package/src/security/watchdog.js

@@ -0,0 +1,107 @@
+// Watchdog — periodic checks for memory usage and self-modification
+
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const AGENT_SRC_DIR = path.resolve(__dirname, "..");
+
+const HEAP_WARN_BYTES = 500 * 1024 * 1024; // 500 MB
+const CHECK_INTERVAL = 30000; // 30 seconds
+
+let watchdogTimer = null;
+let initialHash = null;
+
+/**
+ * Compute a hash of all file mtimes and sizes in src/.
+ * This detects self-modification of the agent source.
+ */
+function computeSrcHash() {
+  const hasher = crypto.createHash("sha256");
+  try {
+    collectFiles(AGENT_SRC_DIR, hasher, 0);
+  } catch {
+    // If we can't read src, return a sentinel
+    return "unreadable";
+  }
+  return hasher.digest("hex");
+}
+
+function collectFiles(dir, hasher, depth) {
+  if (depth > 10) return;
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  // Sort for consistent hash
+  entries.sort((a, b) => a.name.localeCompare(b.name));
+  for (const entry of entries) {
+    if (entry.name === "node_modules" || entry.name === ".git") continue;
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      collectFiles(full, hasher, depth + 1);
+    } else {
+      try {
+        const stat = fs.statSync(full);
+        hasher.update(`${full}:${stat.size}:${stat.mtimeMs}\n`);
+      } catch {
+        // skip unreadable files
+      }
+    }
+  }
+}
+
+/**
+ * Start the watchdog timer.
+ * @param {object} store - Zustand store
+ * @param {object} config - App config
+ * @param {object} [auditFns] - { auditLog } for logging alerts
+ * @returns {Function} stopWatchdog — call to stop the timer
+ */
+export function startWatchdog(store, config, auditFns) {
+  const auditLog = auditFns?.auditLog || (() => {});
+
+  // Capture initial state
+  initialHash = computeSrcHash();
+
+  watchdogTimer = setInterval(() => {
+    try {
+      // 1. Memory check
+      const mem = process.memoryUsage();
+      if (mem.heapUsed > HEAP_WARN_BYTES) {
+        const mb = (mem.heapUsed / 1024 / 1024).toFixed(0);
+        auditLog("WATCHDOG_ALERT", null, {}, {
+          alert: "high_memory",
+          heapUsedMB: mb,
+        });
+      }
+
+      // 2. Self-modification detection
+      const currentHash = computeSrcHash();
+      if (initialHash && currentHash !== initialHash && currentHash !== "unreadable") {
+        auditLog("WATCHDOG_ALERT", null, {}, {
+          alert: "src_modified",
+          message: "Agent source files have been modified since startup",
+        });
+        // Update hash so we don't spam alerts
+        initialHash = currentHash;
+      }
+    } catch {
+      // Watchdog failures are non-fatal
+    }
+  }, CHECK_INTERVAL);
+
+  // Don't block Node.js exit
+  if (watchdogTimer.unref) watchdogTimer.unref();
+
+  return function stopWatchdog() {
+    if (watchdogTimer) {
+      clearInterval(watchdogTimer);
+      watchdogTimer = null;
+    }
+  };
+}

package/src/sessions.js

@@ -0,0 +1,130 @@
+import fs from "node:fs/promises";
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import path from "node:path";
+import { config } from "./config.js";
+import { stripTimeStamp } from "./agent/time-stamp.js";
+
+// ── HMAC Integrity ──────────────────────────────────────────
+
+function getSessionKey() {
+  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();
+  mkdirSync(config.sessionsDir, { recursive: true });
+  const key = randomBytes(32).toString("hex");
+  writeFileSync(keyFile, key, { encoding: "utf-8", mode: 0o600 });
+  return key;
+}
+
+function computeSessionHmac(data) {
+  return createHmac("sha256", getSessionKey()).update(data, "utf-8").digest("hex");
+}
+
+function hmacPath(sessionId) {
+  return path.join(config.sessionsDir, `${sessionId}.hmac`);
+}
+
+export function generateSessionId() {
+  return new Date().toISOString().slice(0, 19).replace(/[:.]/g, "-");
+}
+
+export async function saveSession(id, { messages, model, inputHistory, profile, plan, pastedImages, lastSummary, provider, sessionCost, sessionPromptTokens, sessionCompletionTokens }) {
+  await fs.mkdir(config.sessionsDir, { recursive: true });
+  const filePath = path.join(config.sessionsDir, `${id}.json`);
+  const data = {
+    id,
+    model,
+    provider: provider || null,
+    updated: new Date().toISOString(),
+    cwd: process.cwd(),
+    messages,
+    inputHistory: inputHistory || [],
+    profile: profile || null,
+    plan: plan || null,
+    pastedImages: pastedImages || [],
+    lastSummary: lastSummary || null,
+    sessionCost: sessionCost || 0,
+    sessionPromptTokens: sessionPromptTokens || 0,
+    sessionCompletionTokens: sessionCompletionTokens || 0,
+  };
+  const json = JSON.stringify(data, null, 2);
+  await fs.writeFile(filePath, json, "utf-8");
+  // Update HMAC
+  writeFileSync(hmacPath(id), computeSessionHmac(json), "utf-8");
+}
+
+export async function loadSession(id) {
+  const filePath = path.join(config.sessionsDir, `${id}.json`);
+  const content = await fs.readFile(filePath, "utf-8");
+
+  // Verify integrity
+  const hp = hmacPath(id);
+  if (existsSync(hp)) {
+    const stored = readFileSync(hp, "utf-8").trim();
+    const computed = computeSessionHmac(content);
+    try {
+      const storedBuf = Buffer.from(stored, "hex");
+      const computedBuf = Buffer.from(computed, "hex");
+      if (storedBuf.length !== computedBuf.length || !timingSafeEqual(storedBuf, computedBuf)) {
+        console.error(`[SECURITY] Session integrity check FAILED for ${id} — possible tampering`);
+        throw new Error(`Session ${id} failed integrity check`);
+      }
+    } catch (err) {
+      if (err.message.includes("integrity check")) throw err;
+      console.error(`[SECURITY] Session HMAC error for ${id} — rejecting`);
+      throw new Error(`Session ${id} failed integrity check`);
+    }
+  } else if (content.trim().length > 0) {
+    // Session data exists without HMAC → auto-heal (migration)
+    writeFileSync(hmacPath(id), computeSessionHmac(content), "utf-8");
+  }
+
+  return JSON.parse(content);
+}
+
+/** A message's text, whether its content is a string or a list of parts. */
+function textOf(content) {
+  if (typeof content === "string") return stripTimeStamp(content);
+  if (Array.isArray(content)) return stripTimeStamp(content.filter((p) => p?.type === "text").map((p) => p.text).join(" ")).trim();
+  return "";
+}
+
+export async function listSessions() {
+  try {
+    const files = await fs.readdir(config.sessionsDir);
+    const sessions = [];
+    for (const file of files) {
+      if (!file.endsWith(".json")) continue;
+      const id = file.replace(".json", "");
+      try {
+        const filePath = path.join(config.sessionsDir, file);
+        const raw = await fs.readFile(filePath, "utf-8");
+        const data = JSON.parse(raw);
+        const userMsg = data.messages?.find((m) => m.role === "user");
+        // The last thing the operator asked, for /resume: the first message
+        // of a long session says little about where it got to.
+        const userMsgs = (data.messages || []).filter((m) => m.role === "user");
+        const lastUser = userMsgs[userMsgs.length - 1];
+        sessions.push({
+          id,
+          model: data.model || "?",
+          updated: data.updated || "",
+          userMessages: userMsgs.length,
+          last: textOf(lastUser?.content),
+          preview: userMsg
+            ? textOf(userMsg.content).length > 60
+              ? textOf(userMsg.content).slice(0, 60) + "..."
+              : textOf(userMsg.content)
+            : "(empty)",
+        });
+      } catch {
+        sessions.push({ id, model: "?", updated: "", preview: "(corrupt)" });
+      }
+    }
+    sessions.sort((a, b) => b.updated.localeCompare(a.updated));
+    return sessions;
+  } catch {
+    return [];
+  }
+}

package/src/spend.js

@@ -0,0 +1,97 @@
+// Spend modes: economy, normal, generous. One switch for how many tokens go
+// into each model call (docs/spend-modes.md).
+//
+// Every saving rule had its own variable and a default tuned for cheap,
+// small-window runs, so a first try with a capable model met an agent that
+// summarised what it had read and searched for tools it had been given.
+// A mode sets them together, the way the care level sets which tools ask.
+// A variable for a single setting still wins over the mode.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+
+export const SPEND_NAMES = ["economy", "normal", "generous"];
+export const DEFAULT_SPEND = "normal";
+
+/**
+ * The table of docs/spend-modes.md, as data. Fractions are of the model's
+ * context window; `cap` is a ceiling in tokens (null: none); `unknown` is
+ * used when the window is not known.
+ */
+export const SPEND_LEVELS = {
+  economy: {
+    description: "fewest tokens a call: tools through search, early compression and swap, saving advice for the model",
+    mcpInlineMax: 10,
+    compress: { fraction: 0.25, cap: 64000, unknown: 32000 },
+    swapFromShare: 0.5,
+    swap: { resultMax: 2048, budgetTokens: 8000, headBytes: 1024 },
+    conv: { fraction: 0.4, cap: 150000, unknown: 60000 },
+    advice: true,
+  },
+  normal: {
+    description: "balanced: up to 30 MCP tools whole, compression at half the window, swap just before it",
+    mcpInlineMax: 30,
+    compress: { fraction: 0.5, cap: 128000, unknown: 64000 },
+    swapFromShare: 0.75,
+    swap: { resultMax: 4096, budgetTokens: 16000, headBytes: 1500 },
+    conv: { fraction: 0.6, cap: 300000, unknown: 100000 },
+    advice: false,
+  },
+  generous: {
+    description: "most context: every tool whole, compression and swap only near the window's edge",
+    mcpInlineMax: 200,
+    compress: { fraction: 0.8, cap: null, unknown: 200000 },
+    swapFromShare: 0.9,
+    swap: { resultMax: 16384, budgetTokens: 64000, headBytes: 4096 },
+    conv: { fraction: 0.85, cap: null, unknown: 200000 },
+    advice: false,
+  },
+};
+
+function spendFile() {
+  const dir = process.env.FLINT_DATA_DIR ? path.resolve(process.env.FLINT_DATA_DIR) : path.join(homedir(), ".flint");
+  return path.join(dir, "spend.json");
+}
+
+/** A level name from loose input ("e", "Economy", "gen"), or null. */
+export function parseSpendName(input) {
+  const s = String(input || "").trim().toLowerCase();
+  if (!s) return null;
+  return SPEND_NAMES.find((n) => n === s || n.startsWith(s)) || null;
+}
+
+/** FLINT_SPEND, else the saved choice, else normal. An unknown name reads as normal. */
+export function getSpendLevel(env = process.env) {
+  const fromEnv = parseSpendName(env.FLINT_SPEND);
+  if (fromEnv) return fromEnv;
+  try {
+    const f = spendFile();
+    if (existsSync(f)) {
+      const saved = parseSpendName(JSON.parse(readFileSync(f, "utf8")).level);
+      if (saved) return saved;
+    }
+  } catch {}
+  return DEFAULT_SPEND;
+}
+
+/** Save a level; returns the level, or null for a name that is not one. */
+export function setSpendLevel(name) {
+  const level = parseSpendName(name);
+  if (!level) return null;
+  const f = spendFile();
+  mkdirSync(path.dirname(f), { recursive: true });
+  writeFileSync(f, JSON.stringify({ level }, null, 2) + "\n", "utf8");
+  return level;
+}
+
+export function spendSettings(level = getSpendLevel()) {
+  return SPEND_LEVELS[level] || SPEND_LEVELS[DEFAULT_SPEND];
+}
+
+/** A window share with a ceiling, or the fallback when the window is unknown. */
+export function windowShare({ fraction, cap, unknown }, window) {
+  if (!window) return unknown;
+  const v = Math.floor(window * fraction);
+  return cap ? Math.min(v, cap) : v;
+}

package/src/startup-watchdog.js

@@ -0,0 +1,59 @@
+// Startup watchdog: if Flint has not finished starting within the timeout, it
+// exits rather than hang. Time spent waiting for the operator is not startup.
+//
+// Owner, 2026-10-01, first run on a fresh machine: the first-run wizard and the
+// "How careful should Flint be?" question were on screen, and the watchdog
+// killed Flint at 30 s while it waited for an answer. The launcher's
+// "loading..." spinner was also still repainting over both prompts, because the
+// child only told it to stop once the main UI had drawn.
+
+const TIMEOUT_MS = 30000;
+
+let timer = null;
+let done = false;
+
+function arm() {
+  if (done) return;
+  if (timer) clearTimeout(timer);
+  timer = setTimeout(() => {
+    process.stderr.write(`\n[WATCHDOG] Startup timeout (${TIMEOUT_MS / 1000}s) -- force exit\n`);
+    process.exit(1);
+  }, TIMEOUT_MS);
+  timer.unref?.();
+}
+
+/** Start counting. Called once, at the top of index.js. */
+export function startStartupWatchdog() {
+  done = false;
+  arm();
+}
+
+/** Startup finished: stop counting for good. */
+export function clearStartupWatchdog() {
+  done = true;
+  if (timer) clearTimeout(timer);
+  timer = null;
+}
+
+/** For tests: is the watchdog currently counting? */
+export function isStartupWatchdogArmed() {
+  return timer !== null;
+}
+
+/**
+ * Run an interactive startup step: no countdown while the operator answers,
+ * and the launcher spinner is told to stop before the question is drawn.
+ * The countdown restarts in full once the step is over.
+ */
+export async function whileWaitingForOperator(fn) {
+  if (timer) clearTimeout(timer);
+  timer = null;
+  // Same message the main UI sends when it has drawn; the launcher only
+  // stops its spinner, so sending it early is harmless.
+  try { process.send?.({ type: "flint:ready" }); } catch { /* no IPC channel */ }
+  try {
+    return await fn();
+  } finally {
+    arm();
+  }
+}

package/src/stdio/args.js

@@ -0,0 +1,71 @@
+// Command-line flags of the stdio mode.
+//
+// Flint takes the flags agent CLIs commonly take for the same job, so a host that
+// drives `claude` as a long-lived subprocess can start Flint with the same command line:
+//
+//   flint --print --verbose --model <id> \
+//         --input-format stream-json --output-format stream-json \
+//         [--session-id <id> | --resume <id>] [--dangerously-skip-permissions] \
+//         [--system-prompt-file <path>] [--append-system-prompt <text>] \
+//         [--mcp-config <path>]
+//
+// `--stdio` alone means the same thing. Flags such CLIs have and Flint does
+// not need (--add-dir, --max-turns, ...) are accepted and ignored, so a host
+// passing them does not have to know which agent it is talking to.
+
+const VALUE_FLAGS = new Set([
+  "--model", "--session-id", "--resume", "-r", "--system-prompt", "--system-prompt-file",
+  "--append-system-prompt", "--append-system-prompt-file", "--mcp-config", "--input-format",
+  "--output-format", "--cwd", "--max-turns", "--add-dir", "--permission-mode",
+  "--allowedTools", "--allowed-tools", "--disallowedTools", "--disallowed-tools",
+  "--fallback-model", "--settings",
+]);
+
+/** Session ids become file names: letters, digits, dash and underscore only. */
+export function isSafeSessionId(id) {
+  return typeof id === "string" && /^[A-Za-z0-9_-]{1,128}$/.test(id);
+}
+
+/**
+ * The stdio-mode options in argv, or null when Flint was not started in it.
+ * Throws on a value that cannot be used, so the host sees the reason on
+ * stderr and a non-zero exit instead of a session that quietly ignores it.
+ */
+export function parseStdioArgs(argv) {
+  const args = argv.slice(2);
+  const values = {};
+  const flags = new Set();
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    const eq = a.startsWith("--") ? a.indexOf("=") : -1;
+    if (eq > 0) { values[a.slice(0, eq)] = a.slice(eq + 1); continue; }
+    if (VALUE_FLAGS.has(a)) { values[a] = args[i + 1]; i++; continue; }
+    flags.add(a);
+  }
+  const streaming = values["--input-format"] === "stream-json" || values["--output-format"] === "stream-json";
+  if (!flags.has("--stdio") && !streaming) return null;
+  if (values["--input-format"] && values["--input-format"] !== "stream-json") {
+    throw new Error(`--input-format ${values["--input-format"]} is not supported; use stream-json`);
+  }
+  if (values["--output-format"] && values["--output-format"] !== "stream-json") {
+    throw new Error(`--output-format ${values["--output-format"]} is not supported; use stream-json`);
+  }
+  const resume = values["--resume"] ?? values["-r"] ?? null;
+  const sessionId = resume ?? values["--session-id"] ?? null;
+  if (sessionId != null && !isSafeSessionId(sessionId)) {
+    throw new Error(`session id "${sessionId}" may contain only letters, digits, - and _`);
+  }
+  return {
+    model: values["--model"] || null,
+    sessionId,
+    resume: resume != null,
+    systemPrompt: values["--system-prompt"] ?? null,
+    systemPromptFile: values["--system-prompt-file"] ?? null,
+    appendSystemPrompt: values["--append-system-prompt"] ?? null,
+    appendSystemPromptFile: values["--append-system-prompt-file"] ?? null,
+    mcpConfig: values["--mcp-config"] ?? null,
+    cwd: values["--cwd"] ?? null,
+    skipPermissions: flags.has("--dangerously-skip-permissions") || values["--permission-mode"] === "bypassPermissions",
+    verbose: flags.has("--verbose"),
+  };
+}

package/src/stdio/guard.js

@@ -0,0 +1,59 @@
+// First thing index.js imports, so it runs before any other module is
+// evaluated. In the stdio mode stdout carries the protocol and nothing else:
+// one stray console.log from any module would be a line the host cannot
+// parse. So here, before anything can print:
+//
+//   - the real stdout writer is kept for the protocol (protocolWrite);
+//   - process.stdout.write and console.log/info/warn/error go to stderr;
+//   - --cwd is applied, so every module sees the agent's own folder;
+//   - FLINT_DATA_DIR defaults to ~/.flint, so sessions and the task database
+//     live in the home of the user the host runs this agent as (a host that
+//     gives every agent its own user and HOME) instead of the checkout.
+//
+// Outside the stdio mode this module does nothing.
+
+import { format } from "node:util";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { parseStdioArgs } from "./args.js";
+
+let parsed = null;
+let parseError = null;
+try {
+  parsed = parseStdioArgs(process.argv);
+} catch (err) {
+  parseError = err;
+}
+
+export const stdioArgs = parsed;
+export const stdioArgsError = parseError;
+
+const realWrite = process.stdout.write.bind(process.stdout);
+
+/** Write one protocol object as a line on the real stdout. */
+export function protocolWrite(obj) {
+  realWrite(JSON.stringify(obj) + "\n");
+}
+
+if (parsed || parseError) {
+  const toStderr = (...args) => { process.stderr.write(format(...args) + "\n"); };
+  process.stdout.write = (chunk, encoding, cb) => process.stderr.write(chunk, encoding, cb);
+  console.log = toStderr;
+  console.info = toStderr;
+  console.warn = toStderr;
+  console.error = toStderr;
+  console.debug = toStderr;
+  if (parseError) {
+    process.stderr.write(`[flint] ${parseError.message}\n`);
+    process.exit(2);
+  }
+  if (parsed.cwd) {
+    try {
+      process.chdir(parsed.cwd);
+    } catch (err) {
+      process.stderr.write(`[flint] cannot use --cwd ${parsed.cwd}: ${err.message}\n`);
+      process.exit(2);
+    }
+  }
+  if (!process.env.FLINT_DATA_DIR) process.env.FLINT_DATA_DIR = join(homedir(), ".flint");
+}