kronk-cli 0.3.1 → 0.5.0

package/src/subagent.js

@@ -0,0 +1,218 @@
+import { def, TOOLS } from './tools.js';
+import { config } from './config.js';
+import { c } from './ui.js';
+
+/**
+ * Sub-agents: one delegated task, one throwaway context.
+ *
+ * The point is the same one src/distill.js makes about command output, moved
+ * up a level. A survey that reads thirty files to answer one question costs
+ * the main conversation thirty files' worth of window, permanently, and it is
+ * still paying for them ten turns later. Handing that survey to a sub-agent
+ * costs the conversation exactly one tool result: the report. Everything the
+ * sub-agent read is discarded with its context.
+ *
+ * So this is not parallelism — a local Kronk server has one resident copy of
+ * the model and calls queue behind each other, so two sub-agents at once is
+ * slower than two in sequence, not faster. It is context economy. Delegate
+ * what is expensive to read and cheap to conclude.
+ */
+
+/** Look, never touch. Every sub-agent gets at least these. */
+const READ_ONLY = ['read_file', 'list_dir', 'search'];
+
+/**
+ * Rules every sub-agent is held to, whatever it is allowed to touch.
+ *
+ * The first two carry the whole contract. A sub-agent that reports "I found
+ * the bug" without saying where is a sub-agent whose entire context was spent
+ * for nothing — the caller cannot go and look, because the files it read are
+ * gone.
+ */
+const CONTRACT = `You are a sub-agent of kronk-cli, running fully offline on the user's machine.
+
+You have been given one self-contained task and a context of your own.
+
+- Nobody sees your work. The agent that delegated this cannot see the files you read, the commands you ran, or your reasoning — your final reply is the only thing it ever receives.
+- So the reply has to stand alone: the answer, the exact paths and line numbers behind it, whatever failed, and whatever you had to assume. Quote the few lines that matter verbatim; never paste whole files, because not having to hold them is the reason you were given this task.
+- Do not ask questions. There is nobody to answer one. Take the most reasonable reading of the task, act on it, and say what you assumed.
+- Do not stop half way and report progress. Finish the task, then report.
+- Keep the reply under about 30 lines.
+- The working directory is the user's project root. Paths are relative to it. You are already inside it. Do not \`cd\` above it.`;
+
+/**
+ * The roles a sub-agent can be given.
+ *
+ * Two, not ten. Each one is a line the delegating model has to read and choose
+ * between on every call, and a local model asked to pick between eight
+ * near-synonyms picks badly — the split that actually changes what can happen
+ * is "can it touch anything", so that is the split.
+ */
+export const AGENTS = {
+  explore: {
+    use: 'reading, searching, tracing how something works, answering a question about the code',
+    tools: READ_ONLY,
+    rules: '- You can only read: read_file, list_dir and search. You cannot run commands and you cannot change anything. If the task needs a command run or a file written, say so in your reply rather than trying.',
+  },
+  code: {
+    use: 'making a change, running a build or a test suite, reproducing a failure',
+    tools: [...READ_ONLY, 'write_file', 'bash'],
+    rules: '- You can also write files and run commands. The user is still asked before each one, and a refusal is an answer: report it, do not look for a way around it.\n'
+      + '- After you write code, RUN it and fix what breaks. Never report that something works unless you have executed it and seen the output.',
+  },
+};
+
+const agentList = () => Object.entries(AGENTS)
+  .map(([name, a]) => `"${name}" — ${a.use}`).join('; ');
+
+/**
+ * The instruction the delegating model actually reads.
+ *
+ * Same reasoning as set_plan's description in src/tools.js: a description is
+ * the one place a small model reliably looks, so the whole protocol lives
+ * here — what it is for, that the sub-agent starts blank, and that a vague
+ * prompt is the failure mode.
+ */
+export const TASK_TOOL = def('task',
+  'Delegate one self-contained piece of work to a sub-agent that runs in its own context. '
+  + 'Use it when getting the answer means reading or running a lot but the answer itself is '
+  + 'small — surveys, searches across many files, reproducing a failure. What the sub-agent '
+  + 'reads never enters this conversation; only its report does. The sub-agent cannot see this '
+  + 'conversation and cannot ask you anything, so the prompt must carry everything it needs and '
+  + 'must say exactly what to report back. It cannot delegate further. Prefer one well-scoped '
+  + 'task over several vague ones.',
+  {
+    agent: {
+      type: 'string',
+      enum: Object.keys(AGENTS),
+      description: `Which sub-agent to run: ${agentList()}.`,
+    },
+    prompt: {
+      type: 'string',
+      description: 'The whole task, written for someone who knows nothing about this '
+        + 'conversation: what to do, where to look, and exactly what to report back.',
+    },
+  },
+  ['agent', 'prompt']);
+
+/**
+ * The delegation tool, when it is allowed at all.
+ *
+ * Empty below the top level, and that is the recursion guard: a sub-agent is
+ * never handed the tool that would let it spawn one. Nothing else enforces
+ * depth, and nothing else needs to.
+ */
+export function taskTools(depth = 0) {
+  return depth === 0 && config.subagents ? [TASK_TOOL] : [];
+}
+
+/** The built-ins this role is allowed, in the order src/tools.js defines them. */
+export function subagentTools(agent) {
+  const allowed = new Set(AGENTS[agent]?.tools ?? READ_ONLY);
+  return TOOLS.filter((t) => allowed.has(t.function.name));
+}
+
+/**
+ * The sub-agent's system prompt: the contract, its role's rules, and the same
+ * project primer the main agent was given at startup.
+ *
+ * The primer is worth its tokens — without it every sub-agent spends its first
+ * two steps working out what the project is, in a context it only gets one of.
+ */
+export function systemFor(agent) {
+  const spec = AGENTS[agent];
+  const primer = config.projectPrimer ? `\n\n---\n\n${config.projectPrimer}` : '';
+  return `${CONTRACT}\n${spec.rules}${primer}`;
+}
+
+/** Nest one line of a sub-agent's output under the call that started it. */
+const nest = (line) => String(line).split('\n')
+  .map((l) => `${c.grey('   │')} ${l}`).join('\n');
+
+const MAX_REPORT_LINES = 14;
+
+/** The report on screen, dimmed and bounded — the caller received all of it. */
+function reportLines(text) {
+  const lines = text.split('\n');
+  const shown = lines.slice(0, MAX_REPORT_LINES).map((l) => c.grey(`   ${l}`));
+  const hidden = lines.length - shown.length;
+  if (hidden > 0) {
+    shown.push(c.grey(`   …${hidden} more line${hidden === 1 ? '' : 's'} (the agent received all of it)`));
+  }
+  return shown;
+}
+
+/**
+ * The sub-agent's last word, which is the entire value of the call.
+ *
+ * A turn always ends on an assistant message — see `endTurn` in src/agent.js —
+ * so the tail is the report. An empty one is reported as the error it is
+ * rather than handed back as a blank tool result the caller would have to
+ * interpret.
+ */
+function reportFrom(messages) {
+  const last = [...messages].reverse().find((m) => m.role === 'assistant');
+  const text = String(last?.content ?? '').trim();
+  if (!text) return 'error: the sub-agent finished without reporting anything. Do the work here, or delegate again with a more specific prompt.';
+  return text;
+}
+
+/**
+ * Run one delegated task to completion and hand back only its report.
+ *
+ * `run` is `runTurn` from src/agent.js, passed in rather than imported: the
+ * dispatch for this tool lives in that loop, so importing it back would be a
+ * cycle for nothing. `approve` and `grant` are the caller's own, unchanged —
+ * delegation is not a way to get a command past the user.
+ */
+export async function runTask(args, {
+  run, model, signal, approve, grant, out = console.log, maxSteps = config.subagentSteps,
+}) {
+  const agent = args?.agent ?? 'explore';
+  const prompt = String(args?.prompt ?? '').trim();
+  if (!AGENTS[agent]) {
+    return `error: unknown agent "${agent}" — use one of: ${Object.keys(AGENTS).join(', ')}`;
+  }
+  if (!prompt) return 'error: task needs a prompt saying what to do and what to report back';
+
+  const messages = [
+    { role: 'system', content: systemFor(agent) },
+    { role: 'user', content: prompt },
+  ];
+
+  // A sub-agent on another model gets that model's window and output cap, not
+  // the session's. Compacting a 32k sub-agent at 85% of the main model's 131k
+  // means never compacting it at all.
+  const own = config.subagentModel ? config.subagentLimits : null;
+
+  const done = await run({
+    messages,
+    // A smaller model for the grunt work is the whole reason this is a knob:
+    // the survey is reading and grepping, the synthesis is not.
+    model: config.subagentModel ?? model,
+    window: own ? own.contextWindow : config.contextWindow,
+    maxTokens: own?.maxTokens ?? config.maxTokens,
+    signal,
+    approve,
+    grant,
+    // No MCP: a local model already struggles past ~25 tools, and the
+    // sub-agent's list is meant to be the short one.
+    mcp: null,
+    tools: subagentTools(agent),
+    // The checklist is module state belonging to the task the user asked for.
+    // A sub-agent that called set_plan would clear it out from under the agent
+    // that delegated to it.
+    plan: false,
+    // Its reasoning and prose are not printed: they are not the answer, and a
+    // second stream interleaved with the caller's is unreadable. Tool calls
+    // still show, indented, so the run is not a black box.
+    stream: false,
+    out: (line) => out(nest(line)),
+    maxSteps,
+    depth: 1,
+  });
+
+  const report = reportFrom(done);
+  reportLines(report).forEach((l) => out(l));
+  return report;
+}

package/src/theme.js

@@ -0,0 +1,226 @@
+/**
+ * What colour to print in, given the terminal we were launched from.
+ *
+ * The status line, the context meter and every hint under it were bright black
+ * (SGR 90). On a light background that is a readable grey; on a dark one most
+ * terminals render it around #555, which is a few points of contrast away from
+ * the background it sits on — the line the REPL shows before every prompt was
+ * the hardest thing on screen to read. Bright black is the only grey the
+ * sixteen-colour palette has, so the fix is not a different code but a
+ * different palette per background, chosen from the 256-colour cube.
+ *
+ * Three ways to learn the background, in order of how much we trust them:
+ * what the user said (`KRONK_THEME`, `theme` in ~/.kronk-cli.json), what the
+ * terminal advertises (`COLORFGBG`), and what it answers when asked (OSC 11).
+ * The last one is a round trip over the tty, so it happens once at startup and
+ * never blocks for longer than a blink.
+ */
+
+/**
+ * Palettes, as SGR parameters. Each is chosen for contrast against its own
+ * background, not for fidelity to the sixteen-colour name it replaces: `red`
+ * on a light background is a darker red than on a dark one, and both are still
+ * unmistakably red.
+ *
+ * The `grey`/`dim` pair is the whole point. 245 on dark and 242 on light both
+ * land near 4.5:1 against a typical terminal background, where 90 on dark is
+ * closer to 1.9:1.
+ */
+export const PALETTES = {
+  256: {
+    dark: {
+      dim: '38;5;244', bold: '1', italic: '3', strike: '9',
+      red: '38;5;203', green: '38;5;114', yellow: '38;5;221', blue: '38;5;111',
+      magenta: '38;5;176', cyan: '38;5;116', grey: '38;5;245',
+    },
+    light: {
+      dim: '38;5;244', bold: '1', italic: '3', strike: '9',
+      red: '38;5;160', green: '38;5;28', yellow: '38;5;136', blue: '38;5;26',
+      magenta: '38;5;90', cyan: '38;5;30', grey: '38;5;242',
+    },
+  },
+  // Sixteen colours: no cube to pick from, so the only lever is whether a hue
+  // comes from the normal or the bright half. Light keeps exactly what this
+  // program printed before the palettes existed.
+  16: {
+    dark: {
+      dim: '37', bold: '1', italic: '3', strike: '9',
+      red: '91', green: '92', yellow: '93', blue: '94',
+      magenta: '95', cyan: '96', grey: '37',
+    },
+    light: {
+      dim: '90', bold: '1', italic: '3', strike: '9',
+      red: '31', green: '32', yellow: '33', blue: '34',
+      magenta: '35', cyan: '36', grey: '90',
+    },
+  },
+};
+
+/** Anything we cannot classify is dark: it is what most terminals ship as. */
+export const DEFAULT_THEME = 'dark';
+
+const THEMES = new Set(['dark', 'light']);
+
+/**
+ * How many colours we may use. 0 means print no escapes at all, which is what
+ * NO_COLOR, a dumb terminal, a redirected stdout and `FORCE_COLOR=0` each ask
+ * for; any other FORCE_COLOR overrides the redirect, so a pipe into `less -R`
+ * and the test suite can both see what a terminal would.
+ */
+export function colorDepth(env = process.env, stream = process.stdout) {
+  if (env.NO_COLOR) return 0;
+  if (env.TERM === 'dumb') return 0;
+  if (env.FORCE_COLOR === '0') return 0;
+  if (env.FORCE_COLOR === undefined && !stream?.isTTY) return 0;
+  const term = env.TERM ?? '';
+  if (env.COLORTERM || /-256(color)?\b/.test(term) || /^(alacritty|kitty|wezterm|xterm-ghostty)/.test(term)) {
+    return 256;
+  }
+  return 16;
+}
+
+/**
+ * The background as `COLORFGBG` describes it — `foreground;background`, or
+ * `foreground;bold;background` from rxvt. The background is the last field,
+ * as a palette index: the dark half of the sixteen, plus bright black, means
+ * a dark terminal. `default` is the one honest answer some terminals give and
+ * it tells us nothing, so it stays unclassified rather than guessed at.
+ */
+export function parseColorFgBg(value) {
+  if (typeof value !== 'string') return null;
+  const bg = value.split(';').pop()?.trim();
+  if (!bg || !/^\d+$/.test(bg)) return null;
+  const n = Number(bg);
+  if (n > 15) return null;
+  return [0, 1, 2, 3, 4, 5, 6, 8].includes(n) ? 'dark' : 'light';
+}
+
+/**
+ * The reply to an OSC 11 query: `ESC ] 11 ; rgb:RRRR/GGGG/BBBB`, an optional
+ * alpha component, then BEL or ST. Components are 1 to 4 hex digits wide
+ * depending on the terminal — xterm answers in 16 bits, others in 8.
+ */
+// eslint-disable-next-line no-control-regex -- ESC is what the reply starts with
+const OSC11 = /\x1b\]11;rgba?:([0-9a-f]{1,4})\/([0-9a-f]{1,4})\/([0-9a-f]{1,4})(?:\/[0-9a-f]{1,4})?(?:\x07|\x1b\\)?/i;
+
+/**
+ * The reply found in `buf`: its relative luminance, and where it sat, so the
+ * caller can hand back whatever else was in the buffer. Each component is
+ * scaled by its own width — a short reply is not a near-black one.
+ */
+function matchOsc11(buf) {
+  const m = typeof buf === 'string' ? OSC11.exec(buf) : null;
+  if (!m) return null;
+  const [r, g, b] = m.slice(1, 4).map((h) => parseInt(h, 16) / (16 ** h.length - 1));
+  return {
+    luminance: 0.2126 * r + 0.7152 * g + 0.0722 * b,
+    rest: buf.slice(0, m.index) + buf.slice(m.index + m[0].length),
+  };
+}
+
+/** The relative luminance of an OSC 11 reply, or null if this is not one. */
+export function parseOsc11(reply) {
+  return matchOsc11(reply)?.luminance ?? null;
+}
+
+/** Mid-grey is the boundary; a terminal sitting exactly on it reads as light. */
+export const themeForLuminance = (lum) => (lum >= 0.5 ? 'light' : 'dark');
+
+/**
+ * A theme somebody named, or null for "work it out". `auto` is spelled out
+ * rather than left to an empty value so a config file can turn a forced theme
+ * back off without deleting the key, and a typo falls through to detection
+ * rather than pinning the wrong palette.
+ */
+export const namedTheme = (value) => {
+  const asked = String(value ?? '').trim().toLowerCase();
+  return THEMES.has(asked) ? asked : null;
+};
+
+/** What the environment alone can tell us, or null for "ask the terminal". */
+export function detectTheme(env = process.env) {
+  return namedTheme(env.KRONK_THEME) ?? parseColorFgBg(env.COLORFGBG);
+}
+
+/**
+ * Ask the terminal for its background colour and wait, briefly.
+ *
+ * This puts stdin in raw mode for as long as the answer takes, so it runs
+ * once, before the REPL's readline exists, and only when both ends are a tty.
+ * A terminal that does not implement OSC 11 says nothing at all, which is why
+ * there is a timeout rather than a sentinel to wait for; 100 ms is far longer
+ * than a local round trip and short enough to be invisible.
+ *
+ * Anything read that is not part of the reply is somebody typing ahead, and it
+ * is pushed back onto stdin before this resolves. Without that, a fast typist
+ * — or a script piping commands in — loses whatever landed in the window, and
+ * loses it silently.
+ */
+export function probeBackground({ input = process.stdin, output = process.stdout, timeoutMs = 100 } = {}) {
+  if (!input?.isTTY || !output?.isTTY || typeof input.setRawMode !== 'function') {
+    return Promise.resolve(null);
+  }
+  return new Promise((resolve) => {
+    const wasRaw = input.isRaw;
+    let buf = '';
+    let settled = false;
+    const finish = (value, rest) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      input.off('data', onData);
+      if (!wasRaw) input.setRawMode(false);
+      input.pause();
+      if (rest) input.unshift?.(Buffer.from(rest, 'latin1'));
+      resolve(value);
+    };
+    const onData = (chunk) => {
+      buf += chunk.toString('latin1');
+      const hit = matchOsc11(buf);
+      if (hit) finish(themeForLuminance(hit.luminance), hit.rest);
+      // Whatever this is, it is not the reply and no longer plausibly the
+      // start of one. Stop reading and give it back.
+      else if (buf.length > 64) finish(null, buf);
+    };
+    const timer = setTimeout(() => finish(null, buf), timeoutMs);
+    input.setRawMode(true);
+    input.resume();
+    input.on('data', onData);
+    output.write('\x1b]11;?\x07');
+  });
+}
+
+let depth = colorDepth();
+let active = detectTheme() ?? DEFAULT_THEME;
+
+/** Which palette is in force. Read by the tests and by `/theme`. */
+export const theme = () => active;
+
+/** Depth 0 means every colour helper is the identity function. */
+export const colorsOn = () => depth > 0;
+
+/** Set both explicitly. Tests use it; nothing in the program has to guess. */
+export function useTheme({ name, colors } = {}) {
+  if (THEMES.has(name)) active = name;
+  if (colors !== undefined) depth = colors ? (colors === true ? 256 : colors) : 0;
+  return active;
+}
+
+/**
+ * Settle the palette for this session: what the user asked for, what the
+ * environment said, or failing both what the terminal answers. Startup awaits this once; everything that
+ * prints reads `ansi` per call, so the banner and every later line agree.
+ */
+export async function resolveTheme({ prefer, ...options } = {}) {
+  const known = namedTheme(prefer) ?? detectTheme();
+  if (known) { active = known; return active; }
+  if (depth === 0) return active;              // nothing to colour, don't touch the tty
+  active = (await probeBackground(options)) ?? DEFAULT_THEME;
+  return active;
+}
+
+/** The SGR parameters for a palette entry, or null when colour is off. */
+export function ansi(name) {
+  if (depth === 0) return null;
+  return PALETTES[depth === 256 ? 256 : 16][active][name] ?? null;
+}

package/src/tools.js

@@ -206,7 +206,13 @@ export function safe(p) {
   return abs;
 }
 
-const def = (name, description, properties, required) => ({
+/**
+ * A tool definition in the shape the OpenAI-compatible API wants.
+ *
+ * Exported because src/subagent.js defines a tool too — one that is only
+ * offered at the top level, so it cannot live in TOOLS below.
+ */
+export const def = (name, description, properties, required) => ({
   type: 'function',
   function: { name, description, parameters: { type: 'object', properties, required } },
 });
@@ -284,6 +290,7 @@ export function describe(name, args) {
     case 'search':     return `search /${args.pattern}/ in ${args.path ?? '.'}`;
     case 'bash':       return `bash: ${args.cmd}`;
     case 'set_plan':   return `plan: ${args.items?.length ?? 0} items`;
+    case 'task':       return `task ${args.agent ?? 'explore'}: ${String(args.prompt ?? '').split('\n')[0]}`;
     default:           return `${name}(${JSON.stringify(args)})`;
   }
 }

package/src/ui.js

@@ -1,16 +1,27 @@
-const on = process.stdout.isTTY && !process.env.NO_COLOR;
-const wrap = (code) => (s) => (on ? `\x1b[${code}m${s}\x1b[0m` : s);
+import { ansi } from './theme.js';
+
+/**
+ * Each colour resolves its escape when it is called, not when this module is
+ * loaded: the background is only known after the terminal has been asked, and
+ * that answer arrives after the first import. See src/theme.js.
+ */
+const wrap = (name) => (s) => {
+  const code = ansi(name);
+  return code ? `\x1b[${code}m${s}\x1b[0m` : s;
+};
 
 export const c = {
-  dim: wrap('2'),
-  bold: wrap('1'),
-  red: wrap('31'),
-  green: wrap('32'),
-  yellow: wrap('33'),
-  blue: wrap('34'),
-  magenta: wrap('35'),
-  cyan: wrap('36'),
-  grey: wrap('90'),
+  dim: wrap('dim'),
+  bold: wrap('bold'),
+  italic: wrap('italic'),
+  strike: wrap('strike'),
+  red: wrap('red'),
+  green: wrap('green'),
+  yellow: wrap('yellow'),
+  blue: wrap('blue'),
+  magenta: wrap('magenta'),
+  cyan: wrap('cyan'),
+  grey: wrap('grey'),
 };
 
 export const banner = (model, url) => `