opencode-harness-kit 0.4.3 → 0.4.4

package/src/tasks.js

@@ -6,7 +6,7 @@
 // the goal, the constraints, the decisions, any prose a human added -- survives
 // a rewrite untouched.
 
-export const TASK_FIELDS = ["files", "change", "verify", "status"]
+export const TASK_FIELDS = ["files", "change", "verify", "status", "output"]
 
 const SECTIONS = ["Constraints", "Decisions", "Risks", "Tasks"]
 
@@ -17,12 +17,14 @@ const fieldRe = new RegExp(`^\\s+-\\s+(${TASK_FIELDS.join("|")})\\s*:\\s*(.*)$`)
 /**
  * @typedef {object} Task
  * @property {number} index      position in the file, zero based
+ * @property {number} ordinal    position among the tasks with the same title
  * @property {boolean} checked   the checkbox was ticked
  * @property {string} title      the task on one line
  * @property {string} files      which files it is allowed to touch
  * @property {string} change     what it is supposed to change
  * @property {string} verify     the command that proves it
  * @property {string} status     pending | done | blocked
+ * @property {string} output     the output that command actually produced
  * @property {number} start      first line of the task block
  * @property {number} end        last line of the task block
  * @property {string} [key]      indexed by field name when a block is written
@@ -74,21 +76,31 @@ export function parseTasks(text) {
 
   /** @type {Task[]} */
   const tasks = []
+  // How many tasks with the same title have been seen. A driver that has to
+  // find its task again after the file changed underneath it needs a way to
+  // tell two identically-named tasks apart.
+  const titleCounts = new Map()
   for (let i = 0; i < lines.length; i++) {
     const m = lines[i].match(taskRe)
     if (!m) continue
     // A checkbox outside the Tasks section is prose, not a task.
     if (!inSection(lines, i, "Tasks")) continue
 
+    const title = m[2].trim()
+    const ordinal = titleCounts.get(title) ?? 0
+    titleCounts.set(title, ordinal + 1)
+
     /** @type {Record<string, any> & Task} */
     const t = {
       index: tasks.length,
+      ordinal,
       checked: m[1].toLowerCase() === "x",
-      title: m[2].trim(),
+      title,
       files: "",
       change: "",
       verify: "",
       status: "",
+      output: "",
       start: i,
       end: i,
     }
@@ -104,8 +116,17 @@ export function parseTasks(text) {
         continue
       }
       // A wrapped value continues the field above it, indented deeper.
+      //
+      // Under `verify` it cannot be the command. A continuation of the
+      // verify line is the output of that command, and folding it back into
+      // the field made the driver hand "npm test exit 0 in 3s" to a shell.
+      // It is collected as output instead, where it cannot be executed.
       if (last && lines[j].trim() && /^\s{4,}\S/.test(lines[j])) {
-        t[last] = `${t[last]} ${lines[j].trim()}`.trim()
+        if (last === "verify") {
+          t.output = t.output ? `${t.output} ${lines[j].trim()}` : lines[j].trim()
+        } else {
+          t[last] = `${t[last]} ${lines[j].trim()}`.trim()
+        }
         continue
       }
       if (!lines[j].trim()) continue
@@ -165,11 +186,14 @@ export const isDone = (t) => t.checked || t.status === "done"
 export const isBlocked = (t) => t.status === "blocked"
 
 /**
- * Record the outcome of a task: flip the checkbox, set the status, and paste the
- * verify output that was actually observed.
+ * Record the outcome of a task: flip the checkbox, set the status, and record
+ * the verify output that was actually observed.
  *
- * The verify text is written under the `verify:` line rather than replacing it,
- * because the contract asks for the command and the real output together.
+ * The output goes into its own `output:` field rather than under the `verify:`
+ * line. It used to be written as continuation lines under `verify:`, and the
+ * parser folded a continuation back into the field above it - so the command
+ * and its output became one string, and the driver handed that string to a
+ * shell. A separate field cannot be mistaken for a command.
  *
  * @param {string} text
  * @param {Task} task
@@ -179,9 +203,11 @@ export const isBlocked = (t) => t.status === "blocked"
 export function markTask(text, task, { status, verifyOutput }) {
   const lines = String(text).split("\n")
   const boxLine = lines[task.start] ?? ""
+  // The indentation is part of the document: a task nested under a heading
+  // keeps its nesting when it is marked.
   lines[task.start] = boxLine.replace(
-    /^\s*-\s*\[[ xX]\]/,
-    status === "done" ? "- [x]" : "- [ ]",
+    /^(\s*)-\s*\[[ xX]\]/,
+    (_match, indent) => `${indent}- ${status === "done" ? "[x]" : "[ ]"}`,
   )
 
   let statusLine = -1
@@ -198,28 +224,76 @@ export function markTask(text, task, { status, verifyOutput }) {
   )
 
   if (verifyOutput) {
-    let verifyLine = -1
-    for (let i = task.start; i <= task.end + 1 && i < lines.length; i++) {
-      const f = lines[i]?.match(fieldRe)
-      if (f && f[1] === "verify") {
-        verifyLine = i
-        break
-      }
-    }
-    const verifySource = verifyLine >= 0 ? lines[verifyLine] : undefined
-    if (verifySource) {
-      const indent = (verifySource.match(/^\s*/) ?? [""])[0] + "  "
-      const quoted = String(verifyOutput)
-        .trimEnd()
-        .split("\n")
-        .map((l) => `${indent}${l}`)
-      lines.splice(verifyLine + 1, 0, ...quoted)
-    }
+    // A task that is marked twice keeps one output block, not two.
+    const previous = outputBlock(lines, task)
+    if (previous) lines.splice(previous.start, previous.end - previous.start + 1)
+
+    const verifyLine = fieldLine(lines, task, "verify")
+    const anchor = verifyLine >= 0 ? verifyLine : lastFieldLine(lines, task)
+    const source = lines[anchor] ?? lines[task.start] ?? ""
+    // The field line sits at the same level as the field it belongs to; only
+    // the continuation lines under it are indented deeper.
+    const fieldIndent = (source.match(/^\s*/) ?? [""])[0]
+    const contIndent = `${fieldIndent}  `
+    const quoted = String(verifyOutput)
+      .trimEnd()
+      .split("\n")
+      .map((l) => `${contIndent}${l}`)
+    // The first line rides on the field, the rest are continuations of it.
+    const block = [`${fieldIndent}- output: ${quoted[0].trim()}`, ...quoted.slice(1)]
+    lines.splice(anchor + 1, 0, ...block)
   }
 
   return lines.join("\n")
 }
 
+/**
+ * The line a named field sits on, or -1.
+ * @param {string[]} lines
+ * @param {Task} task
+ * @param {string} name
+ * @returns {number}
+ */
+function fieldLine(lines, task, name) {
+  for (let i = task.start; i <= task.end + 1 && i < lines.length; i++) {
+    const f = lines[i]?.match(fieldRe)
+    if (f && f[1] === name) return i
+  }
+  return -1
+}
+
+/**
+ * The last field line of a task, or the task's own line when it has none.
+ * @param {string[]} lines
+ * @param {Task} task
+ * @returns {number}
+ */
+function lastFieldLine(lines, task) {
+  let last = task.start
+  for (let i = task.start; i <= task.end + 1 && i < lines.length; i++) {
+    if (fieldRe.test(lines[i] ?? "")) last = i
+  }
+  return last
+}
+
+/**
+ * The lines a task's `output:` field occupies, or null when it has none.
+ * @param {string[]} lines
+ * @param {Task} task
+ * @returns {{ start: number, end: number } | null}
+ */
+function outputBlock(lines, task) {
+  const start = fieldLine(lines, task, "output")
+  if (start < 0) return null
+  let end = start
+  for (let i = start + 1; i <= task.end + 1 && i < lines.length; i++) {
+    if (fieldRe.test(lines[i] ?? "")) break
+    if (lines[i].trim() && !/^\s{4,}\S/.test(lines[i])) break
+    end = i
+  }
+  return { start, end }
+}
+
 /**
  * One task rendered as the prompt handed to the agent that will do it.
  *
@@ -237,12 +311,21 @@ export function taskPrompt(task) {
 /**
  * The summary the driver prints when it stops, whatever stopped it.
  *
+ * Every task is counted exactly once. A task that is ticked and also marked
+ * blocked is a contradiction a human can leave in the file, and counting it
+ * in both buckets made the three counters add up to more than the file holds.
+ *
  * @param {TaskFile} parsed
  * @returns {{ done: number, blocked: number, pending: number, total: number }}
  */
 export function summarize(parsed) {
-  const done = parsed.tasks.filter(isDone).length
-  const blocked = parsed.tasks.filter(isBlocked).length
-  const pending = parsed.tasks.filter((t) => !isDone(t) && !isBlocked(t)).length
+  let done = 0
+  let blocked = 0
+  let pending = 0
+  for (const t of parsed.tasks) {
+    if (isDone(t)) done++
+    else if (isBlocked(t)) blocked++
+    else pending++
+  }
   return { done, blocked, pending, total: parsed.tasks.length }
 }

package/src/telemetry-store.ts

@@ -0,0 +1,62 @@
+// The telemetry file, and the one thing that writes to it.
+//
+// It lives in its own module because TWO plugins write to it: the telemetry
+// plugin, and the guard.
+//
+// The guard has to write to it because a denial never reaches
+// `tool.execute.after`. The guard denies by throwing 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. The record of a denial
+// has to be written where the denial happens, or not at all.
+//
+// The file is a JSONL in the project, gitignored, and never a network call.
+
+import { appendFileSync, existsSync, mkdirSync, statSync, renameSync } from "node:fs"
+import { join } from "node:path"
+
+/** Rotate above this, so a long-running project cannot fill its disk. */
+export const MAX_BYTES = 4 * 1024 * 1024
+
+export function logPath(dir: string): string {
+  return join(dir, "telemetry.jsonl")
+}
+
+/** The telemetry file and its rotated predecessors, oldest first. */
+export function logFiles(dir: string): string[] {
+  const out: string[] = []
+  for (const suffix of [".2", ".1", ""]) {
+    const f = `${logPath(dir)}${suffix}`
+    if (existsSync(f)) out.push(f)
+  }
+  // Oldest first: `.2` was rotated twice, `.1` once, and the plain file is
+  // the newest.
+  return out
+}
+
+/** Rotate by size so a long-running project cannot fill its disk. */
+function rotate(file: string) {
+  try {
+    if (existsSync(file) && statSync(file).size > MAX_BYTES) {
+      renameSync(file, `${file}.1`)
+    }
+  } catch {
+    // Best effort.
+  }
+}
+
+/**
+ * Append one record.
+ *
+ * Nothing here is allowed to throw. Telemetry must never be load-bearing: a
+ * full disk or a read-only project must not break a turn.
+ */
+export function write(dir: string, record: Record<string, unknown>) {
+  try {
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
+    const file = logPath(dir)
+    rotate(file)
+    appendFileSync(file, JSON.stringify({ t: new Date().toISOString(), ...record }) + "\n")
+  } catch {
+    // Telemetry must never be load-bearing.
+  }
+}

package/src/telemetry.ts

@@ -31,41 +31,31 @@
 // OpenCode 1.19, its `agent` field is undefined, so it cannot attribute a
 // call to a lane; and a second counter that cannot be correlated with the
 // first would double-count every call.
+//
+// WHAT A DENIAL LOOKS LIKE HERE
+//
+// A denial does NOT reach this plugin. The guard denies by throwing in
+// `tool.execute.before`, and opencode calls `tool.execute.after` only after
+// the tool has run - so a blocked command produces no `after` event. The
+// record of a denial is written by the guard itself, into the same file.
+//
+// The `kind: "guard"` record that used to live here was a false positive: it
+// scraped the word "blocked:" out of the OUTPUT of whatever tool ran, so a
+// `read` of a source file that happened to contain the word produced a record
+// claiming a rule had fired.
 
-import type { Plugin } from "@opencode-ai/plugin"
-import { appendFileSync, mkdirSync, existsSync, statSync, renameSync } from "node:fs"
+import type { Plugin } from "./plugin.js"
 import { join } from "node:path"
-
-const MAX_BYTES = 4 * 1024 * 1024
-
-function logPath(dir: string): string {
-  return join(dir, "telemetry.jsonl")
-}
-
-/** Rotate by size so a long-running project cannot fill its disk. */
-function rotate(file: string) {
-  try {
-    if (existsSync(file) && statSync(file).size > MAX_BYTES) {
-      renameSync(file, `${file}.1`)
-    }
-  } catch {
-    // Best effort.
-  }
-}
-
-function write(dir: string, record: Record<string, unknown>) {
-  try {
-    if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
-    const file = logPath(dir)
-    rotate(file)
-    appendFileSync(file, JSON.stringify({ t: new Date().toISOString(), ...record }) + "\n")
-  } catch {
-    // Telemetry must never be load-bearing.
-  }
-}
-
-export const TelemetryPlugin: Plugin = async ({ worktree }) => {
-  const dir = join(worktree, ".space")
+import { write } from "./telemetry-store.js"
+import { projectRoot } from "./project.js"
+import { safeStringify } from "./safe.js"
+import { ASK_GATED } from "./rules.js"
+
+export const TelemetryPlugin: 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 telemetry was written
+  // somewhere nobody looks, or nowhere at all.
+  const dir = join(projectRoot(directory, worktree), ".space")
   const started = Date.now()
 
   // The message id of every lane record already written, and of every one
@@ -80,7 +70,7 @@ export const TelemetryPlugin: Plugin = async ({ worktree }) => {
   const closed = new Set<string>()
 
   return {
-    event: async ({ event }) => {
+    event: async ({ event }: any) => {
       // Events are provider-specific and opencode may add shapes we have never
       // seen. Anything unrecognised is ignored rather than trusted.
       const type = (event as { type?: unknown } | undefined)?.type
@@ -88,7 +78,11 @@ export const TelemetryPlugin: Plugin = async ({ worktree }) => {
 
       // Provider rate limits are the one signal that changes behaviour, so
       // they get logged even though the event shape is provider-specific.
-      if (/error|rate|limit|quota/i.test(type)) {
+      //
+      // The match is on whole tokens rather than on substrings, so an
+      // opencode event whose name happens to contain a letter of "rate" is
+      // not filed as a provider event and drowns the real ones.
+      if (/(^|[._-])(error|errors|rate|limit|limits|quota)([._-]|$)/i.test(type)) {
         write(dir, { kind: "provider-event", type, detail: truncate(safeStringify(event)) })
         return
       }
@@ -117,15 +111,19 @@ export const TelemetryPlugin: Plugin = async ({ worktree }) => {
       }
     },
 
-    "tool.execute.after": async (input, output) => {
-      const text = typeof output?.output === "string" ? output.output : ""
-      if (text.includes("[opencode-harness-kit] blocked")) {
-        write(dir, { kind: "guard", tool: input.tool, rule: extractRule(text) })
-        return
-      }
+    "tool.execute.after": async (input: any, output: any) => {
+      // A command the guard has a rule about, and that the guard let through.
+      //
+      // The list is `ASK_GATED` in rules.js, not a keyword list here: the
+      // guard's policy about what it does not block lives in one place, and a
+      // second copy of it would drift.
+      //
+      // This is the opposite of a denial, and the name says so. A record
+      // called "guard-attempt" that only ever contained ALLOWED commands was
+      // describing the wrong thing entirely.
       const command = String((input.args as { command?: unknown })?.command ?? "")
-      if (input.tool === "bash" && /git push|rm -rf|chmod 777/.test(command)) {
-        write(dir, { kind: "guard-attempt", tool: input.tool, command: truncate(command) })
+      if (input.tool === "bash" && ASK_GATED.some((p) => p.test(command))) {
+        write(dir, { kind: "guard-allowed", tool: input.tool, command: truncate(command) })
       }
     },
 
@@ -150,6 +148,10 @@ function laneOf(event: unknown): {
   model?: string
   provider?: string
   ms?: number
+  /** The context that request carried, in tokens. */
+  ctx?: number
+  /** The reasoning that request spent, in tokens. */
+  reasoning?: number
 } | null {
   const e = event as { properties?: any } | undefined
   const info = e?.properties?.info ?? e?.properties
@@ -166,31 +168,32 @@ function laneOf(event: unknown): {
   const ms = created !== undefined && completed !== undefined ? completed - created : undefined
 
   if (!id || !agent) return null
+  // The context the request carried, and the reasoning it spent.
+  //
+  // Without these, "which lanes are worth keeping" can only be answered on
+  // FREQUENCY - a lane used once a week looks the same as a lane used once a
+  // week that costs a million tokens. The two answers are different questions
+  // and the second one is the expensive one.
+  const tokens = (info as any).tokens ?? {}
+  const ctx =
+    typeof tokens.input === "number"
+      ? tokens.input + (typeof tokens.cache?.read === "number" ? tokens.cache.read : 0)
+      : undefined
+  const reasoning = typeof tokens.reasoning === "number" ? tokens.reasoning : undefined
+
   return {
     id,
     agent,
     model: typeof modelId === "string" ? modelId : undefined,
     provider: typeof providerId === "string" ? providerId : undefined,
     ms: typeof ms === "number" && ms >= 0 ? ms : undefined,
+    ctx: typeof ctx === "number" ? ctx : undefined,
+    reasoning,
   }
 }
 
-function extractRule(output: string): string {
-  const m = output.match(/blocked:\s*([^\n]+)/)
-  return m ? m[1].trim() : "unknown"
-}
-
 function truncate(s: string, n = 300): string {
   return s.length > n ? `${s.slice(0, n)}...` : s
 }
 
-/** Stringify without throwing on a cycle or a BigInt. */
-function safeStringify(value: unknown): string {
-  try {
-    return JSON.stringify(value) ?? String(value)
-  } catch {
-    return String(value)
-  }
-}
-
 export default TelemetryPlugin

package/src/trust.js

@@ -62,6 +62,37 @@ export function repoOf(repository) {
   return `${m[1]}/${m[2]}`
 }
 
+/**
+ * Open a URL in the user's browser.
+ *
+ * `xdg-open` is the Linux opener. macOS uses `open` and Windows uses
+ * `rundll32`, so on two of the three platforms this kit claims to support
+ * the browser simply never opened - and the failure was swallowed, so the
+ * message afterwards still said the page was open.
+ *
+ * @param {string} url
+ * @returns {boolean} whether a browser was actually opened
+ */
+export function openBrowser(url) {
+  /** @type {Array<[string, string[]]>} */
+  const candidates =
+    process.platform === "darwin"
+      ? [["open", [url]]]
+      : process.platform === "win32"
+        ? [["rundll32", ["url.dll,FileProtocolHandler", url]]]
+        : [["xdg-open", [url]], ["gio", ["open", url]], ["gnome-open", [url]]]
+  for (const [bin, args] of candidates) {
+    try {
+      execFileSync(bin, args, { stdio: "ignore", timeout: 10_000 })
+      return true
+    } catch {
+      // Try the next opener. The URL is printed either way, because a
+      // browser that cannot be opened here can be opened anywhere.
+    }
+  }
+  return false
+}
+
 /**
  * Run npm and return its output.
  *
@@ -153,19 +184,24 @@ async function npmWithOtp(args, state = {}) {
   // OC_TRUST_NO_BROWSER turns the opening off, which is what a test needs:
   // a test that opens a browser on the machine it runs on is a test that
   // breaks whatever the person at the keyboard was doing.
+  let opened = false
   if (!process.env.OC_TRUST_NO_BROWSER) {
-    try {
-      execFileSync("xdg-open", [authUrl], { stdio: "ignore", timeout: 10_000 })
-    } catch {
-      // No browser here. The URL below is the way out.
-    }
+    opened = openBrowser(authUrl)
   }
   console.error("")
   console.error(bold("  npm needs to confirm it is you."))
   console.error(`  ${authUrl}`)
   console.error(dim("  Answer there however your npm account is set up - an authenticator"))
   console.error(dim("  app, a security key, or a code sent to your email."))
-  console.error(dim("  This page is open in a browser, or copy the URL above."))
+  // Saying the page is open when it is not sends the person looking for a
+  // browser window that was never opened.
+  console.error(
+    dim(
+      opened
+        ? "  This page is open in a browser, or copy the URL above."
+        : "  Open this page in a browser: the URL above is the way in.",
+    ),
+  )
   console.error("")
 
   const token = await waitForToken(doneUrl)
@@ -270,10 +306,15 @@ export async function main(argv = []) {
     console.error("  npm install -g npm@latest")
     return 1
   }
-  try {
-    npm(["whoami"])
-  } catch {
+  // Whether the account is logged in. `npm whoami` is run captured rather
+  // than through `npm()`, because `npm()` ends the process on a failure - so
+  // the guidance below was unreachable and the user saw only npm's raw
+  // error text.
+  const who = npmCaptured(["whoami"])
+  if (who.code !== 0) {
     console.error(red("not logged in to the npm registry."))
+    const said = who.out.trim().split("\n").filter(Boolean).slice(-2).join(" ")
+    if (said) console.error(dim(`  npm said: ${said}`))
     console.error("  npm login")
     return 1
   }
@@ -379,6 +420,11 @@ export async function main(argv = []) {
       console.error("  revoke it on npmjs.com and run this again.")
       return 1
     }
+    // What is being replaced, kept so the failure below can say how to put
+    // it back. npm cannot edit a configuration, and a revoke that is not
+    // followed by a create leaves the package with NO trusted publisher at
+    // all - strictly worse than before this command ran.
+    const previous = describe(config)
     const revoked = await npmWithOtp(["trust", "revoke", name, "--id", id, "-y"], state)
     if (revoked.code !== 0) {
       console.error(red("npm did not revoke the old configuration, so nothing was replaced."))
@@ -401,6 +447,21 @@ export async function main(argv = []) {
     )
     if (created.code !== 0) {
       console.error(red("npm did not create the replacement configuration."))
+      // The old configuration is gone by now. Say so plainly, and say what
+      // the old one was, so the package is not left with nothing and nobody
+      // knowing why.
+      console.error(
+        red("  The old configuration has already been revoked, so this package has no trusted publisher now."),
+      )
+      console.error(
+        dim(`  It was: repository ${previous.repository} · file ${previous.file} · no environment`),
+      )
+      console.error(dim("  Put it back with:"))
+      console.error(
+        dim(
+          `    npm trust github ${name} --file ${previous.file} --repo ${previous.repository} --allow-publish --allow-stage-publish -y`,
+        ),
+      )
       const detail = created.out.trim()
       if (detail) {
         console.error(dim("  npm said:"))