ucode-agent 1.26.1 → 1.27.0

package/src/tools/index.js

@@ -8,7 +8,7 @@ import { readFile, readFiles, writeFile, batchWrite, editFile, multiEdit, editFi
 import { listDir, glob, grep } from './search.js';
 import { findSymbol, outline } from './symbols.js';
 import { renameSymbol } from './rename.js';
-import { addBlock, BLOCK_NAMES } from './blocks.js';
+import { addBlock, BLOCK_NAMES, PLAIN_BLOCK_NAMES, ALL_BLOCK_NAMES } from './blocks.js';
 import { typeOf } from './types.js';
 import { runCommand, runCommands } from './shell.js';
 import { webSearch } from './web.js';
@@ -82,27 +82,45 @@ export const tools = [
   {
     name: 'create_app',
     description:
-      'Start a new app from a starter that already works. Two to choose between, and the ' +
-      'choice matters. "plain-html": one index.html, one stylesheet, one ES module — nothing ' +
-      'to install, nothing to build, opens straight in a browser. Use it whenever the user ' +
-      'asks for plain HTML/CSS/JS, or for a single page, a toy, a game or a visualisation. ' +
-      '"next-shadcn": Next.js 16, TypeScript, Tailwind 4 and shadcn with 33 components, light ' +
-      'and dark, toasts, and a design preset — for anything with routes, data or many screens; ' +
-      'its packages install in the background so you can write components at once. This is how ' +
-      'every Next.js app begins - never run create-next-app or shadcn init. Do not reach for ' +
-      'Next.js when a single HTML file is what was asked for.',
+      'Start a new app AND write it, in one call. Pass "files" with the whole app and this ' +
+      'is the only call the build needs: the starter lands, your files are written over it, ' +
+      'and the result comes back with everything. Two starters. "plain-html" (the default): ' +
+      'one index.html, one stylesheet, one ES module — nothing to install, nothing to build, ' +
+      'opens straight in a browser, and its three files come back inside this result so there ' +
+      'is never a reason to read them. Use it for anything that is one page: a tasks app, a ' +
+      'toy, a game, a visualisation, a calculator, a timer. "next-shadcn": Next.js 16, ' +
+      'TypeScript, Tailwind 4 and shadcn with 33 components — only when the app genuinely ' +
+      'needs routes, a database or many screens, because it costs an install and a build. ' +
+      'This is how every Next.js app begins - never run create-next-app or shadcn init.',
     parameters: {
       type: 'object',
       properties: {
         folder: str('A new, empty folder for the app, relative to the project root, e.g. "stride".'),
         name: str('The display name of the app, e.g. "Stride".'),
         description: str('One line about the app, used in the page metadata.'),
+        files: {
+          type: 'array',
+          description:
+            'The app itself, written in this same call, straight over the starter\'s files. ' +
+            'Pass the whole app here rather than following up with batch_write - it saves a ' +
+            'round trip, which is most of the time a build takes. Paths are relative to the ' +
+            'project root and so include the app folder, e.g. "stride/index.html".',
+          items: {
+            type: 'object',
+            properties: {
+              path: str('Path relative to the project root, e.g. "stride/index.html".'),
+              content: str('The complete contents of the file.'),
+            },
+            required: ['path', 'content'],
+          },
+        },
         template: {
           type: 'string',
           enum: ['next-shadcn', 'plain-html'],
           description:
-            'Which starter. "plain-html" for plain HTML/CSS/JS, a single page, a toy or a game: ' +
-            'no install, no build. "next-shadcn" (the default) for routes, data or many screens.',
+            'Which starter. "plain-html" (the default) for one page, a toy, a game, or any ' +
+            'app that does not need a server: no install, no build, nothing to wait for. ' +
+            '"next-shadcn" only for routes, a database or many screens.',
         },
         design: {
           type: 'string',
@@ -369,16 +387,20 @@ export const tools = [
   {
     name: 'add_block',
     description:
-      'Add a ready-made, polished piece of an app — ' + BLOCK_NAMES.join(', ') + '. Each is ' +
-      'copied in as an ordinary source file you can then edit, built on the shadcn ' +
-      'components already in the starter, so nothing needs installing. Call it with no ' +
-      'name to see what each one is for. Prefer these over writing a table or an empty ' +
-      'state from scratch: they already handle sorting, empty and loading states, ' +
-      'alignment and small screens.',
+      'Add a ready-made, polished piece of an app, copied in as an ordinary source file ' +
+      'you can then edit. Which set you get is decided by the app itself, so you never ' +
+      'pick wrong. For a plain page: ' + PLAIN_BLOCK_NAMES.join(', ') + ' — plain ES ' +
+      'modules that import nothing and style themselves from the CSS variables already ' +
+      'in styles.css. For a React app: ' + BLOCK_NAMES.join(', ') + ' — built on the ' +
+      'shadcn components already in the starter. ALWAYS reach for these before writing a ' +
+      'list, a filter row, a store, a dialog or a table by hand: they already handle the ' +
+      'keyboard, the empty state, small screens and the cases that get skipped, and every ' +
+      'one you use is a hundred lines you do not have to type. Call it with no name to ' +
+      'see what each is for.',
     parameters: {
       type: 'object',
       properties: {
-        name: str('Which block, e.g. "data-table". Omit to list them.'),
+        name: str(`Which block, e.g. "${ALL_BLOCK_NAMES[0]}". Omit to list the ones this app can use.`),
         folder: str('The app folder to add it to. Defaults to the project root.'),
       },
     },
@@ -506,7 +528,7 @@ const run = {
 /** Tools that change the project or execute code. */
 export const MUTATING = new Set([
   'write_file', 'batch_write', 'edit_file', 'multi_edit', 'edit_files', 'rename_symbol', 'add_block',
-  'run_command', 'run_commands', 'deploy',
+  'run_command', 'run_commands', 'create_app', 'deploy',
 ]);
 
 /** Tools with no side effects, so several may run at the same time. */
@@ -519,7 +541,7 @@ export const WRITES = new Set([
 ]);
 
 /** Tools that change files on disk, which parallel workers take turns at. */
-export const FILE_WRITES = new Set(['write_file', 'batch_write', 'edit_file', 'multi_edit', 'edit_files', 'rename_symbol']);
+export const FILE_WRITES = new Set(['write_file', 'batch_write', 'edit_file', 'multi_edit', 'edit_files', 'rename_symbol', 'create_app']);
 
 // ---------------------------------------------------------------------------
 // Argument checking
@@ -532,6 +554,14 @@ export const FILE_WRITES = new Set(['write_file', 'batch_write', 'edit_file', 'm
  * wrong and can correct itself, instead of a TypeError thrown from somewhere
  * inside fs that means nothing to anybody.
  */
+/**
+ * Arguments whose tool reads more shapes than the schema advertises.
+ *
+ * Kept here rather than in the schema so the wire format stays exactly what
+ * the model is asked for — the leniency is ucode's, not part of the contract.
+ */
+const LENIENT = new Set(['create_app.files']);
+
 function check(name, args) {
   const schema = tools.find((t) => t.name === name).parameters;
   const problems = [];
@@ -552,10 +582,27 @@ function check(name, args) {
     }
     if (value === undefined || value === null) continue;
 
-    const actual = Array.isArray(value) ? 'array' : typeof value;
+    let actual = Array.isArray(value) ? 'array' : typeof value;
     const wanted = spec.type === 'integer' ? 'number' : spec.type;
     // A number sent as a string is close enough — the tool coerces it anyway.
     if (wanted === 'number' && actual === 'string' && value.trim() !== '' && !Number.isNaN(Number(value))) continue;
+
+    // An array or object sent as a JSON string is the single most common way
+    // a model gets a nested argument wrong, and it is one every model makes
+    // sometimes. Rejecting it costs a whole round trip to be told something
+    // that could simply be read: parse it and carry on.
+    if ((wanted === 'array' || wanted === 'object') && actual === 'string') {
+      try {
+        const parsed = JSON.parse(value);
+        const kind = Array.isArray(parsed) ? 'array' : typeof parsed;
+        if (kind === wanted || LENIENT.has(`${name}.${key}`)) { args[key] = parsed; actual = kind; }
+      } catch { /* not JSON either — the message below is the right answer */ }
+    }
+
+    // A list of files written as a { path: contents } map. The tool reads it
+    // either way, so refusing it here would be a round trip spent on nothing.
+    if (wanted === 'array' && actual === 'object' && LENIENT.has(`${name}.${key}`)) continue;
+
     if (actual !== wanted) problems.push(`"${key}" should be ${spec.type} but was ${actual}`);
   }
 
@@ -649,7 +696,8 @@ export function describe(name, args = {}) {
       // HTML app announced itself as Next.js, which is a line that is simply
       // untrue on screen while the opposite happens on disk.
       return `Creating ${clip(args.name || args.folder, 30)} from the ` +
-        `${args.template === 'plain-html' ? 'HTML' : 'Next.js'} starter`;
+        `${args.template === 'next-shadcn' ? 'Next.js' : 'HTML'} starter` +
+        `${args.files?.length ? ` with ${args.files.length} file${args.files.length === 1 ? '' : 's'}` : ''}`;
     case 'look_at_app':
       return `Looking at ${clip(args.url, 40)} on a phone and a desktop`;
     case 'web_search':

package/src/tools/scaffold.js

@@ -15,6 +15,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { ToolFailure } from '../core/failure.js';
 import { resolveIn, guard, result } from './shared.js';
+import { batchWrite } from './files.js';
 import { packageJsonWritten, installIn } from './shell.js';
 import { restore, populate } from './cache.js';
 
@@ -28,6 +29,44 @@ const TEXT = /\.(?:json|md|mjs|css|html|jsx?|tsx?)$/i;
 
 export const TEMPLATE_NAMES = ['next-shadcn', 'plain-html'];
 
+/**
+ * Which of a starter's files come back inside the result, in full.
+ *
+ * Reading a file ucode just copied is a whole round trip spent learning what
+ * it already had on disk, and a round trip is ten to forty seconds. The
+ * three-file starter is small enough to hand over outright; the Next.js one
+ * is a hundred files and its guide has to do that job instead.
+ */
+const SHOW_BACK = { 'plain-html': ['index.html', 'styles.css', 'app.js'] };
+
+/**
+ * The files argument, however it was written.
+ *
+ * A list of `{ path, content }` is what the schema asks for, and it is what
+ * arrives most of the time. The rest of the time it is a JSON string, or a
+ * `{ "todo/app.js": "..." }` map, or the same list with the keys named
+ * something adjacent. Each of those, refused, is a round trip spent being
+ * told what could have been read — so they are all read.
+ */
+function normaliseFiles(files) {
+  let value = files;
+  if (typeof value === 'string') {
+    try { value = JSON.parse(value); } catch { return []; }
+  }
+  if (!value || typeof value !== 'object') return [];
+
+  const entries = Array.isArray(value)
+    ? value
+    : Object.entries(value).map(([path, content]) => ({ path, content }));
+
+  return entries.map((entry) => {
+    if (typeof entry !== 'object' || entry === null) return entry;
+    const path = entry.path ?? entry.file ?? entry.filename ?? entry.name;
+    const content = entry.content ?? entry.contents ?? entry.text ?? entry.body ?? entry.source;
+    return { ...entry, path, content };
+  });
+}
+
 /** What each starter is for, so the choice is made on purpose. */
 export const TEMPLATE_NOTES = {
   'next-shadcn': 'Next.js, TypeScript, Tailwind and shadcn/ui. For anything with routes, data or many components.',
@@ -63,14 +102,6 @@ async function copyTree(from, to, fill) {
   return copied;
 }
 
-/**
- * @param {object} o
- * @param {string} o.folder       new, empty folder for the app
- * @param {string} o.name         display name, e.g. "Stride"
- * @param {string} [o.description]
- * @param {string} [o.template]
- * @param {boolean} [o.install]   start the background install (tests turn it off)
- */
 /**
  * Give the new app its look: one of the hand-picked presets in the starter's
  * presets/ folder — a full light and dark palette and a font — written into
@@ -129,7 +160,21 @@ export async function applyDesign(appDir, design) {
   return preset;
 }
 
-export async function createApp({ folder, name, description, template = 'next-shadcn', design, install = true }) {
+/**
+ * Start an app, and — when the model passes them — write its files in the
+ * same call.
+ *
+ * @param {object} o
+ * @param {string} o.folder        new, empty folder for the app
+ * @param {string} o.name          display name, e.g. "Stride"
+ * @param {string} [o.description]
+ * @param {string} [o.template]    defaults to plain-html: nothing to install
+ * @param {string} [o.design]
+ * @param {{path: string, content: string}[]} [o.files]  the app itself, paths
+ *   relative to the project root, written straight over the starter's
+ * @param {boolean} [o.install]    start the background install (tests turn it off)
+ */
+export async function createApp({ folder, name, description, template = 'plain-html', design, files, install = true }) {
   if (!TEMPLATE_NAMES.includes(template)) {
     throw new ToolFailure({
       kind: 'bad_args',
@@ -139,6 +184,26 @@ export async function createApp({ folder, name, description, template = 'next-sh
     });
   }
 
+  // Every shape a model reaches for when handing over a set of files. Reading
+  // them all costs nothing; refusing them costs a round trip each, which is
+  // the whole reason this argument exists.
+  const given = normaliseFiles(files);
+
+  // Checked before anything is copied: a bad entry found halfway through
+  // would leave the folder created, and the retry would then be refused for
+  // already having files in it.
+  const bad = given.findIndex(
+    (f) => typeof f?.path !== 'string' || typeof f?.content !== 'string'
+  );
+  if (bad !== -1) {
+    throw new ToolFailure({
+      kind: 'bad_args',
+      attempted: 'creating an app',
+      failed: `Entry ${bad + 1} of "files" is missing "path" or "content" — both must be strings.`,
+      fix: 'Fix that entry and call create_app again. Nothing has been created yet.',
+    });
+  }
+
   const target = resolveIn(folder, 'create_app', 'folder');
   const attempted = `creating an app in ${target.show}`;
   if (target.show === '.') {
@@ -173,7 +238,7 @@ export async function createApp({ folder, name, description, template = 'next-sh
     __APP_DESCRIPTION__: plain(description) || display,
   };
 
-  const files = await copyTree(path.join(TEMPLATES, template), target.abs, fill);
+  const copied = await copyTree(path.join(TEMPLATES, template), target.abs, fill);
   // Next.js serves static files from public/; a plain page has no such place
   // and an empty folder in a three-file app is clutter.
   if (template !== 'plain-html') await fs.mkdir(path.join(target.abs, 'public'), { recursive: true });
@@ -202,9 +267,27 @@ export async function createApp({ folder, name, description, template = 'next-sh
 
   const guide = await fs.readFile(path.join(target.abs, 'TEMPLATE.md'), 'utf8').catch(() => '');
 
-  return result(
-    `Created ${target.show} from the ${template} starter — ${files.length} files, already known to build.\n` +
+  // The app's own files, written in this same call. Two round trips become
+  // one, and round trips are nearly all of the time a build takes.
+  const mine = given;
+  const wrote = mine.length ? await batchWrite({ files: mine }) : null;
+  const written = new Set(mine.map((f) => resolveIn(f.path, 'create_app', 'files').abs));
+
+  // The starter's own files, in full, so there is never a reason to read them
+  // back — and only the ones this call did not already write over. A read is
+  // another round trip to learn what ucode already knows.
+  const starter = [];
+  for (const rel of SHOW_BACK[template] ?? []) {
+    const abs = path.join(target.abs, rel);
+    if (written.has(abs)) continue;
+    const text = await fs.readFile(abs, 'utf8').catch(() => null);
+    if (text !== null) starter.push(`=== ${target.show}/${rel} ===\n${text}`);
+  }
+
+  const out = result(
+    `Created ${target.show} from the ${template} starter — ${copied.length} files, already known to build.\n` +
       (look ? `Design: the ${look.name} preset (${look.summary}), font ${look.fonts?.sans ?? 'Geist'}.\n` : '') +
+      (wrote ? `\nYour ${mine.length} file${mine.length === 1 ? '' : 's'}:\n${wrote.content}\n` : '') +
       (linked
         ? `Its packages are already in place (${linked.toLocaleString()} files, linked from the starter cache) — ` +
           'nothing to install: build and run straight away.\n'
@@ -215,7 +298,14 @@ export async function createApp({ folder, name, description, template = 'next-sh
       (needsInstall
         ? `Run this app's commands with cwd: "${target.show}" (npm run build, npm run dev).\n\n${guide}`
         : `Nothing to install and nothing to build: open ${target.show}/index.html directly, or serve the ` +
-          `folder with "python -m http.server 8000" if it fetches anything.\n\n${guide}`),
-    `${files.length} files${linked ? ' · packages ready' : install && needsInstall ? ' · installing in the background' : ''}`
+          `folder with "python -m http.server 8000" if it fetches anything.\n\n${guide}`) +
+      (starter.length
+        ? `\n\nThe starter's files, in full — they are below, so do not read them back:\n\n${starter.join('\n\n')}`
+        : ''),
+    `${copied.length} files${wrote ? ` · ${mine.length} written` : ''}` +
+      `${linked ? ' · packages ready' : install && needsInstall ? ' · installing in the background' : ''}`,
+    24_000
   );
+  if (wrote?.diff?.length) out.diff = wrote.diff;
+  return out;
 }

package/src/ui/plain.js

@@ -14,6 +14,7 @@ import chalk from 'chalk';
 import {
   theme, blue, sky, dim, boxTop, boxBottom, boxRow,
   BANNER, BANNER_WIDTH, SPINNER, clip, shortenPath, asLabel, padVis, visLen, planLine,
+  tidyReply, trimAnswer,
 } from './theme.js';
 import { formatDuration, doneLine } from './activity.js';
 import { renderer, render } from './markdown.js';
@@ -185,8 +186,9 @@ export class Plain {
     for (const line of lines) this.output.write(`    ${dim(line)}\n`);
   }
 
-  assistant(text) {
-    const out = render(this.md, text);
+  assistant(text, { closing = false } = {}) {
+    const body = closing ? trimAnswer(tidyReply(text)) : tidyReply(text);
+    const out = render(this.md, body);
     if (!out) return;
     this.stopSpinner();
     this.output.write(`\n${out}\n\n`);

package/src/ui/screen.js

@@ -39,7 +39,7 @@ import chalk from 'chalk';
 import {
   theme, blue, sky, deep, dim, edge, ADDED, REMOVED, BANNER, BANNER_WIDTH, SPINNER,
   boxTop, boxBottom, boxRow, visLen, padVis, clip, wrapAnsi,
-  shortenPath, asLabel, ensureColour, planLine, bare, narration, narrationMark, groupKind, groupLabel, groupTarget, runLine, planRows, tidyReply } from './theme.js';
+  shortenPath, asLabel, ensureColour, planLine, bare, narration, narrationMark, groupKind, groupLabel, groupTarget, runLine, planRows, tidyReply, trimAnswer } from './theme.js';
 import { FRAME_MS, fitActivity, shimmer, spinnerGlyph, formatDuration, doneLine, stepPaint } from './activity.js';
 import { renderer, render, polish } from './markdown.js';
 import { VERSION } from '../core/version.js';
@@ -254,11 +254,20 @@ export class Screen {
     this.render();
   }
 
-  assistant(text) {
+  /**
+   * The reply, at full strength, with room either side.
+   *
+   * `closing` says this is the last thing the turn will say. It is then also
+   * the last thing left on screen, and what the whole session reads like
+   * afterwards, so it is cut to eight lines — see trimAnswer.
+   */
+  assistant(text, { closing = false } = {}) {
     if (!text?.trim()) return;
+    const body = closing ? trimAnswer(tidyReply(text)) : tidyReply(text);
+    if (!body.trim()) return;
     this.endRun();
     this.add('');
-    this.add(render(this.md, tidyReply(text)));
+    this.add(render(this.md, body));
     this.add('');
     this.render();
   }
@@ -529,7 +538,7 @@ export class Screen {
    * rather than an answer, in which case one short line folds down into the
    * status line it was always meant to be.
    */
-  streamEnd({ asNarration = false } = {}) {
+  streamEnd({ asNarration = false, closing = false } = {}) {
     if (this.streamAt === undefined) return '';
     const text = this.streamBuf;
     this.lines.length = this.streamAt;
@@ -537,7 +546,7 @@ export class Screen {
     this.streamBuf = '';
 
     if (asNarration && isLabel(text)) this.narrate(text);
-    else if (text.trim()) this.assistant(text);
+    else if (text.trim()) this.assistant(text, { closing });
     else this.render();
     return text;
   }

package/src/ui/theme.js

@@ -395,7 +395,7 @@ export function runLine({ label, count = 1, targets = [], added = 0, removed = 0
  * taken out, is a colon pointing at nothing — which reads as the reply having
  * been cut off mid-thought. The lead-in goes with what it was leading to.
  */
-const LEAD_IN = /(?:^|\n)[^\n]{0,80}:[ \t]*\n+$/;
+const LEAD_IN = /(?:^|\n)[^\n]{0,80}:[ \t]*\n+$/;
 
 export function withoutCodeBlocks(text, keepLines = 4) {
   const FENCE = /```([A-Za-z0-9+-]*)\n([\s\S]*?)```/g;
@@ -411,26 +411,102 @@ export function withoutCodeBlocks(text, keepLines = 4) {
  * The reply as it should be read: no pasted code, and no sentence left
  * pointing at code that is no longer there.
  */
-/**
- * The reply as it should be read.
- *
- * A long pasted block goes, and so does the sentence that introduced it — a
- * colon pointing at nothing reads as the reply having been cut off. A short
- * block stays: three lines showing a command to run belong in an answer.
- */
-export function tidyReply(text, keepLines = 4) {
-  const MARK = "\u0000CUT\u0000";
-  const FENCE = new RegExp("```([A-Za-z0-9+-]*)\\n([\\s\\S]*?)```", "g");
-
-  const marked = String(text ?? "").replace(FENCE, (all, lang, body) => {
-    const rows = body.replace(new RegExp("\\n+$"), "").split("\n");
-    return rows.length <= keepLines ? all : MARK;
-  });
-
-  const leadIn = new RegExp("(?:^|\\n)[^\\n]{0,80}:[ \t]*\\n+" + MARK, "g");
-  return marked
-    .replace(leadIn, "\n")
-    .split(MARK).join("")
-    .replace(new RegExp("\\n{3,}", "g"), "\n\n")
-    .trim();
-}
+/**
+ * The reply as it should be read.
+ *
+ * A long pasted block goes, and so does the sentence that introduced it — a
+ * colon pointing at nothing reads as the reply having been cut off. A short
+ * block stays: three lines showing a command to run belong in an answer.
+ */
+export function tidyReply(text, keepLines = 4) {
+  const MARK = "\u0000CUT\u0000";
+  const FENCE = new RegExp("```([A-Za-z0-9+-]*)\\n([\\s\\S]*?)```", "g");
+
+  const marked = String(text ?? "").replace(FENCE, (all, lang, body) => {
+    const rows = body.replace(new RegExp("\\n+$"), "").split("\n");
+    return rows.length <= keepLines ? all : MARK;
+  });
+
+  const leadIn = new RegExp("(?:^|\\n)[^\\n]{0,80}:[ \t]*\\n+" + MARK, "g");
+  return marked
+    .replace(leadIn, "\n")
+    .split(MARK).join("")
+    .replace(new RegExp("\\n{3,}", "g"), "\n\n")
+    .trim();
+}
+
+/**
+ * The closing message, cut to what a terminal can take.
+ *
+ * A model that finishes a build by walking back through the request — every
+ * feature ticked off, every file listed — leaves that as the last thing on
+ * screen, and the whole session then reads like a status report. Eight lines
+ * is the whole of it: what it is, and how to try it.
+ *
+ * What goes: an opening that reads the request back, and the middle of a list
+ * too long to be worth reading. What stays: the first lines, the line that
+ * admits something is unfinished, and the line naming a file or a command —
+ * the two the user actually acts on, and both of them live at the end.
+ */
+export const ANSWER_LINES = 8;
+const ANSWER_ROOM = 600;   // eight wrapped lines of prose, for a reply with no line breaks in it
+
+const RESTATED = /^(?:you (?:asked|wanted|requested|said)\b|the (?:request|task|ask)\b|as (?:you )?requested\b|here(?:'s| is) what (?:you asked|i)\b|to (?:summarise|summarize|recap)\b|(?:request|task|summary|recap|overview)\s*:)/i;
+const CAVEAT = /\b(?:however|failed|couldn't|could not|cannot|can't|didn't|did not|isn't|is not|doesn't|does not|not (?:yet|wired|working|done|implemented)|missing|unfinished|except)\b/i;
+const ACTIONABLE = /\b(?:open|run|serve|visit|try|start|npm|npx|node|pnpm|yarn)\b|https?:\/\/|\.(?:html?|css|jsx?|tsx?|md|json|py|rs|go)\b/i;
+const BULLET = /^\s*(?:[-*•>]|\d+[.)]|[✓✔✅☑])\s+/;
+
+export function trimAnswer(text, max = ANSWER_LINES) {
+  const all = String(text ?? '').replace(/\r/g, '').split('\n');
+
+  let start = 0;
+  while (start < all.length && (!all[start].trim() || RESTATED.test(all[start].trim()))) start++;
+  const rows = all.slice(start);
+
+  const body = rows.map((row, i) => ({ row, i })).filter((r) => r.row.trim());
+  if (!body.length) return '';
+
+  let kept;
+  if (body.length <= max) {
+    kept = body.map((r) => r.i);
+  } else {
+    // Searched from the end: the caveat and the how-to-try-it line are the
+    // last things written, and they are the two worth pulling out of the part
+    // being dropped.
+    const tail = body.slice(Math.max(1, max - 2));
+    const pick = (re) => [...tail].reverse().find((r) => re.test(r.row))?.i;
+    const rescued = [...new Set([pick(CAVEAT), pick(ACTIONABLE)])].filter((i) => i !== undefined);
+    const head = body.slice(0, max - rescued.length).map((r) => r.i);
+    kept = [...new Set([...head, ...rescued])].sort((a, b) => a - b);
+  }
+
+  const out = [];
+  let previous = -1;
+  for (const i of kept) {
+    if (previous >= 0 && i > previous + 1) out.push('');   // a gap in the middle is a paragraph break
+    // A line lifted out of a list is no longer in one.
+    out.push(previous >= 0 && i > previous + 1 ? rows[i].replace(BULLET, '') : rows[i]);
+    previous = i;
+  }
+
+  return withinRoom(out.join('\n').replace(/\n{3,}/g, '\n\n').trim());
+}
+
+/**
+ * One long paragraph is one line and fills the screen anyway. Whole sentences
+ * only: a reply cut mid-clause reads as a crash rather than as an ending.
+ */
+function withinRoom(text, room = ANSWER_ROOM) {
+  if (text.length <= room) return text;
+
+  const parts = text.split(/(?<=[.!?])(\s+)/);
+  let out = '';
+  let sentences = 0;
+  for (let i = 0; i < parts.length; i += 2) {
+    const next = out + parts[i] + (parts[i + 1] ?? '');
+    if (sentences >= 2 && next.trimEnd().length > room) break;
+    out = next;
+    sentences++;
+  }
+  return (out.trim() || text.slice(0, room)).trim();
+}