@tritard/waterbrother 0.6.6 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tritard/waterbrother",
-  "version": "0.6.6",
+  "version": "0.8.0",
   "description": "Waterbrother: Grok-powered coding CLI with local tools, sessions, operator modes, and approval controls",
   "type": "module",
   "bin": {

package/src/agent.js

@@ -101,6 +101,8 @@ function buildSystemPrompt(profile, experienceMode = "standard", autonomyMode =
     if (executionContext.chosenOption) ctxLines.push(`Chosen approach: ${executionContext.chosenOption}`);
     if (executionContext.contractSummary) ctxLines.push(`Contract: ${executionContext.contractSummary}`);
     if (executionContext.phase) ctxLines.push(`Phase: ${executionContext.phase}. Execute the chosen approach — do not re-decide.`);
+    if (executionContext.plan) ctxLines.push(`Execution plan:\n${executionContext.plan}`);
+    if (executionContext.reminders) ctxLines.push(`Scope reminders:\n${executionContext.reminders}`);
     if (ctxLines.length > 0) base += `\n\nExecution context:\n${ctxLines.join("\n")}`;
   }
   if (!memoryBlock) return base;

package/src/cli.js

@@ -19,6 +19,8 @@ import { runDecisionPass, runInventPass, formatDecisionForDisplay, formatDecisio
 import { runBuildWorkflow, startFeatureTask, runChallengeWorkflow } from "./workflow.js";
 import { createPanelRenderer, buildPanelState } from "./panel.js";
 import { deriveTaskNameFromPrompt, nextActionsForState, routeNaturalInput } from "./router.js";
+import { compressEpisode, saveEpisode, loadRecentEpisodes, findRelevantEpisodes, buildEpisodicMemoryBlock, buildReminderBlock } from "./episodic.js";
+import { formatPlanForDisplay } from "./planner.js";
 
 const execFileAsync = promisify(execFile);
 const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
@@ -4033,6 +4035,21 @@ async function promptLoop(agent, session, context) {
   if (!context.runtime.projectMemory) {
     context.runtime.projectMemory = await readProjectMemory(context.cwd);
   }
+
+  // Load episodic memory and combine with project memory
+  try {
+    const recentEpisodes = await loadRecentEpisodes({ cwd: context.cwd, limit: 5 });
+    if (recentEpisodes.length > 0) {
+      const episodicBlock = buildEpisodicMemoryBlock(recentEpisodes);
+      context.runtime.episodicMemory = episodicBlock;
+      const fullMemory = [
+        context.runtime.projectMemory?.promptText || "",
+        episodicBlock
+      ].filter(Boolean).join("\n\n");
+      agent.setMemory(fullMemory);
+    }
+  } catch {}
+
   if (!Array.isArray(context.runtime.lastSearchResults)) {
     context.runtime.lastSearchResults = [];
   }
@@ -5002,6 +5019,13 @@ async function promptLoop(agent, session, context) {
         continue;
       }
       try {
+        // Save episodic memory before closing
+        try {
+          const receipt = context.runtime.lastReceipt || null;
+          const episode = compressEpisode({ task, receipt });
+          await saveEpisode({ cwd: context.cwd, episode });
+        } catch {}
+
         await closeTask({ cwd: context.cwd, taskId: task.id });
         clearTaskFromSession(currentSession);
         agent.toolRuntime.setTaskContext(null);
@@ -5117,6 +5141,29 @@ async function promptLoop(agent, session, context) {
 
       await maybeAutoCompactConversation({ agent, currentSession, context, pendingInput: buildPrompt });
 
+      // Inject adaptive reminders from episodic memory
+      try {
+        const contractPaths = task.activeContract?.paths || [];
+        const taskTags = [task.name, task.goal].filter(Boolean).join(" ").toLowerCase().split(/\s+/).filter((w) => w.length >= 3);
+        const relevant = await findRelevantEpisodes({ cwd: context.cwd, filePatterns: contractPaths, tags: taskTags, limit: 3 });
+        if (relevant.length > 0) {
+          const reminders = buildReminderBlock({
+            episodes: relevant,
+            memoryText: context.runtime.projectMemory?.raw || "",
+            contractPaths
+          });
+          if (reminders) {
+            agent.setExecutionContext({
+              taskName: task.name,
+              chosenOption: task.chosenOption || null,
+              contractSummary: task.activeContract?.summary || null,
+              phase: "build",
+              reminders
+            });
+          }
+        }
+      } catch {}
+
       const turnSummary = { startedAt: Date.now(), tools: [], events: [{ at: Date.now(), name: "thinking" }] };
       const spinner = createProgressSpinner("building...");
       let lastProgressAt = Date.now();
@@ -5174,6 +5221,13 @@ async function promptLoop(agent, session, context) {
               markProgress();
               currentSession.runState = { state, detail: "", updatedAt: new Date().toISOString() };
             },
+            onPlan(plan) {
+              markProgress();
+              spinner.stop();
+              console.log(formatPlanForDisplay(plan));
+              printRailTransition("executing");
+              spinner.setLabel("executing plan...");
+            },
             onAssistantDelta() { markProgress(); },
             onToolStart(toolCall) {
               markProgress();

package/src/config.js

@@ -197,6 +197,7 @@ export function resolveRuntimeConfig(config, overrides = {}) {
           ? Boolean(config.panelEnabled)
           : true,
     decisionModel: overrides.decisionModel || config.decisionModel || "",
+    plannerModel: overrides.plannerModel || config.plannerModel || "",
     taskDefaults: normalizeTaskDefaults(
       overrides.taskDefaults !== undefined ? overrides.taskDefaults : config.taskDefaults
     ),

package/src/episodic.js

@@ -0,0 +1,279 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import crypto from "node:crypto";
+
+const STOP_WORDS = new Set(["the", "a", "an", "in", "to", "for", "of", "on", "at", "by", "and", "or", "is", "it", "this", "that", "with", "from", "as", "be", "was", "are"]);
+const MAX_INDEX_ENTRIES = 200;
+const MAX_EPISODIC_PROMPT_CHARS = 2000;
+const MAX_REMINDER_CHARS = 1500;
+const MAX_FILES_PER_EPISODE = 50;
+
+function memoryDir(cwd) {
+  return path.join(cwd, ".waterbrother", "memory");
+}
+
+function indexPath(cwd) {
+  return path.join(memoryDir(cwd), "index.json");
+}
+
+function episodePath(cwd, id) {
+  return path.join(memoryDir(cwd), `${id}.json`);
+}
+
+function slugify(name) {
+  return String(name || "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "")
+    .slice(0, 60);
+}
+
+function makeEpisodeId(taskName) {
+  const slug = slugify(taskName);
+  const rand = crypto.randomBytes(3).toString("hex");
+  return slug ? `ep_${slug}-${rand}` : `ep_${rand}`;
+}
+
+function deriveTags(text) {
+  return String(text || "")
+    .toLowerCase()
+    .split(/[\s/\\._\-:,;!?'"()[\]{}]+/)
+    .filter((w) => w.length >= 3 && !STOP_WORDS.has(w))
+    .filter((v, i, a) => a.indexOf(v) === i)
+    .slice(0, 20);
+}
+
+function deriveFilePatterns(files) {
+  const dirs = new Set();
+  for (const f of files) {
+    const dir = path.dirname(f).replace(/\\/g, "/");
+    if (dir && dir !== ".") dirs.add(`${dir}/**`);
+  }
+  return [...dirs];
+}
+
+async function readIndex(cwd) {
+  try {
+    const raw = await fs.readFile(indexPath(cwd), "utf8");
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
+}
+
+async function writeIndex(cwd, index) {
+  await fs.mkdir(memoryDir(cwd), { recursive: true });
+  await fs.writeFile(indexPath(cwd), `${JSON.stringify(index, null, 2)}\n`, "utf8");
+}
+
+export function compressEpisode({ task, receipt }) {
+  const id = makeEpisodeId(task.name || task.id);
+  const filesChanged = (receipt?.changedFiles || []).slice(0, MAX_FILES_PER_EPISODE);
+  const filePatterns = deriveFilePatterns(filesChanged);
+
+  // Key facts
+  const keyFacts = [];
+  if (task.goal) keyFacts.push(`Goal: ${task.goal}`);
+  if (task.chosenOption) {
+    const option = task.lastDecision?.options?.find((o) => o.id === task.chosenOption);
+    keyFacts.push(`Chose: ${task.chosenOption}${option?.title ? ` — ${option.title}` : ""}`);
+  }
+  if (receipt?.diffStat) {
+    const lastLine = receipt.diffStat.split("\n").pop()?.trim();
+    if (lastLine) keyFacts.push(`Diff: ${lastLine}`);
+  }
+  if (Array.isArray(receipt?.verification)) {
+    for (const v of receipt.verification) {
+      keyFacts.push(`Verify ${v.command}: ${v.ok ? "passed" : "FAILED"}`);
+    }
+  }
+
+  // Warnings and concerns
+  const warnings = [];
+  const sentinelConcerns = [];
+  if (receipt?.review?.concerns?.length) {
+    sentinelConcerns.push(...receipt.review.concerns);
+  }
+  if (receipt?.challenge?.concerns?.length) {
+    for (const c of receipt.challenge.concerns) {
+      if (!sentinelConcerns.includes(c)) sentinelConcerns.push(c);
+    }
+  }
+  if (Array.isArray(receipt?.verification)) {
+    for (const v of receipt.verification) {
+      if (!v.ok) warnings.push(`Verification failed: ${v.command}`);
+    }
+  }
+
+  // Outcome
+  let outcome = "closed-empty";
+  if (receipt?.mutated) {
+    outcome = task.accepted ? "accepted" : "closed-unaccepted";
+  }
+
+  // Tags from task name, goal, and file paths
+  const tagSource = [task.name, task.goal, ...filesChanged].join(" ");
+  const tags = deriveTags(tagSource);
+
+  return {
+    id,
+    taskId: task.id,
+    taskName: task.name || "",
+    closedAt: new Date().toISOString(),
+    goal: task.goal || "",
+    chosenOption: task.chosenOption || null,
+    outcome,
+    filesChanged,
+    filePatterns,
+    keyFacts: keyFacts.slice(0, 8),
+    warnings: warnings.slice(0, 5),
+    sentinelConcerns: sentinelConcerns.slice(0, 5),
+    tags
+  };
+}
+
+export async function saveEpisode({ cwd, episode }) {
+  await fs.mkdir(memoryDir(cwd), { recursive: true });
+  await fs.writeFile(episodePath(cwd, episode.id), `${JSON.stringify(episode, null, 2)}\n`, "utf8");
+
+  // Update index
+  const index = await readIndex(cwd);
+  const entry = {
+    id: episode.id,
+    taskName: episode.taskName,
+    closedAt: episode.closedAt,
+    tags: episode.tags,
+    filePatterns: episode.filePatterns,
+    outcome: episode.outcome
+  };
+  index.unshift(entry);
+  if (index.length > MAX_INDEX_ENTRIES) index.length = MAX_INDEX_ENTRIES;
+  await writeIndex(cwd, index);
+}
+
+export async function loadRecentEpisodes({ cwd, limit = 5 }) {
+  const index = await readIndex(cwd);
+  const recent = index.slice(0, limit);
+  const episodes = [];
+  for (const entry of recent) {
+    try {
+      const raw = await fs.readFile(episodePath(cwd, entry.id), "utf8");
+      episodes.push(JSON.parse(raw));
+    } catch {
+      // Skip missing/corrupt episodes
+    }
+  }
+  return episodes;
+}
+
+export async function findRelevantEpisodes({ cwd, filePatterns = [], tags = [], limit = 5 }) {
+  const index = await readIndex(cwd);
+  if (index.length === 0) return [];
+
+  const queryDirs = filePatterns.map((p) => p.replace(/\/?\*\*$/, "").replace(/\\/g, "/"));
+  const queryTags = new Set(tags.map((t) => t.toLowerCase()));
+
+  const scored = [];
+  for (const entry of index) {
+    let score = 0;
+
+    // File pattern overlap
+    if (queryDirs.length > 0 && Array.isArray(entry.filePatterns)) {
+      for (const ep of entry.filePatterns) {
+        const epDir = ep.replace(/\/?\*\*$/, "").replace(/\\/g, "/");
+        for (const qd of queryDirs) {
+          if (epDir.startsWith(qd) || qd.startsWith(epDir)) {
+            score += 3;
+            break;
+          }
+        }
+      }
+    }
+
+    // Tag overlap
+    if (queryTags.size > 0 && Array.isArray(entry.tags)) {
+      for (const t of entry.tags) {
+        if (queryTags.has(t)) score += 1;
+      }
+    }
+
+    if (score > 0) scored.push({ entry, score });
+  }
+
+  scored.sort((a, b) => b.score - a.score || new Date(b.entry.closedAt) - new Date(a.entry.closedAt));
+  const top = scored.slice(0, limit);
+
+  const episodes = [];
+  for (const { entry } of top) {
+    try {
+      const raw = await fs.readFile(episodePath(cwd, entry.id), "utf8");
+      episodes.push(JSON.parse(raw));
+    } catch {}
+  }
+  return episodes;
+}
+
+export function buildEpisodicMemoryBlock(episodes) {
+  if (!episodes || episodes.length === 0) return "";
+  const lines = ["Recent work in this project:"];
+  let chars = lines[0].length;
+
+  for (const ep of episodes) {
+    const date = ep.closedAt ? ep.closedAt.slice(0, 10) : "unknown";
+    const parts = [`[${date}] "${ep.taskName}" (${ep.outcome})`];
+    if (ep.keyFacts?.length > 0) parts.push(ep.keyFacts[0]);
+    if (ep.warnings?.length > 0) parts.push(`Warning: ${ep.warnings[0]}`);
+    if (ep.sentinelConcerns?.length > 0) parts.push(`Sentinel: ${ep.sentinelConcerns[0]}`);
+    const line = `- ${parts.join(". ")}`;
+    if (chars + line.length + 1 > MAX_EPISODIC_PROMPT_CHARS) break;
+    lines.push(line);
+    chars += line.length + 1;
+  }
+
+  return lines.join("\n");
+}
+
+export function buildReminderBlock({ episodes = [], memoryText = "", contractPaths = [] }) {
+  const contractDirs = contractPaths.map((p) => p.replace(/\/?\*\*$/, "").replace(/\\/g, "/").toLowerCase());
+  const reminders = [];
+  let chars = 0;
+
+  // From episodes: warnings and concerns for overlapping scopes
+  for (const ep of episodes) {
+    const epDirs = (ep.filePatterns || []).map((p) => p.replace(/\/?\*\*$/, "").replace(/\\/g, "/").toLowerCase());
+    const overlaps = contractDirs.length === 0 || epDirs.some((ed) => contractDirs.some((cd) => ed.startsWith(cd) || cd.startsWith(ed)));
+    if (!overlaps) continue;
+
+    for (const w of (ep.warnings || [])) {
+      const line = `[from "${ep.taskName}"]: ${w}`;
+      if (chars + line.length > MAX_REMINDER_CHARS) break;
+      reminders.push(line);
+      chars += line.length;
+    }
+    for (const c of (ep.sentinelConcerns || [])) {
+      const line = `[from "${ep.taskName}"]: Sentinel flagged: ${c}`;
+      if (chars + line.length > MAX_REMINDER_CHARS) break;
+      reminders.push(line);
+      chars += line.length;
+    }
+  }
+
+  // From WATERBROTHER.md: lines mentioning paths in contract scope
+  if (memoryText && contractDirs.length > 0) {
+    const memLines = memoryText.split("\n");
+    for (const ml of memLines) {
+      const lower = ml.toLowerCase();
+      const relevant = contractDirs.some((cd) => lower.includes(cd.split("/").pop()));
+      if (relevant && ml.trim().length > 5) {
+        const line = `[from WATERBROTHER.md]: ${ml.trim()}`;
+        if (chars + line.length > MAX_REMINDER_CHARS) break;
+        reminders.push(line);
+        chars += line.length;
+      }
+    }
+  }
+
+  if (reminders.length === 0) return "";
+  return `Reminders for this scope:\n${reminders.join("\n")}`;
+}

package/src/planner.js

@@ -0,0 +1,128 @@
+import { createJsonCompletion } from "./grok-client.js";
+
+const PLANNER_SCHEMA = `Respond with ONLY a JSON object matching this schema:
+{
+  "summary": "one-line summary of what will be done",
+  "steps": [
+    {
+      "action": "read|edit|create|delete|run",
+      "target": "file path or shell command",
+      "description": "what this step does and why"
+    }
+  ],
+  "risks": ["potential issues to watch for"],
+  "estimate": "rough scope — e.g. ~30 lines, 2 files"
+}`;
+
+const PLANNER_SYSTEM_PROMPT = `You are a senior engineer creating an implementation plan. You do NOT write code — you plan.
+
+Your job is to:
+1. Decompose the task into concrete, ordered steps
+2. Specify exactly which files to read, edit, create, or delete
+3. Specify which shell commands to run (tests, builds, etc.)
+4. Flag risks the executor should watch for
+5. Keep the plan tight — no unnecessary steps
+
+Rules:
+- Each step must have an action (read, edit, create, delete, run), a target (file path or command), and a description
+- Order matters — read before edit, edit before test
+- Include verification steps (run tests, lint, etc.)
+- Keep descriptions to one sentence
+- Do not include markdown, code fences, or text outside the JSON
+
+${PLANNER_SCHEMA}`;
+
+function buildPlannerPrompt({ task, goal, contract, memory, episodicContext }) {
+  const parts = [];
+  if (task?.name) parts.push(`Task: ${task.name}`);
+  if (goal) parts.push(`Goal: ${goal}`);
+  if (task?.chosenOption) {
+    const option = task.lastDecision?.options?.find((o) => o.id === task.chosenOption);
+    if (option) parts.push(`Chosen approach: ${option.title} — ${option.summary}`);
+  }
+  if (contract?.paths?.length) parts.push(`Contract scope: ${contract.paths.join(", ")}`);
+  if (contract?.commands?.length) parts.push(`Verification commands: ${contract.commands.join(", ")}`);
+  if (memory) parts.push(`Project context:\n${memory}`);
+  if (episodicContext) parts.push(`Recent history:\n${episodicContext}`);
+  parts.push("Create a step-by-step implementation plan as JSON.");
+  return parts.join("\n\n");
+}
+
+export function normalizePlan(plan) {
+  if (!plan || typeof plan !== "object") return null;
+  const steps = Array.isArray(plan.steps) ? plan.steps : [];
+  return {
+    summary: String(plan.summary || "").trim(),
+    steps: steps.map((s, i) => ({
+      number: i + 1,
+      action: ["read", "edit", "create", "delete", "run"].includes(String(s.action || "").trim())
+        ? String(s.action).trim()
+        : "read",
+      target: String(s.target || "").trim(),
+      description: String(s.description || "").trim()
+    })),
+    risks: Array.isArray(plan.risks) ? plan.risks.map(String) : [],
+    estimate: String(plan.estimate || "").trim()
+  };
+}
+
+export async function runPlannerPass({ apiKey, baseUrl, model, task, goal, contract, memory, episodicContext, signal }) {
+  if (!goal && !task?.name) throw new Error("goal or task name required for planner");
+
+  const messages = [
+    { role: "system", content: PLANNER_SYSTEM_PROMPT },
+    { role: "user", content: buildPlannerPrompt({ task, goal, contract, memory, episodicContext }) }
+  ];
+
+  const completion = await createJsonCompletion({
+    apiKey,
+    baseUrl,
+    model,
+    messages,
+    temperature: 0.2,
+    signal
+  });
+
+  const plan = normalizePlan(completion.json);
+  if (!plan || plan.steps.length === 0) {
+    throw new Error("Planner returned no steps");
+  }
+
+  return { plan, usage: completion.usage || null };
+}
+
+export function formatPlanForDisplay(plan) {
+  if (!plan) return "No plan available.";
+  const lines = [];
+  if (plan.summary) lines.push(plan.summary);
+  lines.push("");
+  for (const step of plan.steps) {
+    const icon = step.action === "read" ? "📖" : step.action === "edit" ? "✏️" : step.action === "create" ? "📄" : step.action === "delete" ? "🗑️" : step.action === "run" ? "▶" : "•";
+    lines.push(`  ${step.number}. ${icon} ${step.action} ${step.target}`);
+    if (step.description) lines.push(`     ${step.description}`);
+  }
+  if (plan.risks.length > 0) {
+    lines.push("");
+    for (const risk of plan.risks) {
+      lines.push(`  ⚠ ${risk}`);
+    }
+  }
+  if (plan.estimate) lines.push(`\n  ${plan.estimate}`);
+  return lines.join("\n");
+}
+
+export function formatPlanForExecutor(plan) {
+  if (!plan || !plan.steps?.length) return "";
+  const lines = ["Implementation plan — follow these steps in order:"];
+  for (const step of plan.steps) {
+    lines.push(`${step.number}. [${step.action}] ${step.target} — ${step.description}`);
+  }
+  if (plan.risks.length > 0) {
+    lines.push("\nRisks to watch for:");
+    for (const risk of plan.risks) {
+      lines.push(`- ${risk}`);
+    }
+  }
+  lines.push("\nExecute each step. Do not skip steps or improvise beyond the plan.");
+  return lines.join("\n");
+}

package/src/workflow.js

@@ -1,6 +1,7 @@
 import { createTask, findTaskByName, saveTask, slugify } from "./task-store.js";
 import { computeImpactMap, summarizeImpactMap } from "./impact.js";
 import { reviewTurn, challengeReceipt } from "./reviewer.js";
+import { runPlannerPass, formatPlanForExecutor, formatPlanForDisplay } from "./planner.js";
 
 export async function runBuildWorkflow({
   agent,
@@ -12,13 +13,44 @@ export async function runBuildWorkflow({
   if (!task) throw new Error("no active task");
   if (!promptText) throw new Error("build requires a prompt");
 
+  // Planner/Executor split: if plannerModel is configured, run planner first
+  const plannerModel = context.runtime?.plannerModel;
+  let planBlock = "";
+  if (plannerModel) {
+    try {
+      if (handlers.onStateChange) handlers.onStateChange("planning");
+      const { plan } = await runPlannerPass({
+        apiKey: context.runtime.apiKey,
+        baseUrl: context.runtime.baseUrl,
+        model: plannerModel,
+        task,
+        goal: promptText,
+        contract: task.activeContract || null,
+        memory: context.runtime.projectMemory?.promptText || "",
+        episodicContext: context.runtime.episodicMemory || "",
+        signal: handlers.signal
+      });
+      task.lastPlan = plan;
+      planBlock = formatPlanForExecutor(plan);
+      // Show the plan to the user
+      if (handlers.onPlan) {
+        handlers.onPlan(plan);
+      }
+    } catch (error) {
+      // Planner failure is non-fatal — fall back to unplanned execution
+      planBlock = "";
+    }
+  }
+
   // Inject execution context into agent system prompt
-  agent.setExecutionContext({
+  const executionCtx = {
     taskName: task.name,
     chosenOption: task.chosenOption || null,
     contractSummary: task.activeContract?.summary || null,
     phase: "build"
-  });
+  };
+  if (planBlock) executionCtx.plan = planBlock;
+  agent.setExecutionContext(executionCtx);
 
   // Pre-seed contract if task has one
   if (task.activeContract) {
@@ -35,8 +67,13 @@ export async function runBuildWorkflow({
     });
   }
 
+  // Build prompt: prepend plan if available
+  const executorPrompt = planBlock
+    ? `${planBlock}\n\n---\n\nNow execute: ${promptText}`
+    : promptText;
+
   // Run the turn
-  const response = await agent.runBuildTurn(promptText, handlers);
+  const response = await agent.runBuildTurn(executorPrompt, handlers);
 
   // Complete turn and get receipt
   const receipt = await agent.toolRuntime.completeTurn({ signal: handlers.signal });