flint-agent 1.14.0

package/src/agent/knowledge.js

@@ -0,0 +1,114 @@
+/**
+ * Knowledge Store — backend-agnostic facts & patterns
+ *
+ * Stores learned facts and patterns. Retrieves by keyword match.
+ * Backend adapters: text file (default), mesh, agent-memory.
+ *
+ * Used by:
+ *   - Layer 3 (Execution): retrieve before planning
+ *   - Layer 4 (Verification Gate): store after successful task
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { createLogger } from "../logging/logger.js";
+import { config } from "../config.js";
+
+const log = createLogger("knowledge");
+
+// --- Storage path ---
+const KNOWLEDGE_DIR = join(config.sessionsDir || process.cwd(), "..", "knowledge");
+const FACTS_FILE = join(KNOWLEDGE_DIR, "facts.jsonl");
+
+// --- In-memory cache ---
+let _facts = [];
+let _loaded = false;
+
+/**
+ * Load facts from disk (lazy, once).
+ */
+function _ensureLoaded() {
+  if (_loaded) return;
+  _loaded = true;
+  try {
+    if (existsSync(FACTS_FILE)) {
+      const lines = readFileSync(FACTS_FILE, "utf-8").split("\n").filter(Boolean);
+      _facts = lines.map(l => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
+      log.info("loaded", { count: _facts.length });
+    }
+  } catch (e) {
+    log.warn("load-failed", { error: e.message });
+  }
+}
+
+/**
+ * Store a fact or pattern.
+ * @param {object} entry - { type: "fact"|"pattern", text, context, confidence, triggers }
+ */
+export function store(entry) {
+  _ensureLoaded();
+  entry.timestamp = new Date().toISOString();
+  entry.confidence = entry.confidence || 0.5;
+  _facts.push(entry);
+
+  try {
+    mkdirSync(KNOWLEDGE_DIR, { recursive: true });
+    writeFileSync(FACTS_FILE, _facts.map(f => JSON.stringify(f)).join("\n") + "\n");
+    log.info("stored", { type: entry.type, text: (entry.text || "").slice(0, 60) });
+  } catch (e) {
+    log.warn("store-failed", { error: e.message });
+  }
+}
+
+/**
+ * Retrieve relevant facts/patterns for a task.
+ * @param {string} query - task description or keywords
+ * @param {number} limit - max results
+ * @returns {Array} matching entries, sorted by relevance
+ */
+export function retrieve(query, limit = 3) {
+  _ensureLoaded();
+  if (!_facts.length || !query) return [];
+
+  const words = query.toLowerCase().split(/\s+/).filter(w => w.length > 2);
+  const scored = _facts.map(f => {
+    const text = `${f.text || ""} ${(f.triggers || []).join(" ")} ${f.context || ""}`.toLowerCase();
+    const matches = words.filter(w => text.includes(w)).length;
+    return { ...f, score: matches * (f.confidence || 0.5) };
+  }).filter(f => f.score > 0);
+
+  scored.sort((a, b) => b.score - a.score);
+  return scored.slice(0, limit);
+}
+
+/**
+ * Update confidence of a fact (called when pattern reused successfully).
+ * @param {number} index - fact index
+ * @param {number} delta - confidence change (+0.1 on success, -0.1 on failure)
+ */
+export function updateConfidence(index, delta) {
+  _ensureLoaded();
+  if (index >= 0 && index < _facts.length) {
+    _facts[index].confidence = Math.max(0, Math.min(1, (_facts[index].confidence || 0.5) + delta));
+    try {
+      writeFileSync(FACTS_FILE, _facts.map(f => JSON.stringify(f)).join("\n") + "\n");
+    } catch {}
+  }
+}
+
+/**
+ * Get all facts (for debugging/display).
+ */
+export function getAll() {
+  _ensureLoaded();
+  return [..._facts];
+}
+
+/**
+ * Format retrieved knowledge for injection into prompt.
+ */
+export function formatForPrompt(entries) {
+  if (!entries.length) return null;
+  const lines = entries.map(e => `- [${e.type}] ${e.text}`);
+  return `[KNOWLEDGE — learned from previous tasks]\n${lines.join("\n")}`;
+}

package/src/agent/learning.js

@@ -0,0 +1,180 @@
+/**
+ * Learning System — extract facts & patterns from completed tasks
+ *
+ * After successful task completion:
+ * 1. Analyze tool call sequence
+ * 2. Extract reusable patterns (e.g. "search → read → save → open")
+ * 3. Extract facts (e.g. "desktop_shell works for remote file creation")
+ * 4. Store via knowledge.js
+ *
+ * No LLM calls — pure code extraction from action history.
+ */
+
+import { store as storeKnowledge, retrieve } from "./knowledge.js";
+import { createLogger } from "../logging/logger.js";
+
+const log = createLogger("learning");
+
+/**
+ * Extract learnings from a completed task.
+ * @param {object} opts
+ * @param {Array} opts.messages - conversation messages from agent loop
+ * @param {string} opts.task - original task description
+ * @param {object} opts.plan - completed plan (goal + tasks)
+ * @param {string} opts.outcome - "success" | "partial" | "failed"
+ */
+export function extractLearnings({ messages, task, plan, outcome }) {
+  if (outcome === "failed") return; // don't learn from failures (yet)
+
+  const toolCalls = _extractToolSequence(messages);
+  if (toolCalls.length < 2) return; // nothing to learn from 1 tool call
+
+  // Check if we already know this pattern
+  const existing = retrieve(task, 1);
+  if (existing.length > 0 && existing[0].score > 2) {
+    log.info("pattern-already-known", { task: task.slice(0, 40) });
+    return;
+  }
+
+  // Extract pattern: ordered sequence of unique tool names
+  const pattern = _buildPattern(toolCalls, task);
+  if (pattern) {
+    storeKnowledge(pattern);
+    log.info("pattern-stored", { type: pattern.type, text: pattern.text.slice(0, 60) });
+  }
+
+  // Extract facts: tools that worked in specific contexts
+  const facts = _buildFacts(toolCalls, task);
+  for (const fact of facts) {
+    storeKnowledge(fact);
+    log.info("fact-stored", { text: fact.text.slice(0, 60) });
+  }
+}
+
+/**
+ * Extract tool call sequence from messages.
+ */
+function _extractToolSequence(messages) {
+  const calls = [];
+  for (const m of messages) {
+    if (m.role === "assistant" && m.tool_calls) {
+      for (const tc of m.tool_calls) {
+        const name = tc.function?.name || "unknown";
+        let args = {};
+        try { args = JSON.parse(tc.function?.arguments || "{}"); } catch {}
+        calls.push({ name, args });
+      }
+    }
+  }
+  return calls;
+}
+
+/**
+ * Build a reusable pattern from tool sequence.
+ */
+function _buildPattern(toolCalls, task) {
+  // Deduplicate consecutive same-tool calls
+  const steps = [];
+  let prev = null;
+  for (const tc of toolCalls) {
+    const shortName = _shortToolName(tc.name);
+    if (shortName !== prev) {
+      steps.push(shortName);
+      prev = shortName;
+    }
+  }
+
+  if (steps.length < 2 || steps.length > 15) return null;
+
+  // Extract task keywords for triggers
+  const triggers = task.toLowerCase()
+    .split(/\s+/)
+    .filter(w => w.length > 3)
+    .filter(w => !["this", "that", "then", "with", "from", "using", "into", "open", "the"].includes(w))
+    .slice(0, 5);
+
+  return {
+    type: "pattern",
+    text: `For "${_summarizeTask(task)}": ${steps.join(" → ")}`,
+    context: task.slice(0, 100),
+    triggers,
+    confidence: 0.6,
+    steps,
+  };
+}
+
+/**
+ * Build facts from tool usage in context.
+ */
+function _buildFacts(toolCalls, task) {
+  const facts = [];
+  const seen = new Set();
+
+  for (const tc of toolCalls) {
+    const shortName = _shortToolName(tc.name);
+
+    // Fact: MCP tool used for file operation
+    if (tc.name.includes("mcp_") && tc.args?.command && tc.args.command.includes("echo")) {
+      const key = "remote-echo";
+      if (!seen.has(key)) {
+        seen.add(key);
+        facts.push({
+          type: "fact",
+          text: `Use ${shortName} (remote shell) for file creation on remote systems, not local write_file`,
+          context: "remote file operations",
+          triggers: ["file", "save", "create", "remote", "desktop"],
+          confidence: 0.7,
+        });
+      }
+    }
+
+    // Fact: successful tool for reading web content
+    if (tc.name.includes("chrome") && tc.args?.action === "page_read") {
+      const key = "chrome-read";
+      if (!seen.has(key)) {
+        seen.add(key);
+        facts.push({
+          type: "fact",
+          text: `Use chrome page_read for extracting web page content (faster than screenshot+OCR)`,
+          context: "web content extraction",
+          triggers: ["read", "page", "content", "extract", "web"],
+          confidence: 0.8,
+        });
+      }
+    }
+  }
+
+  return facts;
+}
+
+/**
+ * Shorten tool name: mcp_screenbox_desktop_shell → desktop_shell
+ */
+function _shortToolName(name) {
+  if (name.startsWith("mcp_")) {
+    const parts = name.split("_");
+    return parts.slice(2).join("_") || name;
+  }
+  return name;
+}
+
+/**
+ * Summarize task to ~30 chars.
+ */
+function _summarizeTask(task) {
+  if (task.length <= 30) return task;
+  return task.slice(0, 27) + "...";
+}
+
+/**
+ * True if a tool result looks like a genuine failure. Matches structural
+ * failure markers (non-zero exit, "Error:" prefix, permission/path errors)
+ * -- deliberately NOT the bare word "error", which appears in legitimate
+ * content like a command string or a README about error handling.
+ *
+ * Shared with agent.js's failure-recovery gate so both use one definition.
+ */
+export function isFailureResult(content) {
+  if (typeof content !== "string") return false;
+  return /error\s*\(exit|\berror:|\berror executing\b|\(exit\s+[1-9]|exit\s+code\s+[1-9]|exit\s+status\s+[1-9]|\bpermission denied\b|\bno such file\b|\bcommand not found\b|\bfailed to\b|\beconnrefused\b|\beconnreset\b|\benoent\b|\beacces\b|traceback \(most recent/i.test(content);
+}

package/src/agent/modes.js

@@ -0,0 +1,187 @@
+// Mode registry — maps intent classes to behavioral modes.
+//
+// Each mode defines:
+//   - promptAddition: behavioral rules injected into system prompt
+//   - maxIterations: iteration budget override
+//   - model: optional model override (e.g. use Sonnet for project, Flash for chat)
+//
+// Model override: set via AGENT_MODEL_<MODE> env var or mode.model field.
+// If not set, uses session default (config.model).
+//
+// 22 intent classes → 12 modes (many-to-one mapping).
+
+export const MODES = {
+  conversation: {
+    name: "conversation",
+    intents: ["chat", "knowledge_qa", "reasoning"],
+    model: null, // cheapest model OK — override via AGENT_MODEL_CONVERSATION
+    promptAddition: `[MODE: conversation]
+- Prefer responding in text without tools. Use tools only if the question requires checking live data.
+- Keep responses concise. No preamble. No trailing offers.
+- Match the user's language and register.`,
+    maxIterations: 5,
+  },
+
+  quick_action: {
+    name: "quick_action",
+    intents: ["shell_command", "file_read"],
+    promptAddition: `[MODE: quick_action]
+- Execute in 1-3 tool calls. No planning phase needed.
+- Show the result immediately. Minimal explanation.
+- If the result is an error — report it clearly, suggest a fix.`,
+    maxIterations: 5,
+  },
+
+  planning: {
+    name: "planning",
+    intents: ["task_create", "task_update", "task_view"],
+    promptAddition: `[MODE: planning]
+- Create or manage tasks/plans. Use task tools (create_plan, update_task, list_tasks).
+- When user says "plan X" — produce a text plan (bullet list). Do NOT auto-execute it.
+- Only create a formal plan (via create_plan tool) if user explicitly confirms.`,
+    maxIterations: 5,
+  },
+
+  files: {
+    name: "files",
+    intents: ["file_write", "file_edit", "file_manage"],
+    promptAddition: `[MODE: files]
+- File operations: create, edit, move, copy, delete, search.
+- Always verify the file exists before editing. Show relevant content after changes.
+- For edits: read first, modify, write back. Show the diff or changed section.
+- Respect scope: only touch files the user mentioned.`,
+    maxIterations: 8,
+  },
+
+  project: {
+    name: "project",
+    intents: ["complex_multi"],
+    promptAddition: `[MODE: project]
+- Multi-step feature work, refactoring, or bug fixing.
+- Plan before executing: list what you'll change and why.
+- After changes: run tests if available. Report results.
+- Commit-ready: changes should be minimal and focused.`,
+    maxIterations: 30,
+  },
+
+  autonomous: {
+    name: "autonomous",
+    intents: [],
+    promptAddition: `[MODE: autonomous]
+- Long self-directed work. You have extended budget.
+- Write intermediate progress reports every 5-10 iterations.
+- Self-verify: when you think you're done, check once more.
+- If stuck after 3 attempts on same approach — try a different strategy.`,
+    maxIterations: 50,
+  },
+
+  research: {
+    name: "research",
+    intents: ["web_search", "web_fetch"],
+    promptAddition: `[MODE: research]
+- Gather information from web and local sources.
+- Structure findings: summary first, then details.
+- Cite sources when using web results.
+- If multiple sources disagree — note the discrepancy.`,
+    maxIterations: 10,
+  },
+
+  computer_use: {
+    name: "computer_use",
+    intents: ["desktop"],
+    promptAddition: `[MODE: computer_use]
+- Desktop GUI interaction via screenshot/click/type tools.
+- MANDATORY workflow: screenshot → look (OCR) → click. Never click blind.
+- Prefer keyboard shortcuts over mouse when possible.
+- If Chrome is open: use Chrome semantics (page_read, page_map) before OCR.`,
+    maxIterations: 20,
+  },
+
+  delegation: {
+    name: "delegation",
+    intents: ["agent_spawn"],
+    promptAddition: `[MODE: delegation]
+- Spawn child agents for parallel work.
+- Give each agent a clear, specific task description.
+- Wait for results. Aggregate and summarize for the user.
+- Max 3 concurrent child agents unless user specifies more.`,
+    maxIterations: 10,
+  },
+
+  secretary: {
+    name: "secretary",
+    intents: [],
+    promptAddition: `[MODE: secretary]
+- Communication tasks: email, messages, scheduling.
+- Use formal tone for external communications.
+- Always show draft before sending. Wait for user approval.
+- Include all relevant context (who, what, when, where).`,
+    maxIterations: 5,
+  },
+
+  monitoring: {
+    name: "monitoring",
+    intents: [],
+    promptAddition: `[MODE: monitoring]
+- Periodic checks and alerts.
+- Run check → compare with previous state → report changes.
+- Only alert on meaningful changes, not noise.
+- Keep logs of what was checked and when.`,
+    maxIterations: 5,
+  },
+
+  creative: {
+    name: "creative",
+    intents: ["creative_text"],
+    promptAddition: `[MODE: creative]
+- Content generation: writing, editing, formatting.
+- Longer output is acceptable. Use markdown formatting.
+- If user asks to save result to file — use write_file.`,
+    maxIterations: 5,
+  },
+};
+
+// Build reverse map: intent → mode
+const _intentToMode = new Map();
+for (const [modeName, mode] of Object.entries(MODES)) {
+  for (const intent of mode.intents) {
+    _intentToMode.set(intent, modeName);
+  }
+}
+
+/**
+ * Get mode config for a given intent class.
+ * Falls back to "project" for unknown intents (safest default).
+ * Resolves model: env AGENT_MODEL_<MODE> > mode.model > null (use session default).
+ * @param {string} intentClass — from intent classifier
+ * @returns {{ name, promptAddition, maxIterations, model }}
+ */
+export function getModeForIntent(intentClass) {
+  const modeName = _intentToMode.get(intentClass) || "project";
+  const mode = MODES[modeName];
+  // Resolve model: env var takes priority
+  const envKey = `AGENT_MODEL_${modeName.toUpperCase()}`;
+  const resolvedModel = process.env[envKey] || mode.model || null;
+  return { ...mode, model: resolvedModel };
+}
+
+/**
+ * Get mode by name directly.
+ * @param {string} modeName
+ * @returns {object|null}
+ */
+export function getMode(modeName) {
+  return MODES[modeName] || null;
+}
+
+/**
+ * List all available modes (for /help or tool listing).
+ * @returns {Array<{name, description}>}
+ */
+export function listModes() {
+  return Object.values(MODES).map(m => ({
+    name: m.name,
+    intents: m.intents,
+    maxIterations: m.maxIterations,
+  }));
+}

package/src/agent/outcome-ask.js

@@ -0,0 +1,91 @@
+// Which of the three things happened on a turn that changed nothing.
+//
+// A turn that changed nothing must tell the operator WHICH: the agent did not find what to
+// change, or found it and could not apply the change, or there was nothing to
+// change. Only the model that did the turn can say, so it is asked.
+//
+// It used to be asked inside the conversation: a [OUTCOME] system message, then
+// `continue`, and the loop took the next reply as the turn's answer. The
+// question says "in one sentence", the model obeys, and the one sentence
+// REPLACED the answer. Measured on ten readiness probes, 2026-09-21: eight
+// turns of ten came back to the operator as a single sentence about change,
+// their actual answer lost inside the loop. cut-0003 asked "go to the server",
+// ran a command, and the whole answer was "The request was not asking for a
+// change."
+//
+// So the question is not a turn of the conversation. It is one small call of
+// its own, like the classifier, and its answer is a line of explanation, never
+// the answer itself. That also makes it cheaper: the in-conversation ask
+// re-sent the whole context and the tool schemas, around 9k prompt tokens on
+// the measured run; this sends the evidence and nothing else.
+
+import { config } from "../config.js";
+import { chatCompletion } from "../api/client.js";
+import { createLogger } from "../logging/logger.js";
+
+const log = createLogger("outcome-ask");
+
+const SYSTEM = `You are reporting on one turn of an agent that finished without changing any file on disk.
+
+Say, in ONE short sentence addressed to the operator, which of these is true:
+- you did not find what to change;
+- you found what to change but did not apply the change;
+- there was nothing to change;
+- the request was not asking for a change.
+
+Reply with that sentence and nothing else. No preamble, no JSON, no quotes.`;
+
+/**
+ * Ask why the turn changed nothing.
+ *
+ * @param {object} turn
+ * @param {string} turn.request   what the user asked for
+ * @param {string} turn.answer    what the agent replied
+ * @param {string[]} turn.tools   names of the tools the turn called, in order
+ * @param {AbortSignal} [turn.signal]
+ * @returns {Promise<string|null>} one sentence, or null when the call did not happen
+ */
+export async function askOutcome({ request, answer, tools = [], signal }) {
+  if (!config.apiKey) return null;
+
+  const evidence = [
+    `REQUEST: ${String(request || "").slice(0, 1500)}`,
+    `YOUR ANSWER: ${String(answer || "").slice(0, 1500)}`,
+    `TOOLS YOU CALLED: ${tools.length ? tools.join(", ") : "(none)"}`,
+    "NOTHING ON DISK CHANGED.",
+  ].join("\n\n");
+
+  try {
+    const { message } = await chatCompletion(
+      [
+        { role: "system", content: SYSTEM },
+        { role: "user", content: evidence },
+      ],
+      [],
+      null,
+      {
+        source: "outcome",
+        model: config.model,
+        maxTokens: 80,
+        temperature: 0,
+        stream: false,
+        signal,
+        // A ceiling of its own, always: the turn's signal cancels the ask when
+        // the user aborts, but it never expires on its own, and a hung reason
+        // must not hold back the answer that is already written.
+        timeoutMs: 15000,
+      },
+    );
+    const text = (message?.content || "").trim();
+    if (!text) return null;
+    // One sentence is what was asked for; a model that writes three gets cut,
+    // because this line sits next to the answer and must not compete with it.
+    return text.split("\n")[0].slice(0, 300);
+  } catch (err) {
+    // The reason is best effort. The FACT that nothing changed is not: the
+    // caller states that either way. Losing the
+    // reason must never cost the operator the fact.
+    log.warn("outcome-ask failed", { error: err.message });
+    return null;
+  }
+}

package/src/agent/project-context.js

@@ -0,0 +1,76 @@
+// Project context (FLINT.md) — the agent's own notebook for the project
+// it's currently working in. Walks up from CWD looking for FLINT.md,
+// scans for prompt injection, returns content. Cached per-CWD for the
+// life of the process (invalidated by file mtime change).
+//
+// Injected at the top of EVERY LLM prompt — classifier, agent loop,
+// reflection, etc. — so the agent's own project rules are visible
+// before any other context.
+
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { config } from "../config.js";
+import { detectInjection } from "../security/content-fence.js";
+
+const MAX_CHARS = config.maxContextChars;
+const _cache = new Map(); // path → { content, mtimeMs }
+
+function findFile(startDir) {
+  let dir = startDir;
+  for (let i = 0; i < 10; i++) {
+    const p = join(dir, "FLINT.md");
+    if (existsSync(p)) return p;
+    const parent = join(dir, "..");
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+export function loadFlintMd(cwd = process.cwd()) {
+  const p = findFile(cwd);
+  if (!p) return null;
+
+  let mtimeMs;
+  try {
+    mtimeMs = statSync(p).mtimeMs;
+  } catch {
+    return null;
+  }
+
+  const cached = _cache.get(p);
+  if (cached && cached.mtimeMs === mtimeMs) return cached.content;
+
+  let content;
+  try {
+    content = readFileSync(p, "utf-8");
+  } catch {
+    return null;
+  }
+  if (content.length > MAX_CHARS) {
+    content = content.slice(0, MAX_CHARS) + "\n... (truncated)";
+  }
+
+  // Injection scan — FLINT.md is user- or agent-written, but we still
+  // scan because the agent itself could be fooled into writing malicious
+  // instructions there via a crafted user message in a prior turn.
+  const scan = detectInjection(content);
+  if (scan.detected && scan.score >= 3) {
+    const blocked = `[BLOCKED: FLINT.md at ${p} failed injection scan (score ${scan.score})]`;
+    _cache.set(p, { content: blocked, mtimeMs });
+    return blocked;
+  }
+
+  _cache.set(p, { content, mtimeMs });
+  return content;
+}
+
+export function formatFlintMdBlock(cwd = process.cwd()) {
+  const content = loadFlintMd(cwd);
+  if (!content) return "";
+  return [
+    "<trusted-context name=\"project-rules\" source=\"FLINT.md\">",
+    content,
+    "</trusted-context>",
+  ].join("\n");
+}