@quadiusai/dsh-greenharness 0.0.0-stage → 0.1.1

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)
+}

package/src/core/read-index.mjs

@@ -0,0 +1,74 @@
+/**
+ * Content-addressed index of file reads still visible in the model context.
+ *
+ * A read whose rendered content is byte-identical to an earlier read of the same file range
+ * can be replaced by a short pointer to that earlier result. The pointer is only valid while
+ * the earlier result is still in context, so the index is cleared on compaction and pruning
+ * and forgets a path whenever the agent edits or rewrites it.
+ */
+
+/**
+ * Create an empty read index.
+ * @returns {{ bySession: Map<string, Map<string, { path: string, digest: string, callId: string }>> }}
+ */
+export function createReadIndex() {
+  return { bySession: new Map() }
+}
+
+/**
+ * Key for one file range.
+ * @param {string} path - the file path as the agent passed it.
+ * @param {number | null} offset - first line, or null when defaulted.
+ * @param {number | null} limit - line count, or null when defaulted.
+ * @returns {string} the range key.
+ */
+function rangeKey(path, offset, limit) {
+  return JSON.stringify([path, offset ?? null, limit ?? null])
+}
+
+/**
+ * Record a successful read.
+ * @param {ReturnType<typeof createReadIndex>} index - the read index (mutated).
+ * @param {string} sessionId - the owning session.
+ * @param {{ path: string, offset?: number | null, limit?: number | null, digest: string, callId: string }} read - the read.
+ */
+export function rememberRead(index, sessionId, read) {
+  const entries = index.bySession.get(sessionId) ?? new Map()
+  entries.set(rangeKey(read.path, read.offset, read.limit), { path: read.path, digest: read.digest, callId: read.callId })
+  index.bySession.set(sessionId, entries)
+}
+
+/**
+ * Find an earlier read of the same range with identical content.
+ * @param {ReturnType<typeof createReadIndex>} index - the read index.
+ * @param {string} sessionId - the owning session.
+ * @param {{ path: string, offset?: number | null, limit?: number | null, digest: string }} read - the new read.
+ * @returns {string | undefined} the call id of the identical earlier read, if one is indexed.
+ */
+export function findUnchangedRead(index, sessionId, read) {
+  const entry = index.bySession.get(sessionId)?.get(rangeKey(read.path, read.offset, read.limit))
+  return entry !== undefined && entry.digest === read.digest ? entry.callId : undefined
+}
+
+/**
+ * Forget every indexed range of a path, after the agent edited or rewrote it.
+ * @param {ReturnType<typeof createReadIndex>} index - the read index (mutated).
+ * @param {string} sessionId - the owning session.
+ * @param {string} path - the changed file path.
+ */
+export function forgetPath(index, sessionId, path) {
+  const entries = index.bySession.get(sessionId)
+  if (entries === undefined) return
+  for (const [key, entry] of entries) {
+    if (entry.path === path) entries.delete(key)
+  }
+}
+
+/**
+ * Forget a session's whole index, after compaction or pruning removed earlier results from context.
+ * @param {ReturnType<typeof createReadIndex>} index - the read index (mutated).
+ * @param {string} sessionId - the owning session.
+ */
+export function clearSession(index, sessionId) {
+  index.bySession.delete(sessionId)
+}

package/src/core/route.mjs

@@ -0,0 +1,41 @@
+/**
+ * Helpers for the two DSH hooks that carry per-step routing.
+ *
+ * DSH keeps the last logged request header and seeds the next model call from it, so a route
+ * must be applied on every call, not only where the tier changes. The `agent/request` waterfall
+ * is where a plugin replaces the call configuration; `agent/pre-step` is where it can edit the
+ * messages admitted to a step.
+ */
+
+/**
+ * Replace provider, model and reasoning effort in one model-call configuration. Every other
+ * control is kept. The inherited effort is always dropped first, so a route without an effort
+ * does not keep the previous tier's effort.
+ *
+ * @param {Record<string, any>} config - the configuration DSH would use (not mutated).
+ * @param {{ provider: string, model: string, reasoningEffort?: string }} route - the tier route.
+ * @returns {Record<string, any>} a new configuration.
+ */
+export function applyRoute(config, route) {
+  const { reasoningEffort: _inheritedEffort, ...controls } = config
+  return {
+    ...controls,
+    provider: route.provider,
+    model: route.model,
+    ...(route.reasoningEffort === undefined ? {} : { reasoningEffort: route.reasoningEffort }),
+  }
+}
+
+/**
+ * Drop DSH's model-switch notices. DSH adds one whenever the entry point's default selection
+ * differs from the last logged request. Per-step routing makes that differ on purpose, so the
+ * notice would repeat on every step and name the wrong model. The routing ledger records each
+ * change instead.
+ *
+ * @template {{ source?: { kind?: string } | undefined }} T
+ * @param {ReadonlyArray<T>} messages - the messages admitted to a step.
+ * @returns {T[]} the messages without model-switch notices.
+ */
+export function withoutModelNotices(messages) {
+  return messages.filter(message => message?.source?.kind !== 'model-selection')
+}

package/src/core/verify.mjs

@@ -0,0 +1,89 @@
+import { createHash } from 'node:crypto'
+import { stripAnsi } from './ansi.mjs'
+import { FAIL_RE } from './patterns.mjs'
+
+/**
+ * Command patterns that count as verifiers: test runners, type checkers, linters and build checks.
+ * A bash call matching one of these is a verifier call, and its exit status drives the cascade.
+ */
+export const DEFAULT_VERIFIER_PATTERNS = [
+  String.raw`\b(?:npm|pnpm|yarn|bun)\s+(?:run\s+)?test\b`,
+  String.raw`\b(?:pytest|py\.test)\b`,
+  String.raw`\bpython3?\s+-m\s+(?:pytest|unittest)\b`,
+  String.raw`\bnode\s+--test\b`,
+  String.raw`\b(?:vitest|jest|mocha)\b`,
+  String.raw`\bgo\s+test\b`,
+  String.raw`\bcargo\s+(?:test|check|clippy)\b`,
+  String.raw`\b(?:tsc|mypy|ruff|eslint)\b`,
+  String.raw`\bmake\s+(?:test|check)\b`,
+]
+
+/**
+ * Compile verifier command patterns.
+ * @param {string[]} sources - regular-expression sources, matched case-insensitively.
+ * @returns {RegExp[]} compiled patterns.
+ */
+export function compileVerifierPatterns(sources) {
+  return sources.map(source => new RegExp(source, 'i'))
+}
+
+/**
+ * Whether a command is a verifier call.
+ * @param {string} command - the bash command text.
+ * @param {RegExp[]} patterns - compiled verifier patterns.
+ * @returns {boolean} true when any pattern matches.
+ */
+export function isVerifierCommand(command, patterns) {
+  return patterns.some(pattern => pattern.test(command))
+}
+
+/**
+ * Read the `[exit code: N]` marker that the bash tool appends to non-zero results.
+ * @param {string} text - rendered tool output.
+ * @returns {number | undefined} the exit code, or undefined when no marker is present.
+ */
+export function parseExitMarker(text) {
+  const match = /\[exit code: (-?\d+)\]/.exec(text)
+  return match ? Number(match[1]) : undefined
+}
+
+/**
+ * Stable identity of one failure: the normalized failure lines with digits, durations and
+ * addresses removed. The same failure at a different line or timing gets the same fingerprint.
+ * @param {string} text - rendered tool output of the failing command.
+ * @returns {string} a 12-character hex digest.
+ */
+export function fingerprintOf(text) {
+  const lines = stripAnsi(String(text ?? '')).split('\n')
+  let signal = lines.filter(line => FAIL_RE.test(line)).slice(0, 8)
+  if (signal.length === 0) signal = lines.filter(line => line.trim() !== '').slice(-5)
+  const normalized = signal
+    .map(line => line
+      .replace(/0x[0-9a-f]+/gi, '#')
+      .replace(/\d+(?:\.\d+)?\s*(?:ms|s|µs)\b/g, '#')
+      .replace(/\d+/g, '#')
+      .replace(/\s+/g, ' ')
+      .trim())
+    .join('\n')
+  return createHash('sha1').update(normalized).digest('hex').slice(0, 12)
+}
+
+/**
+ * Classify the outcome of one executed command.
+ * @param {{ exitCode: number, timedOut?: boolean, text?: string }} run - exit status, timeout flag and rendered output.
+ * @returns {{ passed: boolean, exitCode: number, timedOut: boolean, fingerprint: string | null }}
+ *   `fingerprint` is null for passing runs.
+ */
+export function classifyOutcome({ exitCode, timedOut = false, text = '' }) {
+  const passed = !timedOut && exitCode === 0
+  return { passed, exitCode, timedOut, fingerprint: passed ? null : fingerprintOf(text) }
+}
+
+/**
+ * Canonical spelling of a command for keys: whitespace collapsed and trimmed.
+ * @param {unknown} command - the command argument.
+ * @returns {string} the normalized command, empty when absent.
+ */
+export function normalizeCommand(command) {
+  return String(command ?? '').trim().replace(/\s+/g, ' ')
+}

package/src/index.mjs

@@ -0,0 +1,233 @@
+/**
+ * GreenHarness: a DeepSeek Harness (dsh) plugin that cuts the token, GPU and dollar cost of
+ * multi-step agent work. Installed as a DSH bundle with `dsh plugin add @quadiusai/dsh-greenharness`;
+ * every setting has a default, and `/greenharness` controls it while DSH runs. See README.md.
+ *
+ * The plugin changes four things, and each has a ledger record:
+ *   1. Cascade: routes each model call to the small or large model from verifier outcomes. The
+ *      route is applied in the `agent/request` waterfall, DSH's hook for replacing a call's
+ *      provider, model and effort.
+ *   2. Distillation: shortens bash output before it enters the session log, keeping the full
+ *      output in the spill store.
+ *   3. Read dedupe: replaces a byte-identical re-read of a file still in context with a pointer.
+ *   4. Loop breaker: denies a repeated failing command and escalates the model tier.
+ *
+ * @module @quadiusai/dsh-greenharness
+ */
+import z from '@deepseek-ai/schemastery'
+import { createLedger } from './core/ledger.mjs'
+import { applyRoute, withoutModelNotices } from './core/route.mjs'
+import { normalizeSettings } from './config.mjs'
+import { createGreenHarness } from './runtime.mjs'
+import { runCommand } from './control.mjs'
+
+/** Cordis plugin identity. */
+export const name = 'greenharness'
+
+/** Needs the command registry to offer `/greenharness`. */
+export const inject = ['commands', 'llm']
+
+// Every field defaults to empty: an absent tier is an empty route, and normalizeSettings decides.
+const route = z.object({
+  provider: z.string().default(''),
+  model: z.string().default(''),
+  reasoningEffort: z.string().default(''),
+})
+
+const price = z.object({
+  inputPerMTok: z.number(),
+  cachedInputPerMTok: z.number(),
+  outputPerMTok: z.number(),
+})
+
+/**
+ * Plugin configuration schema. Every field is optional. Without tiers GreenHarness never switches
+ * models, and the other mechanisms still run. Routing is switched on at runtime with
+ * `/greenharness large <provider> <model>`.
+ */
+export const Config = z.object({
+  tiers: z.object({
+    small: route,
+    large: route,
+  }).default({}),
+  cascade: z.object({
+    escalateAfterFailures: z.number().default(1),
+    deescalateAfterPasses: z.number().default(2),
+    minStepsPerTier: z.number().default(2),
+  }).default({}),
+  verifier: z.object({
+    patterns: z.array(z.string()).default([]),
+  }).default({}),
+  distill: z.object({
+    enabled: z.boolean().default(true),
+    maxChars: z.number().default(6000),
+    contextLines: z.number().default(2),
+  }).default({}),
+  readDedupe: z.object({
+    enabled: z.boolean().default(true),
+  }).default({}),
+  loopBreaker: z.object({
+    enabled: z.boolean().default(true),
+    threshold: z.number().default(3),
+  }).default({}),
+  ledger: z.object({
+    path: z.string().default('.greenharness/ledger.jsonl'),
+    pricing: z.dict(price).default({}),
+  }).default({}),
+})
+
+/**
+ * Mount GreenHarness.
+ * @param {import('@deepseek-ai/cordis').Context} ctx - plugin context.
+ * @param {z.infer<typeof Config>} config - validated configuration.
+ */
+export function apply(ctx, config) {
+  const settings = normalizeSettings(config)
+  const ledger = createLedger(settings.ledger.path)
+  const runtime = createGreenHarness(settings, { ledger, logger: ctx.logger })
+  const control = { paused: false }
+
+  // Routing. Registered at boot, before the agent's own model-selection listener, so this is the
+  // outer `agent/request` decision: the route it returns is the one the call sends.
+  ctx.on('agent/request', async (payload, next) => {
+    const proposed = await next()
+    try {
+      if (control.paused) return proposed
+      const route = runtime.routeForNextCall(payload.agent.session.header.id, proposed)
+      return route === undefined ? proposed : applyRoute(proposed, route)
+    } catch (error) {
+      reportError(ctx, ledger, 'agent/request', error)
+      return proposed
+    }
+  })
+
+  // DSH adds a "model changed" notice whenever its default selection differs from the last logged
+  // request. Per-step routing makes that happen on purpose, so the notice is removed; the ledger
+  // records each route change instead. DSH registers its notice listener on each agent, with
+  // `prepend`, when the agent is created. This listener goes on the same agent context after it,
+  // also with `prepend`, so it is the outer listener and sees the messages after the notice is
+  // added. Registered at boot, it would run inside the notice listener and miss it.
+  ctx.on('agent/created', ({ agent }) => {
+    agent?.ctx?.on('agent/pre-step', async (_payload, next) => {
+      const decision = await next()
+      if (decision.kind !== 'enter') return decision
+      const messages = withoutModelNotices(decision.messages)
+      return messages.length === decision.messages.length ? decision : { ...decision, messages }
+    }, { prepend: true })
+  })
+
+  ctx.on('tools/pre-execute', async (exec, next) => {
+    const decision = await next()
+    if (control.paused || decision.kind !== 'allow') return decision
+    const call = toCall(ctx, exec)
+    if (call === undefined) return decision
+    try {
+      return runtime.beforeTool(call) ?? decision
+    } catch (error) {
+      reportError(ctx, ledger, 'tools/pre-execute', error)
+      return decision
+    }
+  })
+
+  ctx.on('tools/post-execute', async (exec, result, next) => {
+    const decision = await next()
+    if (control.paused || decision.kind !== 'accept' || Object.hasOwn(decision, 'value')) return decision
+    const call = toCall(ctx, exec, result)
+    if (call === undefined) return decision
+    try {
+      const replacement = await runtime.afterTool(call)
+      if (replacement === undefined) return decision
+      return { ...decision, kind: 'accept', content: [{ type: 'text', text: replacement.text }] }
+    } catch (error) {
+      reportError(ctx, ledger, 'tools/post-execute', error)
+      return decision
+    }
+  })
+
+  registerCommand(ctx, { control, settings, runtime, llm: ctx.llm })
+
+  ctx.on('session/event', (session, event) => {
+    try {
+      runtime.observeEvent(session.header.id, event)
+    } catch (error) {
+      reportError(ctx, ledger, 'session/event', error)
+    }
+  })
+}
+
+/**
+ * Offer `/greenharness` in DSH's command registry. The handler is pure over the host object; see
+ * control.mjs.
+ * @param {import('@deepseek-ai/cordis').Context} ctx
+ * @param {{ control: { paused: boolean }, settings: any, runtime: any }} host
+ */
+function registerCommand(ctx, host) {
+  ctx.effect(function* () {
+    yield ctx.commands.register({
+      definitionId: '@quadiusai/dsh-greenharness',
+      name: 'greenharness',
+      description: 'GreenHarness: see tokens saved, choose cheap and strong models, switch features (try: help)',
+      input: { hint: 'help | models | large <number> | small <number> | on | off' },
+      handler: (invocation) => runCommand(invocation.rawInput, host),
+    })
+  }, 'greenharness command')
+}
+
+/**
+ * Keep a plugin failure visible in the ledger. DSH's logger output is not always shown, and a
+ * swallowed error would look like the plugin never ran.
+ * @param {import('@deepseek-ai/cordis').Context} ctx
+ * @param {{ write(record: object): void }} ledger
+ * @param {string} stage - the hook that failed.
+ * @param {unknown} error
+ */
+function reportError(ctx, ledger, stage, error) {
+  const message = error instanceof Error ? error.message : String(error)
+  try {
+    ledger.write({ type: 'error', stage, message })
+  } catch {
+    // The ledger is unavailable too; the logger below still reports the failure.
+  }
+  ctx.logger?.warn?.(`greenharness: ${stage} failed: ${message}`)
+}
+
+/**
+ * Adapt one DSH tool execution to the runtime's call shape.
+ * @param {import('@deepseek-ai/cordis').Context} ctx
+ * @param {any} exec - the DSH ToolExecution.
+ * @param {any} [result] - the normalized ToolExecutionResult, after dispatch.
+ */
+function toCall(ctx, exec, result) {
+  const agent = exec.agent
+  if (agent === undefined) return undefined
+  const value = result?.value
+  return {
+    sessionId: agent.session.header.id,
+    name: exec.name,
+    args: exec.arguments ?? {},
+    callId: exec.callId,
+    isError: result?.isError === true,
+    exitCode: typeof value?.exitCode === 'number' ? value.exitCode : undefined,
+    timedOut: value?.timedOut === true,
+    text: contentText(result?.content),
+    spill: async (text) => {
+      const store = ctx.get('spillStore')
+      if (store === undefined) return undefined
+      const ref = await store.saveText({
+        owner: { sessionId: agent.session.header.id },
+        source: { kind: 'tool', toolName: exec.name, callId: exec.callId, label: 'result' },
+        suggestedName: `${exec.name}.txt`,
+        content: text,
+      })
+      return ref.retrievalHint
+    },
+  }
+}
+
+/**
+ * Text of a tool result's text blocks, in order.
+ * @param {Array<{ type: string, text?: string }> | undefined} content
+ */
+function contentText(content) {
+  return (content ?? []).filter(block => block.type === 'text').map(block => block.text ?? '').join('\n')
+}