ucode-agent 1.63.0 → 1.65.0

package/src/core/mcp.js

@@ -0,0 +1,337 @@
+/**
+ * mcp.js — tools from MCP servers: GitHub, docs, databases, whatever the user connects.
+ *
+ *   ~/.ucode/mcp.json          servers for every project
+ *   <project>/.ucode/mcp.json  servers for this one (asked about once, see settings.js)
+ *
+ *   { "servers": {
+ *       "context7": { "command": "npx", "args": ["-y", "@upstash/context7-mcp"] },
+ *       "github":   { "url": "https://api.githubcopilot.com/mcp/",
+ *                     "headers": { "Authorization": "Bearer ${GITHUB_TOKEN}" } } } }
+ *
+ * "mcpServers" is read too, so a block copied from another tool's docs works.
+ * ${NAME} in args, env and headers is taken from the environment, so a token
+ * never has to sit in the file.
+ *
+ * The protocol is JSON-RPC over a child's stdin and stdout, or over HTTP. The
+ * official SDK pulls in a web server framework to speak it, which every
+ * install of ucode would then download; the client half is this file.
+ */
+
+import { spawn } from 'node:child_process';
+import os from 'node:os';
+import path from 'node:path';
+import { readJson, writeJson } from './settings.js';
+import { VERSION } from './version.js';
+
+export const USER_MCP = path.join(os.homedir(), '.ucode', 'mcp.json');
+export const projectMcpFile = (cwd) => path.join(cwd, '.ucode', 'mcp.json');
+
+const PROTOCOL = '2025-06-18';
+const START_MS = 30_000;
+const CALL_MS = 120_000;
+const MAX_RESULT = 12_000;
+
+const expand = (value) => String(value ?? '').replace(/\$\{(\w+)\}/g, (_, name) => process.env[name] ?? '');
+const expandAll = (obj = {}) => Object.fromEntries(Object.entries(obj).map(([k, v]) => [k, expand(v)]));
+
+/** The servers a file lists, each { name, command?, args?, env?, url?, headers? }. */
+export async function readServers(file) {
+  const data = await readJson(file);
+  const servers = data.servers ?? data.mcpServers ?? {};
+  return Object.entries(servers)
+    .filter(([, s]) => s && typeof s === 'object' && (s.command || s.url) && s.disabled !== true)
+    .map(([name, s]) => ({ name, ...s }));
+}
+
+/** Add or replace one server in a config file. */
+export async function addServer(file, name, spec) {
+  const data = await readJson(file);
+  const key = data.mcpServers && !data.servers ? 'mcpServers' : 'servers';
+  await writeJson(file, { ...data, [key]: { ...(data[key] ?? {}), [name]: spec } });
+}
+
+/** Take a server out of a config file. Resolves to whether it was there. */
+export async function removeServer(file, name) {
+  const data = await readJson(file);
+  const key = data.servers?.[name] ? 'servers' : data.mcpServers?.[name] ? 'mcpServers' : null;
+  if (!key) return false;
+  const { [name]: _gone, ...rest } = data[key];
+  await writeJson(file, { ...data, [key]: rest });
+  return true;
+}
+
+/** A name a function call can carry: letters, digits, _ and -, at most 64. */
+export const toolName = (server, tool) =>
+  `${server}__${tool}`.replace(/[^A-Za-z0-9_-]/g, '_').replace(/^[^A-Za-z_]/, '_$&').slice(0, 64);
+
+const KEEP = new Set(['type', 'description', 'properties', 'required', 'items', 'enum', 'anyOf', 'nullable',
+  'minimum', 'maximum', 'minItems', 'maxItems', 'minLength', 'maxLength', 'title']);
+
+/**
+ * An MCP input schema in the subset Gemini accepts. Anything else in a schema
+ * ($schema, additionalProperties, $ref, formats other than date-time) gets the
+ * whole request refused, and one server's odd schema would take every other
+ * tool down with it.
+ */
+export function cleanSchema(schema, root = true) {
+  if (!schema || typeof schema !== 'object' || Array.isArray(schema)) {
+    return root ? { type: 'object', properties: {} } : { type: 'string' };
+  }
+  const out = {};
+  for (const [key, value] of Object.entries(schema)) {
+    if (!KEEP.has(key)) continue;
+    if (key === 'type' && Array.isArray(value)) {
+      const real = value.filter((t) => t !== 'null');
+      out.type = real[0] ?? 'string';
+      if (real.length < value.length) out.nullable = true;
+    } else if (key === 'properties' && value && typeof value === 'object') {
+      out.properties = Object.fromEntries(Object.entries(value).map(([k, v]) => [k, cleanSchema(v, false)]));
+    } else if (key === 'items') {
+      out.items = cleanSchema(Array.isArray(value) ? value[0] : value, false);
+    } else if (key === 'anyOf' && Array.isArray(value)) {
+      out.anyOf = value.map((v) => cleanSchema(v, false));
+    } else if (key === 'enum' && Array.isArray(value)) {
+      out.enum = value.filter((v) => typeof v === 'string');
+    } else {
+      out[key] = value;
+    }
+  }
+  if (schema.oneOf && !out.anyOf) out.anyOf = schema.oneOf.map((v) => cleanSchema(v, false));
+  if (schema.format === 'date-time') out.format = 'date-time';
+  if (out.enum && !out.enum.length) delete out.enum;
+  if (root || out.type === 'object' || out.properties) {
+    out.type = 'object';
+    out.properties ??= {};
+    if (Array.isArray(out.required)) out.required = out.required.filter((k) => k in out.properties);
+  } else if (!out.type && !out.anyOf) {
+    out.type = 'string';
+  }
+  return out;
+}
+
+/** One server's reply to a tools/call, as text for the model. */
+export function resultText(result) {
+  const parts = (result?.content ?? []).map((c) => {
+    if (c.type === 'text') return c.text;
+    if (c.type === 'resource') return c.resource?.text ?? `[resource ${c.resource?.uri ?? ''}]`;
+    if (c.type === 'resource_link') return `[${c.name ?? 'link'}: ${c.uri}]`;
+    return `[${c.type} not shown]`;
+  });
+  if (!parts.length && result?.structuredContent) parts.push(JSON.stringify(result.structuredContent, null, 2));
+  const text = parts.join('\n').trim() || '(the tool returned nothing)';
+  return text.length > MAX_RESULT ? `${text.slice(0, MAX_RESULT)}\n[cut at ${MAX_RESULT} characters]` : text;
+}
+
+/**
+ * Quote one argument for cmd.exe. Inside double quotes cmd treats & | < > ^
+ * as text; a quote is doubled, and % is broken up so no variable expands.
+ */
+const winQuote = (a) => (/^[\w./:=@\\-]+$/.test(a)
+  ? a
+  : `"${String(a).replace(/"/g, '""').replace(/%/g, '"%"')}"`);
+
+/** A server spoken to over its stdin and stdout, one JSON message per line. */
+class StdioLink {
+  constructor(spec, cwd) {
+    this.pending = new Map();
+    this.next = 1;
+    const args = (spec.args ?? []).map(expand);
+    const env = { ...process.env, ...expandAll(spec.env) };
+    // npx and friends are .cmd files on Windows, which only a shell can start.
+    this.child = process.platform === 'win32'
+      ? spawn([spec.command, ...args].map(winQuote).join(' '), { cwd, env, shell: true, windowsHide: true })
+      : spawn(spec.command, args, { cwd, env, windowsHide: true });
+    this.errors = '';
+    let rest = '';
+    this.child.stdout.setEncoding('utf8');
+    this.child.stdout.on('data', (chunk) => {
+      const lines = (rest + chunk).split('\n');
+      rest = lines.pop();
+      for (const line of lines) if (line.trim()) this.receive(line);
+    });
+    this.child.stderr.on('data', (d) => { this.errors = (this.errors + d).slice(-2000); });
+    const fail = (why) => {
+      for (const { reject } of this.pending.values()) reject(new Error(why));
+      this.pending.clear();
+      this.closed = why;
+    };
+    this.child.on('error', (err) => fail(err.message));
+    this.child.on('close', (code) => fail(`the server stopped (exit ${code})${this.errors ? `: ${this.errors.trim().split('\n').pop()}` : ''}`));
+  }
+
+  receive(line) {
+    let msg;
+    try { msg = JSON.parse(line); } catch { return; }
+    // A request from the server: answer ping, decline the rest.
+    if (msg.method && msg.id !== undefined) {
+      this.send(msg.method === 'ping'
+        ? { jsonrpc: '2.0', id: msg.id, result: {} }
+        : { jsonrpc: '2.0', id: msg.id, error: { code: -32601, message: 'ucode does not support that' } });
+      return;
+    }
+    const waiting = this.pending.get(msg.id);
+    if (!waiting) return;
+    this.pending.delete(msg.id);
+    if (msg.error) waiting.reject(new Error(msg.error.message ?? 'the server returned an error'));
+    else waiting.resolve(msg.result);
+  }
+
+  send(msg) {
+    if (!this.closed) this.child.stdin.write(`${JSON.stringify(msg)}\n`);
+  }
+
+  request(method, params, ms) {
+    if (this.closed) return Promise.reject(new Error(this.closed));
+    const id = this.next++;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => { this.pending.delete(id); reject(new Error(`no answer after ${ms / 1000}s`)); }, ms);
+      this.pending.set(id, {
+        resolve: (v) => { clearTimeout(timer); resolve(v); },
+        reject: (e) => { clearTimeout(timer); reject(e); },
+      });
+      this.send({ jsonrpc: '2.0', id, method, params });
+    });
+  }
+
+  notify(method, params) {
+    this.send({ jsonrpc: '2.0', method, ...(params ? { params } : {}) });
+  }
+
+  close() {
+    try { this.child.stdin.end(); this.child.kill(); } catch { /* already gone */ }
+  }
+}
+
+/** A server spoken to over HTTP: each message a POST, the answer JSON or an event stream. */
+class HttpLink {
+  constructor(spec) {
+    this.url = expand(spec.url);
+    this.headers = expandAll(spec.headers);
+    this.next = 1;
+  }
+
+  async post(body, ms) {
+    const res = await fetch(this.url, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        accept: 'application/json, text/event-stream',
+        'mcp-protocol-version': PROTOCOL,
+        ...(this.session ? { 'mcp-session-id': this.session } : {}),
+        ...this.headers,
+      },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(ms),
+    });
+    this.session = res.headers.get('mcp-session-id') ?? this.session;
+    if (!res.ok) throw new Error(`HTTP ${res.status}: ${(await res.text()).slice(0, 200)}`);
+    return res;
+  }
+
+  async request(method, params, ms) {
+    const id = this.next++;
+    const res = await this.post({ jsonrpc: '2.0', id, method, params }, ms);
+    const type = res.headers.get('content-type') ?? '';
+    let msg;
+    if (type.includes('text/event-stream')) {
+      const text = await res.text();
+      for (const event of text.split(/\r?\n\r?\n/)) {
+        const data = event.split(/\r?\n/).filter((l) => l.startsWith('data:')).map((l) => l.slice(5).trim()).join('\n');
+        if (!data) continue;
+        try {
+          const parsed = JSON.parse(data);
+          if (parsed.id === id) { msg = parsed; break; }
+        } catch { /* not a message */ }
+      }
+    } else {
+      msg = await res.json();
+    }
+    if (!msg) throw new Error('the server sent no answer');
+    if (msg.error) throw new Error(msg.error.message ?? 'the server returned an error');
+    return msg.result;
+  }
+
+  notify(method, params) {
+    this.post({ jsonrpc: '2.0', method, ...(params ? { params } : {}) }, 10_000).catch(() => {});
+  }
+
+  close() {}
+}
+
+/** Every connected server, and the tools they offer. */
+export class McpHub {
+  constructor() {
+    this.servers = new Map(); // name -> { ok, error, tools: [{ name, remote, description, schema }], link }
+    this.byTool = new Map();  // exposed tool name -> { server, remote }
+  }
+
+  /** Connect to each server at once. A server that fails is noted, never fatal. */
+  async start(specs, { cwd = process.cwd() } = {}) {
+    await Promise.all(specs.map((spec) => this.connect(spec, cwd)));
+    return this.status();
+  }
+
+  async connect(spec, cwd) {
+    let link;
+    try {
+      link = spec.url ? new HttpLink(spec) : new StdioLink(spec, cwd);
+      await link.request('initialize', {
+        protocolVersion: PROTOCOL,
+        capabilities: {},
+        clientInfo: { name: 'ucode', version: VERSION },
+      }, START_MS);
+      link.notify('notifications/initialized');
+      const tools = [];
+      let cursor;
+      do {
+        const page = await link.request('tools/list', cursor ? { cursor } : {}, START_MS);
+        tools.push(...(page?.tools ?? []));
+        cursor = page?.nextCursor;
+      } while (cursor);
+      const exposed = tools.map((t) => ({
+        name: toolName(spec.name, t.name),
+        remote: t.name,
+        description: String(t.description ?? `${t.name} from ${spec.name}`).slice(0, 1000),
+        schema: cleanSchema(t.inputSchema),
+      }));
+      for (const t of exposed) this.byTool.set(t.name, { server: spec.name, remote: t.remote });
+      this.servers.set(spec.name, { ok: true, tools: exposed, link, spec });
+    } catch (err) {
+      link?.close();
+      this.servers.set(spec.name, { ok: false, error: err.message, tools: [], spec });
+    }
+  }
+
+  /** Tool definitions in ucode's neutral format. */
+  tools() {
+    return [...this.servers.values()].flatMap((s) => s.tools.map((t) => ({
+      name: t.name,
+      description: `[${s.spec.name}] ${t.description}`,
+      parameters: t.schema,
+    })));
+  }
+
+  has(name) {
+    return this.byTool.has(name);
+  }
+
+  serverOf(name) {
+    return this.byTool.get(name)?.server;
+  }
+
+  async call(name, args) {
+    const { server, remote } = this.byTool.get(name);
+    const s = this.servers.get(server);
+    const result = await s.link.request('tools/call', { name: remote, arguments: args ?? {} }, CALL_MS);
+    return { text: resultText(result), isError: Boolean(result?.isError) };
+  }
+
+  status() {
+    return [...this.servers.entries()].map(([name, s]) => ({ name, ok: s.ok, tools: s.tools.length, error: s.error }));
+  }
+
+  close() {
+    for (const s of this.servers.values()) s.link?.close();
+  }
+}

package/src/core/mcpcli.js

@@ -0,0 +1,52 @@
+/**
+ * mcpcli.js — `ucode mcp add | list | remove`, the way to connect a server
+ * without editing JSON by hand. Servers go in ~/.ucode/mcp.json (every
+ * project) unless --project puts them in this folder's .ucode/mcp.json.
+ *
+ *   ucode mcp add context7 npx -y @upstash/context7-mcp
+ *   ucode mcp add github --url https://api.githubcopilot.com/mcp/ --header "Authorization=Bearer ${GITHUB_TOKEN}"
+ */
+
+import { USER_MCP, projectMcpFile, readServers, addServer, removeServer, McpHub } from './mcp.js';
+
+export async function mcpCommand(argv, { cwd = process.cwd() } = {}) {
+  const project = argv.includes('--project');
+  const args = argv.filter((a) => a !== '--project');
+  const file = project ? projectMcpFile(cwd) : USER_MCP;
+  const [action, name, ...rest] = args;
+
+  if (action === 'add') {
+    if (!name || !rest.length) return 'usage: ucode mcp add <name> <command> [args...]   or   ucode mcp add <name> --url <url>';
+    let spec;
+    if (rest[0] === '--url') {
+      const headers = {};
+      for (let i = 2; i < rest.length; i++) {
+        if (rest[i] === '--header' && rest[i + 1]?.includes('=')) {
+          const [k, ...v] = rest[++i].split('=');
+          headers[k] = v.join('=');
+        }
+      }
+      spec = { url: rest[1], ...(Object.keys(headers).length ? { headers } : {}) };
+    } else {
+      spec = { command: rest[0], args: rest.slice(1) };
+    }
+    await addServer(file, name, spec);
+    // Try it now, so a typo shows up here rather than mid-build.
+    const hub = new McpHub();
+    const [status] = await hub.start([{ name, ...spec }], { cwd });
+    hub.close();
+    return status.ok
+      ? `added ${name} to ${file} — ${status.tools} tools, ready next time you start ucode`
+      : `added ${name} to ${file}, but it did not start: ${status.error}`;
+  }
+
+  if (action === 'remove' || action === 'rm') {
+    if (!name) return 'usage: ucode mcp remove <name>';
+    return (await removeServer(file, name)) ? `removed ${name}` : `no server called ${name} in ${file}`;
+  }
+
+  const [mine, here] = await Promise.all([readServers(USER_MCP), readServers(projectMcpFile(cwd))]);
+  const line = (s, where) => `  ${s.name.padEnd(16)} ${where.padEnd(8)} ${s.url ?? [s.command, ...(s.args ?? [])].join(' ')}`;
+  const rows = [...mine.map((s) => line(s, 'yours')), ...here.map((s) => line(s, 'project'))];
+  return rows.length ? rows.join('\n') : 'no MCP servers yet — ucode mcp add <name> <command> [args...]';
+}

package/src/core/provider.js

@@ -146,6 +146,73 @@ let stalls = 0;
 let current = process.env.UCODE_MODEL || DEFAULT_MODEL;
 let client = null;
 
+/**
+ * Another OpenAI-compatible server instead of Google: Ollama on this computer,
+ * or any host the user points UCODE_BASE_URL at. Its models are its own, so
+ * any id is accepted, and it gets none of the Google-only pacing.
+ */
+export function customProvider() {
+  const url = process.env.UCODE_BASE_URL;
+  return Boolean(url) && !/googleapis\.com/i.test(url);
+}
+
+/**
+ * How hard the model thinks, per request: 'low', 'medium' or 'high'.
+ *
+ * Measured on Flash-Lite: with nothing set it does not think at all, and got a
+ * two-step riddle wrong that 'low' got right for under a second more. On a
+ * whole-app write 'low' thinks nothing and costs nothing, while 'medium' and
+ * 'high' spend about 2,800 thinking tokens (+5s). So the loop asks for 'low'
+ * on ordinary steps and saves the dearer levels for where they pay.
+ *
+ * UCODE_THINK=0 sends no level at all. A server that rejects the field is
+ * remembered and not sent it again.
+ */
+let effortRejected = false;
+const thinkingOn = () => process.env.UCODE_THINK !== '0' && !effortRejected;
+
+/** Requests actually sent this process — what the free daily limit counts. */
+let requests = 0;
+export const requestCount = () => requests;
+
+/**
+ * Google's free tier counts requests per minute, per model: about 15 on
+ * Flash-Lite and 10 on Flash. Going over costs a refusal and then a wait of up
+ * to a minute; spacing the requests out beforehand costs a second or two, and
+ * only when a build is actually running that fast. One under the limit, since
+ * workers share it. UCODE_RPM sets the number; 0 turns pacing off.
+ */
+export function rpmFor(id) {
+  const set = process.env.UCODE_RPM;
+  if (set !== undefined && set !== '') return Math.max(0, Number(set) || 0);
+  if (customProvider()) return 0;
+  return /flash-lite/.test(id) ? 14 : 9;
+}
+
+/** How long to wait before the next request, given when the recent ones went out. */
+export function paceDelay(times, now, rpm) {
+  if (!rpm) return 0;
+  const recent = times.filter((t) => now - t < 60_000);
+  if (recent.length < rpm) return 0;
+  return Math.max(0, recent[recent.length - rpm] + 60_000 - now);
+}
+
+const sentAt = new Map(); // model id -> times its requests went out
+
+async function pace(id, opts) {
+  // One shared list per model, read fresh after every wait and added to with
+  // no await in between: parallel workers each see the others' requests.
+  for (;;) {
+    const wait = paceDelay(sentAt.get(id) ?? [], Date.now(), rpmFor(id));
+    if (!wait || opts.signal?.aborted) break;
+    opts.onWait?.(`keeping under Google's free per-minute limit — ${Math.ceil(wait / 1000)}s`);
+    await pause(Math.min(1000, wait));
+  }
+  const now = Date.now();
+  sentAt.set(id, [...(sentAt.get(id) ?? []).filter((t) => now - t < 60_000), now]);
+  requests++;
+}
+
 export function model() {
   return current;
 }
@@ -160,7 +227,7 @@ export function setModel(id) {
       fix: `Pick one of: ${Object.keys(MODELS).join(', ')}`,
     });
   }
-  if (!MODELS[wanted]) {
+  if (!MODELS[wanted] && !customProvider()) {
     throw new Failure({
       kind: 'bad_model',
       attempted: `switching to "${wanted}"`,
@@ -235,8 +302,8 @@ export function providerKey() {
 }
 
 function apiKey() {
-  // UCODE_API_KEY is the documented name. The provider's own variable name is
-  // still read, so a key set up for another tool keeps working here.
+  // A local server such as Ollama wants no key, but the client insists on one.
+  if (customProvider()) return (process.env.UCODE_API_KEY || providerKey() || 'local').trim();
   const key = providerKey();
   if (!key) {
     throw new Failure({
@@ -711,6 +778,7 @@ 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;
+  if (opts.effort && thinkingOn()) request.reasoning_effort = opts.effort;
 
   // A side call (the design review) passes fewer: it is better skipped than
   // waited on through a string of rate-limit pauses.
@@ -727,21 +795,33 @@ export async function ask(messages, tools = [], opts = {}) {
 
   for (let attempt = 1; attempt <= attempts; attempt++) {
     try {
+      await pace(id, opts);
+      let reply;
       if (opts.onText) {
-        const reply = await streamed(request, callOpts, id);
-        stalls = 0;
-        return reply;
+        reply = await streamed(request, callOpts, id);
+      } else {
+        const { data, response } = await connection().chat.completions
+          .create(request, { signal: opts.signal })
+          .withResponse();
+        noteLimits(response?.headers);
+        reply = normalize(data, id, request.tools?.map((t) => t.function.name));
       }
-      const { data, response } = await connection().chat.completions
-        .create(request, { signal: opts.signal })
-        .withResponse();
-      noteLimits(response?.headers);
       stalls = 0;
-      return normalize(data, id, request.tools?.map((t) => t.function.name));
+      if (request.reasoning_effort === undefined && opts.effort && thinkingOn()) effortRejected = true;
+      return reply;
     } catch (err) {
       noteLimits(err?.headers);
       problem = explain(err, id);
 
+      // A server that does not know reasoning_effort rejects the whole request.
+      // Asked once more without it; only if that works is it left off for good,
+      // so a 400 for some other reason never switches thinking off.
+      if (problem.kind === 'bad_request' && request.reasoning_effort !== undefined && printed === 0) {
+        delete request.reasoning_effort;
+        attempt--;
+        continue;
+      }
+
       // Retrying a model that keeps freezing only repeats the wait. After a
       // few in a row, say so and hand the choice back.
       if (problem.detail?.stalled && ++stalls >= MAX_STALLS) {
@@ -923,6 +1003,7 @@ async function streamed(request, opts, id) {
       promptTokens: usage?.prompt_tokens ?? 0,
       outputTokens: usage?.completion_tokens ?? 0,
       totalTokens: usage?.total_tokens ?? 0,
+      cachedTokens: usage?.prompt_tokens_details?.cached_tokens ?? 0,
     },
     finishReason,
     model: id,
@@ -1178,6 +1259,7 @@ function normalize(data, id, names) {
       promptTokens: u.prompt_tokens ?? 0,
       outputTokens: u.completion_tokens ?? 0,
       totalTokens: u.total_tokens ?? 0,
+      cachedTokens: u.prompt_tokens_details?.cached_tokens ?? 0,
     },
     finishReason,
     model: id,

package/src/core/scope.js

@@ -33,9 +33,68 @@ const QUESTION = /\?\s*$|^\s*(?:what|how|why|when|where|who|which|can|could|does
 /** Does this message ask for something to be built? Never for a question. */
 export const asksToBuild = (input) => !QUESTION.test(input) && BUILDS.some((re) => re.test(input));
 
-/** The request as the model sees it: one that asks for an app carries the note. */
-export function withScope(input) {
-  return asksToBuild(input) ? `${input}\n\n${SCOPE_NOTE}` : input;
+/**
+ * A design direction for one build, so two apps never come out the same.
+ *
+ * Left to itself the model reaches for the same tone, the same system font and
+ * whatever accent the starter shipped with. Handing it a direction - a tone,
+ * a pair of typefaces, an accent - is a choice already made, which is free; a
+ * generic build caught afterwards costs a fix round. Every font is a free
+ * Google Font with a system fallback, so an offline page still renders.
+ */
+export const DIRECTIONS = [
+  { tone: 'calm', display: 'DM Serif Display', body: 'DM Sans', accent: '#c2410c', base: 'light' },
+  { tone: 'technical', display: 'JetBrains Mono', body: 'IBM Plex Sans', accent: '#16a34a', base: 'dark' },
+  { tone: 'playful', display: 'Baloo 2', body: 'Nunito', accent: '#e11d48', base: 'light' },
+  { tone: 'editorial', display: 'Fraunces', body: 'Source Sans 3', accent: '#b45309', base: 'light' },
+  { tone: 'clinical', display: 'IBM Plex Sans', body: 'IBM Plex Sans', accent: '#0369a1', base: 'light' },
+  { tone: 'industrial', display: 'Space Grotesk', body: 'Space Grotesk', accent: '#eab308', base: 'dark' },
+  { tone: 'warm', display: 'Bricolage Grotesque', body: 'Figtree', accent: '#ea580c', base: 'light' },
+  { tone: 'dense', display: 'Manrope', body: 'Manrope', accent: '#2563eb', base: 'light' },
+  { tone: 'retro', display: 'Righteous', body: 'Rubik', accent: '#db2777', base: 'dark' },
+  { tone: 'natural', display: 'Lora', body: 'Karla', accent: '#4d7c0f', base: 'light' },
+  { tone: 'bold', display: 'Archivo Black', body: 'Archivo', accent: '#dc2626', base: 'light' },
+  { tone: 'soft', display: 'Quicksand', body: 'Mulish', accent: '#0e7490', base: 'light' },
+];
+
+/** The direction note for one build. `pick` is for tests. */
+export function directionNote(pick = Math.random) {
+  const d = DIRECTIONS[Math.floor(pick() * DIRECTIONS.length) % DIRECTIONS.length];
+  const type = d.display === d.body ? `"${d.display}"` : `"${d.display}" for headings and "${d.body}" for text`;
+  return '(From ucode: design direction for this build, unless the request sets its own - ' +
+    `tone ${d.tone}; type ${type}, from Google Fonts with a system fallback; accent ${d.accent} ` +
+    `on a ${d.base} base. In the same reply as your first tool call, say in one line the app's name, ` +
+    'its tone, its accent and the one memorable detail it will have, then build to exactly that.)';
+}
+
+/**
+ * A change to code that already exists - the other half of what ucode is for.
+ *
+ * Every rule in the system prompt about building is about a new app: design
+ * it, write it whole, hand it over. Asked to fix a bug in a real project, a
+ * model following those rules redesigns the page. So a change request in a
+ * folder with code in it carries its own note instead.
+ */
+export const EDIT_NOTE =
+  '(From ucode: this is a change to an existing project. Find the code first - find_symbol, grep ' +
+  'or outline - then read only the files involved, together in one read_files. Make the smallest ' +
+  'change that does it, in the style the code already uses. Do not redesign, rename or reformat ' +
+  'what works, and do not start a new app. Then run the project\'s checks.)';
+
+const CHANGE = /\b(?:fix|bug|error|broken|crash|fails?|change|update|refactor|rename|add|remove|delete|improve|optimi[sz]e|clean ?up|move|replace|support|implement|make it|make the)\b/i;
+
+/** Does this message ask for a change to code that is already here? */
+export const asksToChange = (input) => !asksToBuild(input) && CHANGE.test(input);
+
+/**
+ * The request as the model sees it. One that asks for an app carries the
+ * scope note and a design direction; a change in a folder with code in it
+ * carries the note for working in an existing project.
+ */
+export function withScope(input, { hasCode = false, pick = Math.random } = {}) {
+  if (asksToBuild(input)) return `${input}\n\n${directionNote(pick)}\n${SCOPE_NOTE}`;
+  if (hasCode && asksToChange(input)) return `${input}\n\n${EDIT_NOTE}`;
+  return input;
 }
 
 /** A message with no letters or digits in it ("+", "?", "...") — nothing to answer or build. */