opencode-harness-kit 0.0.0-stage → 0.1.0

package/src/config.js

@@ -0,0 +1,326 @@
+// Compile a profile into an opencode.jsonc.
+//
+// Config that does not depend on the model - permission allowlist, pruning
+// defaults, experimental flags - is fixed here. Everything model-specific is
+// derived from the profile, so switching models changes only the profile file.
+
+import { pruneThreshold, reservedTokens, resolveRoles, resolveDefaultVariant } from "./profile.js"
+
+import { join } from "node:path"
+import { homedir } from "node:os"
+
+/** @typedef {import("./profile.js").Profile} Profile */
+
+/**
+ * Where the global rule set lives, as opencode should be told to look for it.
+ *
+ * Honours OPENCODE_CONFIG_DIR, because `~/.config/opencode` is only the default
+ * and emitting it unconditionally points at the wrong file for anyone using a
+ * custom config directory - the installer would write one place and the
+ * compiler would name another. Written with a leading `~` when it is the
+ * default, which is both correct and readable in the generated file.
+ */
+export function globalInstructionsPath() {
+  const dir = process.env.OPENCODE_CONFIG_DIR ?? join(homedir(), ".config", "opencode")
+  if (dir === join(homedir(), ".config", "opencode")) return "~/.config/opencode/GLOBAL.md"
+  return join(dir, "GLOBAL.md")
+}
+
+/**
+ * The default location, for documentation and tests. Prefer
+ * `globalInstructionsPath()` when generating a config.
+ *
+ * It is written by `oc-harness install`, which symlinks this file rather than
+ * copying it, so the repo stays the source of truth. `oc-harness verify` fails if
+ * the path it names does not resolve - the failure mode where a config points at
+ * an instruction file that was never installed is silent and makes the whole
+ * harness a no-op.
+ */
+export const GLOBAL_INSTRUCTIONS = "~/.config/opencode/GLOBAL.md"
+
+/**
+ * Read-only and verification commands.
+ *
+ * Measured against 5,239 real bash calls from one install: 95.3% would prompt
+ * under a narrow allowlist, 23% under this one. The gated remainder is
+ * deliberate - ssh, curl, rm, pkill, osascript, cp, mv, kill, docker.
+ *
+ * `X*` with no space is used on purpose: opencode's `X *` pattern requires a
+ * trailing space and therefore does not match a bare `X`.
+ *
+ * The `gh` verbs below are the read half of the CLI and nothing else. `gh pr
+ * create`, `gh pr merge` and `gh api` are NOT here: they write, and `gh api` in
+ * particular can POST to any endpoint. Measured cost of gating the whole `gh`
+ * surface was 146 prompts; gating only the mutating verbs keeps those 146
+ * prompt-free without opening a publish path the guard plugin cannot police.
+ */
+export const BASH_ALLOWLIST = [
+  "ls*", "cat*", "head*", "tail*", "wc*", "file*", "stat*", "pwd*", "env*", "printenv*",
+  "date*", "whoami*", "which*", "find*", "tree*", "du*", "df*", "lsof*", "sed*", "awk*",
+  "sort*", "uniq*", "diff*", "grep*", "rg*", "echo*", "printf*", "sleep*",
+  "cd*", "realpath*", "basename*", "dirname*", "readlink*",
+  "for*", "set*", "export*", "unset*", "bash*", "sh*", "true*", "false*", "test*",
+  "read*", "#*", "xargs*", "seq*", "exit*", ":*",
+  "node*", "python3*", "python*", "npm*", "bun*", "uv*", "go*", "cargo*", "rustc*",
+  "opencode*", "sqlite3*", "jq*", "fd*",
+  "git status*", "git log*", "git diff*", "git show*", "git branch*",
+  "git rev-parse*", "git config --get*", "git remote*", "git blame*",
+  "git stash list*", "git ls-files*", "git describe*", "git shortlog*", "git --version*",
+  // `git -C <dir> <read-verb>` only. A bare `git -C *` would allow `git -C x push`.
+  "git -C * status*", "git -C * log*", "git -C * diff*", "git -C * rev-parse*",
+  "git -C * ls-files*", "git -C * show*",
+  // Staging is local and reversible; publishing is not and stays gated.
+  "git add*",
+  // `chmod 777` is denied below. `+x` is ordinary build work.
+  "chmod +x*", "chmod u+x*",
+  "mkdir*", "ps*",
+  "gh pr list*", "gh pr view*", "gh pr diff*", "gh pr checks*", "gh pr status*",
+  "gh issue list*", "gh issue view*", "gh repo view*", "gh auth status*",
+  "PYTEST_DISABLE_PLUGIN_AUTOLOAD=1*", "PYTHONPATH=*", "PYTHONUNBUFFERED=1*",
+  "python3 -m pytest*", "python3 -m venv*", "python3 -m compileall*",
+  "python3 -c*", "python3 agent/*", "python3 src/*", "python3 -",
+  ".venv/bin/python*", "pytest*", "ruff*", "mypy*", "black*",
+  "npm test*", "npm run *", "npm ci*", "npm ls*", "npm view *",
+  "npx*", "uv run *", "uv pip *", "bun run *", "bunx*", "node -e*",
+  "opencode debug*", "opencode --version*", "opencode models*",
+]
+
+/** Hard blocks. The guard plugin enforces the same set in code. */
+export const BASH_DENYLIST = [
+  "git push *",
+  "git push*",
+  "rm -rf *",
+  "rm -fr *",
+  "curl * | sh",
+  "curl * | bash",
+  "chmod 777 *",
+  "chmod 777*",
+  "gh pr create*",
+  "gh pr merge*",
+  "gh pr close*",
+  "gh release*",
+  "gh repo delete*",
+]
+
+/**
+ * Iteration cap per role, written as `agent.<role>.steps`.
+ *
+ * `steps` is a loop breaker rather than a quality knob. On exhaustion OpenCode
+ * forces a text-only response, so an agent that has stopped making progress
+ * reports what it has instead of silently looping until the context is gone.
+ * The caps are sized to the role's real work: build gets room because it runs
+ * the edit-verify-fix cycle, verify gets room because a full suite is many
+ * commands, and the read-only roles are capped tight because they have one job.
+ */
+export const AGENT_STEPS = /** @type {Record<string, number>} */ ({
+  build: 40,
+  plan: 25,
+  reviewer: 15,
+  locate: 12,
+  verify: 20,
+})
+
+/** Roles the kit writes, with the permissions that keep them honest. */
+const AGENT_PERMISSIONS = /** @type {Record<string, Record<string, string>>} */ ({
+  plan: { edit: "deny" },
+  reviewer: { edit: "deny" },
+  locate: { edit: "deny", bash: "deny" },
+  verify: { edit: "deny" },
+})
+
+/**
+ * @param {Profile} p
+ * @param {{ base?: Record<string, any>, comments?: boolean }} [opts]
+ * @returns {string}
+ */
+export function generateConfig(p, opts = {}) {
+  const base = opts.base ?? {}
+  const model = `${p.provider}/${p.model}`
+  const roles = resolveRoles(p)
+  const instructionsPath = globalInstructionsPath()
+
+  const agent = { ...(base.agent ?? {}) }
+  for (const [role, level] of Object.entries(roles)) {
+    if (level === undefined) continue
+    const existing = { ...(agent[role] ?? {}) }
+    // The model is pinned, never inherited. Preserving a model already written
+    // on the agent is how `build` ended up on a `may-train` model while the rest
+    // of the file claimed the profile's zero-retention one: the compiler was
+    // asked to re-run over a hand-edited config and kept the hand-edit.
+    existing.model = model
+    if (level === null) delete existing.variant
+    else existing.variant = level
+    if (AGENT_PERMISSIONS[role]) {
+      existing.permission = {
+        ...(existing.permission ?? {}),
+        ...AGENT_PERMISSIONS[role],
+      }
+    }
+    if (AGENT_STEPS[role]) existing.steps = AGENT_STEPS[role]
+    agent[role] = existing
+  }
+
+  const bashRules = {
+    "*": "ask",
+    ...Object.fromEntries(BASH_ALLOWLIST.map((rule) => [rule, "allow"])),
+    ...Object.fromEntries(BASH_DENYLIST.map((rule) => [rule, "deny"])),
+  }
+
+  const compaction = { ...(base.compaction ?? {}) }
+  // `tail_turns` is dropped even if the inherited config had one. It only
+  // applies during compaction, and compaction is keyed off the full context
+  // ceiling, which a normal session never reaches. On the measured install it
+  // had never fired once, so it was inert config.
+  delete compaction.tail_turns
+  compaction.auto = true
+  compaction.prune = true
+  compaction.reserved = reservedTokens(p)
+
+  const base_ = { ...base }
+  // Two keys are dropped from the inherited config outright rather than merged.
+  // Both are cases where an existing value silently defeats the compiler:
+  // `variant` is rejected by the schema and stripped at load, so keeping it
+  // makes the file look tiered while doing nothing; and `tool_output` set tight
+  // by an earlier version would otherwise survive every regeneration.
+  delete base_.variant
+  delete base_.tool_output
+
+  const out = {
+    $schema: "https://opencode.ai/config.json",
+    ...base_,
+
+    model,
+    // Same model, not a cheaper one: swapping models mid-session changes the
+    // voice and the tool habits. Lower the effort instead. An inherited
+    // small_model pointing at a different model is replaced, not preserved.
+    small_model: model,
+    // No top-level `variant`. The 1.18.35 Config schema sets
+    // `additionalProperties: false` and has no `variant` key, so OpenCode
+    // strips it from the resolved config - verified with `opencode debug
+    // config`. The per-role tiering is carried by `agent.<role>.variant`,
+    // which is a real schema key, and `effort.js` sets the session default at
+    // the `config` hook where the runtime does still see it.
+    default_agent: base.default_agent ?? "build",
+
+    // The default is 1, which blocks subagents from spawning subagents and so
+    // removes every nested review loop.
+    subagent_depth: base.subagent_depth ?? 2,
+    // Omitting `lsp` disables it entirely, so this must be set explicitly.
+    lsp: base.lsp ?? true,
+    instructions: base.instructions ?? [instructionsPath],
+
+    compaction,
+    // OpenCode's own default (2000 lines / 51200 bytes), reached back from an
+    // earlier 200 / 8192. The tight setting truncated 415 of 2,959 measured
+    // `read` calls, and 418 calls were issued with an `offset` to fetch the
+    // rest: the truncation causes the re-read, one for one. At the measured
+    // 17.3s median per request that round trip costs far more than the tokens
+    // it saves, and prune.ts already bounds old tool output deterministically.
+    // Only 14 of 2,959 reads exceed 51,200 bytes, so this ceiling is not the
+    // thing that limits context. `oc-harness baseline` re-measures all four
+    // numbers if this ever needs arguing again.
+    tool_output: { max_lines: 2000, max_bytes: 51200 },
+
+    skills: base.skills ?? {},
+
+    experimental: {
+      batch_tool: true,
+      continue_loop_on_deny: true,
+      ...(base.experimental ?? {}),
+    },
+
+    permission: {
+      ...(base.permission ?? {}),
+      read: "allow",
+      // `allow` here is load-bearing in a way that is easy to get backwards, and
+      // it is pinned rather than inherited for the same reason the model is: an
+      // inherited `ask` survives regeneration and re-breaks every read-only
+      // role.
+      //
+      // OpenCode appends the global rule AFTER the agent's own, and last match
+      // wins, so a global `edit: "ask"` silently overrides every agent's
+      // `edit: "deny"` and the read-only roles can edit files after a prompt.
+      // `allow` is the implicit default and emits no rule at all, which leaves
+      // the per-agent `deny` intact. Writes outside the project are still
+      // gated by `external_directory`, which defaults to `ask`.
+      edit: "allow",
+      // OpenCode ships this as `deny` on every built-in agent, so a genuinely
+      // blocked agent has no cheap way to say so and falls back to prose. One
+      // structured question is cheaper to answer and easier to act on.
+      question: "allow",
+      doom_loop: base.permission?.doom_loop ?? "ask",
+      bash: bashRules,
+    },
+
+    agent,
+
+    // The router plugin reads this at startup to know which fallback queue to
+    // walk, and it is also how a profile stays identifiable after the config
+    // has been hand-edited.
+    harness: {
+      profile: p.id,
+      ...(p.fallback?.length ? { fallback: p.fallback[0] } : {}),
+      threshold: pruneThreshold(p),
+    },
+  }
+
+  return render(out, p, { comments: opts.comments ?? true, instructionsPath })
+}
+
+/**
+ * @param {Record<string, any>} cfg
+ * @param {Profile} p
+ * @param {{ comments: boolean, instructionsPath?: string }} opts
+ * @returns {string}
+ */
+function render(cfg, p, opts) {
+  const c = opts.comments ? "// " : ""
+  const instructionsPath = opts.instructionsPath ?? globalInstructionsPath()
+  const input = p.limits.input ?? p.limits.context
+  const levels = p.effort?.levels ?? []
+  const roles = resolveRoles(p)
+
+  const head = [
+    `${c}Generated by opencode-harness-kit. Edit profiles/${p.id}.json instead`,
+    `${c}of this file, then re-run: oc-harness use ${p.id}`,
+    `${c}`,
+    `${c}profile      ${p.id}`,
+    `${c}model        ${p.provider}/${p.model}`,
+    `${c}context      ${p.limits.context.toLocaleString("en-US")} tokens`,
+    `${c}input cap    ${input.toLocaleString("en-US")} tokens`,
+    `${c}output cap   ${p.limits.output.toLocaleString("en-US")} tokens`,
+    `${c}reasoning    ${levels.length ? levels.join(" < ") : "(not tunable)"}`,
+    `${c}retention    ${p.retention}${p.retention === "may-train" ? "  <-- prompts may train a model" : ""}`,
+    `${c}`,
+    `${c}Derived numbers, do not hand-edit:`,
+    `${c}  compaction.reserved  ${reservedTokens(p).toLocaleString("en-US")}  (${Math.round((p.effort?.reserveShare ?? 0.12) * 100)}% of the input cap, held back for reasoning growth)`,
+    `${c}  prune threshold      ${pruneThreshold(p).toLocaleString("en-US")}  (input cap minus reserve)`,
+    `${c}  role effort          ${Object.entries(roles).map(([k, v]) => `${k}=${v ?? "unset"}`).join("  ")}`,
+    `${c}  agent steps          ${Object.entries(AGENT_STEPS).filter(([r]) => roles[r]).map(([r, n]) => `${r}=${n}`).join("  ")}`,
+  ]
+
+  if (!levels.length) {
+    head.push(`${c}`, `${c}This model publishes no tunable reasoning effort, so no variant is written.`)
+  } else {
+    head.push(
+      `${c}`,
+      `${c}Effort is per-role above. There is no top-level "variant" key: the 1.18.35`,
+      `${c}Config schema rejects it, and the router sets the session default at runtime.`,
+    )
+  }
+  if (p.supports?.temperature === false) {
+    head.push(`${c}This model does not support temperature, so none is set.`)
+  }
+  if (p.prune?.enabled) {
+    head.push(
+      `${c}  prune keeps         ${p.prune.keepRecentToolCalls ?? 6} tool calls, ${p.prune.keepRecentTurns ?? 3} turns verbatim`,
+    )
+  }
+  head.push(
+    `${c}`,
+    `${c}Run "oc-harness verify" to check this file still matches the profile and`,
+    `${c}that the agents and ${instructionsPath} are actually installed.`,
+  )
+
+  return `${head.join("\n")}\n${JSON.stringify(cfg, null, 2)}\n`
+}

package/src/effort.js

@@ -0,0 +1,98 @@
+// Apply a profile's role-based reasoning effort to the OpenCode config.
+//
+// Why this exists: no plugin hook can change a live session's model, but the
+// `config` hook runs once at startup, which is early enough to assign each
+// agent its effort level. Effort is the largest latency lever available without
+// changing models: on one measured install, `max` cost 18.7s median per request
+// against 7.8s for `xhigh` on a different model, while 77% of responses ended
+// on a tool call rather than prose.
+//
+// A level is never emitted raw. It is resolved against the profile's own
+// available levels, so a role asking for `max` on a model without `max` gets
+// the nearest level that actually exists.
+
+import { loadProfile, resolveRoles, resolveDefaultVariant } from "./profile.js"
+
+/**
+ * @typedef {import("./profile.js").Profile} Profile
+ * @typedef {import("./profile.js").EffortRequest} EffortRequest
+ * @typedef {import("@opencode-ai/plugin").Config} Config
+ * @typedef {object} EffortResult
+ * @property {string} profileId
+ * @property {string} model
+ * @property {string|null} defaultVariant
+ * @property {Record<string, string|null>} roles
+ * @property {string[]} notes
+ */
+
+/** Roles the kit manages. A role a profile does not mention is left alone. */
+export const MANAGED_ROLES = ["plan", "build", "reviewer", "locate", "verify"]
+
+/**
+ * @param {string} profileId
+ * @returns {EffortResult}
+ */
+export function planEffort(profileId) {
+  const p = loadProfile(profileId)
+  const levels = p.effort?.levels ?? []
+  const roles = resolveRoles(p)
+  const notes = []
+
+  if (levels.length === 0) {
+    notes.push(
+      `${p.model} publishes no tunable reasoning effort; variant will be omitted for every role.`,
+    )
+  }
+  for (const [role, want] of Object.entries(p.roles ?? {})) {
+    const got = roles[role]
+    if (want && got && want !== got) {
+      notes.push(`role ${role} asked for ${want}; ${p.model} tops out at ${got}.`)
+    }
+  }
+
+  return {
+    profileId,
+    model: `${p.provider}/${p.model}`,
+    defaultVariant: resolveDefaultVariant(p),
+    roles,
+    notes,
+  }
+}
+
+/**
+ * Mutate the resolved OpenCode config so each managed agent declares its own
+ * model and effort level.
+ *
+ * `AgentConfig.variant` only applies to the agent's own configured model, so
+ * the model is written alongside the variant instead of relying on the global
+ * default. That is also what makes per-role effort work at all.
+ *
+ * @param {Config} config
+ * @param {EffortResult} result
+ * @param {{ fallbackProfileId?: string }} [opts]
+ * @returns {Config}
+ */
+export function applyEffort(config, result, opts = {}) {
+  const cfg = /** @type {Record<string, any>} */ (config)
+
+  // Always pin the model. When the model has no tunable effort we still set it
+  // and simply omit `variant` below.
+  cfg.model = result.model
+
+  cfg.agent = cfg.agent ?? {}
+  for (const role of MANAGED_ROLES) {
+    const level = result.roles[role]
+    if (level === undefined) continue // role not described by this profile
+    const existing = cfg.agent[role] ?? {}
+    if (!existing.model) existing.model = result.model
+    if (level === null) delete existing.variant
+    else existing.variant = level
+    cfg.agent[role] = existing
+  }
+
+  cfg.harness = opts.fallbackProfileId
+    ? { profile: result.profileId, fallback: opts.fallbackProfileId }
+    : { profile: result.profileId }
+
+  return config
+}

package/src/guard.ts

@@ -0,0 +1,59 @@
+// Guard hook.
+//
+// The decision logic lives in rules.js so it can be tested without a
+// TypeScript runtime. This file is only the wiring.
+//
+// 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"
+
+const MARKER = "[opencode-harness-kit] blocked"
+
+function deny(why: string, detail: string): never {
+  // Throwing is the only way to stop a tool call from a hook.
+  throw new Error(
+    `${MARKER}: ${why}\n  ${detail}\n` +
+      `  This is enforced in code, not by a prompt. If the command is genuinely ` +
+      `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 }) => {
+  return {
+    "tool.execute.before": async (input, output) => {
+      try {
+        if (input.tool === "bash") {
+          const hit = checkBash(String(output.args?.command ?? ""))
+          if (hit) deny(hit.name, `${hit.why}\n  command: ${truncate(hit.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)}`)
+        }
+      } 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.
+        throw new Error(
+          `${MARKER} (guard failed closed): ${
+            err instanceof Error ? err.message : String(err)
+          }`,
+        )
+      }
+    },
+  }
+}
+
+export default GuardPlugin

package/src/index.ts

@@ -0,0 +1,80 @@
+// Plugin entry point.
+//
+// IMPORTANT: opencode treats every exported function in this module as a plugin
+// and calls it with the plugin input. A library re-exported from here is not a
+// plugin, so calling it produces something like "result.model of undefined" at
+// load time. Only plugin functions belong in this file; consumers import the
+// library modules (profile, config, rules) directly, per the package exports map.
+//
+// Each concern lives in its own module so a project can install only the ones
+// it wants. Nothing here names a model: which model is in use, what effort each
+// role gets, and how much context to reserve all come from a profile.
+
+import { mkdirSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+import type { Plugin } from "@opencode-ai/plugin"
+import { GuardPlugin } from "./guard.js"
+import { PrunePlugin } from "./prune.js"
+import { RouterPlugin } from "./router.js"
+import { TelemetryPlugin } from "./telemetry.js"
+import { applyEffort, planEffort } from "./effort.js"
+import { profileIdFromConfig } from "./profile.js"
+
+export interface HarnessOptions {
+  /** Profile id. Defaults to the one recorded in the config by `oc-harness use`. */
+  profile?: string
+  /** Load a subset. Defaults to all four. */
+  only?: Array<"guard" | "prune" | "router" | "telemetry">
+}
+
+export const HarnessPlugin: Plugin = async (ctx, options?: HarnessOptions) => {
+  const opts = (options ?? {}) as HarnessOptions
+  const want = new Set(opts.only ?? ["guard", "prune", "router", "telemetry"])
+
+  const plugins: Plugin[] = []
+  if (want.has("guard")) plugins.push(GuardPlugin)
+  if (want.has("telemetry")) plugins.push(TelemetryPlugin)
+  if (want.has("router")) plugins.push(RouterPlugin)
+  if (want.has("prune")) plugins.push(PrunePlugin)
+
+  const merged: Record<string, any> = {}
+  for (const p of plugins) {
+    const hooks = await p(ctx, {})
+    for (const [name, fn] of Object.entries(hooks)) {
+      const existing = merged[name]
+      merged[name] =
+        typeof existing === "function" && typeof fn === "function"
+          ? async (...a: unknown[]) => {
+              await existing(...a)
+              await (fn as (...b: unknown[]) => unknown)(...a)
+            }
+          : fn
+    }
+  }
+
+  // Effort assignment belongs to the config hook, which runs once at startup.
+  // Chained after the router so a failover profile wins.
+  const routerConfig = merged["config"]
+  merged["config"] = async (config: any) => {
+    if (routerConfig) await routerConfig(config)
+    // config.harness is unreliable here: OpenCode validates the config against a
+    // schema with additionalProperties false, so our custom key never reaches
+    // the hook. The config file does, so read the id from there.
+    const id = opts.profile ?? config?.harness?.profile ?? profileIdFromConfig()
+    if (!id) return
+    try {
+      applyEffort(config, planEffort(id))
+      // 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")
+      mkdirSync(dir, { recursive: true })
+      writeFileSync(join(dir, "active"), `${id}\n`)
+    } catch {
+      // Never block startup on a bad profile.
+    }
+  }
+
+  return merged as any
+}
+
+export default HarnessPlugin