flint-agent 1.14.0

package/src/bus/index.js

@@ -0,0 +1,270 @@
+// Unified Message Bus — SQLite-backed priority queue
+// All input channels (TUI, API, child agents, scheduler) push here.
+// Agent loop drains by priority. Crash-safe: pending messages survive restart.
+
+import { getDb } from "../tasks/db.js";
+import { createLogger } from "../logging/logger.js";
+
+const log = createLogger("bus");
+
+// Ring buffer for recent bus events (for /bus/log endpoint)
+const _eventLog = [];
+const MAX_EVENTS = 100;
+function logEvent(type, msg) {
+  _eventLog.push({ type, ts: new Date().toISOString(), ...msg });
+  if (_eventLog.length > MAX_EVENTS) _eventLog.shift();
+}
+
+/**
+ * Get recent bus events (last N).
+ * @param {number} [limit=50]
+ */
+export function recentEvents(limit = 50) {
+  return _eventLog.slice(-limit);
+}
+
+// Priority levels (lower = higher priority)
+export const PRIORITY = {
+  USER: 0,      // TUI input, /commands
+  API: 1,       // HTTP /message from paired client
+  AGENT: 2,     // Child agent responses
+  TASK: 3,      // Scheduled tasks firing
+  EVENT: 4,     // Email, Telegram, external events
+  SYSTEM: 5,    // BG process alerts, heartbeat
+};
+
+/**
+ * Push a message onto the bus.
+ * @param {object} msg
+ * @param {string} msg.channel - 'user' | 'api' | 'agent' | 'scheduler' | 'telegram' | 'email' | 'voice'
+ * @param {string} msg.content - Message text
+ * @param {number} [msg.priority=5] - 0=highest, 10=lowest
+ * @param {string} [msg.source] - Agent port, email address, etc.
+ * @param {object} [msg.metadata] - Channel-specific data (stored as JSON)
+ * @param {string} [msg.sessionId] - Session context
+ * @returns {{ id: number }} Inserted message ID
+ */
+export function push({ channel, content, priority, source, metadata, sessionId }) {
+  const db = getDb();
+  const result = db.prepare(
+    `INSERT INTO message_queue (channel, content, priority, source, metadata, session_id)
+     VALUES (?, ?, ?, ?, ?, ?)`
+  ).run(
+    channel,
+    content,
+    priority ?? PRIORITY.SYSTEM,
+    source || null,
+    metadata ? JSON.stringify(metadata) : null,
+    sessionId || null,
+  );
+  const id = result.lastInsertRowid;
+  log.debug("PUSH", { id, channel, priority: priority ?? PRIORITY.SYSTEM, source });
+  logEvent("push", { id: Number(id), channel, priority: priority ?? PRIORITY.SYSTEM, source, contentPreview: content.slice(0, 80) });
+  return { id: Number(id) };
+}
+
+/**
+ * Drain the highest-priority pending message.
+ * Atomically sets status = 'processing'.
+ * @returns {object|null} Message row or null if queue empty
+ */
+export function drain() {
+  const db = getDb();
+  // Single atomic operation: select + update
+  const msg = db.prepare(
+    `SELECT * FROM message_queue
+     WHERE status = 'pending'
+     ORDER BY priority ASC, created_at ASC
+     LIMIT 1`
+  ).get();
+
+  if (!msg) return null;
+
+  db.prepare(
+    `UPDATE message_queue SET status = 'processing', processed_at = datetime('now') WHERE id = ?`
+  ).run(msg.id);
+
+  log.debug("DRAIN", { id: msg.id, channel: msg.channel, priority: msg.priority });
+  logEvent("drain", { id: msg.id, channel: msg.channel, priority: msg.priority });
+
+  return {
+    ...msg,
+    status: "processing",
+    metadata: msg.metadata ? JSON.parse(msg.metadata) : null,
+  };
+}
+
+/**
+ * Mark a message as successfully processed.
+ * @param {number} id - Message ID
+ * @param {string} [result] - Agent response summary (for audit)
+ */
+export function complete(id, result) {
+  const db = getDb();
+  db.prepare(
+    `UPDATE message_queue SET status = 'done', result = ?, processed_at = datetime('now') WHERE id = ?`
+  ).run(result || null, id);
+  log.debug("DONE", { id, resultLen: result?.length || 0 });
+  logEvent("done", { id, resultPreview: (result || "").slice(0, 80) });
+}
+
+/**
+ * Mark a message as failed.
+ * @param {number} id - Message ID
+ * @param {string} [error] - Error description
+ */
+/**
+ * Take back a message that is still waiting, for the operator to edit it
+ * (Esc on an unread message). Only a pending message: once the agent has
+ * taken it, it is read and cannot be recalled.
+ * @returns {boolean} true if it was still pending and is now cancelled
+ */
+export function cancelPending(id) {
+  const db = getDb();
+  const r = db.prepare(
+    `UPDATE message_queue SET status = 'failed', result = 'recalled for editing', processed_at = datetime('now') WHERE id = ? AND status = 'pending'`
+  ).run(id);
+  if (r.changes) logEvent("cancel", { id });
+  return r.changes > 0;
+}
+
+export function fail(id, error) {
+  const db = getDb();
+  db.prepare(
+    `UPDATE message_queue SET status = 'failed', result = ?, processed_at = datetime('now') WHERE id = ?`
+  ).run(error || "unknown error", id);
+  log.warn("FAIL", { id, error });
+  logEvent("fail", { id, error });
+}
+
+/**
+ * Crash recovery: reset stale 'processing' messages back to 'pending'.
+ * Called on startup to recover from mid-processing crashes.
+ * @param {number} [staleMinutes=5] - Messages processing longer than this are stale
+ * @returns {number} Number of recovered messages
+ */
+export function recover(staleMinutes = 5) {
+  const db = getDb();
+  const result = db.prepare(
+    `UPDATE message_queue
+     SET status = 'pending', processed_at = NULL
+     WHERE status = 'processing'
+       AND processed_at < datetime('now', ? || ' minutes')`
+  ).run(`-${staleMinutes}`);
+  const count = result.changes;
+  if (count > 0) {
+    log.info("RECOVER", { count, staleMinutes });
+    logEvent("recover", { count, staleMinutes });
+  }
+  return count;
+}
+
+// Older than this, nobody is still waiting for the answer: an API caller's
+// sync wait is 180 s, a child agent's report is about work long gone.
+const LEFTOVER_MAX_AGE_MINUTES = 10;
+
+/**
+ * Start-up: put this session's half-done messages back in the queue, and
+ * expire what an earlier run left for someone else.
+ *
+ * Owner, 2026-10-02: a console started with --new drained a benchmark task an
+ * API client had sent five days earlier to another session, and ran it with
+ * the API's automatic approval. A message belongs to the session it was sent
+ * to and to the minutes after it was sent. Expired: any message of another
+ * session, and any message older than LEFTOVER_MAX_AGE_MINUTES. Reminders
+ * (channel 'scheduler') are kept: they are the operator's own schedule.
+ *
+ * @param {object} opts
+ * @param {string} opts.sessionId - The session this start runs
+ * @returns {{ recovered: number, expired: number }}
+ */
+export function prepareQueueAtStart({ sessionId }) {
+  const recovered = recover();
+  const db = getDb();
+  const r = db.prepare(
+    `UPDATE message_queue
+     SET status = 'failed', result = 'expired: left in the queue by an earlier run', processed_at = datetime('now')
+     WHERE status IN ('pending', 'processing')
+       AND channel != 'scheduler'
+       AND ((session_id IS NOT NULL AND session_id != ?)
+            OR created_at < datetime('now', ? || ' minutes'))`
+  ).run(sessionId || "", `-${LEFTOVER_MAX_AGE_MINUTES}`);
+  const expired = r.changes;
+  if (expired > 0) {
+    log.info("EXPIRE", { expired, sessionId });
+    logEvent("expire", { count: expired });
+  }
+  return { recovered, expired };
+}
+
+/**
+ * Cleanup old processed messages.
+ * @param {number} [doneHours=24] - Delete 'done' messages older than this
+ * @param {number} [failedDays=7] - Delete 'failed' messages older than this
+ * @returns {{ done: number, failed: number }} Counts of deleted messages
+ */
+export function cleanup(doneHours = 24, failedDays = 7) {
+  const db = getDb();
+  const doneResult = db.prepare(
+    `DELETE FROM message_queue
+     WHERE status = 'done'
+       AND processed_at < datetime('now', ? || ' hours')`
+  ).run(`-${doneHours}`);
+  const failedResult = db.prepare(
+    `DELETE FROM message_queue
+     WHERE status = 'failed'
+       AND processed_at < datetime('now', ? || ' days')`
+  ).run(`-${failedDays}`);
+  const counts = { done: doneResult.changes, failed: failedResult.changes };
+  if (counts.done + counts.failed > 0) {
+    log.debug("CLEANUP", counts);
+  }
+  return counts;
+}
+
+/**
+ * Get queue statistics for StatusBar and monitoring.
+ * @returns {{ pending: number, processing: number, done: number, failed: number, total: number }}
+ */
+export function stats() {
+  const db = getDb();
+  const rows = db.prepare(
+    `SELECT status, COUNT(*) as count FROM message_queue GROUP BY status`
+  ).all();
+  const s = { pending: 0, processing: 0, done: 0, failed: 0, total: 0 };
+  for (const row of rows) {
+    s[row.status] = row.count;
+    s.total += row.count;
+  }
+  return s;
+}
+
+/**
+ * Get all pending messages (for inspection, not processing).
+ * @param {number} [limit=50]
+ * @returns {object[]}
+ */
+export function pending(limit = 50) {
+  const db = getDb();
+  return db.prepare(
+    `SELECT * FROM message_queue
+     WHERE status = 'pending'
+     ORDER BY priority ASC, created_at ASC
+     LIMIT ?`
+  ).all(limit).map(row => ({
+    ...row,
+    metadata: row.metadata ? JSON.parse(row.metadata) : null,
+  }));
+}
+
+/**
+ * Get message by ID (for polling result).
+ * @param {number} id
+ * @returns {object|null}
+ */
+export function getMessage(id) {
+  const db = getDb();
+  const row = db.prepare("SELECT * FROM message_queue WHERE id = ?").get(id);
+  if (!row) return null;
+  return { ...row, metadata: row.metadata ? JSON.parse(row.metadata) : null };
+}

package/src/bus/plugins.js

@@ -0,0 +1,65 @@
+// Channel plugin loader
+// Scans plugins/ directory for channel plugins.
+// Each plugin: { name, priority, start(bus), stop() }
+
+import { createLogger } from "../logging/logger.js";
+import { readdirSync } from "node:fs";
+import path from "node:path";
+import { config } from "../config.js";
+
+const log = createLogger("bus-plugins");
+
+const _plugins = new Map(); // name → plugin instance
+
+/**
+ * Load and start all channel plugins from plugins/ directory.
+ * @param {object} bus - bus module (push, drain, etc.)
+ */
+export async function loadPlugins(bus) {
+  const pluginsDir = path.join(config.projectRoot, "plugins");
+  let files;
+  try {
+    files = readdirSync(pluginsDir).filter(f => f.endsWith(".js"));
+  } catch {
+    // No plugins directory — that's fine
+    return;
+  }
+
+  for (const file of files) {
+    try {
+      const mod = await import(path.join(pluginsDir, file));
+      const plugin = mod.default || mod;
+      if (!plugin.name || !plugin.start) {
+        log.warn(`Plugin ${file} missing name or start(), skipping`);
+        continue;
+      }
+      await plugin.start(bus);
+      _plugins.set(plugin.name, plugin);
+      log.info(`Plugin loaded: ${plugin.name}`, { file, priority: plugin.priority });
+    } catch (err) {
+      log.error(`Failed to load plugin ${file}: ${err.message}`);
+    }
+  }
+}
+
+/**
+ * Stop all loaded plugins.
+ */
+export async function stopPlugins() {
+  for (const [name, plugin] of _plugins) {
+    try {
+      if (plugin.stop) await plugin.stop();
+      log.debug(`Plugin stopped: ${name}`);
+    } catch (err) {
+      log.error(`Failed to stop plugin ${name}: ${err.message}`);
+    }
+  }
+  _plugins.clear();
+}
+
+/**
+ * Get list of loaded plugin names.
+ */
+export function listPlugins() {
+  return [..._plugins.keys()];
+}

package/src/child-idle.js

@@ -0,0 +1,14 @@
+// When a child agent counts as idle, for its idle timeout (index.js).
+//
+// The timeout was reset only when the store's message count changed, and a
+// turn writes its messages back at the end. A child given a research task
+// shut itself down one minute in, between two browser calls, with nothing
+// written (2026-10-02, agent@3010). Working is not idle.
+
+/** A turn, queued work, or a stoppable task in flight: not idle. */
+export function childBusy({ processing, processingCount, agentStatus, abortController } = {}) {
+  return !!processing
+    || (processingCount || 0) > 0
+    || (!!agentStatus && agentStatus !== "idle")
+    || !!abortController;
+}

package/src/cli.js

@@ -0,0 +1,118 @@
+import chalk from "chalk";
+import { listSessions } from "./sessions.js";
+import { migrateEnvKey, setKey, hasKey } from "./providers/keys.js";
+import { listProviders, getProvider } from "./providers/registry.js";
+import { setActiveProvider, setLastModel } from "./providers/state.js";
+import { config, needsFirstRunSetup } from "./config.js";
+
+// -- CLI argument parsing --
+
+export function getArgValue(name) {
+  const idx = process.argv.indexOf(name);
+  return (idx !== -1 && process.argv[idx + 1]) ? process.argv[idx + 1] : null;
+}
+
+export function parseCLI() {
+  const args = process.argv;
+  if (args.includes("--list")) return { action: "list" };
+  if (args.includes("--headless")) {
+    const taskIdx = args.indexOf("--task");
+    const task = (taskIdx !== -1 && args[taskIdx + 1]) ? args[taskIdx + 1] : null;
+    const cwdIdx = args.indexOf("--cwd");
+    const cwd = (cwdIdx !== -1 && args[cwdIdx + 1]) ? args[cwdIdx + 1] : null;
+    const budgetIdx = args.indexOf("--budget");
+    const budget = (budgetIdx !== -1 && args[budgetIdx + 1]) ? parseFloat(args[budgetIdx + 1]) : null;
+    return { action: "headless", task, cwd, budget };
+  }
+  if (args.includes("--new")) return { action: "new" };
+  if (args.includes("--last")) return { action: "last" };
+  const idx = args.indexOf("--session");
+  if (idx !== -1 && args[idx + 1])
+    return { action: "resume", id: args[idx + 1] };
+  return { action: "new" };
+}
+
+export async function runListSessions() {
+  const sessions = await listSessions();
+  if (!sessions.length) {
+    console.log(chalk.gray("No sessions found."));
+  } else {
+    console.log(chalk.cyan.bold("\n  Sessions:\n"));
+    for (const s of sessions) {
+      console.log(`  ${chalk.yellow(s.id)}  ${chalk.gray(s.model)}  ${s.preview}`);
+    }
+    console.log();
+  }
+  process.exit(0);
+}
+
+export async function migrateKeys() {
+  await migrateEnvKey("OPENROUTER_API_KEY", "openrouter");
+  await migrateEnvKey("OPENAI_API_KEY", "openai");
+  await migrateEnvKey("ANTHROPIC_API_KEY", "anthropic");
+}
+
+/** Real provider keys are long tokens; a few characters is a stray keypress. */
+export function looksLikeApiKey(key) {
+  const k = String(key || "").trim();
+  return k.length >= 20 && !/\s/.test(k);
+}
+
+export async function runFirstRunSetup(cli) {
+  if (!needsFirstRunSetup || cli.action === "list") return;
+
+  const readline = await import("node:readline");
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const ask = (q) => new Promise((r) => rl.question(q, r));
+
+  console.log(chalk.cyan("\n  +-------------------------------------+"));
+  console.log(chalk.cyan("  |     Flint Agent -- First Run       |"));
+  console.log(chalk.cyan("  +-------------------------------------+\n"));
+  console.log(chalk.gray("  No API keys found. Let's set one up.\n"));
+
+  const providers = listProviders().filter((p) => p.keyRequired);
+  for (let i = 0; i < providers.length; i++) {
+    console.log(chalk.white(`  ${i + 1}. ${providers[i].name} (${providers[i].id})`));
+  }
+  console.log(chalk.white(`  ${providers.length + 1}. Ollama (local, no key needed)`));
+  console.log();
+
+  const choice = await ask(chalk.cyan("  Choose provider (number): "));
+  const idx = parseInt(choice.trim(), 10) - 1;
+
+  if (idx === providers.length) {
+    config.provider = "ollama";
+    setActiveProvider("ollama");
+    config.model = "llama3.2";
+    console.log(chalk.green("\n  Selected Ollama. Make sure it's running on localhost:11434.\n"));
+  } else if (idx >= 0 && idx < providers.length) {
+    const selected = providers[idx];
+    // Owner, 2026-10-01: the spinner hid this prompt, a stray "1" was saved as
+    // the OpenRouter key, and the wizard said "Key saved". Anything this short
+    // is not a key, so ask again rather than store it.
+    let trimmedKey = "";
+    for (let attempt = 0; attempt < 3; attempt++) {
+      trimmedKey = (await ask(chalk.cyan(`  Enter ${selected.name} API key: `))).trim();
+      if (!trimmedKey || looksLikeApiKey(trimmedKey)) break;
+      console.log(chalk.yellow("  That does not look like an API key (too short). Paste the full key."));
+      trimmedKey = "";
+    }
+    if (trimmedKey) {
+      await setKey(selected.id, trimmedKey);
+      config.provider = selected.id;
+      config.apiKey = trimmedKey;
+      setActiveProvider(selected.id);
+      config.model = selected.defaultModel;
+      console.log(chalk.green(`\n  Key saved (encrypted). Provider: ${selected.name}, Model: ${selected.defaultModel}\n`));
+    } else {
+      console.log(chalk.yellow("\n  No key entered. You can add one later with /key <provider>.\n"));
+    }
+  } else {
+    console.log(chalk.yellow("\n  Invalid choice. You can set up later with /key <provider>.\n"));
+  }
+
+  // Once, at the end of the first run: where Flint lives (owner, 2026-10-02:
+  // one line, no nagging).
+  console.log(chalk.gray("  Flint is free and open source: https://klymentiev.com/projects/flint\n"));
+  rl.close();
+}