opencode-harness-kit 0.6.4 → 0.7.0

package/src/effort.js

@@ -12,6 +12,7 @@
 // `max` gets the nearest level that actually exists.
 
 import { loadProfile, resolveRoles, resolveDefaultVariant, resolveLaneModel, LANE_NAMES } from "./profile.js"
+import { unhealthyModels } from "./health.js"
 
 /**
  * @typedef {import("./profile.js").Profile} Profile
@@ -39,14 +40,27 @@ import { loadProfile, resolveRoles, resolveDefaultVariant, resolveLaneModel, LAN
 export const MANAGED_ROLES = LANE_NAMES
 
 /**
+ * The spent routes the effort plan honours.
+ *
+ * `opts.unhealthy` is a bare-model set a caller computed already - the one
+ * contract the tests and the CLI use. `opts.dir` is the project root, and it
+ * asks the plan to read the health file itself under the profile's OWN
+ * provider: a health file keyed `openrouter/<x>` must not read as a spent
+ * `opencode/<x>`, and a bare set has already lost the provider it came from,
+ * so the caller cannot narrow it after the fact. Passing both is the
+ * caller's narrowed set, and it wins.
+ *
  * @param {string} profileId
- * @param {{ unhealthy?: Set<string> }} [opts]
+ * @param {{ unhealthy?: Set<string>, dir?: string }} [opts]
  * @returns {EffortResult}
  */
 export function planEffort(profileId, opts = {}) {
   const p = loadProfile(profileId)
+  const unhealthy =
+    opts.unhealthy ?? (opts.dir ? unhealthyModels(opts.dir, p.provider) : undefined)
+  const scoped = unhealthy === undefined ? opts : { ...opts, unhealthy }
   const levels = p.effort?.levels ?? []
-  const roles = resolveRoles(p, opts)
+  const roles = resolveRoles(p, scoped)
   const notes = []
 
   if (levels.length === 0) {
@@ -75,7 +89,7 @@ export function planEffort(profileId, opts = {}) {
   /** @type {Record<string, string>} */
   const laneModels = {}
   for (const role of Object.keys(p.roles ?? {})) {
-    laneModels[role] = resolveLaneModel(p, role, opts).model
+    laneModels[role] = resolveLaneModel(p, role, scoped).model
   }
 
   return {

package/src/guard.ts

@@ -10,6 +10,20 @@ import type { Plugin } from "./plugin.js"
 import { homedir, tmpdir } from "node:os"
 import { join, resolve } from "node:path"
 import { checkBash, checkDenied, checkWrite, insideRoot } from "./rules.js"
+import {
+  budgetLimits,
+  createBudget,
+  ledgerPath,
+  readSpend,
+  recordSpend,
+  recordStop,
+  repairSpend,
+  requestTokens,
+  stopRecorded,
+  tokens,
+  windowLimits,
+  windowSpend,
+} from "./budget.js"
 
 import { write } from "./telemetry-store.js"
 import { projectRoot } from "./project.js"
@@ -53,6 +67,25 @@ function hunkFollows(lines: string[], from: number): boolean {
   return false
 }
 
+/**
+ * How many lines a standard unified-diff hunk header announces.
+ *
+ * The body of a hunk is where a `---`/`+++` pair can appear as content, so
+ * the body has to be stepped over rather than read. `@@ -1 +1 @@` has one
+ * old and one new line; `@@ -1,0 +1,2 @@` has two; `@@ -1,2 +1,3 @@` has
+ * five; `@@` with no counts (opencode's own marker) announces none.
+ *
+ * @param {string} header
+ * @returns {number}
+ */
+function hunkLineCount(header: string): number {
+  const m = /^@@\s+-(\d+)(?:,(\d+))?\s+\+(\d+)(?:,(\d+))?\s+@@/.exec(header)
+  if (!m) return 0
+  const oldCount = m[2] === undefined ? 1 : Number(m[2])
+  const newCount = m[4] === undefined ? 1 : Number(m[4])
+  return oldCount + newCount
+}
+
 /**
  * The files a patch touches.
  *
@@ -61,6 +94,11 @@ function hunkFollows(lines: string[], from: number): boolean {
  * markers, and a plain unified diff with `--- a/path` and `+++ b/path`
  * headers.
  *
+ * An update may also carry `*** Move to: path`, which is the path the file
+ * is written TO. Reading only the `*** Update File:` line checked the file
+ * the patch read from and left the destination unchecked, so a patch could
+ * move a file out of the project while every path it named was inside it.
+ *
  * A unified diff names the file TWICE: `--- a/path` is where the change
  * comes FROM, `+++ b/path` is where it goes TO. A deletion is `--- a/path`
  * and `+++ /dev/null`, so the path that has to be scope-checked is the one
@@ -92,15 +130,48 @@ export function pathsInPatch(text: string): string[] {
   // Whether a hunk header has been seen. After one, a `+++` line is added
   // content and not the header of another file.
   let seenHunk = false
+  // How many body lines of the current hunk are still to be stepped over.
+  // Reading a hunk body as headers is what turned a removed line whose
+  // content is "-- foo" into a path.
+  let hunkRemaining = 0
+  // opencode's own patch format names files with `*** ... File:` markers,
+  // and everything between them is content. A body line in that format is
+  // not a diff header, and the parser must not read one as a path.
+  let applyPatch = false
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i]
     const marker = /^\*\*\*\s+(?:Add|Update|Delete)\s+File:\s*(.+)$/.exec(line)
     if (marker) {
+      applyPatch = true
       push(marker[1])
       continue
     }
+    // The destination of an update that moves the file. It is a write just
+    // like the `*** Update File:` path, and the path it moves to is the one
+    // that can leave the project.
+    const move = /^\*\*\*\s+Move to:\s*(.+)$/.exec(line)
+    if (move) {
+      push(move[1])
+      continue
+    }
+    if (applyPatch) continue
+    // Step over the body of a hunk before looking for headers in it. A
+    // hunk body line starts with a space, `-` or `+`; `\ No newline...` is
+    // a note and counts for nothing.
+    if (hunkRemaining > 0) {
+      const first = line[0]
+      if (first === " " || first === "-" || first === "+") {
+        hunkRemaining--
+        continue
+      }
+      if (first === "\\") continue
+      // A line that cannot be a hunk body means the counts were wrong. Fall
+      // through and read this line normally rather than swallow a header.
+      hunkRemaining = 0
+    }
     if (/^@@/.test(line)) {
       seenHunk = true
+      hunkRemaining = hunkLineCount(line)
       continue
     }
     // The `---` and `+++` headers of a unified diff are one pair: the
@@ -167,7 +238,7 @@ function truncate(s: string, n = 200): string {
   return one.length > n ? `${one.slice(0, n)}...` : one
 }
 
-export const GuardPlugin: Plugin = async ({ worktree, directory }) => {
+export const GuardPlugin: Plugin = async ({ worktree, directory, client }) => {
   // The project root, not the worktree: the worktree is the filesystem root
   // in a project that is not a git repository, so the scope check was against
   // "/" - which contains every path - and the denial log went nowhere.
@@ -188,9 +259,241 @@ export const GuardPlugin: Plugin = async ({ worktree, directory }) => {
     deny(why, detail)
   }
 
+  // The free tier is a shared window and opencode never shows a number for
+  // it. One session made 599 requests and 12,025,980 uncached input tokens;
+  // the first sign of trouble was the provider refusing the next one, which
+  // reads as a broken model rather than a spent budget. This counts the window
+  // and says so while there is still room to act.
+  //
+  // Per session, because a subagent gets its own session and its own prompt:
+  // charging its tokens to the parent would warn the wrong conversation.
+  const limits = budgetLimits()
+  const budgets = new Map<string, ReturnType<typeof createBudget>>()
+  /** `step-finish` parts already counted, so an update is not a second step. */
+  const counted = new Set<string>()
+  // A single request that re-sent more than `OC_HARNESS_TURN_STOP`. This is
+  // the count that sees a deny/retry loop: each retry is a new request whose
+  // per-session total still looks small, but whose context re-send is the
+  // whole prompt. Keyed by session, valued by the size that tripped it.
+  const turnStops = new Map<string, number>()
+
+  // The window is shared, so the count cannot live in this process: two
+  // sessions open at once are two processes, and the one that has to warn is
+  // often not the one that spent. Every step is appended to a ledger file and
+  // the last hour is summed from it.
+  const window = windowLimits()
+  const ledger = ledgerPath()
+  let windowWarned = false
+  let windowSpent = false
+  /** Why the window is spent, so the refusal states the real reason. */
+  let windowWhy = ""
+
+  /** The sum crossing its stop. Also the reason a recorded stop keeps holding. */
+  const sumWhy = () =>
+    `all sessions have used ${tokens(window.stopAt)} context tokens in the last ` +
+    `${Math.round(window.windowMs / 60_000)} min. Wait for it to roll, or raise OC_HARNESS_BUDGET_WINDOW_STOP.`
+
+  const budgetFor = (sessionID: string) => {
+    let b = budgets.get(sessionID)
+    if (!b) {
+      b = createBudget(limits)
+      budgets.set(sessionID, b)
+    }
+    return b
+  }
+
+  /**
+   * Why the shared window is spent, or null if it is not.
+   *
+   * Checked against the ledger, not only the cached flag: a session that opens
+   * after the window ran out has seen no step of its own, so the flag would
+   * still be false and its first tool call would go through.
+   *
+   * Three ways to be spent, and all three fail closed:
+   *
+   *   - a stop was recorded and its marker has not aged out. The sum is over
+   *     the last hour; the provider's window is not, so a lock that ends when
+   *     the sum rolls over was only partly on.
+   *   - the sum crossed the stop.
+   *   - the ledger exists and cannot be read. That is not a window with room
+   *     in it - it is an unknown count, and the old code read it as zero.
+   */
+  const sharedWindowSpent = (): string | null => {
+    if (windowSpent) return windowWhy
+    if (window.stopAt <= 0) return null
+    const entries = readSpend(ledger)
+    if (entries === null) {
+      // A corrupt ledger used to fail closed, and the only way out was a
+      // hand-delete the user had never heard of. Repair it instead and say so
+      // in telemetry; only a repair that cannot be written still fails closed.
+      if (repairSpend(ledger)) {
+        write(telemetryDir, { kind: "budget repair", tool: "ledger", rule: "corrupt ledger moved to .corrupt" })
+        return null
+      }
+      windowSpent = true
+      windowWhy =
+        `the ledger at ${ledger} exists but cannot be read or repaired, so the spend cannot be counted. ` +
+        `It is treated as spent rather than as zero: delete that file to start the window over, ` +
+        `or raise OC_HARNESS_BUDGET_WINDOW_STOP.`
+      return windowWhy
+    }
+    const now = Date.now()
+    if (window.sticky && stopRecorded(entries, now)) {
+      windowSpent = true
+      windowWhy =
+        `a stop was recorded in this ledger and holds until its entries age out (six hours). ` +
+        `The provider's window does not reopen on the ${Math.round(window.windowMs / 60_000)}-min timer, ` +
+        `so this one does not either. Raise OC_HARNESS_BUDGET_WINDOW_STOP, or set ` +
+        `OC_HARNESS_BUDGET_WINDOW_STICKY=0 to let the sum alone decide.`
+      return windowWhy
+    }
+    if (windowSpend(entries, now, window.windowMs) >= window.stopAt) {
+      windowSpent = true
+      windowWhy = sumWhy()
+      // Persist the lock. The sum rolls out of the one-hour window while the
+      // provider's window stays shut, and a session that opens after the roll
+      // must not get a fresh turn out of the same spent budget.
+      try {
+        recordStop(ledger)
+      } catch {
+        // An unwritable ledger still blocks this process through windowSpent.
+      }
+      return windowWhy
+    }
+    return null
+  }
+
+  /** A toast is a courtesy, never a reason to fail a turn. */
+  const toast = async (message: string, variant: "info" | "warning" | "error") => {
+    try {
+      await client?.tui?.showToast({ body: { message, variant, duration: 12_000 } })
+    } catch {
+      // A client that cannot show a toast still gets the block below.
+    }
+  }
+
   return {
+    // The tokens are reported on the `step-finish` part, once per request.
+    // `message.updated` was the other candidate, but its token count grows
+    // while the request streams and would have to be diffed per message; the
+    // step part is already the final cost of that request.
+    //
+    // The cost is the whole context, not `tokens.input`: with prompt caching
+    // the uncached part is a few hundred tokens against tens of thousands of
+    // `cache.read`, so counting `input` alone made every threshold here about
+    // five to forty times too high. See `requestTokens` in ./budget.js.
+    event: async ({ event }: any) => {
+      if (event?.type !== "message.part.updated") return
+      const part = event.properties?.part
+      if (!part || part.type !== "step-finish" || !part.sessionID) return
+      if (part.id) {
+        if (counted.has(part.id)) return
+        counted.add(part.id)
+      }
+      const b = budgetFor(part.sessionID)
+      const spent = requestTokens(part.tokens)
+      const crossed = b.add(spent)
+
+      // The shared window, from the ledger every session writes to.
+      let recent = 0
+      if (spent > 0) {
+        try {
+          recent = windowSpend(recordSpend(ledger, spent), Date.now(), window.windowMs)
+        } catch {
+          // An unwritable state directory must not break the session. The
+          // per-session budget above still applies.
+        }
+        if (!windowWarned && window.warnAt > 0 && recent >= window.warnAt) {
+          windowWarned = true
+          await toast(
+            `All sessions have used ${tokens(recent)} context tokens in the last ${Math.round(window.windowMs / 60_000)} min ` +
+              `(warn at ${tokens(window.warnAt)}). The provider's window is shared, so a new session does not reset it.`,
+            "warning",
+          )
+        }
+        if (!windowSpent && window.stopAt > 0 && recent >= window.stopAt) {
+          windowSpent = true
+          // Without this, `sharedWindowSpent()` returned the empty windowWhy
+          // and every tool call was allowed: the toast said "blocked" while
+          // the guard passed. The reason and the marker have to be set here,
+          // where the sum crossed.
+          windowWhy = sumWhy()
+          try {
+            recordStop(ledger)
+          } catch {
+            // The in-process flag still blocks this session.
+          }
+          await toast(
+            `The shared window hit ${tokens(window.stopAt)} context tokens in ${Math.round(window.windowMs / 60_000)} min: ` +
+              `tool calls are now blocked in every session. Wait for it to roll, or raise OC_HARNESS_BUDGET_WINDOW_STOP.`,
+            "error",
+          )
+        }
+      }
+
+      // The turn stop, before the total: a loop is one request re-sending the
+      // whole prompt, and the total may still be far below its stop. Block the
+      // next tool call in this session and say not to retry - a retry is what
+      // spent the window.
+      if (
+        limits.turnStopAt > 0 &&
+        spent >= limits.turnStopAt &&
+        !turnStops.has(part.sessionID)
+      ) {
+        turnStops.set(part.sessionID, spent)
+        await toast(
+          `One request in this session re-sent ${tokens(spent)} context tokens ` +
+            `(turn stop ${tokens(limits.turnStopAt)}). Tool calls in this session are now blocked: ` +
+            `stop, do not retry the same step. Start a new session with a smaller task.`,
+          "error",
+        )
+      }
+
+      if (crossed.warn) {
+        await toast(
+          `This session has used ${tokens(b.total)} context tokens (warn at ${tokens(limits.warnAt)}). ` +
+            `Start a new session before the provider's window runs out.`,
+          "warning",
+        )
+      }
+      if (crossed.stop) {
+        await toast(
+          `This session hit its ${tokens(limits.stopAt)}-token budget: tool calls are now blocked. ` +
+            `Start a new session, or raise OC_HARNESS_BUDGET_STOP.`,
+          "error",
+        )
+      }
+    },
     "tool.execute.before": async (input: any, output: any) => {
       try {
+        const budget = input.sessionID ? budgets.get(input.sessionID) : undefined
+        if (budget?.stopped) {
+          refuse(
+            input.tool,
+            "session token budget",
+            "the session hit its token budget",
+            `it has used ${tokens(budget.total)} context tokens, and the stop threshold is ${tokens(limits.stopAt)}. ` +
+              `Start a new session, or raise OC_HARNESS_BUDGET_STOP.`,
+          )
+        }
+        // A new session does not reset the provider's window, so the shared
+        // stop has to hold across sessions - otherwise the fix for a spent
+        // session is "open another one", which spends the same window again.
+        const spentReason = sharedWindowSpent()
+        if (spentReason) {
+          refuse(input.tool, "shared token window", "the shared token window is spent", spentReason)
+        }
+        const turnSpend = input.sessionID ? turnStops.get(input.sessionID) : undefined
+        if (turnSpend !== undefined) {
+          refuse(
+            input.tool,
+            "single request budget",
+            "a single request in this session re-sent too much context",
+            `it re-sent ${tokens(turnSpend)} tokens against a turn stop of ${tokens(limits.turnStopAt)}. ` +
+              `Stop: do not retry the same step, because every retry re-sends the same prompt. ` +
+              `Start a new session with a smaller task, or raise OC_HARNESS_TURN_STOP.`,
+          )
+        }
         if (input.tool === "bash") {
           // The bash tool takes a `workdir`, and it becomes the command's
           // working directory. A command run from outside the project is

package/src/health.js

@@ -236,16 +236,28 @@ export function unhealthyRoutes(dir) {
  * lane chains list bare model ids, so the prefix is dropped here. Comparing
  * the two directly would never match, and a spent route would look healthy.
  *
+ * The drop collides when two providers host the same model id: a recorded
+ * `openrouter/<x>` then reads as a spent `opencode/<x>`, and every lane whose
+ * chain names the opencode one is pushed off a route that is fine. `provider`
+ * narrows the answer to the routes a session of THAT provider can actually
+ * hit - a provider-qualified key for another provider is dropped, and a key
+ * with no provider at all is kept, because a bare key is a standing statement
+ * about the model id and it is not readable as any narrower one. Callers
+ * including the router, whose lane set may not share one provider, keep the
+ * unfiltered call and its old behaviour.
+ *
  * A route whose window has passed is not spent any more, and is not returned
  * here: the provider's quota comes back at 00:00 UTC, and a lane that stays
  * on its fallback forever is a lane that never comes back either.
  *
  * @param {string} dir the project root
+ * @param {string} [provider] only count routes served by this provider
  * @returns {Set<string>}
  */
-export function unhealthyModels(dir) {
+export function unhealthyModels(dir, provider) {
   const out = new Set()
   for (const key of Object.keys(unhealthyRoutes(dir))) {
+    if (provider && key.includes("/") && !key.startsWith(`${provider}/`)) continue
     out.add(key.includes("/") ? key.slice(key.indexOf("/") + 1) : key)
   }
   return out

package/src/index.ts

@@ -20,7 +20,6 @@ import { TelemetryPlugin } from "./telemetry.js"
 import { applyEffort, planEffort } from "./effort.js"
 import { profileIdFromConfig } from "./profile.js"
 import { projectRoot } from "./project.js"
-import { unhealthyModels } from "./health.js"
 
 export interface HarnessOptions {
   /** Profile id. Defaults to the one recorded in the config by `oc-harness use`. */
@@ -69,9 +68,9 @@ export const HarnessPlugin: Plugin = async (ctx, options?: HarnessOptions) => {
     // file the router writes is somewhere else entirely.
     const project = projectRoot(ctx.directory, ctx.worktree)
     try {
-      // The same set of spent routes the router used. A lane that failed over
-      // to a model with fewer effort levels must not keep the variant the
-      // previous model had.
+      // The same set of spent routes the router used, read HERE under the
+      // profile's own provider: a health file keyed `openrouter/<x>` must not
+      // read as a spent `opencode/<x>` for a profile served by opencode.
       //
       // The session model is read before the effort plan is applied, because
       // the router may have moved it onto a fallback while the base route was
@@ -80,16 +79,28 @@ export const HarnessPlugin: Plugin = async (ctx, options?: HarnessOptions) => {
         typeof config?.harness?.sessionModel === "string"
           ? config.harness.sessionModel
           : undefined
-      applyEffort(config, planEffort(id, { unhealthy: unhealthyModels(project) }), {
+      applyEffort(config, planEffort(id, { dir: project }), {
         sessionModel,
       })
-      // Record it where the prune hook looks, so pruning picks up this
-      // profile's thresholds without access to the resolved config.
-      //
-      // Under the PROJECT root, not the worktree: the worktree is the
-      // filesystem root in a project that is not a git repository, and the
-      // write fails there with a permission error that this catch swallows.
-      // The pruner then finds no active profile and does nothing at all.
+    } catch {
+      // Never block startup on a bad profile.
+    }
+    // Record it where the prune hook looks, so pruning picks up this
+    // profile's thresholds without access to the resolved config.
+    //
+    // Under the PROJECT root, not the worktree: the worktree is the
+    // filesystem root in a project that is not a git repository, and the
+    // write fails there with a permission error that this catch swallows.
+    // The pruner then finds no active profile and does nothing at all.
+    //
+    // This used to sit inside the same try as applyEffort, and an applyEffort
+    // throw skipped it: a config that could not accept the effort plan (an
+    // agent dictionary OpenCode froze, a model line it rejects) left the
+    // marker stale, and the pruner ran on the PREVIOUS profile's thresholds
+    // until the next clean startup. The marker is therefore written
+    // independently - it is a statement about which profile the config names,
+    // not a consequence of whether the effort plan applied.
+    try {
       const dir = join(project, ".space")
       mkdirSync(dir, { recursive: true })
       writeFileSync(join(dir, "active"), `${id}\n`)

package/src/profile.js

@@ -57,7 +57,7 @@ export const ROOT = findRoot(resolve(HERE, ".."))
  * @typedef {"zero-retention" | "retained" | "may-train" | "unknown"} Retention
  * @typedef {string | null} EffortRequest
  * @typedef {{ model: string, levels?: string[], chain?: string[] }} RoleModel
- * @typedef {{ description: string, mode?: string, steps?: number, permission?: Record<string, any>, prompt: string }} Lane
+ * @typedef {{ description: string, mode?: string, steps?: number, permission?: Record<string, any>, prompt: string, skills?: boolean }} Lane
  * @typedef {object} Profile
  * @property {string} id
  * @property {string} [title]

package/src/prune.ts

@@ -21,6 +21,7 @@ import { loadProfile, pruneThreshold, ROOT } from "./profile.js"
 import { projectRoot } from "./project.js"
 import { readFileSync, existsSync } from "node:fs"
 import { join } from "node:path"
+import { rotate as rotateFile, MAX_BYTES } from "./telemetry-store.js"
 
 /**
  * Which profile is active. In order: an explicit environment variable, then the
@@ -486,13 +487,26 @@ export const PrunePlugin: Plugin = async ({ worktree, directory }) => {
   }
 }
 
-async function logPrune(
+/**
+ * Append one line to the project's prune log, and rotate it when the file
+ * outgrew `maxBytes`.
+ *
+ * Exported so the rotation can be driven directly in the tests: reaching it
+ * through the hook needs a 4MB fixture, which is not a fixture.
+ *
+ * @param {string} worktree the project the log belongs to
+ * @param {string} profileId the profile the prune ran under
+ * @param {StubStats & { saved: number, threshold: number }} stats
+ * @param {number} [maxBytes] rotate above this; the telemetry default
+ */
+export async function logPrune(
   worktree: string,
   profileId: string,
   stats: StubStats & {
     saved: number
     threshold: number
   },
+  maxBytes: number = MAX_BYTES,
 ) {
   // The WORKTREE, not `process.cwd()`. Every other writer in this kit uses
   // the worktree, and the plugin's worktree is the project. The process cwd
@@ -504,6 +518,12 @@ async function logPrune(
   try {
     const { mkdir, appendFile } = await import("node:fs/promises")
     await mkdir(dir, { recursive: true })
+    // Rotated on the same scheme as the telemetry log: the file records one
+    // line per prune run, nothing samples its SIZE before appending, and an
+    // active project filled it to 1.5 megabytes in a day. The telemetry store
+    // already owns the three-generation rotation; the prune log borrows it
+    // rather than naming its own file schedule.
+    rotateFile(join(dir, "prune.jsonl"), maxBytes)
     await appendFile(
       join(dir, "prune.jsonl"),
       JSON.stringify({