@agjs/tsforge 0.1.0

package/src/loop/loop.types.ts

@@ -0,0 +1,99 @@
+import type { ErrorParser } from "../validate";
+import {
+  type RUN_STATUS,
+  type STUCK_REASON,
+  type SPEC_STATUS,
+} from "./loop.constants";
+
+/** A progress event emitted as the loop runs, for live observability. */
+export interface ILoopEvent {
+  kind:
+    | "start"
+    | "red"
+    | "cycle"
+    | "token"
+    | "message"
+    | "fix"
+    | "edit"
+    | "create"
+    | "validated"
+    | "done"
+    | "stuck"
+    | "run"
+    | "tool"
+    | "repair"
+    | "timing"
+    | "usage"
+    | "ttsr";
+  task: string;
+  message: string;
+  cycle?: number;
+  cycles?: number;
+  /** For `timing` events: how long the turn took, in milliseconds. */
+  ms?: number;
+  errors?: number;
+  passed?: boolean;
+  file?: string;
+  /** For `create` events: the new file's content (rendered as a code block). */
+  content?: string;
+  /** For `edit` events: the replaced / replacement snippets (rendered as a diff). */
+  oldString?: string;
+  newString?: string;
+  /** For `run` events: the shell command and its result. */
+  command?: string;
+  exitCode?: number;
+  output?: string;
+  /** For `token` events: which stream it came from. The renderer collapses
+   *  `reasoning` to a compact "thinking…" indicator (the full text still goes to
+   *  the log); `tool` markers and gate output (no channel) print normally. */
+  channel?: "reasoning" | "content" | "tool";
+  /** For `usage` events: real per-call token accounting (for the --log metrics). */
+  promptTokens?: number;
+  completionTokens?: number;
+  totalTokens?: number;
+  /** For `usage` (and salvage-warning `tool`) events: whether THIS model call
+   *  ran with thinking enabled — lets the analyzer correlate malformed-tool-call
+   *  rate with the thinking mode (see analyze-malformed). */
+  thinking?: boolean;
+  /** For the `start` event: run metadata, so a log is self-describing for the
+   *  analyzer (which model / how big a context window the metrics are against). */
+  model?: string;
+  contextWindow?: number;
+}
+
+export type Reporter = (event: ILoopEvent) => void;
+
+export type RunStatus = (typeof RUN_STATUS)[keyof typeof RUN_STATUS];
+export type StuckReason = (typeof STUCK_REASON)[keyof typeof STUCK_REASON];
+export type SpecStatus = (typeof SPEC_STATUS)[keyof typeof SPEC_STATUS];
+
+export interface IRunResult {
+  task: string;
+  /** The gate failed before we started (a real goalpost). */
+  redConfirmed: boolean;
+  status: RunStatus;
+  /** Model turns used. */
+  cycles: number;
+  reason?: StuckReason;
+  /** Edits/creates applied to editable files (measure edit churn). */
+  edits?: number;
+  /** Times an edit RAISED the gate error count (regressions). */
+  regressions?: number;
+}
+
+export interface IRunOptions {
+  parse?: ErrorParser;
+  onEvent?: Reporter;
+  temperature?: number;
+  /** Per-request thinking toggle passed to the provider. */
+  enableThinking?: boolean;
+  /** Cap reasoning tokens per model call (vLLM `thinking_token_budget`). */
+  thinkingTokenBudget?: number;
+  /** Hard backstop on model turns (default LOOP_LIMITS.maxTurns). */
+  maxTurns?: number;
+}
+
+export interface ISpecResult {
+  status: SpecStatus;
+  results: IRunResult[];
+}

package/src/loop/prompt/index.ts

@@ -0,0 +1,2 @@
+export { SYSTEM, CHAT_SYSTEM, COMPACT_SYSTEM, seedPrompt } from "./prompt";
+export { renderFileSection, exportedSymbols } from "./project-map";

package/src/loop/prompt/project-map.ts

@@ -0,0 +1,69 @@
+import { LOOP_LIMITS } from "../loop.constants";
+import type { IFileView } from "../../lib/fs";
+
+/** Exported symbol names in a file (lightweight regex — for the project map). */
+export function exportedSymbols(content: string): string[] {
+  const names = new Set<string>();
+  const decl =
+    /export\s+(?:default\s+)?(?:async\s+)?(?:function|const|let|class|interface|type|enum)\s+([A-Za-z_$][\w$]*)/g;
+
+  for (const m of content.matchAll(decl)) {
+    if (m[1] !== undefined) {
+      names.add(m[1]);
+    }
+  }
+
+  for (const m of content.matchAll(/export\s*\{([^}]*)\}/g)) {
+    const inner = m[1];
+
+    if (inner === undefined) {
+      continue;
+    }
+
+    for (const part of inner.split(",")) {
+      const name = part
+        .trim()
+        .split(/\s+as\s+/)[0]
+        ?.trim();
+
+      if (name !== undefined && name.length > 0) {
+        names.add(name);
+      }
+    }
+  }
+
+  return [...names];
+}
+
+/** A compact map: `path (N lines) — exports: A, B`, one per file. */
+function projectMap(views: readonly IFileView[]): string {
+  return views
+    .map((v) => {
+      const lines = v.content.split("\n").length;
+      const ex = exportedSymbols(v.content);
+
+      return `  ${v.path} (${String(lines)} lines)${ex.length > 0 ? ` — exports: ${ex.join(", ")}` : ""}`;
+    })
+    .join("\n");
+}
+
+/**
+ * Render a set of files for the prompt: full contents when small, a navigable
+ * MAP when the combined size exceeds LOOP_LIMITS.mapThresholdChars (the model then
+ * uses read/search/symbol_search to inspect specifics). Exported for testing.
+ */
+export function renderFileSection(views: readonly IFileView[]): {
+  text: string;
+  mapped: boolean;
+} {
+  const total = views.reduce((n, v) => n + v.content.length, 0);
+
+  if (total > LOOP_LIMITS.mapThresholdChars) {
+    return { text: projectMap(views), mapped: true };
+  }
+
+  return {
+    text: views.map((v) => `File ${v.path}:\n${v.content}`).join("\n\n"),
+    mapped: false,
+  };
+}

package/src/loop/prompt/prompt.ts

@@ -0,0 +1,107 @@
+import type { ITask } from "../../spec";
+import type { IFileView } from "../../lib/fs";
+import { PACK_REGISTRY } from "../../stack-detection";
+import type { IStackProfile } from "../../stack-detection";
+import { renderFileSection } from "./project-map";
+
+/** The implement-agent system prompt: who it is, the tools, and the strict-TS
+ *  house rules the gate enforces. */
+export const SYSTEM = [
+  "You are an expert TypeScript engineer working inside tsforge, a harness specialized for STRICT TypeScript. Implement the task by editing code until the gate passes.",
+  "Tools: `read` (inspect a file), `edit` (replace an exact, unique snippet), `create` (a new file), `run` (execute any shell command and see its output).",
+  "Lead with action: write the implementation FIRST (one `create`/`edit`) — do NOT deliberate at length before writing any code.",
+  "After every edit the harness AUTOMATICALLY runs the gate and gives you the result (the errors + fix guidance for the failing rules). You do NOT need to run the acceptance command yourself — read that result and fix exactly what it reports, then edit again. Keep going until it reports green; the harness ends the task at that point.",
+  "Test hypotheses by RUNNING them, never by reasoning them out. Unsure about an edge case, rounding, or ordering (`Math.floor(100/3)`, largest-remainder ties)? `run` a quick `bun -e '…console.log(…)'`, or write a throwaway `scratch/check.ts` importing your impl and `run` it. `scratch/` is yours — the gate ignores it.",
+  "The gate is `tsc` strict + eslint with every rule an error, so write TypeScript that satisfies it: interfaces are `I`-prefixed; `===`; no `var`; never the non-null `!` — guard index access (`const x = arr[i]; if (x === undefined) {...}`); no `any` and no `as` — type every parameter (e.g. `.reduce((acc: number, r: number) => …, 0)`); explicit boolean conditions. When the gate flags errors in read-only files (tests/types), they come from your editable file being missing or wrong-shaped and vanish once it's correct — don't edit them.",
+].join("\n");
+
+/**
+ * The INTERACTIVE assistant prompt (the CLI's `Session`). Unlike `SYSTEM` — which
+ * drives a single task to a gate and is told to "keep going until green" — this
+ * frames an open-ended conversation: investigate with tools, then ANSWER or ACT
+ * and STOP. Without this framing the model treats every message as implement-to-
+ * green and scans the repo forever when asked a question (there's no gate to hit).
+ */
+export const CHAT_SYSTEM = [
+  "You are tsforge, an expert TypeScript coding assistant. You are launched inside a repository, but NOT every request is about that repository. The user talks to you; you help by answering, and by inspecting/changing code with your tools.",
+  "Tools: `read` (inspect a file), `run` (execute any shell command — `ls`, `rg`, tests, `tsc`), `edit` (replace an exact, unique snippet), `create` (a new file).",
+  "File paths are RELATIVE to the workspace root: use `tsconfig.json` or `src/app.ts` — never an absolute path, and never repeat the workspace folder in the path.",
+  "MATCH EFFORT TO THE REQUEST. A self-contained ask — 'write a `double` function', 'explain `satisfies`' — has nothing to do with the surrounding repo: just answer it directly (reply with the code; only `create` a file if asked). Do NOT read or scan the repository for these. Investigate the codebase ONLY when the request is actually about THIS project (a bug here, a change here, 'what would you change?').",
+  "ASK BEFORE GUESSING when the request is genuinely ambiguous — unclear scope, unclear which file to touch, or unclear whether it even relates to this repo (e.g. 'add a retry' with no target). Ask ONE short clarifying question and stop; the user will answer and you continue. But don't over-ask: when a sensible default is obvious, take it and state the assumption in one line.",
+  "Be decisive, not exhaustive. When you do investigate, a few targeted reads beat reading everything — as soon as you can answer or act, STOP calling tools and reply.",
+  "For a QUESTION about the repo, investigate briefly then give a concise, concrete answer (cite specific files/symbols; offer your top few recommendations, not a survey). For a CHANGE, make it with `edit`/`create`, verify by `run`ning the tests or `tsc`, then briefly state what you did.",
+  "When you write code, use strict TypeScript: `I`-prefixed interfaces; `===`; no `var`; never the non-null `!` (guard index access: `const x = arr[i]; if (x === undefined) {…}`); no `any`/`as` (type parameters); explicit boolean conditions.",
+].join("\n");
+
+/** Prompt for `/compact`: condense a long conversation, keeping what matters for
+ *  continuing the work — not a chatty recap. */
+export const COMPACT_SYSTEM = [
+  "You are compacting a coding session to save context. Summarize the conversation below into a concise brief that lets the assistant CONTINUE seamlessly.",
+  "Preserve: the user's goals/requests, decisions made, files created or changed (with their purpose), key facts learned about the codebase, and any OPEN threads or next steps.",
+  "Drop: small talk, redundant tool output, and anything already superseded. Use terse bullet points. Do not invent anything not in the transcript.",
+].join("\n");
+
+/** Build stack-aware guidance from an IStackProfile. Includes the stack name
+ *  and guidance strings from active packs (skipping empty/always-on packs). */
+export function buildStackGuidance(profile: IStackProfile): string {
+  const lines: string[] = [];
+
+  lines.push(`## Project stack & conventions`);
+  lines.push(`Stack: **${profile.name}** (${profile.reason})`);
+
+  for (const packId of profile.packs) {
+    // Find the descriptor by ID from the registry
+    const descriptor = Object.values(PACK_REGISTRY).find(
+      (d) => d.id === packId
+    );
+
+    // Add guidance if present and non-empty
+    if (descriptor?.guidance !== undefined) {
+      lines.push(`- ${descriptor.guidance}`);
+    }
+  }
+
+  return lines.length > 1 ? lines.join("\n") : "";
+}
+
+/** Build the first user message: the task contract + editable/context files
+ *  (full dumps when small, a navigable MAP when large — see renderFileSection). */
+export function seedPrompt(
+  task: ITask,
+  editable: IFileView[],
+  context: IFileView[],
+  stack?: IStackProfile
+): string {
+  const intent =
+    task.intent !== undefined && task.intent.length > 0
+      ? `Spec contract — implement EXACTLY this:\n${task.intent}`
+      : "";
+
+  const ed = renderFileSection(editable);
+  const editableText =
+    editable.length === 0
+      ? "(none of the editable files exist yet — create them)"
+      : ed.mapped
+        ? `The editable files are large — here is a MAP (path · lines · exports). INSPECT specifics with read/search/symbol_search/find_references before editing; don't guess:\n${ed.text}`
+        : ed.text;
+
+  const ctx = context.length > 0 ? renderFileSection(context) : null;
+  const contextText =
+    ctx === null
+      ? ""
+      : `Read-only context (do NOT edit)${ctx.mapped ? " — MAP; read specifics on demand" : ""}:\n${ctx.text}`;
+
+  const stackText = stack !== undefined ? buildStackGuidance(stack) : "";
+
+  return [
+    `Task ${task.id}.`,
+    intent,
+    stackText,
+    `Acceptance command (run this to verify — it must exit 0): ${task.accept}`,
+    `Editable files: ${task.files.join(", ")}`,
+    `Current editable contents:\n${editableText}`,
+    contextText,
+  ]
+    .filter((s) => s.length > 0)
+    .join("\n\n");
+}

package/src/loop/quality.ts

@@ -0,0 +1,174 @@
+import { join } from "node:path";
+import type { ITask } from "../spec";
+import type { IAgent } from "../agent";
+import type { IProvider } from "../inference";
+import { validate, type ErrorParser } from "../validate";
+import { runAccept } from "../validate";
+import { judge } from "../eval";
+import { qualityHints } from "./feedback";
+import type { Reporter } from "./loop.types";
+
+export interface IQualityResult {
+  quality: number;
+  notes: string;
+  attempts: number;
+}
+
+export interface IQualityMeta {
+  goal: string;
+  criteria: string;
+}
+
+export interface IQualityOptions {
+  /** Stop when quality reaches this (default 5). */
+  target?: number;
+  /** Max improvement attempts (default 2). */
+  maxAttempts?: number;
+  parse?: ErrorParser;
+  onEvent?: Reporter;
+}
+
+/**
+ * After a task is green, drive its *quality* up: judge it, and while it's below
+ * target, feed the reviewer's critique back as an improvement instruction,
+ * re-validate (must stay green), and re-judge — keeping only changes that both
+ * keep the gate green and raise the score. Never ends below the green baseline.
+ */
+export async function qualityRepair(
+  task: ITask,
+  cwd: string,
+  agent: IAgent,
+  judgeProvider: IProvider,
+  meta: IQualityMeta,
+  opts: IQualityOptions = {}
+): Promise<IQualityResult> {
+  const target = opts.target ?? 5;
+  const maxAttempts = opts.maxAttempts ?? 2;
+  const report: Reporter = opts.onEvent ?? (() => undefined);
+
+  let best = await score(task, cwd, judgeProvider, meta);
+
+  report({
+    kind: "fix",
+    task: task.id,
+    message: `quality ${best.quality}/5 — ${best.notes}`,
+  });
+
+  let attempts = 0;
+
+  while (best.quality < target && attempts < maxAttempts) {
+    attempts += 1;
+
+    const snapshot = await snapshotFiles(task, cwd);
+
+    // Turn the reviewer's prose into concrete bad→good guidance where we have a
+    // card for the issue it named (the quality channel — these are idiomatic
+    // problems the gate can't flag).
+    const hints = qualityHints(best.notes);
+    const guidance =
+      hints.length > 0
+        ? `\n\nConcrete fixes for the idioms it named:\n${hints}`
+        : "";
+
+    await agent.implement({
+      cwd,
+      task,
+      errors: [
+        {
+          key: "quality",
+          message: `The code is green but a senior reviewer scored it ${best.quality}/5: "${best.notes}". Improve the code to address that critique.${guidance} Do NOT break the tests or the gate.`,
+        },
+      ],
+      cycle: attempts,
+      report,
+    });
+
+    if (task.fix !== undefined && task.fix.length > 0) {
+      await runAccept({ ...task, accept: task.fix }, cwd);
+    }
+
+    const gate = await validate(task, cwd, opts.parse);
+
+    if (!gate.passed) {
+      await restoreFiles(snapshot, cwd);
+      report({
+        kind: "fix",
+        task: task.id,
+        message: `quality attempt ${attempts}: broke the gate — reverted`,
+      });
+      continue;
+    }
+
+    const next = await score(task, cwd, judgeProvider, meta);
+
+    if (next.quality > best.quality) {
+      best = next;
+      report({
+        kind: "fix",
+        task: task.id,
+        message: `quality ↑ ${best.quality}/5`,
+      });
+    } else {
+      await restoreFiles(snapshot, cwd);
+      report({
+        kind: "fix",
+        task: task.id,
+        message: `quality attempt ${attempts}: no gain (${next.quality}/5) — kept previous`,
+      });
+    }
+  }
+
+  return { quality: best.quality, notes: best.notes, attempts };
+}
+
+interface IScore {
+  quality: number;
+  notes: string;
+}
+
+async function score(
+  task: ITask,
+  cwd: string,
+  judgeProvider: IProvider,
+  meta: IQualityMeta
+): Promise<IScore> {
+  let code = "";
+
+  for (const file of task.files) {
+    code += `// ${file}\n${await Bun.file(join(cwd, file)).text()}\n\n`;
+  }
+
+  const result = await judge(judgeProvider, {
+    goal: meta.goal,
+    criteria: meta.criteria,
+    code,
+  });
+
+  return { quality: result.overall, notes: result.notes };
+}
+
+async function snapshotFiles(
+  task: ITask,
+  cwd: string
+): Promise<Map<string, string>> {
+  const snapshot = new Map<string, string>();
+
+  for (const file of task.files) {
+    const handle = Bun.file(join(cwd, file));
+
+    if (await handle.exists()) {
+      snapshot.set(file, await handle.text());
+    }
+  }
+
+  return snapshot;
+}
+
+async function restoreFiles(
+  snapshot: Map<string, string>,
+  cwd: string
+): Promise<void> {
+  for (const [file, content] of snapshot) {
+    await Bun.write(join(cwd, file), content);
+  }
+}