@quadiusai/dsh-greenharness 0.0.0-stage → 0.1.0

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,160 @@
+/**
+ * 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 commands (settings last until DSH restarts):',
+  '  /greenharness                 status: what is on, and what it has done so far',
+  '  /greenharness on | off        resume or pause every mechanism',
+  '  /greenharness large <provider> <model> [effort]',
+  '                                turn on model routing with this large model',
+  '  /greenharness small <provider> <model> [effort]',
+  '                                set the small model (default: the model DSH uses)',
+  '  /greenharness routing on | off',
+  '  /greenharness distill on | off   shorten long command output',
+  '  /greenharness dedupe on | off    replace a repeated file read with a pointer',
+  '  /greenharness loop on | off      block a repeated failing command',
+  '  /greenharness help',
+].join('\n')
+
+/**
+ * Parse the text after `/greenharness`.
+ * @param {string} rawInput
+ * @returns {{ action: 'status' | 'help' } | { action: 'pause', paused: boolean }
+ *   | { action: 'toggle', mechanism: string, enabled: boolean }
+ *   | { action: 'tier', tier: 'small' | 'large', route: { provider: string, model: string, reasoningEffort: 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 === 'large' || verb === 'small') {
+    if (args.length < 2 || args.length > 3) return usage(`/greenharness ${verb} <provider> <model> [effort]`)
+    return { action: 'tier', tier: verb, route: { provider: args[0], model: args[1], reasoningEffort: args[2] ?? '' } }
+  }
+  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 {{ kind: 'success' | 'error', text: string }}
+ */
+export 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 '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 ? '' : 'Tip: pick a big model with  /greenharness large <provider> <model>  to save more.',
+  )
+  return lines.filter((l, i, a) => !(l === '' && (i === a.length - 1))).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)}.`)
+}
+
+/** @param {{ tier: 'small' | 'large', route: object }} command @param {{ settings: any }} host */
+function setTier({ tier, route }, { settings }) {
+  settings.tiers[tier] = route
+  if (tier === 'large') {
+    settings.routing.enabled = true
+    return ok(`Large model set to ${route.provider}/${route.model}. Routing is on: calls escalate to it after failing tests.`)
+  }
+  return ok(`Small model set to ${route.provider}/${route.model}.`)
+}
+
+/** @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()
+}

package/src/core/patterns.mjs

@@ -0,0 +1,26 @@
+/**
+ * Line classifiers shared by the distiller, the verifier fingerprint and the tests.
+ * Each pattern describes one kind of line seen in test runners, compilers, linters
+ * and shells. Patterns only decide what to keep; they never rewrite text.
+ */
+
+/** Lines that carry a failure signal (failures, errors, assertion detail, stack-trace headers). */
+export const FAIL_RE = /\b(?:fail(?:s|ed|ure|ures|ing)?|errors?|exceptions?|tracebacks?|panic(?:ked)?|assert(?:ion|ions|ed)?|expected|received|actual|not ok|typeerror|referenceerror|syntaxerror|rangeerror|cannot find|no such file|segmentation fault|timed? ?out|killed)\b|[✗✖×]|^\s*E\s{3,}/i
+
+/** Summary lines that state zero failures; these are summaries, not failures. */
+export const ZERO_RE = /\b(?:0\s+(?:failed|failures?|errors?|problems?)|(?:failed|failures?|errors?)\s*[:=]\s*0)\b/i
+
+/** Result summaries and run metadata that must survive distillation. */
+export const SUMMARY_RE = /\b\d+\s+(?:passed|failed|skipped|todo|errors?|failures?|tests?|suites?|problems?|examples?)\b|^\s*Tests?\s*:|^\s*Test Files\b|^\s*#\s*(?:tests|pass|fail|suites|duration_ms)\b|^\s*(?:ok|not ok)\b|\bexit code\b|\bran \d+\b|^={3,}.*={3,}\s*$|\bdone in\b|\bfinished in\b|\bduration\b/i
+
+/** Lines a human must not miss even when they are not failures (security, deprecation, permissions). */
+export const SAFETY_RE = /\b(?:warn(?:ing|ings)?|deprecat\w*|secur\w*|cve-\d{4}-\d+|permission|denied|unauthori[sz]ed|forbidden|credential\w*|secret\w*|vulnerab\w*|fatal)\b/i
+
+/** Spinner frames and progress bars: rendering noise with no information. */
+export const PROGRESS_RE = /^\s*[|/\\-]\s*$|^\s*\[[#=\- ]{4,}\]?\s*\d{0,3}%?\s*$|^\s*\d{1,3}%\s*\|/
+
+/** Stack-trace frame headers in common runtimes. */
+export const FRAME_RE = /^\s*(?:at\s+\S|File "[^"]+", line \d+|❯\s|-->\s)/
+
+/** Frames inside installed libraries or the runtime itself; they rarely explain an application failure. */
+export const LIB_FRAME_RE = /node_modules[\\/]|node:internal|\binternal\/|site-packages[\\/]|dist-packages[\\/]|\/usr\/lib|\/\.nvm\/|\/\.pyenv\/|<frozen |<internal\//

package/src/core/pricing.mjs

@@ -0,0 +1,23 @@
+/**
+ * Per-request API cost from provider-reported usage.
+ *
+ * Usage counts are disjoint, as DSH reports them: `inputTokens` is uncached input,
+ * `cacheReadTokens` is cached input, `cacheWriteTokens` is cache creation, and `outputTokens`
+ * includes reasoning tokens. Rates are USD per million tokens.
+ *
+ * @param {{ inputTokens?: number, outputTokens?: number, cacheReadTokens?: number, cacheWriteTokens?: number } | undefined} usage
+ * @param {{ inputPerMTok?: number, cachedInputPerMTok?: number, outputPerMTok?: number } | undefined} price
+ * @returns {number} estimated cost in USD; 0 when no price is configured for the route.
+ */
+export function usageCostUsd(usage, price) {
+  if (usage === undefined || price === undefined) return 0
+  const perToken = rate => (rate ?? 0) / 1_000_000
+  const input = usage.inputTokens ?? 0
+  const cacheWrite = usage.cacheWriteTokens ?? 0
+  const cacheRead = usage.cacheReadTokens ?? 0
+  const output = usage.outputTokens ?? 0
+  return input * perToken(price.inputPerMTok)
+    + cacheWrite * perToken(price.inputPerMTok)
+    + cacheRead * perToken(price.cachedInputPerMTok ?? price.inputPerMTok)
+    + output * perToken(price.outputPerMTok)
+}