@agjs/tsforge 0.1.0

package/src/agent/model-agent.ts

@@ -0,0 +1,297 @@
+import { basename } from "node:path";
+import type { IAgent, IAgentContext } from "./agent.types";
+import type { IChatMessage, IProvider } from "../inference";
+import type { ErrorSet } from "../validate";
+import { applyEdits } from "../files/edit";
+import { applyCreate } from "../files/create";
+import { EDIT_FAIL_REASON } from "../files";
+import { isInScope, normalizeWorkspacePath } from "../lib/scope";
+import { readFiles, type IFileView } from "../lib/fs";
+import { EDIT_TOOL, CREATE_TOOL, TOOL_NAME } from "./agent.constants";
+import { toEdits, toCreate } from "./tools";
+import { ruleHelp } from "../loop/feedback";
+
+/**
+ * The errors the agent can actually act on: those in its editable files (plus
+ * file-less generic ones). Cascade errors located in read-only context (e.g. a
+ * test file failing because the not-yet-created impl can't be imported) are NOT
+ * the model's to fix — surfacing them makes it spiral on a contradiction it
+ * can't resolve. Those clear on their own once the editable files are correct.
+ */
+function editableErrors(errors: ErrorSet, files: string[]): ErrorSet {
+  return errors.filter((e) => {
+    if (e.file === undefined) {
+      return true;
+    }
+
+    return isInScope(e.file, files) || isInScope(basename(e.file), files);
+  });
+}
+
+/**
+ * The real agent: show the model the declared files + current failures, ask for
+ * `edit`/`create` tool calls, and apply them through the edit engine (which
+ * enforces exact/unique matches and no-clobber creates). The model can only
+ * produce a matching `oldString` if it sees the file, so we read the declared
+ * files into context first.
+ */
+export function modelAgent(
+  provider: IProvider,
+  options: { temperature?: number; thinkingTokenBudget?: number } = {}
+): IAgent {
+  // Edit-application failures from the previous cycle, fed back so the model
+  // learns when an edit was rejected (otherwise rejections are invisible to it).
+  let lastFailures: string[] = [];
+
+  return {
+    async implement(ctx: IAgentContext): Promise<void> {
+      const editable = await readFiles(ctx.cwd, ctx.task.files);
+      const readonly = await readFiles(ctx.cwd, ctx.task.context ?? []);
+      const res = await provider.complete(
+        buildMessages(ctx, editable, readonly, lastFailures),
+        {
+          tools: [EDIT_TOOL, CREATE_TOOL],
+          toolChoice: "auto",
+          // Temp 0 by default — the eval sweep showed it's decisively better for
+          // convergence on coding tasks (temp 0: 100% pass vs temp 0.5: 0%).
+          temperature: options.temperature ?? 0,
+          // Cap reasoning so the quality-repair pass can't ramble unbounded
+          // ("writing novels"): the budget that bounds the implement loop must
+          // bound this agent too, or the cap leaks.
+          ...(options.thinkingTokenBudget === undefined
+            ? {}
+            : { thinkingTokenBudget: options.thinkingTokenBudget }),
+          // Stream: keeps the connection alive on long thinking calls (no
+          // idle-drop) and emits a heartbeat. Reasoning is NOT logged — only a
+          // dim dot per ~200 reasoning chars (proof of life, not the wall).
+          onToken: (text) => {
+            ctx.report?.({ kind: "token", task: ctx.task.id, message: text });
+          },
+        }
+      );
+
+      const failures: string[] = [];
+
+      for (const call of res.toolCalls) {
+        const failure = await applyCall(ctx, call.name, call.arguments);
+
+        if (failure !== null) {
+          failures.push(failure);
+        }
+      }
+
+      lastFailures = failures;
+    },
+  };
+}
+
+/** Apply one tool call; return a human-readable failure message, or null on success. */
+async function applyCall(
+  ctx: IAgentContext,
+  name: string,
+  args: Record<string, unknown>
+): Promise<string | null> {
+  if (name === TOOL_NAME.edit) {
+    return applyAgentEdit(ctx, args);
+  }
+
+  if (name === TOOL_NAME.create) {
+    return applyAgentCreate(ctx, args);
+  }
+
+  return null;
+}
+
+async function applyAgentEdit(
+  ctx: IAgentContext,
+  args: Record<string, unknown>
+): Promise<string | null> {
+  const edit = toEdits(args);
+
+  if (edit === null) {
+    return "an `edit` call had malformed arguments (need `file` plus `oldString`/`newString` or an `edits` array)";
+  }
+
+  edit.file = normalizeWorkspacePath(ctx.cwd, edit.file);
+
+  const scopeError = outOfScope(ctx, edit.file);
+
+  if (scopeError !== null) {
+    return scopeError;
+  }
+
+  const result = await applyEdits(ctx.cwd, edit.file, edit.edits);
+
+  if (result.ok) {
+    for (const r of edit.edits) {
+      ctx.report?.({
+        kind: "edit",
+        task: ctx.task.id,
+        file: edit.file,
+        message: `edit ${edit.file}`,
+        oldString: r.oldString,
+        newString: r.newString,
+      });
+    }
+
+    return null;
+  }
+
+  const where =
+    edit.edits.length > 1 ? ` (replacement #${result.index + 1})` : "";
+  const detail =
+    result.reason === EDIT_FAIL_REASON.ambiguous
+      ? `oldString matched ${result.matches ?? 0} places — include more surrounding lines to make it unique`
+      : result.reason;
+
+  ctx.report?.({
+    kind: "edit",
+    task: ctx.task.id,
+    file: edit.file,
+    message: `${edit.file} — rejected (${result.reason})`,
+  });
+
+  return `edit to ${edit.file} REJECTED${where}: ${detail}`;
+}
+
+async function applyAgentCreate(
+  ctx: IAgentContext,
+  args: Record<string, unknown>
+): Promise<string | null> {
+  const create = toCreate(args);
+
+  if (create === null) {
+    return "a `create` call had malformed arguments (need file, content)";
+  }
+
+  create.file = normalizeWorkspacePath(ctx.cwd, create.file);
+
+  const scopeError = outOfScope(ctx, create.file);
+
+  if (scopeError !== null) {
+    return scopeError;
+  }
+
+  const result = await applyCreate(ctx.cwd, create);
+
+  if (result.ok) {
+    ctx.report?.({
+      kind: "create",
+      task: ctx.task.id,
+      file: create.file,
+      message: `create ${create.file}`,
+      content: create.content,
+    });
+
+    return null;
+  }
+
+  ctx.report?.({
+    kind: "create",
+    task: ctx.task.id,
+    file: create.file,
+    message: `${create.file} — rejected (already exists)`,
+  });
+
+  return `create ${create.file} REJECTED: file already exists — use \`edit\` instead`;
+}
+
+/** Reject (and report) an edit/create whose path is outside the editable scope. */
+function outOfScope(ctx: IAgentContext, file: string): string | null {
+  if (isInScope(file, ctx.task.files)) {
+    return null;
+  }
+
+  ctx.report?.({
+    kind: "edit",
+    task: ctx.task.id,
+    file,
+    message: `${file} — out of scope (read-only)`,
+  });
+
+  return `${file} is OUT OF SCOPE — you may only edit/create: ${ctx.task.files.join(
+    ", "
+  )}. Read-only context (tests, etc.) must not be changed.`;
+}
+
+function buildMessages(
+  ctx: IAgentContext,
+  editable: IFileView[],
+  readonly: IFileView[],
+  priorFailures: string[]
+): IChatMessage[] {
+  const system = [
+    "You are a TypeScript engineer working inside an automated harness. Make the task pass by emitting `edit` and `create` tool calls.",
+    "`edit` replaces an exact, UNIQUE snippet in an existing file — include enough surrounding lines so oldString matches exactly once. `create` makes a new file.",
+    "Scope: you may ONLY edit/create the editable files. NEVER edit the read-only context (tests, specs) — it is fixed.",
+    "House rules (enforced by the gate): interfaces are `I`-prefixed and you update EVERY reference when you rename a type; never use the non-null assertion `!` — guard index access instead (`const x = arr[i]; if (x !== undefined)`); avoid `while (true)` and other constant conditions — prefer `.filter(...)`, `for...of`, or a bounded loop; no `any` and no `as`; change only what the failures require and don't re-break fixed issues.",
+  ].join("\n");
+
+  const editableText =
+    editable.length > 0
+      ? editable.map((f) => `File ${f.path}:\n${f.content}`).join("\n\n")
+      : "(no editable files exist yet — create them)";
+
+  const contextText =
+    readonly.length > 0
+      ? `Read-only context (do NOT edit):\n${readonly
+          .map((f) => `File ${f.path}:\n${f.content}`)
+          .join("\n\n")}`
+      : "";
+
+  // Only show failures the model can actually fix (in its editable files).
+  const ownErrors = editableErrors(ctx.errors, ctx.task.files);
+  const readOnlyCount = ctx.errors.length - ownErrors.length;
+
+  const failures =
+    ownErrors.length > 0
+      ? `Current failures in your editable files:\n${ownErrors
+          .map((e) => `- ${e.message}`)
+          .join("\n")}`
+      : "No failures in your editable files.";
+
+  const readOnlyNote =
+    readOnlyCount > 0
+      ? `Note: ${readOnlyCount} other gate error(s) are in READ-ONLY files (e.g. tests). They are NOT yours to fix and will resolve once your editable files export the right shapes — ignore them.`
+      : "";
+
+  // The failing rules' own docs (bad→good), keyed to the model's OWN errors —
+  // so it fixes from the rule's example instead of re-deriving it.
+  const coaching = ruleHelp(ownErrors);
+  const guidance =
+    coaching.length > 0
+      ? `How to satisfy the gate here (the failing rules, with examples):\n${coaching}`
+      : "";
+
+  const rejected =
+    priorFailures.length > 0
+      ? `Your previous edits were REJECTED and did NOT apply — fix and retry:\n${priorFailures
+          .map((f) => `- ${f}`)
+          .join("\n")}`
+      : "";
+
+  const intent =
+    ctx.task.intent !== undefined && ctx.task.intent.length > 0
+      ? `Spec contract — implement EXACTLY this (authoritative; the tests check it but this states the intent):\n${ctx.task.intent}`
+      : "";
+
+  const user = [
+    `Task ${ctx.task.id} (cycle ${ctx.cycle}).`,
+    intent,
+    `Acceptance command: ${ctx.task.accept}`,
+    `Editable files: ${ctx.task.files.join(", ")}`,
+    `Editable file contents:\n${editableText}`,
+    contextText,
+    failures,
+    readOnlyNote,
+    guidance,
+    rejected,
+  ]
+    .filter((s) => s.length > 0)
+    .join("\n\n");
+
+  return [
+    { role: "system", content: system },
+    { role: "user", content: user },
+  ];
+}

package/src/agent/tool-repair.ts

@@ -0,0 +1,194 @@
+/**
+ * Cost-ordered tool-call repair ladder for open-model reliability.
+ *
+ * The harness mediates between the model's output distribution and strict tool
+ * schemas — rejecting RECOVERABLE noise that commercial models absorb invisibly.
+ * As tsforge grows, this is the one place that keeps every new tool forgiving
+ * the same way (CommandCode: "open model bad at tool calling is a harness
+ * problem" — failure modes are a small finite set).
+ *
+ * CRITICAL ordering: VALIDATE THEN REPAIR, never preprocess-then-validate. We
+ * only touch input the tool's own parser has ALREADY rejected — so a valid
+ * input (e.g. file `content` that happens to be JSON-shaped) is never rewritten.
+ * The parser is the prior; we spend repair budget only where it disagreed.
+ *
+ * The ladder (cost-ordered, earliest-win):
+ *
+ *  L0: null-drop, autolink-unwrap — lossless, always safe. Applied first.
+ *
+ *  L1: schema coercion — against the tool's declared params:
+ *      - stringified arrays: '["a"]' → ["a"] (when param type is array)
+ *      - stringified numbers/booleans: "42"→42, "true"→true (when typed)
+ *      - single string → [string] for array params
+ *      - trim markdown fences from paths (```path``` → path)
+ *
+ *  L2: safe defaults — ONLY where unambiguous (rare; study per-tool failures):
+ *      - bool params default to true (unusual, but seen when model guesses)
+ *      - (expand as telemetry surfaces safe patterns; bias toward L3 re-ask)
+ *
+ *  L3: re-ask — when not recoverable:
+ *      - `recoverable: false` + targeted `feedback` (field, type, example)
+ *      - turn.ts routes through as the tool result; loop re-asks the model
+ *      - analyze-malformed.ts histograms re-ask rate per rule
+ */
+
+export interface IRepairResult {
+  readonly args: Record<string, unknown>;
+  readonly applied: readonly string[]; // e.g. ["drop-null:limit", "coerce:files"]
+  readonly recoverable: boolean; // false → re-ask via feedback
+  readonly feedback?: string; // targeted error text for the re-ask path
+}
+
+/**
+ * Run the repair ladder on args that failed schema validation. Returns
+ * the repaired args, a list of applied repair names (for telemetry), whether
+ * the result is usable, and (if not) targeted feedback for the model.
+ * Applies repairs in order: L0 (lossless) → L1 (schema coerce) → L2 (defaults)
+ * → L3 (feedback if still broken).
+ */
+export function repairArgs(args: Record<string, unknown>): IRepairResult {
+  const applied: string[] = [];
+  let out = args;
+
+  // L0: Lossless repairs (null-drop, autolink-unwrap).
+  out = applyL0(out, applied);
+
+  // L1: Schema coercion (stringified arrays, numbers, booleans, markdown fences).
+  // For now, we have no schema context here — deferred to handlers that know
+  // their field types (toEdits, toCreate, etc.). They COULD call schema-aware
+  // coercers; for now they just pass valid structures or null (triggering L3).
+  // Future: wire tool schemas and coerce here.
+
+  // L2: Safe defaults — none established yet; defer to telemetry.
+
+  // L3: If still broken, handlers will validate and route through L3 feedback.
+  // This function returns what we could fix.
+  return {
+    args: out,
+    applied,
+    recoverable: true,
+  };
+}
+
+/**
+ * L0: Lossless repairs. Safe on any arg, any type. Mutates `applied` in place.
+ */
+function applyL0(
+  args: Record<string, unknown>,
+  applied: string[]
+): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+
+  for (const [key, value] of Object.entries(args)) {
+    if (value === null || value === undefined) {
+      applied.push(`drop-null:${key}`);
+      continue;
+    }
+
+    if (typeof value === "string") {
+      const unlinked = unwrapAutoLink(value);
+
+      if (unlinked !== value) {
+        applied.push(`unwrap-autolink:${key}`);
+        out[key] = unlinked;
+        continue;
+      }
+    }
+
+    out[key] = value;
+  }
+
+  return out;
+}
+
+const AUTO_LINK = /^\[([^\]]+)\]\(([^)]+)\)$/;
+
+/**
+ * `[notes.md](notes.md)` / `[x](http://x)` where the link text equals the URL
+ * (ignoring an `http(s)://` prefix and whitespace) → the text. Anything else
+ * (a real link with distinct text/url) is returned unchanged.
+ */
+function unwrapAutoLink(value: string): string {
+  const match = AUTO_LINK.exec(value.trim());
+
+  if (match === null) {
+    return value;
+  }
+
+  const text = (match[1] ?? "").replace(/\s+/g, "");
+  const url = (match[2] ?? "").replace(/^https?:\/\//, "").replace(/\s+/g, "");
+
+  return text === url ? (match[1] ?? "").trim() : value;
+}
+
+/**
+ * L1: Schema coercion — per-tool rules applied by handlers that know their
+ * field types (via tool schema context). These helpers are called by toEdits,
+ * toCreate, toRead, toRun when they detect a coercible mismatch.
+ */
+
+/** Coerce a string to an array if it's a stringified JSON array. */
+export function coerceStringToArray(value: unknown): unknown[] | null {
+  if (typeof value !== "string") {
+    return null;
+  }
+
+  const trimmed = value.trim();
+
+  if (!trimmed.startsWith("[") || !trimmed.endsWith("]")) {
+    return null;
+  }
+
+  try {
+    const parsed: unknown = JSON.parse(trimmed);
+
+    return Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Coerce a string to its typed value if it's stringified. */
+export function coerceStringValue(
+  value: unknown,
+  expectedType: "number" | "boolean"
+): number | boolean | null {
+  if (typeof value !== "string") {
+    return null;
+  }
+
+  const trimmed = value.trim().toLowerCase();
+
+  if (expectedType === "number") {
+    const n = Number(trimmed);
+
+    return Number.isFinite(n) ? n : null;
+  }
+
+  // expectedType === "boolean"
+  if (trimmed === "true") {
+    return true;
+  }
+
+  if (trimmed === "false") {
+    return false;
+  }
+
+  return null;
+}
+
+/** Strip markdown code fences and extra whitespace from a string. */
+export function trimMarkdownFences(value: unknown): string | null {
+  if (typeof value !== "string") {
+    return null;
+  }
+
+  let s = value.trim();
+
+  // `  ```path.ts```  ` → `path.ts`
+  if (s.startsWith("```") && s.endsWith("```")) {
+    s = s.slice(3, -3).trim();
+  }
+
+  return s;
+}

package/src/agent/tools.ts

@@ -0,0 +1,190 @@
+import type { ICreateFile, IReplacement } from "../files";
+import { isArray, isRecord } from "../lib/guards";
+import { runShellCommand } from "../lib/fs";
+import { coerceStringToArray, trimMarkdownFences } from "./tool-repair";
+import type { IShellResult } from "./agent.types";
+
+/** Default kill-timeout for the `run` tool (ms) — generous enough for a slow
+ *  test/build, short enough that a hung `tail -f`/`vite dev` can't wedge the
+ *  harness forever. Override per-process with TSFORGE_RUN_TIMEOUT_MS (0 = off). */
+const DEFAULT_RUN_TIMEOUT_MS = 120_000;
+
+function runToolTimeoutMs(): number {
+  const env = Number(process.env.TSFORGE_RUN_TIMEOUT_MS);
+
+  return Number.isFinite(env) && env >= 0 ? env : DEFAULT_RUN_TIMEOUT_MS;
+}
+
+/**
+ * Resolve the target file path from a tool call. Our schema asks for `file`, but
+ * the model frequently reaches for `path` (the Claude-Code convention) and other
+ * synonyms. A schema mismatch on the very FIRST tool call poisons the whole
+ * trajectory — observed on react-board: 7 rejected reads in turn 1 sent the
+ * model into an inert "let me read…" loop. So we accept the aliases instead of
+ * rejecting (input-repair: meet the model where it is). `file` wins if present.
+ * Also applies L1 coercions: trims markdown fences, coerces if stringified.
+ */
+export function fileArg(args: Record<string, unknown>): string | null {
+  for (const key of ["file", "path", "filename", "filepath", "filePath"]) {
+    const value = args[key];
+
+    if (value === undefined || value === null) {
+      continue;
+    }
+
+    // L1: trim markdown fences (```path.ts``` → path.ts)
+    const trimmed = trimMarkdownFences(value);
+
+    if (trimmed !== null && trimmed.length > 0) {
+      return trimmed;
+    }
+
+    // Already a string but not markdown-wrapped.
+    if (typeof value === "string" && value.length > 0) {
+      return value;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Normalize either edit form into a file + ordered replacement list. Accepts the
+ * single `{file, oldString, newString}` shape AND the batched `{file, edits:[…]}`
+ * shape, so old callers and the multi-site path share one contract.
+ * Applies L1 coercions: stringified arrays are parsed.
+ */
+export function toEdits(
+  args: Record<string, unknown>
+): { file: string; edits: IReplacement[] } | null {
+  const { edits: editsDef, oldString: oldStr, newString: newStr } = args;
+  let edits = editsDef;
+  const file = fileArg(args);
+
+  if (file === null) {
+    return null;
+  }
+
+  // L1: Coerce stringified arrays (e.g. from models that emit '[{...}]' as a string).
+  if (typeof edits === "string") {
+    const parsed = coerceStringToArray(edits);
+
+    if (parsed !== null) {
+      edits = parsed;
+    }
+  }
+
+  if (isArray(edits)) {
+    const list: IReplacement[] = [];
+
+    for (const e of edits) {
+      if (
+        isRecord(e) &&
+        typeof e.oldString === "string" &&
+        typeof e.newString === "string"
+      ) {
+        list.push({ oldString: e.oldString, newString: e.newString });
+      } else {
+        return null;
+      }
+    }
+
+    return list.length > 0 ? { file, edits: list } : null;
+  }
+
+  if (typeof oldStr === "string" && typeof newStr === "string") {
+    return { file, edits: [{ oldString: oldStr, newString: newStr }] };
+  }
+
+  return null;
+}
+
+export function toCreate(args: Record<string, unknown>): ICreateFile | null {
+  const { content } = args;
+  const file = fileArg(args);
+
+  if (file !== null && typeof content === "string") {
+    return { file, content };
+  }
+
+  return null;
+}
+
+/**
+ * Build L3 re-ask feedback for a broken tool call. Targets the exact field,
+ * shows what was received, names the expected type, and provides a working example.
+ */
+export function buildRepairFeedback(
+  toolName: string,
+  field: string,
+  received: unknown,
+  expectedType: string,
+  example: string
+): string {
+  return (
+    `\n\n⚠ Tool argument repair failed — the \`${toolName}\` tool cannot proceed ` +
+    `without fixing \`${field}\`:\n` +
+    `  received: ${JSON.stringify(received)} (${typeof received})\n` +
+    `  expected: ${expectedType}\n` +
+    `  example: \`${example}\`\n\n` +
+    `Fix the argument and call the tool again.`
+  );
+}
+
+export function toRun(
+  args: Record<string, unknown>
+): { command: string } | null {
+  const { command } = args;
+
+  return typeof command === "string" ? { command } : null;
+}
+
+export function toRead(args: Record<string, unknown>): { file: string } | null {
+  const file = fileArg(args);
+
+  return file !== null ? { file } : null;
+}
+
+/**
+ * Parse hashline edit args: file (required), hash (optional), input (required).
+ */
+export function toHashlineEdit(
+  args: Record<string, unknown>
+): { file: string; hash?: string; input: string } | null {
+  const file = fileArg(args);
+  const { hash, input } = args;
+
+  if (file === null || typeof input !== "string" || input.length === 0) {
+    return null;
+  }
+
+  const hashStr =
+    typeof hash === "string" && hash.length > 0 ? hash : undefined;
+
+  return { file, hash: hashStr, input };
+}
+
+/** Run a shell command in `cwd` and capture stdout/stderr/exit — the `run` tool.
+ *  Cancellable via `signal`; killed after a timeout (default `runToolTimeoutMs`)
+ *  so a hung command can't wedge the harness. A timeout appends a clear note. */
+export async function runCommand(
+  cwd: string,
+  command: string,
+  opts: { signal?: AbortSignal; timeoutMs?: number } = {}
+): Promise<IShellResult> {
+  const timeoutMs = opts.timeoutMs ?? runToolTimeoutMs();
+  const run = await runShellCommand(cwd, command, {
+    timeoutMs,
+    ...(opts.signal === undefined ? {} : { signal: opts.signal }),
+  });
+
+  const note = run.timedOut
+    ? `\n[command killed after ${timeoutMs}ms timeout — TSFORGE_RUN_TIMEOUT_MS to change]`
+    : "";
+
+  return {
+    stdout: run.stdout,
+    stderr: run.stderr + note,
+    exitCode: run.exitCode,
+  };
+}