ucode-agent 1.4.0 → 1.6.0

package/src/core/stuck.js

@@ -0,0 +1,269 @@
+/**
+ * stuck.js — noticing when the model is going round in circles.
+ *
+ * Measured on a real build (a tip calculator, 84 model steps): six edits whose
+ * old_string and new_string were identical, the same build failing three times
+ * running on the same two type errors, and thirty reads of files whose current
+ * text was already in the conversation. Every one of those is a whole round
+ * trip, and a small model that has started repeating itself rarely stops on
+ * its own — the error it keeps getting says what is wrong, but nothing says
+ * "you have tried exactly this before".
+ *
+ * So each finished tool call becomes an event, and the recent events are
+ * checked for four patterns:
+ *
+ *   repeat     the same call, with the same arguments, failing the same way
+ *   identical  edits refused because old_string and new_string are the same
+ *   reread     reading a file whose unchanged text is still in view
+ *   build      a build failing with the same error text
+ *
+ * The first time a pattern reaches its threshold, the result that completed it
+ * carries a firm, specific note: what was repeated, the error, what to do
+ * instead. If the same pattern turns up again after that note, a nudge has not
+ * worked, and the caller hands the turn to another model.
+ *
+ * Everything here is pure: events in, verdicts out. The loop owns the side
+ * effects — appending the text and switching the model.
+ */
+
+import { createHash } from 'node:crypto';
+
+/** How many recent tool calls the patterns are looked for in. */
+export const WINDOW = 20;
+
+/** Occurrences inside the window that make a hit. */
+export const THRESHOLDS = { repeat: 3, identical: 2, reread: 1, build: 3 };
+
+const hash = (s) => createHash('sha1').update(String(s)).digest('hex').slice(0, 16);
+
+/** Argument values compared the way a person would: whitespace runs do not make a call different. */
+function stable(value) {
+  if (typeof value === 'string') return value.replace(/\s+/g, ' ').trim();
+  if (Array.isArray(value)) return value.map(stable);
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(Object.keys(value).sort().map((k) => [k, stable(value[k])]));
+  }
+  return value;
+}
+
+/** Name and arguments, reduced to one short string. */
+export function signature(call) {
+  return `${call?.name}:${hash(JSON.stringify(stable(call?.args ?? {})))}`;
+}
+
+/** Commands whose job is to build or type-check the project. */
+const BUILD = /\b(?:npm|pnpm|yarn|bun)\s+(?:run\s+)?build\b|\bnext\s+build\b|\bvite\s+build\b|\btsc\b(?![^&|;]*--watch)/i;
+
+export const isBuild = (command) => BUILD.test(String(command ?? ''));
+
+const ERROR_LINE = /\berror\b|Error:|Module not found|Can't resolve|Type error|is not defined|Unterminated/i;
+const GENERIC = /^(?:>\s*)?Build error occurred|Failed to (?:type check|compile)|build worker exited|exiting the build|^exit code:|^What to do:|^- |build failed with \d+ errors?|^Import trace|^\d+ errors? found/i;
+
+/**
+ * The part of a build's output that names what is wrong, with the noise that
+ * changes from run to run — timings, digests — taken out, so two failures on
+ * the same errors compare equal.
+ */
+export function buildErrors(output) {
+  const clean = (l) => l
+    .replace(/\b\d+(?:\.\d+)?\s?m?s\b/g, '')
+    .replace(/digest: '[^']*'/g, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+  const lines = String(output ?? '').split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
+  const errors = [...new Set(lines.filter((l) => ERROR_LINE.test(l) && !GENERIC.test(l)).map(clean))];
+  return (errors.length ? errors.slice(0, 12) : lines.slice(-5).map(clean)).join('\n');
+}
+
+/**
+ * One finished call as the detector sees it.
+ *
+ * @param {object} call          { name, args }
+ * @param {object} outcome
+ * @param {object} [outcome.out]      a tool result ({ content, exitCode? })
+ * @param {object} [outcome.err]      a ToolFailure
+ * @param {string[]} [outcome.rereads] files this call re-read while their text was still in view
+ */
+export function eventFor(call, { out, err, rereads = [] } = {}) {
+  const args = call?.args ?? {};
+  const event = { tool: call?.name, sig: signature(call), failed: false, rereads: [...rereads] };
+  event.path = args.path ?? args.files?.[0]?.path ?? null;
+
+  if (err) {
+    event.failed = true;
+    event.kind = err.kind ?? 'error';
+    event.error = String(err.failed ?? err.message ?? err);
+    event.identical = event.kind === 'bad_args' && /old_string and new_string are identical/.test(event.error);
+    return event;
+  }
+
+  if (call?.name === 'run_command' && out && out.exitCode !== undefined && out.exitCode !== 0) {
+    const command = String(args.command ?? '');
+    event.failed = true;
+    event.kind = `exit ${out.exitCode}`;
+    event.command = command;
+    if (isBuild(command)) {
+      event.build = true;
+      event.error = buildErrors(out.content);
+    } else {
+      event.error = buildErrors(out.content).slice(0, 400);
+    }
+  }
+  return event;
+}
+
+/**
+ * Does the latest event complete a pattern? Returns the hit, or null.
+ *
+ * Only the newest event can complete one: every earlier event was checked when
+ * it arrived, so looking again would report the same hit twice.
+ */
+export function detect(events, { window = WINDOW, thresholds = THRESHOLDS } = {}) {
+  const recent = events.slice(-window);
+  const last = recent[recent.length - 1];
+  if (!last) return null;
+
+  if (last.identical) {
+    const count = recent.filter((e) => e.identical).length;
+    return count >= thresholds.identical
+      ? { pattern: 'identical', key: 'identical', count, tool: last.tool, path: last.path, error: last.error }
+      : null;
+  }
+
+  if (last.build) {
+    const count = recent.filter((e) => e.build && e.error === last.error).length;
+    return count >= thresholds.build
+      ? { pattern: 'build', key: `build:${hash(last.error)}`, count, command: last.command, error: last.error }
+      : null;
+  }
+
+  if (last.rereads?.length) {
+    const count = recent.filter((e) => e.rereads?.length).length;
+    return count >= thresholds.reread
+      ? { pattern: 'reread', key: 'reread', count, paths: last.rereads }
+      : null;
+  }
+
+  if (last.failed) {
+    const same = (e) => e.failed && !e.identical && !e.build && e.sig === last.sig && e.kind === last.kind && e.error === last.error;
+    const count = recent.filter(same).length;
+    return count >= thresholds.repeat
+      ? {
+          pattern: 'repeat', key: `repeat:${last.sig}:${last.kind}:${hash(last.error)}`, count,
+          tool: last.tool, kind: last.kind, error: last.error, path: last.path, command: last.command,
+        }
+      : null;
+  }
+
+  return null;
+}
+
+/** What each pattern is, as a few words for the user and for the model-switch note. */
+export function describeHit(hit) {
+  switch (hit.pattern) {
+    case 'identical': return 'making edits that change nothing';
+    case 'build': return 'rebuilding on the same errors';
+    case 'reread': return 're-reading files it already has';
+    default: return `repeating a failing ${hit.tool}`;
+  }
+}
+
+const nth = (n) => `${n}${n % 10 === 1 && n % 100 !== 11 ? 'st' : n % 10 === 2 && n % 100 !== 12 ? 'nd' : n % 10 === 3 && n % 100 !== 13 ? 'rd' : 'th'}`;
+
+/** What to do instead, by the kind of failure being repeated. */
+function adviceFor(hit) {
+  if (hit.tool === 'run_command') {
+    return 'Read the output above: it names the problem. Change the cause - the code, the ' +
+      'command, or its cwd - before running it again, or take a different route.';
+  }
+  switch (hit.kind) {
+    case 'no_match':
+      return `Read ${hit.path ?? 'the file'} once, copy old_string from that result exactly as it ` +
+        'stands, without the line-number gutter - or, if the change is large, rewrite the file with write_file.';
+    case 'ambiguous':
+      return 'Add the lines around it to old_string until it matches one place only.';
+    case 'not_found':
+      return 'That path does not exist. Find the right one with glob or list_dir first.';
+    case 'bad_args':
+      return 'Fix exactly the argument the error names before calling it again.';
+    default:
+      return 'Change what the error points at, or take a different route.';
+  }
+}
+
+/** The note appended to the result that completed a hit. Empty when the result already says it. */
+export function nudge(hit, { switched = false } = {}) {
+  const lead = switched
+    ? 'ucode has handed this turn to another model, because the last one kept ' +
+      `${describeHit(hit)} after being told to stop. `
+    : '';
+
+  switch (hit.pattern) {
+    case 'identical':
+      return `${lead}STOP - that is ${hit.count} edits in a row whose old_string and new_string are ` +
+        'identical. An edit like that changes nothing, so it is refused every time. If ' +
+        `${hit.path ?? 'the file'} already says what you want, that part is finished: move on to the ` +
+        'next thing. If it does not, put the text you actually want in new_string.';
+    case 'build':
+      return `${lead}STOP - \`${hit.command}\` has now failed ${hit.count} times with the same errors:\n` +
+        `${hit.error}\n` +
+        'Building again without changing the code those lines point at fails the same way, and each ' +
+        'build takes most of a minute. Fix every error listed - in one pass, with edit_files or ' +
+        'multi_edit - then build once.';
+    case 'reread':
+      // The result itself already says the text was not sent again and why;
+      // only a model switch has anything to add.
+      return switched
+        ? `${lead}Work from the file text already in this conversation instead of reading it again.`
+        : '';
+    default:
+      return `${lead}STOP - this is the ${nth(hit.count)} time ${hit.tool} has been called with exactly ` +
+        `these arguments, and it failed the same way every time (${hit.kind}: ${oneLine(hit.error)}). ` +
+        `Calling it again will fail again. ${adviceFor(hit)}`;
+  }
+}
+
+const oneLine = (s) => {
+  const line = String(s ?? '').split('\n')[0];
+  return line.length > 200 ? `${line.slice(0, 200)}…` : line;
+};
+
+/**
+ * The detector with memory: which hits have already had their nudge.
+ *
+ * observe() returns null, a nudge, or a switch. A nudge is remembered for as
+ * long as it is inside the window; the same pattern turning up again while it
+ * is remembered means the nudge did not work. After a switch the slate is
+ * wiped, so the new model gets a nudge of its own before any further switch.
+ */
+export class StuckWatch {
+  constructor({ window = WINDOW, thresholds = THRESHOLDS } = {}) {
+    this.window = window;
+    this.thresholds = thresholds;
+    this.events = [];
+    this.seq = 0;
+    this.nudged = new Map(); // hit key -> seq of the event that was nudged
+  }
+
+  observe(event) {
+    this.seq++;
+    this.events.push({ ...event, seq: this.seq });
+    if (this.events.length > this.window * 2) this.events.splice(0, this.events.length - this.window);
+
+    const hit = detect(this.events, { window: this.window, thresholds: this.thresholds });
+    if (!hit) return null;
+
+    const at = this.nudged.get(hit.key);
+    if (at !== undefined && this.seq - at < this.window) {
+      this.reset();
+      return { action: 'switch', hit, text: nudge(hit, { switched: true }) };
+    }
+    this.nudged.set(hit.key, this.seq);
+    return { action: 'nudge', hit, text: nudge(hit) };
+  }
+
+  reset() {
+    this.events = [];
+    this.nudged.clear();
+  }
+}

package/src/tools/browser.js

@@ -25,6 +25,7 @@ const WIDTHS = [
   { name: 'desktop', width: 1440, height: 900 },
 ];
 const LOCAL = /^https?:\/\/(?:localhost|127\.0\.0\.1|0\.0\.0\.0|\[::1\])(?::\d+)?(?:\/|$)/i;
+const MAX_SHOT_HEIGHT = 3000;
 
 let browserPromise = null;
 
@@ -131,7 +132,8 @@ async function review(shots) {
       role: 'system',
       content:
         'You are a senior product designer reviewing screenshots of a web app, one at a phone width ' +
-        'and one at desktop width. List the concrete visual problems a user would notice, most ' +
+        'and one at desktop width. Each screenshot is the whole page, top to bottom, so anything not ' +
+        'in it is genuinely not there. List the concrete visual problems a user would notice, most ' +
         'important first: broken or cramped layout, overflow, misalignment, weak hierarchy (is the ' +
         'most important thing the most prominent?), inconsistent spacing, low contrast, default-looking ' +
         'components, awkward empty states, text that is too small. For each: where it is, what is wrong, ' +
@@ -144,11 +146,40 @@ async function review(shots) {
       images: shots.map((s) => s.dataUrl),
     },
   ];
-  const reply = await ask(request, [], { model: VISION_MODEL, temperature: 0.2, maxOutputTokens: 900 });
-  return reply.text.trim();
+  const reply = await ask(request, [], {
+    model: VISION_MODEL,
+    temperature: 0.2,
+    // A reasoning model spends its budget thinking before it writes; 900
+    // tokens came back as an empty review. Keep the thinking short, and leave
+    // room for the answer.
+    maxOutputTokens: 4000,
+    reasoning: { effort: 'low' },
+    // The free vision model is often busy. One try, and a hard cap: a review
+    // that cannot run is skipped, never waited on.
+    attempts: 1,
+    signal: AbortSignal.timeout(REVIEW_BUDGET_MS),
+  });
+  const text = reply.text.trim();
+  if (!text) throw new Error('the vision model returned an empty review');
+  return text;
 }
 
-export async function lookAtApp({ url, paths = ['/'], review: wantReview = true }) {
+const REVIEW_BUDGET_MS = 60_000;
+
+/**
+ * The designer's review is the slow part — a reasoning model looking at
+ * screenshots, most of a minute — so each app gets one per turn: a look after
+ * the fixes only re-runs the fast checks. A review that failed (busy model,
+ * empty reply) gets one more try on the next look, then is let go.
+ */
+const reviews = new Map(); // base URL -> { done, tries }
+
+/** A new request from the user: the apps may be reviewed afresh. */
+export function forgetReviews() {
+  reviews.clear();
+}
+
+export async function lookAtApp({ url, paths = ['/'] }) {
   const base = String(url ?? '').trim().replace(/\/+$/, '');
   if (!LOCAL.test(`${base}/`)) {
     throw new ToolFailure({
@@ -167,76 +198,104 @@ export async function lookAtApp({ url, paths = ['/'], review: wantReview = true
   await fs.mkdir(shotsDir, { recursive: true });
 
   const b = await browser();
-  const sections = [];
-  const toReview = [];
-  let problems = 0;
 
-  for (const pagePath of pages) {
-    for (const size of WIDTHS) {
-      const context = await b.newContext({ viewport: { width: size.width, height: size.height }, deviceScaleFactor: 1 });
-      const page = await context.newPage();
-      const errors = [];
-      const failed = [];
-      page.on('console', (m) => {
-        if (m.type() === 'error' && !/devtools|download the react/i.test(m.text())) errors.push(m.text().slice(0, 200));
-      });
-      page.on('pageerror', (e) => errors.push(`uncaught: ${String(e.message).slice(0, 200)}`));
-      page.on('requestfailed', (r) => failed.push(`${r.method()} ${r.url().slice(0, 100)} — ${r.failure()?.errorText ?? 'failed'}`));
-      page.on('response', (r) => { if (r.status() >= 400) failed.push(`${r.status()} ${r.url().slice(0, 100)}`); });
+  // Every page at every width opens at once, each in its own context: the
+  // wait is for the slowest one, not the sum of them all.
+  const checks = await Promise.all(pages.flatMap((pagePath) => WIDTHS.map(async (size) => {
+    let problems = 0;
+    let shot = null;
+    const context = await b.newContext({ viewport: { width: size.width, height: size.height }, deviceScaleFactor: 1 });
+    const page = await context.newPage();
+    const errors = [];
+    const failed = [];
+    page.on('console', (m) => {
+      if (m.type() === 'error' && !/devtools|download the react/i.test(m.text())) errors.push(m.text().slice(0, 200));
+    });
+    page.on('pageerror', (e) => errors.push(`uncaught: ${String(e.message).slice(0, 200)}`));
+    page.on('requestfailed', (r) => failed.push(`${r.method()} ${r.url().slice(0, 100)} — ${r.failure()?.errorText ?? 'failed'}`));
+    page.on('response', (r) => { if (r.status() >= 400) failed.push(`${r.status()} ${r.url().slice(0, 100)}`); });
 
-      const target = `${base}${pagePath}`;
-      let loadError = null;
-      try {
-        // A dev server compiles a page on its first request, which can take a
-        // while; networkidle then waits for the page's own data to arrive.
-        await page.goto(target, { waitUntil: 'networkidle', timeout: 60_000 });
-      } catch (err) {
-        try { await page.goto(target, { waitUntil: 'load', timeout: 30_000 }); }
-        catch (err2) { loadError = String(err2.message).split('\n')[0]; }
-      }
-      await page.waitForTimeout(600); // let entrance animations settle
+    const target = `${base}${pagePath}`;
+    let loadError = null;
+    try {
+      // 'load', not 'networkidle': a dev server holds a hot-reload
+      // connection open and polls, so the network may never go quiet and
+      // 'networkidle' would wait out its whole timeout on every page, at
+      // every width. 'load' covers the first-request compile; the page's own
+      // data then gets a short, bounded chance to settle.
+      await page.goto(target, { waitUntil: 'load', timeout: 90_000 });
+      await page.waitForLoadState('networkidle', { timeout: 1_500 }).catch(() => {});
+    } catch (err) {
+      loadError = String(err.message).split('\n')[0];
+    }
+    await page.waitForTimeout(400); // let entrance animations settle
 
-      const file = path.join(shotsDir, `${safeName(pagePath)}-${size.name}.jpg`);
-      let facts = null;
+    const file = path.join(shotsDir, `${safeName(pagePath)}-${size.name}.jpg`);
+    let facts = null;
+    try {
       if (!loadError) {
         facts = await page.evaluate(inspect).catch((err) => ({ error: err.message }));
-        const buffer = await page.screenshot({ type: 'jpeg', quality: 70, fullPage: false });
+        // The whole page, so the reviewer never reports as missing what is
+        // only below the fold — capped, so an endless feed stays one image.
+        const tall = await page.evaluate(() => document.documentElement.scrollHeight).catch(() => 0);
+        const buffer = await page.screenshot({
+          type: 'jpeg',
+          quality: 70,
+          fullPage: true,
+          ...(tall > MAX_SHOT_HEIGHT ? { clip: { x: 0, y: 0, width: size.width, height: MAX_SHOT_HEIGHT } } : {}),
+        });
         await fs.writeFile(file, buffer);
-        toReview.push({ label: `${pagePath} at ${size.width}px (${size.name})`, dataUrl: `data:image/jpeg;base64,${buffer.toString('base64')}` });
+        shot = { label: `${pagePath} at ${size.width}px (${size.name})`, dataUrl: `data:image/jpeg;base64,${buffer.toString('base64')}` };
       }
-      await context.close();
+    } catch (err) {
+      loadError = `the page broke while being checked: ${String(err.message).split('\n')[0]}`;
+    } finally {
+      await context.close().catch(() => {});
+    }
 
-      const lines = [`### ${pagePath} at ${size.width}px (${size.name})`];
-      if (loadError) {
-        lines.push(`Could not load: ${loadError}`);
+    const lines = [`### ${pagePath} at ${size.width}px (${size.name})`];
+    if (loadError) {
+      lines.push(`Could not load: ${loadError}`);
+      problems++;
+    } else {
+      lines.push(`Screenshot: ${path.relative(getRoot(), file).split(path.sep).join('/')}`);
+      if (facts?.empty) { lines.push('- The page rendered no visible text at all.'); problems++; }
+      if (facts?.overflow) {
+        lines.push(`- Content is ${facts.overflow}px wider than the screen, so it scrolls sideways:`, ...facts.wide.map((w) => `  - ${w}`));
         problems++;
-      } else {
-        lines.push(`Screenshot: ${path.relative(getRoot(), file).split(path.sep).join('/')}`);
-        if (facts?.empty) { lines.push('- The page rendered no visible text at all.'); problems++; }
-        if (facts?.overflow) {
-          lines.push(`- Content is ${facts.overflow}px wider than the screen, so it scrolls sideways:`, ...facts.wide.map((w) => `  - ${w}`));
-          problems++;
-        }
-        if (facts?.broken?.length) { lines.push(`- Broken images: ${facts.broken.join(', ')}`); problems++; }
-        if (facts?.unnamed?.length) { lines.push(`- Buttons or links with no accessible name: ${facts.unnamed.join(', ')}`); problems++; }
-        if (facts?.inputsNoLabel) { lines.push(`- ${facts.inputsNoLabel} form field(s) without a label.`); problems++; }
-        if (facts?.noAlt) lines.push(`- ${facts.noAlt} image(s) without alt text.`);
-        if (facts?.tiny) lines.push(`- ${facts.tiny} tap target(s) smaller than 32px on a phone.`);
-        if (facts?.smallText) lines.push(`- ${facts.smallText} text element(s) under 12px.`);
       }
-      if (errors.length) { lines.push('- Console errors:', ...[...new Set(errors)].slice(0, 6).map((e) => `  - ${e}`)); problems++; }
-      if (failed.length) { lines.push('- Failed requests:', ...[...new Set(failed)].slice(0, 6).map((f) => `  - ${f}`)); problems++; }
-      if (lines.length === 2 && !loadError) lines.push('- No errors, no overflow, nothing unlabeled.');
-      sections.push(lines.join('\n'));
+      if (facts?.broken?.length) { lines.push(`- Broken images: ${facts.broken.join(', ')}`); problems++; }
+      if (facts?.unnamed?.length) { lines.push(`- Buttons or links with no accessible name: ${facts.unnamed.join(', ')}`); problems++; }
+      if (facts?.inputsNoLabel) { lines.push(`- ${facts.inputsNoLabel} form field(s) without a label.`); problems++; }
+      if (facts?.noAlt) lines.push(`- ${facts.noAlt} image(s) without alt text.`);
+      if (facts?.tiny) lines.push(`- ${facts.tiny} tap target(s) smaller than 32px on a phone.`);
+      if (facts?.smallText) lines.push(`- ${facts.smallText} text element(s) under 12px.`);
     }
-  }
+    if (errors.length) { lines.push('- Console errors:', ...[...new Set(errors)].slice(0, 6).map((e) => `  - ${e}`)); problems++; }
+    if (failed.length) { lines.push('- Failed requests:', ...[...new Set(failed)].slice(0, 6).map((f) => `  - ${f}`)); problems++; }
+    if (lines.length === 2 && !loadError) lines.push('- No errors, no overflow, nothing unlabeled.');
+    const broken = Boolean(loadError || errors.length || facts?.empty);
+    return { section: lines.join('\n'), shot, problems, broken };
+  })));
+
+  const sections = checks.map((c) => c.section);
+  const toReview = checks.map((c) => c.shot).filter(Boolean);
+  const problems = checks.reduce((n, c) => n + c.problems, 0);
+  const broken = checks.some((c) => c.broken);
 
+  // A page that crashed or threw is fixed first; reviewing a screenshot of an
+  // error overlay is a minute spent on nothing.
   let critique = '';
-  if (wantReview !== false && toReview.length) {
+  const state = reviews.get(base) ?? { done: false, tries: 0 };
+  if (!broken && !state.done && state.tries < 2 && toReview.length) {
+    state.tries++;
+    reviews.set(base, state);
     try {
       critique = await review(toReview.slice(0, 4));
+      state.done = true;
     } catch (err) {
-      critique = `(The visual review could not run: ${err.failed ?? err.message}. The checks above still apply.)`;
+      const why = String(err.failed ?? err.message).replace(/[.\s]+$/, '');
+      critique = `(The visual review could not run: ${why}. The checks above still apply.)`;
     }
   }
 
@@ -246,7 +305,10 @@ export async function lookAtApp({ url, paths = ['/'], review: wantReview = true
     '',
     problems
       ? 'Fix the problems above, then look again to confirm.'
-      : 'The automatic checks found nothing. Weigh the visual review, fix what is worth fixing.',
+      : state.done && critique
+        ? 'The automatic checks found nothing. Weigh the visual review, fix what is worth fixing - ' +
+          'the next look re-runs only the fast checks.'
+        : 'The automatic checks found nothing.',
   ].filter(Boolean).join('\n\n');
 
   return result(