flint-agent 1.14.0

package/src/agent/prompt-budget.js

@@ -0,0 +1,117 @@
+// Prompt Budget Allocator — waterfall allocation with min/max per section.
+//
+// Each section declares priority, min tokens, max tokens.
+// Allocator gives min to all sections first, then distributes remaining
+// budget up to max in priority order. Conversation history gets the remainder.
+//
+// Token estimation: chars / 4 (rough but fast, no tiktoken dependency).
+
+import { config } from "../config.js";
+
+const DEFAULT_MAX_PROMPT_TOKENS = 100_000;
+const CHARS_PER_TOKEN = 4; // rough approximation
+
+/**
+ * Estimate token count from string content.
+ */
+export function estimateTokens(text) {
+  if (!text) return 0;
+  return Math.ceil(text.length / CHARS_PER_TOKEN);
+}
+
+/**
+ * Create a budget allocator instance.
+ * @param {number} [maxTokens] - Total prompt budget in tokens
+ */
+export function createBudgetAllocator(maxTokens) {
+  const budget = maxTokens || config.maxPromptTokens || DEFAULT_MAX_PROMPT_TOKENS;
+  const sections = [];
+
+  return {
+    /**
+     * Add a named section with content and budget constraints.
+     * @param {string} name - Section identifier
+     * @param {string} content - Section text content
+     * @param {object} opts
+     * @param {number} opts.priority - Lower = higher priority (1 = must-have, 10 = nice-to-have)
+     * @param {number} [opts.min] - Minimum tokens (guaranteed if content available)
+     * @param {number} [opts.max] - Maximum tokens (cap even if budget allows more)
+     * @param {boolean} [opts.fixed] - If true, include as-is without truncation
+     */
+    addSection(name, content, { priority, min = 0, max = Infinity, fixed = false } = {}) {
+      if (!content) return;
+      const tokens = estimateTokens(content);
+      sections.push({ name, content, tokens, priority, min, max, fixed });
+    },
+
+    /**
+     * Build the final prompt string respecting the budget.
+     * Returns { prompt, stats } where stats shows per-section token usage.
+     */
+    build() {
+      if (!sections.length) return { prompt: "", stats: {} };
+
+      // Sort by priority (lower = higher priority)
+      const sorted = [...sections].sort((a, b) => a.priority - b.priority);
+
+      // Phase 1: give minimum to all sections
+      let used = 0;
+      const allocations = new Map();
+
+      for (const s of sorted) {
+        if (s.fixed) {
+          allocations.set(s.name, s.tokens);
+          used += s.tokens;
+        } else {
+          const minAlloc = Math.min(s.min, s.tokens); // don't allocate more than content
+          allocations.set(s.name, minAlloc);
+          used += minAlloc;
+        }
+      }
+
+      // Phase 2: distribute remaining budget up to max, in priority order
+      let remaining = budget - used;
+      for (const s of sorted) {
+        if (s.fixed || remaining <= 0) continue;
+        const current = allocations.get(s.name);
+        const want = Math.min(s.tokens, s.max) - current;
+        if (want <= 0) continue;
+        const give = Math.min(want, remaining);
+        allocations.set(s.name, current + give);
+        remaining -= give;
+      }
+
+      // Phase 3: build output, truncating sections to their allocation
+      const parts = [];
+      const stats = {};
+
+      // Maintain original insertion order
+      for (const s of sections) {
+        const allocated = allocations.get(s.name) || 0;
+        stats[s.name] = { tokens: s.tokens, allocated, truncated: false };
+
+        if (s.fixed || s.tokens <= allocated) {
+          parts.push(s.content);
+        } else {
+          // Truncate: keep head (70%) + tail (20%) + marker
+          const maxChars = allocated * CHARS_PER_TOKEN;
+          if (maxChars <= 0) continue;
+          const headChars = Math.floor(maxChars * 0.7);
+          const tailChars = Math.floor(maxChars * 0.2);
+          const head = s.content.slice(0, headChars);
+          const tail = s.content.slice(-tailChars);
+          parts.push(`${head}\n\n[...truncated ${s.name}: ${s.tokens} tokens -> ${allocated} tokens...]\n\n${tail}`);
+          stats[s.name].truncated = true;
+        }
+      }
+
+      return {
+        prompt: parts.join("\n\n"),
+        stats,
+        budget,
+        used: [...allocations.values()].reduce((a, b) => a + b, 0),
+        remaining: budget - [...allocations.values()].reduce((a, b) => a + b, 0),
+      };
+    },
+  };
+}

package/src/agent/reflection-extractor.js

@@ -0,0 +1,140 @@
+// Extract a reflection from a session transcript using an LLM call.
+//
+// Prompts the model with 3 questions — what did I do, what did I do wrong,
+// how can I do better — and parses the structured response.
+//
+// Part of Layer 1 memory architecture.
+
+import { chatCompletion } from "../api/client.js";
+import { appendReflection } from "../memory/reflections.js";
+import { createLogger } from "../logging/logger.js";
+
+const log = createLogger("reflection");
+
+const EXTRACTION_SYSTEM = `You are a self-reflection analyzer for an AI agent.
+
+Given a session transcript, answer three questions about the AGENT'S behavior (not the user's):
+
+1. DID — What did the agent do this session? One concise sentence.
+2. WRONG — What did the agent do wrong or suboptimally? Up to 5 bullet points. Each must be CONCRETE and ACTIONABLE (e.g. "used python3 on Windows where it's unavailable" not "had trouble with tools"). If nothing went wrong, use empty list.
+3. BETTER — How should the agent behave next time to avoid those mistakes? Up to 5 bullet points. Each must be a specific actionable rule the agent can follow next time.
+
+Output ONLY valid JSON matching this schema, no other text:
+{"did": "one sentence", "wrong": ["point1", "point2"], "better": ["rule1", "rule2"], "tags": ["tag1", "tag2"]}
+
+Tags are short keywords (e.g. "verbosity", "tool-choice", "file-ops", "consistency", "windows-paths").
+
+If the session was trivial or empty (no real agent action), output:
+{"did": "", "wrong": [], "better": [], "tags": []}
+— this will be discarded.`;
+
+/**
+ * Extract a reflection from a session transcript.
+ * @param {Array} messages — array of {role, content} message objects
+ * @param {string} sessionId — session id to tag the reflection with
+ * @param {object} opts — { signal?, maxTranscriptChars? }
+ * @returns {Promise<string|null>} id of appended reflection, or null if discarded/failed
+ */
+export async function extractAndStoreReflection(messages, sessionId, opts = {}) {
+  const maxChars = opts.maxTranscriptChars || 12000;
+  const transcript = buildTranscript(messages, maxChars);
+
+  // Skip if session too short to be meaningful
+  if (transcript.length < 100) {
+    log.debug("reflection-skipped", { reason: "transcript too short", sessionId, chars: transcript.length });
+    return null;
+  }
+
+  try {
+    const extractionMessages = [
+      { role: "system", content: EXTRACTION_SYSTEM },
+      { role: "user", content: `Session transcript:\n\n${transcript}\n\nExtract the reflection. JSON only, no preamble.` },
+    ];
+
+    const result = await chatCompletion(extractionMessages, [], null, {
+      signal: opts.signal,
+      source: "extractor",
+    });
+    const text = result?.text || result?.message?.content || "";
+
+    const parsed = parseReflectionJson(text);
+    if (!parsed) {
+      log.warn("reflection-parse-failed", { sessionId, rawLen: text.length });
+      return null;
+    }
+
+    // Discard if empty (model decided nothing to reflect on)
+    if (!parsed.did && parsed.wrong.length === 0 && parsed.better.length === 0) {
+      log.info("reflection-empty", { sessionId });
+      return null;
+    }
+
+    const id = appendReflection({
+      session_id: sessionId,
+      did: parsed.did,
+      wrong: parsed.wrong,
+      better: parsed.better,
+      tags: parsed.tags,
+    });
+    log.info("reflection-stored", { sessionId, id, wrong: parsed.wrong.length, better: parsed.better.length });
+    return id;
+  } catch (e) {
+    log.warn("reflection-failed", { sessionId, error: e.message });
+    return null;
+  }
+}
+
+/**
+ * Build a compact transcript from the message array. Strips system messages,
+ * trims tool outputs, caps total length.
+ */
+function buildTranscript(messages, maxChars) {
+  const out = [];
+  for (const m of messages || []) {
+    if (m.role === "system") continue;
+    const content = typeof m.content === "string" ? m.content : JSON.stringify(m.content || "");
+    if (!content.trim()) continue;
+    // Trim long tool results
+    const trimmed = content.length > 500 ? content.slice(0, 400) + "... [truncated]" : content;
+    const tool_calls = Array.isArray(m.tool_calls) ? m.tool_calls.map(t => t.function?.name || t.name).filter(Boolean) : [];
+    const prefix = tool_calls.length ? `[${m.role}, used: ${tool_calls.join(",")}]` : `[${m.role}]`;
+    out.push(`${prefix} ${trimmed}`);
+  }
+  let transcript = out.join("\n");
+  if (transcript.length > maxChars) {
+    // Keep head and tail — middle of long sessions is least interesting
+    const head = transcript.slice(0, Math.floor(maxChars * 0.4));
+    const tail = transcript.slice(-Math.floor(maxChars * 0.5));
+    transcript = head + "\n\n... [middle truncated] ...\n\n" + tail;
+  }
+  return transcript;
+}
+
+/**
+ * Extract the JSON object from a model response that may have extra text around it.
+ */
+function parseReflectionJson(text) {
+  if (!text) return null;
+  // Try direct parse
+  try {
+    return normalize(JSON.parse(text.trim()));
+  } catch {}
+  // Find first { ... } block
+  const m = text.match(/\{[\s\S]*\}/);
+  if (!m) return null;
+  try {
+    return normalize(JSON.parse(m[0]));
+  } catch {
+    return null;
+  }
+}
+
+function normalize(obj) {
+  if (!obj || typeof obj !== "object") return null;
+  return {
+    did: typeof obj.did === "string" ? obj.did : "",
+    wrong: Array.isArray(obj.wrong) ? obj.wrong.map(String).filter(s => s.trim()) : [],
+    better: Array.isArray(obj.better) ? obj.better.map(String).filter(s => s.trim()) : [],
+    tags: Array.isArray(obj.tags) ? obj.tags.map(String).filter(s => s.trim()) : [],
+  };
+}

package/src/agent/steering.js

@@ -0,0 +1,86 @@
+// Steering that applies to the NEXT completion only.
+//
+// Before this, twelve places in agent.js pushed a system message straight into
+// the conversation array, and nothing ever took one out. The array is also the
+// session and the source of the rolling context window, so every nudge became a
+// standing instruction: it survived the turn that raised it, crossed into the
+// next turn, and stacked with copies of itself.
+//
+// Measured on ten readiness probes, 2026-09-21, from the payloads in
+// sessions/*.messages.jsonl:
+//
+//     [OUTCOME]   raised 8 times     sent to the model 202 times
+//     [SAFETY]                       sent to the model 192 times
+//     most system messages in one call                  20
+//     most copies of one nudge in one call                3
+//     leftover nudges present at the start of a turn      6
+//
+// What that did to answers: three standing orders to answer "in one
+// sentence" and the answer collapses to one sentence.
+//
+// A nudge now lives in this slot instead. It is assembled into ONE system
+// message appended to the payload of the next completion, and dropped. It never
+// touches the conversation, so it cannot be saved, cannot be re-sent and cannot
+// pile up.
+
+/**
+ * Order the nudges are read in, most urgent first. Not a filter: everything
+ * raised in one iteration is sent in one message, because dropping a nudge
+ * silently is how a loop-breaker goes missing. Order is what resolves a
+ * disagreement between two of them.
+ */
+export const STEER_KINDS = {
+  security: 100,
+  loop: 90,
+  // A call of the model's own that was malformed and not run: it has to hear
+  // that before anything about budget or style, or it waits for a result.
+  "tool-call": 85,
+  budget: 80,
+  verify: 70,
+  outcome: 65,
+  supervisor: 60,
+  safety: 50,
+  reflection: 40,
+};
+
+/**
+ * One slot per agent run.
+ *
+ * @returns {{add: (kind: string, text: string) => void, take: () => object|null, size: () => number}}
+ */
+export function createSteering() {
+  /** @type {Array<{rank: number, seq: number, text: string}>} */
+  let pending = [];
+  let seq = 0;
+
+  return {
+    /**
+     * Raise a nudge for the next completion.
+     *
+     * An unknown kind throws rather than defaulting: a nudge with no rank would
+     * be ordered by accident, and silently taking the lowest rank is exactly the
+     * kind of fallback that hides a typo until someone reads a payload.
+     */
+    add(kind, text) {
+      const rank = STEER_KINDS[kind];
+      if (rank === undefined) throw new Error(`unknown steering kind: ${kind}`);
+      if (typeof text !== "string" || !text.trim()) return;
+      // The same line twice in one payload teaches the model nothing and was
+      // half of what the measurement found.
+      if (pending.some((p) => p.text === text)) return;
+      pending.push({ rank, seq: seq++, text });
+    },
+
+    /** Take everything raised since the last completion, as one message. Clears. */
+    take() {
+      if (!pending.length) return null;
+      const ordered = [...pending].sort((a, b) => b.rank - a.rank || a.seq - b.seq);
+      pending = [];
+      return { role: "system", content: ordered.map((p) => p.text).join("\n\n") };
+    },
+
+    size() {
+      return pending.length;
+    },
+  };
+}