flint-agent 1.14.0

package/src/tools/inbox-tools.js

@@ -0,0 +1,48 @@
+// Inbox tools — check_inbox, dismiss_notifications
+import { readInbox, allInbox, unreadCount } from "../memory/inbox.js";
+
+export function createInboxTools() {
+  return [
+    {
+      type: "function",
+      function: {
+        name: "check_inbox",
+        description: "Read unread notifications (reminders, messages, events). Returns all unread items and marks them as read.",
+        parameters: {
+          type: "object",
+          properties: {
+            all: {
+              type: "boolean",
+              description: "If true, show all recent notifications (including already read). Default: false (unread only).",
+            },
+          },
+        },
+      },
+    },
+  ];
+}
+
+export async function handleInboxTool(name, args) {
+  if (name === "check_inbox") {
+    const showAll = args?.all || false;
+    const items = showAll ? allInbox(30) : readInbox();
+
+    if (items.length === 0) {
+      return showAll ? "No recent notifications." : "No unread notifications.";
+    }
+
+    const lines = items.map((item) => {
+      const status = item.read ? "(read)" : "(new)";
+      const time = item.ts.slice(11, 16); // HH:MM
+      const from = item.from ? ` from ${item.from}` : "";
+      return `[${time}] ${item.type}${from} ${status}: ${item.content}`;
+    });
+
+    const remaining = unreadCount();
+    const footer = remaining > 0 ? `\n${remaining} more unread.` : "";
+
+    return lines.join("\n") + footer;
+  }
+
+  return null;
+}

package/src/tools/mesh.js

@@ -0,0 +1,135 @@
+import { config } from "../config.js";
+
+const MEMORY_URL = config.memoryUrl;
+
+async function meshFetch(path, opts = {}) {
+  const url = `${MEMORY_URL}${path}`;
+  const res = await fetch(url, {
+    headers: { "Content-Type": "application/json", ...opts.headers },
+    ...opts,
+  });
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`Mesh API ${res.status}: ${text}`);
+  }
+  return res.json();
+}
+
+export const tools = [
+  {
+    type: "function",
+    function: {
+      name: "mesh_search",
+      description:
+        "Semantic search across all documents in Mesh memory. " +
+        "Finds documents by meaning, not exact words. " +
+        "Use this to recall past decisions, worklogs, notes, and any saved knowledge.",
+      parameters: {
+        type: "object",
+        properties: {
+          query: { type: "string", description: "What to search for (natural language)" },
+          limit: { type: "number", description: "Max results (default 5)" },
+          tags: {
+            type: "array",
+            items: { type: "string" },
+            description: "Optional tag filter, e.g. ['type:worklog', 'guid:mesh-api']",
+          },
+        },
+        required: ["query"],
+      },
+    },
+  },
+  {
+    type: "function",
+    function: {
+      name: "mesh_add",
+      description:
+        "Save a document to Mesh memory. Auto-tags (date, source) are added automatically. " +
+        "Type and project tags are inferred from similar documents. " +
+        "Use this to remember important information, decisions, worklogs, research results.",
+      parameters: {
+        type: "object",
+        properties: {
+          content: { type: "string", description: "Document text (min 10 chars)" },
+          tags: {
+            type: "array",
+            items: { type: "string" },
+            description: "Optional tags, e.g. ['type:worklog', 'guid:my-project']",
+          },
+        },
+        required: ["content"],
+      },
+    },
+  },
+  {
+    type: "function",
+    function: {
+      name: "mesh_recent",
+      description: "Get recent documents from Mesh memory.",
+      parameters: {
+        type: "object",
+        properties: {
+          limit: { type: "number", description: "Max documents (default 5)" },
+          type: { type: "string", description: "Filter by type: worklog, note, decision, research, etc." },
+        },
+      },
+    },
+  },
+];
+
+export const handlers = {
+  async mesh_search({ query, limit = 5, tags }) {
+    const body = { query, limit };
+    if (tags?.length) body.tags = tags;
+    const data = await meshFetch("/search", {
+      method: "POST",
+      body: JSON.stringify(body),
+    });
+    const results = data.results || [];
+    if (!results.length) return `No results found for: ${query}`;
+    const lines = [`Found ${results.length} results for "${query}":\n`];
+    for (const r of results) {
+      const score = (r.similarity_score || 0).toFixed(3);
+      const date = (r.created_at || "").slice(0, 10);
+      const tags = (r.tags || []).join(", ");
+      const preview = (r.content || "").slice(0, 200);
+      lines.push(`[${r.guid}] score=${score} date=${date}`);
+      lines.push(`  tags: ${tags}`);
+      lines.push(`  ${preview}`);
+      lines.push("");
+    }
+    return lines.join("\n");
+  },
+
+  async mesh_add({ content, tags }) {
+    const body = { content, source: "flint" };
+    if (tags?.length) body.tags = tags;
+    const data = await meshFetch("/", {
+      method: "PUT",
+      body: JSON.stringify(body),
+    });
+    const finalTags = (data.tags || []).join(", ");
+    return (
+      `Document saved: ${data.guid}\n` +
+      `Tags: ${finalTags}\n` +
+      `Auto-tagging will infer additional tags from similar documents.`
+    );
+  },
+
+  async mesh_recent({ limit = 5, type } = {}) {
+    const params = new URLSearchParams({ limit: String(limit) });
+    if (type) params.set("tag", `type:${type}`);
+    const data = await meshFetch(`/?${params}`);
+    if (!Array.isArray(data) || !data.length) return "No documents found.";
+    const lines = [`Recent ${data.length} documents:\n`];
+    for (const doc of data) {
+      const date = (doc.created_at || "").slice(0, 10);
+      const tags = (doc.tags || []).join(", ");
+      const preview = (doc.content || "").slice(0, 120);
+      lines.push(`[${doc.guid}] ${date} [${tags}]`);
+      lines.push(`  ${preview}`);
+      lines.push("");
+    }
+    return lines.join("\n");
+  },
+};

package/src/tools/own-env.js

@@ -0,0 +1,136 @@
+// Flint's own writable environment: a Python venv and an npm prefix that the
+// shell tools put first on PATH.
+//
+// WHY: when a task needs a library Flint does not have (read a PDF, speak a
+// line), the model does the right thing and installs one. On 2026-09-27 in the
+// bench box every such install failed: python3 and pip3 on PATH were another
+// program's venv owned by root, the system python had no pip, npm -g pointed at
+// /usr/local. E-docs-003 took 24 calls, most of them pip, npm and apt attempts
+// refused one after another. A user's machine can be the same: a managed
+// python, a read-only global prefix. So Flint brings a place it may write to,
+// and pip / npm -g land there without the model having to know it exists.
+//
+// It lives next to ~/.flint/plugins, not in FLINT_DATA_DIR: what was installed
+// is the user's tooling, shared by every session, like the plugins.
+//
+// If no python can make a venv, the shell tools run with the PATH they had and
+// the reason is logged: nothing is pretended.
+
+import { existsSync, mkdirSync } from "node:fs";
+import { join, delimiter } from "node:path";
+import { homedir } from "node:os";
+import { spawn } from "node:child_process";
+import { createLogger } from "../logging/logger.js";
+
+const log = createLogger("own-env");
+const isWin = process.platform === "win32";
+
+export function ownEnvPaths(dir = process.env.FLINT_ENV_DIR || join(homedir(), ".flint", "env")) {
+  const venv = join(dir, "py");
+  const npmPrefix = join(dir, "npm");
+  return {
+    dir,
+    venv,
+    venvBin: join(venv, isWin ? "Scripts" : "bin"),
+    venvPython: join(venv, isWin ? "Scripts" : "bin", isWin ? "python.exe" : "python"),
+    npmPrefix,
+    // npm puts global bins in <prefix> on Windows and <prefix>/bin elsewhere,
+    // and global modules in <prefix>/node_modules vs <prefix>/lib/node_modules.
+    npmBin: isWin ? npmPrefix : join(npmPrefix, "bin"),
+    npmModules: isWin ? join(npmPrefix, "node_modules") : join(npmPrefix, "lib", "node_modules"),
+  };
+}
+
+function run(cmd, args, timeoutMs) {
+  return new Promise((resolve) => {
+    let err = "";
+    let child;
+    try {
+      child = spawn(cmd, args, { stdio: ["ignore", "ignore", "pipe"], windowsHide: true });
+    } catch (e) {
+      resolve({ ok: false, err: e.message });
+      return;
+    }
+    const timer = setTimeout(() => { try { child.kill(); } catch {} }, timeoutMs);
+    child.stderr.on("data", (d) => { err += d; });
+    child.on("error", (e) => { clearTimeout(timer); resolve({ ok: false, err: e.message }); });
+    child.on("close", (code) => { clearTimeout(timer); resolve({ ok: code === 0, err: err.trim().slice(-300) }); });
+  });
+}
+
+// On Windows, the first real python of that name on PATH, skipping the Store's
+// App Execution Alias stubs in ...\Microsoft\WindowsApps. Spawned from a process
+// that sits in a job object (seen under the vitest pool on 2026-09-28) the stub
+// printed "AssignProcessToJobObject: (87)" and took the PARENT down with it,
+// not just its own call: a Flint under a supervisor would die on its first
+// shell command. Elsewhere the bare name is fine.
+function resolvePython(name) {
+  if (!isWin) return name;
+  for (const d of (process.env.PATH || "").split(delimiter)) {
+    if (!d || /[\\/]Microsoft[\\/]WindowsApps[\\/]?$/i.test(d)) continue;
+    const exe = join(d, `${name}.exe`);
+    if (existsSync(exe)) return exe;
+  }
+  return null;
+}
+
+// FLINT_OWN_ENV=0 turns it off. The test configs set it: otherwise every
+// test that runs a shell command made a venv in the developer's real
+// ~/.flint/env and waited seconds for it, and the suite went flaky on
+// timeouts (2026-09-28). The own-env test turns it back on in a temp dir.
+function ownEnvOff() {
+  return process.env.FLINT_OWN_ENV === "0";
+}
+
+// One promise per env dir: the first shell command and the boot warm-up share it.
+const pending = new Map();
+
+/**
+ * Make the venv and the npm prefix if they are not there yet. Never throws.
+ * @returns {Promise<{python: boolean, reason?: string}>}
+ */
+export function ensureOwnEnv(paths = ownEnvPaths()) {
+  if (ownEnvOff()) return Promise.resolve({ python: false, reason: "FLINT_OWN_ENV=0" });
+  if (!pending.has(paths.dir)) pending.set(paths.dir, create(paths));
+  return pending.get(paths.dir);
+}
+
+async function create(paths) {
+  try { mkdirSync(paths.npmModules, { recursive: true }); } catch {}
+  if (!isWin) { try { mkdirSync(paths.npmBin, { recursive: true }); } catch {} }
+  if (existsSync(paths.venvPython)) return { python: true };
+
+  // "python3" first: on Linux "python" may be absent or Python 2.
+  const candidates = [process.env.FLINT_PYTHON, ...["python3", "python"].map(resolvePython)].filter(Boolean);
+  const reasons = [];
+  for (const py of candidates) {
+    const r = await run(py, ["-m", "venv", paths.venv], 120000);
+    if (r.ok && existsSync(paths.venvPython)) {
+      log.info("own venv created", { python: py, venv: paths.venv });
+      return { python: true };
+    }
+    reasons.push(`${py}: ${r.err || "no venv made"}`);
+  }
+  const reason = reasons.join("; ");
+  log.warn("own venv not created; pip installs go wherever the system python points", { reason });
+  return { python: false, reason };
+}
+
+/**
+ * The environment a shell command runs with, with Flint's own env first.
+ * Pure: reads the disk for what exists, changes nothing.
+ */
+export function withOwnEnv(env, paths = ownEnvPaths()) {
+  if (ownEnvOff()) return { ...env };
+  const out = { ...env };
+  const front = [];
+  if (existsSync(paths.venvPython)) {
+    front.push(paths.venvBin);
+    out.VIRTUAL_ENV = paths.venv;
+  }
+  front.push(paths.npmBin);
+  out.NPM_CONFIG_PREFIX = paths.npmPrefix;
+  out.NODE_PATH = [paths.npmModules, env.NODE_PATH].filter(Boolean).join(delimiter);
+  out.PATH = [...front, env.PATH].filter(Boolean).join(delimiter);
+  return out;
+}