opencode-harness-kit 0.4.2 → 0.4.4

package/dist/plugin.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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>;

package/dist/profile.d.ts

@@ -0,0 +1,399 @@
+export declare const ROOT: string;
+export type Retention = "zero-retention" | "retained" | "may-train" | "unknown";
+export type EffortRequest = string | null;
+export type RoleModel = {
+    model: string;
+    levels?: string[];
+    chain?: string[];
+};
+export type Lane = {
+    description: string;
+    mode?: string;
+    steps?: number;
+    permission?: Record<string, any>;
+    prompt: string;
+};
+export type Profile = {
+    id: string;
+    title?: string;
+    provider: string;
+    model: string;
+    family?: string | null;
+    /**
+     * the route for opencode's short auxiliary calls
+     */
+    utility?: {
+        model: string;
+        why?: string;
+    };
+    verified?: string;
+    retention: Retention;
+    maxRetention?: Retention;
+    notes?: string;
+    limits: {
+        context: number;
+        input?: number;
+        output: number;
+    };
+    supports?: {
+        reasoning?: boolean;
+        temperature?: boolean;
+        toolCall?: boolean;
+        structuredOutput?: boolean;
+        attachment?: boolean;
+    };
+    effort?: {
+        levels?: string[];
+        default?: string | null;
+        reserveShare?: number;
+    };
+    roles?: Record<string, EffortRequest>;
+    roleModels?: Record<string, RoleModel>;
+    prune?: {
+        enabled?: boolean;
+        keepRecentToolCalls?: number;
+        keepRecentTurns?: number;
+        keepUserMessages?: boolean;
+    };
+    fallback?: string[];
+};
+export type RetentionRecord = {
+    retention: Retention;
+    note?: string;
+    verified?: string;
+    source?: string;
+};
+/**
+ * @typedef {"zero-retention" | "retained" | "may-train" | "unknown"} Retention
+ * @typedef {string | null} EffortRequest
+ * @typedef {{ model: string, levels?: string[], chain?: string[] }} RoleModel
+ * @typedef {{ description: string, mode?: string, steps?: number, permission?: Record<string, any>, prompt: string }} Lane
+ * @typedef {object} Profile
+ * @property {string} id
+ * @property {string} [title]
+ * @property {string} provider
+ * @property {string} model
+ * @property {string | null} [family]
+ * @property {{ model: string, why?: string }} [utility] the route for opencode's short auxiliary calls
+ * @property {string} [verified]
+ * @property {Retention} retention
+ * @property {Retention} [maxRetention]
+ * @property {string} [notes]
+ * @property {{ context: number, input?: number, output: number }} limits
+ * @property {{ reasoning?: boolean, temperature?: boolean, toolCall?: boolean,
+ *             structuredOutput?: boolean, attachment?: boolean }} [supports]
+ * @property {{ levels?: string[], default?: string | null, reserveShare?: number }} [effort]
+ * @property {Record<string, EffortRequest>} [roles]
+ * @property {Record<string, RoleModel>} [roleModels]
+ * @property {{ enabled?: boolean, keepRecentToolCalls?: number,
+ *             keepRecentTurns?: number, keepUserMessages?: boolean }} [prune]
+ * @property {string[]} [fallback]
+ * @typedef {{ retention: Retention, note?: string, verified?: string, source?: string }} RetentionRecord
+ */
+export declare class ProfileError extends Error {
+}
+/**
+ * The lanes a profile may enable. Five are workflow positions in the plan ->
+ * build -> review -> finish loop; five are capability lanes that exist because
+ * one free model can do a job none of the other nine can.
+ */
+export declare const LANE_NAMES: string[];
+/** The lanes that are part of the plan -> build -> review -> finish loop. */
+export declare const WORKFLOW_LANES: string[];
+/**
+ * How bad a retention level is, as a number. Bigger is worse.
+ *
+ * `unknown` is the worst of them. `retentionAllowed` refuses it outright - a
+ * lane that would run on a model nobody has stated the terms of is worse
+ * than a lane that runs on a worse model with known terms - so a severity
+ * table that ranked it as milder than `may-train` contradicted the rule it
+ * sits next to.
+ *
+ * @param {string} level
+ * @returns {number} the rank, or -1 for a level that is not one of them
+ */
+export declare function retentionSeverity(level: string): number;
+/**
+ * Profiles live in profiles/ (verified). schema.json and index.json are not
+ * profiles.
+ */
+export declare function profileDirs(): string[];
+/** @param {string} id @returns {string | null} */
+export declare function profilePath(id: string): string | null;
+/** @returns {string[]} */
+export declare function listProfileIds(): string[];
+/** @param {string} id @returns {Profile} */
+export declare function loadProfile(id: string): Profile;
+/**
+ * Fill in derived fields so nothing downstream has to guess.
+ * @param {Profile} p @returns {Profile}
+ */
+export declare function normalize(p: Profile): Profile;
+/**
+ * The lane table: what each job is for, and nothing about models.
+ * @returns {Record<string, Lane>}
+ */
+export declare function loadLanes(): Record<string, Lane>;
+/**
+ * @param {string} name
+ * @returns {Lane | null}
+ */
+export declare function laneMeta(name: string): Lane | null;
+/** @returns {string[]} */
+export declare function laneNames(): string[];
+export declare function loadRetention(): {
+    models: Record<string, RetentionRecord>;
+    defaults: Record<string, string>;
+};
+/**
+ * Retention as declared in retention.yml, which wins over the profile copy.
+ * Accepts either a bare profile id or an already-qualified provider/model.
+ * @param {string} id
+ * @returns {RetentionRecord | undefined}
+ */
+export declare function retentionFor(id: string): RetentionRecord | undefined;
+/**
+ * The retention of a model id, out of a retention table.
+ *
+ * Pure, so a test can hand it a table whose `defaults.unknown` says
+ * something else. The shipped table says "unknown", which is what the
+ * hardcoded fallback used to be - so a test that only checked the value
+ * could not tell the two apart.
+ *
+ * @param {{ models?: Record<string, RetentionRecord>, defaults?: Record<string, string> }} table
+ * @param {string} model
+ * @returns {Retention}
+ */
+export declare function retentionOf(table: {
+    models?: Record<string, RetentionRecord>;
+    defaults?: Record<string, string>;
+}, model: string): Retention;
+/**
+ * The retention of a model id, qualified or not.
+ *
+ * A model with no entry in retention.yml gets the `defaults.unknown` value
+ * from that file, which is `unknown` today. The fallback used to be
+ * hardcoded here, so the `defaults:` block in retention.yml looked like
+ * configuration and was not.
+ *
+ * @param {string} model
+ * @returns {Retention}
+ */
+export declare function modelRetention(model: string): Retention;
+/**
+ * Whether a model's retention is at or below a ceiling.
+ *
+ * `unknown` is never allowed: a lane that would run on a model nobody has
+ * stated the terms of is worse than a lane that runs on a worse model with
+ * known terms.
+ *
+ * @param {string} model
+ * @param {Retention} ceiling
+ * @returns {boolean}
+ */
+export declare function retentionAllowed(model: string, ceiling: Retention): boolean;
+/**
+ * The ordered models that may serve a lane.
+ *
+ * A lane with no `roleModels` entry runs on the profile's base model, which
+ * is the single-model profile shape. A lane with a `chain` walks it.
+ *
+ * @param {Profile} p
+ * @param {string} role
+ * @returns {string[]}
+ */
+export declare function resolveLaneChain(p: Profile, role: string): string[];
+/**
+ * The model that actually serves a lane right now.
+ *
+ * The first rung of the chain that is allowed by the retention ceiling and is
+ * not marked unhealthy wins. When no rung qualifies, the lane falls back to
+ * the profile's base model, so a lane is never left without a model - and a
+ * base model that is itself spent is the last resort rather than the first.
+ *
+ * @param {Profile} p
+ * @param {string} role
+ * @param {{ unhealthy?: Set<string> }} [opts]
+ * @returns {{ model: string, levels: string[] }}
+ */
+export declare function resolveLaneModel(p: Profile, role: string, opts?: {
+    unhealthy?: Set<string>;
+}): {
+    model: string;
+    levels: string[];
+};
+/**
+ * The effort levels a model publishes, read from that model's own profile.
+ *
+ * @param {string} model
+ * @returns {string[]}
+ */
+export declare function levelsOfModel(model: string): string[];
+/**
+ * Model and effort levels for one lane, or null when the lane stays on the
+ * profile's base model with no chain.
+ *
+ * @param {Profile} p
+ * @param {string} role
+ * @param {{ unhealthy?: Set<string> }} [opts]
+ * @returns {{ model: string, levels: string[] } | null}
+ */
+export declare function resolveRoleModel(p: Profile, role: string, opts?: {
+    unhealthy?: Set<string>;
+}): {
+    model: string;
+    levels: string[];
+} | null;
+/**
+ * @param {Profile} p
+ * @param {{ unhealthy?: Set<string> }} [opts]
+ * @returns {Record<string, string | null>}
+ */
+export declare function resolveRoles(p: Profile, opts?: {
+    unhealthy?: Set<string>;
+}): Record<string, string | null>;
+/** @param {Profile} p @returns {string | null} */
+export declare function resolveDefaultVariant(p: Profile): string | null;
+/**
+ * Pick the available level closest to what a role asked for.
+ *
+ * A role asking for `max` on a model topping out at `xhigh` gets `xhigh`. A
+ * model with no tunable effort resolves to null, meaning "emit no variant"
+ * rather than "emit a level the model does not have".
+ *
+ * @param {string[]} levels
+ * @param {EffortRequest} requested
+ * @returns {string | null}
+ */
+export declare function resolveEffort(levels: string[], requested: EffortRequest): string | null;
+/** @param {Profile} p @param {string} [path] */
+export declare function validate(p: Profile, path?: string): void;
+/**
+ * The model whose limits govern context management: the NARROWEST one in play.
+ *
+ * A fleet mixes models with a 1M window and models with a 200k one, and
+ * `compaction.reserved` is a single number for the whole config. Sizing it by
+ * the widest model would reserve a sixth of a 1M window - 125k tokens - and
+ * leave a 200k lane with 74k usable, which is where the lane stops working.
+ * Sizing it by the narrowest model means every lane keeps a workable window,
+ * and a lane with a wide window simply compacts a little later.
+ *
+ * @param {Profile} p
+ * @param {{ unhealthy?: Set<string> }} [opts]
+ * @returns {number}
+ */
+export declare function inputCap(p: Profile, opts?: {
+    unhealthy?: Set<string>;
+}): number;
+/**
+ * Tokens held back from the input ceiling for reasoning growth and in-flight
+ * tool output. Scaled from the model, never hardcoded.
+ * @param {Profile} p
+ * @param {{ unhealthy?: Set<string> }} [opts]
+ * @returns {number}
+ */
+export declare function reservedTokens(p: Profile, opts?: {
+    unhealthy?: Set<string>;
+}): number;
+/**
+ * Context budget above which pruning should already be working.
+ * @param {Profile} p
+ * @param {{ unhealthy?: Set<string> }} [opts]
+ * @returns {number}
+ */
+export declare function pruneThreshold(p: Profile, opts?: {
+    unhealthy?: Set<string>;
+}): number;
+/**
+ * Every model a profile can put behind the user: the base model plus the model
+ * each lane actually resolves to.
+ *
+ * @param {Profile} p
+ * @param {{ unhealthy?: Set<string> }} [opts]
+ * @returns {string[]}
+ */
+export declare function modelsInPlay(p: Profile, opts?: {
+    unhealthy?: Set<string>;
+}): string[];
+/**
+ * The split lanes, each with the limits of the model that lane actually runs
+ * on. A lane on a different model has a different output cap, and the header
+ * has to say so: reading "output cap 524,288" and assuming `build` can spend
+ * all of it is wrong whenever build is split onto a smaller model.
+ *
+ * @param {Profile} p
+ * @param {{ unhealthy?: Set<string> }} [opts]
+ * @returns {{ role: string, model: string, levels: string[], limits: Profile["limits"] | null }[]}
+ */
+export declare function roleSplitModels(p: Profile, opts?: {
+    unhealthy?: Set<string>;
+}): {
+    role: string;
+    model: string;
+    levels: string[];
+    limits: Profile["limits"] | null;
+}[];
+/**
+ * The retention that actually applies once every lane is considered, which is
+ * what a config header has to print. `retention.yml` is the source of truth.
+ *
+ * `worst` is the MODEL responsible for that level, not the level itself. The
+ * two used to be the same field with two different meanings - a retention
+ * class on one path and a model id on the other - and the header prints it as
+ * a model name, so a fleet that resolved to a `retained` lane said
+ * "but retained makes the whole file retained".
+ *
+ * @param {Profile} p
+ * @param {{ unhealthy?: Set<string> }} [opts]
+ * @returns {{ retention: string, worst: string | null }}
+ */
+export declare function effectiveRetention(p: Profile, opts?: {
+    unhealthy?: Set<string>;
+}): {
+    retention: string;
+    worst: string | null;
+};
+/** Where opencode keeps its config, honouring the same env var it does. */
+export declare function configDir(): string;
+/** @returns {string} */
+export declare function configFilePath(): string;
+/**
+ * The config directory written the way opencode's `{file:...}` references
+ * want it: a tilde when it is the default, an absolute path otherwise.
+ *
+ * A relative reference is silently ignored by opencode, so a prompt file that
+ * resolves to nothing leaves the lane with no instructions and no error.
+ *
+ * @returns {string}
+ */
+export declare function configDirRef(): string;
+/**
+ * The reference opencode resolves for a lane's prompt file.
+ * @param {string} lane
+ * @returns {string}
+ */
+export declare function promptRef(lane: string): string;
+/**
+ * Parse JSONC the way OpenCode does: comments and trailing commas are legal.
+ *
+ * A regex that strips `//` cannot be used here. The generated config carries
+ * `"$schema": "https://opencode.ai/config.json"`, so a naive strip corrupts the
+ * URL; and a trailing comma -- ordinary in a hand-edited `.jsonc` -- makes
+ * `JSON.parse` throw, which used to surface as an empty object and silently
+ * dropped every hand-tuned key in `oc-harness use`. This walks the text once,
+ * tracking string state, so both are handled correctly.
+ *
+ * @param {string} text
+ * @returns {Record<string, unknown> | null} null when the text is not valid JSONC
+ */
+export declare function parseJsonc(text: string): Record<string, unknown> | null;
+/**
+ * Read the active profile id from the config file on disk.
+ *
+ * Returns null when the file is absent, unreadable, or not valid JSONC. Callers
+ * fall back to the profile named in the `config` hook, so a null here degrades
+ * to the default profile rather than failing.
+ *
+ * @returns {string | null}
+ */
+export declare function profileIdFromConfig(): string | null;

package/dist/project.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The root of the project a session is working in.
+ *
+ * @param {string | null | undefined} directory the session's working directory
+ * @param {string | null | undefined} worktree opencode's worktree, as a fallback
+ * @returns {string}
+ */
+export declare function projectRoot(directory: string | null | undefined, worktree: string | null | undefined): string;

package/dist/prune.d.ts

@@ -0,0 +1,6 @@
+import type { Plugin } from "./plugin.js";
+export declare const PrunePlugin: Plugin;
+export declare const pruneMeta: {
+    note: string;
+};
+export default PrunePlugin;

package/dist/router.d.ts

@@ -0,0 +1,3 @@
+import type { Plugin } from "./plugin.js";
+export declare const RouterPlugin: Plugin;
+export default RouterPlugin;

package/dist/rules.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Whether a write target stays inside the project. A relative path is resolved
+ * against the project root, which is where the agent's working directory is.
+ * @param {string} target
+ * @param {string} root
+ * @returns {boolean}
+ */
+export declare function insideRoot(target: string, root: string): boolean;
+export type Rule = {
+    name: string;
+    test?: RegExp;
+    check?: (text: string) => boolean;
+    why: string;
+    scope?: "segment" | "command";
+    unless?: RegExp;
+};
+export type Hit = {
+    name: string;
+    why: string;
+    segment: string;
+};
+/**
+ * Split a shell command into the individual commands it runs. Separators
+ * inside quotes, and heredoc bodies, are not command boundaries.
+ * @param {string} command
+ * @returns {string[]}
+ */
+export declare function segments(command: string): string[];
+/**
+ * Split one segment into words, honouring quotes so that a quoted phrase is
+ * one argument rather than several.
+ * @param {string} segment
+ * @returns {string[]}
+ */
+export declare function tokenize(segment: string): string[];
+/**
+ * A segment with its prefixes removed, so a rule anchored at `^` sees the
+ * command it is actually about: `sudo rm -rf /` becomes `rm -rf /`.
+ * Segment rules are matched against this rather than the raw text, because
+ * without it every anchored rule is one `sudo` away from being decorative.
+ * @param {string} segment
+ * @returns {string} empty when the segment names no command
+ */
+export declare function stripPrefixes(segment: string): string;
+/**
+ * Resolve the git subcommand a segment actually runs, or null if the segment
+ * does not run git.
+ * @param {string} segment
+ * @returns {string | null}
+ */
+export declare function gitSubcommand(segment: string): string | null;
+/**
+ * The command line hidden inside `sh -c "..."` or `eval "..."`.
+ * @param {string} segment
+ * @returns {string | null}
+ */
+export declare function shellPayload(segment: string): string | 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 declare const ASK_GATED: RegExp[];
+/** @type {Rule[]} */
+export declare const BASH_RULES: Rule[];
+/** @type {Rule[]} */
+export declare const WRITE_RULES: Rule[];
+/**
+ * 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 declare function checkDenied(command: string, depth?: number): {
+    pattern: string;
+    segment: string;
+} | null;
+/**
+ * @param {string} command
+ * @param {Rule[]} [rules]
+ * @param {number} [depth]
+ * @returns {Hit | null}
+ */
+export declare function checkBash(command: string, rules?: Rule[], depth?: number): Hit | null;
+/**
+ * @param {string} target
+ * @param {Rule[]} [rules]
+ * @param {string} [root] the project directory, when the host knows it
+ * @returns {Hit | null}
+ */
+export declare function checkWrite(target: string, rules?: Rule[], root?: string): Hit | null;
+/** Names of every rule, for `oc-harness show` and documentation. */
+export declare function ruleNames(): string[];

package/dist/safe.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Stringify a value, never throwing.
+ *
+ * @param {unknown} value
+ * @returns {string}
+ */
+export declare function safeStringify(value: unknown): string;

package/dist/telemetry-store.d.ts

@@ -0,0 +1,12 @@
+/** Rotate above this, so a long-running project cannot fill its disk. */
+export declare const MAX_BYTES: number;
+export declare function logPath(dir: string): string;
+/** The telemetry file and its rotated predecessors, oldest first. */
+export declare function logFiles(dir: string): string[];
+/**
+ * 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 declare function write(dir: string, record: Record<string, unknown>): void;

package/dist/telemetry.d.ts

@@ -0,0 +1,3 @@
+import type { Plugin } from "./plugin.js";
+export declare const TelemetryPlugin: Plugin;
+export default TelemetryPlugin;

package/docs/EXIT-CODES.md

@@ -0,0 +1,71 @@
+# Exit codes
+
+Every command that can fail says so in its exit code, so a script can tell
+"the kit says no" from "the kit broke". A command that succeeded exits 0 and
+prints nothing to stderr.
+
+## `oc-harness run`
+
+The unattended loop. It walks `space-tasks.md`, asks the agent for one task
+at a time, and re-runs the task's own verify command before believing it.
+
+| Code | Meaning |
+|---|---|
+| 0 | Every task is done. |
+| 1 | There is no task file. The loop needs a plan to walk. |
+| 2 | Stopped early and a person is needed: a task is blocked, a task has no verify command, the round cap was reached, or the time budget ran out. |
+| 3 | The agent itself failed. The reason is the agent's own last words, and the task is marked blocked with them. |
+| 4 | The verify command failed. The task is marked blocked and the real output is in `space-tasks.md` - not in the exit code, which is no place for a stack trace. |
+
+Code 2 is the "asked for something impossible" code: nothing about it is a
+bug, and the reason is printed. Codes 3 and 4 mean the work did not land.
+
+## `oc-harness doctor`
+
+| Code | Meaning |
+|---|---|
+| 0 | Everything checks out. |
+| 1 | Something does not. The problems are listed, one per line. |
+
+`--check-models` exits 1 as soon as a profile has drifted from the live
+catalogue. `--watch` never exits: it polls, and reports only what CHANGED.
+
+A failed catalogue fetch is not a finding. It is reported, the models are not
+announced as withdrawn, and the poll carries on - a catalogue that cannot be
+read says nothing about the models in it.
+
+With `--json` the report is the only thing on stdout: a script that pipes it
+into a parser gets JSON, and a failure is a JSON object with an `error` in
+it, not a parse error.
+
+## The measurement gates
+
+`npm run measure:check` runs two measurements and both have to pass.
+
+| Code | Meaning |
+|---|---|
+| 0 | Every measurement that could be compared is inside its threshold. |
+| 1 | One is not. The report names the threshold and the number. |
+
+A measurement that could NOT be compared - the two windows do not hold the
+same work, so the difference is confounded - is reported as a NOTE and NOT
+gated. The attributable measurement of the same thing, the pruner replayed
+over real stored sessions, is the one that gates.
+
+A gate that fires for reasons nobody can act on is a gate people switch off,
+so the incomparable case is reported loudly and gated never, and the
+attributable measurement carries the gate.
+
+## `oc-harness install` and `oc-harness use`
+
+| Code | Meaning |
+|---|---|
+| 0 | The install is in place, or the change was confirmed. |
+| 1 | The install was refused, left alone, or a step failed. |
+
+`doctor` also exits 1 when there is no config, or no profile recorded in
+it: a kit that is installed but points at nothing is a broken install, and
+a check that passes it is not a check.
+
+Nothing is overwritten without a confirmation, unless `--yes` is given. With
+`--yes`, the old config is still written to the backup directory first.