opencode-harness-kit 0.6.4 → 0.7.0

package/bin/oc-harness.mjs

@@ -15,7 +15,7 @@
 import { chmodSync, copyFileSync, cpSync, mkdirSync, readFileSync, writeFileSync, existsSync, rmSync, symlinkSync, readdirSync, readlinkSync, realpathSync, lstatSync, appendFileSync, renameSync, unlinkSync } from "node:fs"
 import { homedir } from "node:os"
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path"
-import { execFileSync } from "node:child_process"
+import { execFileSync, spawnSync } from "node:child_process"
 import { fileURLToPath } from "node:url"
 import { createInterface } from "node:readline/promises"
 
@@ -94,7 +94,17 @@ function ensurePackageCopy() {
   for (const name of ["dist", "profiles", "prompts", "skills"]) {
     cpSync(join(ROOT, name), join(COPY_ROOT, name), { recursive: true })
   }
-  for (const name of ["lanes.json", "retention.yml", "GLOBAL.md"]) {
+  for (const name of ["lanes.json", "retention.yml", "GLOBAL.md", "package.json"]) {
+    // `package.json` travels with the copy because `kitVersion()` in
+    // src/config.js reads it UP from the plugin bundle's own location
+    // (`../package.json` from `dist/`). Without it, every kit field the
+    // telemetry plugin and the CLI print from a copy install read
+    // "unknown" - an install that could not say which version it was.
+    //
+    // `bin/` is deliberately NOT copied: nothing inside the copy points at
+    // the CLI, and `npx` re-fetches the entry point when the cache has been
+    // cleaned. A second copy of a 176KB CLI for a path nobody in the copy
+    // walks is dead weight, not durability.
     cpSync(join(ROOT, name), join(COPY_ROOT, name))
   }
   writeFileSync(join(COPY_ROOT, ".source"), `${want}\n`)
@@ -1620,7 +1630,7 @@ async function cmdUse(id, catalog = null, sink = {}) {
     }
     fail(msg, wantJson)
   }
-  if (!id) fail("usage: oc-harness use <profile> [--print] [--yes]")
+  if (!id) fail("usage: oc-harness use <profile> [--print] [--yes] [--no-skills]")
   let p = null
   try {
     p = loadProfile(id)
@@ -1759,7 +1769,15 @@ async function cmdUse(id, catalog = null, sink = {}) {
     )
   }
 
-  const out = generateConfig(p, { base: effectiveBase, comments: true })
+  // Relative skills paths resolve against the same directory the file lives
+  // in - the one OpenCode reads them against. The toolkit default assumes
+  // the standard config dir; the CLI knows where it actually wrote this one.
+  const out = generateConfig(p, {
+    base: effectiveBase,
+    comments: true,
+    configDir: CONFIG_DIR,
+    skills: !flag("--no-skills"),
+  })
   if (flag("--print")) {
     process.stdout.write(out)
     return
@@ -3072,8 +3090,8 @@ async function runDoctor(catalog) {
     }
     const live = catalog?.[p.provider]?.models?.[p.model]
     if (!live) {
-      console.log(`  ${red("✗")} ${id.padEnd(32)} ${red("not in models.dev - may be withdrawn")}`)
-      note("drift", id, "not in models.dev - may be withdrawn")
+      console.log(`  ${red("✗")} ${id.padEnd(32)} ${red("not in models.dev - drifted from live metadata")}`)
+      note("drift", id, "not in models.dev - drifted from live metadata")
       drift++
       continue
     }
@@ -3525,11 +3543,62 @@ async function cmdRun() {
     fail(`--role ${role} is not one of ${lanes.join(", ")}`)
   }
 
+  // `spawnSync("opencode", ...)` in the driver reports a missing binary as a
+  // failed agent, which marks the FIRST task blocked and blames the task. The
+  // install is the thing that is broken, so say that here, before any task is
+  // touched.
+  try {
+    execFileSync("opencode", ["--version"], { stdio: "ignore", timeout: 15_000 })
+  } catch (err) {
+    const code = err && typeof err === "object" && "code" in err ? err.code : undefined
+    fail(
+      code === "ENOENT"
+        ? "opencode is not on PATH. Install it first: https://opencode.ai/docs"
+        : "opencode --version failed. Fix the install before running the loop.",
+    )
+  }
+
+  // The files: scope check reads `git status`. Outside a work tree it cannot
+  // see anything, so it used to switch itself off in silence -- an unattended
+  // run believing it was fenced while it was not. The one honest place to say
+  // that is here, before the first task, and the explicit override is the same
+  // flag that already means "no scope check".
+  const allowExtraFiles = flag("--allow-extra-files")
+  if (!allowExtraFiles) {
+    const git = spawnSync("git", ["rev-parse", "--is-inside-work-tree"], {
+      encoding: "utf8",
+      timeout: 10_000,
+    })
+    if (git.status !== 0 || String(git.stdout ?? "").trim() !== "true") {
+      fail(
+        "oc-harness run needs a git work tree, because the files: scope check reads git status. Run it inside a repository, or pass --allow-extra-files to run without the check.",
+      )
+    }
+  }
+
+  // A lane's step cap is the other way an agent stops mid-task. When it is
+  // reached opencode exits 0 with a text-only answer, so the loop sees a
+  // failed verify and has no idea why. Reading the cap here lets the stop say
+  // "it ran out of steps" instead of leaving that to the log.
+  let stepCap = 0
+  try {
+    const cfg = existsSync(CONFIG_FILE) ? parseJsonc(readFileSync(CONFIG_FILE, "utf8")) : null
+    const configured = cfg?.agent?.[role]?.steps
+    if (Number.isInteger(configured) && configured > 0) stepCap = configured
+  } catch {
+    // An unreadable config is opencode's failure to report, and it will. A
+    // label on a stop is not worth turning into a second reason to fail.
+  }
+
   const result = runLoop({
     cwd: process.cwd(),
     role,
     maxRounds,
     budgetMinutes,
+    allowExtraFiles,
+    forceUnlock: flag("--force-unlock"),
+    review: flag("--review"),
+    stepCap,
   })
 
   const s = result.summary
@@ -3625,6 +3694,7 @@ try {
     auto      refresh + install + use + verify, asking nothing - the
               unattended reconcile, for an agent or a job
     use <id>  compile a profile into ${CONFIG_FILE}
+              --no-skills omits the skill list from the lanes' prompt
     show <id> print the resolved lane plan and derived numbers
     refresh <id>  update capability fields from models.dev
     install   symlink the plugin, prompts, skills and GLOBAL.md into the config dir
@@ -3642,7 +3712,7 @@ try {
     cost      what the kit is doing on this project, in numbers
     restore <file>  put one back
     baseline  measure the current opencode install
-    run       drive .space/tasks.md to done with the build agent
+    run       build and verify .space/tasks.md one task at a time
 
   options
     --print        write the config to stdout instead of disk
@@ -3665,6 +3735,14 @@ try {
     --role <agent>  which agent does the work (default: build)
     --max-rounds N  stop after N tasks (default: 20)
     --budget MIN    stop after MIN minutes (default: 120)
+    --allow-extra-files  let a task change files its files: line does not
+                   name. Without this, an out-of-scope edit stops the loop,
+                   and the run needs a git work tree to see the change.
+    --force-unlock  clear a lock held by a live pid. Only for a lock left by
+                   a pid that was reused; two real runs must not overlap.
+    --review       after verify, ask the reviewer lane for a schema'd verdict.
+                   The run stops on fail or on any malformed verdict. The
+                   verdict is written to .space/review/.
 `)
     // An unknown command is a typo, not a request for help. Without this
     // `oc-harness tsl` prints help and exits 0, so a script calling it never

package/dist/budget.d.ts

@@ -0,0 +1,247 @@
+export declare const DEFAULT_WARN_TOKENS = 2000000;
+export declare const DEFAULT_STOP_TOKENS = 5000000;
+export declare const DEFAULT_TURN_STOP_TOKENS = 300000;
+export declare const DEFAULT_WINDOW_MINUTES = 60;
+export declare const DEFAULT_WINDOW_WARN_TOKENS = 4000000;
+export declare const DEFAULT_WINDOW_STOP_TOKENS = 8000000;
+/**
+ * What one request cost, in context tokens.
+ *
+ * A `step-finish` part reports four separate numbers: `input` is the part of
+ * the prompt that was not cached, `cache.read` is the cached prefix the model
+ * still had to read, `cache.write` is the prefix stored for the next request,
+ * and `output`/`reasoning` are what the model wrote. The first three are the
+ * context; only the first was counted before, which is why a step that cost
+ * 37,324 tokens was recorded as 844.
+ *
+ * `cache.write` is charged once, on the request that stored it, so summing it
+ * here is not double counting the reads that follow. Nor does it overlap
+ * `input`: across 605 measured steps the reported `total` was exactly
+ * `input + cache.read + cache.write + output + reasoning` every time, so the
+ * parts are disjoint and the three that are counted are the whole context.
+ *
+ * A value that is not a number contributes zero: a missing field must not turn
+ * the whole count into NaN, because a NaN comparison never fires a threshold.
+ *
+ * @param {any} tokens a `step-finish` part's `tokens`
+ * @returns {number}
+ */
+export declare function requestTokens(tokens: any): number;
+/**
+ * The limits this process should use.
+ *
+ * @param {Record<string, string | undefined>} [env]
+ * @returns {{ warnAt: number, stopAt: number, turnStopAt: number }}
+ */
+export declare function budgetLimits(env?: Record<string, string | undefined>): {
+    warnAt: number;
+    stopAt: number;
+    turnStopAt: number;
+};
+/**
+ * A running total for one session.
+ *
+ * `add` returns the thresholds this call CROSSED, so the caller can warn once
+ * rather than once per request. A request that lands exactly on a threshold
+ * crosses it, and a request of zero tokens - a retry that never reached the
+ * provider - moves nothing.
+ *
+ * @param {{ warnAt?: number, stopAt?: number }} [limits]
+ */
+export declare function createBudget({ warnAt, stopAt }?: {
+    warnAt?: number;
+    stopAt?: number;
+}): {
+    /**
+     * @param {any} input tokens this request cost
+     * @returns {{ warn: boolean, stop: boolean }}
+     */
+    add(input: any): {
+        warn: boolean;
+        stop: boolean;
+    };
+    readonly total: number;
+    readonly warned: boolean;
+    readonly stopped: boolean;
+};
+/**
+ * A count with separators, for a message a human reads.
+ *
+ * @param {number} n
+ * @returns {string}
+ */
+export declare function tokens(n: number): string;
+/**
+ * Where the shared ledger lives.
+ *
+ * `XDG_STATE_HOME` is the right place for state that survives a reboot and is
+ * not configuration; falling back to `~/.local/state` is what the spec says to
+ * do. `OC_HARNESS_BUDGET_FILE` overrides both, which is what the tests use and
+ * what a user on a shared account would want.
+ *
+ * @param {Record<string, string | undefined>} [env]
+ * @returns {string}
+ */
+export declare function ledgerPath(env?: Record<string, string | undefined>): string;
+/**
+ * The entries in the ledger, or none.
+ *
+ * Three answers, not two, because "I could not read the count" and "the count
+ * is zero" are different facts and only one of them means there is room left:
+ *
+ *   - no file            -> `[]`: nothing has been spent yet.
+ *   - a file that parses -> its entries.
+ *   - a file that does not parse -> `null`.
+ *
+ * It used to return `[]` for the third case, which made a corrupt or
+ * half-written ledger indistinguishable from an empty window: the shared stop
+ * silently disappeared. `sharedWindowSpent()` in `guard.ts` repairs the file
+ * instead (see `repairSpend`): a ledger that cannot be read must not lock the
+ * window forever, because the only way out is a hand-delete the user may not
+ * know about. Nothing here throws.
+ *
+ * A `stop` entry is a marker, not a spend: `{ t, n: 0, stop: true }` records
+ * that the window was locked at `t`, so the lock can outlive the sliding sum
+ * that tripped it.
+ *
+ * @param {string} path
+ * @returns {{ t: number, n: number, stop?: boolean }[] | null}
+ */
+export declare function readSpend(path: string): {
+    t: number;
+    n: number;
+    stop?: boolean;
+}[] | null;
+/**
+ * Keep the entries that are still inside the keep window, oldest first.
+ *
+ * @param {{ t: number, n: number, stop?: boolean }[]} entries
+ * @param {number} now
+ * @returns {{ t: number, n: number, stop?: boolean }[]}
+ */
+export declare function pruneSpend(entries: {
+    t: number;
+    n: number;
+    stop?: boolean;
+}[], now: number): {
+    t: number;
+    n: number;
+    stop?: boolean;
+}[];
+/**
+ * Move an unreadable ledger aside and start a fresh one.
+ *
+ * The old code read a corrupt file as "spent" and failed closed, which is the
+ * right answer for a single tool call and the wrong answer for the machine:
+ * the only exit was deleting a file the user had never heard of, so the next
+ * session was blocked for six hours by a truncated JSON write. The evidence
+ * still matters - a corrupt ledger is a bug worth reading - so the broken file
+ * is renamed to `<path>.corrupt` rather than deleted, and an empty ledger
+ * replaces it. The count cannot be recovered, so the new file starts at zero;
+ * if the old file had a stop marker, `.corrupt` still holds it.
+ *
+ * Returns false when the repair could not be written; the caller then falls
+ * back to the old fail-closed answer rather than pretending the window is
+ * empty.
+ *
+ * @param {string} path
+ * @returns {boolean}
+ */
+export declare function repairSpend(path: string): boolean;
+/**
+ * Write the ledger, atomically.
+ *
+ * Read-modify-write without a lock: two sessions finishing a step in the same
+ * millisecond can lose one entry. That is a few thousand tokens on a budget of
+ * millions, and a lock file in this path is a worse failure mode - a crashed
+ * session would leave the window blocked for everyone.
+ *
+ * @param {string} path
+ * @param {{ t: number, n: number, stop?: boolean }[]} entries
+ */
+export declare function writeSpend(path: string, entries: {
+    t: number;
+    n: number;
+    stop?: boolean;
+}[]): void;
+/**
+ * Add one request's cost to the shared ledger.
+ *
+ * A ledger that cannot be read is repaired first, so the first write after a
+ * corruption appends to a fresh file instead of overwriting the broken one.
+ * The repair does not invent a stop: the count is unknown, and a marker that
+ * holds for six hours is the failure this repair exists to end.
+ *
+ * @param {string} path
+ * @param {number} n
+ * @param {number} [now]
+ * @returns {{ t: number, n: number, stop?: boolean }[]} the pruned ledger
+ */
+export declare function recordSpend(path: string, n: number, now?: number): {
+    t: number;
+    n: number;
+    stop?: boolean;
+}[];
+/**
+ * Record that the window was locked, so the lock survives the window it was
+ * measured in.
+ *
+ * The sum is over the last hour, and the provider's window is not: it stayed
+ * shut for hours after the stop fired. A lock that releases itself on a timer
+ * is a lock that was only partly on, so the marker holds until `KEEP_MS`.
+ *
+ * @param {string} path
+ * @param {number} [now]
+ * @returns {{ t: number, n: number, stop?: boolean }[]} the pruned ledger
+ */
+export declare function recordStop(path: string, now?: number): {
+    t: number;
+    n: number;
+    stop?: boolean;
+}[];
+/**
+ * Whether a stop marker is still inside the keep window.
+ *
+ * @param {{ t: number, n: number, stop?: boolean }[]} entries
+ * @param {number} now
+ * @returns {boolean}
+ */
+export declare function stopRecorded(entries: {
+    t: number;
+    n: number;
+    stop?: boolean;
+}[], now: number): boolean;
+/**
+ * Tokens spent in the last `windowMs`, across every session on this machine.
+ *
+ * @param {{ t: number, n: number, stop?: boolean }[]} entries
+ * @param {number} now
+ * @param {number} windowMs
+ * @returns {number}
+ */
+export declare function windowSpend(entries: {
+    t: number;
+    n: number;
+    stop?: boolean;
+}[], now: number, windowMs: number): number;
+/**
+ * The shared-window thresholds.
+ *
+ * `OC_HARNESS_BUDGET_WINDOW_MINUTES` sets the window (default 60). Zero or a
+ * value that is not a positive number falls back to the default: a window of
+ * zero would sum nothing and silently disable the tripwire.
+ *
+ * `OC_HARNESS_BUDGET_WINDOW_STICKY` (default on) makes a stop hold until its
+ * marker ages out, instead of ending when the entries that tripped it roll out
+ * of the window. `0` restores the sum-only behaviour, which unlocks the
+ * window on a timer the provider does not keep.
+ *
+ * @param {Record<string, string | undefined>} [env]
+ * @returns {{ windowMs: number, warnAt: number, stopAt: number, sticky: boolean }}
+ */
+export declare function windowLimits(env?: Record<string, string | undefined>): {
+    windowMs: number;
+    warnAt: number;
+    stopAt: number;
+    sticky: boolean;
+};

package/dist/config.d.ts

@@ -27,6 +27,35 @@ export declare const GLOBAL_INSTRUCTIONS = "~/.config/opencode/GLOBAL.md";
  * @returns {string}
  */
 export declare function kitVersion(): string;
+/** Where opencode's user config lives when nothing overrides it. */
+export declare const DEFAULT_CONFIG_DIR: string;
+/** Where this kit itself lives - the parent of the bundle (or src) directory. */
+export declare function kitRoot(): string;
+/**
+ * The skills.paths entries of a base config, with the dead ones dropped.
+ *
+ * A `paths` entry that never resolves is not a configuration - it is noise
+ * the file carries for every reader to puzzle over, and a reader who DOES
+ * puzzle over it gets a wrong model of the world: this kit's config shipped
+ * `["../skills"]` which had dl resolved to `~/.config/skills` - a directory
+ * that has never existed on this machine - for release after release.
+ *
+ * A relative entry resolves against the opencode config directory; an
+ * absolute one stands as written; a relative one is also checked against the
+ * kit root, because an entry pointing INTO the kit was always a plausible
+ * intent and the kit knows where its own skills are. Nothing that resolves
+ * is kept; word everything else is dropped and named in the header, the same
+ * way dropped bash rules and removed lanes are.
+ *
+ * @param {any} skills
+ * @param {string} configDir
+ * @param {string} [kitRoot] where the kit itself lives, when overridable
+ * @returns {{ skills: any, dropped: string[] }}
+ */
+export declare function cleanSkillPaths(skills: any, configDir: string, kitRoot?: string): {
+    skills: any;
+    dropped: string[];
+};
 /**
  * The memory plugin this kit can turn on.
  *
@@ -122,11 +151,15 @@ export declare const BASH_ALLOWLIST: string[];
 export { BASH_DENYLIST } from "./denylist.js";
 /**
  * @param {Profile} p
- * @param {{ base?: Record<string, any>, comments?: boolean, unhealthy?: Set<string> }} [opts]
+ * @param {{ base?: Record<string, any>, comments?: boolean, unhealthy?: Set<string>,
+ *          configDir?: string, kitRoot?: string, skills?: boolean }} [opts]
  * @returns {string}
  */
 export declare function generateConfig(p: Profile, opts?: {
     base?: Record<string, any>;
     comments?: boolean;
     unhealthy?: Set<string>;
+    configDir?: string;
+    kitRoot?: string;
+    skills?: boolean;
 }): string;

package/dist/effort.d.ts

@@ -35,12 +35,23 @@ export type EffortResult = {
  */
 export declare const MANAGED_ROLES: string[];
 /**
+ * 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 declare function planEffort(profileId: string, opts?: {
     unhealthy?: Set<string>;
+    dir?: string;
 }): EffortResult;
 /**
  * Mutate the resolved OpenCode config so each managed agent declares its own

package/dist/guard.d.ts

@@ -8,6 +8,11 @@ export declare const MARKER = "[opencode-harness-kit] blocked";
  * 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

package/dist/health.d.ts

@@ -110,11 +110,22 @@ export declare function unhealthyRoutes(dir: string): Record<string, SpentEntry>
  * 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 declare function unhealthyModels(dir: string): Set<string>;
+export declare function unhealthyModels(dir: string, provider?: string): Set<string>;