OpenCode Harness API reference
Configure createOpenCodeHarness(), apply its option defaults, and interpret success, redaction, cleanup, and partial-run failures.
Import createOpenCodeHarness() and OpenCodeHarnessOptions from @evilkiwi/vector/evals.
function createOpenCodeHarness(options: OpenCodeHarnessOptions): Harness<string, string>;OpenCodeHarnessOptions
| Option | Type | Required | Default | Meaning |
|---|---|---|---|---|
fixture |
URL |
Yes | Committed repository directory copied into each disposable run. | |
plugin |
URL |
Yes | OpenCode-loadable entrypoint module. | |
agent |
string |
Yes | Agent selected for the session. | |
model |
OpenCode ModelRef |
Yes | Provider and model selected for the session. | |
environment |
Record<string, string> |
Yes | Environment values layered over the inherited process environment. | |
commandTimeoutMs |
number |
No | 5_000 |
Fixture Git command timeout. |
readinessTimeoutMs |
number |
No | 15_000 |
Server readiness, session execution, and evidence timeout. |
shutdownGraceMs |
number |
No | 2_000 |
Child-process shutdown grace for each signal. |
diagnosticsLimit |
number |
No | 1_048_576 |
Maximum retained characters for each process diagnostic stream. |
Every numeric option must be a positive safe integer. An invalid value throws when the OpenCode Harness is created, with the option name, attempted value, valid bound, and recovery.
createOpenCodeHarness() captures the resolved options. Each run(prompt, context) accepts one prompt and returns a standard vitest-evals HarnessRun after successful execution, complete required evidence, process shutdown, and temporary-state cleanup.
Environment and redaction
Vector starts from process.env, then applies options.environment. It redacts explicit environment values, inherited values whose names contain AUTH, CREDENTIAL, KEY, PASSWORD, SECRET, or TOKEN, and inherited OPENCODE_CONFIG_CONTENT from Vector-owned evidence.
Caller-owned artifacts remain unchanged and may contain sensitive values.
Failure contract
If execution, observation, evidence assembly, cancellation, shutdown, or cleanup fails, the returned promise rejects with an error named OpenCodeHarnessError. Vitest-evals attaches the partial HarnessRun to that error. The partial run includes sanitized Vector-owned evidence and all recorded failures available at the boundary.
Use vitest-evals’ getHarnessRunFromError() to retrieve the attachment. Treat availability markers as authoritative. Do not infer an absent or unavailable signal from nearby evidence. Conditional cost evidence is omitted unless observation is complete and every included cost is finite and authoritative.
Read Run evals for a complete Evaluation Suite example.