feat: OpenCode integration

[happy-v587]

Feature description

Add an official OpenCode integration that gives each user turn automatic, project-scoped recall from PowerContext and exposes curated Memory and work-continuity tools.

The integration should align with the core behavior of the DeepSeek Harness plugin while using OpenCode's native plugin, tool, permission, and Skill surfaces. Runtime, Memory selection, ranking, citations, rendering, and persistence remain owned by the PowerContext Server.

Expected user flow:

powercontext setup opencode --source oceanbase/powercontext --ref master
powercontext server run
opencode

Installation can be checked independently from Server health:

powercontext doctor opencode
powercontext doctor

Problem and proposed solution

PowerContext supports several coding-agent hosts, but OpenCode users currently need to call HTTP/MCP manually and cannot receive relevant project context automatically before a model request. MCP tools alone are insufficient because an agent cannot reliably search for context it does not yet know exists.

The proposed solution is a self-contained TypeScript package under integrations/opencode/plugins/powercontext, targeting OpenCode >=1.18.21 <2.

Automatic recall and prompt capture

Map one OpenCode turn to the existing HTTP contract:

chat.message
  -> extract non-synthetic user text
  -> derive the project scope
  -> POST /v1/context/prepare
  -> validate powercontext.prepared-context.v1
  -> independently POST /v1/sources/content

experimental.chat.messages.transform
  -> inject the prepared value before model dispatch
  -> label it as untrusted historical evidence
  -> deduplicate it across tool-loop model steps

Recall, capture, and optional flush must fail independently. An unavailable or incompatible Server must never block normal OpenCode work. Prepared content is transient model context and must not be persisted into the OpenCode transcript.

Scope mapping

Resolve scope in this order:

1. POWERCONTEXT_OPENCODE_SCOPE_ID;
2. normalized git:<host>/<path> from remote.origin.url;
3. local:<sha256> of the resolved worktree path.

This keeps OpenCode compatible with project Memory created through Codex, Claude Code, DeepSeek Harness, and Pi.

Tools and permissions

Expose curated pc_* tools for:

• Memory search and lifecycle operations;
• bounded context preparation and explicit Source capture;
• Handoff preparation and continuation;
• Experience and Skill generation/read operations;
• read-only Artifact Candidate review.

Generate operation routing from openapi/powercontext.yaml. Durable mutations must use OpenCode's permission prompt. Candidate approval/rejection and destructive or administrative operations remain explicit human CLI or Dashboard actions.

Skill, configuration, and security

Install an OpenCode-native project-context Skill in the resolved global config directory. Setup may replace only an existing Skill carrying a PowerContext ownership manifest; a user-owned same-name path must remain untouched.

Use the POWERCONTEXT_OPENCODE_ prefix for:

BASE_URL
AUTHORIZATION
SCOPE_ID
CAPTURE_PROMPTS
FLUSH_ON_CAPTURE
REQUEST_TIMEOUT_MS
HTTP_BUDGET_MS
MAX_BYTES
FLUSH_MAX_CALLS

The integration must reject unsafe Server URLs, redirects, oversized or invalid responses, and secret-shaped captured or durable content. Authorization comes only from the environment and must not appear in metadata or diagnostics.

Installation and diagnosis

Add powercontext setup opencode and powercontext doctor opencode.

Setup validates the OpenCode version and checked-in bundle, registers the plugin globally, and installs the owned Skill with backup-and-replace recovery. Doctor reports the OpenCode executable, configured plugin, and installed Skill independently.

The plugin does not start or embed the Server and does not modify the PowerContext HTTP API or persisted formats.

Alternatives considered

1. Use MCP only. This exposes model-initiated tools but cannot guarantee automatic recall before the first model request.
2. Target the OpenCode v2 plugin API. Its context hook is a closer semantic match, but v2 is currently beta and would narrow compatibility. The initial release uses the OpenCode 1.x plugin API.
3. Persist recalled context through chat.message. This is simpler but would pollute the transcript. The selected design caches recall per turn and injects it transiently through experimental.chat.messages.transform.
4. Implement a DSH-style direct /pc command. OpenCode 1.x server plugins cannot reliably return a local command result without invoking the model, so diagnosis and review remain CLI/Dashboard operations.
5. Extract a shared JavaScript integration runtime first. DSH, Pi, and OpenCode have different host contracts. Self-contained packages with shared contract tests avoid coupling installation to another integration's source tree.

Additional context

• Tracking issue: Tracking Issue: Agent Integrations for PowerContext #1213
• Implementation PR: feat(opencode): add PowerContext integration #1329
• The OpenCode v1 pre-dispatch path depends on experimental.chat.messages.transform; compatibility must be protected by tests against the supported OpenCode version.

Are you willing to contribute to this feature?

• Yes, I am willing to contribute code, docs, or design feedback.