opencode-harness-kit 0.4.2 → 0.4.4

package/src/router.ts

@@ -18,9 +18,13 @@
 // retry it. The daily window resets at 00:00 UTC, so waiting inside a session
 // is the wrong shape anyway.
 
-import type { Plugin } from "@opencode-ai/plugin"
+import type { Plugin } from "./plugin.js"
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs"
 import { join } from "node:path"
+import { safeStringify } from "./safe.js"
+import { projectRoot } from "./project.js"
+import { utilityModel } from "./config.js"
+import { readHealth, writeHealth, unhealthyModels } from "./health.js"
 import {
   loadProfile,
   pruneThreshold,
@@ -32,55 +36,6 @@ import {
   resolveRoles,
 } from "./profile.js"
 
-interface Health {
-  unhealthy: Record<string, { at: string; reason: string }>
-  active?: string
-}
-
-function healthPath(worktree: string): string {
-  return join(worktree, ".space", "health.json")
-}
-
-function readHealth(worktree: string): Health {
-  try {
-    return JSON.parse(readFileSync(healthPath(worktree), "utf8"))
-  } catch {
-    return { unhealthy: {} }
-  }
-}
-
-function writeHealth(worktree: string, h: Health) {
-  try {
-    mkdirSync(join(worktree, ".space"), { recursive: true })
-    writeFileSync(healthPath(worktree), JSON.stringify(h, null, 2))
-  } catch {
-    // Best effort.
-  }
-}
-
-/**
- * The models a previous session found spent.
- *
- * Exported so the effort hook resolves a lane's variant against the model the
- * lane actually ended up on. A lane that failed over from a model with a
- * `none` effort level to one without levels has to lose its variant, or the
- * config asks for an effort the new model does not publish.
- *
- * @param {string} worktree
- * @returns {Set<string>}
- */
-export function unhealthyModels(worktree: string): Set<string> {
-  const health = readHealth(worktree)
-  // The health file is keyed by the qualified route, `opencode/<model>`. The
-  // 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.
-  const out = new Set<string>()
-  for (const key of Object.keys(health.unhealthy ?? {})) {
-    out.add(key.includes("/") ? key.slice(key.indexOf("/") + 1) : key)
-  }
-  return out
-}
-
 /** Patterns that mean "this route is spent", not "this request was bad". */
 const SPENT = [
   /FreeUsageLimitError/i,
@@ -103,17 +58,21 @@ const WARN_TEXT =
   "new session. Run `oc-harness list` to see the lanes and their chains, or `oc-harness doctor` " +
   "to check whether the profile still matches live metadata."
 
-export const RouterPlugin: Plugin = async ({ worktree }) => {
+export const RouterPlugin: Plugin = async ({ worktree, directory }) => {
+  // The project root, not the worktree: the worktree is the filesystem root in
+  // a project that is not a git repository, so the health file was written
+  // nowhere and no lane ever failed over.
+  const project = projectRoot(directory, worktree)
   let failedSessions = 0
   let warned = false
 
   return {
     // Runs once, before the session does any work.
-    config: async (config) => {
+    config: async (config: any) => {
       try {
         const cfg = config as Record<string, any>
-        const health = readHealth(worktree)
-        const unhealthy = unhealthyModels(worktree)
+        const health = readHealth(project)
+        const unhealthy = unhealthyModels(project)
 
         // config.harness is stripped by schema validation, so the active
         // profile comes from the config file on disk.
@@ -139,13 +98,15 @@ export const RouterPlugin: Plugin = async ({ worktree }) => {
         if (health.unhealthy?.[baseKey]) {
           const queue = [id, ...(profile.fallback ?? [])]
           for (const candidate of queue) {
-            if (health.unhealthy?.[`opencode/${candidate}`]) continue
             let fallback
             try {
               fallback = loadProfile(candidate)
             } catch {
               continue
             }
+            // The health file is keyed by MODEL, and a fleet's profile id is
+            // not its model - so the check has to be against the model's own
+            // key. Checking the id was a check that could never fire.
             const key = `opencode/${fallback.model}`
             if (health.unhealthy?.[key]) continue
             const fleet = isFleet(profile)
@@ -158,7 +119,7 @@ export const RouterPlugin: Plugin = async ({ worktree }) => {
               threshold: fleet ? pruneThreshold(profile) : undefined,
             })
             health.active = candidate
-            writeHealth(worktree, health)
+            writeHealth(project, health)
             break
           }
         }
@@ -189,12 +150,15 @@ export const RouterPlugin: Plugin = async ({ worktree }) => {
       }
     },
 
-    event: async ({ event }) => {
+    event: async ({ event }: any) => {
       const e = event as any
       const type = e?.type
       if (!type) return
 
-      const text = JSON.stringify(e)
+      // The event is opencode's object, and it can hold a reference back to
+      // itself. A plain JSON.stringify on a cyclic object throws, and a hook
+      // that throws takes the event down with it.
+      const text = safeStringify(e)
       const reason = classify(text)
       if (!reason) return
 
@@ -203,14 +167,14 @@ export const RouterPlugin: Plugin = async ({ worktree }) => {
       const key = modelID ? `opencode/${modelID}` : undefined
       if (!key) return
 
-      const health = readHealth(worktree)
+      const health = readHealth(project)
       if (health.unhealthy[key]) return // already recorded, do not spam
       health.unhealthy[key] = { at: new Date().toISOString(), reason }
-      writeHealth(worktree, health)
+      writeHealth(project, health)
       failedSessions++
     },
 
-    "chat.message": async (input, output) => {
+    "chat.message": async (input: any, output: any) => {
       // If this session has already hit a spent route, say so once, early,
       // instead of letting the agent burn turns discovering it.
       if (failedSessions === 0) return
@@ -226,7 +190,7 @@ export const RouterPlugin: Plugin = async ({ worktree }) => {
         return
       }
       // Nothing to attach to: the health file and telemetry still record it.
-      writeHealth(worktree, readHealth(worktree))
+      writeHealth(project, readHealth(project))
     },
   }
 }
@@ -268,7 +232,12 @@ function applySessionModel(
   try {
     const model = `${profile.provider}/${profile.model}`
     cfg.model = model
-    cfg.small_model = model
+    // The utility route belongs to the fleet, not to the model that happens
+    // to be the session's. Overwriting it with the fallback's session model
+    // threw away the cheap route exactly when the fleet failed over, and
+    // `verify` then called the difference between the file on disk and the
+    // running session a drift.
+    cfg.small_model = utilityModel(profile) ?? model
     const variant = profile.effort?.default
     if (profile.effort?.levels?.length && variant) cfg.variant = variant
     else delete cfg.variant

package/src/rules.js

@@ -3,6 +3,7 @@
 
 import { homedir, tmpdir } from "node:os"
 import { resolve as resolvePath, sep } from "node:path"
+import { deniedBy } from "./denylist.js"
 
 // Two ideas here:
 //
@@ -147,9 +148,22 @@ export function segments(command) {
       if (command[i + 1] === "|") i++
       continue
     }
-    if (ch === "&" && command[i + 1] === "&") {
+    if (ch === "&") {
+      // `&>` and `>&` are redirections, not separators: `cmd &> log` writes
+      // both streams to a file, and `cmd 2>&1` duplicates a descriptor. Both
+      // keep the `&` as part of the command.
+      if (command[i - 1] === ">" || command[i + 1] === ">") {
+        cur += ch
+        continue
+      }
+      // `&&` runs the next command only if the first one succeeded, and a
+      // single `&` runs it regardless. Both are command boundaries.
+      if (command[i + 1] === "&") {
+        flush()
+        i++
+        continue
+      }
       flush()
-      i++
       continue
     }
     cur += ch
@@ -210,7 +224,20 @@ export function tokenize(segment) {
 }
 
 const ENV_ASSIGN = /^[A-Za-z_][A-Za-z0-9_]*=/
-const GIT_WRAPPERS = new Set(["env", "sudo", "doas", "nohup", "time", "command", "exec", "xargs"])
+// The wrappers that put another command in front of the real one. `npx`
+// runs a package's binary, so `npx npm publish` is `npm publish` with two
+// words in front of it.
+const GIT_WRAPPERS = new Set([
+  "env",
+  "sudo",
+  "doas",
+  "nohup",
+  "time",
+  "command",
+  "exec",
+  "xargs",
+  "npx",
+])
 // Wrappers whose flag consumes the next word, e.g. `sudo -u deploy git push`.
 const WRAPPER_VALUE_FLAGS = new Set(["-u", "--user", "-g", "--group", "-I", "-P", "-n", "-a", "-d"])
 // git options that take a value, so the subcommand is the word after them.
@@ -322,13 +349,32 @@ const MAX_SHELL_DEPTH = 2
 export function shellPayload(segment) {
   const tokens = tokenize(segment)
   if (tokens.length < 2) return null
-  if (tokens[0] === "eval") return tokens.slice(1).join(" ") || null
-  if (!SHELL_BIN.test(tokens[0])) return null
-  const c = tokens.findIndex((t) => /^-[a-zA-Z]*c$/.test(t))
+  // The wrappers come off FIRST. `sudo bash -c "rm -rf /"` hides a whole
+  // command line behind one argument, and the shell doing the hiding is the
+  // second word - so looking only at the first word missed every command
+  // with a wrapper in front of it, which is the shape a wrapper is used for.
+  const i = skipPrefixes(tokens)
+  if (i >= tokens.length) return null
+  if (tokens[i] === "eval") return tokens.slice(i + 1).join(" ") || null
+  if (!SHELL_BIN.test(tokens[i])) return null
+  const c = tokens.findIndex((t, n) => n > i && /^-[a-zA-Z]*c$/.test(t))
   if (c === -1 || c === tokens.length - 1) return null
   return tokens.slice(c + 1).join(" ") || null
 }
 
+/**
+ * Commands the guard deliberately does NOT block.
+ *
+ * `git push` is ask-gated through opencode's permission rules rather than
+ * guard-blocked, so it is the one command the agent reaches for that the
+ * guard has a policy about and lets through. It lives here, beside the rules,
+ * so there is ONE place that says what the guard's policy is - a keyword list
+ * in the telemetry was a second copy of it, and it drifted.
+ *
+ * @type {RegExp[]}
+ */
+export const ASK_GATED = [/^\s*git\s+push\b/]
+
 /** @type {Rule[]} */
 export const BASH_RULES = [
   {
@@ -367,7 +413,18 @@ export const BASH_RULES = [
   {
     name: "history rewrite",
     scope: "segment",
-    test: /^git\s+(reset\s+--hard|clean\s+-[a-zA-Z]*f|rebase\s+.*--force)/i,
+    // The subcommand is resolved rather than read off the front of the text,
+    // because git takes options before it: `git -C /repo reset --hard` is the
+    // same command as `git reset --hard`, and a rule anchored at `^git` is
+    // defeated by every one of them. `gitSubcommand` already knows which
+    // options take a value and which ones are global.
+    check: (text) => {
+      const sub = gitSubcommand(text)
+      if (sub === "reset") return /(^|\s)--hard(\s|$)/.test(text)
+      if (sub === "clean") return /(^|\s)-[a-zA-Z]*f/.test(text)
+      if (sub === "rebase") return /(^|\s)--force/.test(text)
+      return false
+    },
     why: "destroys work that only exists locally",
   },
 ]
@@ -407,6 +464,41 @@ function matches(rule, text) {
   return !rule.unless?.test(text)
 }
 
+/**
+ * The shared denylist, checked the way the rules are checked.
+ *
+ * The denylist used to be matched against the RAW command string, which is
+ * what lets `cd /tmp && npm publish` through: the pattern is `npm publish*`
+ * and the command does not start with it. It also let `sudo npm publish` and
+ * `sh -c "npm publish"` through, for the same reason.
+ *
+ * So the denylist is checked per SEGMENT, with the wrappers stripped, and
+ * the payload of a `bash -c` is checked too - exactly the way the rules are
+ * checked. One list, one way of reading it.
+ *
+ * @param {string} command
+ * @param {number} [depth]
+ * @returns {{ pattern: string, segment: string } | null}
+ */
+export function checkDenied(command, depth = 0) {
+  if (!command || !command.trim()) return null
+  const parts = segments(command)
+  const normalized = parts.map((seg) => stripPrefixes(seg))
+  for (let i = 0; i < parts.length; i++) {
+    const pattern = deniedBy(normalized[i])
+    if (pattern) return { pattern, segment: parts[i] }
+  }
+  if (depth < MAX_SHELL_DEPTH) {
+    for (const seg of parts) {
+      const payload = shellPayload(seg)
+      if (!payload) continue
+      const hit = checkDenied(payload, depth + 1)
+      if (hit) return hit
+    }
+  }
+  return null
+}
+
 /**
  * @param {string} command
  * @param {Rule[]} [rules]

package/src/safe.ts

@@ -0,0 +1,27 @@
+// Stringify without throwing.
+//
+// An event object comes from opencode, and opencode passes the object it
+// holds - which can hold anything, including a reference back to itself. A
+// plain `JSON.stringify` on a cyclic object throws, and a hook that throws
+// takes the event down with it.
+//
+// This is the one place the kit stringifies something it did not build, so it
+// is the one place that has to be careful.
+
+/**
+ * Stringify a value, never throwing.
+ *
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function safeStringify(value: unknown): string {
+  try {
+    return JSON.stringify(value) ?? String(value)
+  } catch {
+    try {
+      return String(value)
+    } catch {
+      return "[unstringifiable]"
+    }
+  }
+}

package/src/sqlite.js

@@ -0,0 +1,144 @@
+// The one way this kit talks to the opencode database.
+//
+// It shells out to the `sqlite3` CLI rather than using a node driver, so
+// there is no native module to build and no runtime dependency to install -
+// the tool is either on the machine or it is not.
+//
+// When it is not, the failure used to be a raw `spawnSync sqlite3 ENOENT`
+// stack trace. A missing tool is a thing a person can fix, and the error
+// said what to install.
+//
+// Plain JS with JSDoc types, like the rest of src/: the CLI and the eval
+// scripts have to run under plain node.
+
+import { execFileSync } from "node:child_process"
+
+/**
+ * Whether the sqlite3 CLI is available.
+ * @returns {boolean}
+ */
+/** @type {boolean | null} */
+let sqliteCli = null
+export function hasSqlite() {
+  // Memoised. The measurement scripts issue one query per message, and a
+  // process spawn per query is thousands of throwaway processes.
+  if (sqliteCli !== null) return sqliteCli
+  try {
+    execFileSync("sqlite3", ["-version"], { stdio: "ignore" })
+    sqliteCli = true
+  } catch {
+    sqliteCli = false
+  }
+  return sqliteCli
+}
+
+/**
+ * Whether python3 with its built-in sqlite3 module is available.
+ *
+ * The fallback exists because python3 is on more machines than the sqlite3
+ * CLI is, and a measurement harness that cannot run is a measurement nobody
+ * takes.
+ *
+ * @returns {boolean}
+ */
+/** @type {boolean | null} */
+let pythonSqlite = null
+export function hasPythonSqlite() {
+  if (pythonSqlite !== null) return pythonSqlite
+  try {
+    execFileSync("python3", ["-c", "import sqlite3"], { stdio: "ignore" })
+    pythonSqlite = true
+  } catch {
+    pythonSqlite = false
+  }
+  return pythonSqlite
+}
+
+/**
+ * Whether this machine can read a sqlite database at all.
+ * @returns {boolean}
+ */
+export function canQuerySqlite() {
+  return hasSqlite() || hasPythonSqlite()
+}
+
+/**
+ * Explain that there is no way to read a sqlite database here, and what to
+ * install.
+ * @returns {string}
+ */
+export function sqliteMissingMessage() {
+  return [
+    "this script needs a way to read a sqlite database, and this machine has neither.",
+    "",
+    "  the sqlite3 command-line tool:  brew install sqlite3 / apt install sqlite3",
+    "  or python3 with its built-in sqlite3 module:  apt install python3",
+    "",
+    "It is the sqlite3 CLI and not the sqlite3 library: the python3 and node",
+    "modules of that name do not put a `sqlite3` command on your PATH.",
+  ].join("\n")
+}
+
+/**
+ * A database path as a URI.
+ *
+ * A path with a `?` or a `#` in it is parsed as a URI query or fragment
+ * rather than as a filename, so it is percent-encoded.
+ *
+ * @param {string} db
+ * @returns {string}
+ */
+function encodePath(db) {
+  return db.split("/").map(encodeURIComponent).join("/")
+}
+
+/**
+ * Run a query and return the rows.
+ *
+ * The sqlite3 CLI is the fast path. When it is not installed, python3's
+ * built-in sqlite3 module does the same job - and python3 is on more machines
+ * than the CLI is, so the measurement harness runs where it otherwise could
+ * not.
+ *
+ * @param {string} db the database path
+ * @param {string} sql
+ * @returns {any[]}
+ */
+export function query(db, sql) {
+  if (hasSqlite()) {
+    // The path is percent-encoded, because it goes into a URI. A `?` in a
+    // path is a query separator, so a database called "we?ird.db" was read
+    // as a database called "we" with the query "ird.db?mode=ro" - and the
+    // error was "no such table" from a database that had the table.
+    const out = execFileSync("sqlite3", ["-json", `file:${encodePath(db)}?mode=ro`, sql], {
+      encoding: "utf8",
+      maxBuffer: 256 * 1024 * 1024,
+    }).trim()
+    return out ? JSON.parse(out) : []
+  }
+  return queryWithPython(db, sql)
+}
+
+/**
+ * The same query, through python3's sqlite3 module.
+ *
+ * @param {string} db the database path
+ * @param {string} sql
+ * @returns {any[]}
+ */
+function queryWithPython(db, sql) {
+  // The cursor is used once. The description came from a SECOND execute of
+  // the same statement, which re-ran the whole scan.
+  const script = [
+    "import json, sqlite3, sys",
+    "con = sqlite3.connect('file:' + sys.argv[1] + '?mode=ro', uri=True)",
+    "cur = con.execute(sys.argv[2])",
+    "cols = [d[0] for d in cur.description]",
+    "print(json.dumps([dict(zip(cols, r)) for r in cur.fetchall()]))",
+  ].join("\n")
+  const out = execFileSync("python3", ["-c", script, encodePath(db), sql], {
+    encoding: "utf8",
+    maxBuffer: 256 * 1024 * 1024,
+  }).trim()
+  return out ? JSON.parse(out) : []
+}