ucode-agent 1.39.0 → 1.41.0

package/README.md

@@ -27,7 +27,7 @@ corner:
          add a dark mode toggle that remembers the choice
 
 
-                                                                           v1.36.0
+                                                                           v1.41.0
 ```
 
 A light crosses the wordmark once as it opens, and the three lines under the box

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ucode-agent",
-  "version": "1.39.0",
+  "version": "1.41.0",
   "description": "ucode - a terminal coding agent that reads, edits and runs your code, on NVIDIA and Cohere models.",
   "type": "module",
   "main": "ucode.js",

package/skills/build-app/DIGEST.md

@@ -1,94 +1,121 @@
-# Building something from nothing — the short form
-
-The failure mode is not bad code. It is a folder of files that has never been
-run, handed over as if it works.
-
-## 1. Decide the shape before any file exists
-
-One line each: **what it does**, **the core loop** (the one path that must work
-perfectly), **the stack**, **the file list**.
-
-| Need | Choose |
-| --- | --- |
-| One page, no secrets, no server | `create_app` with `plain-html` |
-| Interactive client app, no secrets | `plain-html` still, unless it truly needs a build |
-| Pages plus a server, secrets, API routes, SEO | `create_app` with `next-shadcn` |
-| An API on its own | Node (Hono/Express) or Python (FastAPI) |
-
-Pick the smallest one that does the job and mean it: a tasks app, a
-calculator, a timer, a game, a visualisation — all one page. Next.js costs an
-install and a build, minutes the user waits through, and buys nothing an app
-with no server needs.
-
-## 2. Start from the starter — and finish in the same call
-
-`create_app` takes `files`, so for a one-page app the scaffold and the whole
-app are one call:
-
-```
-create_app({ folder: "tide", name: "Tide", files: [
-  { path: "tide/index.html", content: "…" },
-  { path: "tide/styles.css", content: "…" },
-  { path: "tide/app.js",     content: "…" },
-]})
-```
-
-Every round trip is ten to forty seconds of the user's time, so one call
-instead of four is most of how long the build takes.
-
-- `plain-html` is the default: three files, no install, no build. Its files
-  come back in full inside the result — **never read them back**.
-- `next-shadcn` installs in the background; commands in that folder wait for
-  it on their own, so start writing components at once. Re-tint `globals.css`
-  for the app's direction rather than shipping the slate default.
-- Never run `create-next-app` or `shadcn init`. Nothing you run has a
-  keyboard: every scaffolder needs its answers as flags up front.
-
-## 2b. Do not type what already exists
-
-`add_block` has the pieces every app needs, written for whichever starter this
-one uses: a list you can add to, tick off, rename and remove; a filter row; a
-localStorage store; a dialog; toasts; a theme toggle; a table; an empty state.
-Call it before writing any of those by hand. Each is a hundred lines you skip,
-and typing is the slowest part of a build — a page assembled from blocks is
-done minutes before the same page typed out. Call `add_block` with no name to
-see what fits this app.
-
-## 3. Structure
-
-One component per file, named for what it is, not a 600-line `page.tsx`. In
-Next.js: `src/app` (routes, `globals.css`, `api/<name>/route.ts`),
-`src/components/<feature>/`, `src/lib/` for outside services and schemas.
-Server components by default, `"use client"` only where it is interactive.
-Types at every boundary; parse external data rather than trusting its shape.
-
-## 4. Secrets and outside services
-
-- **A key never reaches the browser.** It lives in a server route. Anything
-  imported by a `"use client"` file ships to every visitor, including a
-  "hardcoded for now" key — put it in a server-only module and say where.
-- Every outbound call gets a timeout (`AbortSignal.timeout(60_000)`), a status
-  check, and an error that says what failed — surfaced as a real message,
-  never a silent `catch {}`.
-- Calling a model: ask for JSON and parse it defensively (extract the first
-  `{...}`, validate, clamp numbers), put the judgement rules in the prompt
-  explicitly, and make the route timeout longer than the model takes.
-
-## 5. Build order
-
-Skeleton and design tokens first, so everything after is styled correctly the
-first time; then the server route with the real integration; then the core
-loop UI wired to it; then every state — empty, loading, success, error,
-invalid input; then polish: motion, responsive, copy, title and metadata.
-
-## 6. Prove it works, then report
-
-`npm run build` type-checks and lints — a build that fails is not done. Start
-it (`npm run dev` backgrounds itself and returns the URL; do not start it
-twice), then `look_at_app` on every page. A clean build proves it compiles,
-not that it works. Fix what you find and check again.
-
-Done means: the core loop works end to end, no TODO, no placeholder copy, no
-dead buttons, no console errors, every async action has its states, secrets
-server-side, build passes. Then say what you built, how to run it, and — in
-one sentence — anything you did not finish or could not test.
+# Building something from nothing — the short form
+
+The failure mode is not bad code. It is a folder of files that has never been
+run, handed over as if it works.
+
+## 1. Decide the shape before any file exists
+
+One line each: **what it does**, **the core loop** (the one path that must work
+perfectly), **the stack**, **the file list**.
+
+| Need | Choose |
+| --- | --- |
+| One page, no secrets, no server | `create_app` with `plain-html` |
+| Interactive client app, no secrets | `plain-html` still, unless it truly needs a build |
+| Pages plus a server, secrets, API routes, SEO | `create_app` with `next-shadcn` |
+| An API on its own | Node (Hono/Express) or Python (FastAPI) |
+
+Pick the smallest one that does the job and mean it: a tasks app, a
+calculator, a timer, a game, a visualisation — all one page. Next.js costs an
+install and a build, minutes the user waits through, and buys nothing an app
+with no server needs.
+
+## 2. Start from the starter — and finish in the same call
+
+`create_app` takes `files`, so for a one-page app the scaffold and the whole
+app are one call:
+
+```
+create_app({ folder: "tide", name: "Tide", files: [
+  { path: "tide/index.html", content: "…" },
+  { path: "tide/styles.css", content: "…" },
+  { path: "tide/app.js",     content: "…" },
+]})
+```
+
+Every round trip is ten to forty seconds of the user's time, so one call
+instead of four is most of how long the build takes.
+
+- `plain-html` is the default: three files, no install, no build. Its files
+  come back in full inside the result — **never read them back**.
+- `next-shadcn` installs in the background; commands in that folder wait for
+  it on their own, so start writing components at once. Re-tint `globals.css`
+  for the app's direction rather than shipping the slate default.
+- Never run `create-next-app` or `shadcn init`. Nothing you run has a
+  keyboard: every scaffolder needs its answers as flags up front.
+
+## 2a. Paths in `files` are not the paths in the page
+
+The two are relative to different things, and getting them confused is the
+commonest way a finished build comes up as bare markup. `files` paths are
+relative to the **project root**, so they carry the app folder. A link inside a
+page is relative to **that page**, so it must not.
+
+```
+create_app({ folder: "tide", name: "Tide", files: [
+  { path: "tide/index.html", content: "... <link rel=stylesheet href=\"styles.css\">
+                                            <script type=module src=\"app.js\"></script> ..." },
+  { path: "tide/styles.css", content: "..." },
+  { path: "tide/app.js",     content: "..." },
+]})
+```
+
+Wrong, and it 404s: `href="tide/styles.css"` inside `tide/index.html` — the
+browser resolves that to `tide/tide/styles.css`, so no stylesheet and no script
+load, and the page is unstyled markup with dead buttons.
+
+## 2b. Look before you create
+
+`create_app` refuses a folder that already has something in it unless you pass
+the app in `files` — and a folder you half-made on an earlier attempt counts.
+One `list_dir` in front of it costs a second and tells you whether you are
+starting or resuming. The same goes for any command that makes a directory.
+
+## 2c. Do not type what already exists
+
+`add_block` has the pieces every app needs, written for whichever starter this
+one uses: a list you can add to, tick off, rename and remove; a filter row; a
+localStorage store; a dialog; toasts; a theme toggle; a table; an empty state.
+Call it before writing any of those by hand. Each is a hundred lines you skip,
+and typing is the slowest part of a build — a page assembled from blocks is
+done minutes before the same page typed out. Call `add_block` with no name to
+see what fits this app.
+
+## 3. Structure
+
+One component per file, named for what it is, not a 600-line `page.tsx`. In
+Next.js: `src/app` (routes, `globals.css`, `api/<name>/route.ts`),
+`src/components/<feature>/`, `src/lib/` for outside services and schemas.
+Server components by default, `"use client"` only where it is interactive.
+Types at every boundary; parse external data rather than trusting its shape.
+
+## 4. Secrets and outside services
+
+- **A key never reaches the browser.** It lives in a server route. Anything
+  imported by a `"use client"` file ships to every visitor, including a
+  "hardcoded for now" key — put it in a server-only module and say where.
+- Every outbound call gets a timeout (`AbortSignal.timeout(60_000)`), a status
+  check, and an error that says what failed — surfaced as a real message,
+  never a silent `catch {}`.
+- Calling a model: ask for JSON and parse it defensively (extract the first
+  `{...}`, validate, clamp numbers), put the judgement rules in the prompt
+  explicitly, and make the route timeout longer than the model takes.
+
+## 5. Build order
+
+Skeleton and design tokens first, so everything after is styled correctly the
+first time; then the server route with the real integration; then the core
+loop UI wired to it; then every state — empty, loading, success, error,
+invalid input; then polish: motion, responsive, copy, title and metadata.
+
+## 6. Prove it works, then report
+
+`npm run build` type-checks and lints — a build that fails is not done. Start
+it (`npm run dev` backgrounds itself and returns the URL; do not start it
+twice), then `look_at_app` on every page. A clean build proves it compiles,
+not that it works. Fix what you find and check again.
+
+Done means: the core loop works end to end, no TODO, no placeholder copy, no
+dead buttons, no console errors, every async action has its states, secrets
+server-side, build passes. Then say what you built, how to run it, and — in
+one sentence — anything you did not finish or could not test.

package/src/core/loop.js

@@ -103,6 +103,9 @@ const SILENT = new Set(['update_plan']);
 const MAX_FIX_ROUNDS = 3;
 
 /** Files worth checking after they change. */
+/** A file with a page in it — something a browser can be pointed at. */
+const PAGE = /\.(?:html?|tsx|jsx)$/i;
+
 const CHECKABLE = /\.(?:[cm]?[jt]sx?|py|html?)$/i;
 
 /** Where TypeScript keeps what it learned, so the next check is a quick one. */
@@ -631,6 +634,24 @@ function systemPrompt({ cwd, skills, mode, check, map, memory }) {
     '',
 
     '',
+    '',
+    'NEVER ASSUME A LIBRARY IS THERE. Not React, not lodash, not a component kit,',
+    'however well known it is. Check what this project already uses before you reach',
+    'for it: its package.json, the file next to the one you are writing, what the',
+    'starter actually shipped. The plain-html starter has no build step and no',
+    'packages at all, so JSX, TypeScript and bare module imports are not syntax it',
+    'can run — a JSX tag in a plain module is a page that renders nothing and one',
+    'unexpected-token error in the console. Write what the project can execute.',
+    '',
+    'CALL TOOLS TOGETHER WHEN THEY DO NOT DEPEND ON EACH OTHER. Several can go in',
+    'one reply and they run at the same time. Six files is one read_files in one',
+    'message, never six read_file calls in six — each of those is a round trip you',
+    'and the user sit through. Same for independent searches, same for commands',
+    'that do not feed each other.',
+    '',
+    'POINT AT CODE AS file:line. The filter is built in src/app.js:42 — not in the',
+    'app file somewhere near the filter. One of those the reader can open; the',
+    'other they have to go hunting from.',
     'Before you guess at an API, ask: type_of gives the exact signature from the',
     'TypeScript this project has installed, and find_symbol says where something is declared without',
     'reading five files to find it. Rename with rename_symbol rather than edit_file — a',
@@ -1082,6 +1103,8 @@ export class Agent {
     // /undo can put the whole turn back.
     beginTurn();
     this.lookedThisTurn = false;
+    this.reads = new Map();
+    this.declines = 0;
     forgetReviews(); // a new request: its apps get a fresh design review
     const images = await this.attachImages(input);
     this.push(images.length
@@ -1641,7 +1664,14 @@ export class Agent {
     // 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 ?? '')) {
+      // The pages stay. A build proves the project compiles, which is not the
+      // same claim as the page working — and clearing everything here meant a
+      // Next.js app, where a passing `npm run build` is part of every turn,
+      // never reached the look at all. That is the one check that opens the
+      // thing and presses its buttons, skipped on the whole framework.
+      const pages = [...(this.sinceCheck ?? [])].filter((f) => PAGE.test(f));
       this.sinceCheck?.clear();
+      for (const p of pages) this.sinceCheck?.add(p);
     }
     if (!QUIET.has(call.name)) this.ui.toolResult(out.summary);
     // The change as its two numbers, not as a copy of the file. The diff rows
@@ -1670,11 +1700,32 @@ export class Agent {
     // user made, and anything that actually failed, still shows.
     if (err instanceof Declined) this.ui.toolFailed('declined');
     else if (err.kind !== 'bad_args') this.ui.toolFailed(`${err.kind}: ${err.failed}`);
+
+    // Declines that keep coming are not decisions, they are a wall.
+    //
+    // A traced build ran 250 steps and 32 minutes before dying on the step
+    // limit because every command it tried was declined — a piped session
+    // cannot answer "go ahead? [y/N]", so the answer is always no. The model
+    // read each refusal as being about that command, picked a different one,
+    // and was refused again. Nothing ever told it the refusals were the room
+    // rather than the request.
+    //
+    // Two are a person saying no to two things. The third is the wall, and it
+    // is worth naming, because the way out is to finish without commands
+    // rather than to keep hunting for one that is allowed.
+    this.declines = err instanceof Declined ? (this.declines ?? 0) + 1 : 0;
     this.push({
       role: 'tool',
       toolCallId: call.id,
       name: call.name,
-      content: err.forModel() + (err instanceof Declined ? '' : this.stuckNote(call, { err })),
+      content: err.forModel()
+        + (err instanceof Declined ? '' : this.stuckNote(call, { err }))
+        + (this.declines >= 3
+          ? '\n\nThat is the third command declined in a row. They are not being refused one by one — '
+            + 'nothing can be run in this session at all, and the next one will be declined too. '
+            + 'Stop trying to run things: finish the work with the files you have, and say plainly '
+            + 'in your reply which steps someone will need to run themselves.'
+          : ''),
     });
     return err.kind === 'bad_args';
   }
@@ -1705,6 +1756,34 @@ export class Agent {
       });
     }
 
+    // Reading the same unchanged file over and over.
+    //
+    // A traced build of a one-page app spent 53 of its 80 tool calls on
+    // read_file, most of them the same handful of files again and again — six
+    // seconds and a few thousand tokens each, for text that was already in the
+    // conversation. The prompt has asked it not to since 1.27; asking is not
+    // working, so the third read of a file nothing has written to since says
+    // so instead of sending the file a third time.
+    //
+    // Two reads are left alone: the first is the work, and the second is
+    // usually a fair re-check after an edit. Only the third is a loop. And it
+    // is keyed on the file being untouched since — the moment anything writes
+    // to it, the count starts again and a real re-read goes through.
+    if (call.name === 'read_file' && call.args?.path) {
+      const key = String(call.args.path);
+      const seen = (this.reads ??= new Map()).get(key) ?? 0;
+      if (seen >= 2 && !this.sinceCheck?.has(key)) {
+        this.reads.set(key, seen + 1);
+        return {
+          content: `You have already read ${key} ${seen} times this turn and nothing has written to it since, ` +
+          'so its contents are unchanged and already above. Use what is there. If you need a part ' +
+          'you have lost, say which and read the files you still need together in one read_files.',
+          summary: 'unchanged since you last read it',
+        };
+      }
+      this.reads.set(key, seen + 1);
+    }
+
     if (call.name === 'load_skill') return this.loadSkill(call.args?.name);
     if (call.name === 'update_plan') return this.updatePlan(call.args?.items);
     if (call.name === 'delegate') return this.delegate(call.args?.tasks);
@@ -2036,7 +2115,7 @@ export class Agent {
   async lookOnceThisTurn(root, changed) {
     if (this.lookedThisTurn) return null;
 
-    const pages = [...changed].filter((f) => /\.(?:html?|tsx|jsx)$/i.test(f));
+    const pages = [...changed].filter((f) => PAGE.test(f));
     if (!pages.length) return null;
     this.lookedThisTurn = true;
 
@@ -2056,7 +2135,12 @@ export class Agent {
       const html = pages.find((f) => /\.html?$/i.test(f));
       if (!html) return null;
       return await withStaticServer(path.dirname(path.resolve(root, html)), look);
-    } catch {
+    } catch (err) {
+      // Say so, quietly, rather than skipping in silence. A browser that will
+      // not start is a reason to carry on without the look — but a check that
+      // stops running and never mentions it is worse than one that was never
+      // written, because everything downstream still believes it ran.
+      this.ui.note(`could not open the app to check it: ${String(err?.failed ?? err?.message ?? err).split('\n')[0]}`);
       return null;
     }
   }

package/templates/plain-html/TEMPLATE.md

@@ -15,6 +15,21 @@ Open `index.html` in a browser, or serve the folder if the app fetches
 anything: `python -m http.server 8000`. There is nothing to install and
 nothing to compile, so a change is visible on refresh.
 
+## What this starter cannot run
+
+There is no build step, so there is no compiler to turn anything into browser
+JavaScript. That rules out, in `app.js` or any module it loads:
+
+- **JSX** — `render(<App />, root)` is a syntax error in a plain module. The
+  page renders nothing and the console says an unexpected token was found.
+- **TypeScript** — no types, no `interface`, no `as`.
+- **Bare imports** — `import React from "react"` has nowhere to resolve from.
+  Only relative paths (`./store.js`) and full URLs work.
+
+Write plain ES modules and DOM calls. If the app genuinely needs a framework,
+it needed `next-shadcn` instead, and that decision belongs before the first
+file, not after the page comes up blank.
+
 ## Conventions worth keeping
 
 - **One state object, one render.** Patching the DOM from several places is