@plainconceptsplatform/agent-harness 2.3.0 → 2.4.0

package/{src → cli}/utils/agent-color.js

@@ -1,83 +1,111 @@
-/**
- * Deterministic colour for an agent, derived from its name.
- *
- * opencode accepts either a hex value or one of its theme keywords. Two of
- * those keywords are reserved for the primaries so they stay recognisable
- * across every project: build is `primary`, plan is `warning`. Every other
- * agent gets a hex derived from its name, so a `butterfly-engineer` is the
- * same colour in every repository that has one, with no central registry and
- * no chance of two agents in one project colliding by accident.
- *
- * Saturation and lightness are fixed rather than hashed. That is what keeps
- * the result usable: hashing them too would eventually produce near-grey,
- * near-black or near-white agents that are invisible against one theme or the
- * other. Only the hue varies.
- */
-
-/** opencode's theme keywords. Treated as unset so a name-derived hex wins. */
-export const THEME_COLORS = new Set([
-  'primary',
-  'secondary',
-  'accent',
-  'success',
-  'warning',
-  'error',
-  'info',
-])
-
-/** Reserved: the two primaries, which never take a derived colour. */
-export const RESERVED_COLORS = { build: 'primary', plan: 'warning' }
-
-const SATURATION = 68
-const LIGHTNESS = 52
-
-/**
- * FNV-1a, 32 bit. Chosen because it is short enough to duplicate verbatim in
- * the shipped plugin and produces the same hue everywhere: the same name must
- * resolve to the same colour on every machine and in every project.
- */
-function hash(value) {
-  let h = 0x811c9dc5
-  for (let i = 0; i < value.length; i++) {
-    h ^= value.charCodeAt(i)
-    h = Math.imul(h, 0x01000193) >>> 0
-  }
-  return h >>> 0
-}
-
-function hslToHex(h, s, l) {
-  const sat = s / 100
-  const light = l / 100
-  const c = (1 - Math.abs(2 * light - 1)) * sat
-  const x = c * (1 - Math.abs(((h / 60) % 2) - 1))
-  const m = light - c / 2
-
-  const [r, g, b] =
-    h < 60 ? [c, x, 0] :
-    h < 120 ? [x, c, 0] :
-    h < 180 ? [0, c, x] :
-    h < 240 ? [0, x, c] :
-    h < 300 ? [x, 0, c] :
-    [c, 0, x]
-
-  const toHex = v => Math.round((v + m) * 255).toString(16).padStart(2, '0')
-  return `#${toHex(r)}${toHex(g)}${toHex(b)}`.toUpperCase()
-}
-
-/** The colour for an agent, honouring the two reserved primaries. */
-export function agentColor(name) {
-  if (name in RESERVED_COLORS) return RESERVED_COLORS[name]
-  return hslToHex(hash(name) % 360, SATURATION, LIGHTNESS)
-}
-
-/**
- * Whether a frontmatter colour should be replaced by the derived one.
- *
- * A theme keyword is replaced: those came from the old template, which asked
- * whoever ran /make-engineer to pick one and avoid collisions by hand. An
- * explicit hex is left alone, because someone chose it deliberately.
- */
-export function shouldDeriveColor(current) {
-  if (!current) return true
-  return THEME_COLORS.has(current.trim().toLowerCase())
-}
+/**
+ * Deterministic colour for an agent, derived from its name.
+ *
+ * opencode accepts either a hex value or one of its theme keywords. Two of
+ * those keywords are reserved for the primaries so they stay recognisable
+ * across every project: build is `primary`, plan is `warning`. Every other
+ * agent gets a hex derived from its name, so a `butterfly-engineer` is the
+ * same colour in every repository that has one, with no central registry and
+ * no chance of two agents in one project colliding by accident.
+ *
+ * Saturation and lightness are fixed rather than hashed. That is what keeps
+ * the result usable: hashing them too would eventually produce near-grey,
+ * near-black or near-white agents that are invisible against one theme or the
+ * other. Only the hue varies.
+ */
+
+/** opencode's theme keywords. Treated as unset so a name-derived hex wins. */
+export const THEME_COLORS = new Set([
+  'primary',
+  'secondary',
+  'accent',
+  'success',
+  'warning',
+  'error',
+  'info',
+])
+
+/** Reserved: the two primaries, which never take a derived colour. */
+export const RESERVED_COLORS = { build: 'primary', plan: 'warning' }
+
+const SATURATION = 68
+const LIGHTNESS = 52
+
+/**
+ * FNV-1a, 32 bit. Chosen because it is short enough to duplicate verbatim in
+ * the shipped plugin and produces the same hue everywhere: the same name must
+ * resolve to the same colour on every machine and in every project.
+ */
+function hash(value) {
+  let h = 0x811c9dc5
+  for (let i = 0; i < value.length; i++) {
+    h ^= value.charCodeAt(i)
+    h = Math.imul(h, 0x01000193) >>> 0
+  }
+  return h >>> 0
+}
+
+function hslToHex(h, s, l) {
+  const sat = s / 100
+  const light = l / 100
+  const c = (1 - Math.abs(2 * light - 1)) * sat
+  const x = c * (1 - Math.abs(((h / 60) % 2) - 1))
+  const m = light - c / 2
+
+  const [r, g, b] =
+    h < 60 ? [c, x, 0] :
+    h < 120 ? [x, c, 0] :
+    h < 180 ? [0, c, x] :
+    h < 240 ? [0, x, c] :
+    h < 300 ? [x, 0, c] :
+    [c, 0, x]
+
+  const toHex = v => Math.round((v + m) * 255).toString(16).padStart(2, '0')
+  return `#${toHex(r)}${toHex(g)}${toHex(b)}`.toUpperCase()
+}
+
+/** The colour for an agent, honouring the two reserved primaries. */
+export function agentColor(name) {
+  if (name in RESERVED_COLORS) return RESERVED_COLORS[name]
+  return hslToHex(hash(name) % 360, SATURATION, LIGHTNESS)
+}
+
+/**
+ * Render a colour for YAML frontmatter.
+ *
+ * A hex has to be quoted. `#` opens a comment in YAML, so `color: #D83155`
+ * parses as null and opencode rejects the agent outright with "Invalid input
+ * color". Theme keywords need no quoting and are left bare.
+ */
+export function yamlColor(value) {
+  return value.startsWith('#') ? `"${value}"` : value
+}
+
+/** The value of a frontmatter colour, with any quoting removed. */
+export function unquoteColor(raw) {
+  return (raw ?? '').trim().replace(/^["']/, '').replace(/["']$/, '')
+}
+
+/**
+ * The frontmatter colour line an agent should have, or null when the current
+ * one is already correct. Covers both jobs: choosing the colour, and quoting it
+ * so the file actually parses.
+ */
+export function colorLineFor(name, rawCurrent) {
+  const current = unquoteColor(rawCurrent)
+  const target = shouldDeriveColor(current) ? agentColor(name) : current
+  const rendered = yamlColor(target)
+  return (rawCurrent ?? '').trim() === rendered ? null : `color: ${rendered}`
+}
+
+/**
+ * Whether a frontmatter colour should be replaced by the derived one.
+ *
+ * A theme keyword is replaced: those came from the old template, which asked
+ * whoever ran /make-engineer to pick one and avoid collisions by hand. An
+ * explicit hex is left alone, because someone chose it deliberately.
+ */
+export function shouldDeriveColor(current) {
+  if (!current) return true
+  return THEME_COLORS.has(current.trim().toLowerCase())
+}

package/{src → cli}/utils/exec-spinner.js

@@ -1,47 +1,47 @@
-import chalk from 'chalk'
-import ora from 'ora'
-
-// ── Screen / step state ──────────────────────────────────────────────────────
-
-const previousSteps = [];    // up to 2 completed steps, each is an array of lines
-let currentStepLines = [];   // lines accumulated in the current step
-let stepSpinner = null;      // ora spinner shown while step is working
-
-export function appendLine(line) {
-  currentStepLines.push(line);
-}
-
-export function stopSpinner() {
-  if (stepSpinner) {
-    stepSpinner.stop();
-    stepSpinner = null;
-  }
-}
-
-export function startSpinner(text = 'working...') {
-  stopSpinner();
-  stepSpinner = ora({ text: chalk.dim(text), color: 'red' }).start();
-}
-
-export function redraw() {
-  if (process.stdout.isTTY) console.clear();
-
-  // Show up to 2 previous steps dimmed
-  for (const stepLines of previousSteps) {
-    for (const line of stepLines) {
-      process.stdout.write(`${chalk.dim(line)}\n`);
-    }
-    process.stdout.write('\n');
-  }
-
-  // Current step output
-  for (const line of currentStepLines) {
-    process.stdout.write(`${line}\n`);
-  }
-}
-
-export function rotateStep() {
-  previousSteps.push(currentStepLines);
-  if (previousSteps.length > 2) previousSteps.shift();
-  currentStepLines = [];
-}
+import chalk from 'chalk'
+import ora from 'ora'
+
+// ── Screen / step state ──────────────────────────────────────────────────────
+
+const previousSteps = [];    // up to 2 completed steps, each is an array of lines
+let currentStepLines = [];   // lines accumulated in the current step
+let stepSpinner = null;      // ora spinner shown while step is working
+
+export function appendLine(line) {
+  currentStepLines.push(line);
+}
+
+export function stopSpinner() {
+  if (stepSpinner) {
+    stepSpinner.stop();
+    stepSpinner = null;
+  }
+}
+
+export function startSpinner(text = 'working...') {
+  stopSpinner();
+  stepSpinner = ora({ text: chalk.dim(text), color: 'red' }).start();
+}
+
+export function redraw() {
+  if (process.stdout.isTTY) console.clear();
+
+  // Show up to 2 previous steps dimmed
+  for (const stepLines of previousSteps) {
+    for (const line of stepLines) {
+      process.stdout.write(`${chalk.dim(line)}\n`);
+    }
+    process.stdout.write('\n');
+  }
+
+  // Current step output
+  for (const line of currentStepLines) {
+    process.stdout.write(`${line}\n`);
+  }
+}
+
+export function rotateStep() {
+  previousSteps.push(currentStepLines);
+  if (previousSteps.length > 2) previousSteps.shift();
+  currentStepLines = [];
+}

package/{src → cli}/utils/exec.js

@@ -1,134 +1,134 @@
-import chalk from 'chalk'
-import { execa } from 'execa'
-import ora from 'ora'
-import { appendLine, redraw, rotateStep, startSpinner, stopSpinner } from './exec-spinner.js'
-import { MARKERS } from './terminal.js';
-
-// ── Public API ───────────────────────────────────────────────────────────────
-
-/**
- * Run a shell command with a spinner.
- * Returns { success, stdout, stderr }
- */
-export async function run(command, args = [], { label, cwd = process.cwd() } = {}) {
-  const spinner = ora(label ?? `${command} ${args.join(' ')}`).start();
-  try {
-    const result = await execa(command, args, { cwd, reject: false });
-    if (result.exitCode === 0) {
-      spinner.succeed();
-    } else {
-      spinner.fail();
-    }
-    return { success: result.exitCode === 0, stdout: result.stdout, stderr: result.stderr };
-  } catch (err) {
-    spinner.fail();
-    return { success: false, stdout: '', stderr: err.message };
-  }
-}
-
-/**
- * Check if a command is available on PATH.
- * Returns true/false.
- */
-export async function commandExists(command) {
-  try {
-    const result = await execa(command, ['--version'], { reject: false });
-    return result.exitCode === 0;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Print a section header, clears screen, shows previous step dimmed, starts new step.
- */
-export function header(text) {
-  rotateStep();
-
-  const line1 = '';
-  const line2 = chalk.bold.hex('#fe3d57')(`━━ ${text}`);
-  const line3 = '';
-
-  appendLine(line1);
-  appendLine(line2);
-  appendLine(line3);
-
-  redraw();
-
-  startSpinner('working...');
-}
-
-/**
- * Restart the step spinner after prompts or logs.
- */
-export function loading(text = 'working...') {
-  startSpinner(text);
-}
-
-/**
- * Print a success line.
- */
-export function success(text) {
-  stopSpinner();
-  const line = chalk.green(`${MARKERS.OK_PREFIX}${text}`);
-  appendLine(line);
-  console.log(line);
-}
-
-/**
- * Print a warning line.
- */
-export function warn(text) {
-  stopSpinner();
-  const line = chalk.yellow(`${MARKERS.WARN_PREFIX}${text}`);
-  appendLine(line);
-  console.log(line);
-}
-
-/**
- * Print an error line.
- */
-export function error(text) {
-  stopSpinner();
-  const line = chalk.red(`${MARKERS.ERROR_PREFIX}${text}`);
-  appendLine(line);
-  console.log(line);
-}
-
-/**
- * Print an info line.
- */
-export function info(text) {
-  stopSpinner();
-  const line = chalk.dim(`${MARKERS.EMPTY}${text}`);
-  appendLine(line);
-  console.log(line);
-}
-
-/**
- * Print an action prompt line (white bold, requires user interaction).
- */
-export function prompt(text) {
-  stopSpinner();
-  const line = chalk.bold(`${MARKERS.EMPTY}${text}`);
-  appendLine(line);
-  console.log(line);
-}
-
-/**
- * Print a code block.
- */
-export function code(lines) {
-  stopSpinner();
-  appendLine('');
-  console.log();
-  for (const line of lines) {
-    const formatted = chalk.bgGray.white(
-      `${MARKERS.EMPTY}${line}${MARKERS.EMPTY}`,
-    );
-    appendLine(formatted);
-    console.log(formatted);
-  }
-  appendLine('');
-  console.log();
-}
+import chalk from 'chalk'
+import { execa } from 'execa'
+import ora from 'ora'
+import { appendLine, redraw, rotateStep, startSpinner, stopSpinner } from './exec-spinner.js'
+import { MARKERS } from './terminal.js';
+
+// ── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Run a shell command with a spinner.
+ * Returns { success, stdout, stderr }
+ */
+export async function run(command, args = [], { label, cwd = process.cwd() } = {}) {
+  const spinner = ora(label ?? `${command} ${args.join(' ')}`).start();
+  try {
+    const result = await execa(command, args, { cwd, reject: false });
+    if (result.exitCode === 0) {
+      spinner.succeed();
+    } else {
+      spinner.fail();
+    }
+    return { success: result.exitCode === 0, stdout: result.stdout, stderr: result.stderr };
+  } catch (err) {
+    spinner.fail();
+    return { success: false, stdout: '', stderr: err.message };
+  }
+}
+
+/**
+ * Check if a command is available on PATH.
+ * Returns true/false.
+ */
+export async function commandExists(command) {
+  try {
+    const result = await execa(command, ['--version'], { reject: false });
+    return result.exitCode === 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Print a section header, clears screen, shows previous step dimmed, starts new step.
+ */
+export function header(text) {
+  rotateStep();
+
+  const line1 = '';
+  const line2 = chalk.bold.hex('#fe3d57')(`━━ ${text}`);
+  const line3 = '';
+
+  appendLine(line1);
+  appendLine(line2);
+  appendLine(line3);
+
+  redraw();
+
+  startSpinner('working...');
+}
+
+/**
+ * Restart the step spinner after prompts or logs.
+ */
+export function loading(text = 'working...') {
+  startSpinner(text);
+}
+
+/**
+ * Print a success line.
+ */
+export function success(text) {
+  stopSpinner();
+  const line = chalk.green(`${MARKERS.OK_PREFIX}${text}`);
+  appendLine(line);
+  console.log(line);
+}
+
+/**
+ * Print a warning line.
+ */
+export function warn(text) {
+  stopSpinner();
+  const line = chalk.yellow(`${MARKERS.WARN_PREFIX}${text}`);
+  appendLine(line);
+  console.log(line);
+}
+
+/**
+ * Print an error line.
+ */
+export function error(text) {
+  stopSpinner();
+  const line = chalk.red(`${MARKERS.ERROR_PREFIX}${text}`);
+  appendLine(line);
+  console.log(line);
+}
+
+/**
+ * Print an info line.
+ */
+export function info(text) {
+  stopSpinner();
+  const line = chalk.dim(`${MARKERS.EMPTY}${text}`);
+  appendLine(line);
+  console.log(line);
+}
+
+/**
+ * Print an action prompt line (white bold, requires user interaction).
+ */
+export function prompt(text) {
+  stopSpinner();
+  const line = chalk.bold(`${MARKERS.EMPTY}${text}`);
+  appendLine(line);
+  console.log(line);
+}
+
+/**
+ * Print a code block.
+ */
+export function code(lines) {
+  stopSpinner();
+  appendLine('');
+  console.log();
+  for (const line of lines) {
+    const formatted = chalk.bgGray.white(
+      `${MARKERS.EMPTY}${line}${MARKERS.EMPTY}`,
+    );
+    appendLine(formatted);
+    console.log(formatted);
+  }
+  appendLine('');
+  console.log();
+}

package/{src → cli}/utils/models-pricing.js

@@ -1,42 +1,42 @@
-// Providers considered "canonical" for reference pricing, in priority order.
-// When a model's own provider has no cost (e.g. github-copilot shows $0),
-// we look up the same model name in these providers and attach canonicalCost.
-export const CANONICAL_PROVIDERS = ['anthropic', 'openai', 'google', 'mistral', 'meta', 'cohere'];
-
-export function parseModels(data) {
-  // Build name → canonical cost lookup from authoritative providers first
-  const canonicalCostByName = new Map();
-  for (const providerId of CANONICAL_PROVIDERS) {
-    const provider = data[providerId];
-    if (!provider?.models) continue;
-    for (const model of Object.values(provider.models)) {
-      if (!model.tool_call) continue;
-      const name = model.name;
-      if (name && model.cost?.input !== undefined && !canonicalCostByName.has(name)) {
-        canonicalCostByName.set(name, model.cost.input);
-      }
-    }
-  }
-
-  const models = [];
-  for (const [providerId, provider] of Object.entries(data)) {
-    if (!provider.models) continue;
-    for (const [modelId, model] of Object.entries(provider.models)) {
-      if (!model.tool_call) continue;
-      const name = model.name || modelId;
-      const cost = model.cost?.input;
-      const canonicalCost = canonicalCostByName.get(name);
-      models.push({
-        id: `${providerId}/${modelId}`,
-        name,
-        cost,
-        // canonicalCost: cost from the authoritative provider for this model name.
-        // Defined when cost !== canonicalCost (different provider, reseller, or $0 subscription).
-        canonicalCost: canonicalCost !== undefined && canonicalCost !== cost ? canonicalCost : undefined,
-        context: model.limit?.context,
-      });
-    }
-  }
-  models.sort((a, b) => (a.cost ?? Infinity) - (b.cost ?? Infinity));
-  return models;
-}
+// Providers considered "canonical" for reference pricing, in priority order.
+// When a model's own provider has no cost (e.g. github-copilot shows $0),
+// we look up the same model name in these providers and attach canonicalCost.
+export const CANONICAL_PROVIDERS = ['anthropic', 'openai', 'google', 'mistral', 'meta', 'cohere'];
+
+export function parseModels(data) {
+  // Build name → canonical cost lookup from authoritative providers first
+  const canonicalCostByName = new Map();
+  for (const providerId of CANONICAL_PROVIDERS) {
+    const provider = data[providerId];
+    if (!provider?.models) continue;
+    for (const model of Object.values(provider.models)) {
+      if (!model.tool_call) continue;
+      const name = model.name;
+      if (name && model.cost?.input !== undefined && !canonicalCostByName.has(name)) {
+        canonicalCostByName.set(name, model.cost.input);
+      }
+    }
+  }
+
+  const models = [];
+  for (const [providerId, provider] of Object.entries(data)) {
+    if (!provider.models) continue;
+    for (const [modelId, model] of Object.entries(provider.models)) {
+      if (!model.tool_call) continue;
+      const name = model.name || modelId;
+      const cost = model.cost?.input;
+      const canonicalCost = canonicalCostByName.get(name);
+      models.push({
+        id: `${providerId}/${modelId}`,
+        name,
+        cost,
+        // canonicalCost: cost from the authoritative provider for this model name.
+        // Defined when cost !== canonicalCost (different provider, reseller, or $0 subscription).
+        canonicalCost: canonicalCost !== undefined && canonicalCost !== cost ? canonicalCost : undefined,
+        context: model.limit?.context,
+      });
+    }
+  }
+  models.sort((a, b) => (a.cost ?? Infinity) - (b.cost ?? Infinity));
+  return models;
+}

package/{src → cli}/utils/paths.js

@@ -6,7 +6,7 @@ import path from 'node:path'
  *
  * These filenames are a contract with every repo the harness has been
  * installed into: the CLI writes them, and the opencode plugins shipped in
- * src/content/.opencode/plugins/ read them back at runtime. Changing a name
+ * harness/.opencode/plugins/ read them back at runtime. Changing a name
  * here means changing it in that payload too, or the plugins go blind.
  *
  * They are deliberately named for the harness rather than for the CLI, so a

package/{src → cli}/utils/process.js

@@ -1,3 +1,3 @@
-export function exit(code = 0) {
-  process.exit(code)
-}
+export function exit(code = 0) {
+  process.exit(code)
+}