@quadiusai/dsh-greenharness 0.0.0-stage → 0.1.1

package/src/config.mjs

@@ -0,0 +1,100 @@
+import { DEFAULT_VERIFIER_PATTERNS, compileVerifierPatterns } from './core/verify.mjs'
+
+/**
+ * Validate and complete the plugin configuration. Misconfiguration fails at load: a tier
+ * without a provider and model, a non-integer threshold, or an invalid verifier pattern throws
+ * here rather than silently changing routing later.
+ *
+ * @param {Record<string, any>} raw - the configuration DSH validated against the plugin schema.
+ * @returns {{
+ *   tiers: { small?: Route, large?: Route },
+ *   routing: { enabled: boolean },
+ *   cascade: { escalateAfterFailures: number, deescalateAfterPasses: number, minStepsPerTier: number },
+ *   verifier: { patterns: string[] },
+ *   distill: { enabled: boolean, maxChars: number, contextLines: number },
+ *   readDedupe: { enabled: boolean },
+ *   loopBreaker: { enabled: boolean, threshold: number },
+ *   ledger: { path: string, pricing: Record<string, Price> },
+ * }} complete settings with every default applied.
+ */
+export function normalizeSettings(raw) {
+  const tiers = raw?.tiers ?? {}
+  // Tiers are optional. Without a large tier, routing stays off and only the other mechanisms run.
+  const small = isSetRoute(tiers.small) ? normalizeRoute(tiers.small, 'tiers.small') : undefined
+  const large = isSetRoute(tiers.large) ? normalizeRoute(tiers.large, 'tiers.large') : undefined
+
+  const cascade = {
+    escalateAfterFailures: integerAtLeast(raw.cascade?.escalateAfterFailures ?? 1, 1, 'cascade.escalateAfterFailures'),
+    deescalateAfterPasses: integerAtLeast(raw.cascade?.deescalateAfterPasses ?? 2, 1, 'cascade.deescalateAfterPasses'),
+    minStepsPerTier: integerAtLeast(raw.cascade?.minStepsPerTier ?? 2, 0, 'cascade.minStepsPerTier'),
+  }
+
+  const patterns = raw.verifier?.patterns?.length ? [...raw.verifier.patterns] : [...DEFAULT_VERIFIER_PATTERNS]
+  try {
+    compileVerifierPatterns(patterns)
+  } catch (error) {
+    throw new Error(`greenharness: verifier.patterns has an invalid regular expression: ${String(error)}`)
+  }
+
+  return {
+    tiers: { small, large },
+    routing: { enabled: large !== undefined },
+    cascade,
+    verifier: { patterns },
+    distill: {
+      enabled: raw.distill?.enabled ?? true,
+      maxChars: integerAtLeast(raw.distill?.maxChars ?? 6000, 500, 'distill.maxChars'),
+      contextLines: integerAtLeast(raw.distill?.contextLines ?? 2, 0, 'distill.contextLines'),
+    },
+    readDedupe: { enabled: raw.readDedupe?.enabled ?? true },
+    loopBreaker: {
+      enabled: raw.loopBreaker?.enabled ?? true,
+      threshold: integerAtLeast(raw.loopBreaker?.threshold ?? 3, 2, 'loopBreaker.threshold'),
+    },
+    ledger: {
+      path: raw.ledger?.path ?? '.greenharness/ledger.jsonl',
+      pricing: raw.ledger?.pricing ?? {},
+    },
+  }
+}
+
+/**
+ * @typedef {{ provider: string, model: string, reasoningEffort: string }} Route
+ * @typedef {{ inputPerMTok?: number, cachedInputPerMTok?: number, outputPerMTok?: number }} Price
+ */
+
+/**
+ * A tier is set when it names a provider or a model. An empty tier (from a schema default) is unset,
+ * and a half-written tier still fails in normalizeRoute.
+ * @param {{ provider?: string, model?: string } | undefined} route
+ */
+function isSetRoute(route) {
+  return Boolean(route && (route.provider || route.model))
+}
+
+/**
+ * Normalize one tier route.
+ * @param {{ provider?: string, model?: string, reasoningEffort?: string } | undefined} route - the configured route.
+ * @param {string} label - configuration path, for error messages.
+ * @returns {Route} the route; an empty reasoningEffort means the adapter default.
+ */
+function normalizeRoute(route, label) {
+  if (!route || !route.provider || !route.model) {
+    throw new Error(`greenharness: ${label} needs both \`provider\` and \`model\``)
+  }
+  return { provider: String(route.provider), model: String(route.model), reasoningEffort: String(route.reasoningEffort ?? '') }
+}
+
+/**
+ * Require an integer at or above a minimum.
+ * @param {unknown} value - the configured value.
+ * @param {number} min - the smallest accepted value.
+ * @param {string} label - configuration path, for error messages.
+ * @returns {number} the value.
+ */
+function integerAtLeast(value, min, label) {
+  if (!Number.isInteger(value) || value < min) {
+    throw new Error(`greenharness: ${label} must be an integer >= ${min} (got ${String(value)})`)
+  }
+  return value
+}

package/src/control.mjs

@@ -0,0 +1,261 @@
+/**
+ * The /greenharness slash command: parsing, and the replies it gives. These are pure functions
+ * over a host object, so they can be tested without DSH.
+ *
+ * host = { control: { paused: boolean }, settings, runtime }
+ *
+ * @module @quadiusai/dsh-greenharness/control
+ */
+
+/** Mechanisms that can be switched on or off by name. */
+const TOGGLES = new Set(['distill', 'dedupe', 'loop', 'routing'])
+
+export const HELP = [
+  'GREENHARNESS: HOW TO USE IT',
+  '',
+  'It starts saving tokens on its own. These commands let you steer it.',
+  '',
+  'SEE WHAT IT IS DOING',
+  '  /greenharness                 summary: tokens saved, progress bar, models',
+  '',
+  'CHOOSE MODELS (the cheap one for easy steps, a strong one for hard steps)',
+  '  /greenharness models          list the models you have set up in DSH, numbered',
+  '  /greenharness large 3         use model number 3 from that list as the strong model',
+  '  /greenharness large nvidia Nemotron 3 Ultra',
+  '                                or type part of its name, the provider first is optional',
+  '  /greenharness small 1         set the cheap model (default: whatever DSH already uses)',
+  '  Add API keys first in DSH: Settings > Models.',
+  '',
+  'TURN THINGS ON OR OFF',
+  '  /greenharness on | off        resume or pause everything',
+  '  /greenharness routing on|off  switching between the cheap and strong model',
+  '  /greenharness distill on|off  shorten very long command output',
+  '  /greenharness dedupe on|off   replace a repeated file read with a short pointer',
+  '  /greenharness loop on|off     stop a command that keeps failing the same way',
+  '',
+  'Settings last until DSH restarts.',
+].join('\n')
+
+const EFFORTS = new Set(['minimal', 'low', 'medium', 'high', 'xhigh', 'max'])
+
+/**
+ * Parse the text after `/greenharness`.
+ * @param {string} rawInput
+ * @returns {{ action: 'status' | 'help' } | { action: 'pause', paused: boolean }
+ *   | { action: 'toggle', mechanism: string, enabled: boolean }
+ *   | { action: 'models' } | { action: 'tier', tier: 'small' | 'large', args: string[] }
+ *   | { action: 'error', message: string }}
+ */
+export function parseCommand(rawInput = '') {
+  const [first = 'status', ...args] = String(rawInput).trim().split(/\s+/).filter(Boolean)
+  const verb = first.toLowerCase()
+  if (verb === 'status' || verb === 'help') {
+    return args.length === 0 ? { action: verb } : usage(`/greenharness ${verb}`)
+  }
+  if (verb === 'on' || verb === 'off') {
+    return args.length === 0 ? { action: 'pause', paused: verb === 'off' } : usage(`/greenharness ${verb}`)
+  }
+  if (TOGGLES.has(verb)) {
+    const value = (args[0] ?? '').toLowerCase()
+    if (args.length !== 1 || (value !== 'on' && value !== 'off')) return usage(`/greenharness ${verb} on|off`)
+    return { action: 'toggle', mechanism: verb, enabled: value === 'on' }
+  }
+  if (verb === 'models') return args.length === 0 ? { action: 'models' } : usage('/greenharness models')
+  if (verb === 'large' || verb === 'small') return { action: 'tier', tier: verb, args }
+  return { action: 'error', message: `Unknown command "${first}". Try /greenharness help.` }
+}
+
+/**
+ * Run one command and return the reply DSH shows.
+ * @param {string} rawInput
+ * @param {{ control: { paused: boolean }, settings: any, runtime: { stats(): Record<string, number> } }} host
+ * @returns {Promise<{ kind: 'success' | 'error', text: string }>}
+ */
+export async function runCommand(rawInput, host) {
+  const command = parseCommand(rawInput)
+  switch (command.action) {
+    case 'error': return fail(command.message)
+    case 'help': return ok(HELP)
+    case 'status': return ok(statusText(host))
+    case 'pause':
+      host.control.paused = command.paused
+      return ok(command.paused ? 'GreenHarness paused. Tool output and model routing are left alone.' : 'GreenHarness resumed.')
+    case 'toggle': return toggle(command, host)
+    case 'models': return showModels(host)
+    case 'tier': return setTier(command, host)
+    default: return fail('Unknown command. Try /greenharness help.')
+  }
+}
+
+/**
+ * The status reply: switches, models, and what this process has done so far.
+ * @param {{ control: { paused: boolean }, settings: any, runtime: { stats(): Record<string, number> } }} host
+ */
+export function statusText({ control, settings, runtime }) {
+  const stats = runtime.stats()
+  const count = key => stats[key] ?? 0
+  const describe = route => (route ? `${route.provider}/${route.model}` : 'not set')
+  const small_ = settings.tiers.small
+    ? describe(settings.tiers.small)
+    : 'the model DSH uses (recorded at the first routed call)'
+  const savedTokens = Math.round(count('charsSaved') / 4)
+  const smallTok = count('smallTokens')
+  const large = count('largeTokens')
+  const spent = smallTok + large
+  const cheapShare = spent === 0 ? 0 : smallTok / spent
+  const lines = [
+    `GreenHarness is ${control.paused ? 'PAUSED' : 'ON'}`,
+    '',
+    `Tokens saved so far: about ${savedTokens.toLocaleString('en-US')}`,
+    `  (long outputs shortened: ${count('tool:distill')}, repeated reads replaced: ${count('tool:dedupe')}, loops stopped: ${count('loop-break')})`,
+    `Work done by the cheap model: ${bar(cheapShare)} ${Math.round(cheapShare * 100)}%`,
+    `Model calls: ${count('request')}. Switches between models: ${count('route')}.`,
+  ]
+  if (count('costUsd') > 0) lines.push(`Cost so far: $${count('costUsd').toFixed(4)}`)
+  lines.push(
+    '',
+    `Models: small = ${small_}, large = ${describe(settings.tiers.large)}. Routing ${onOff(settings.routing.enabled)}.`,
+    `Features: shorten output ${onOff(settings.distill.enabled)}, repeated reads ${onOff(settings.readDedupe.enabled)}, loop stop ${onOff(settings.loopBreaker.enabled)}.`,
+    ...(settings.tiers.large ? [] : ['Next step: type /greenharness models, then /greenharness large <number> to add a strong model.']),
+    'All commands: /greenharness help',
+  )
+  return lines.join('\n')
+}
+
+/** A 20-cell text progress bar. @param {number} fraction 0..1 */
+export function bar(fraction) {
+  const filled = Math.max(0, Math.min(20, Math.round(fraction * 20)))
+  return '[' + '█'.repeat(filled) + '░'.repeat(20 - filled) + ']'
+}
+
+/** @param {{ mechanism: string, enabled: boolean }} command @param {{ settings: any }} host */
+function toggle({ mechanism, enabled }, { settings }) {
+  if (mechanism === 'routing') {
+    if (enabled && settings.tiers.large === undefined) {
+      return fail('Routing needs a large model first: /greenharness large <provider> <model>')
+    }
+    settings.routing.enabled = enabled
+    return ok(`Routing ${onOff(enabled)}.`)
+  }
+  const owner = { distill: settings.distill, dedupe: settings.readDedupe, loop: settings.loopBreaker }[mechanism]
+  owner.enabled = enabled
+  return ok(`${mechanism === 'loop' ? 'Loop breaker' : mechanism[0].toUpperCase() + mechanism.slice(1)} ${onOff(enabled)}.`)
+}
+
+const norm = text => String(text).toLowerCase().replace(/[^a-z0-9]/g, '')
+
+/**
+ * Every model DSH knows about, numbered. Providers that cannot list models are skipped quietly.
+ * @param {{ llm?: any }} host
+ * @returns {Promise<{ n: number, provider: string, providerName: string, id: string, name: string }[]>}
+ */
+async function loadListing(host) {
+  const entries = []
+  if (host.llm === undefined) return entries
+  for (const provider of host.llm.listProviders()) {
+    let models = []
+    try {
+      models = await host.llm.listModels(provider.id)
+    } catch {
+      continue
+    }
+    for (const model of models) {
+      entries.push({ n: entries.length + 1, provider: provider.id, providerName: provider.name, id: model.id, name: model.name })
+    }
+  }
+  host.listing = entries
+  return entries
+}
+
+const row = e => `  ${String(e.n).padStart(2)}. ${e.name}   (${e.providerName}, id ${e.id})`
+
+/** @param {{ llm?: any, listing?: any[] }} host */
+async function showModels(host) {
+  const entries = await loadListing(host)
+  if (entries.length === 0) {
+    return ok([
+      'DSH has no models to list yet.',
+      'Add your API key and models first: open Settings > Models in DSH, then run /greenharness models again.',
+    ].join('\n'))
+  }
+  return ok([
+    'MODELS YOU CAN CHOOSE FROM',
+    ...entries.map(row),
+    '',
+    'Pick the strong one:   /greenharness large <number>      e.g. /greenharness large 3',
+    'Pick the cheap one:    /greenharness small <number>',
+  ].join('\n'))
+}
+
+/**
+ * Work out which model the user meant: a list number, or words from its name with an optional
+ * provider first and an optional reasoning effort last.
+ * @param {string[]} args
+ * @param {{ llm?: any, listing?: any[] }} host
+ * @returns {Promise<{ route: { provider: string, model: string, reasoningEffort: string }, label: string } | { error: string }>}
+ */
+async function resolveModel(args, host) {
+  let effort = ''
+  if (args.length > 1 && EFFORTS.has(args[args.length - 1].toLowerCase())) effort = args[args.length - 1].toLowerCase()
+  const words = effort === '' ? args : args.slice(0, -1)
+  if (words.length === 0) return { error: 'Which model? Run /greenharness models to see the list, then use its number.' }
+  const entries = host.listing?.length ? host.listing : await loadListing(host)
+  const pick = e => ({ route: { provider: e.provider, model: e.id, reasoningEffort: effort }, label: `${e.name} (${e.providerName})` })
+  if (words.length === 1 && /^\d+$/.test(words[0])) {
+    const hit = entries.find(e => e.n === Number(words[0]))
+    return hit ? pick(hit) : { error: `There is no model number ${words[0]}. Run /greenharness models to see the list.` }
+  }
+  if (host.llm === undefined) {
+    if (words.length < 2) return { error: 'Use: /greenharness large <provider> <model>' }
+    return { route: { provider: words[0], model: words.slice(1).join(' '), reasoningEffort: effort }, label: `${words[0]}/${words.slice(1).join(' ')}` }
+  }
+  const providers = host.llm.listProviders()
+  const owner = providers.find(p => norm(p.id) === norm(words[0]) || norm(p.name) === norm(words[0]))
+  const rest = owner ? words.slice(1) : words
+  const pool = owner ? entries.filter(e => e.provider === owner.id) : entries
+  const query = norm(rest.join(''))
+  if (query === '') return { error: `Which model from ${owner.name}? Run /greenharness models to see the list.` }
+  const exact = pool.filter(e => norm(e.id) === query || norm(e.name) === query)
+  const near = exact.length > 0 ? exact : pool.filter(e => norm(e.id).includes(query) || norm(e.name).includes(query))
+  if (near.length === 1) return pick(near[0])
+  if (near.length > 1) {
+    return { error: ['That matches several models. Pick one by number:', ...near.map(row)].join('\n') }
+  }
+  if (owner && rest.length === 1) {
+    return { route: { provider: owner.id, model: rest[0], reasoningEffort: effort }, label: `${rest[0]} (${owner.name}, typed id)` }
+  }
+  return { error: `I could not find a model matching "${rest.join(' ')}". Run /greenharness models to see what DSH has. Add keys and models in Settings > Models.` }
+}
+
+/** @param {{ tier: 'small' | 'large', args: string[] }} command @param {{ settings: any, llm?: any, listing?: any[] }} host */
+async function setTier({ tier, args }, host) {
+  if (args.length === 0) return showModels(host)
+  const found = await resolveModel(args, host)
+  if ('error' in found) return fail(found.error)
+  host.settings.tiers[tier] = found.route
+  if (tier === 'large') {
+    host.settings.routing.enabled = true
+    return ok(`Strong model set to ${found.label}.\nSwitching is ON: GreenHarness will use it when the cheap model keeps failing tests, then go back.\nType /greenharness to watch it work.`)
+  }
+  return ok(`Cheap model set to ${found.label}.`)
+}
+
+/** @param {string} message */
+function usage(message) {
+  return { action: 'error', message: `Usage: ${message}` }
+}
+
+/** @param {boolean} value */
+function onOff(value) {
+  return value ? 'on' : 'off'
+}
+
+/** @param {string} text */
+function ok(text) {
+  return { kind: 'success', text }
+}
+
+/** @param {string} text */
+function fail(text) {
+  return { kind: 'error', text }
+}

package/src/core/ansi.mjs

@@ -0,0 +1,15 @@
+/**
+ * Terminal control sequences: CSI (colors, cursor moves), OSC (titles, hyperlinks) and
+ * single-character escapes. Removing them makes line counts and fingerprints reflect
+ * visible text only.
+ */
+const ANSI_RE = /\u001b\[[0-?]*[ -/]*[@-~]|\u001b\][^\u0007\u001b]*(?:\u0007|\u001b\\)|\u001b[@-Z\\-_]/g
+
+/**
+ * Remove terminal control sequences from text.
+ * @param {string} text - raw terminal output.
+ * @returns {string} the same text without control sequences.
+ */
+export function stripAnsi(text) {
+  return text.replace(ANSI_RE, '')
+}

package/src/core/cascade.mjs

@@ -0,0 +1,81 @@
+/**
+ * Two-tier model cascade: a small model runs by default; a verifier failure moves the next
+ * step to the large model; verifier passes move back once they are stable. Pure state
+ * machine: callers read the returned change and apply it to the agent.
+ */
+
+/** Default policy: escalate on the first failure, return after two passes, and stay at least two steps per tier. */
+export const DEFAULT_CASCADE_POLICY = Object.freeze({
+  escalateAfterFailures: 1,
+  deescalateAfterPasses: 2,
+  minStepsPerTier: 2,
+})
+
+/**
+ * Create cascade state for one session.
+ * @param {Partial<typeof DEFAULT_CASCADE_POLICY>} [policy] - overrides for the default policy.
+ * @returns {{ policy: typeof DEFAULT_CASCADE_POLICY, tier: 'small' | 'large', stepsInTier: number, consecutiveFailures: number, consecutivePasses: number }}
+ */
+export function createCascade(policy = {}) {
+  return {
+    policy: { ...DEFAULT_CASCADE_POLICY, ...policy },
+    tier: 'small',
+    stepsInTier: 0,
+    consecutiveFailures: 0,
+    consecutivePasses: 0,
+  }
+}
+
+/**
+ * Count one completed model step in the current tier.
+ * @param {ReturnType<typeof createCascade>} cascade - the session's cascade state (mutated).
+ */
+export function recordStep(cascade) {
+  cascade.stepsInTier += 1
+}
+
+/**
+ * Apply a verifier outcome to the cascade.
+ * @param {ReturnType<typeof createCascade>} cascade - the session's cascade state (mutated).
+ * @param {boolean} passed - whether the verifier command passed.
+ * @returns {{ from: string, to: string, reason: string } | null} the tier change, or null when the tier stays.
+ */
+export function recordVerification(cascade, passed) {
+  if (passed) {
+    cascade.consecutiveFailures = 0
+    cascade.consecutivePasses += 1
+    const stable = cascade.consecutivePasses >= cascade.policy.deescalateAfterPasses
+      && cascade.stepsInTier >= cascade.policy.minStepsPerTier
+    return cascade.tier === 'large' && stable ? switchTier(cascade, 'small', 'verifier-passed') : null
+  }
+  cascade.consecutivePasses = 0
+  cascade.consecutiveFailures += 1
+  const escalate = cascade.consecutiveFailures >= cascade.policy.escalateAfterFailures
+  return cascade.tier === 'small' && escalate ? switchTier(cascade, 'large', 'verifier-failed') : null
+}
+
+/**
+ * Force the large tier, for example when the loop breaker fires.
+ * @param {ReturnType<typeof createCascade>} cascade - the session's cascade state (mutated).
+ * @param {string} reason - audit reason recorded with the change.
+ * @returns {{ from: string, to: string, reason: string } | null} the tier change, or null when already large.
+ */
+export function escalate(cascade, reason) {
+  return cascade.tier === 'large' ? null : switchTier(cascade, 'large', reason)
+}
+
+/**
+ * Move to another tier and reset the counters that belong to the old tier.
+ * @param {ReturnType<typeof createCascade>} cascade - the session's cascade state (mutated).
+ * @param {'small' | 'large'} tier - the destination tier.
+ * @param {string} reason - audit reason.
+ * @returns {{ from: string, to: string, reason: string }} the change.
+ */
+function switchTier(cascade, tier, reason) {
+  const from = cascade.tier
+  cascade.tier = tier
+  cascade.stepsInTier = 0
+  cascade.consecutiveFailures = 0
+  cascade.consecutivePasses = 0
+  return { from, to: tier, reason }
+}

package/src/core/distill.mjs

@@ -0,0 +1,128 @@
+import { stripAnsi } from './ansi.mjs'
+import { FAIL_RE, FRAME_RE, LIB_FRAME_RE, PROGRESS_RE, SAFETY_RE, SUMMARY_RE, ZERO_RE } from './patterns.mjs'
+
+/** Minimum size reduction (output at most this fraction of the input) before a distillation is used. */
+const MIN_REDUCTION_RATIO = 0.9
+
+/**
+ * Classify one line for distillation.
+ * @param {string} line - one line with control sequences removed.
+ * @returns {'summary' | 'fail' | 'safety' | 'lib-frame' | 'frame' | 'plain'} the line's kind.
+ */
+function classify(line) {
+  if (ZERO_RE.test(line)) return 'summary'
+  if (FAIL_RE.test(line)) return 'fail'
+  if (SAFETY_RE.test(line)) return 'safety'
+  if (FRAME_RE.test(line)) return LIB_FRAME_RE.test(line) ? 'lib-frame' : 'frame'
+  if (SUMMARY_RE.test(line)) return 'summary'
+  return 'plain'
+}
+
+/**
+ * Keep the signal in one shell or tool output and drop the rest, without changing any kept line.
+ *
+ * Kept, in order: failure, summary and safety lines; user-code stack frames and plain lines
+ * within `contextLines` of a failure; the first and last three lines. Dropped: progress
+ * frames, library stack frames, passing-test noise. Runs of three or more identical kept
+ * lines collapse to one line with a count. Output above `maxChars` keeps its head and tail.
+ *
+ * @param {string} raw - tool output as the model would read it.
+ * @param {{ maxChars?: number, contextLines?: number }} [options] - size budget and window around failures.
+ * @returns {{ text: string, changed: boolean, stats: { inChars: number, outChars: number, droppedLines: number, droppedFrames: number, collapsedRepeats: number, failLines: number, elidedChars: number } }}
+ *   `changed` is true only when the distilled text is at most 90% of the input and differs from it.
+ */
+export function distillOutput(raw, options = {}) {
+  const maxChars = options.maxChars ?? 6000
+  const contextLines = options.contextLines ?? 2
+  const input = String(raw ?? '')
+  const stats = {
+    inChars: input.length, outChars: 0, droppedLines: 0, droppedFrames: 0,
+    collapsedRepeats: 0, failLines: 0, elidedChars: 0,
+  }
+
+  let lines = stripAnsi(input).replace(/\r\n?/g, '\n').split('\n')
+  lines = lines.filter((line) => {
+    if (line.trim() !== '' && PROGRESS_RE.test(line)) {
+      stats.droppedLines += 1
+      return false
+    }
+    return true
+  })
+
+  const kinds = lines.map(classify)
+  stats.failLines = kinds.filter(kind => kind === 'fail').length
+
+  const nearFailure = new Array(lines.length).fill(false)
+  kinds.forEach((kind, index) => {
+    if (kind !== 'fail') return
+    const from = Math.max(0, index - contextLines)
+    const to = Math.min(lines.length - 1, index + contextLines)
+    for (let j = from; j <= to; j += 1) nearFailure[j] = true
+  })
+
+  const keep = lines.map((_, index) => {
+    const kind = kinds[index]
+    if (kind === 'fail' || kind === 'summary' || kind === 'safety') return true
+    if (kind === 'lib-frame') return false
+    if (index < 3 || index >= lines.length - 3) return true
+    return nearFailure[index]
+  })
+
+  const emitted = []
+  let gap = 0
+  let runText = null
+  let runCount = 0
+  const flushRun = () => {
+    if (runText === null) return
+    if (runCount >= 3) {
+      emitted.push(`${runText}  (×${runCount})`)
+      stats.collapsedRepeats += runCount - 1
+    } else {
+      for (let k = 0; k < runCount; k += 1) emitted.push(runText)
+    }
+    runText = null
+    runCount = 0
+  }
+
+  for (let index = 0; index < lines.length; index += 1) {
+    if (!keep[index]) {
+      if (kinds[index] === 'lib-frame') stats.droppedFrames += 1
+      if (gap === 0) flushRun()
+      gap += 1
+      continue
+    }
+    if (gap > 0) {
+      emitted.push(`[… ${gap} line${gap === 1 ? '' : 's'} omitted]`)
+      gap = 0
+    }
+    const text = lines[index]
+    if (text === runText) {
+      runCount += 1
+    } else {
+      flushRun()
+      runText = text
+      runCount = 1
+    }
+  }
+  flushRun()
+  if (gap > 0) emitted.push(`[… ${gap} line${gap === 1 ? '' : 's'} omitted]`)
+
+  let text = emitted.join('\n').replace(/[ \t]+$/gm, '')
+  if (text.length > maxChars) {
+    const headBudget = Math.floor(maxChars * 0.4)
+    const tailBudget = Math.max(0, maxChars - headBudget - 80)
+    const headSlice = text.slice(0, headBudget)
+    const headCut = headSlice.lastIndexOf('\n')
+    const headText = headCut > 0 ? headSlice.slice(0, headCut) : headSlice
+    const tailSlice = text.slice(text.length - tailBudget)
+    const tailCut = tailSlice.indexOf('\n')
+    const tailText = tailCut >= 0 ? tailSlice.slice(tailCut + 1) : tailSlice
+    const omitted = text.length - headText.length - tailText.length
+    stats.elidedChars = omitted
+    text = `${headText}\n[… ${omitted} chars omitted …]\n${tailText}`
+  }
+
+  stats.outChars = text.length
+  const changed = text !== input && text.length <= input.length * MIN_REDUCTION_RATIO
+  return { text, changed, stats }
+}

package/src/core/ledger.mjs

@@ -0,0 +1,21 @@
+import { appendFileSync, mkdirSync } from 'node:fs'
+import { dirname } from 'node:path'
+
+/**
+ * Cost and decision ledger: one JSON object per line, appended as events happen.
+ * Record types: `request` (provider usage per model step), `tool` (per tool result, with the
+ * distillation or dedupe action), `route` (tier change), `loop-break` (denied command).
+ *
+ * @param {string} path - JSONL file to append to; an empty value disables the ledger.
+ * @returns {{ path: string, write(record: Record<string, unknown>): void }}
+ */
+export function createLedger(path) {
+  if (!path) return { path: '', write() {} }
+  mkdirSync(dirname(path), { recursive: true })
+  return {
+    path,
+    write(record) {
+      appendFileSync(path, `${JSON.stringify({ ts: new Date().toISOString(), ...record })}\n`)
+    },
+  }
+}

package/src/core/loop-guard.mjs

@@ -0,0 +1,52 @@
+import { normalizeCommand } from './verify.mjs'
+
+/**
+ * Loop guard: counts consecutive runs of the same command that fail with the same failure
+ * fingerprint. A run with a different fingerprint is progress and restarts the count; a
+ * passing run clears it; any workspace edit clears every count.
+ */
+
+/**
+ * Create an empty loop-guard state for one session.
+ * @returns {{ streaks: Map<string, { count: number, fingerprint: string }> }}
+ */
+export function createLoopGuard() {
+  return { streaks: new Map() }
+}
+
+/**
+ * Record the outcome of an executed command.
+ * @param {ReturnType<typeof createLoopGuard>} guard - the session's loop-guard state (mutated).
+ * @param {string} command - the command text.
+ * @param {{ passed: boolean, fingerprint: string | null }} outcome - from `classifyOutcome`.
+ * @returns {number} the current consecutive count for this command (0 after a pass).
+ */
+export function recordCommandOutcome(guard, command, outcome) {
+  const key = normalizeCommand(command)
+  if (outcome.passed || outcome.fingerprint === null) {
+    guard.streaks.delete(key)
+    return 0
+  }
+  const previous = guard.streaks.get(key)
+  const count = previous !== undefined && previous.fingerprint === outcome.fingerprint ? previous.count + 1 : 1
+  guard.streaks.set(key, { count, fingerprint: outcome.fingerprint })
+  return count
+}
+
+/**
+ * Consecutive same-fingerprint failures for one command.
+ * @param {ReturnType<typeof createLoopGuard>} guard - the session's loop-guard state.
+ * @param {string} command - the command text.
+ * @returns {number} the count, 0 when the command has no active streak.
+ */
+export function streakOf(guard, command) {
+  return guard.streaks.get(normalizeCommand(command))?.count ?? 0
+}
+
+/**
+ * Clear every streak after a workspace change, because a failing command may pass now.
+ * @param {ReturnType<typeof createLoopGuard>} guard - the session's loop-guard state (mutated).
+ */
+export function noteWorkspaceChange(guard) {
+  guard.streaks.clear()
+}