sandbox-agent/research/specs/opencode-adapter-package-plan.md

Plan: OpenCode Adapter Package + ACP Journal Persistence

Decisions Locked

• Move OpenCode support into its own Rust package: yes.
• Re-enable /opencode/* only after tests pass: yes.
• Persist ACP-side representation like the TypeScript SDK; convert to OpenCode response/event shapes at runtime: yes.
• Use sqlx + SQLite with WAL + migrations: yes.
• Session restoration strategy should be lazy (TS SDK-style): yes.
• Validation target is parity with current OpenCode compat suite, plus ACP-protocol gaps not currently covered: yes.
• Docs/behavior must clearly state: auto-restore handles runtime/session loss, but cannot recover if persistence storage is wiped: yes.

Context

Current OpenCode compatibility logic lives in a large monolith (server/packages/sandbox-agent/src/opencode_compat.rs) and session bridge (server/packages/sandbox-agent/src/opencode_session_manager.rs). In the active ACP-v1 baseline, /opencode/* is disabled/unmounted and sandbox-agent opencode is disabled.

The TypeScript SDK already defines a stable persistence+restore model:

• Persist SessionRecord + envelope SessionEvent journal.
• Recreate stale sessions lazily.
• Inject replay context on the next prompt.

This plan ports that model into the Rust OpenCode adapter runtime.

Goals

• Extract OpenCode compatibility into a dedicated package with clean boundaries.
• Rebuild session tracking/restore using a persisted ACP journal via SQLite (sqlx).
• Keep OpenCode-specific JSON shapes as runtime projections derived from persisted ACP records.
• Re-enable /opencode/* when parity tests + new ACP coverage pass.

Non-Goals

• Full redesign of all OpenCode compat endpoint semantics in one pass.
• Replacing ACP core runtime behavior.
• Introducing Postgres in this phase (SQLite is canonical backend for adapter persistence).

Package Architecture

New package

• Add server/packages/opencode-adapter (crate name suggestion: sandbox-agent-opencode-adapter).
• Public entry points:
  • build_opencode_router(state: Arc<AdapterAppState>) -> Router
  • OpenCodeAdapter::new(...)
  • OpenCodeAdapterConfig (db path, replay limits, feature toggles)

Responsibilities split

• sandbox-agent package:
  • Own server bootstrapping, auth, and top-level routing.
  • Mount /opencode/* by nesting adapter router.
• opencode-adapter package:
  • OpenCode HTTP handlers.
  • ACP bridge client/session orchestration.
  • ACP journal persistence (SQLite/sqlx).
  • Runtime projection from ACP journal -> OpenCode model/session/message/event views.

Persistence Model (ACP Journal First)

Mirror TS SDK semantics in Rust.

Tables (initial)

1. sessions

• id TEXT PRIMARY KEY (local/session ID exposed to OpenCode)
• agent TEXT NOT NULL
• agent_session_id TEXT NOT NULL (current live ACP session id)
• last_connection_id TEXT NOT NULL
• created_at INTEGER NOT NULL
• destroyed_at INTEGER NULL
• session_init_json TEXT NULL (JSON-encoded ACP session/new init payload)

2. events

• id TEXT PRIMARY KEY
• session_id TEXT NOT NULL
• created_at INTEGER NOT NULL
• connection_id TEXT NOT NULL
• sender TEXT NOT NULL (client or agent)
• payload_json TEXT NOT NULL (full ACP envelope JSON)
• index: (session_id, created_at, id)

3. opencode_session_metadata (small adjunct metadata table)

• session_id TEXT PRIMARY KEY
• metadata_json TEXT NOT NULL
• Stores OpenCode-specific metadata not guaranteed to be derivable from ACP envelope stream alone (title, parent, directory, project id, version, share url, permission mode).

Note: the canonical event history remains ACP envelopes; this metadata table is a projection cache/anchor for OpenCode-specific fields.

SQLite settings

• Set PRAGMA journal_mode=WAL on initialization.
• Set PRAGMA synchronous=NORMAL (or FULL if we prioritize durability over throughput; default recommendation: NORMAL for compatibility throughput).
• Use sqlx::migrate!() with versioned migrations under package-local migrations/.

Restore Algorithm (TS-style, Rust implementation)

For each session request (lazy restore trigger path):

1. Read persisted sessions row.
2. Ensure active ACP connection for the target agent.
3. If connection/session binding is still valid, continue.
4. If stale:

• Collect replay source from persisted events (last replay_max_events).
• Build replay text (bounded by replay_max_chars) from ACP envelopes:
  • include createdAt, sender, payload JSON line format.
  • append truncation marker if over limit.
• Recreate ACP session (session/new or session/load/session/resume depending on capabilities; fallback to session/new with stored init).
• Update persisted agent_session_id + last_connection_id.
• Queue replay injection for next prompt.

5. On first post-restore prompt, prepend replay text as text part (same pattern as TS SDK).

Runtime Projection Strategy

Do not persist OpenCode wire payloads as source of truth.

• Build OpenCode session/message/state views from:
  • ACP journal (events)
  • session row (sessions)
  • metadata adjunct (opencode_session_metadata)
• Use projection reducers for:
  • session status (idle/busy/error)
  • message records and parts
  • tool call/result linkage
  • pending permission/question state
• Keep hot in-memory projection cache for active sessions; rebuild on process start from persisted rows/events.

API + Routing Re-enable Plan

Phase A: extraction scaffolding

• Create new adapter crate with minimal router + state wiring.
• Move code from opencode_compat.rs / opencode_session_manager.rs into adapter modules.
• Keep /opencode/* disabled while extraction is in progress.

Phase B: persistence integration

• Add sqlx SQLite store + migrations.
• Replace in-memory canonical session/event tracking with persisted journal.
• Keep in-memory structures only as transient caches.

Phase C: restore + replay

• Implement lazy restore path for stale bindings.
• Implement replay text generation + prompt injection.
• Ensure OpenCode message/prompt endpoints use restored session path automatically.

Phase D: re-enable

• Mount adapter router under /opencode in sandbox-agent router.
• Re-enable CLI opencode command path after tests are green.

ACP Coverage Additions (Beyond Current OpenCode Compat Parity)

Add adapter support/tests for ACP capabilities that are relevant but not fully exercised by current compat suite:

• session/load / session/resume path handling when available.
• session/fork bridging through ACP when supported.
• session/cancel correctness from OpenCode abort flows.
• Proper handling of ACP notifications and request/response ordering through reconnect/restore windows.
• Preservation of _sandboxagent/... extension method naming (no /v1/ in method prefix).

Test Plan

1) Existing parity suite (must pass)

• server/packages/sandbox-agent/tests/opencode-compat/*
• Keep compatibility behavior for session, messaging, events, models, permissions, questions, tools.

2) New persistence/restore tests (required)

• Restart test: create session + message, restart server, verify /opencode/session + messages restore.
• Lazy restore test: stale connection forces restore on first prompt and succeeds.
• Replay injection test: confirm replay preamble is injected once after restore.
• Storage loss test: wiping DB causes non-recoverable sessions (expected behavior, explicit assertion).

3) ACP gap tests (required)

• session/cancel round-trip from OpenCode abort endpoint.
• session/load/session/resume (if runtime advertises capability).
• session/fork mapping with parent linkage preserved in metadata projection.

4) Migration and WAL tests

• Migration bootstrap from empty DB succeeds.
• WAL mode enabled at runtime.
• Projection rebuild from persisted events produces deterministic session/message views.

Rollout / Gate

Only re-enable /opencode/* and CLI opencode command after:

1. OpenCode compat parity suite passes.
2. New persistence/restore tests pass.
3. ACP gap tests above pass.
4. No regressions in /v1/* ACP core tests.

Implementation Checklist

• Create server/packages/opencode-adapter crate.
• Add workspace dependency wiring (Cargo.toml root + package Cargo files).
• Port OpenCode handlers/session bridge into adapter modules.
• Add sqlx dependency/features and migration framework.
• Implement SQLite journal store (sessions, events, metadata table).
• Implement lazy restore + replay injection.
• Implement runtime projection reducer from ACP events.
• Mount /opencode router in sandbox-agent only after tests are green.
• Re-enable CLI opencode command.
• Update docs (OpenCode compatibility + session restoration semantics).

Risks / Mitigations

• Risk: Projection bugs produce subtle OpenCode shape mismatches.
  • Mitigation: golden/event-sequence tests + parity SDK tests.
• Risk: replay payload growth impacts prompt quality.
  • Mitigation: strict replay_max_events + replay_max_chars bounds.
• Risk: process restart while turn in-flight causes partial state.
  • Mitigation: projection derives terminal/active status from event phases; explicit stale-turn reconciliation rule.

Explicit Behavior Contract

• Sessions are automatically restorable when live runtime/session state is lost, as long as persisted storage remains.
• If persistence storage is lost/wiped, prior sessions cannot be restored.