opencode-harness-kit 0.0.0-stage → 0.2.0

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