Skip to content

feat(runtime): OpenCode as a configurable agent runtime (Ollama / OpenRouter / OpenAI-compatible) — Refs #2981 - #4663

Merged
vybe merged 18 commits into
devfrom
feat/2981-opencode-runtime-v3
Nov 19, 2026
Merged

vybe merged 18 commits into
devfrom
feat/2981-opencode-runtime-v3

Conversation

@vybe

@vybe vybe commented Nov 19, 2026

Copy link
Copy Markdown
Contributor

Supersedes #4196. Same work, rebased onto current dev (2fa0232f6, ~213 commits ahead of the previous base a214d32ce). The old PR kept the merge-train commit; this branch has 15 replayed commits + 1 registry commit = 16 total, no merge commits.

Summary

Adds OpenCode (pinned opencode-ai@1.18.32) as the fourth agent runtime, next to Claude Code, Gemini CLI and Codex. Providers are configuration, not code:

  • Ollama at any URL
  • OpenRouter
  • any OpenAI-compatible endpoint, set with OPENCODE_PROVIDER_<ID>_* in the agent's .env, or with the platform settings openrouter_api_key and opencode_default_provider_base_url

This branch was re-cut from current dev (2fa0232), with the work re-applied onto dev's structure: #3838 stdin, file_path_policy, gemini_settings, and the #2328 max_turns change. There is no feature flag. Invariant #5 (the vendored model_context) is untouched. The link is Refs #2981: some acceptance criteria are still open (see Known gaps).

Rebase notes (onto dev 2fa0232)

Conflicts resolved at:

  1. cc761d08d (fix(ui): Add GitHub repository URL input to Create Agent modal (#255) #257) — Dockerfile: kept both sides; OpenCode install+provider pre-seed first, then dev's ent#1168 passwd -l comment above useradd. agent_server/routers/chat.py: took the PR's _model_surface() and carried dev's newer fable alias note (Sonnet 5.5/Opus 5.5/Haiku 5.5/Fable 5.2) + fable/fable[1m] accept paths into it.
  2. b9b5305aa (Session tab — --resume-default chat surface (Closes #651) #652) — src/backend/routers/chat.py: kept both imports (get_agent_runtime + dev's resolve_default_model). services/task_execution_service.py: took dev's single-resolver body (ent#1202); the PR's OpenCode platform-default step now lives in agent_model_service.resolve_default_model. Side effect: a2a row creation and /api/model "backend turn model" also report the OpenCode default for consistency.
  3. 48632c055 (feat(#411): canary invariant harness Phase 1 (S-01, E-02, L-03) #653) — agent_service/lifecycle.py: kept dev's imports + added apply_opencode_provider_env. tests/unit/test_1028_settings_package.py: kept both route-line sets.
  4. 91ce189d3 (fix: Architecture invariant — model centralization (INV-14) + doc-drift (INV-7→#1309, INV-8→#1310 split out) #654) — agent_server/routers/info.py: kept both health fields (vendor_telemetry_opt_out + _read_only_enforcement()).
  5. 684c0670b (docs) — merged agent-runtimes.md table row: PR's opencode/provider/model text + dev's Claude-Code model note.

Registry: the 9 tests/registry.d/ entries from #4196 are appended to tests/registry.json (dev's format). The directory is deleted. 812 entries, 812 unique files, JSON valid. Registry commit: 662150106.

Validation (rebased head 6621501)

  • shellcheck 0.11.0 on startup.sh: 0 findings on PR, 0 on dev ✓
  • python -m compileall on 43 changed .py files: OK ✓
  • Alembic heads: 125 revision(s), 1 head (0124_execution_continues_execution_id) ✓
  • enterprise-docs-guard: OK ✓
  • Narrow pytest (20 targeted files — the PR's 15 test files + direct importers of changed model-resolution code):
    • PR: 5 failed, 629 passed, 7 skipped, 189 warnings in 185.89s
    • dev baseline: 5 failed, 276 passed, 115 warnings in 120.94s
    • Verdict: all 5 failures pre-existing on dev (test_1028_settings_package.py AttributeError: '_IncludedRouter' object has no attribute 'path', fastapi 0.142 vs <0.116 pin). Under fastapi 0.115.14: 8 passed, 16 warnings in 0.96s ✓
  • 4 sibling-isolated files (docs(deploy): document stale-image recovery for self-hosted devs (#557) #626): 17 passed / 10 passed / 21 passed / 13 passed ✓
  • Full suite: not complete — 1 unidentified failure seen in a partial 22% run (under investigation, may be pre-existing).

What changed (by area)

  • Agent runtime (docker/base-image/agent_server)
    • opencode_runtime.py: parses --format json, uses a per-turn XDG_CONFIG_HOME, enforces read-only, honours the deny-list, caps max_turns by counting steps (422), and classifies errors (statusCode 401/403 → 503, 429 → 429).
    • Telemetry: input_tokens is the last step's input and output_tokens is the sum over steps. Tool calls are recorded as part entries.
    • Also: --command playbooks, session-tab resume, and image attachments with an honest per-provider capability: metadata.warnings plus a prepended sentence when the provider cannot receive images.
    • opencode_provider.py (provider blocks, missing-key refusal), opencode_mcp.py (.mcp.json → mcp:), agents_md_mirror.py (AGENTS.md is a per-turn copy, never a link), and runtime_names.py (the dependency-free runtime-identity module).
    • runtime_adapter, chat, info, state, result_callback and models (warnings, images) updated for the new runtime.
  • Base image: OpenCode is installed with its platform package named explicitly, and the build asserts the installed version in the same layer. Provider packages are pre-seeded under /opt/trinity/opencode, so no turn fetches from npm. The Go and OpenCode architecture is resolved at build time (arm64). startup.sh gains the OpenCode layers.
  • Backend:
    • runtimes list in main.py.
    • validate_runtime_model at create time.
    • Runtime-aware platform default (platform_default_model_opencode).
    • validate_dispatch_model(raw, runtime) accepts provider/model on /chat, /task and sessions.
    • Provider keys: openrouter_api_key is encrypted under ent#435, and the provider env is applied on create and recreate.
    • Platform prompt: tools are named with the trinity_ prefix.
    • session_turn_service: falls back when a session is not found.
  • Tests: 8 new OpenCode test files, registered in tests/registry.json, including failure paths: missing key, bad model shape, auth/rate classification, turn cap, and broken stdin handoff. test_runtime_capabilities_matrix, test_2796, test_1083 and test_1028 were extended.
  • Docs: architecture/agent-runtime.md (incl. the B1/B2 stdin + env note), requirements/runtimes.md (§14.3 schema, new §14.4), requirements/infrastructure.md, a new feature flow docs/memory/feature-flows/opencode-runtime.md (+ index row), an "OpenCode agents" section in docs/user-docs/agents/agent-runtimes.md (runtime block, OPENCODE_PROVIDER_<ID>_*, openrouter_api_key, the images switch, what the missing-key refusal looks like) and a runtime note in harness-authoring-guide.md. No unreleased-notes file exists on dev (docs/releases/<version>.md is drafted at the release cut), so the release-note line is in the body of the docs commit.
  • Tests (2): tests/unit/test_2981_opencode_platform_default.py covers get_platform_default_model(runtime=…) and _default_model_for. pytest on that file + test_lilu257_opencode_runtime.py: 119 passed, 7 skipped, 16 warnings in 2.57s (the 7 skips = pinned binary absent).

Not carried from the lab fork: template.yaml runtime.env. The runtime does not need it, because provider configuration is read from the agent's .env.

Evidence from the Lilu instance

These are Lilu's measurements, quoted as given:

  • /self-diagnostic ran as --command → execution sHr-5ZVULsNBDntUTBIKAw 200 SELFDIAG-OK args=["alpha beta"]
  • unknown /nosuchcmd → g7ueVMuhjtNyOeFxuCRNg failed in 450 ms, no model spawned
  • session resume I-BXa7DBus4-YX4Nz0Wheg → FxJaf8lvgBophfTcthxtog answered PELICAN in the same ses_e64fa4eeeffeboee31drH4hfaC
  • telemetry lilu659proof01 on ollama/gemma4:12b: input_tokens 50730 = the last step, output_tokens 1125 = sum, cost_usd 0.0, bash ×3 with real ids
  • images lilu660default01: metadata.warnings non-empty + prepended sentence when the provider cannot receive images
  • lilu660switch01 with OPENCODE_PROVIDER_OLLAMA_IMAGES=true: gemma4:12b described the PNG
  • openrouter/nvidia/nemotron-3.5-super-vl:free described it in 11 s
  • the missing-key refusal: openrouter/anthropic/claude-sonnet-5 with no key → named 400 refusal in 1.03 s, never a silent fallback

The stdin handoff and the env-delivered share/permission settings (B1/B2) were added after these measurements. They are unit-tested only and have not run against the live binary.

Known gaps

  • The backend chat proxy flattens 4xx to 503 (Abilityai/lilu#657).
  • The backend task proxy drops max_turns for every runtime (bug: agent base image Dockerfile hard-depends on ppa:deadsnakes/ppa — intermittent unavailability blocks critical fix deployment for days #658).
  • The ollama images default is env-only; there is no auto-detect from GET /api/show.
  • DISPATCH_ASYNC is off by default, which gates the 202 path.
  • A pre-existing flaky _install_fake_subprocess test helper.
  • The base image has not been built from this branch. CI does not build it; please build it on x86_64 before merge.
  • Workspace turns ignore the OpenCode platform default: client_portal/service.py::resolve_turn_model returns None for every non-Claude agent and never reads platform_default_model_opencode, so a Workspace turn on an OpenCode agent runs on the agent's own model while a task, schedule or chat turn uses the OpenCode default. Found while porting the tests; not changed here.
  • Two of the lab fork's #652 tests were not ported — they exercise resolve_effective_model_with_source and _resolve_chat_default_model, which exist only on the fork.
  • 1 failure in a partial broad run (22% of the full suite): the test name was not captured before the run was killed. Likely pre-existing — the narrow 20-file targeted set passed 629 with only the 5 known fastapi failures. Under investigation.
  • Full pytest tests/unit on the rebased branch: narrow set 5 failed, 629 passed, 7 skipped (5 pre-existing). Full suite pending.
  • Open OpenCode runtime MVP — a fourth runtime: value that runs an unmodified Trinity agent on a non-Anthropic model #2981 acceptance criteria, still live-only: a chat turn and a scheduled turn on an open-weight model, a Replicate custom provider end to end, a real /verify-local, and the fidelity-ablation doc.

How to test

  1. pytest tests/unit/test_2981_opencode_platform_default.py tests/unit/test_lilu257_*.py tests/unit/test_lilu263_base_image_arch.py tests/unit/test_lilu627_agents_md_mirror.py tests/unit/test_lilu659_opencode_part_and_images.py tests/unit/test_runtime_capabilities_matrix.py tests/unit/test_codex_runtime.py tests/unit/test_2796_dispatch_model_validation.py. The tests that need the binary skip when it is absent.
  2. Build the base image. The build fails if opencode --version does not report 1.18.32.
  3. Create an agent with runtime: {type: opencode, model: ollama/<model>} and OPENCODE_PROVIDER_OLLAMA_BASE_URL in its .env. Chat with it, run a /task, then resume from the Sessions tab.
  4. Set openrouter/<model> with no key: expect a named 400.

Reviewer note on scope (trinity-pm)

This is 58 files (52 code/test files plus 6 from the docs and test-port commits), which is about at the ~50-file guideline. trinity-pm suggested splitting the model-sources half (provider-as-configuration, platform settings and the dispatch gate) into a follow-up PR. It is kept here because the operator ruling names providers-as-configuration as part of this deliverable. It is a clean split point if reviewers prefer.

Small changes that touch the existing runtimes:

  • Codex: /api/model now accepts any gpt-* id; Codex refreshes AGENTS.md on every turn.
  • Agent-side /api/model is now validated per runtime.
  • info now reports the Claude version.
  • The async-dispatch check is case-insensitive.

B1–B5 (review of #3888)

Status Where
B1 workspace config overrides read-only/share Partly addressed Every spawn sets OPENCODE_DISABLE_SHARE=1. Read-only also passes the deny set as OPENCODE_PERMISSION, which is applied after every config file. Open: per-agent agent.<name>.permission rules in the workspace .opencode/ still come after it, and rules are evaluated last-match-wins. Fixing that needs verification against the real binary.
B2 prompt via argv > 128 KiB Addressed The prompt goes on stdin (#3838 shape), -- is kept, and a failed handoff kills the child and unregisters it. Tests: 200 KiB prompt, broken pipe.
B3 auth 500→503 Addressed classify_opencode_failure reads error.data.statusCode (401/403 → 503, 429 → 429). The real captured stream lines are not yet in the fixtures.
B4 dispatch gate refuses provider/model Addressed validate_dispatch_model(raw, runtime) on /chat, /task and sessions; tests in test_2796.
B5 "Fixes" while ACs open, base image unbuilt Addressed (wording) / open (build) Refs #2981 only. The base-image build and the live ACs are listed under Known gaps.

🤖 Generated with Claude Code

vybe and others added 16 commits November 19, 2026 14:12
… + platform prompt) (Abilityai/lilu#257)

Issue: Abilityai/lilu#257
(cherry picked from commit 3f1910b0927f0926fec56e94554aa20fa6194582)
…bilityai/lilu#263)

Both x86-only pins are now resolved from `uname -m` and asserted in the same RUN layer.

- Go: `go1.23.4.linux-amd64.tar.gz` was hardcoded and on arm64 downloaded and untarred SILENTLY (641 s to install a toolchain that cannot execute). Now `linux-${goarch}` with an in-layer `go version` assertion against the resolved arch.
- OpenCode: `opencode-linux-x64@${OPENCODE_VERSION}` is a direct npm target, so arm64 refused it loudly (EBADPLATFORM). The explicit platform-package naming from #257 survives; only the NAME resolves.
- Unmapped architectures fail loudly rather than defaulting.
- `uname -m` over `TARGETARCH`: all three docker build call sites use the classic builder, where TARGETARCH expands empty.

Tests: tests/unit/test_lilu263_base_image_arch.py, 12 passed; all 12 A/B-verified to fail against the pre-fix Dockerfile at 3f1910b0. Registered in tests/registry.d/.


Refs: Abilityai/lilu#263, blocks Abilityai/lilu#257 done-when 7

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
(cherry picked from commit 7932ee8e545ce078fac3c4549a84bec7074423db)
…bilityai/lilu#272)

Squash of fix/272-ollama-gateway-default (9481a464) onto lilu.



Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
(cherry picked from commit bd29f16adb74005b13c80aa800da69d21a13b717)
…t links (Abilityai/lilu#627)

ent#819 forbids the platform creating links in an agent home, and its
guard is a tree-wide text scan. Per the Lilu decision on #627:

- AGENTS.md: startup.sh restores upstream's cp, and Codex and OpenCode
  refresh the copy at every turn (agents_md_mirror.py). A sha256
  provenance record under AGENT_TMPDIR tells our copy from an authored
  file. Our copy or a missing file is refreshed, an authored file never
  is, and a leftover lilu#257 symlink is replaced by a copy.
- node_modules (+ package.json, package-lock.json, auth.json): copied
  into the per-turn config dir and at boot, option (a). Measured on an
  equivalent seed (the Dockerfile's npm install): 21 MB, copytree median
  493 ms over 5 runs. Both are under the 2 s / 300 MB limits.

Zero link calls are left in src/backend and docker/base-image, and
test_ent819 passes unedited at 13/13.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
(cherry picked from commit 39a9b0f0ca3c29aad2cf8907e6b73e44ea6f4f33)
Abilityai/lilu#651, Abilityai/lilu#649)

Issue: Abilityai/lilu#651 (child of #650)
(cherry picked from commit 9243aab4e1488501690c58e3362148760105e927)
…lt + provider/model dispatch gate (Abilityai/lilu#652)

Issue: Abilityai/lilu#652

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
(cherry picked from commit 6c6ff96a50a94b88ab90bc73c684ca4a6be2234f)
…OpenAI-compatible (Abilityai/lilu#653)

Issue: Abilityai/lilu#653
(cherry picked from commit cd771c553bddf05497a67da633a5142832c5906f)
…_turns 422, error classification parity (Abilityai/lilu#654)

Issue: Abilityai/lilu#654
(cherry picked from commit a3e65ee27356be9a1a33433c685ad7816ff3a07a)
…ast-step input tokens, images (Abilityai/lilu#655)

Squash of Abilityai/lilu-trinity#22 (head 33656c629, 2 commits on a3e65ee27). 568 passed, 7 skipped (pinned-binary tests) in 116.39s. Declared partial: three behaviours unchecked against the real 1.18.32 binary (--command with no args and no message; unknown --session id text; -f combined with --command) - proven on the DGX after redeploy. execution_classification.py and model_context.py deliberately unchanged. Landed by lilu tick 10, execution 1mYMdV7SQwzMPPaVEO8zGg.

(cherry picked from commit 310e532b116d25b7171a40caafbe454afe6c1883)
…(lilu#660) (lilu-trinity#23)

* fix(opencode): read step/tool payload under part on 1.18.32 (Abilityai/lilu#659)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat(opencode): per-provider images capability, never a silent text-only turn (Abilityai/lilu#660)

OPENCODE_PROVIDER_<ID>_IMAGES (default off for ollama / URL-declared
OpenAI-compatible, on for openrouter/anthropic/openai), surfaced as
capabilities().image_input. When true, the provider block declares
modalities {input: [text, image]} - the field the pinned 1.18.32 binary
gates image parts on. When false, the image is not passed, the model is
told, and the turn returns a metadata warning plus a prepended sentence.
Also: fixture tests for the #659 part-nesting fix.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Trinity Agent (lilu-engineer) <trinity-agent@ability.ai>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
(cherry picked from commit 2bfbadeb54589c7a83958088d0ac50d223dfcea3)
- helpers.py: import re (validate_runtime_model's pattern; the fork got it
  from an unrelated validator dev does not have)
- task_execution_service._default_model_for: OpenCode resolves its own
  platform default (platform_default_model_opencode); other non-Claude
  runtimes keep None. Replaces the fork-only resolution helper.
- opencode_runtime headless model: per-call > AGENT_RUNTIME_MODEL > runtime
  default, inline (the fork-only resolve_runtime_model_with_source is not on dev)
- provider configuration is read from the agent's .env over the container
  baseline; template.yaml runtime.env is a fork-only feature and is not
  carried, so docs/messages/tests no longer claim it

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…read-only deny via env (Refs #2981)

- The message is written to stdin and stdin is closed; '--' is kept and the
  prompt is never an argv element, so a >128 KiB message no longer makes
  Popen raise E2BIG. A failed handoff ends the child and unregisters it.
- OPENCODE_DISABLE_SHARE=1 on every spawn, and in read-only mode the deny set
  as OPENCODE_PERMISSION, both applied after every config file, so a
  workspace opencode.json can no longer re-enable share or edit/bash.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…2981

- feature-flows/opencode-runtime.md + its feature-flows.md index row
- user-docs/agents/agent-runtimes.md: creating an OpenCode agent (runtime
  block, OPENCODE_PROVIDER_<ID>_* env, the openrouter_api_key platform
  setting, the images switch, the missing-key refusal verbatim)
- harness-authoring-guide.md: the OpenCode runtime note (env-delivered
  controls, prompt on stdin)
- architecture/agent-runtime.md + requirements/runtimes.md §14.4: the stdin
  and env-delivered share/permission (B1/B2) behaviour

Release note: dev keeps release notes only per cut (docs/releases/<version>.md,
drafted by /release from the commits since the last tag); there is no
unreleased-notes file, so the line rides here for the next cut:
- **OpenCode runtime** (#2981): a fourth agent runtime, `runtime: {type:
  opencode, model: provider/model}`, running OpenRouter, a local Ollama or any
  OpenAI-compatible endpoint; needs a base-image rebuild and agent recreate.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Ports the Abilityai/lilu#652 platform-default tests onto dev's surface:
settings_service.get_platform_default_model(runtime="opencode") and
task_execution_service._default_model_for. The fork-only resolver tests
(resolve_effective_model_with_source, the chat-payload resolver) are not
carried; those functions do not exist on dev.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…inment guard (#4196) — mechanical, per the merge-train note on the PR

- test_926: the shipped runtime set now carries opencode (main.py runtimes list)
- test_agent_readiness_probe: stub apply_opencode_provider_env, lifecycle.py's new import
- test_lilu20 TestScopeFence: the #263 Go-arch comment quoted the lilu#20 note's
  exact phrase, so text.index landed on the wrong note — reworded the quote
- startup.sh: SC2015 (A && B && cp || true) on the package.json copy, flagged by
  CI's shellcheck — an explicit if
- opencode_runtime: _ensure_within realpath containment at the turns root (the
  Codex #1187 precedent); _safe_token already leaves nothing traversable, this
  is the normalise-then-startswith shape CodeQL's py/path-injection recognises
  (11 alerts on turn_dir-derived paths), with a direct guard test

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…on (#4196)

Upstream dev has no tests/registry.d/ — tests/registry.json is the single
registry. The 9 per-file entries this PR added under tests/registry.d/ are
appended to registry.json's test_files in dev's format (same keys and key
order, 2-space indent) and the directory is removed. 812 entries, 812
unique files, JSON re-validated.

Refs Abilityai/lilu#656

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@vybe vybe added the status-needs-fix PR has an unaddressed review/validation finding; cleared by the author's next push (#2815) label Nov 19, 2026
@github-actions

Copy link
Copy Markdown

⚠️ Nightly unit-suite check skipped — merge conflict against dev.

Resolve by running git merge dev locally and pushing the result. The next nightly run will re-test once the conflict is gone.

…v fallbacks (Refs #2981)

- opencode_runtime: 504/500 answers carry fixed words plus the exception
  class name; the exception text goes to the log (#4284).
- base image: the provider pre-seed installs with npm ci from a tracked
  lockfile in docker/base-image/opencode-providers (#4435).
- OPENROUTER_API_KEY and OPENCODE_DEFAULT_PROVIDER_BASE_URL are passed to the
  backend in all three compose files and documented in .env.example, so the
  env fallback the settings code reads is reachable on deploy.
- Example Ollama URL in a docstring and test fixture is a placeholder host.

Base image built from this commit on arm64: opencode --version reports 1.18.32.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@vybe vybe added the ui PR touches the frontend UI — triggers Playwright e2e tests label Nov 19, 2026
@github-actions github-actions Bot removed the status-needs-fix PR has an unaddressed review/validation finding; cleared by the author's next push (#2815) label Nov 19, 2026
@vybe
vybe marked this pull request as ready for review November 19, 2026 18:37

@trinity-ability trinity-ability left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Validated at f76dc2d: Tier 1 green incl. regression diff, journey-smoke and frontend-e2e green on the PR, base image built on arm64 and x86_64 (opencode 1.18.32).

@vybe
vybe merged commit 9edb0e1 into dev Nov 19, 2026
27 checks passed
@github-actions

Copy link
Copy Markdown

⚠️ Live-instance suite skipped — merge conflict against dev.

Resolve by merging dev locally and pushing the result; the next nightly re-tests.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ui PR touches the frontend UI — triggers Playwright e2e tests

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants