flint-agent 1.14.0

package/src/stdio/protocol.js

@@ -0,0 +1,167 @@
+// The stream-json protocol of the stdio mode: one JSON object per line on
+// stdin and on stdout, in the common stream-json shapes, so a host written for
+// `claude --input-format stream-json --output-format stream-json` reads Flint
+// without changes. A host driving it reads:
+//
+//   assistant  message.content[] text and tool_use blocks, message.usage, message.id
+//   result     subtype ("success" or an error), result, usage, total_cost_usd
+//   error      message (a turn that could not run at all)
+//
+// and writes `user` messages and `control_request` interrupts. Everything else
+// (system init, tool results, control responses) is for other hosts and logs.
+//
+// Pure functions only; the loop that uses them is stdio/run.js.
+
+/** A tool result line is for logs; the model already has the full text. */
+export const TOOL_RESULT_MAX_CHARS = 16000;
+
+/** Parse one input line. Null for a blank or non-JSON line, which is skipped. */
+export function parseInputLine(line) {
+  const s = String(line || "").trim();
+  if (!s) return null;
+  try {
+    const v = JSON.parse(s);
+    return v && typeof v === "object" ? v : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The content of a `user` envelope as Flint's processMessage takes it: a
+ * string when it is only text, else OpenAI-style parts with images as data
+ * URLs. Null when the envelope carries nothing to answer.
+ */
+export function userContent(envelope) {
+  const content = envelope?.message?.content;
+  if (typeof content === "string") return content.trim() ? content : null;
+  if (!Array.isArray(content)) return null;
+  const parts = [];
+  for (const b of content) {
+    if (!b || typeof b !== "object") continue;
+    if (b.type === "text" && b.text) parts.push({ type: "text", text: String(b.text) });
+    else if (b.type === "image" && b.source?.type === "base64" && b.source.data) {
+      parts.push({ type: "image_url", image_url: { url: `data:${b.source.media_type || "image/png"};base64,${b.source.data}` } });
+    } else if (b.type === "image" && b.source?.type === "url" && b.source.url) {
+      parts.push({ type: "image_url", image_url: { url: b.source.url } });
+    }
+  }
+  if (!parts.length) return null;
+  if (parts.every((p) => p.type === "text")) return parts.map((p) => p.text).join("\n\n");
+  return parts;
+}
+
+function toolInput(args) {
+  if (args && typeof args === "object") return args;
+  try {
+    const v = JSON.parse(args || "{}");
+    return v && typeof v === "object" ? v : { value: v };
+  } catch {
+    return { raw: String(args) };
+  }
+}
+
+function usageOf(usage) {
+  return {
+    input_tokens: usage?.prompt_tokens || 0,
+    output_tokens: usage?.completion_tokens || 0,
+    cache_read_input_tokens: usage?.prompt_tokens_details?.cached_tokens || 0,
+    cache_creation_input_tokens: 0,
+  };
+}
+
+export function initEvent({ sessionId, model, cwd, tools = [], mcpServers = [], permissionMode, version }) {
+  return {
+    type: "system",
+    subtype: "init",
+    session_id: sessionId,
+    cwd,
+    model,
+    tools,
+    mcp_servers: mcpServers,
+    permissionMode,
+    agent: "flint",
+    version,
+  };
+}
+
+/**
+ * One model reply as an `assistant` message: its text, then one tool_use block
+ * per tool call. Null for a reply with neither.
+ */
+export function assistantEvent({ reply, usage, model, sessionId, messageId }) {
+  const content = [];
+  const text = typeof reply?.content === "string" ? reply.content.trim() : "";
+  if (text) content.push({ type: "text", text });
+  for (const tc of reply?.tool_calls || []) {
+    content.push({ type: "tool_use", id: tc.id, name: tc.function?.name, input: toolInput(tc.function?.arguments) });
+  }
+  if (!content.length) return null;
+  return {
+    type: "assistant",
+    message: {
+      id: messageId,
+      type: "message",
+      role: "assistant",
+      model,
+      content,
+      stop_reason: reply?.tool_calls?.length ? "tool_use" : "end_turn",
+      usage: usageOf(usage),
+    },
+    parent_tool_use_id: null,
+    session_id: sessionId,
+  };
+}
+
+export function toolResultEvent({ toolUseId, result, isError, sessionId }) {
+  let text = typeof result === "string" ? result : JSON.stringify(result);
+  if (text == null) text = "";
+  if (text.length > TOOL_RESULT_MAX_CHARS) {
+    text = text.slice(0, TOOL_RESULT_MAX_CHARS) + `\n[... ${text.length - TOOL_RESULT_MAX_CHARS} more characters]`;
+  }
+  return {
+    type: "user",
+    message: { role: "user", content: [{ type: "tool_result", tool_use_id: toolUseId, content: text, is_error: !!isError }] },
+    parent_tool_use_id: null,
+    session_id: sessionId,
+  };
+}
+
+/**
+ * The end of a turn. `subtype` is "success", "error_during_execution" (the
+ * turn failed or was interrupted) or "error_max_turns" (the step limit).
+ */
+export function resultEvent({ subtype, text, sessionId, durationMs, numTurns, costUsd, promptTokens, completionTokens, stopReason }) {
+  return {
+    type: "result",
+    subtype,
+    is_error: subtype !== "success",
+    duration_ms: durationMs,
+    num_turns: numTurns,
+    result: text || "",
+    session_id: sessionId,
+    total_cost_usd: costUsd || 0,
+    usage: { input_tokens: promptTokens || 0, output_tokens: completionTokens || 0 },
+    stop_reason: stopReason || null,
+  };
+}
+
+export function controlResponse(requestId, extra = {}) {
+  return { type: "control_response", response: { subtype: "success", request_id: requestId, response: extra } };
+}
+
+export function controlError(requestId, error) {
+  return { type: "control_response", response: { subtype: "error", request_id: requestId, error } };
+}
+
+/**
+ * Which result subtype a finished processMessage maps to. Flint's own stop
+ * reasons (agent/agent.js): "done"; "denied" (it stopped asking after
+ * repeated denials and said so, an answer like any other); "budget" (the
+ * cost ceiling); "error", "stall", "empty" (the turn did not get anywhere).
+ */
+export function resultSubtype(stopReason) {
+  if (!stopReason || stopReason === "done" || stopReason === "denied") return "success";
+  if (stopReason === "budget") return "error_max_budget_usd";
+  return "error_during_execution";
+}

package/src/stdio/run.js

@@ -0,0 +1,106 @@
+// The stdio mode: Flint as a long-lived subprocess driven over stream-json,
+// the way a host drives an agent CLI.
+//
+// One process is one session. Each `user` line on stdin is one turn; turns
+// run one at a time, in order. While a turn runs, its model replies and tool
+// results are written to stdout as they happen, and the turn ends with one
+// `result` line. A `control_request` with subtype "interrupt" stops the
+// running turn, which then ends with a `result` of subtype
+// "error_during_execution". The process stays up
+// between turns and exits when stdin closes, after the running turn.
+//
+// No terminal UI, no HTTP server, no message bus: a host that starts several
+// of these gets several independent agents, not several readers of one queue.
+
+import { createInterface } from "node:readline";
+import { store } from "../store/index.js";
+import { app } from "../app-state.js";
+import { config } from "../config.js";
+import { processMessage, setTurnObserver } from "../message-handler.js";
+import { bulkSetPermission, setUnattended } from "../tools/permissions.js";
+import { getDefinitions } from "../tools/registry.js";
+import { killAllChildrenSync } from "../tools/process-tools.js";
+import { saveSession } from "../sessions.js";
+import { sessionData } from "../app-state.js";
+import { initEvent } from "./protocol.js";
+import { createStdioSession } from "./session.js";
+
+const ANSI_RE = /\x1b\[[0-9;?]*[A-Za-z]|\x1b\][^\x07]*\x07/g;
+
+/** Run the stdio mode until stdin closes. Never returns. */
+export async function runStdio({ opts, write, version }) {
+  config.headless = true;
+  if (opts.model) {
+    config.model = opts.model;
+    store.getState().setModel(opts.model);
+  }
+  if (opts.skipPermissions) bulkSetPermission("allow");
+
+  // Every store line goes to stderr: the host keeps it for diagnosis
+  // (gateway: the stderr tail in the session's error record).
+  const addLine = store.getState().addLine.bind(store.getState());
+  store.setState({
+    addLine: (text, ...rest) => {
+      const raw = typeof text === "string" ? text.replace(ANSI_RE, "") : String(text ?? "");
+      if (raw.trim()) process.stderr.write(raw.replace(/\s+$/, "") + "\n");
+      return addLine(text, ...rest);
+    },
+  });
+
+  // The MCP servers connect in the background; the first turn waits for
+  // them (up to 15 s, as the bus does for API messages), or the agent would
+  // start without the tools its host gave it.
+  const waitStart = Date.now();
+  while (!app.mcpReady && Date.now() - waitStart < 15000) await new Promise((r) => setTimeout(r, 200));
+
+  const sessionId = store.getState().sessionId;
+  write(initEvent({
+    sessionId,
+    model: config.model,
+    cwd: process.cwd(),
+    tools: getDefinitions().map((t) => t.function?.name).filter(Boolean),
+    mcpServers: (app.mcpStatusList || []).map((s) => ({ name: s.name, status: s.ok ? "connected" : "failed" })),
+    permissionMode: opts.skipPermissions ? "bypassPermissions" : "default",
+    version,
+  }));
+
+  const session = createStdioSession({
+    write,
+    sessionId,
+    model: () => config.model,
+    run: async (content, { signal, observer }) => {
+      // Nobody can answer an approval prompt here: a tool that would ask is
+      // refused at once (permissions.js, unattended), unless the host passed
+      // --dangerously-skip-permissions.
+      setUnattended(true);
+      setTurnObserver(observer);
+      try {
+        return await processMessage(content, null, { signal });
+      } finally {
+        setTurnObserver(null);
+      }
+    },
+    // What an agent CLI leaves in the transcript after a stop. Without it the
+    // next turn read the stopped command as unfinished work and ran it again,
+    // in the background this time (2026-10-02).
+    onInterrupted: async () => {
+      store.getState().pushMessage({ role: "user", content: "[Request interrupted by user. Do not resume that work unless asked again.]" });
+      await saveSession(sessionId, sessionData(store));
+    },
+    onIdleEnd: () => shutdown(0),
+  });
+
+  // Background processes the agent started end with it: a host that closes
+  // stdin or kills this process expects nothing of it left behind.
+  function shutdown(code) {
+    try { killAllChildrenSync(); } catch {}
+    process.exit(code);
+  }
+  process.on("SIGTERM", () => shutdown(143));
+  process.on("SIGINT", () => shutdown(130));
+
+  const rl = createInterface({ input: process.stdin, crlfDelay: Infinity });
+  rl.on("line", (l) => session.line(l));
+  rl.on("close", () => session.end());
+  await new Promise(() => {});
+}

package/src/stdio/session.js

@@ -0,0 +1,180 @@
+// The stdio mode's session logic, kept free of the agent's own modules so it
+// can be tested alone: the host's instructions (CLAUDE.md and the prompt
+// flags), the MCP config file, and the loop that turns input lines into turns
+// and turns into protocol lines. stdio/run.js wires it to the agent.
+
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import {
+  parseInputLine, userContent, assistantEvent, toolResultEvent,
+  resultEvent, resultSubtype, controlResponse,
+} from "./protocol.js";
+
+/**
+ * CLAUDE.md files an agent in this folder is expected to read: the folder's
+ * own and every parent's, outermost first. A host may keep an agent's role
+ * there and shared rules one level up.
+ */
+export function claudeMdChain(cwd) {
+  const found = [];
+  let dir = path.resolve(cwd);
+  for (;;) {
+    const f = path.join(dir, "CLAUDE.md");
+    if (existsSync(f)) found.unshift(f);
+    const up = path.dirname(dir);
+    if (up === dir) break;
+    dir = up;
+  }
+  return found;
+}
+
+/**
+ * The host's instructions, in the order they apply: --system-prompt (or its
+ * file), the CLAUDE.md chain, then --append-system-prompt (or its file).
+ */
+export function hostPromptFrom(opts, { cwd = process.cwd(), read = (f) => readFileSync(f, "utf8") } = {}) {
+  const parts = [];
+  if (opts.systemPrompt) parts.push(opts.systemPrompt);
+  if (opts.systemPromptFile) parts.push(read(opts.systemPromptFile));
+  for (const f of claudeMdChain(cwd)) {
+    const text = read(f).trim();
+    if (text) parts.push(`<instructions source="${f}">\n${text}\n</instructions>`);
+  }
+  if (opts.appendSystemPrompt) parts.push(opts.appendSystemPrompt);
+  if (opts.appendSystemPromptFile) parts.push(read(opts.appendSystemPromptFile));
+  const body = parts.map((p) => String(p).trim()).filter(Boolean).join("\n\n");
+  if (!body) return "";
+  // Without this line the model kept the core prompt's "You are FLINT" over
+  // the host's role: a test agent told to answer "Pebble" answered "FLINT."
+  // (2026-10-02). An agent's CLAUDE.md is who it is.
+  return "The program running you gave you the identity, role and rules below. " +
+    "They take precedence over the defaults above: where they name you, give you a role, " +
+    "or say how to answer, follow them.\n\n" + body;
+}
+
+/** The MCP config file to load: --mcp-config, else .mcp.json in the folder. */
+export function mcpConfigPath(opts, cwd = process.cwd()) {
+  if (opts.mcpConfig) return path.resolve(cwd, opts.mcpConfig);
+  const local = path.join(cwd, ".mcp.json");
+  return existsSync(local) ? local : null;
+}
+
+/**
+ * Turns one session's lines into turns. `write` takes one protocol object;
+ * `run` runs one turn (processMessage); both are injectable for tests.
+ */
+export function createStdioSession({ write, run, sessionId, model, onIdleEnd, onInterrupted }) {
+  const modelName = typeof model === "function" ? model : () => model;
+  const queue = [];
+  let current = null;       // { controller, interrupted }
+  let busy = false;
+  let ended = false;
+  let turnNo = 0;
+
+  async function runTurn(content) {
+    turnNo++;
+    const controller = new AbortController();
+    current = { controller, interrupted: false };
+    const started = Date.now();
+    let apiCalls = 0;
+    let toolSeq = 0;
+    const pendingIds = new Map();   // tool name -> ids of its calls not yet answered
+
+    const observer = {
+      onReply(reply, usage) {
+        apiCalls++;
+        for (const tc of reply?.tool_calls || []) {
+          if (!tc.id) tc.id = `toolu_flint_${turnNo}_${++toolSeq}`;
+          const name = tc.function?.name;
+          if (!pendingIds.has(name)) pendingIds.set(name, []);
+          pendingIds.get(name).push(tc.id);
+        }
+        const ev = assistantEvent({ reply, usage, model: modelName(), sessionId, messageId: `msg_flint_${turnNo}_${apiCalls}` });
+        if (ev) write(ev);
+      },
+      onToolResult(name, result, denied) {
+        const id = pendingIds.get(name)?.shift() || `toolu_flint_${turnNo}_${++toolSeq}`;
+        const text = typeof result === "string" ? result : JSON.stringify(result);
+        const isError = !!denied || /^(error|\[error)/i.test(String(text || "").trim());
+        write(toolResultEvent({ toolUseId: id, result: text, isError, sessionId }));
+      },
+    };
+
+    let ev;
+    try {
+      const res = await run(content, { signal: controller.signal, observer });
+      const stats = res?.stats || {};
+      const subtype = current.interrupted ? "error_during_execution" : resultSubtype(res?.stop_reason);
+      ev = resultEvent({
+        subtype,
+        text: res?.text || "",
+        sessionId,
+        durationMs: Date.now() - started,
+        numTurns: apiCalls,
+        costUsd: stats.cost,
+        promptTokens: stats.promptTokens,
+        completionTokens: stats.completionTokens,
+        stopReason: current.interrupted ? "interrupted" : (res?.stop_reason || "done"),
+      });
+    } catch (err) {
+      const interrupted = current.interrupted || err?.name === "AbortError";
+      ev = resultEvent({
+        subtype: "error_during_execution",
+        text: interrupted ? "" : `Error: ${err?.message || err}`,
+        sessionId,
+        durationMs: Date.now() - started,
+        numTurns: apiCalls,
+        stopReason: interrupted ? "interrupted" : "error",
+      });
+    } finally {
+      if (current?.interrupted) {
+        try { await onInterrupted?.(); } catch {}
+      }
+      current = null;
+    }
+    write(ev);
+  }
+
+  async function pump() {
+    if (busy) return;
+    busy = true;
+    try {
+      while (queue.length) await runTurn(queue.shift());
+    } finally {
+      busy = false;
+    }
+    if (ended) onIdleEnd?.();
+  }
+
+  return {
+    /** One input line. */
+    line(raw) {
+      const msg = parseInputLine(raw);
+      if (!msg) return;
+      if (msg.type === "user") {
+        const content = userContent(msg);
+        if (content == null) return;
+        queue.push(content);
+        pump();
+        return;
+      }
+      if (msg.type === "control_request") {
+        const subtype = msg.request?.subtype;
+        if (subtype === "interrupt" && current) {
+          current.interrupted = true;
+          current.controller.abort(new Error("interrupted by host"));
+        }
+        // Every request is answered, so a host waiting on one never hangs:
+        // interrupt with nothing running, initialize, and the requests Flint
+        // has no use for all get a plain success.
+        write(controlResponse(msg.request_id ?? null));
+      }
+    },
+    /** stdin closed: finish what is queued, then end. */
+    end() {
+      ended = true;
+      if (!busy) onIdleEnd?.();
+    },
+    get busy() { return busy; },
+  };
+}