@agjs/tsforge 0.2.6 → 0.2.8

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@agjs/tsforge",
   "type": "module",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "license": "MIT",
   "description": "TypeScript coding harness with a deterministic gate, stack-aware guardrails, and stream-level correction.",
   "repository": {

package/src/cli.ts

@@ -2,13 +2,7 @@
 import { join, isAbsolute } from "node:path";
 import { appendFileSync, mkdirSync } from "node:fs";
 import { createInterface } from "node:readline/promises";
-import {
-  runTask,
-  RUN_STATUS,
-  Session,
-  PLAN_APPROVED_NOTE,
-  LOOP_LIMITS,
-} from "./loop";
+import { runTask, RUN_STATUS, Session, PLAN_APPROVED_NOTE } from "./loop";
 import {
   PROVIDER_LIMITS,
   PROVIDER_DEFAULTS,
@@ -34,6 +28,7 @@ import {
 } from "./render";
 import type { ITask } from "./spec";
 import type { Reporter, ILoopEvent } from "./loop";
+import { loadLedger, activeRules, forgetMemory } from "./loop/memory";
 import {
   buildGate,
   buildWebGate,
@@ -681,6 +676,7 @@ const HELP = [
   "  /sessions        list saved sessions (resume one with: tsforge --resume <id>)",
   "  /cost            rough conversation size (messages + ~tokens)",
   "  /metrics         token totals + generation rate (tok/s) this session",
+  "  /memory          show learned failure→fix lessons (/memory forget to clear)",
   "  /exit, /quit     leave the session",
   "",
   "Anything else is sent to the agent. It works with its tools; when it stops,",
@@ -997,9 +993,10 @@ async function repl(args: ICliArgs): Promise<number> {
     session.setFix(buildWebFix(framework));
     session.setIncrementalCheck(buildWebTscCheck());
     session.guide(webGuidance(framework));
-    // A from-scratch web build needs the big turn budget — the default cap was
-    // measured to cut a todo app off mid-write, before its gate ever ran.
-    session.setMaxTurns(LOOP_LIMITS.webMaxTurns);
+    // A from-scratch web build legitimately needs many turns. Don't pin a low
+    // ceiling here — the interactive session already rides the high runaway
+    // backstop (interactiveBackstopTurns) and stops on the progress guards, so a
+    // long, converging build is never cut off mid-write.
   };
 
   // The `scaffold_web` tool invokes this when the AGENT decides to build a web app
@@ -1252,6 +1249,40 @@ async function repl(args: ICliArgs): Promise<number> {
         await printSessions(args.dir);
         break;
 
+      case "memory": {
+        if (arg.trim() === "forget") {
+          await forgetMemory(args.dir);
+          process.stdout.write("  memory cleared for this repo\n");
+          break;
+        }
+
+        const ledger = await loadLedger(args.dir);
+
+        if (ledger.entries.length === 0) {
+          process.stdout.write("  no learned lessons yet\n");
+          break;
+        }
+
+        const activeNames = new Set(
+          activeRules(ledger, Date.now()).map((r) => r.name)
+        );
+
+        process.stdout.write(
+          `  ${String(ledger.entries.length)} lesson(s), ${String(activeNames.size)} active (● fires · ○ still accruing):\n`
+        );
+
+        for (const entry of ledger.entries.slice(0, 20)) {
+          const mark = activeNames.has(entry.name) ? "●" : "○";
+
+          process.stdout.write(
+            `    ${mark} ${entry.rule} · ${String(entry.hits)} hit(s)\n`
+          );
+        }
+
+        process.stdout.write("  /memory forget to clear\n");
+        break;
+      }
+
       case "cost": {
         const chars = session.messages.reduce(
           (sum, m) => sum + m.content.length,

package/src/loop/loop.constants.ts

@@ -31,17 +31,31 @@ export const LOOP_LIMITS = {
    */
   maxEditLines: 50,
   /**
-   * Give up after the gate shows the EXACT same error set this many edits in a
-   * row (genuine spinning). Generous; the turn cap is the real backstop.
+   * Give up after the gate shows the EXACT same error SET this many edits in a
+   * row (genuine spinning) — the coarse net. The finer `samePersist` guard
+   * (below) usually trips first; this catches a stable-but-shuffling set.
    */
-  gateStuckRepeats: 10,
+  gateStuckRepeats: 6,
+  /**
+   * The PRIMARY no-progress guard: give up when a SINGLE error — same (file,rule)
+   * key — survives this many consecutive gate cycles, i.e. the model keeps failing
+   * at the same thing N attempts running, even while OTHER errors churn around it.
+   * This (not a raw turn count) is how the loop decides it's genuinely stuck.
+   */
+  samePersist: 5,
   /**
    * Above this many chars of combined file content, the seed prompt sends a
    * navigable project MAP instead of full dumps. Below it, full dumps.
    */
   mapThresholdChars: 12000,
-  /** Hard backstop on model turns per task. */
+  /** Hard backstop on model turns per HEADLESS task (eval/cron — no human to
+   *  intervene). Interactive sessions use `interactiveBackstopTurns` instead. */
   maxTurns: 40,
+  /** Interactive runaway safety only — NOT the primary stop. A human is present
+   *  and can interrupt, and the progress guards (`samePersist` / `gateStuckRepeats`)
+   *  pull the agent out the moment it stops converging, so this is set high enough
+   *  that normal long, productive back-and-forth never trips it. */
+  interactiveBackstopTurns: 250,
   /** Turn budget for a from-scratch WEB build (heavy gate, many files): used by
    *  headless web builds AND applied when an interactive session scaffolds via
    *  `scaffold_web` — measured: a todo app was still WRITING components when it

package/src/loop/loop.types.ts

@@ -37,6 +37,8 @@ export interface ILoopEvent {
    *  reads to tell a type error from a lint rule, not just a count. */
   rules?: readonly string[];
   passed?: boolean;
+  /** For `stuck` events: a human-readable blocker diagnosis. */
+  detail?: string;
   file?: string;
   /** For `create` events: the new file's content (rendered as a code block). */
   content?: string;
@@ -82,6 +84,9 @@ export interface IRunResult {
   /** Model turns used. */
   cycles: number;
   reason?: StuckReason;
+  /** When stuck: a human-readable blocker diagnosis (the persistent rule/file +
+   *  last error) so an interactive session can hand back something actionable. */
+  detail?: string;
   /** Edits/creates applied to editable files (measure edit churn). */
   edits?: number;
   /** Times an edit RAISED the gate error count (regressions). */

package/src/loop/memory/consolidate.ts

@@ -0,0 +1,254 @@
+import { join } from "node:path";
+import { rm } from "node:fs/promises";
+
+import { isRecord, isArray } from "../../lib/guards";
+import type { ITtsrRule } from "../ttsr";
+
+import {
+  EMPTY_LEDGER,
+  MIN_HITS_TO_ACTIVATE,
+  DECAY_MS,
+  type ICandidateLesson,
+  type ILedgerEntry,
+  type IMemoryLedger,
+} from "./memory.types";
+
+const MEMORY_DIR = ".tsforge";
+const LEDGER_FILE = "memory.json";
+const LEARNED_RULES_FILE = "learned-rules.json";
+const MAX_GUIDANCE = 300;
+
+/** Escape a string for use as a literal regex source. */
+function escapeRegex(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/** djb2 hash → base36, for a short stable id from a snippet. */
+function shortHash(text: string): string {
+  let hash = 5381;
+
+  for (let i = 0; i < text.length; i += 1) {
+    hash = (hash * 33) ^ text.charCodeAt(i);
+  }
+
+  return (hash >>> 0).toString(36);
+}
+
+/** The single most informative line of a snippet — the condition matches THIS,
+ *  not the whole (possibly multi-line) replaced block, so it stays a tight,
+ *  meaningful trigger. */
+function salientLine(before: string): string {
+  const lines = before
+    .split("\n")
+    .map((l) => l.trim())
+    .filter((l) => l.length > 0);
+
+  return lines.reduce(
+    (best, line) => (line.length > best.length ? line : best),
+    ""
+  );
+}
+
+/** A conservative literal-regex condition source matching the mistake's salient line. */
+export function conditionFor(before: string): string {
+  return escapeRegex(salientLine(before));
+}
+
+/** A deterministic, collision-resistant rule name from the gate rule + the snippet. */
+export function ruleName(rule: string, before: string): string {
+  const slug = rule.replace(/[^a-zA-Z0-9]+/g, "-").toLowerCase();
+
+  return `learned-${slug}-${shortHash(salientLine(before))}`;
+}
+
+/** TTSR file globs for the fixed file's family (by extension). */
+function fileGlobsFor(file: string): string[] {
+  if (file.endsWith(".tsx")) {
+    return ["**/*.tsx"];
+  }
+
+  if (file.endsWith(".ts")) {
+    return ["**/*.ts"];
+  }
+
+  return ["**/*"];
+}
+
+/** The corrective nudge shown when the learned pattern recurs (capped). */
+function guidanceFor(rule: string, after: string): string {
+  const fix = salientLine(after);
+  const base = `This pattern previously failed the gate (${rule}) in this repo. Use the known-good fix instead`;
+  const withFix = fix.length > 0 ? `${base}, e.g.: ${fix}` : `${base}.`;
+
+  return withFix.length > MAX_GUIDANCE
+    ? `${withFix.slice(0, MAX_GUIDANCE - 1)}…`
+    : withFix;
+}
+
+function candidateToEntry(
+  candidate: ICandidateLesson,
+  sessionId: string,
+  now: number
+): ILedgerEntry {
+  return {
+    name: ruleName(candidate.rule, candidate.before),
+    rule: candidate.rule,
+    condition: conditionFor(candidate.before),
+    guidance: guidanceFor(candidate.rule, candidate.after),
+    fileGlobs: fileGlobsFor(candidate.file),
+    hits: 1,
+    source: sessionId,
+    lastSeen: now,
+  };
+}
+
+/**
+ * Merge a run's candidates into the ledger. `hits` counts DISTINCT SESSIONS, so
+ * multiple candidates with the same name from one run bump it by exactly one;
+ * a lesson from a NEW session bumps an existing entry. Returns a new ledger.
+ */
+export function mergeCandidates(
+  ledger: IMemoryLedger,
+  candidates: readonly ICandidateLesson[],
+  sessionId: string,
+  now: number
+): IMemoryLedger {
+  const byName = new Map<string, ILedgerEntry>(
+    ledger.entries.map((e) => [e.name, e])
+  );
+  // Dedupe this session's candidates by name first (one fix seen twice in a run
+  // is still one occurrence).
+  const seenThisSession = new Set<string>();
+
+  for (const candidate of candidates) {
+    const name = ruleName(candidate.rule, candidate.before);
+
+    if (seenThisSession.has(name)) {
+      continue;
+    }
+
+    seenThisSession.add(name);
+
+    const existing = byName.get(name);
+
+    if (existing === undefined) {
+      byName.set(name, candidateToEntry(candidate, sessionId, now));
+      continue;
+    }
+
+    // A new session re-producing the lesson bumps hits; the same session never does.
+    const bump = existing.source === sessionId ? 0 : 1;
+
+    byName.set(name, {
+      ...existing,
+      hits: existing.hits + bump,
+      source: sessionId,
+      lastSeen: now,
+    });
+  }
+
+  return { version: 1, entries: [...byName.values()] };
+}
+
+/** Project the ledger to ACTIVE learned TTSR rules: recurring (hits ≥ threshold)
+ *  and not decayed (seen within DECAY_MS). Accumulation ≠ injection. */
+export function activeRules(ledger: IMemoryLedger, now: number): ITtsrRule[] {
+  return ledger.entries
+    .filter(
+      (e) => e.hits >= MIN_HITS_TO_ACTIVATE && now - e.lastSeen < DECAY_MS
+    )
+    .map((e) => ({
+      name: e.name,
+      condition: [e.condition],
+      scope: "tool-args" as const,
+      fileGlobs: e.fileGlobs,
+      guidance: e.guidance,
+      repeatMode: "cooldown" as const,
+      repeatGap: 3,
+    }));
+}
+
+/** Parse a stored ledger, tolerating any malformation (→ empty), like the rest
+ *  of tsforge's disk readers. */
+function parseLedger(content: string): IMemoryLedger {
+  let parsed: unknown;
+
+  try {
+    parsed = JSON.parse(content);
+  } catch {
+    return EMPTY_LEDGER;
+  }
+
+  if (!isRecord(parsed) || !isArray(parsed.entries)) {
+    return EMPTY_LEDGER;
+  }
+
+  const entries = parsed.entries.filter(
+    (e): e is ILedgerEntry =>
+      isRecord(e) &&
+      typeof e.name === "string" &&
+      typeof e.rule === "string" &&
+      typeof e.condition === "string" &&
+      typeof e.guidance === "string" &&
+      isArray(e.fileGlobs) &&
+      typeof e.hits === "number" &&
+      typeof e.source === "string" &&
+      typeof e.lastSeen === "number"
+  );
+
+  return { version: 1, entries };
+}
+
+/** Forget all learned memory for a project: delete the ledger and the active
+ *  learned-rules file (`tsforge memory forget`). Best-effort. */
+export async function forgetMemory(cwd: string): Promise<void> {
+  for (const name of [LEDGER_FILE, LEARNED_RULES_FILE]) {
+    await rm(join(cwd, MEMORY_DIR, name), { force: true });
+  }
+}
+
+/** Load the project ledger from `<cwd>/.tsforge/memory.json`. */
+export async function loadLedger(cwd: string): Promise<IMemoryLedger> {
+  const file = Bun.file(join(cwd, MEMORY_DIR, LEDGER_FILE));
+
+  if (!(await file.exists())) {
+    return EMPTY_LEDGER;
+  }
+
+  return parseLedger(await file.text());
+}
+
+/**
+ * The full Phase-1 consolidation step: load the ledger, merge this run's
+ * candidates, persist the ledger, and (re)write the active learned-rules file
+ * the TTSR loader reads. Returns the count of active rules written.
+ */
+export async function consolidate(
+  cwd: string,
+  candidates: readonly ICandidateLesson[],
+  sessionId: string,
+  now: number = Date.now()
+): Promise<number> {
+  if (candidates.length === 0) {
+    return 0;
+  }
+
+  const merged = mergeCandidates(
+    await loadLedger(cwd),
+    candidates,
+    sessionId,
+    now
+  );
+  const active = activeRules(merged, now);
+
+  await Bun.write(
+    join(cwd, MEMORY_DIR, LEDGER_FILE),
+    `${JSON.stringify(merged, null, 2)}\n`
+  );
+  await Bun.write(
+    join(cwd, MEMORY_DIR, LEARNED_RULES_FILE),
+    `${JSON.stringify(active, null, 2)}\n`
+  );
+
+  return active.length;
+}

package/src/loop/memory/index.ts

@@ -0,0 +1,18 @@
+export { mineLessons } from "./mine";
+export {
+  consolidate,
+  loadLedger,
+  forgetMemory,
+  mergeCandidates,
+  activeRules,
+  conditionFor,
+  ruleName,
+} from "./consolidate";
+export {
+  EMPTY_LEDGER,
+  MIN_HITS_TO_ACTIVATE,
+  DECAY_MS,
+  type ICandidateLesson,
+  type ILedgerEntry,
+  type IMemoryLedger,
+} from "./memory.types";

package/src/loop/memory/memory.types.ts

@@ -0,0 +1,65 @@
+/**
+ * tsforge MEMORY — the reflect → distill → consolidate → recall loop.
+ *
+ * Phase 1 (this module set) is the failure→fix channel: mine a run's event
+ * stream for mistakes the model MADE then FIXED, accumulate them in a local
+ * ledger with recurrence counts, and project the recurring ones into the
+ * `.tsforge/learned-rules.json` TTSR file the harness already loads. Memory
+ * accumulates aggressively; recall stays cheap (a learned rule is a dormant
+ * trigger — zero prompt cost until the exact mistake recurs).
+ */
+
+/** A mistake-then-fix pair mined from one run: the gate rule that was failing,
+ *  the file it was fixed in, and the edit that cleared it. */
+export interface ICandidateLesson {
+  /** The gate rule/code that disappeared after the edit (e.g. "no-explicit-any",
+   *  "TS18048"). */
+  readonly rule: string;
+  /** The file whose edit cleared the failure. */
+  readonly file: string;
+  /** The offending snippet (the edit's replaced text). */
+  readonly before: string;
+  /** The fix (the edit's replacement text). */
+  readonly after: string;
+}
+
+/** One accumulated lesson in the project ledger. Carries provenance so it can
+ *  decay: a lesson the model stops re-committing eventually retires. */
+export interface ILedgerEntry {
+  /** Stable, deterministic rule name (derived from rule + a hash of `before`). */
+  readonly name: string;
+  /** The gate rule/code this lesson guards against. */
+  readonly rule: string;
+  /** The TTSR condition (a conservative literal regex source matching `before`). */
+  readonly condition: string;
+  /** The corrective guidance injected when the pattern recurs (≤300 chars). */
+  readonly guidance: string;
+  /** Glob(s) the rule applies to (the fixed file's directory family). */
+  readonly fileGlobs: readonly string[];
+  /** How many distinct sessions have produced this lesson. */
+  readonly hits: number;
+  /** The most recent session id that produced it. */
+  readonly source: string;
+  /** ms timestamp of the most recent occurrence (for decay). */
+  readonly lastSeen: number;
+}
+
+/** The on-disk project ledger (`.tsforge/memory.json`): every candidate ever
+ *  seen, with counts. The subset with `hits >= MIN_HITS_TO_ACTIVATE` is
+ *  projected into the active `.tsforge/learned-rules.json`. */
+export interface IMemoryLedger {
+  readonly version: 1;
+  readonly entries: readonly ILedgerEntry[];
+}
+
+/** Empty ledger for a repo with no memory yet. */
+export const EMPTY_LEDGER: IMemoryLedger = { version: 1, entries: [] };
+
+/** A lesson must be seen in at least this many sessions before it becomes an
+ *  active learned rule — so a single fluke fix never starts steering future
+ *  runs (accumulation ≠ injection). */
+export const MIN_HITS_TO_ACTIVATE = 2;
+
+/** A learned rule unseen for longer than this is retired from the active set
+ *  (kept in the ledger but no longer projected), so stale lessons don't silt up. */
+export const DECAY_MS = 1000 * 60 * 60 * 24 * 45; // 45 days

package/src/loop/memory/mine.ts

@@ -0,0 +1,76 @@
+import type { ILoopEvent } from "../loop.types";
+
+import type { ICandidateLesson } from "./memory.types";
+
+/** Cap edits attributed to a single fix window — keeps a noisy burst of edits
+ *  from cross-producing a flood of weak candidates (the hits gate filters the
+ *  rest anyway). */
+const MAX_EDITS_PER_WINDOW = 3;
+
+interface IEditWindow {
+  file: string;
+  before: string;
+  after: string;
+}
+
+/**
+ * Mine a run's event stream for failure→fix lessons: a gate rule/code that was
+ * FAILING and then DISAPPEARED after one or more edits. Each such (rule, edit)
+ * pair is a candidate — the edit's replaced text (`before`) is the mistake, its
+ * replacement (`after`) is the fix.
+ *
+ * Deterministic, no model call. Only `edit` events teach (they carry the
+ * before→after diff); `create` is net-new so there is no mistake-pattern to
+ * learn. Attribution is coarse (the validated event lists rule codes, not their
+ * files), so one fix window can yield a few candidates; the cross-session hits
+ * gate in consolidation is what promotes only the recurring, real ones.
+ */
+export function mineLessons(events: readonly ILoopEvent[]): ICandidateLesson[] {
+  const candidates: ICandidateLesson[] = [];
+  let prevFailing: Set<string> | null = null;
+  let edits: IEditWindow[] = [];
+
+  for (const event of events) {
+    if (
+      event.kind === "edit" &&
+      event.file !== undefined &&
+      event.oldString !== undefined &&
+      event.newString !== undefined &&
+      event.oldString.trim().length > 0
+    ) {
+      edits.push({
+        file: event.file,
+        before: event.oldString,
+        after: event.newString,
+      });
+
+      continue;
+    }
+
+    if (event.kind !== "validated") {
+      continue;
+    }
+
+    const failing = new Set(event.rules ?? []);
+
+    if (prevFailing !== null && edits.length > 0) {
+      const fixed = [...prevFailing].filter((rule) => !failing.has(rule));
+
+      for (const rule of fixed) {
+        for (const edit of edits.slice(-MAX_EDITS_PER_WINDOW)) {
+          candidates.push({
+            rule,
+            file: edit.file,
+            before: edit.before,
+            after: edit.after,
+          });
+        }
+      }
+    }
+
+    prevFailing = failing;
+    edits = [];
+  }
+
+  return candidates;
+}