@agjs/tsforge 0.2.6 → 0.2.8

package/src/loop/session.ts

@@ -28,7 +28,10 @@ import {
 import { connectMcpServers } from "../mcp";
 import { loadAndRegisterPlugins } from "../config/external-plugins";
 import { LOOP_LIMITS, RUN_STATUS } from "./loop.constants";
-import type { Reporter } from "./loop.types";
+import type { Reporter, ILoopEvent } from "./loop.types";
+import type { TtsrManager } from "./ttsr";
+import { initTtsrManager, applyTtsrInterrupt } from "./ttsr-init";
+import { mineLessons, consolidate as consolidateMemory } from "./memory";
 import { CHAT_SYSTEM, COMPACT_SYSTEM } from "./prompt";
 import {
   buildTsService,
@@ -396,6 +399,12 @@ export class Session {
   private readonly forceTools: boolean;
   /** Mid-session turn-cap override (setMaxTurns) — a web scaffold raises it. */
   private maxTurnsOverride?: number;
+  /** TTSR manager (built-in + project + memory-learned rules). Null when TTSR is
+   *  disabled. Built in `create` (needs async rule loading). */
+  private ttsrManager: TtsrManager | null = null;
+  /** Events of the CURRENT send (reset each drive), buffered off ctx.report so the
+   *  post-send memory hook can mine the run for failure→fix lessons. */
+  private readonly sendEvents: ILoopEvent[] = [];
 
   private constructor(cfg: ISessionConfig, ctx: ILoopCtx) {
     this.provider = cfg.provider;
@@ -443,9 +452,19 @@ export class Session {
     }
 
     this.ctx = ctx;
+    // Buffer events off ctx.report (where edit/create/validated flow) so the
+    // post-send memory hook can mine them; still forward to the original reporter.
+    const rawCtxReport = ctx.report;
+
+    this.ctx.report = (event) => {
+      this.sendEvents.push(event);
+      rawCtxReport(event);
+    };
+
     this.state = {
       prevGateErrors: [],
       gateNoProgress: 0,
+      errorAge: new Map(),
       lastGateCount: -1,
       edits: 0,
       regressions: 0,
@@ -522,7 +541,14 @@ export class Session {
       },
     };
 
-    return new Session(cfg, ctx);
+    const session = new Session(cfg, ctx);
+
+    // Build the TTSR manager (built-in + project + memory-learned rules) so the
+    // interactive loop gets the SAME mid-stream guidance the headless loop does —
+    // including the failure→fix lessons learned in this repo.
+    session.ttsrManager = await initTtsrManager(cfg.cwd, report, SESSION_ID);
+
+    return session;
   }
 
   /** The current gate command (empty when none). */
@@ -698,8 +724,13 @@ export class Session {
    */
   async send(text: string, opts: ISendOptions = {}): Promise<ISendResult> {
     const { ctx, report } = this;
+    // Interactive ceiling is a RUNAWAY backstop, not the primary stop — the
+    // progress guards (samePersist / gateNoProgress) pull the agent out the moment
+    // it stops converging. Set high so normal long back-and-forth never trips it.
     const maxTurns =
-      this.maxTurnsOverride ?? this.cfg.maxTurns ?? LOOP_LIMITS.maxTurns;
+      this.maxTurnsOverride ??
+      this.cfg.maxTurns ??
+      LOOP_LIMITS.interactiveBackstopTurns;
     const sendStart = performance.now();
 
     // Thread cancellation to the tool `run` commands and the gate (not just the
@@ -1018,6 +1049,9 @@ export class Session {
       mcpSchemas.length > 0 ? [...baseTools, ...mcpSchemas] : baseTools;
     const callStart = performance.now();
     let firstTokenAt = 0;
+
+    this.ttsrManager?.resetBuffer();
+
     const res = await this.provider.complete(ctx.messages, {
       tools: offeredTools,
       temperature: this.cfg.temperature ?? 0,
@@ -1026,6 +1060,7 @@ export class Session {
       ...(this.cfg.thinkingTokenBudget === undefined
         ? {}
         : { thinkingTokenBudget: this.cfg.thinkingTokenBudget }),
+      ...this.ttsrCallOption(),
       ...(signal === undefined ? {} : { signal }),
       onToken: (token, channel) => {
         // Stamp the first token so tokens/sec measures generation rate (excluding
@@ -1067,6 +1102,10 @@ export class Session {
 
     ctx.messages.push(assistantMessage(res));
 
+    // Every model call advances TTSR cooldown accounting (including interrupted
+    // ones, so repeatGap rules count correctly after a retry).
+    this.ttsrManager?.incrementTurnCount();
+
     if (res.salvaged !== undefined && res.salvaged > 0) {
       report({
         kind: "tool",
@@ -1364,10 +1403,103 @@ export class Session {
     }
   }
 
+  /** Drive one send to a terminal result, then mine the send's events for
+   *  failure→fix lessons (best-effort, never affects the result). The buffer is
+   *  reset per send so each maps to one "run". */
   private async drive(
     maxTurns: number,
     sendStart: number,
     opts: ISendOptions
+  ): Promise<ISendResult> {
+    this.sendEvents.length = 0;
+
+    try {
+      return await this.driveInner(maxTurns, sendStart, opts);
+    } finally {
+      await this.consolidateLessons();
+    }
+  }
+
+  /** Mine the current send's events into the project's learned-rules memory.
+   *  Gated on the TTSR flag (learned rules are recalled via TTSR). */
+  private async consolidateLessons(): Promise<void> {
+    if (!flags.ttsr()) {
+      return;
+    }
+
+    try {
+      const candidates = mineLessons(this.sendEvents);
+      const runId = `${SESSION_ID}-${Date.now().toString(36)}`;
+      const active = await consolidateMemory(this.ctx.cwd, candidates, runId);
+
+      if (active > 0) {
+        this.report({
+          kind: "ttsr",
+          task: SESSION_ID,
+          message: `memory: ${String(active)} learned rule(s) active in .tsforge/learned-rules.json`,
+        });
+      }
+    } catch {
+      // Memory is supplementary — never let it break a send.
+    }
+  }
+
+  /** The `ttsrManager` completion option, or nothing when TTSR is off. */
+  private ttsrCallOption():
+    | { ttsrManager: TtsrManager }
+    | Record<string, never> {
+    return this.ttsrManager === null ? {} : { ttsrManager: this.ttsrManager };
+  }
+
+  /** Apply a mid-stream TTSR fire (inject guidance, retry). Returns true when it
+   *  fired (the caller should `continue`). */
+  private handleTtsrFired(
+    res: IModelResponse,
+    turn: number,
+    turnStart: number,
+    sendStart: number
+  ): boolean {
+    if (res.ttsrFired === undefined) {
+      return false;
+    }
+
+    applyTtsrInterrupt(
+      res.ttsrFired,
+      this.state,
+      this.ctx.messages,
+      this.report,
+      SESSION_ID,
+      this.ttsrManager
+    );
+    emitTiming(this.report, SESSION_ID, turn, turnStart, sendStart);
+
+    return true;
+  }
+
+  /** Handle a degenerate stream: a bounded recovery or a terminal stop. Returns a
+   *  stop result, "retry" to continue with a forced tool, or null if not degenerate. */
+  private degenerationStop(
+    res: IModelResponse,
+    degenerations: number,
+    turn: number,
+    turnStart: number,
+    sendStart: number
+  ): ISendResult | "retry" | null {
+    if (res.degenerated !== true) {
+      return null;
+    }
+
+    const stop = this.degenerationRecovery(degenerations, turn);
+
+    emitTiming(this.report, SESSION_ID, turn, turnStart, sendStart);
+
+    return stop ?? "retry";
+  }
+
+  private async driveInner(
+    maxTurns: number,
+    sendStart: number,
+    opts: ISendOptions
   ): Promise<ISendResult> {
     const { ctx, report } = this;
     // The gate confirms CHANGES, not answers: it fires only once the model has
@@ -1433,24 +1565,34 @@ export class Session {
 
       forceTool = false;
 
-      // The stream caught a degenerate repetition loop. Try a BOUNDED recovery
-      // (force a concrete tool call next turn — can't loop in prose) before
-      // giving up; see degenerationRecovery.
-      if (res.degenerated === true) {
-        const stop = this.degenerationRecovery(degenerations, turn);
-
-        emitTiming(report, SESSION_ID, turn, turnStart, sendStart);
+      // A learned/built-in TTSR rule fired mid-stream — inject its corrective
+      // guidance and retry (checked before degeneration so the fix lands first).
+      // This is how memory's failure→fix lessons reach an interactive session.
+      if (this.handleTtsrFired(res, turn, turnStart, sendStart)) {
+        continue;
+      }
 
-        if (stop !== null) {
-          return stop;
-        }
+      // The stream caught a degenerate repetition loop. Bounded recovery (force a
+      // concrete tool call next turn) before giving up; see degenerationRecovery.
+      const deg = this.degenerationStop(
+        res,
+        degenerations,
+        turn,
+        turnStart,
+        sendStart
+      );
 
+      if (deg === "retry") {
         degenerations += 1;
         forceTool = true;
 
         continue;
       }
 
+      if (deg !== null) {
+        return deg;
+      }
+
       // FORCED-TOOLS: a lone yield_status call becomes a normal stop.
       this.resolveYieldCalls(res);
 
@@ -1505,7 +1647,7 @@ export class Session {
       kind: "stuck",
       task: SESSION_ID,
       cycles: maxTurns,
-      message: `stuck (hit ${maxTurns}-turn cap)`,
+      message: `stuck (hit the ${maxTurns}-turn runaway backstop — progress guards never tripped, which is unusual; re-steer or narrow the task)`,
     });
 
     return { status: "stuck", turns: maxTurns };

package/src/loop/ttsr-init.ts

@@ -0,0 +1,111 @@
+import { join } from "node:path";
+
+import type { Reporter } from "./loop.types";
+import type { ILoopState } from "./turn";
+import type { IChatMessage } from "../inference";
+import { flags } from "../config";
+import { TtsrManager, parseProjectRules, type ITtsrRule } from "./ttsr";
+import { DEFAULT_TTSR_RULES } from "./ttsr-defaults";
+
+const TTSR_INTERRUPT_CAP = 3;
+
+/**
+ * Load a project's TTSR rules: hand-authored `.tsforge/rules.json` AND the
+ * memory-learned `.tsforge/learned-rules.json` (the failure→fix lessons the
+ * harness wrote itself). Both are tolerated-if-missing. Learned rules are named
+ * `learned-*`, so they never collide with hand or built-in rules on dedup.
+ */
+export async function loadProjectTtsrRules(cwd: string): Promise<ITtsrRule[]> {
+  const files = [
+    join(cwd, ".tsforge", "rules.json"),
+    join(cwd, ".tsforge", "learned-rules.json"),
+  ];
+  const rules: ITtsrRule[] = [];
+
+  for (const path of files) {
+    const file = Bun.file(path);
+
+    if (await file.exists()) {
+      rules.push(...parseProjectRules(await file.text()));
+    }
+  }
+
+  return rules;
+}
+
+/**
+ * Build the TTSR manager for a run: built-in defaults + project + learned rules.
+ * Shared by the headless loop (run.ts) and the interactive session (session.ts).
+ * Returns null when TTSR is disabled by flag.
+ */
+export async function initTtsrManager(
+  cwd: string,
+  report: Reporter,
+  taskId: string
+): Promise<TtsrManager | null> {
+  if (!flags.ttsr()) {
+    return null;
+  }
+
+  const manager = new TtsrManager();
+
+  for (const rule of DEFAULT_TTSR_RULES) {
+    manager.addRule(rule);
+  }
+
+  let added = 0;
+
+  for (const rule of await loadProjectTtsrRules(cwd)) {
+    if (manager.addRule(rule)) {
+      added += 1;
+    }
+  }
+
+  if (added > 0) {
+    report({
+      kind: "ttsr",
+      task: taskId,
+      message: `loaded ${added} project/learned TTSR rule(s) from .tsforge/`,
+    });
+  }
+
+  return manager;
+}
+
+/**
+ * Apply a TTSR interrupt: count it, report it, inject the corrective guidance as
+ * a user message, and disable the manager once the per-run cap is hit (so a
+ * stubborn pattern can't loop forever). Shared by both loops; the caller decides
+ * what to do next (retry the turn). Timing emission stays with the caller.
+ */
+export function applyTtsrInterrupt(
+  ttsrFired: { ruleName: string; guidance: string },
+  state: ILoopState,
+  messages: IChatMessage[],
+  report: Reporter,
+  taskId: string,
+  ttsrManager: TtsrManager | null
+): void {
+  state.ttsrInterrupts += 1;
+
+  report({
+    kind: "ttsr",
+    task: taskId,
+    message: `⚠ TTSR interrupted: ${ttsrFired.ruleName}`,
+  });
+
+  if (state.ttsrInterrupts >= TTSR_INTERRUPT_CAP) {
+    report({
+      kind: "tool",
+      task: taskId,
+      message: `TTSR disabled after ${state.ttsrInterrupts} interrupts (hit cap)`,
+    });
+
+    ttsrManager?.disable();
+  }
+
+  messages.push({
+    role: "user",
+    content: `⚠ generation interrupted: ${ttsrFired.guidance} Rewrite the affected part without that pattern.`,
+  });
+}

package/src/loop/turn.ts

@@ -8,6 +8,7 @@ import {
   sameErrorSet,
   type ErrorParser,
   type ErrorSet,
+  type IErrorItem,
 } from "../validate";
 import { isInScope } from "../lib/scope";
 import { fileExists, resolveScopeFiles } from "../lib/fs";
@@ -126,6 +127,9 @@ export interface ILoopCtx {
 export interface ILoopState {
   prevGateErrors: ErrorSet;
   gateNoProgress: number;
+  /** Per-error-key (file:rule) survival count: how many consecutive gate cycles
+   *  each error has persisted. Drives the primary `samePersist` no-progress stop. */
+  errorAge: Map<string, number>;
   lastGateCount: number;
   edits: number;
   regressions: number;
@@ -688,6 +692,46 @@ function autoFixNotice(files: string[]): string {
   );
 }
 
+/**
+ * Advance each error's per-(file:rule) survival count and return the first error
+ * that has now persisted for `samePersist` consecutive gate cycles — the model
+ * keeps failing at the SAME thing — or null. Rebuilds the map from the CURRENT
+ * keys, so a fixed error's age drops out (no stale growth) and an error that
+ * comes back later starts fresh. Catches "stuck on X" even while OTHER errors
+ * churn around it (which the whole-set `gateNoProgress` guard misses).
+ */
+export function trackErrorAges(
+  state: ILoopState,
+  gateErrors: ErrorSet
+): IErrorItem | null {
+  const next = new Map<string, number>();
+  let stuck: IErrorItem | null = null;
+
+  for (const e of gateErrors) {
+    const age = (state.errorAge.get(e.key) ?? 0) + 1;
+
+    next.set(e.key, age);
+
+    if (age >= LOOP_LIMITS.samePersist && stuck === null) {
+      stuck = e;
+    }
+  }
+
+  state.errorAge = next;
+
+  return stuck;
+}
+
+/** The blocker diagnosis surfaced when a single error persists too long — names
+ *  the rule + file + attempt count + the last message, so an interactive session
+ *  hands back something the user can act on. */
+export function persistDetail(e: IErrorItem): string {
+  const where = e.file !== undefined ? ` in ${e.file}` : "";
+  const rule = e.rule ?? "the same error";
+
+  return `stuck on ${rule}${where} after ${String(LOOP_LIMITS.samePersist)} attempts (last: ${e.message.slice(0, 140)})`;
+}
+
 /**
  * The deterministic gate — the only authority on "done". Auto-fix, run the
  * optional fix command, validate, and return a terminal result (done/stuck) or
@@ -817,17 +861,47 @@ export async function settleGate(
     };
   }
 
+  // PRIMARY no-progress stop: the model keeps failing at the SAME (file,rule)
+  // for `samePersist` cycles running — even if other errors churn. Hand back a
+  // concrete blocker rather than spinning to a raw turn cap.
+  const persisted = trackErrorAges(state, gateErrors);
+
+  if (persisted !== null) {
+    const detail = persistDetail(persisted);
+
+    report({
+      kind: "stuck",
+      task: task.id,
+      cycles: turn,
+      detail,
+      message: `task ${task.id}: ${detail}`,
+    });
+
+    return {
+      task: task.id,
+      redConfirmed: true,
+      status: RUN_STATUS.stuck,
+      cycles: turn,
+      reason: STUCK_REASON.stalled,
+      detail,
+    };
+  }
+
+  // Coarser secondary net: the WHOLE error set unchanged this many cycles.
   state.gateNoProgress = sameErrorSet(state.prevGateErrors, gateErrors)
     ? state.gateNoProgress + 1
     : 0;
   state.prevGateErrors = gateErrors;
 
   if (state.gateNoProgress >= LOOP_LIMITS.gateStuckRepeats) {
+    const detail = `gate unchanged ${String(LOOP_LIMITS.gateStuckRepeats)} cycles (${String(gateErrors.length)} error(s) not converging)`;
+
     report({
       kind: "stuck",
       task: task.id,
       cycles: turn,
-      message: `task ${task.id}: stuck (gate unchanged ${LOOP_LIMITS.gateStuckRepeats}x)`,
+      detail,
+      message: `task ${task.id}: stuck — ${detail}`,
     });
 
     return {
@@ -836,6 +910,7 @@ export async function settleGate(
       status: RUN_STATUS.stuck,
       cycles: turn,
       reason: STUCK_REASON.stalled,
+      detail,
     };
   }