@quadiusai/dsh-greenharness 0.0.0-stage → 0.1.1

package/src/runtime.mjs

@@ -0,0 +1,297 @@
+import { createHash } from 'node:crypto'
+import { usageCostUsd } from './core/pricing.mjs'
+import { distillOutput } from './core/distill.mjs'
+import { createCascade, escalate, recordStep, recordVerification } from './core/cascade.mjs'
+import { createLoopGuard, noteWorkspaceChange, recordCommandOutcome, streakOf } from './core/loop-guard.mjs'
+import { clearSession, createReadIndex, findUnchangedRead, forgetPath, rememberRead } from './core/read-index.mjs'
+import {
+  classifyOutcome, compileVerifierPatterns, isVerifierCommand, normalizeCommand, parseExitMarker,
+} from './core/verify.mjs'
+
+/** Session events after which earlier tool results may have left the model context. */
+const CONTEXT_REMOVAL_EVENTS = new Set(['compaction/start', 'compaction/end', 'compaction/prune', 'compaction/summary'])
+
+/**
+ * One tool call as GreenHarness sees it. The Cordis adapter builds this from the DSH execution
+ * and result; tests build it directly.
+ * @typedef {object} ToolCall
+ * @property {string} sessionId - owning session id.
+ * @property {string} name - tool name (`bash`, `read`, `edit`, `write`, ...).
+ * @property {Record<string, any>} args - the arguments the model sent.
+ * @property {string} [callId] - the tool call id.
+ * @property {boolean} [isError] - whether the tool reported an error.
+ * @property {number} [exitCode] - structured exit status for bash, when DSH reports it.
+ * @property {boolean} [timedOut] - whether bash timed out.
+ * @property {string} [text] - the rendered result text the model reads.
+ * @property {(text: string) => Promise<string | undefined>} [spill] - stores full output and returns a retrieval hint.
+ */
+
+/**
+ * Build the GreenHarness runtime: routing, output distillation, read dedupe, loop breaking and
+ * the cost ledger. The Cordis adapter asks it for the route of each model call, feeds it tool
+ * calls, and passes it session events.
+ *
+ * @param {ReturnType<import('./config.mjs').normalizeSettings>} settings - complete settings.
+ * @param {{ ledger: { write(record: object): void }, logger?: { warn(message: string): void } }} deps - sinks.
+ */
+export function createGreenHarness(settings, { ledger, logger } = {}) {
+  const verifierRegexes = compileVerifierPatterns(settings.verifier.patterns)
+  const sessions = new Map()
+  const reads = createReadIndex()
+  // Tallies for the /greenharness status command: every record written, by type (and action for tools).
+  const tally = {}
+  const log = {
+    write(record) {
+      const key = record.type === 'tool' ? `tool:${record.action}` : record.type
+      tally[key] = (tally[key] ?? 0) + 1
+      if (record.type === 'tool' && record.rawChars > record.outChars) {
+        tally.charsSaved = (tally.charsSaved ?? 0) + (record.rawChars - record.outChars)
+      }
+      if (record.type === 'request') {
+        const u = record.usage ?? {}
+        const tier = record.tier === 'large' ? 'large' : 'small'
+        tally[`${tier}Tokens`] = (tally[`${tier}Tokens`] ?? 0) + (u.inputTokens ?? 0) + (u.outputTokens ?? 0)
+        tally.costUsd = (tally.costUsd ?? 0) + (record.costUsd ?? 0)
+      }
+      ledger.write(record)
+    },
+  }
+
+  /**
+   * @param {string} sessionId
+   */
+  function stateOf(sessionId) {
+    let state = sessions.get(sessionId)
+    if (state === undefined) {
+      state = { cascade: createCascade(settings.cascade), loop: createLoopGuard(), route: undefined }
+      sessions.set(sessionId, state)
+    }
+    return state
+  }
+
+  /**
+   * The provider, model and reasoning effort of one tier. An empty effort means the provider's default.
+   * @param {'small' | 'large'} tier
+   * @returns {{ provider: string, model: string, reasoningEffort?: string }}
+   */
+  function tierRoute(tier) {
+    const route = settings.tiers[tier]
+    if (route === undefined) return undefined
+    return route.reasoningEffort === ''
+      ? { provider: route.provider, model: route.model }
+      : { provider: route.provider, model: route.model, reasoningEffort: route.reasoningEffort }
+  }
+
+  /**
+   * The tier a logged route belongs to. Any route that is not the large tier counts as small.
+   * @param {{ provider?: string, model?: string } | undefined} route
+   * @returns {'small' | 'large'}
+   */
+  function tierOfRoute(route) {
+    const large = settings.tiers.large
+    if (large === undefined) return 'small'
+    return route?.provider === large.provider && route?.model === large.model ? 'large' : 'small'
+  }
+
+  /**
+   * Record a tier change. It takes effect on the session's next model call, which asks
+   * `routeForNextCall` for its route.
+   * @param {ToolCall} call
+   * @param {{ from: string, to: string, reason: string } | null} change
+   * @param {Record<string, unknown>} [extra]
+   */
+  function applyChange(call, change, extra = {}) {
+    if (change === null) return
+    log.write({
+      type: 'route', session: call.sessionId, from: change.from, to: change.to,
+      reason: change.reason, selection: tierRoute(change.to), ...extra,
+    })
+  }
+
+  /**
+   * The route of the next model call of a session. The call counts as one step in the current
+   * tier. The Cordis adapter applies the returned route in its `agent/request` waterfall.
+   * @param {string} sessionId
+   * @returns {{ provider: string, model: string, reasoningEffort?: string }}
+   */
+  function routeForNextCall(sessionId, proposed) {
+    if (!settings.routing.enabled || settings.tiers.large === undefined) return undefined
+    // Without an explicit small tier, the small tier is the model DSH would use by default. It is
+    // captured from the first call that is routed, before any route has been applied.
+    if (settings.tiers.small === undefined && proposed?.provider && proposed?.model) {
+      settings.tiers.small = { provider: proposed.provider, model: proposed.model, reasoningEffort: proposed.reasoningEffort ?? '' }
+    }
+    if (settings.tiers.small === undefined) return undefined
+    const state = stateOf(sessionId)
+    recordStep(state.cascade)
+    return tierRoute(state.cascade.tier)
+  }
+
+  /** @param {ToolCall} call */
+  function beforeTool(call) {
+    if (!settings.loopBreaker.enabled || call.name !== 'bash') return undefined
+    const command = normalizeCommand(call.args?.command)
+    const state = stateOf(call.sessionId)
+    const count = streakOf(state.loop, command)
+    if (count < settings.loopBreaker.threshold) return undefined
+    applyChange(call, escalate(state.cascade, 'loop-breaker'))
+    log.write({ type: 'loop-break', session: call.sessionId, command: truncate(command), count })
+    return {
+      kind: 'deny',
+      reason: `GreenHarness loop guard: \`${command}\` has failed ${count} times in a row with the same failure and no file change since. Do not run it again unchanged. Read the failure, change the code or the command, then rerun. The next step uses the stronger model.`,
+    }
+  }
+
+  /**
+   * Verifier bookkeeping, loop streaks and output distillation for one bash result.
+   * @param {ToolCall} call
+   * @param {ReturnType<typeof stateOf>} state
+   * @returns {Promise<{ text: string } | undefined>} the replacement result text, when distilled.
+   */
+  async function afterBash(call, state) {
+    const command = normalizeCommand(call.args?.command)
+    if (call.isError === true && call.exitCode === undefined && call.timedOut !== true) {
+      // The command never ran (its arguments were rejected), so it is no verifier outcome and
+      // does not move the cascade or the loop streak.
+      log.write({
+        type: 'tool', session: call.sessionId, tool: 'bash', action: 'not-run', command: truncate(command),
+        rawChars: (call.text ?? '').length, outChars: (call.text ?? '').length,
+      })
+      return undefined
+    }
+    const exitCode = call.exitCode ?? parseExitMarker(call.text ?? '') ?? (call.isError ? 1 : 0)
+    const outcome = classifyOutcome({ exitCode, timedOut: call.timedOut === true, text: call.text ?? '' })
+    const repeats = recordCommandOutcome(state.loop, command, outcome)
+    const verifier = isVerifierCommand(command, verifierRegexes)
+    if (verifier) applyChange(call, recordVerification(state.cascade, outcome.passed), { command: truncate(command) })
+
+    let replacement
+    let action = 'none'
+    if (settings.distill.enabled && (call.text ?? '').length > 0) {
+      const distilled = distillOutput(call.text, { maxChars: settings.distill.maxChars, contextLines: settings.distill.contextLines })
+      if (distilled.changed) {
+        const hint = call.spill ? await call.spill(call.text).catch(() => undefined) : undefined
+        const candidate = composeDistilled(distilled, hint)
+        if (candidate.length < call.text.length) {
+          replacement = candidate
+          action = 'distill'
+        }
+      }
+    }
+
+    log.write({
+      type: 'tool', session: call.sessionId, tool: 'bash', action,
+      verifier, passed: outcome.passed, exitCode, fingerprint: outcome.fingerprint, repeats,
+      command: truncate(command), rawChars: (call.text ?? '').length, outChars: replacement?.length ?? (call.text ?? '').length,
+    })
+    return replacement === undefined ? undefined : { text: replacement }
+  }
+
+  /** @param {ToolCall} call */
+  function afterRead(call) {
+    if (!settings.readDedupe.enabled || call.isError) return undefined
+    const path = call.args?.file_path
+    if (typeof path !== 'string') return undefined
+    const text = call.text ?? ''
+    const read = {
+      path,
+      offset: numberOrNull(call.args?.offset),
+      limit: numberOrNull(call.args?.limit),
+      digest: createHash('sha1').update(text).digest('hex'),
+    }
+    const earlier = findUnchangedRead(reads, call.sessionId, read)
+    if (earlier !== undefined) {
+      const replacement = `[greenharness: this read returns the same lines as the earlier read of ${path} (call ${earlier}), which is still in context. Omitted to save tokens. Reuse that result.]`
+      log.write({ type: 'tool', session: call.sessionId, tool: 'read', action: 'dedupe', path, rawChars: text.length, outChars: replacement.length })
+      return { text: replacement }
+    }
+    rememberRead(reads, call.sessionId, { ...read, callId: call.callId ?? '' })
+    log.write({ type: 'tool', session: call.sessionId, tool: 'read', action: 'none', path, rawChars: text.length, outChars: text.length })
+    return undefined
+  }
+
+  /** @param {ToolCall} call */
+  async function afterTool(call) {
+    const state = stateOf(call.sessionId)
+    if (call.name === 'bash') return afterBash(call, state)
+    if (call.name === 'read') return afterRead(call)
+    if ((call.name === 'edit' || call.name === 'write') && call.isError !== true) {
+      if (typeof call.args?.file_path === 'string') forgetPath(reads, call.sessionId, call.args.file_path)
+      noteWorkspaceChange(state.loop)
+    }
+    return undefined
+  }
+
+  /**
+   * Session event observer: writes one ledger record per model call, with the route that call
+   * actually used, and clears the read index when the context shrinks.
+   * @param {string} sessionId
+   * @param {{ type: string, data?: any }} event
+   */
+  function observeEvent(sessionId, event) {
+    const state = stateOf(sessionId)
+    if (event.type === 'request/header') {
+      const config = event.data?.header?.config
+      if (config !== undefined) state.route = { provider: config.provider, model: config.model, reasoningEffort: config.reasoningEffort }
+      return
+    }
+    if (event.type === 'assistant/message') {
+      const usage = event.data?.usage
+      if (usage === undefined) return
+      const route = state.route ?? tierRoute(state.cascade.tier) ?? { provider: '', model: '' }
+      log.write({
+        type: 'request', session: sessionId, turn: event.data.turn, step: event.data.step,
+        tier: tierOfRoute(route), provider: route.provider, model: route.model,
+        reasoningEffort: route.reasoningEffort ?? null, usage,
+        costUsd: usageCostUsd(usage, settings.ledger.pricing[route.provider]),
+      })
+      return
+    }
+    if (CONTEXT_REMOVAL_EVENTS.has(event.type)) clearSession(reads, sessionId)
+  }
+
+  return {
+    /** Counts of ledger records written by this process. */
+    stats() {
+      return { ...tally }
+    },
+    beforeTool,
+    afterTool,
+    observeEvent,
+    routeForNextCall,
+    /**
+     * Read-only view of one session's routing state, for tests and diagnostics.
+     * @param {string} sessionId
+     */
+    inspect(sessionId) {
+      const state = stateOf(sessionId)
+      return { tier: state.cascade.tier, stepsInTier: state.cascade.stepsInTier, consecutiveFailures: state.cascade.consecutiveFailures }
+    },
+  }
+}
+
+/**
+ * Text that replaces a distilled tool result, with a pointer to the full output when it was spilled.
+ * @param {ReturnType<typeof distillOutput>} distilled
+ * @param {string | undefined} hint
+ */
+function composeDistilled(distilled, hint) {
+  const { stats } = distilled
+  const pointer = hint === undefined ? '' : ` Full output: ${hint}`
+  return `${distilled.text}\n[greenharness: distilled ${stats.inChars} to ${stats.outChars} chars; dropped ${stats.droppedLines} progress lines and ${stats.droppedFrames} library frames.${pointer}]`
+}
+
+/**
+ * @param {string} text
+ * @param {number} [limit]
+ */
+function truncate(text, limit = 240) {
+  return text.length <= limit ? text : `${text.slice(0, limit)}…`
+}
+
+/**
+ * @param {unknown} value
+ */
+function numberOrNull(value) {
+  return typeof value === 'number' ? value : null
+}