kodelyth-ecc 2.24.11 → 2.29.0

package/scripts/super-agent/dag.js

@@ -0,0 +1,123 @@
+// scripts/super-agent/dag.js
+//
+// Pure dependency-graph model for a super-agent run's plan. No I/O. A step is
+//   { id, description, deps: [ids], exitCriteria?, status, ... }
+// and this module answers the only questions the orchestrator needs: which steps
+// are runnable right now, is the plan finished, and is it stuck. Keeping this
+// pure is what makes the whole control plane testable without spawning an agent.
+'use strict';
+
+const STATUS = Object.freeze({
+  PENDING: 'pending',
+  IN_PROGRESS: 'in_progress',
+  DONE: 'done',
+  FAILED: 'failed',
+  SKIPPED: 'skipped',
+});
+
+// Normalize a raw plan into well-formed steps (stable string ids, deps array,
+// a starting status). Ids are coerced to strings so numeric ids from a blueprint
+// and string deps compare correctly.
+function normalizeSteps(steps) {
+  return (Array.isArray(steps) ? steps : []).map((s) => ({
+    status: STATUS.PENDING,
+    ...s,
+    id: String(s && s.id != null ? s.id : ''),
+    deps: Array.isArray(s && s.deps) ? s.deps.map(String) : [],
+  }));
+}
+
+// Validate the plan is a sane DAG: unique non-empty ids, deps that exist, no
+// self-dependency, and no cycles. Returns { ok, errors: [] }.
+function validate(steps) {
+  const errors = [];
+  const ids = new Set();
+  for (const s of steps) {
+    if (!s.id) errors.push('a step has no id');
+    else if (ids.has(s.id)) errors.push(`duplicate step id: ${s.id}`);
+    else ids.add(s.id);
+  }
+  for (const s of steps) {
+    for (const d of s.deps) {
+      if (d === s.id) errors.push(`step ${s.id} depends on itself`);
+      else if (!ids.has(d)) errors.push(`step ${s.id} depends on unknown step ${d}`);
+    }
+  }
+  if (errors.length === 0 && hasCycle(steps)) errors.push('the plan has a dependency cycle');
+  return { ok: errors.length === 0, errors };
+}
+
+// Kahn's algorithm: if we cannot topologically order every step, there is a cycle.
+function hasCycle(steps) {
+  const indeg = new Map(steps.map((s) => [s.id, 0]));
+  const byId = new Map(steps.map((s) => [s.id, s]));
+  for (const s of steps) {
+    for (const d of s.deps) {
+      if (byId.has(d)) indeg.set(s.id, indeg.get(s.id) + 1);
+    }
+  }
+  const queue = [...indeg.entries()].filter(([, n]) => n === 0).map(([id]) => id);
+  const dependents = new Map(steps.map((s) => [s.id, []]));
+  for (const s of steps) {
+    for (const d of s.deps) {
+      if (dependents.has(d)) dependents.get(d).push(s.id);
+    }
+  }
+  let visited = 0;
+  while (queue.length) {
+    const id = queue.shift();
+    visited++;
+    for (const dep of dependents.get(id) || []) {
+      indeg.set(dep, indeg.get(dep) - 1);
+      if (indeg.get(dep) === 0) queue.push(dep);
+    }
+  }
+  return visited !== steps.length;
+}
+
+// Steps that can run now: still pending, with every dependency DONE (or SKIPPED,
+// which counts as satisfied — a skipped step did not fail).
+function readySteps(steps) {
+  const satisfied = new Set(
+    steps.filter((s) => s.status === STATUS.DONE || s.status === STATUS.SKIPPED).map((s) => s.id),
+  );
+  return steps.filter(
+    (s) => s.status === STATUS.PENDING && s.deps.every((d) => satisfied.has(d)),
+  );
+}
+
+function isComplete(steps) {
+  return steps.length > 0 && steps.every((s) => s.status === STATUS.DONE || s.status === STATUS.SKIPPED);
+}
+
+// Stuck: there is still work pending, but nothing is runnable and nothing is in
+// progress — so a dependency failed (or, if validate() passed, it cannot be a
+// cycle). The orchestrator turns this into a halt rather than spinning forever.
+function isStalled(steps) {
+  const pending = steps.filter((s) => s.status === STATUS.PENDING);
+  const running = steps.some((s) => s.status === STATUS.IN_PROGRESS);
+  return pending.length > 0 && !running && readySteps(steps).length === 0;
+}
+
+function progress(steps) {
+  const count = (st) => steps.filter((s) => s.status === st).length;
+  return {
+    total: steps.length,
+    done: count(STATUS.DONE),
+    failed: count(STATUS.FAILED),
+    inProgress: count(STATUS.IN_PROGRESS),
+    pending: count(STATUS.PENDING),
+    skipped: count(STATUS.SKIPPED),
+  };
+}
+
+module.exports = {
+  STATUS,
+  normalizeSteps,
+  validate,
+  hasCycle,
+  readySteps,
+  isComplete,
+  isStalled,
+  progress,
+};

package/scripts/super-agent/integrate.js

@@ -0,0 +1,91 @@
+// scripts/super-agent/integrate.js
+//
+// Branch integration for the super-agent — the piece Agent B flagged as missing:
+// "the swarm fans out but never merges worker branches." Two parts:
+//
+//   mergeOrder(steps)  — PURE. The order to merge worker branches in, respecting
+//                        step dependencies (a dependency's branch merges first).
+//   detectConflicts()  — uses `git merge-tree --write-tree` to find, WITHOUT
+//                        touching the working tree, which branches would conflict
+//                        if merged together.
+//
+// The orchestrator's integrate phase uses this to decide whether to proceed
+// (clean) or stop for a human (conflicts) — see submitIntegration.
+'use strict';
+
+const { spawnSync } = require('child_process');
+
+// Topologically order the done-with-branch steps so a dependency is merged
+// before anything built on top of it. Pure; only reorders what is given.
+function mergeOrder(steps) {
+  const withBranch = (steps || []).filter((s) => s.status === 'done' && s.branch);
+  const ids = new Set(withBranch.map((s) => s.id));
+  const byId = new Map(withBranch.map((s) => [s.id, s]));
+  const indeg = new Map(withBranch.map((s) => [s.id, 0]));
+  for (const s of withBranch) {
+    for (const d of s.deps || []) if (ids.has(String(d))) indeg.set(s.id, indeg.get(s.id) + 1);
+  }
+  // Stable: break ties by original order.
+  const order = [];
+  const queue = withBranch.filter((s) => indeg.get(s.id) === 0).map((s) => s.id);
+  while (queue.length) {
+    const id = queue.shift();
+    order.push(id);
+    for (const s of withBranch) {
+      if ((s.deps || []).map(String).includes(id) && indeg.has(s.id)) {
+        indeg.set(s.id, indeg.get(s.id) - 1);
+        if (indeg.get(s.id) === 0) queue.push(s.id);
+      }
+    }
+  }
+  // Any leftover (shouldn't happen for a validated plan) appended in input order.
+  for (const s of withBranch) if (!order.includes(s.id)) order.push(s.id);
+  return order.map((id) => ({ step: id, branch: byId.get(id).branch }));
+}
+
+function branchNames(branches) {
+  return (branches || [])
+    .map((b) => (typeof b === 'string' ? b : b && b.branch))
+    .filter(Boolean);
+}
+
+// Does merging branchB into branchA conflict? No working-tree side effects.
+function pairConflicts(repoRoot, branchA, branchB) {
+  const r = spawnSync('git', ['merge-tree', '--write-tree', branchA, branchB], {
+    cwd: repoRoot, encoding: 'utf8', maxBuffer: 32 * 1024 * 1024,
+  });
+  if (r.status === 0) return { conflict: false };
+  if (r.status === 1) return { conflict: true, files: parseConflictFiles(r.stdout) };
+  return { conflict: false, error: (r.stderr || '').trim() || `git merge-tree exited ${r.status}` };
+}
+
+// Best-effort: pull file paths out of merge-tree's conflict section. The first
+// line is the tree oid; conflict detail follows. Version-tolerant — we just keep
+// anything that looks like a path, deduped.
+function parseConflictFiles(stdout) {
+  const files = new Set();
+  for (const line of String(stdout || '').split('\n').slice(1)) {
+    const m = line.match(/(?:^|\s)([\w.\-/]+\.[\w]+)(?:\s|$)/);
+    if (m) files.add(m[1]);
+  }
+  return [...files];
+}
+
+// Pairwise conflict scan across all worker branches. Catches the common case —
+// two workers editing the same file — before any real merge happens. Returns
+// { clean, conflicts: [{ branches:[a,b], files:[] }], errors: [] }.
+function detectConflicts(repoRoot, branches) {
+  const names = branchNames(branches);
+  const conflicts = [];
+  const errors = [];
+  for (let i = 0; i < names.length; i++) {
+    for (let j = i + 1; j < names.length; j++) {
+      const c = pairConflicts(repoRoot, names[i], names[j]);
+      if (c.error) errors.push({ branches: [names[i], names[j]], error: c.error });
+      else if (c.conflict) conflicts.push({ branches: [names[i], names[j]], files: c.files || [] });
+    }
+  }
+  return { clean: conflicts.length === 0, conflicts, errors };
+}
+
+module.exports = { mergeOrder, detectConflicts, pairConflicts, parseConflictFiles, branchNames };

package/scripts/super-agent/orchestrator.js

@@ -0,0 +1,175 @@
+// scripts/super-agent/orchestrator.js
+//
+// The super-agent driver — the piece Agent B found missing. It is an Arena-style
+// state machine: a PURE nextAction(run) decides what to do next, and the driving
+// LLM performs that action (decompose with blueprint, dispatch via the swarm,
+// evaluate with the GAN loop, integrate branches, verify) and reports back
+// through a submit* function, which advances the run and persists it.
+//
+//   plan ──decompose──▶ execute ──(all steps done)──▶ integrate ──▶ verify ──▶ done
+//                         │
+//                         └─ dispatch ready steps (deps satisfied), budget-gated
+//
+// nextAction never mutates, so the whole control plane is tested without spawning
+// a single agent. Mutations + phase transitions live in the submit* recorders.
+'use strict';
+
+const dag = require('./dag.js');
+const state = require('./state.js');
+const { PHASE } = state;
+
+// Rough per-step token estimate for the budget gate. Deliberately conservative;
+// real spend is accrued from what the driver reports.
+const DEFAULT_STEP_TOKENS = 4000;
+
+function estimateTokens(steps) {
+  return (steps.length || 1) * DEFAULT_STEP_TOKENS;
+}
+
+function stepBrief(s) {
+  return {
+    id: s.id,
+    description: s.description || '',
+    deps: s.deps || [],
+    contextBrief: s.contextBrief || s.context || '',
+    exitCriteria: s.exitCriteria || s.exit || '',
+  };
+}
+
+function branchesOf(run) {
+  return run.steps
+    .filter((s) => s.status === dag.STATUS.DONE && s.branch)
+    .map((s) => ({ step: s.id, branch: s.branch }));
+}
+
+// ── The state machine (pure) ─────────────────────────────────────────────────
+function nextAction(run) {
+  if (!run || run.status !== 'running') {
+    return { action: 'report', reason: (run && (run.stopReason || run.status)) || 'no run', run: run && state.summarize(run) };
+  }
+
+  switch (run.phase) {
+    case PHASE.PLAN:
+      // No plan yet → ask the driver to decompose the goal into a step DAG.
+      return { action: 'decompose', goal: run.goal, scope: run.scope };
+
+    case PHASE.EXECUTE: {
+      if (dag.isStalled(run.steps)) {
+        return { action: 'halt', reason: 'plan stalled — a dependency failed, so no remaining step can run' };
+      }
+      const ready = dag.readySteps(run.steps);
+      if (ready.length === 0) {
+        // Not stalled and nothing ready → steps are in progress; wait for results.
+        return { action: 'await', inProgress: run.steps.filter((s) => s.status === dag.STATUS.IN_PROGRESS).map((s) => s.id) };
+      }
+      const afford = state.canAfford(run, estimateTokens(ready));
+      if (!afford.ok) return { action: 'halt', reason: `budget: ${afford.reason}` };
+      return { action: 'dispatch', parallel: ready.length > 1, steps: ready.map(stepBrief) };
+    }
+
+    case PHASE.INTEGRATE:
+      return { action: 'integrate', branches: branchesOf(run), scope: run.scope };
+
+    case PHASE.VERIFY:
+      return { action: 'verify', scope: run.scope };
+
+    case PHASE.DONE:
+      return { action: 'report', reason: 'done', run: state.summarize(run) };
+
+    default:
+      return { action: 'report', reason: `unknown phase: ${run.phase}`, run: state.summarize(run) };
+  }
+}
+
+// ── Recorders (mutate + advance + persist) ───────────────────────────────────
+
+// The driver decomposed the goal (via blueprint). Install the plan.
+function submitPlan(run, rawSteps, { persist = true } = {}) {
+  requirePhase(run, PHASE.PLAN);
+  const steps = dag.normalizeSteps(rawSteps);
+  const v = dag.validate(steps);
+  if (!v.ok) throw new Error(`super-agent: invalid plan — ${v.errors.join('; ')}`);
+  if (steps.length === 0) throw new Error('super-agent: plan has no steps');
+  run.steps = steps;
+  run.phase = PHASE.EXECUTE;
+  state.record(run, { event: 'planned', steps: steps.length });
+  return persist ? state.save(run) : run;
+}
+
+// Mark a step as about to run (so nextAction reports it as in-progress, not ready).
+function markDispatched(run, stepIds, { persist = true } = {}) {
+  const want = new Set((Array.isArray(stepIds) ? stepIds : [stepIds]).map(String));
+  for (const s of run.steps) {
+    if (want.has(s.id) && s.status === dag.STATUS.PENDING) s.status = dag.STATUS.IN_PROGRESS;
+  }
+  state.record(run, { event: 'dispatched', steps: [...want] });
+  return persist ? state.save(run) : run;
+}
+
+// The driver finished a step. Record result + budget, then advance the phase if
+// the plan is now complete or stalled.
+function submitStepResult(run, stepId, { status = dag.STATUS.DONE, branch = null, result = null, tokensSpent = 0 } = {}, { persist = true } = {}) {
+  const s = run.steps.find((x) => x.id === String(stepId));
+  if (!s) throw new Error(`super-agent: unknown step ${stepId}`);
+  s.status = status;
+  if (branch) s.branch = branch;
+  if (result != null) s.result = result;
+  state.accrue(run, { tokensSpent, steps: 1 });
+  state.record(run, { event: 'step', step: s.id, status, tokensSpent });
+
+  if (dag.isComplete(run.steps)) {
+    run.phase = PHASE.INTEGRATE;
+  } else if (dag.isStalled(run.steps)) {
+    state.stop(run, 'plan stalled after a step failed');
+  }
+  return persist ? state.save(run) : run;
+}
+
+// The driver merged the worker branches.
+function submitIntegration(run, { merged = true, conflicts = [], tokensSpent = 0 } = {}, { persist = true } = {}) {
+  requirePhase(run, PHASE.INTEGRATE);
+  state.accrue(run, { tokensSpent });
+  if (Array.isArray(conflicts) && conflicts.length > 0) {
+    state.record(run, { event: 'integration-conflicts', conflicts });
+    state.stop(run, `integration conflicts in: ${conflicts.join(', ')}`);
+  } else if (!merged) {
+    state.stop(run, 'integration reported not merged');
+  } else {
+    run.phase = PHASE.VERIFY;
+    state.record(run, { event: 'integrated' });
+  }
+  return persist ? state.save(run) : run;
+}
+
+// The driver ran the verification gate (tests/build).
+function submitVerification(run, { passed = false, detail = '', tokensSpent = 0 } = {}, { persist = true } = {}) {
+  requirePhase(run, PHASE.VERIFY);
+  state.accrue(run, { tokensSpent });
+  if (passed) {
+    run.phase = PHASE.DONE;
+    run.status = 'done';
+    state.record(run, { event: 'verified', detail });
+  } else {
+    run.status = 'failed';
+    run.stopReason = `verification failed: ${detail || 'tests/build did not pass'}`;
+    state.record(run, { event: 'verification-failed', detail });
+  }
+  return persist ? state.save(run) : run;
+}
+
+function requirePhase(run, expected) {
+  if (run.phase !== expected) {
+    throw new Error(`super-agent: expected phase "${expected}" but run is in "${run.phase}"`);
+  }
+}
+
+module.exports = {
+  nextAction,
+  submitPlan,
+  markDispatched,
+  submitStepResult,
+  submitIntegration,
+  submitVerification,
+  estimateTokens,
+  DEFAULT_STEP_TOKENS,
+};

package/scripts/super-agent/state.js

@@ -0,0 +1,136 @@
+// scripts/super-agent/state.js
+//
+// Run lifecycle, persistence (so a run resumes after a crash or a new session),
+// and the budget governor for the super-agent orchestrator. Mirrors the pattern
+// of scripts/arena/state.js: the control plane is tokenless and durable, so the
+// expensive part (actually running agents) can stop and pick up again.
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+const safeFs = require('../lib/safe-fs.js');
+const dag = require('./dag.js');
+
+const RUN_DIR = process.env.KODELYTH_SUPER_AGENT_DIR
+  || path.join(os.homedir(), '.kodelythecc', 'super-agent');
+
+const PHASE = Object.freeze({
+  PLAN: 'plan',
+  EXECUTE: 'execute',
+  INTEGRATE: 'integrate',
+  VERIFY: 'verify',
+  DONE: 'done',
+});
+
+function runPath(id) {
+  return path.join(RUN_DIR, `${id}.json`);
+}
+
+function createRun({ goal, limits = {}, scope = '.' } = {}) {
+  if (!goal || !String(goal).trim()) throw new Error('super-agent: a run needs a goal');
+  return {
+    id: crypto.randomBytes(6).toString('hex'),
+    goal: String(goal).trim(),
+    scope,
+    createdAt: new Date().toISOString(),
+    status: 'running',           // running | done | failed | stopped
+    phase: PHASE.PLAN,
+    steps: [],
+    budget: {
+      // 0 / null means "no cap". Caps are the governor Agent B flagged as missing
+      // — a single per-session token-budget could not bound a whole run.
+      tokenCap: limits.tokenCap || 0,
+      stepCap: limits.stepCap || 0,
+      tokensSpent: 0,
+      stepsRun: 0,
+    },
+    history: [],
+    stopReason: null,
+  };
+}
+
+function record(run, event) {
+  run.history.push({ at: new Date().toISOString(), ...event });
+}
+
+// Budget governor. Returns { ok, reason? }. Checks both the token cap and the
+// step cap; an estimate of 0 still fails if we are already over.
+function canAfford(run, estTokens = 0) {
+  const b = run.budget;
+  if (b.stepCap && b.stepsRun >= b.stepCap) {
+    return { ok: false, reason: `step cap reached (${b.stepsRun}/${b.stepCap})` };
+  }
+  if (b.tokenCap && b.tokensSpent + estTokens > b.tokenCap) {
+    return { ok: false, reason: `token cap would be exceeded (${b.tokensSpent}+${estTokens} > ${b.tokenCap})` };
+  }
+  return { ok: true };
+}
+
+function accrue(run, { tokensSpent = 0, steps = 0 } = {}) {
+  run.budget.tokensSpent += Math.max(0, tokensSpent) || 0;
+  run.budget.stepsRun += Math.max(0, steps) || 0;
+}
+
+function stop(run, reason) {
+  run.status = 'stopped';
+  run.stopReason = reason;
+  record(run, { event: 'stopped', reason });
+}
+
+function save(run) {
+  fs.mkdirSync(RUN_DIR, { recursive: true });
+  // Atomic: a crash mid-write must not corrupt a resumable run.
+  safeFs.replaceFileAtomic(runPath(run.id), JSON.stringify(run, null, 2) + '\n', 0o600);
+  return run;
+}
+
+function load(id) {
+  const raw = fs.readFileSync(runPath(id), 'utf8');
+  return JSON.parse(raw);
+}
+
+function exists(id) {
+  return fs.existsSync(runPath(id));
+}
+
+function list() {
+  if (!fs.existsSync(RUN_DIR)) return [];
+  return fs.readdirSync(RUN_DIR)
+    .filter((f) => f.endsWith('.json'))
+    .map((f) => {
+      try { return JSON.parse(fs.readFileSync(path.join(RUN_DIR, f), 'utf8')); }
+      catch { return null; }
+    })
+    .filter(Boolean)
+    .sort((a, b) => String(b.createdAt).localeCompare(String(a.createdAt)));
+}
+
+function summarize(run) {
+  return {
+    id: run.id,
+    goal: run.goal,
+    status: run.status,
+    phase: run.phase,
+    progress: dag.progress(run.steps),
+    budget: run.budget,
+    stopReason: run.stopReason,
+  };
+}
+
+module.exports = {
+  PHASE,
+  RUN_DIR,
+  runPath,
+  createRun,
+  record,
+  canAfford,
+  accrue,
+  stop,
+  save,
+  load,
+  exists,
+  list,
+  summarize,
+};

package/scripts/terse/ledger.js

@@ -1,9 +1,16 @@
 // scripts/terse/ledger.js
-// Output-token savings ledger. Stores one JSONL row per terse-active turn.
-// Zero deps. Reads only. Writes append-only.
+// Output-token savings ledger. Stores one JSONL row per recorded terse turn.
+// Zero deps. Writes append-only.
+//
+// IMPORTANT — these rows are ESTIMATES, not measured savings. There is no
+// non-terse copy of the same reply to diff against, so `saved` is modeled:
+// actual output tokens times a per-level baseline multiplier (RAW_MULT below).
+// Every figure here is an estimate and each row is flagged `estimated: true`.
+// (The Terse *file* compressor in compress.js, by contrast, reports real,
+// measured before/after bytes.)
 //
 // Row shape:
-//   { ts, level, rawEstimate, actual, saved, projectHash?, source }
+//   { ts, level, rawEstimate, actual, saved, estimated, baseline, projectHash?, source }
 //
 // Path: ~/.kodelythecc/terse/ledger.jsonl (overridable via KODELYTH_TERSE_DIR)
 
@@ -31,8 +38,10 @@ function estimateTokens(text) {
   return Math.round(Buffer.byteLength(text, 'utf8') / 4);
 }
 
-// Baseline output multiplier per level.
-// Empirically: full ≈ 0.5x normal, ultra ≈ 0.35x, lite ≈ 0.75x.
+// Per-level baseline multiplier used to MODEL what the same reply would have
+// cost without terse (full ≈ 2x the terse size, ultra ≈ 2.85x, lite ≈ 1.33x).
+// These are assumptions, not measurements — every `saved` figure derived from
+// them is an estimate, which is why each row is flagged `estimated: true`.
 const RAW_MULT = { lite: 1.33, full: 2.0, ultra: 2.85, off: 1.0 };
 
 function appendTurn({ actualText, level = 'full', source = 'unknown', projectHash = null }) {
@@ -46,6 +55,8 @@ function appendTurn({ actualText, level = 'full', source = 'unknown', projectHas
     rawEstimate,
     actual,
     saved,
+    estimated: true,                 // modeled from RAW_MULT, not a measured A/B
+    baseline: RAW_MULT[level] || 1,
     source,
     ...(projectHash ? { projectHash } : {}),
   };

package/skills/terse-mode/SKILL.md

@@ -83,7 +83,7 @@ Example — ~70% shorter:
 
 - Slash command: `/terse [lite|full|ultra|off]` — sticks for the session
 - CLI: `kodelyth-ecc terse enable [--target claude-code|--all]` — installs the skill + command into your AI tool
-- Statusline (Claude Code): shows `[TERSE ⚡ 12.4k]` — lifetime output tokens saved
+- Dashboard (Claude Code): the **Token Savings** tab shows lifetime *estimated* output savings from the terse ledger — modeled, not measured (see the ledger note in `docs/terse-mode.md`)
 
 ## Honest numbers