# Compatibility

SEED-agent is an OpenCode plugin, so compatibility has two layers:

| Runtime | Requirement |
| --- | --- |
| OS | Linux only for the current npm release |
| Node.js | `>=20` |
| OpenCode CLI | `>=1.15.6` |
| Tested OpenCode CLI | `1.15.7` |
| Plugin SDK dependency | `@opencode-ai/plugin@1.15.6` |

`package.json` records the supported OS plus Node and OpenCode requirements, and
`package-lock.json` pins the plugin SDK dependency. Because the OpenCode CLI is
installed outside this package, the enforceable runtime gate is:

```bash
node ./bin/seed-agent.js doctor --project --agents
```

`doctor` fails when the installed OpenCode CLI is older than the supported
minimum. It also checks that the plugin is registered, SEED config exists,
provider availability is visible, Lab-Representative is available as the SEED
primary face, and legacy/native primary faces are not leaking into the isolated
project install.

## Update Policy

When OpenCode is updated, rerun:

```bash
opencode --version
npm run verify
npm run eval
npm run canary:package
npm run verify:cleanroom
node ./bin/seed-agent.js doctor --project --agents
node ./bin/seed-agent.js run --model anthropic/claude-sonnet-4-5 --variant high "Run a compact SEED compatibility smoke test and report the run directory."
```

If OpenCode changed plugin hooks, agent config shape, command behavior, MCP
config, or session SDK behavior, patch this repository, update this document's
tested version, and push a new lab release.

For lab onboarding, tell users to treat `doctor` as the preflight check before
opening OpenCode for SEED work.

## Eval Verification

Use eval verification when changing the harness contracts that users rely on:

```bash
npm run eval
```

The eval runner loads `evals/seed-harness.eval.json` and executes deterministic
checks against the built `dist/` output. Current cases cover package-mode
project install behavior, evidence-backed report completion with telemetry and
artifact indexing, representative briefings, an inline-spec document/PDF
black-box fixture, Lab Meeting feedback, workspace state, document extraction,
and safety policy blocking for local path leakage. The document/PDF fixture is
one example of the generic dynamic-team path, not a built-in product lane.
`npm run verify` includes these evals through `eval:dist`.

## Clean-Room Source Verification

Use clean-room source verification when developing on a machine that has
personal OpenCode config, Codex/agent skills, local MCP credentials, or provider
environment variables. This checks a tracked source checkout in isolation; it is
not a replacement for package-consumption canary verification.

```bash
npm run verify:cleanroom
```

This script creates a temporary local Git clone of the tracked repository,
sets `HOME`, `XDG_CONFIG_HOME`, `XDG_DATA_HOME`, and `XDG_CACHE_HOME` to an empty
temporary directory, unsets optional MCP/provider environment variables, runs
`npm ci`, `npm run verify`, project-local install, resolves OpenCode's final
config, and checks that `/seed` and the SEED primary face are registered
without native Build/Plan leaks.
The OpenCode resolved-config step allows up to 600 seconds by default because a
brand-new OpenCode HOME can run database migrations and refresh its external
model catalog. Override that with `SEED_CLEANROOM_OPENCODE_TIMEOUT=<seconds>`.
Set `SEED_CLEANROOM_AGENT_LIST=1` to additionally run `opencode agent list`;
that command can be slower on a first OpenCode boot for the same reason.

The goal is to approximate what a maintainer sees after cloning the repository
for source development: no user-level SEED config, no private skills, no
personal MCP overrides, and no provider key unless explicitly supplied. Set
`SEED_CLEANROOM_KEEP=1` to preserve the temporary directory for inspection. Set
`SEED_CLEANROOM_KEEP_PROVIDER_KEYS=1` only when intentionally testing with
provider environment variables.

## Package Canary

Use package canary verification before publishing or handing a tarball to a lab
member. This is the closest local check for the external-user npm installation
UX.

```bash
npm run canary:package
```

This script builds the npm package with `npm pack`, installs the produced
tarball into an empty consumer project with an isolated HOME, checks that the
packed file surface includes runtime files and excludes private maintainer docs,
imports the package entrypoint, runs `seed-agent install --project` from the
installed package, and resolves OpenCode config when the OpenCode CLI is
available. Set `SEED_PACKAGE_CANARY_KEEP=1` to preserve the temporary directory
for inspection.
