opencode-harness-kit 0.4.2 → 0.4.4

package/src/guard.ts

@@ -6,10 +6,82 @@
 // Fail-closed: if the guard cannot decide, it blocks. A guard that quietly
 // passes when broken is worse than none, because the user stops watching it.
 
-import type { Plugin } from "@opencode-ai/plugin"
-import { checkBash, checkWrite } from "./rules.js"
+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"
 
-const MARKER = "[opencode-harness-kit] blocked"
+import { write } from "./telemetry-store.js"
+import { projectRoot } from "./project.js"
+
+export const MARKER = "[opencode-harness-kit] blocked"
+
+/**
+ * The tools that write to a file, and where the path to write lives in each.
+ *
+ * OpenCode 1.19 has `write` and `edit` (both take `filePath`) and
+ * `apply_patch` (which takes a whole patch as `patchText`). On a GPT-5-class
+ * model `write` and `edit` are REMOVED and replaced by `apply_patch`, so a
+ * guard that only knew about `write` and `edit` enforced nothing at all on
+ * those models - the tool the agent actually had was not one it looked at.
+ *
+ * `patch` and `changes[].filePath` are not OpenCode 1.19 shapes. They are
+ * kept because a third-party plugin may register such a tool, and a tool the
+ * guard cannot read is a tool the guard cannot protect.
+ */
+const WRITE_TOOLS = new Set(["write", "edit", "apply_patch", "patch"])
+
+/**
+ * The files a patch touches.
+ *
+ * `apply_patch` sends a patch, not a path, so the paths have to be read out
+ * of it. Two formats are in use: opencode's own `*** Update File: path`
+ * markers, and a plain unified diff with `+++ b/path` headers.
+ *
+ * @param {string} text
+ * @returns {string[]}
+ */
+export function pathsInPatch(text: string): string[] {
+  const out: string[] = []
+  const push = (p: string) => {
+    const v = p.trim()
+    if (!v) return
+    if (v === "/dev/null") return
+    if (!out.includes(v)) out.push(v)
+  }
+  for (const m of text.matchAll(/^\*\*\*\s+(?:Add|Update|Delete)\s+File:\s*(.+)$/gm)) {
+    push(m[1])
+  }
+  for (const m of text.matchAll(/^\+\+\+\s+(?:b\/)?(.+)$/gm)) {
+    push(m[1])
+  }
+  return out
+}
+
+/**
+ * The files a write tool is about to touch.
+ *
+ * @param {string} tool
+ * @param {any} args
+ * @returns {string[]} empty when the arguments name no file
+ */
+export function writeTargets(tool: string, args: any): string[] {
+  if (!args || typeof args !== "object") return []
+  if (tool === "apply_patch") {
+    return pathsInPatch(String(args.patchText ?? args.patch ?? ""))
+  }
+  const out: string[] = []
+  const one = (v: any) => {
+    if (typeof v === "string" && v) out.push(v)
+  }
+  one(args.filePath)
+  one(args.path)
+  for (const c of Array.isArray(args.changes) ? args.changes : []) {
+    one(c?.filePath)
+    one(c?.path)
+  }
+  return out
+}
 
 function deny(why: string, detail: string): never {
   // Throwing is the only way to stop a tool call from a hook.
@@ -19,33 +91,113 @@ function deny(why: string, detail: string): never {
       `safe, run it yourself in a terminal.`,
   )
 }
-
 function truncate(s: string, n = 200): string {
   const one = s.replace(/\s+/g, " ").trim()
   return one.length > n ? `${one.slice(0, n)}...` : one
 }
 
-export const GuardPlugin: Plugin = async ({ worktree }) => {
+export const GuardPlugin: 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 scope check was against
+  // "/" - which contains every path - and the denial log went nowhere.
+  const project = projectRoot(directory, worktree)
+  // Where a denial is recorded.
+  //
+  // It has to be recorded HERE. A denial throws in `tool.execute.before`, and
+  // opencode calls `tool.execute.after` only after the tool has run - so a
+  // blocked command produces no `after` event at all, and the telemetry
+  // plugin never sees it. The file's own header promised to record "tool
+  // denials (to see the guard being useful rather than annoying)", and it
+  // could not.
+  const telemetryDir = join(project, ".space")
+
+  /** Record the denial, then stop the call. */
+  const refuse = (tool: string, rule: string, why: string, detail: string): never => {
+    write(telemetryDir, { kind: "guard", tool, rule })
+    deny(why, detail)
+  }
+
   return {
-    "tool.execute.before": async (input, output) => {
+    "tool.execute.before": async (input: any, output: any) => {
       try {
         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
+          // writing outside the project, which is the one thing the scope
+          // rule exists to stop - and the guard used to ignore the argument
+          // entirely, so `workdir: "/etc"` was a way around it.
+          const raw = output.args?.workdir
+          if (typeof raw === "string" && raw.trim()) {
+            const target = raw.startsWith("~")
+              ? join(homedir(), raw.slice(1))
+              : resolve(project, raw)
+            if (!insideRoot(target, project) && !insideRoot(target, tmpdir())) {
+              refuse(
+                input.tool,
+                "command outside the project",
+                "command runs outside the project",
+                `the working directory is ${truncate(target)}, and this project's files are the ones you were asked to change`,
+              )
+            }
+          }
           const hit = checkBash(String(output.args?.command ?? ""))
-          if (hit) deny(hit.name, `${hit.why}\n  command: ${truncate(hit.segment)}`)
+          if (hit) {
+            refuse(input.tool, hit.name, hit.name, `${hit.why}\n  command: ${truncate(hit.segment)}`)
+          }
+          // The shared denylist, enforced in code.
+          //
+          // The config denies these through opencode's permission map, and the
+          // guard used to enforce a DIFFERENT set - it blocked neither
+          // `gh pr create` nor `npm publish`. The config's own comment said
+          // the two were the same, and they were not. One list, two
+          // enforcers: the permission map can be overridden by a plugin or
+          // lost to a hand-edit, and the guard does not care.
+          const command = String(output.args?.command ?? "")
+          // Checked per segment, with the wrappers stripped and the payload of
+          // a `bash -c` followed: `cd /tmp && npm publish`, `sudo npm
+          // publish` and `sh -c "npm publish"` are all the same command, and
+          // matching the raw string let every one of them through.
+          const denied = checkDenied(command)
+          if (denied) {
+            refuse(
+              input.tool,
+              `denied command (${denied.pattern})`,
+              "denied command",
+              `this command matches \`${denied.pattern}\`, which the kit never allows.\n  command: ${truncate(denied.segment)}`,
+            )
+          }
           return
         }
 
-        if (input.tool === "write" || input.tool === "edit" || input.tool === "patch") {
-          const target =
-            String(output.args?.filePath ?? output.args?.path ?? "") ||
-            String(output.args?.changes?.[0]?.filePath ?? "")
-          const hit = checkWrite(target, undefined, worktree)
-          if (hit) deny(hit.name, `${hit.why}\n  file: ${truncate(hit.segment)}`)
+        if (WRITE_TOOLS.has(input.tool)) {
+          const targets = writeTargets(input.tool, output.args)
+          if (!targets.length) {
+            // A write tool whose arguments name no file. Failing open here
+            // would mean a tool this guard does not understand writes
+            // wherever it likes.
+            refuse(
+              input.tool,
+              "unknown write target",
+              "cannot tell what this write touches",
+              `the ${input.tool} tool's arguments name no file, so the scope of the write is unknown`,
+            )
+          }
+          for (const target of targets) {
+            const hit = checkWrite(target, undefined, project)
+            if (hit) {
+              refuse(input.tool, hit.name, hit.name, `${hit.why}\n  file: ${truncate(hit.segment)}`)
+            }
+          }
         }
       } catch (err) {
         // Our own denial must not be re-wrapped into a confusing failure.
         if (err instanceof Error && err.message.startsWith(MARKER)) throw err
         // Anything unexpected fails closed. An undecidable guard is not a pass.
+        write(telemetryDir, {
+          kind: "guard",
+          tool: input.tool,
+          rule: "guard failed closed",
+        })
         throw new Error(
           `${MARKER} (guard failed closed): ${
             err instanceof Error ? err.message : String(err)

package/src/health.js

@@ -0,0 +1,80 @@
+// The spent-route file.
+//
+// A route is "spent" when the provider says the free tier is exhausted. The
+// router records that, and the effort hook reads it, so the two have to agree
+// on WHERE the file is - and that is the project root, not the worktree.
+//
+// The worktree is opencode's git root, and for a directory that is not a git
+// repository it is the FILESYSTEM ROOT. The router wrote the file under the
+// worktree while the effort hook read it from the worktree, and in a
+// non-git project the two were not even looking at the same place.
+//
+// Plain JS with JSDoc types, like the rest of src/: the CLI and the tests run
+// under plain node, and the plugin loads .ts.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+
+/**
+ * @typedef {object} Health
+ * @property {Record<string, { at: string, reason: string }>} unhealthy
+ * @property {string} [active]
+ */
+
+/**
+ * @param {string} dir the project root
+ * @returns {string}
+ */
+export function healthPath(dir) {
+  return join(dir, ".space", "health.json")
+}
+
+/**
+ * @param {string} dir the project root
+ * @returns {Health}
+ */
+export function readHealth(dir) {
+  try {
+    return JSON.parse(readFileSync(healthPath(dir), "utf8"))
+  } catch {
+    return { unhealthy: {} }
+  }
+}
+
+/**
+ * @param {string} dir the project root
+ * @param {Health} health
+ */
+export function writeHealth(dir, health) {
+  try {
+    if (!existsSync(join(dir, ".space"))) mkdirSync(join(dir, ".space"), { recursive: true })
+    writeFileSync(healthPath(dir), JSON.stringify(health, null, 2))
+  } catch {
+    // Best effort. A health file that cannot be written means no failover,
+    // and failing to write it must not break the session.
+  }
+}
+
+/**
+ * The models a previous session found spent.
+ *
+ * Exported so the effort hook resolves a lane's variant against the same set
+ * of spent routes the router used. A lane that failed over to a model with
+ * fewer effort levels must lose its variant, or the config asks for an effort
+ * the new model does not publish.
+ *
+ * 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.
+ *
+ * @param {string} dir the project root
+ * @returns {Set<string>}
+ */
+export function unhealthyModels(dir) {
+  const health = readHealth(dir)
+  const out = new Set()
+  for (const key of Object.keys(health.unhealthy ?? {})) {
+    out.add(key.includes("/") ? key.slice(key.indexOf("/") + 1) : key)
+  }
+  return out
+}

package/src/index.ts

@@ -12,13 +12,15 @@
 
 import { mkdirSync, writeFileSync } from "node:fs"
 import { join } from "node:path"
-import type { Plugin } from "@opencode-ai/plugin"
+import type { Plugin } from "./plugin.js"
 import { GuardPlugin } from "./guard.js"
 import { PrunePlugin } from "./prune.js"
-import { RouterPlugin, unhealthyModels } from "./router.js"
+import { RouterPlugin } from "./router.js"
 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`. */
@@ -62,6 +64,10 @@ export const HarnessPlugin: Plugin = async (ctx, options?: HarnessOptions) => {
     // the hook. The config file does, so read the id from there.
     const id = opts.profile ?? config?.harness?.profile ?? profileIdFromConfig()
     if (!id) return
+    // The PROJECT root, not the worktree: the worktree is the filesystem
+    // root in a project that is not a git repository, so the spent-route
+    // 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
@@ -74,12 +80,17 @@ export const HarnessPlugin: Plugin = async (ctx, options?: HarnessOptions) => {
         typeof config?.harness?.sessionModel === "string"
           ? config.harness.sessionModel
           : undefined
-      applyEffort(config, planEffort(id, { unhealthy: unhealthyModels(ctx.worktree) }), {
+      applyEffort(config, planEffort(id, { unhealthy: unhealthyModels(project) }), {
         sessionModel,
       })
       // Record it where the prune hook looks, so pruning picks up this
       // profile's thresholds without access to the resolved config.
-      const dir = join(ctx.worktree, ".space")
+      //
+      // 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.
+      const dir = join(project, ".space")
       mkdirSync(dir, { recursive: true })
       writeFileSync(join(dir, "active"), `${id}\n`)
     } catch {

package/src/lane-usage.js

@@ -25,25 +25,50 @@ import { dirname, join, resolve } from "node:path"
  * @typedef {object} LaneUsage
  * @property {number} requests  distinct assistant messages that used the lane
  * @property {number[]} ms       durations of the requests that completed
+ * @property {number[]} ctx      the context each request carried, in tokens
+ * @property {number[]} reasoning the reasoning each request spent, in tokens
  * @property {Set<string>} models the models the lane was seen on
  */
 
 /**
- * The telemetry file for the project containing `startDir`.
+ * The telemetry files for the project containing `startDir`.
+ *
+ * ALL of them, oldest first. The plugin rotates the file when it passes 4 MB
+ * and renames the old one to `telemetry.jsonl.1` - and the reader used to
+ * look at `telemetry.jsonl` alone, so a rotation silently threw away the
+ * history and every lane reported "never used". The number that decides
+ * whether the fleet stays at ten lanes was disappearing on a schedule.
  *
  * @param {string} startDir
- * @returns {string | null} the path, or null when the project has no telemetry
+ * @returns {string[]} the paths, or an empty array when the project has none
  */
-export function findTelemetryFile(startDir) {
+export function findTelemetryFiles(startDir) {
   let dir = resolve(startDir)
-  for (let i = 0; i < 6; i++) {
-    const file = join(dir, ".space", "telemetry.jsonl")
-    if (existsSync(file)) return file
+  for (let i = 0; i < 12; i++) {
+    const space = join(dir, ".space")
+    const files = []
+    for (const suffix of [".2", ".1", ""]) {
+      const f = join(space, `telemetry.jsonl${suffix}`)
+      if (existsSync(f)) files.push(f)
+    }
+    // Oldest first: `.2` was rotated twice, `.1` once, and the plain file is
+    // the newest.
+    if (files.length) return files
     const parent = dirname(dir)
     if (parent === dir) break
     dir = parent
   }
-  return null
+  return []
+}
+
+/**
+ * The telemetry file for the project containing `startDir`.
+ *
+ * @param {string} startDir
+ * @returns {string | null} the path, or null when the project has no telemetry
+ */
+export function findTelemetryFile(startDir) {
+  return findTelemetryFiles(startDir)[0] ?? null
 }
 
 /**
@@ -63,24 +88,34 @@ export function findTelemetryFile(startDir) {
  * three, so counting them would put a known-wrong figure next a known-right
  * one.
  *
- * @param {string | null} file
- * @returns {{ lanes: Record<string, LaneUsage>, records: number, ignored: number }}
+ * @param {string | string[] | null} file one file, or several oldest first
+ * @returns {{ lanes: Record<string, LaneUsage>, records: number, requests: number, ignored: number }}
  */
 export function readLaneUsage(file) {
   /** @type {Record<string, LaneUsage>} */
   const lanes = {}
-  /** @type {Map<string, { lane: string, ms?: number, model?: string }>} */
+  /** @type {Map<string, { lane: string, ms?: number, model?: string, ctx?: number, reasoning?: number }>} */
   const byId = new Map()
   let records = 0
   let ignored = 0
 
-  if (!file || !existsSync(file)) return { lanes, records, ignored }
+  const files = Array.isArray(file) ? file : file ? [file] : []
+  const readable = files.filter((f) => existsSync(f))
+  if (!readable.length) return { lanes, records, requests: 0, ignored }
 
   let text = ""
-  try {
-    text = readFileSync(file, "utf8")
-  } catch {
-    return { lanes, records, ignored }
+  for (const f of readable) {
+    try {
+      const chunk = readFileSync(f, "utf8")
+      // A file that does not end in a newline would otherwise be glued to
+      // the next one, and the two records that meet in the middle would
+      // parse as neither.
+      if (text && !text.endsWith("\n")) text += "\n"
+      text += chunk
+    } catch {
+      // A file we cannot read is a file we cannot count. The rest of the
+      // history is still worth reading.
+    }
   }
 
   for (const line of text.split("\n")) {
@@ -102,7 +137,13 @@ export function readLaneUsage(file) {
     if (rec?.kind !== "lane") continue
     const lane = rec.agent
     const id = rec.id
-    if (typeof lane !== "string" || !lane) continue
+    if (typeof lane !== "string" || !lane) {
+      // A record with no lane cannot be attributed to one, so it is not
+      // counted - and it is counted as ignored, so a malformed file is
+      // visible in the tally rather than silently shrinking the numbers.
+      ignored++
+      continue
+    }
     if (typeof id !== "string" || !id) {
       ignored++
       continue
@@ -117,18 +158,31 @@ export function readLaneUsage(file) {
       lane,
       ms: typeof rec.ms === "number" ? rec.ms : prev?.ms,
       model: typeof rec.model === "string" ? rec.model : prev?.model,
+      ctx: typeof rec.ctx === "number" ? rec.ctx : prev?.ctx,
+      reasoning: typeof rec.reasoning === "number" ? rec.reasoning : prev?.reasoning,
     })
   }
 
   for (const rec of byId.values()) {
     const usage =
-      lanes[rec.lane] ?? (lanes[rec.lane] = { requests: 0, ms: [], models: new Set() })
+      lanes[rec.lane] ?? (lanes[rec.lane] = {
+      requests: 0,
+      ms: [],
+      ctx: [],
+      reasoning: [],
+      models: new Set(),
+    })
     usage.requests++
     if (typeof rec.ms === "number") usage.ms.push(rec.ms)
+    if (typeof rec.ctx === "number") usage.ctx.push(rec.ctx)
+    if (typeof rec.reasoning === "number") usage.reasoning.push(rec.reasoning)
     if (rec.model) usage.models.add(rec.model)
   }
 
-  return { lanes, records, ignored }
+  // `records` is the raw count and `requests` is the count that means
+  // something: one record is written when a message opens and again
+  // when it closes, so the raw count is twice the number of requests.
+  return { lanes, records, requests: byId.size, ignored }
 }
 
 /**

package/src/plugin-type-check.ts

@@ -0,0 +1,38 @@
+// The plugin type, checked against the real one.
+//
+// `src/plugin.ts` declares the shape structurally, so the published
+// declarations do not make a consumer install `@opencode-ai/plugin` - a
+// package that pulls in `effect`, `zod` and `@opencode-ai/sdk`.
+//
+// A structural type that drifts from the real one is a silent breakage: the
+// kit would install, and opencode would not call the hooks. So the real
+// type is checked HERE, in the repository, where the package is installed.
+// A drift is a failed build.
+//
+// This file is not in the exports map, so a consumer never loads it, and
+// the declarations it produces are never reached from `dist/index.d.ts`.
+
+import type { Plugin as OpencodePlugin } from "@opencode-ai/plugin"
+
+import type { Plugin } from "./plugin.js"
+
+import { GuardPlugin } from "./guard.js"
+import { PrunePlugin } from "./prune.js"
+import { RouterPlugin } from "./router.js"
+import { TelemetryPlugin } from "./telemetry.js"
+import { HarnessPlugin } from "./index.js"
+
+// The kit's own plugins have to be opencode plugins. If opencode's type
+// changes shape, this stops compiling, and the fix is a real one rather than
+// a guess.
+const _guard: OpencodePlugin = GuardPlugin
+const _prune: OpencodePlugin = PrunePlugin
+const _router: OpencodePlugin = RouterPlugin
+const _telemetry: OpencodePlugin = TelemetryPlugin
+const _harness: OpencodePlugin = HarnessPlugin
+
+// And the other way round: the local type has to be wide enough to hold
+// them, so a plugin written against the local type is still a valid one.
+const _local: Plugin = _harness
+
+export type { OpencodePlugin }

package/src/plugin.ts

@@ -0,0 +1,39 @@
+// The plugin type, without the plugin package.
+//
+// The kit's plugin functions are typed with opencode's own `Plugin` type,
+// and that type lives in `@opencode-ai/plugin` - a package that depends on
+// `effect`, `zod` and `@opencode-ai/sdk`, and has three peer dependencies of
+// its own.
+//
+// A consumer that installs the kit to compile a config should not have to
+// install all of that. And they do not have to: the published declarations
+// imported the plugin's type, so `npm install opencode-harness-kit` gave a
+// consumer whose type-check failed with "Cannot find module
+// '@opencode-ai/plugin'". The optional peer dependency did not fix it -
+// npm never installs an optional peer on its own.
+//
+// So the type is declared here, structurally: what opencode actually calls.
+//
+// The real type is still checked, in `plugin-type-check.ts`, against the
+// real package - in CI, where the package is installed. A drift between the
+// two is a failed build, not a broken consumer.
+
+/**
+ * A plugin: a function opencode calls once, which returns the hooks it
+ * wants registered.
+ *
+ * The context and the options are opencode's, and the kit does not name
+ * their fields - it uses what it needs and tolerates the rest.
+ */
+export type Plugin = (
+  ctx: any,
+  options?: any,
+) => Promise<Record<string, any>>
+
+/**
+ * The hooks a plugin returns.
+ *
+ * opencode calls each one by name; the kit registers `config`, `tool.execute.before`
+ * and `chat.message`. A hook that is not in this list is not a hook.
+ */
+export type Hooks = Record<string, (...args: any[]) => any>