ucode-agent 1.4.0 → 1.6.0

package/src/core/loop.js

@@ -12,6 +12,8 @@
  */
 
 import path from 'node:path';
+import os from 'node:os';
+import { appendFileSync } from 'node:fs';
 import { readFile, access } from 'node:fs/promises';
 import { spawn } from 'node:child_process';
 
@@ -24,7 +26,7 @@ import {
 } from '../tools/index.js';
 import { projectMap, loadMemory, remember, MEMORY_FILE } from './context.js';
 import { autoUpdate } from './updater.js';
-import { closeBrowser } from '../tools/browser.js';
+import { closeBrowser, forgetReviews } from '../tools/browser.js';
 import {
   newSession, save, load, list, remove, removeAll, titleFrom,
 } from './history.js';
@@ -34,6 +36,11 @@ import { Screen, isLabel } from '../ui/screen.js';
 import { Plain } from '../ui/plain.js';
 import { theme, blue, sky, dim, formatTokens, relativeTime, shortenPath, clip } from '../ui/theme.js';
 import { Failure, ToolFailure, Declined } from './failure.js';
+import { StuckWatch, eventFor, describeHit } from './stuck.js';
+import { serversReadySince } from '../tools/shell.js';
+import { formatDuration } from '../ui/activity.js';
+import { runDoctor } from './doctor.js';
+import { deploy } from '../tools/deploy.js';
 
 /**
  * Tool calls allowed in one turn.
@@ -72,11 +79,126 @@ const CHECKABLE = /\.(?:[cm]?[jt]sx?|py)$/i;
  * model and carries on from exactly where it was.
  */
 const TRANSIENT = new Set(['rate_limit', 'timeout', 'server', 'network', 'no_content']);
+/** Will another model, or a little patience, get past this? Not the daily cap: it covers them all. */
+const passing = (err) => TRANSIENT.has(err.kind) && !err.detail?.daily;
 const MAX_FAILOVERS = 8;
 const COOLDOWN = 5 * 60_000;
 
 const wait = (ms) => new Promise((r) => setTimeout(r, ms));
 
+/**
+ * UCODE_TRACE=1 writes one JSON line per model call and per tool to
+ * ~/.ucode/trace.jsonl (or to the path UCODE_TRACE names): how long it took,
+ * tokens in and out, what was called. It is how "it feels slow" becomes a
+ * number with a cause attached.
+ */
+const TRACE_FILE = process.env.UCODE_TRACE
+  ? (process.env.UCODE_TRACE === '1' ? path.join(os.homedir(), '.ucode', 'trace.jsonl') : process.env.UCODE_TRACE)
+  : null;
+
+/** Tool results worth re-sending in full only while they are recent. */
+const THIN_RESULTS = new Set([
+  'read_file', 'read_files', 'grep', 'glob', 'list_dir', 'run_command', 'run_commands',
+  'look_at_app', 'web_search', 'edit_file', 'multi_edit', 'edit_files',
+]);
+
+/** Replace long strings in old tool arguments with a note of their size. */
+function thinArgs(value) {
+  if (typeof value === 'string') {
+    return value.length > 400
+      ? `[${value.length} characters, already applied — read the file if you need its current text]`
+      : value;
+  }
+  if (Array.isArray(value)) return value.map(thinArgs);
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, thinArgs(v)]));
+  }
+  return value;
+}
+
+/**
+ * The conversation as sent, with bulky history thinned.
+ *
+ * Every file the model writes travels inside its own tool call, so a
+ * thirty-file app is re-sent in full on every later step — tens of thousands
+ * of tokens the provider has to read before it can answer, growing with
+ * each file. Beyond the last few steps that text is replaced by a note of its
+ * size; the files are on disk, and the model re-reads one when it needs it.
+ * Call ids and results stay paired, and the saved session keeps everything.
+ */
+export function lean(messages, keep = 3) {
+  let seen = 0;
+  let cut = -1;
+  for (let i = messages.length - 1; i >= 0; i--) {
+    if (messages[i].role === 'assistant' && messages[i].toolCalls?.length && ++seen === keep) { cut = i; break; }
+  }
+  if (cut <= 0) return messages;
+  return messages.map((m, i) => {
+    if (i >= cut) return m;
+    if (m.role === 'assistant' && m.toolCalls?.length) {
+      return { ...m, toolCalls: m.toolCalls.map((c) => ({ ...c, args: thinArgs(c.args) })) };
+    }
+    if (m.role === 'tool' && THIN_RESULTS.has(m.name) && (m.content?.length ?? 0) > 1500) {
+      return {
+        ...m,
+        content: `${m.content.slice(0, 300)}
+… [${m.content.length} characters from an earlier step, trimmed ` +
+          'to keep the conversation fast — run the tool again if you need this now]',
+      };
+    }
+    return m;
+  });
+}
+
+function trace(event) {
+  if (!TRACE_FILE) return;
+  try { appendFileSync(TRACE_FILE, `${JSON.stringify({ at: Date.now(), ...event })}
+`); } catch { /* never fatal */ }
+}
+
+/** What /stats reports, counted as the session goes. */
+function newStats() {
+  return {
+    started: Date.now(), workMs: 0, turns: 0, steps: 0, tokensIn: 0, tokensOut: 0,
+    tools: {}, failed: 0, written: 0, edited: 0, commands: 0, builds: 0, stuck: 0,
+  };
+}
+
+const BUILD_COMMAND = /\b(?:npm|pnpm|yarn|bun)\s+(?:run\s+)?build\b|\bnext\s+build\b|\bvite\s+build\b/;
+
+function countTool(stats, call, out, err) {
+  stats.tools[call.name] = (stats.tools[call.name] ?? 0) + 1;
+  if (err) { stats.failed++; return; }
+  const a = call.args ?? {};
+  if (call.name === 'write_file') stats.written++;
+  if (call.name === 'batch_write') stats.written += a.files?.length ?? 0;
+  if (call.name === 'edit_file' || call.name === 'multi_edit') stats.edited++;
+  if (call.name === 'edit_files') stats.edited += new Set((a.edits ?? []).map((e) => e.path)).size || 1;
+  if (call.name === 'run_command') {
+    stats.commands++;
+    if (BUILD_COMMAND.test(a.command ?? '')) stats.builds++;
+  }
+  if (call.name === 'run_commands') stats.commands += a.commands?.length ?? 0;
+}
+
+/** The /stats box. */
+export function statsLines(st, messages) {
+  const n = (v) => Number(v).toLocaleString();
+  const top = Object.entries(st.tools).sort((x, y) => y[1] - x[1]).slice(0, 6)
+    .map(([k, v]) => `${k} ${v}`).join(' · ') || 'none yet';
+  const plural = (v, w) => `${v} ${w}${v === 1 ? '' : 's'}`;
+  const rows = [
+    ['Session', `${formatDuration(Date.now() - st.started)} open · ${formatDuration(st.workMs)} working · ${plural(st.turns, 'request')}`],
+    ['Model', `${n(st.steps)} steps · ${formatTokens(st.tokensIn)} in · ${formatTokens(st.tokensOut)} out`],
+    ['Tools', top],
+    ['Files', `${st.written} written · ${st.edited} edited`],
+    ['Commands', `${st.commands} run · ${plural(st.builds, 'build')}${st.failed ? ` · ${plural(st.failed, 'tool call')} failed` : ''}`],
+    ['Context', `${messages} messages${st.stuck ? ` · ${plural(st.stuck, 'loop')} caught` : ''}`],
+  ];
+  const w = Math.max(...rows.map(([k]) => k.length));
+  return ['', `  ${blue('Stats')}`, ...rows.map(([k, v]) => `  ${dim(k.padEnd(w))}  ${v}`), ''];
+}
+
 /** Parallel workers at once, and how many steps each may take. */
 const MAX_WORKERS = 3;
 const WORKER_STEPS = Number(process.env.UCODE_WORKER_STEPS) || 60;
@@ -238,9 +360,15 @@ function systemPrompt({ cwd, skills, mode, check, map, memory }) {
     '',
     '- Need more than one file? read_files, all of them in one call. Never read files',
     '  one at a time when you already know which ones you want.',
+    '- An edit result shows the file as it now stands. Do not read a file again after',
+    '  editing it - you already have its current text.',
     '- Put independent calls in the same message — several greps, a glob and a read.',
     '  Read-only calls in one message run at the same time.',
-    '- batch_write to lay out several new files at once, multi_edit for several changes',
+    '- New Next.js app? create_app - one step, never create-next-app or shadcn init. It',
+    '  copies a starter that already builds and installs it in the background.',
+    '- batch_write to lay out several new files at once - but at most about four per',
+    '  call: one slip in a huge call throws the whole call away.',
+    '- multi_edit for several changes',
     '  to one file, edit_files for a change that spans several files.',
     '- For work with three or more steps, keep a short plan with update_plan - at most',
     '  six items of a few words - and tick items off as they finish. Skip it for small jobs.',
@@ -251,9 +379,12 @@ function systemPrompt({ cwd, skills, mode, check, map, memory }) {
     '  writing files. Running the install yourself afterwards just waits for that one.',
     '- When you finish, ucode type-checks what you changed and hands you the errors, so',
     '  there is no need to run tsc yourself.',
-    '- Once the dev server is ready, run look_at_app on the pages you built and fix what',
-    '  it reports - errors, layout that overflows a phone, and the visual review - then',
-    '  look again. Do not call an interface finished before it has been looked at.',
+    '- Once the dev server is ready, run look_at_app on the pages you built. Fix what it',
+    '  reports - errors, layout that overflows a phone, the review points worth fixing -',
+    '  in one pass, then look once more. A clean second look means it is done: report',
+    '  back instead of polishing in circles. Never call an interface finished unlooked at.',
+    '- Asked to deploy, publish, host or share the app? Use the deploy tool - it picks the',
+    '  name, handles keys and returns the live link. Build locally first.',
     '- Nothing you run has a keyboard. Pass the non-interactive flag to anything that',
     '  would ask a question, or it fails instead of waiting: create-next-app --yes,',
     '  npx shadcn@latest init -d -y, npx shadcn@latest add <names> -y, npm init -y.',
@@ -261,6 +392,17 @@ function systemPrompt({ cwd, skills, mode, check, map, memory }) {
     '  URL once the server says it is ready. Do not start one twice, do not sleep while',
     '  waiting for it, and do not curl it before that result comes back.',
     '',
+    '## When something fails',
+    '',
+    '- A failed build names the problem. Fix exactly that, then build again. Never go',
+    '  exploring inside node_modules: a missing component or package is one install away.',
+    '- A build takes most of a minute. Fix every error it lists in one pass - multi_edit,',
+    '  edit_files - before building again, never one error per build.',
+    '- Never delete an app folder to start over. Fix it where it is - starting again throws',
+    '  away the install and everything already written.',
+    '- Run an app\'s commands with cwd set to its folder, and keep paths inside those',
+    '  commands relative to that folder.',
+    '',
     '## Safety',
     '',
     '- run_command runs without asking. That is trust rather than licence: never run',
@@ -324,6 +466,7 @@ export class Agent {
     // CI and `echo ... | ucode` get the line-based interface instead.
     this.full = Boolean(process.stdout.isTTY && process.stdin.isTTY);
     this.ui = this.full ? new Screen({ cwd }) : new Plain({ cwd });
+    this.stats = newStats();
     this.skills = [];
     this.session = newSession(cwd, model());
     this.working = [];
@@ -571,6 +714,7 @@ export class Agent {
   }
 
   async turn(input) {
+    forgetReviews(); // a new request: its apps get a fresh design review
     const images = await this.attachImages(input);
     this.push(images.length
       ? { role: 'user', content: input, images }
@@ -599,17 +743,36 @@ export class Agent {
     this.busy = true;
     this.abort = new AbortController();
 
+    const turnStarted = Date.now();
+    let finished = false;
+    this.ui.turnStart?.();
     try {
-      await this.run();
+      for (;;) {
+        try {
+          await this.run();
+          break;
+        } catch (err) {
+          // The daily free cap mid-build: wait for the reset and carry on,
+          // rather than leaving a half-built app for the user to restart.
+          if (err?.detail?.daily && !this.abort.signal.aborted && (await this.waitForReset(err))) continue;
+          throw err;
+        }
+      }
+      finished = true;
     } catch (err) {
       if (err?.kind === 'aborted' || this.abort.signal.aborted) this.ui.write(dim('  turn cancelled'));
       else throw err;
     } finally {
+      trace({ kind: 'turn', ms: Date.now() - turnStarted });
+      this.stats.workMs += Date.now() - turnStarted;
+      this.stats.turns++;
       this.busy = false;
       this.abort = null;
       this.ui.stopSpinner();
+      this.ui.turnEnd?.({ ok: finished });
       await this.persist();
       if (this.full) this.showHeader({ clear: false });
+      if (finished) this.openWhenReady(turnStarted);
     }
   }
 
@@ -631,6 +794,7 @@ export class Agent {
     this.failovers = 0;
     this.tried = new Set([model()]);
 
+    this.stuck = new StuckWatch();
     this.touched = new Set();
     this.sinceCheck = new Set();
     this.ranSomething = false;
@@ -669,6 +833,7 @@ export class Agent {
           };
         }
 
+        var asked = Date.now();
         reply = await ask(
           [
             {
@@ -682,7 +847,7 @@ export class Agent {
                 memory: this.memory,
               }),
             },
-            ...this.working,
+            ...lean(this.working),
           ],
           available,
           opts
@@ -710,7 +875,7 @@ export class Agent {
 
         // Busy, slow or down: move to the next model and carry on, rather
         // than ending a half-built app with an error.
-        if (TRANSIENT.has(err.kind) && !this.abort.signal.aborted && (await this.failover(err))) continue;
+        if (passing(err) && !this.abort.signal.aborted && (await this.failover(err))) continue;
         throw err;
       }
 
@@ -719,6 +884,15 @@ export class Agent {
       this.ui.thinkingEnd();
       this.ui.stopSpinner();
       this.record(reply.usage);
+      this.ui.step?.();
+      this.stats.steps++;
+      this.stats.tokensIn += reply.usage.promptTokens ?? 0;
+      this.stats.tokensOut += reply.usage.outputTokens ?? 0;
+      trace({
+        kind: 'model', who: 'lead', model: model(), ms: Date.now() - asked,
+        in: reply.usage.promptTokens, out: reply.usage.outputTokens,
+        calls: reply.toolCalls.map((c) => c.name),
+      });
 
       // Streamed text is already on screen; turn it into rendered markdown.
       // Text that turns out to be narration ahead of a tool call folds into a
@@ -914,11 +1088,112 @@ export class Agent {
     return badArgs;
   }
 
+  /**
+   * Check a finished call against the stuck patterns (see stuck.js) and return
+   * the note to add to its result. A nudge that did not work hands the turn to
+   * another model.
+   */
+  stuckNote(call, outcome) {
+    if (!this.stuck) return '';
+    const verdict = this.stuck.observe(eventFor(call, outcome));
+    if (!verdict) return '';
+    this.stats.stuck++;
+    if (verdict.action === 'switch') {
+      const next = fallbackFor(model(), this.tried ?? new Set([model()]));
+      if (next) {
+        this.tried?.add(next);
+        this.ui.note(`${modelName(model())} kept ${describeHit(verdict.hit)} — handing over to ${modelName(next)}`);
+        setModel(next);
+        this.cooldownUntil = Date.now() + COOLDOWN;
+        if (this.full) this.showHeader({ clear: false });
+      }
+    }
+    return verdict.text ? `\n\n${verdict.text}` : '';
+  }
+
+  /**
+   * The daily free cap was hit mid-turn: keep the session, count down to the
+   * reset, and carry on by itself. Esc stops the wait like any other turn.
+   */
+  async waitForReset(err) {
+    const resetAt = err.detail?.resetAt;
+    if (!Number.isFinite(resetAt)) return false;
+    const at = resetAt + 30_000;
+    const clock = new Date(at).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' });
+    this.ui.stopSpinner();
+    this.ui.note(`Daily limit reached — ucode carries on by itself at ${clock}. Esc to stop`);
+    await this.persist();
+    let lastNote = Date.now();
+    while (Date.now() < at) {
+      if (this.abort?.signal.aborted) return false;
+      const left = formatDuration(at - Date.now());
+      if (this.full) this.ui.startSpinner(`daily limit · carrying on at ${clock} (in ${left})`);
+      else if (Date.now() - lastNote > 30 * 60_000) { this.ui.note(`still waiting for the daily limit — ${left} to go`); lastNote = Date.now(); }
+      await new Promise((r) => setTimeout(r, Math.min(1000, Math.max(0, at - Date.now()))));
+    }
+    this.ui.stopSpinner();
+    this.ui.note('Daily limit has reset — carrying on');
+    return true;
+  }
+
+  /** A dev server came up during this turn: open it in the browser, once. */
+  openWhenReady(since) {
+    if (!this.full || process.env.UCODE_OPEN === '0') return;
+    const server = serversReadySince(since).at(-1);
+    if (!server || (this.opened ??= new Set()).has(server.url)) return;
+    this.opened.add(server.url);
+    const [cmd, args] = process.platform === 'win32'
+      ? ['cmd', ['/c', 'start', '', server.url]]
+      : [process.platform === 'darwin' ? 'open' : 'xdg-open', [server.url]];
+    try {
+      spawn(cmd, args, { stdio: 'ignore', detached: true, windowsHide: true }).unref();
+      this.ui.note(`Opened ${server.url} in your browser`);
+    } catch { /* no browser to open — the link is in the answer */ }
+  }
+
+  cmdStats() {
+    for (const line of statsLines(this.stats, this.working?.length ?? 0)) this.ui.write(line);
+  }
+
+  async cmdDoctor() {
+    this.ui.startSpinner('checking your setup');
+    try {
+      const lines = await runDoctor();
+      this.ui.stopSpinner();
+      for (const line of lines) this.ui.write(line);
+    } finally {
+      this.ui.stopSpinner();
+    }
+  }
+
+  /** /deploy [folder] — the same tool the model calls, run directly. */
+  async cmdDeploy(arg) {
+    const folder = (arg ?? '').trim() || '.';
+    this.ui.toolCall(`Deploying ${folder}`);
+    this.ui.startSpinner('getting ready to deploy');
+    try {
+      const out = await deploy({ folder }, { onOutput: (lines) => this.ui.updateSpinner(lines.at(-1)) });
+      this.ui.stopSpinner();
+      this.ui.toolResult(out.summary);
+      this.ui.write(out.content.split('\n').map((l) => `  ${l}`).join('\n'));
+    } catch (err) {
+      this.ui.stopSpinner();
+      if (err instanceof ToolFailure) this.ui.error(err);
+      else throw err;
+    }
+  }
+
   reportResult(call, out) {
+    // A build or type check that just passed already verified everything
+    // changed so far; the automatic check at the end would only repeat it.
+    if (call.name === 'run_command' && out.exitCode === 0 &&
+        /(?:next build|npm run build|pnpm (?:run )?build|tsc)/.test(call.args?.command ?? '')) {
+      this.sinceCheck?.clear();
+    }
     if (!QUIET.has(call.name)) this.ui.toolResult(out.summary);
     if (out.diff?.length) this.ui.diff(out.diff);
     if (out.output?.length) this.ui.commandOutput(out.output);
-    this.push({ role: 'tool', toolCallId: call.id, name: call.name, content: out.content });
+    this.push({ role: 'tool', toolCallId: call.id, name: call.name, content: out.content + this.stuckNote(call, { out }) });
   }
 
   /** Show a tool failure, hand it to the model, and say if it was bad arguments. */
@@ -932,7 +1207,7 @@ export class Agent {
       role: 'tool',
       toolCallId: call.id,
       name: call.name,
-      content: err.forModel(),
+      content: err.forModel() + (err instanceof Declined ? '' : this.stuckNote(call, { err })),
     });
     return err.kind === 'bad_args';
   }
@@ -994,7 +1269,11 @@ export class Agent {
 
   /** Run a call and settle to { out } or { err } — never throws. */
   execute(call) {
-    return this.dispatch(call).then((out) => ({ out }), (err) => ({ err }));
+    const started = Date.now();
+    return this.dispatch(call).then(
+      (out) => { trace({ kind: 'tool', name: call.name, ms: Date.now() - started }); countTool(this.stats, call, out); return { out }; },
+      (err) => { trace({ kind: 'tool', name: call.name, ms: Date.now() - started, err: err?.kind }); countTool(this.stats, call, null, err); return { err }; }
+    );
   }
 
   updatePlan(items) {
@@ -1080,11 +1359,12 @@ export class Agent {
       if (this.abort?.signal.aborted) break;
 
       let reply;
+      const asked = Date.now();
       try {
         reply = await ask(messages, available, { signal: this.abort?.signal, model: workerModel });
       } catch (err) {
         // Same rule as the lead: a busy model is swapped, not a reason to stop.
-        if (TRANSIENT.has(err.kind) && failovers < 6 && !this.abort?.signal.aborted) {
+        if (passing(err) && failovers < 6 && !this.abort?.signal.aborted) {
           failovers++;
           let next = fallbackFor(workerModel, tried);
           if (!next) { tried.clear(); await wait(20_000); next = fallbackFor(workerModel, tried) ?? workerModel; }
@@ -1097,6 +1377,11 @@ export class Agent {
         throw err;
       }
       this.record(reply.usage);
+      trace({
+        kind: 'model', who: name, model: workerModel, ms: Date.now() - asked,
+        in: reply.usage.promptTokens, out: reply.usage.outputTokens,
+        calls: reply.toolCalls.map((c) => c.name),
+      });
 
       if (!reply.toolCalls.length) {
         this.ui.toolResult(`${name} finished`);
@@ -1288,6 +1573,9 @@ export class Agent {
       case '/clear':    this.showHeader(); return;
       case '/search':   return this.cmdSearch(arg);
       case '/copy':     return this.cmdCopy();
+      case '/stats':    return this.cmdStats();
+      case '/doctor':   return this.cmdDoctor();
+      case '/deploy':   return this.cmdDeploy(arg);
       case '/exit':
       case '/quit':     return 'exit';
 
@@ -1300,6 +1588,9 @@ export class Agent {
   cmdHelp() {
     const rows = [
       ['/help', 'this list'],
+      ['/stats', 'time, steps and tokens this session'],
+      ['/doctor', 'check that everything ucode needs is working'],
+      ['/deploy [folder]', 'put the app online and get its link'],
       ['/model', 'show the models and switch between them'],
       ['/resume', 'pick up an earlier conversation'],
       ['/new', 'save this one and start fresh'],

package/src/core/provider.js

@@ -22,6 +22,7 @@ import { homedir } from 'node:os';
 import { fileURLToPath } from 'node:url';
 import dotenv from 'dotenv';
 import OpenAI from 'openai';
+import { jsonrepair } from 'jsonrepair';
 import { Failure } from './failure.js';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
@@ -395,7 +396,14 @@ export function explain(err, id) {
       (Number.isFinite(asNumber) && asNumber > 0 ? asNumber : null) ??
       seconds(/try again in ([\dhms.]+)/i.exec(detail)?.[1]) ??
       null;
-    const daily = /per day|RPD|TPD|tokens per day/i.test(detail);
+    // The daily cap reads "free-models-per-day-high-balance", with hyphens, and
+    // names its source in the metadata. It is one cap across every free model,
+    // so it is reported at once rather than waited on model after model.
+    const meta = body?.error?.metadata ?? {};
+    const daily = /per[- ]day|RPD|TPD|daily/i.test(`${detail} ${meta.limit_source ?? ''}`);
+    const resetMs = Number(meta.headers?.['X-RateLimit-Reset'] ?? err?.headers?.get?.('x-ratelimit-reset'));
+    const resetAt = daily && Number.isFinite(resetMs) && resetMs > Date.now() ? new Date(resetMs) : null;
+    const cap = Number(meta.headers?.['X-RateLimit-Limit']) || null;
     const wait = Number.isFinite(retryAfter) && retryAfter
       ? (retryAfter >= 60 ? `${Math.ceil(retryAfter / 60)} min` : `${Math.ceil(retryAfter)}s`)
       : null;
@@ -404,14 +412,14 @@ export function explain(err, id) {
       kind: 'rate_limit',
       attempted,
       failed: daily
-        ? `The free daily request cap for ${modelName(id)} is used up.`
+        ? `This key's free daily limit${cap ? ` of ${cap} requests` : ''} is used up. It covers every free model, so switching will not help.`
         : `Too many requests for ${modelName(id)} just now${wait ? ` — clear in ${wait}` : ''}.`,
       fix: daily
-        ? 'Free caps reset each day. /model switches to another one, or add credit to ' +
-          'your account to lift the ceiling.'
+        ? `It resets ${resetAt ? `at ${resetAt.toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' })}` : 'once a day'}. ` +
+          'Adding credit to your account raises the limit.'
         : 'ucode waits these out on its own. Free endpoints are shared, so it usually ' +
           'clears in seconds; /model moves to a quieter one.',
-      detail: { retryAfter, daily },
+      detail: { retryAfter, daily, resetAt: resetAt?.getTime() ?? null },
       cause: err,
     });
   }
@@ -554,7 +562,7 @@ const pause = (ms) => new Promise((r) => setTimeout(r, ms));
  * @param {Array}  messages neutral messages
  * @param {Array}  [tools]  neutral tool definitions
  * @param {object} [opts]   { model, temperature, signal, maxOutputTokens,
- *                            onText, onThinking, onWait }
+ *                            reasoning, attempts, onText, onThinking, onWait }
  */
 export async function ask(messages, tools = [], opts = {}) {
   const id = opts.model || current;
@@ -578,8 +586,11 @@ export async function ask(messages, tools = [], opts = {}) {
   }
   if (opts.temperature !== undefined) request.temperature = opts.temperature;
   if (opts.maxOutputTokens) request.max_tokens = opts.maxOutputTokens;
+  if (opts.reasoning) request.reasoning = opts.reasoning;
 
-  const attempts = 4;
+  // A side call (the design review) passes fewer: it is better skipped than
+  // waited on through a string of rate-limit pauses.
+  const attempts = opts.attempts ?? 4;
   let problem;
 
   // Text already on screen cannot be unprinted, so a stream is only safe to
@@ -710,7 +721,7 @@ async function streamed(request, opts, id) {
 
   const toolCalls = [];
   for (const [index, slot] of partial) {
-    toolCalls.push(readCall({ id: slot.id || `call_${index}`, name: slot.name, raw: slot.args }));
+    toolCalls.push(readCall({ id: slot.id || `call_${index}`, name: slot.name, raw: slot.args, cutOff: finishReason === 'length' }));
   }
 
   return {
@@ -727,6 +738,56 @@ async function streamed(request, opts, id) {
   };
 }
 
+/**
+ * Recover the files from a file-write call whose JSON will not parse.
+ *
+ * The usual cause is a double quote inside the code that the model forgot to
+ * escape — `className="flex"` — which ends the JSON string early. No general
+ * repair can know which quote was meant, but a file write has a fixed shape:
+ * "path", then "content", then either the next file or the end. Splitting on
+ * that shape and escaping the stray quotes gets every file back.
+ */
+export function salvageWrites(text) {
+  const heads = [...text.matchAll(/"path"\s*:\s*"((?:[^"\\]|\\.)*)"\s*,\s*"content"\s*:\s*"/g)];
+  if (!heads.length) return null;
+
+  const files = [];
+  for (let i = 0; i < heads.length; i++) {
+    const from = heads[i].index + heads[i][0].length;
+    const to = i + 1 < heads.length ? heads[i + 1].index : text.length;
+    // The string ends at the last quote that is followed by nothing but JSON
+    // punctuation — `"}, {`, or `"}}, {` when the model added a brace, or `"}]}`.
+    const body = text.slice(from, to).replace(/"[\s,{}[\]]*$/, '');
+    const content = unescapeLoose(body);
+    const pathValue = unescapeLoose(heads[i][1]);
+    if (!pathValue || !content) return null; // not the shape we thought — leave it an honest error
+    files.push({ path: pathValue, content });
+  }
+  return files.length ? files : null;
+}
+
+/**
+ * Decode a JSON string body the forgiving way: the standard escapes are
+ * honoured, and everything JSON would reject — a raw line break, a tab, a stray
+ * quote, an escape JSON does not know — is kept as the character it plainly is.
+ */
+function unescapeLoose(s) {
+  const simple = { n: '\n', t: '\t', r: '\r', b: '\b', f: '\f', '"': '"', '\\': '\\', '/': '/' };
+  let out = '';
+  for (let i = 0; i < s.length; i++) {
+    const c = s[i];
+    if (c !== '\\' || i === s.length - 1) { out += c; continue; }
+    const next = s[++i];
+    if (next === 'u' && /^[0-9a-fA-F]{4}$/.test(s.slice(i + 1, i + 5))) {
+      out += String.fromCharCode(parseInt(s.slice(i + 1, i + 5), 16));
+      i += 4;
+    } else {
+      out += simple[next] ?? next;
+    }
+  }
+  return out;
+}
+
 /**
  * Parse one tool call's arguments.
  *
@@ -734,7 +795,7 @@ async function streamed(request, opts, id) {
  * back to the model, which usually fixes its own JSON on the next step —
  * cheaper than failing the whole turn over a stray comma.
  */
-function readCall({ id, name, raw }) {
+export function readCall({ id, name, raw, cutOff = false }) {
   const call = { id, name, args: {} };
   const text = String(raw ?? '').trim();
   if (!text) return call;
@@ -743,6 +804,28 @@ function readCall({ id, name, raw }) {
     if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) call.args = parsed;
     else call.parseError = `arguments must be a JSON object, got ${Array.isArray(parsed) ? 'array' : typeof parsed}`;
   } catch (err) {
+    // A missing comma or a stray control character in a 3,000-token
+    // batch_write used to throw the whole step away — half a minute of output
+    // discarded over one character. Repair the usual slips instead. Never when
+    // the reply was cut off at the output limit, though: repairing that would
+    // close the string and quietly write half a file.
+    if (!cutOff) {
+      try {
+        const fixed = JSON.parse(jsonrepair(text));
+        if (fixed && typeof fixed === 'object' && !Array.isArray(fixed)) {
+          call.args = fixed;
+          call.repaired = true;
+          return call;
+        }
+      } catch { /* beyond general repair — try the file-write shape next */ }
+
+      const salvaged = (name === 'write_file' || name === 'batch_write') ? salvageWrites(text) : null;
+      if (salvaged) {
+        call.args = name === 'write_file' ? salvaged[0] : { files: salvaged };
+        call.repaired = true;
+        return call;
+      }
+    }
     call.parseError = `${err.message} — the raw arguments were: ${text.slice(0, 300)}`;
   }
   return call;
@@ -753,7 +836,7 @@ function normalize(data, id) {
   const message = choice?.message ?? {};
 
   const toolCalls = (message.tool_calls ?? []).map((c) =>
-    readCall({ id: c.id, name: c.function?.name, raw: c.function?.arguments })
+    readCall({ id: c.id, name: c.function?.name, raw: c.function?.arguments, cutOff: choice?.finish_reason === 'length' })
   );
 
   const u = data?.usage ?? {};