ucode-agent 1.0.0

package/src/core/skills.js

@@ -0,0 +1,165 @@
+/**
+ * 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,
+  };
+}

package/src/core/window.js

@@ -0,0 +1,127 @@
+/**
+ * window.js — keeping a long conversation inside the model's context.
+ *
+ * Two rules, both of which exist because the obvious alternative is worse:
+ *
+ *   Summarize the oldest turns rather than dropping them. Dropping means the
+ *   agent forgets a decision it made an hour ago and quietly contradicts it.
+ *
+ *   Never cut between a tool call and its result. A result with no call above
+ *   it is unreadable to the model and to anyone debugging the transcript.
+ *
+ * Only what gets sent is affected. history.js keeps the full record on disk
+ * whatever happens here.
+ */
+
+import { estimateConversation } from './provider.js';
+
+/** Start folding once the conversation passes this share of the window. */
+export const FOLD_AT = 0.75;
+
+/** After folding, the verbatim tail may occupy this share of the window. */
+export const KEEP = 0.4;
+
+export function usage(messages, limit) {
+  const used = estimateConversation(messages);
+  return {
+    used,
+    limit,
+    percent: limit > 0 ? Math.min(100, (used / limit) * 100) : 0,
+    left: Math.max(0, limit - used),
+  };
+}
+
+export function tooBig(messages, limit) {
+  return usage(messages, limit).used > limit * FOLD_AT;
+}
+
+/**
+ * Where to cut so the kept tail stands on its own.
+ *
+ * Walks backwards accumulating messages until the budget runs out, then nudges
+ * the boundary forward past any tool result whose call would have been folded
+ * away.
+ */
+function cutPoint(messages, budget) {
+  let cut = messages.length;
+  let left = budget;
+
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const cost = estimateConversation([messages[i]]);
+    if (left - cost < 0 && cut < messages.length) break;
+    left -= cost;
+    cut = i;
+  }
+
+  while (cut < messages.length && messages[cut].role === 'tool') cut++;
+
+  // Whatever else happens, the most recent exchange survives intact.
+  if (cut >= messages.length) cut = Math.max(0, messages.length - 1);
+  return cut;
+}
+
+/**
+ * Fold the older half of a conversation into a summary, if it needs it.
+ *
+ * @param {Array} messages
+ * @param {object} o
+ * @param {number} o.limit          token budget
+ * @param {Function} o.summarize    async (older) => string
+ */
+export async function fold(messages, { limit, summarize }) {
+  if (!tooBig(messages, limit)) return { messages, folded: false };
+
+  const cut = cutPoint(messages, limit * KEEP);
+  const older = messages.slice(0, cut);
+  const recent = messages.slice(cut);
+
+  // Nothing old enough to fold — the tail on its own is already oversized.
+  if (older.length === 0) return { messages, folded: false };
+
+  const summary = await summarize(older);
+
+  return {
+    folded: true,
+    summary,
+    droppedCount: older.length,
+    messages: [
+      {
+        role: 'system',
+        content:
+          `Summary of the earlier part of this conversation. ${older.length} messages ` +
+          `were folded away to stay inside the context window.\n\n${summary}\n\n` +
+          'Treat all of that as settled context. Everything after this point is verbatim.',
+        folded: true,
+      },
+      ...recent,
+    ],
+  };
+}
+
+/** What the summarizer is asked to do. */
+export const SUMMARY_PROMPT =
+  'Summarize this conversation so another engineer could pick it up mid-task with ' +
+  'nothing else to go on. Keep, in this order: (1) what the user is trying to achieve, ' +
+  '(2) which files were read or changed and what is in them, (3) decisions taken and the ' +
+  'reasoning, (4) commands run and what they printed, (5) what is still unfinished. ' +
+  'Name exact paths, functions and error messages. No preamble, no commentary.';
+
+/**
+ * Flatten the messages being folded into plain text for the summarizer.
+ * Tool traffic is included but trimmed — that a tool ran and roughly what it
+ * returned matters; its exact bytes almost never do.
+ */
+export function forSummary(messages) {
+  return messages
+    .map((m) => {
+      if (m.role === 'tool') return `[${m.name} returned]\n${(m.content || '').slice(0, 300)}`;
+      if (m.role === 'assistant') {
+        const calls = (m.toolCalls || [])
+          .map((c) => `[called ${c.name}(${JSON.stringify(c.args).slice(0, 200)})]`)
+          .join('\n');
+        return `assistant: ${m.content || ''}\n${calls}`.trim();
+      }
+      return `${m.role}: ${m.content || ''}`;
+    })
+    .join('\n\n');
+}