add-opencode

# OpenCode agent provider

NanoClaw runs agents in a long-lived **poll loop** inside the container. The backend is selected per agent group by the **`provider`** key in that group's `container.json` (materialized from the `container_configs` table) — set it with `ncl groups config update --provider opencode`. Default is `claude`.

Trunk ships with only the `claude` provider baked in. This skill copies the OpenCode provider files in from the `providers` branch, wires them into the host and container barrels, installs dependencies, and rebuilds the image.

## Install

### 1. Copy the provider payload

Fetch the `providers` branch from the configured remote that carries it, then
overwrite every skill-owned provider file with its canonical registry copy:

```nc:copy from-branch:providers
src/providers/opencode.ts
src/providers/opencode-registration.test.ts
container/agent-runner/src/providers/opencode.ts
container/agent-runner/src/providers/mcp-to-opencode.ts
container/agent-runner/src/providers/mcp-to-opencode.test.ts
container/agent-runner/src/providers/opencode-registration.test.ts
container/agent-runner/src/providers/opencode.attachments.test.ts
container/agent-runner/src/providers/opencode.compaction.test.ts
container/agent-runner/src/providers/opencode.config.test.ts
container/agent-runner/src/providers/opencode.factory.test.ts
container/agent-runner/src/providers/opencode.memory.test.ts
container/agent-runner/src/providers/opencode.question.test.ts
```

(`cwd-shim.ts` and its test are deliberately **not** in this payload even though `mcp-to-opencode.ts` imports the shim: trunk ships and owns them — the default provider imports `cwd-shim.ts` — and every path listed here becomes a skill-owned file that removal deletes.)

### 2. Register the provider in both runtimes

Each barrel gets one line appended at the end — skip if the line is already present.

```nc:append to:src/providers/index.ts
import './opencode.js';
```

```nc:append to:container/agent-runner/src/providers/index.ts
import './opencode.js';
```

### 3. Install the matched SDK and CLI pins

The agent-runner is a separate Bun package tree. Keep its SDK on the same exact
version as the globally installed `opencode-ai` CLI:

```nc:dep manager:bun cwd:container/agent-runner
@opencode-ai/sdk@1.4.17
```

```nc:json-merge into:container/cli-tools.json key:name
{
  "name": "opencode-ai",
  "version": "1.4.17"
}
```

Do not use `latest`. OpenCode's CLI and SDK have changed their session API in
lockstep before; mismatched versions can build cleanly and fail at runtime.

### 4. Install the pin guard

Copy the structural test that asserts the CLI manifest and SDK package stay on
the same exact version:

```nc:copy
opencode-cli-tools.test.ts -> src/opencode-cli-tools.test.ts
```

### 5. Build and validate

```nc:run effect:build
pnpm run build
```

```nc:run effect:build
pnpm exec tsc -p container/agent-runner/tsconfig.json --noEmit
```

```nc:run effect:test
pnpm exec vitest run src/providers/opencode-registration.test.ts src/opencode-cli-tools.test.ts
```

```nc:run effect:test
cd container/agent-runner && bun test src/providers/opencode-registration.test.ts
```

```nc:run effect:build
./container/build.sh
```

All checks must be clean before proceeding. The registration tests import the
real host and container barrels; the pin guard covers the non-importable global
CLI; the two typechecks cover both runtime API boundaries.

NanoClaw v2 mounts one shared read-only agent-runner source tree. There are no
per-group source overlays to propagate or repair.

## Configuration

### Host `.env` (typical)

Set model/provider strings in the form OpenCode expects (often `provider/model-id`). **Put comments on their own lines** — a `#` inside a value is kept verbatim and breaks model IDs.

These variables are read **on the host** and passed into the container only when the effective provider is `opencode`. They do not switch the provider by themselves; the group still needs `provider` set to `opencode` (see [Select the provider](#select-the-provider) below).

- `OPENCODE_PROVIDER` — OpenCode provider id, e.g. `openrouter`, `anthropic`, `deepseek`.
- `OPENCODE_MODEL` — full model id in `provider/model` form, e.g. `deepseek/deepseek-chat`.
- `OPENCODE_SMALL_MODEL` — optional second model for lighter tasks; defaults to `OPENCODE_MODEL` if unset.
- `ANTHROPIC_BASE_URL` — **required for non-`anthropic` providers.** The opencode container provider passes this as the `baseURL` for the upstream provider config so requests route through OneCLI's credential proxy or directly to the provider's API. Set it to the provider's API base URL (e.g. `https://api.deepseek.com/v1`, `https://openrouter.ai/api/v1`).
- `OPENCODE_MODEL_CONTEXT_LIMIT` — optional context window, in tokens, declared for **`OPENCODE_MODEL` only** (not the small model); OpenCode auto-compacts as a session approaches it, and a model its registry does not know resolves to `0` and so never compacts. Anything but a positive integer is logged and treated as unset, which emits no limit and leaves behavior unchanged.
- `OPENCODE_MODEL_OUTPUT_LIMIT` — optional max output tokens for the same main model, only applied alongside a valid context limit (without one it is logged and ignored). Anything but a positive integer is logged and treated as unset.
- `OPENCODE_MODEL_INPUT_MODALITIES` — optional comma-separated subset of `text,audio,image,video,pdf`, declared for **`OPENCODE_MODEL` only**. OpenCode drops any file part whose modality the model does not declare, so images and PDFs never reach a registry-unknown custom model unless this is set. Unrecognized entries are logged and skipped; unset declares nothing and leaves behavior unchanged. A distinct `OPENCODE_SMALL_MODEL` never inherits this; it keeps the undeclared-model default regardless.

  Declaring the modality only opens OpenCode's gate. NanoClaw must also pass channel attachments to the provider as structured file parts; until that support is av