ucode-agent 1.26.1 → 1.27.0

package/src/core/skills.js

@@ -1,165 +1,189 @@
-/**
- * skills.js — instruction packs, disclosed progressively.
- *
- * A skill is a folder holding a SKILL.md: YAML frontmatter, then the
- * instructions. Only names and one-line descriptions go into the system
- * prompt; a body is pulled into the conversation the moment it is wanted. The
- * base prompt therefore stays the same size whether there are three skills or
- * thirty.
- *
- * Two ways a body gets loaded:
- *
- *   the model asks for it, with the load_skill tool; or
- *   the frontmatter says `auto:` and one of those words is in the request,
- *   in which case it is already loaded before the model takes its first step.
- *
- * The second one exists because the first one is a judgement call, and a model
- * in a hurry to be helpful skips judgement calls. Design quality is not
- * something to find out was skipped after the app is built.
- *
- * Skills are read from two places, the project first so a repo can override a
- * built-in of the same name:
- *   <cwd>/.ucode/skills/<name>/SKILL.md
- *   <install dir>/skills/<name>/SKILL.md
- */
-
-import { promises as fs } from 'node:fs';
-import path, { dirname } from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-const HERE = dirname(fileURLToPath(import.meta.url));
-
-export const BUILTIN_DIR = path.join(HERE, '..', '..', 'skills');
-
-export function projectDir(cwd = process.cwd()) {
-  return path.join(cwd, '.ucode', 'skills');
-}
-
-/** Enough YAML for `key: value`, quoted or bare. Skills are not config files. */
-export function parseSkill(text, source) {
-  const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(text.replace(/^/, ''));
-  if (!match) {
-    return { error: `${source} has no frontmatter — it must start with a --- line.` };
-  }
-
-  const meta = {};
-  for (const line of match[1].split(/\r?\n/)) {
-    const kv = /^([A-Za-z_][\w-]*)\s*:\s*(.*)$/.exec(line.trim());
-    if (!kv) continue;
-    let value = kv[2].trim();
-    if ((value.startsWith('"') && value.endsWith('"')) ||
-        (value.startsWith("'") && value.endsWith("'"))) {
-      value = value.slice(1, -1);
-    }
-    meta[kv[1]] = value;
-  }
-
-  if (!meta.name) return { error: `${source} frontmatter has no "name".` };
-  if (!meta.description) return { error: `${source} frontmatter has no "description".` };
-
-  return {
-    skill: {
-      name: meta.name,
-      description: meta.description,
-      // Words that pull this skill in before the model has said anything.
-      triggers: (meta.auto ?? '')
-        .split(',')
-        .map((t) => t.trim().toLowerCase())
-        .filter(Boolean),
-      body: match[2].trim(),
-      source,
-    },
-  };
-}
-
-async function readDir(dir) {
-  const skills = [];
-  const problems = [];
-
-  let entries;
-  try {
-    entries = await fs.readdir(dir, { withFileTypes: true });
-  } catch {
-    return { skills, problems }; // no skills directory is a normal state
-  }
-
-  for (const entry of entries) {
-    if (!entry.isDirectory()) continue;
-    const file = path.join(dir, entry.name, 'SKILL.md');
-    let text;
-    try {
-      text = await fs.readFile(file, 'utf8');
-    } catch (err) {
-      if (err.code !== 'ENOENT') problems.push(`${file} could not be read: ${err.message}`);
-      continue;
-    }
-    const { skill, error } = parseSkill(text, file);
-    if (error) problems.push(error);
-    else skills.push(skill);
-  }
-
-  return { skills, problems };
-}
-
-/**
- * Every available skill, project ones shadowing built-ins by name.
- * `problems` rides along non-enumerably for the UI to report.
- */
-export async function loadSkills({ cwd = process.cwd() } = {}) {
-  const builtin = await readDir(BUILTIN_DIR);
-  const project = await readDir(projectDir(cwd));
-
-  const byName = new Map();
-  for (const s of builtin.skills) byName.set(s.name, s);
-  for (const s of project.skills) byName.set(s.name, s);
-
-  const skills = [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
-  Object.defineProperty(skills, 'problems', {
-    value: [...builtin.problems, ...project.problems],
-    enumerable: false,
-  });
-  return skills;
-}
-
-/** The system-prompt block: names and descriptions, never bodies. */
-export function catalogue(skills) {
-  if (!skills.length) return '';
-  return skills.map((s) => `- ${s.name}: ${s.description}`).join('\n');
-}
-
-export function findSkill(skills, name) {
-  const wanted = String(name ?? '').trim().toLowerCase();
-  return skills.find((s) => s.name.toLowerCase() === wanted);
-}
-
-/**
- * Which skills this request should arrive with already loaded.
- *
- * A trigger matches on a word boundary, so "app" fires on "build me an app"
- * but not on "happy". Multi-word triggers are matched as phrases.
- */
-export function autoLoadFor(skills, text) {
-  const request = String(text ?? '').toLowerCase();
-  if (!request.trim()) return [];
-
-  return skills.filter((skill) =>
-    skill.triggers.some((trigger) => {
-      const escaped = trigger.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-      return new RegExp(`(^|[^a-z0-9])${escaped}([^a-z0-9]|$)`, 'i').test(request);
-    })
-  );
-}
-
-/** How a body enters the conversation. */
-export function skillMessage(skill, { automatic = false } = {}) {
-  const why = automatic
-    ? `The "${skill.name}" skill was loaded automatically because this request is the kind it covers.`
-    : `The "${skill.name}" skill was loaded for this task.`;
-  return {
-    role: 'system',
-    content:
-      `${why} Follow it — it outranks your defaults, and it is not optional.\n\n` +
-      `--- BEGIN SKILL: ${skill.name} ---\n${skill.body}\n--- END SKILL ---`,
-    skill: skill.name,
-  };
-}
+/**
+ * skills.js — instruction packs, disclosed progressively.
+ *
+ * A skill is a folder holding a SKILL.md: YAML frontmatter, then the
+ * instructions. Only names and one-line descriptions go into the system
+ * prompt; a body is pulled into the conversation the moment it is wanted. The
+ * base prompt therefore stays the same size whether there are three skills or
+ * thirty.
+ *
+ * Two ways a body gets loaded:
+ *
+ *   the model asks for it, with the load_skill tool; or
+ *   the frontmatter says `auto:` and one of those words is in the request,
+ *   in which case it is already loaded before the model takes its first step.
+ *
+ * The second one exists because the first one is a judgement call, and a model
+ * in a hurry to be helpful skips judgement calls. Design quality is not
+ * something to find out was skipped after the app is built.
+ *
+ * A skill folder may also hold a DIGEST.md: the same rules, cut to the ones
+ * that are never worth skipping. That is what an automatic load sends, and it
+ * is a latency decision rather than a token one — the whole conversation is
+ * re-read by the provider on every single step, so four thousand tokens
+ * loaded on the word "app" is four thousand tokens re-read ten or twenty
+ * times before the app is finished. The full body stays one load_skill away
+ * for work that needs the depth.
+ *
+ * Skills are read from two places, the project first so a repo can override a
+ * built-in of the same name:
+ *   <cwd>/.ucode/skills/<name>/SKILL.md
+ *   <install dir>/skills/<name>/SKILL.md
+ * and beside either of them, an optional DIGEST.md.
+ */
+
+import { promises as fs } from 'node:fs';
+import path, { dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+export const BUILTIN_DIR = path.join(HERE, '..', '..', 'skills');
+
+export function projectDir(cwd = process.cwd()) {
+  return path.join(cwd, '.ucode', 'skills');
+}
+
+/** Enough YAML for `key: value`, quoted or bare. Skills are not config files. */
+export function parseSkill(text, source) {
+  const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(text.replace(/^/, ''));
+  if (!match) {
+    return { error: `${source} has no frontmatter — it must start with a --- line.` };
+  }
+
+  const meta = {};
+  for (const line of match[1].split(/\r?\n/)) {
+    const kv = /^([A-Za-z_][\w-]*)\s*:\s*(.*)$/.exec(line.trim());
+    if (!kv) continue;
+    let value = kv[2].trim();
+    if ((value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
+    meta[kv[1]] = value;
+  }
+
+  if (!meta.name) return { error: `${source} frontmatter has no "name".` };
+  if (!meta.description) return { error: `${source} frontmatter has no "description".` };
+
+  return {
+    skill: {
+      name: meta.name,
+      description: meta.description,
+      // Words that pull this skill in before the model has said anything.
+      triggers: (meta.auto ?? '')
+        .split(',')
+        .map((t) => t.trim().toLowerCase())
+        .filter(Boolean),
+      body: match[2].trim(),
+      source,
+    },
+  };
+}
+
+async function readDir(dir) {
+  const skills = [];
+  const problems = [];
+
+  let entries;
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true });
+  } catch {
+    return { skills, problems }; // no skills directory is a normal state
+  }
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const file = path.join(dir, entry.name, 'SKILL.md');
+    let text;
+    try {
+      text = await fs.readFile(file, 'utf8');
+    } catch (err) {
+      if (err.code !== 'ENOENT') problems.push(`${file} could not be read: ${err.message}`);
+      continue;
+    }
+    const { skill, error } = parseSkill(text, file);
+    if (error) { problems.push(error); continue; }
+    // The short form, if the skill has one. No frontmatter: it is the same
+    // skill, said in fewer words.
+    skill.digest = (await fs.readFile(path.join(dir, entry.name, 'DIGEST.md'), 'utf8').catch(() => '')).trim();
+    skills.push(skill);
+  }
+
+  return { skills, problems };
+}
+
+/**
+ * Every available skill, project ones shadowing built-ins by name.
+ * `problems` rides along non-enumerably for the UI to report.
+ */
+export async function loadSkills({ cwd = process.cwd() } = {}) {
+  const builtin = await readDir(BUILTIN_DIR);
+  const project = await readDir(projectDir(cwd));
+
+  const byName = new Map();
+  for (const s of builtin.skills) byName.set(s.name, s);
+  for (const s of project.skills) byName.set(s.name, s);
+
+  const skills = [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+  Object.defineProperty(skills, 'problems', {
+    value: [...builtin.problems, ...project.problems],
+    enumerable: false,
+  });
+  return skills;
+}
+
+/** The system-prompt block: names and descriptions, never bodies. */
+export function catalogue(skills) {
+  if (!skills.length) return '';
+  return skills.map((s) => `- ${s.name}: ${s.description}`).join('\n');
+}
+
+export function findSkill(skills, name) {
+  const wanted = String(name ?? '').trim().toLowerCase();
+  return skills.find((s) => s.name.toLowerCase() === wanted);
+}
+
+/**
+ * Which skills this request should arrive with already loaded.
+ *
+ * A trigger matches on a word boundary, so "app" fires on "build me an app"
+ * but not on "happy". Multi-word triggers are matched as phrases.
+ */
+export function autoLoadFor(skills, text) {
+  const request = String(text ?? '').toLowerCase();
+  if (!request.trim()) return [];
+
+  return skills.filter((skill) =>
+    skill.triggers.some((trigger) => {
+      const escaped = trigger.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+      return new RegExp(`(^|[^a-z0-9])${escaped}([^a-z0-9]|$)`, 'i').test(request);
+    })
+  );
+}
+
+/**
+ * How a body enters the conversation.
+ *
+ * `short` sends the digest instead of the whole skill, when the skill has
+ * one. Everything in the digest is a rule; what is missing is the worked
+ * examples and the long way round, and load_skill fetches those.
+ */
+export function skillMessage(skill, { automatic = false, short = false } = {}) {
+  const digest = short && skill.digest ? skill.digest : null;
+  const why = automatic
+    ? `The "${skill.name}" skill was loaded automatically because this request is the kind it covers.`
+    : `The "${skill.name}" skill was loaded for this task.`;
+  return {
+    role: 'system',
+    content:
+      `${why} Follow it — it outranks your defaults, and it is not optional.\n\n` +
+      `--- BEGIN SKILL: ${skill.name} ---\n${digest ?? skill.body}\n--- END SKILL ---` +
+      (digest
+        ? `\n\nThat is the short form: every rule, none of the worked examples. For anything ` +
+          `beyond a straightforward screen, call load_skill("${skill.name}") for the whole thing.`
+        : ''),
+    skill: skill.name,
+    short: Boolean(digest),
+  };
+}

package/src/core/window.js

@@ -18,6 +18,22 @@ import { estimateConversation } from './provider.js';
 /** Start folding once the conversation passes this share of the window. */
 export const FOLD_AT = 0.75;
 
+/**
+ * ...or once it passes this many tokens, whichever comes first.
+ *
+ * A share of the window is a correctness threshold: it stops the request
+ * being rejected. It is the wrong measure for speed. These endpoints re-read
+ * the whole conversation on every step and none of them cache it, so a
+ * hundred thousand tokens is a hundred thousand tokens re-read ten times
+ * before the app is finished — and on a million-token model, three quarters
+ * of the window is a build that has been crawling for an hour by the time
+ * anything is folded.
+ *
+ * Folding costs one model call. Past this size, that call has already paid
+ * for itself in the steps that follow it.
+ */
+export const FOLD_TOKENS = Number(process.env.UCODE_FOLD_TOKENS) || 80_000;
+
 /** After folding, the verbatim tail may occupy this share of the window. */
 export const KEEP = 0.4;
 
@@ -32,7 +48,12 @@ export function usage(messages, limit) {
 }
 
 export function tooBig(messages, limit) {
-  return usage(messages, limit).used > limit * FOLD_AT;
+  return usage(messages, limit).used > foldAbove(limit);
+}
+
+/** The size at which folding starts: whichever of the two rules bites first. */
+export function foldAbove(limit) {
+  return Math.min(limit * FOLD_AT, FOLD_TOKENS);
 }
 
 /**
@@ -71,7 +92,11 @@ function cutPoint(messages, budget) {
 export async function fold(messages, { limit, summarize }) {
   if (!tooBig(messages, limit)) return { messages, folded: false };
 
-  const cut = cutPoint(messages, limit * KEEP);
+  // Half the size that triggered the fold, so there is room to work before
+  // the next one. Sized off the same absolute rule, or a fold on a
+  // million-token model would keep a tail that is instantly too big again and
+  // summarize on every single step.
+  const cut = cutPoint(messages, Math.min(limit * KEEP, foldAbove(limit) / 2));
   const older = messages.slice(0, cut);
   const recent = messages.slice(cut);
 

package/src/tools/blocks.js

@@ -6,10 +6,14 @@
  * that it cannot do better, it is that doing better costs steps and attention
  * that belong to the thing being built.
  *
- * These are the parts every app needs, written once and carefully: a shell, a
- * page header, an empty state, a table, a row of stats. They are copied into
- * the app as ordinary source files for the model to edit, not imported from a
- * library it cannot change.
+ * It also costs time in the plainest sense. Typing is the slowest part of a
+ * build — a few thousand tokens at forty a second — so a list, a filter row
+ * and a store that arrive written are a minute the user does not wait.
+ *
+ * Two sets, because the two starters have nothing in common: React and shadcn
+ * components for next-shadcn, and plain ES modules with no imports at all for
+ * plain-html. Which one you get is decided by the app the block is going into,
+ * not by an argument the model has to remember.
  */
 
 import { promises as fs } from 'node:fs';
@@ -49,55 +53,141 @@ export const CATALOGUE = {
   },
 };
 
+/**
+ * The same idea for a page with no build step: plain ES modules that import
+ * nothing, style themselves from the starter's CSS variables, and are ordinary
+ * files the moment they land.
+ */
+export const PLAIN_CATALOGUE = {
+  'item-list': {
+    what: 'A list of things you can add, tick off, rename and remove — a to-do list, a shopping list, saved items. Keyboard throughout, empty state, a count.',
+    exports: 'ItemList',
+    use: `const list = ItemList({
+  items: store.state.items,
+  onChange: (items) => store.set({ items }),
+  placeholder: 'Add a task',
+});
+document.querySelector('#app').append(list.el);`,
+  },
+  'filter-bar': {
+    what: 'A row of filters — All / Active / Done — as real buttons in a labelled group, one tab stop, arrow keys between them.',
+    exports: 'FilterBar',
+    use: `const filters = FilterBar({
+  options: [{ value: 'all', label: 'All' }, { value: 'active', label: 'Active' }],
+  value: 'all',
+  onChange: (value) => { state.filter = value; render(); },
+});`,
+  },
+  store: {
+    what: 'State in one place, saved to localStorage, and the same in every open tab. Survives private mode, a full quota and a value written by an older version.',
+    exports: 'createStore',
+    use: `const store = createStore('tide', { items: [], filter: 'all' });
+store.subscribe(render);
+store.update((s) => ({ items: [...s.items, task] }));`,
+  },
+  modal: {
+    what: 'A dialog that behaves like one: Escape closes it, focus is trapped inside and returns to the opener. Built on the browser\'s own <dialog>.',
+    exports: 'Modal',
+    use: `const confirm = Modal({ title: 'Delete this?', danger: true, onConfirm: remove });
+document.body.append(confirm.el);
+button.addEventListener('click', () => confirm.open());`,
+  },
+  toast: {
+    what: 'A short message that appears, is read out by a screen reader, and goes away. Stacks, caps itself, pauses under the pointer.',
+    exports: 'toast',
+    use: `toast('Saved');
+toast.error('Could not reach the server');
+toast('Deleted', { action: { label: 'Undo', onClick: undo } });`,
+  },
+  'theme-toggle': {
+    what: 'Light and dark: follows the operating system until the user chooses, remembers the choice, and applies it before the first paint so nothing flashes.',
+    exports: 'ThemeToggle, applyTheme, currentTheme',
+    use: `applyTheme();                    // the first line of app.js
+header.append(ThemeToggle().el);`,
+  },
+};
+
 export const BLOCK_NAMES = Object.keys(CATALOGUE);
+export const PLAIN_BLOCK_NAMES = Object.keys(PLAIN_CATALOGUE);
+export const ALL_BLOCK_NAMES = [...new Set([...PLAIN_BLOCK_NAMES, ...BLOCK_NAMES])];
 
-const listing = () =>
-  BLOCK_NAMES.map((name) => `  ${name} — ${CATALOGUE[name].what}`).join('\n');
+const exists = (p) => fs.stat(p).then(() => true, () => false);
 
 /**
- * Copy a block into an app, or list what there is. The file lands in
- * src/components/blocks/ and is the app's to edit from then on.
+ * Which set this app takes.
+ *
+ * A page with an index.html and nothing to install is the plain starter; a
+ * folder with a package.json is React. Asked rather than argued about, so
+ * the model cannot pick the wrong one.
+ */
+async function kindOf(dir) {
+  if (await exists(path.join(dir, 'package.json'))) return 'react';
+  if (await exists(path.join(dir, 'index.html'))) return 'plain';
+  return 'react';
+}
+
+const listing = (catalogue) =>
+  Object.keys(catalogue).map((name) => `  ${name} — ${catalogue[name].what}`).join('\n');
+
+/**
+ * Copy a block into an app, or list what there is. React blocks land in
+ * src/components/blocks/, plain ones in blocks/, and either way the file is
+ * the app's to edit from then on.
  */
 export async function addBlock({ name, folder = '.' }) {
   const wanted = String(name ?? '').trim();
+  const target = resolveIn(folder || '.', 'add_block', 'folder');
+  const kind = await kindOf(target.abs);
+  const catalogue = kind === 'plain' ? PLAIN_CATALOGUE : CATALOGUE;
+  const names = Object.keys(catalogue);
 
   if (!wanted) {
     return result(
-      `Blocks you can add, with add_block({ name, folder }):\n\n${listing()}\n\n` +
-      'Each one is copied into the app as a source file you can then edit.',
-      `${BLOCK_NAMES.length} blocks`
+      `Blocks for ${target.show} (${kind === 'plain' ? 'a page with no build step' : 'React and shadcn'}), ` +
+      `with add_block({ name, folder }):\n\n${listing(catalogue)}\n\n` +
+      'Each one is copied in as a source file you can then edit.',
+      `${names.length} blocks`
     );
   }
 
-  if (!CATALOGUE[wanted]) {
+  if (!catalogue[wanted]) {
+    const other = kind === 'plain' ? CATALOGUE : PLAIN_CATALOGUE;
     throw new ToolFailure({
       kind: 'no_such_block',
       attempted: `adding the "${wanted}" block`,
-      failed: `There is no block called "${wanted}".`,
-      fix: `Pick one of: ${BLOCK_NAMES.join(', ')}. Call add_block with no name to see what each is for.`,
+      failed: other[wanted]
+        ? `"${wanted}" is a ${kind === 'plain' ? 'React' : 'plain-page'} block, and ${target.show} is ${kind === 'plain' ? 'a plain page' : 'a React app'}.`
+        : `There is no block called "${wanted}".`,
+      fix: `For ${target.show}, pick one of: ${names.join(', ')}. Call add_block with no name to see what each is for.`,
     });
   }
 
-  const target = resolveIn(folder || '.', 'add_block', 'folder');
   await guard(target, `add the ${wanted} block to ${target.abs}`);
 
-  const source = await fs.readFile(path.join(BLOCKS, `${wanted}.tsx`), 'utf8').catch(() => null);
+  const from = kind === 'plain'
+    ? path.join(BLOCKS, 'plain', `${wanted}.js`)
+    : path.join(BLOCKS, `${wanted}.tsx`);
+  const source = await fs.readFile(from, 'utf8').catch(() => null);
   if (source === null) {
     throw new ToolFailure({
       kind: 'block_missing',
       attempted: `adding the "${wanted}" block`,
       failed: `The ${wanted} block is listed but its file is not installed.`,
-      fix: 'Write the component by hand, or reinstall ucode.',
+      fix: 'Write it by hand, or reinstall ucode.',
     });
   }
 
-  const rel = path.join('src', 'components', 'blocks', `${wanted}.tsx`);
+  const rel = kind === 'plain'
+    ? path.join('blocks', `${wanted}.js`)
+    : path.join('src', 'components', 'blocks', `${wanted}.tsx`);
   const dest = path.join(target.abs, rel);
+  const importLine = kind === 'plain'
+    ? `import { ${catalogue[wanted].exports} } from './blocks/${wanted}.js';`
+    : `import { ${catalogue[wanted].exports} } from "@/components/blocks/${wanted}";`;
 
-  if (await fs.stat(dest).catch(() => null)) {
+  if (await exists(dest)) {
     return result(
-      `${rel} is already in ${target.show}; it has been left as it is so your edits survive.\n` +
-      `Import: import { ${CATALOGUE[wanted].exports.split(',')[0].trim()} } from "@/components/blocks/${wanted}";`,
+      `${rel} is already in ${target.show}; it has been left as it is so your edits survive.\n${importLine}`,
       'already there'
     );
   }
@@ -105,13 +195,13 @@ export async function addBlock({ name, folder = '.' }) {
   await fs.mkdir(path.dirname(dest), { recursive: true });
   await fs.writeFile(dest, source, 'utf8');
 
-  const first = CATALOGUE[wanted].exports.split(',')[0].trim();
+  const first = catalogue[wanted].exports.split(',')[0].trim();
   return result(
-    `Added ${rel} to ${target.show}.\n\n` +
-    `import { ${CATALOGUE[wanted].exports} } from "@/components/blocks/${wanted}";\n\n` +
-    `${CATALOGUE[wanted].use}\n\n` +
-    `It is an ordinary file now — edit it to suit the app rather than working around it. ` +
-    `It uses the shadcn components already in the starter, so nothing needs installing.`,
+    `Added ${rel} to ${target.show}.\n\n${importLine}\n\n${catalogue[wanted].use}\n\n` +
+    'It is an ordinary file now — edit it to suit the app rather than working around it. ' +
+    (kind === 'plain'
+      ? 'It imports nothing and styles itself from the CSS variables already in styles.css, so it works as it is.'
+      : 'It uses the shadcn components already in the starter, so nothing needs installing.'),
     `${first} added`
   );
 }