feat: add OpenCode as a preset agent

[RAIT-09]

Description

PR4 of the preset-agents overhaul (#348–#351 shipped the registry, enable/disable, collapsible settings, and the "Preset agents" naming): OpenCode becomes a preset agent, and the custom-agent recipe our docs used to carry for it migrates automatically.

Registry entry (feat(agents)): one PRESET_AGENTS entry — command opencode, args ["acp"], install hint curl -fsSL https://opencode.ai/install | bash (npm on native Windows). Settings storage, enumeration, and the settings UI are all registry-driven, so no per-agent code exists elsewhere. OpenCode has no API key wiring: authentication is CLI-managed (run /connect in the OpenCode TUI; credentials live in ~/.local/share/opencode/auth.json and are read by the opencode acp process we spawn). There is no official OPENCODE_API_KEY, and OpenCode is multi-provider, so a single env var would be wrong — verified against opencode.ai/docs on 2026-07-16.

Absorption migration (feat(settings)): these docs historically advised registering OpenCode as a custom agent with id opencode. Without migration, the existing load-time collision rename would move that custom to opencode-2 while fence pins, saved sessions, and defaultAgentId silently retarget a fresh default preset. Instead, a new registry declaration (absorbsCustomAgentId) lets the pure absorbCustomAgents helper adopt the custom's settings (command/args/env/displayName/enabled) as the preset's raw source before custom normalization runs, remove the leftover custom, notify once, and persist — the saved preset entry makes the migration run-once. Deliberately not a generic custom.id == presetId rule: customs colliding with the original four preset ids are dead weight under preset-first resolution and must not overwrite live preset settings. Kiro (PR5) will reuse the same mechanism with a one-line declaration.

Docs (docs(opencode)): new setup page (install, /connect authentication, migration note), sidebar entry, and the full enumeration sweep (index/quick-start tables, FAQ, troubleshooting, ACP support, context files — AGENTS.md with CLAUDE.md fallback — READMEs, agents lists). The custom-agents page keeps Qwen Code and Kiro as examples and points OpenCode to the preset page.

Tests: 188 passing (6 new absorption tests: adoption, skip-when-present, no-op, original-ids-excluded, save-round-trip idempotency, args backfill). An adversarial multi-lens review ran post-implementation; the two doc leftovers it found are fixed in this PR, and the accepted low-severity limitation (downgrade/re-upgrade chain around the one-shot migration) is recorded in the plan document.

Related issue

None (part of the preset overhaul plan; PR5 = Kiro follows).

Type of change

• Bug fix
• New feature
• Documentation
• Refactor
• Other

Checklist

• npm run lint passes ("Use sentence case for UI text" warnings are acceptable for brand names)
• npm run build passes
• Tested in Obsidian
• Existing functionality still works
• Documentation updated if needed

Testing environment

• Agent: OpenCode (real environment). Verified: preset appears with install hint and no API key row; spawns via opencode acp and chats; hand-crafted data.json migration (custom opencode absorbed with displayName/env preserved, Notice shown exactly once, no re-fire on reload); agent: opencode pins and saved sessions keep resolving after migration; preset-entry-present + custom collision falls to the existing opencode-2 rename; existing four presets, custom agents, default-agent selection, and agent switching unaffected
• OS: macOS

Screenshots

N/A

Summary by CodeRabbit

• New Features
  • Added OpenCode as a built-in supported agent, including install, authentication, and verification in the agent flow.
  • Added automatic migration when an existing “OpenCode” custom-agent configuration is detected, moving it to the OpenCode preset.
• Documentation
  • Updated setup guides, Quick Start, FAQs, troubleshooting, context-file support, and ACP support docs to include OpenCode.
• Tests
  • Added/updated coverage for OpenCode availability and the custom→preset migration behavior.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 5c534c9e-28a6-49a3-9c26-37b66bbb6346

📥 Commits

Reviewing files that changed from the base of the PR and between 6c2f982 and 21a7f19.

📒 Files selected for processing (1)

• docs/agent-setup/opencode.md

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/agent-setup/opencode.md

---

📝 Walkthrough

Walkthrough

OpenCode is registered as a built-in preset, with migration from matching custom-agent settings during settings loading. English and Japanese documentation now describe installation, authentication, verification, navigation, and OpenCode support.

Changes

OpenCode preset support

Layer / File(s)	Summary
Preset definition and custom absorption src/services/preset-agents.ts, src/services/settings-normalizer.ts, test/settings-normalizer.test.ts	Adds the OpenCode preset, custom-agent absorption metadata, migration logic, and coverage for adoption, skipping, idempotency, and normalization.
Settings loading and agent enumeration src/plugin.ts, test/session-helpers.test.ts	Applies migration during settings loading, emits notices, persists absorbed settings, and updates agent enumeration expectations.
OpenCode setup documentation docs/.vitepress/config.mts, docs/agent-setup/*, docs/getting-started/quick-start.md	Adds navigation and setup instructions covering installation, command paths, CLI authentication, verification, and custom-agent migration.
OpenCode support references AGENTS.md, README.md, README.ja.md, docs/help/*, docs/index.md, docs/reference/*, docs/usage/context-files.md	Adds OpenCode to supported-agent lists, ACP references, FAQs, troubleshooting, context-file guidance, and project descriptions.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant AgentClient
  participant OpenCode
  participant Settings
  User->>AgentClient: Select OpenCode
  AgentClient->>Settings: Load preset configuration
  AgentClient->>OpenCode: Start opencode acp
  OpenCode-->>AgentClient: ACP connection
  User->>OpenCode: Authenticate with /connect

Loading

Possibly related PRs

• RAIT-09/obsidian-agent-client#348: Introduced the preset-agent registry architecture extended here for OpenCode and custom-agent absorption.

Poem

I’m a bunny hopping through the preset train,
OpenCode joins the agents’ refrain.
/connect finds credentials bright,
ACP carries chats through the night.
Custom paths become presets anew—
A carrot-sized migration, neat and true! 🐇

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the primary change: adding OpenCode as a preset agent.
Description check	✅ Passed	The description follows the required template and includes the main sections, checklist, testing environment, and screenshots.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/opencode-preset

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}