opencode-harness-kit 0.4.2 → 0.4.4

package/dist/config.d.ts

@@ -0,0 +1,127 @@
+export type Profile = import("./profile.js").Profile;
+/** @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 declare function globalInstructionsPath(): string;
+/**
+ * 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 declare const GLOBAL_INSTRUCTIONS = "~/.config/opencode/GLOBAL.md";
+/**
+ * The kit's own version, read from its package.json.
+ *
+ * @returns {string}
+ */
+export declare function kitVersion(): string;
+/**
+ * The memory plugin this kit can turn on.
+ *
+ * The kit does not implement memory. A local vector store with embeddings, a
+ * web UI and auto-capture is a large thing to build badly, and there is one
+ * that is already good: `opencode-mem` (MIT). What the kit can do is make it
+ * one flag away, and keep the config honest about it.
+ */
+export declare const MEMORY_PLUGIN = "opencode-mem@latest";
+/**
+ * The config with the memory plugin turned on.
+ *
+ * The plugin list is preserved. The user's own plugins are not the kit's to
+ * remove, and the entry is added rather than replaced so a config that
+ * already has it does not grow a second copy.
+ *
+ * opencode v1 calls the key `plugin` and v2 calls it `plugins`; whichever
+ * the config already uses is the one that is extended.
+ *
+ * @param {any} base the config as it is on disk
+ * @param {string} [spec] the plugin id, so a pinned version or a mirror works
+ * @returns {any}
+ */
+export declare function withMemoryPlugin(base: any, spec?: string): any;
+/**
+ * Whether the memory plugin can be added to this config.
+ *
+ * A config whose plugin value is not a list is left alone: replacing a
+ * string with a list is data loss, and the promise is that the user's own
+ * plugins are never touched.
+ *
+ * @param {any} base
+ * @returns {boolean}
+ */
+export declare function canAddMemoryPlugin(base: any): boolean;
+/**
+ * The utility route a profile names, as a full model id.
+ *
+ * `small_model` is opencode's route for the short auxiliary calls. It used to
+ * be the session model, so every title and every rewritten question paid the
+ * session model's reasoning - and reasoning, not output, is what a short call
+ * costs.
+ *
+ * @param {any} p the profile
+ * @returns {string | null}
+ */
+export declare function utilityModel(p: any): string | null;
+/**
+ * The instruction list a generated config carries.
+ *
+ * The kit's own file is always in it. A config that already had an
+ * `instructions` array used to replace it wholesale, which unloaded the
+ * whole behavioural layer while everything still looked correct.
+ *
+ * The user's own files keep their order and come first; the kit's is
+ * appended. Duplicates are dropped, so re-running `use` does not grow the
+ * list.
+ *
+ * @param {string[] | string | undefined} base
+ * @param {string} kitPath
+ * @returns {string[]}
+ */
+export declare function mergeInstructions(base: string[] | string | undefined, kitPath: string): string[];
+/**
+ * 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 declare const BASH_ALLOWLIST: string[];
+/**
+ * Hard blocks.
+ *
+ * The list lives in ./denylist.js because it is enforced in TWO places: by
+ * opencode's permission map, and by the guard plugin. The two used to be
+ * different lists, and the comment here claimed they were the same.
+ */
+export { BASH_DENYLIST } from "./denylist.js";
+/**
+ * @param {Profile} p
+ * @param {{ base?: Record<string, any>, comments?: boolean, unhealthy?: Set<string> }} [opts]
+ * @returns {string}
+ */
+export declare function generateConfig(p: Profile, opts?: {
+    base?: Record<string, any>;
+    comments?: boolean;
+    unhealthy?: Set<string>;
+}): string;

package/dist/denylist.d.ts

@@ -0,0 +1,33 @@
+/** @type {string[]} */
+export declare const BASH_DENYLIST: string[];
+/**
+ * Whether a glob pattern matches a command.
+ *
+ * `*` matches any run of characters, including none.
+ *
+ * @param {string} command
+ * @param {string} pattern
+ * @returns {boolean}
+ */
+export declare function matchesPattern(command: string, pattern: string): boolean;
+/**
+ * The first denied pattern a command matches, or null.
+ *
+ * The command is matched whole, and it is matched by the CONFIG too - the
+ * permission map globs the raw command, because that is the only thing it
+ * can see. So this function is the flat, literal half.
+ *
+ * The guard does not stop here. It calls this on each SEGMENT, with the
+ * wrappers stripped and the payload of a `bash -c` followed, so
+ * `sudo bash -c "npm publish"` is caught as well. The two enforcers read the
+ * same list and one of them reads it more carefully; that is the price of
+ * having the list in two places.
+ *
+ * The two PIPE patterns are for the config's side only. `segments()` splits
+ * on `|`, so a segment never contains " | sh" and the guard catches a piped
+ * script through its own rule instead.
+ *
+ * @param {string} command
+ * @returns {string | null}
+ */
+export declare function deniedBy(command: string): string | null;

package/dist/effort.d.ts

@@ -0,0 +1,64 @@
+export type Profile = import("./profile.js").Profile;
+export type EffortRequest = import("./profile.js").EffortRequest;
+export type Config = {
+    agent?: Record<string, any>;
+};
+export type EffortResult = {
+    profileId: string;
+    model: string;
+    defaultVariant: string | null;
+    roles: Record<string, string | null>;
+    laneModels: Record<string, string>;
+    notes: string[];
+};
+/**
+ * @typedef {import("./profile.js").Profile} Profile
+ * @typedef {import("./profile.js").EffortRequest} EffortRequest
+ * @typedef {object} Config
+ * @property {Record<string, any>} [agent]
+ * @typedef {object} EffortResult
+ * @property {string} profileId
+ * @property {string} model
+ * @property {string|null} defaultVariant
+ * @property {Record<string, string|null>} roles
+ * @property {Record<string, string>} laneModels
+ * @property {string[]} notes
+ */
+/**
+ * The lanes a profile manages. A lane a profile does not mention is left alone.
+ *
+ * This used to be a hand-written list of nine lanes, and it drifted: the
+ * fleet has ten, and `longform` was missing. A second list of lane names is a
+ * second source of truth, and the lane table in `lanes.json` is the first one.
+ *
+ * @type {string[]}
+ */
+export declare const MANAGED_ROLES: string[];
+/**
+ * @param {string} profileId
+ * @param {{ unhealthy?: Set<string> }} [opts]
+ * @returns {EffortResult}
+ */
+export declare function planEffort(profileId: string, opts?: {
+    unhealthy?: Set<string>;
+}): EffortResult;
+/**
+ * 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-lane effort work at all.
+ *
+ * The model is only filled in when the agent does not have one. A fleet puts
+ * ten different models behind ten agents, and overwriting them with the
+ * profile's base model here would collapse the whole fleet onto one route.
+ *
+ * @param {Config} config
+ * @param {EffortResult} result
+ * @param {{ sessionModel?: string }} [opts]
+ * @returns {Config}
+ */
+export declare function applyEffort(config: Config, result: EffortResult, opts?: {
+    sessionModel?: string;
+}): Config;

package/dist/guard.d.ts

@@ -0,0 +1,23 @@
+import type { Plugin } from "./plugin.js";
+export declare const MARKER = "[opencode-harness-kit] blocked";
+/**
+ * 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 declare function pathsInPatch(text: string): string[];
+/**
+ * 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 declare function writeTargets(tool: string, args: any): string[];
+export declare const GuardPlugin: Plugin;
+export default GuardPlugin;

package/dist/health.d.ts

@@ -0,0 +1,43 @@
+export type Health = {
+    unhealthy: Record<string, {
+        at: string;
+        reason: string;
+    }>;
+    active?: string;
+};
+/**
+ * @typedef {object} Health
+ * @property {Record<string, { at: string, reason: string }>} unhealthy
+ * @property {string} [active]
+ */
+/**
+ * @param {string} dir the project root
+ * @returns {string}
+ */
+export declare function healthPath(dir: string): string;
+/**
+ * @param {string} dir the project root
+ * @returns {Health}
+ */
+export declare function readHealth(dir: string): Health;
+/**
+ * @param {string} dir the project root
+ * @param {Health} health
+ */
+export declare function writeHealth(dir: string, health: Health): void;
+/**
+ * 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 declare function unhealthyModels(dir: string): Set<string>;

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+import type { Plugin } from "./plugin.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 declare const HarnessPlugin: Plugin;
+export default HarnessPlugin;