chore+docs: config, agent registry, codecontext, v2.6 spec, changelog
Working-tree config/doc changes (.gitignore, CLAUDE.md, AGENTS.md removal + data/AGENTS.md, codecontext Dockerfile/shim — pre-existing) plus this session's v2-6 persistent-agent-sessions openspec proposal/design/tasks (planning only; feature unimplemented, reserves the v2.6.0 tag) and the v2.5.2 CHANGELOG entry. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
283
openspec/changes/v2-6-persistent-agent-sessions/design.md
Normal file
283
openspec/changes/v2-6-persistent-agent-sessions/design.md
Normal file
@@ -0,0 +1,283 @@
|
||||
# v2.6 Design — Persistent agent sessions
|
||||
|
||||
Reference implementations: `/opt/forks/opencode` (server + SDK),
|
||||
`/opt/forks/paseo` (warm ACP + opencode server-manager + reasoning dedup).
|
||||
|
||||
## 1. Architecture overview
|
||||
|
||||
```
|
||||
BooCoder (systemd host service)
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ dispatcher (per-turn unit = tasks row) │
|
||||
│ │ resolve backend + worktree + agent-session for the chat │
|
||||
│ ▼ │
|
||||
│ agent-pool ──────────────────────────────────────────────────┐ │
|
||||
│ ├─ OpenCodeServerBackend (1 process, N sessions) │ │
|
||||
│ │ `opencode serve` ◄── @opencode-ai/sdk ──► /event SSE │ │
|
||||
│ └─ WarmAcpBackend[session] (1 stdio process per session) │ │
|
||||
│ `goose acp` / `qwen --acp` ◄── ClientSideConnection │ │
|
||||
└──────────────────────────────────────────────────────────────┘ │
|
||||
│ broker.publishFrame (delta / reasoning_delta / tool_call) │
|
||||
▼ │
|
||||
web (CoderPane) — unchanged │
|
||||
```
|
||||
|
||||
The **task row stays the per-turn unit**. What changes: instead of building a
|
||||
fresh world per task, the dispatcher resolves the chat's *persistent* backend,
|
||||
worktree, and agent-session, sends one prompt, streams events, diffs, and leaves
|
||||
everything warm.
|
||||
|
||||
## 2. Backends
|
||||
|
||||
Common interface (`AgentBackend`):
|
||||
|
||||
```
|
||||
interface AgentBackend {
|
||||
ensureSession(sessionId, opts): Promise<AgentSessionHandle> // create-or-reuse
|
||||
prompt(handle, input, { worktreePath, model, signal, onEvent }): Promise<TurnResult>
|
||||
closeSession(handle): Promise<void>
|
||||
dispose(): Promise<void> // backend teardown
|
||||
health(): 'up' | 'down'
|
||||
}
|
||||
```
|
||||
|
||||
`onEvent` emits the same normalized events the current `acp-dispatch.ts` produces
|
||||
(`text`, `reasoning`, `tool_call`, `tool_update`) so the broker-frame publishing and
|
||||
`persistExternalAgentTurn` paths are reused unchanged.
|
||||
|
||||
### 2a. OpenCodeServerBackend (shared HTTP server)
|
||||
|
||||
- **Spawn once per BooCoder process:** `opencode serve --hostname 127.0.0.1 --port <p>`
|
||||
with `OPENCODE_SERVER_PASSWORD=<random-at-boot>` (verified: `serve.ts`, `network.ts`;
|
||||
default port 4096, prints `opencode server listening on http://…`). Use the official
|
||||
`@opencode-ai/sdk` (`createOpencodeServer` / `createOpencodeClient`) rather than
|
||||
hand-rolling HTTP — it already parses the ready line and wraps routes.
|
||||
- **One SSE subscription** to `GET /event`, consumed in a single read loop; events
|
||||
demuxed by `properties.sessionID` → BooCode session. Reasoning arrives as
|
||||
`message.part.delta` (`field: "reasoning"`) and `message.part.updated`
|
||||
(`part.type: "reasoning"`); text as the `text` field; tool calls as tool parts.
|
||||
- **One opencode session per BooCode chat.** `client.session.create()` once, store the
|
||||
returned `id` in `agent_sessions.agent_session_id`. Per-turn: `client.session.prompt({
|
||||
path:{id}, body:{ parts:[{type:'text',text}], model:"provider/model" }})`. Worktree
|
||||
routing via the `x-opencode-directory` header (set to the session's persistent
|
||||
worktree) so the agent operates inside it.
|
||||
- **Reasoning dedup (port from Paseo `opencode-agent.ts`):** track
|
||||
`streamedPartKeys` of `reasoning:${partID}`; when a `message.part.updated` reasoning
|
||||
part arrives whose key was already streamed via delta, drop it. Prevents the
|
||||
double-thought bug (covered by Paseo's `opencode-reasoning-dedup` e2e test).
|
||||
|
||||
### 2b. WarmAcpBackend (goose, qwen — stdio)
|
||||
|
||||
- **One persistent process + ACP connection per (chat, agent)** (Paseo's
|
||||
`SpawnedACPProcess`): spawn `goose acp` / `qwen --acp` once, NDJSON over stdio,
|
||||
`initialize` → `session/new` once; store the ACP session id in the
|
||||
`agent_sessions` row. Each turn calls `session/prompt` on the same connection;
|
||||
switching away and back resumes this same connection/session. Reuses the existing `acp-dispatch.ts`
|
||||
`handleSessionUpdate` switch verbatim for `agent_message_chunk` /
|
||||
`agent_thought_chunk` / `tool_call*`.
|
||||
- **Child lifetime is the pool's, not a request's.** Spawn detached/managed; do not
|
||||
tie the process to a single dispatch's abort signal (only the in-flight `prompt`
|
||||
gets the per-turn signal). Mirrors the codecontext shim rule (CLAUDE.md): supervise
|
||||
the child and react to its exit, don't let a request scope kill it.
|
||||
|
||||
## 3. Data model
|
||||
|
||||
Agent switching is **free** within a chat (the picker is per-turn, not locked), so
|
||||
the worktree is shared across agents but each agent keeps its own backend session.
|
||||
That splits into two tables: one **shared worktree per chat**, and one **backend
|
||||
session per (chat, agent)** pair.
|
||||
|
||||
```sql
|
||||
-- One shared worktree per BooCode chat. All agents used in the chat operate in it.
|
||||
CREATE TABLE IF NOT EXISTS session_worktrees (
|
||||
session_id UUID PRIMARY KEY REFERENCES sessions(id),
|
||||
worktree_path TEXT NOT NULL,
|
||||
base_commit TEXT, -- project HEAD captured at create (diff baseline)
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT clock_timestamp()
|
||||
);
|
||||
|
||||
-- One backend session per (chat, agent). Resumed when the user switches back to
|
||||
-- that agent, so each agent retains its own conversation memory across switches.
|
||||
CREATE TABLE IF NOT EXISTS agent_sessions (
|
||||
session_id UUID NOT NULL REFERENCES sessions(id),
|
||||
agent TEXT NOT NULL, -- opencode | goose | qwen (native boocode needs no row)
|
||||
backend TEXT NOT NULL, -- opencode_server | acp_warm
|
||||
agent_session_id TEXT, -- opencode/ACP native session id (the memory handle)
|
||||
server_port INTEGER, -- opencode server port (nullable)
|
||||
status TEXT NOT NULL DEFAULT 'idle', -- idle | active | crashed | closed
|
||||
last_active_at TIMESTAMPTZ,
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT clock_timestamp(),
|
||||
PRIMARY KEY (session_id, agent),
|
||||
CONSTRAINT agent_sessions_backend_chk CHECK (backend IN ('opencode_server','acp_warm')),
|
||||
CONSTRAINT agent_sessions_status_chk CHECK (status IN ('idle','active','crashed','closed'))
|
||||
);
|
||||
```
|
||||
|
||||
Plus one column for attribution (drives the DiffPanel badges in §9):
|
||||
|
||||
```sql
|
||||
-- Which agent staged each pending change. Stamped at queue time:
|
||||
-- worktree-diff path → the task's agent; native boocode write tools → 'boocode';
|
||||
-- manual RightRail create (v2.5.x) → NULL (renders as "manual").
|
||||
ALTER TABLE pending_changes ADD COLUMN IF NOT EXISTS agent TEXT;
|
||||
```
|
||||
|
||||
`tasks.worktree_path` already exists but was per-task; the persistent worktree now
|
||||
lives on `session_worktrees`. `tasks` stays the per-turn record (state machine
|
||||
unchanged) and gains nothing required. **Native boocode** keeps no `agent_sessions`
|
||||
row — it has no warm backend; it reconstructs conversation context from the chat's
|
||||
`messages` rows each turn (so it transparently sees every other agent's prior turns).
|
||||
DB is the source of truth for reconnect after a BooCoder restart (the in-memory pool
|
||||
rebuilds lazily from these tables on the next turn).
|
||||
|
||||
## 3a. Agent switching & continuity (the decided model)
|
||||
|
||||
Per the design review: **free switch, per-agent memory.** Concretely:
|
||||
|
||||
- **Picker is per-turn.** The message route already sends `provider`/`model` per
|
||||
message; nothing locks a chat to one agent. v2.6 keeps that.
|
||||
- **Worktree is shared.** All agents in a chat resolve the same `session_worktrees`
|
||||
row, so file state carries across switches — *once applied*. (See the staging
|
||||
boundary caveat below.)
|
||||
- **Each agent resumes its own session.** Switching opencode → boocode → opencode
|
||||
reuses opencode's stored `agent_session_id` (its memory intact), not a fresh one.
|
||||
Lazy-create on first use of an agent in the chat; resume thereafter.
|
||||
- **Native boocode is the universal reader.** It rebuilds from the `messages` table,
|
||||
so it always sees the full transcript including other agents' turns.
|
||||
- **Gap turns are NOT auto-replayed** into a resumed agent. When you return to
|
||||
opencode, it sees the shared worktree + your new prompt, but did not "hear" the
|
||||
boocode/goose turns in between. (A future refinement could inject a short
|
||||
"changes since you last ran" preamble; out of scope for v2.6.)
|
||||
- **Staging-boundary caveat (must be documented in the UI):** external agents edit
|
||||
*inside the worktree*; native boocode reads/writes the *project root* via
|
||||
`pending_changes`. So unapplied edits do **not** cross between a worktree agent and
|
||||
native boocode — file continuity between the two only exists after apply. This is
|
||||
an inherent consequence of v2.5's review-before-apply model, not a v2.6 bug.
|
||||
- **No mid-turn switch.** Per-chat turns are serialized (§5); the agent is fixed for
|
||||
the duration of an in-flight turn. The user can switch the picker for the *next*
|
||||
turn while one is running, but it won't retarget the running turn.
|
||||
|
||||
## 4. Persistent worktree + incremental diff
|
||||
|
||||
- **Create** on the first turn of a chat (`createWorktree(projectPath, sessionId)`
|
||||
— keyed by chat, not task), capturing project HEAD as `base_commit`. Persist the
|
||||
`session_worktrees` row; all agents in the chat share it.
|
||||
- **Reuse** every subsequent turn — no new worktree, no cleanup between turns.
|
||||
- **Diff strategy (per turn):** diff the worktree against the **project HEAD baseline**
|
||||
captured when the worktree was created. Each turn supersedes the prior
|
||||
`pending_changes` row for that session (one accumulating unified diff, latest wins) —
|
||||
mirrors how the anchored rolling summary supersedes itself. Avoids stacking N partial
|
||||
diffs the user must reason about; the pending change always reflects the full current
|
||||
delta of the worktree.
|
||||
- **Apply** merges the worktree delta back to the project (existing `apply_pending`
|
||||
path); after apply, re-baseline so the next turn's diff is relative to applied state.
|
||||
- **Cleanup** on chat close/archive (new hook) and on `dispose()`; removes the
|
||||
`session_worktrees` row + all `agent_sessions` rows for the chat. Orphan reaper
|
||||
sweeps worktrees with no live `session_worktrees` row (extends the periodic sweeper).
|
||||
|
||||
## 5. Concurrency
|
||||
|
||||
Current dispatcher: global `running` boolean → strictly one task at a time.
|
||||
Target: **per-session serialization, cross-session concurrency.**
|
||||
|
||||
- Replace the single `running` flag with a `Map<sessionId, Promise>` in-flight registry.
|
||||
- `poll()` selects the oldest pending task whose **session has no in-flight turn**, so
|
||||
two different chats run concurrently but a chat never has two turns at once (the agent
|
||||
holds conversational state — overlapping prompts would corrupt it).
|
||||
- The LISTEN/NOTIFY `tasks_new` fast path (v2.5.x) already triggers immediate polls;
|
||||
the registry replaces the boolean guard there too.
|
||||
|
||||
## 6. Lifecycle & failure
|
||||
|
||||
- **Lazy spawn:** backend/worktree/agent-session created on first turn for a session.
|
||||
- **Idle eviction:** pool evicts a backend/session after an idle TTL (e.g. 30 min);
|
||||
worktree persists (DB-backed); next turn re-spawns and reattaches via stored
|
||||
`agent_session_id` (opencode persists sessions on disk; ACP re-`session/new` if the
|
||||
native id is gone).
|
||||
- **Crash recovery:** supervise children; on exit mark `agent_sessions.status='crashed'`,
|
||||
publish `chat_status='error'`, and rebuild on the next turn. opencode server crash
|
||||
takes all opencode sessions down → restart server, recreate sessions.
|
||||
- **Shutdown drain:** `app.addHook('onClose')` disposes the pool (close opencode server,
|
||||
kill warm ACP children) after in-flight turns settle — extends the existing
|
||||
dispatcher `stop()`.
|
||||
- **systemd:** BooCoder already spawns agent children under `NoNewPrivileges`; long-lived
|
||||
pool children are fine. Use `context.Background`-equivalent detachment so children
|
||||
outlive the dispatch that created them.
|
||||
|
||||
## 7. Risks / open questions
|
||||
|
||||
- **opencode single-server blast radius:** one crash drops all opencode sessions. Mitigated
|
||||
by on-disk session persistence + lazy re-create. Could later shard one server per project
|
||||
if it bites.
|
||||
- **Worktree disk growth:** persistent worktrees per session accumulate; the close-hook +
|
||||
orphan reaper must be reliable or disk leaks. Add a max-live-worktrees cap with LRU evict.
|
||||
- **SDK version coupling:** `@opencode-ai/sdk` is a new workspace dep pinned to the installed
|
||||
opencode (1.15.x). Probe-time version check should warn on major drift.
|
||||
- **Incremental-diff baseline correctness:** re-baselining after apply must handle the user
|
||||
editing the project out-of-band; diff vs a stored base commit, not vs a moving target.
|
||||
- **Reconnect fidelity:** after BooCoder restart, reattaching to a stored opencode session id
|
||||
assumes the server (also restarted) still has it on disk — verify the SDK reattach path.
|
||||
- **Cross-agent staging gap:** worktree agents and native boocode don't see each other's
|
||||
*unapplied* edits (worktree vs project root). The UI must make this legible (e.g. show
|
||||
which agent staged a pending change) so a switch doesn't look like lost work. A resumed
|
||||
agent also won't have heard other agents' in-between turns — acceptable per the decided
|
||||
model, but worth a small "N turns by other agents since you last ran" hint later.
|
||||
- **Per-(chat,agent) session sprawl:** a chat that cycles through many agents accumulates
|
||||
warm backends/worktree co-tenants; idle eviction (§6) must key on (chat,agent), and the
|
||||
opencode server's session count is bounded by eviction, not per-chat.
|
||||
|
||||
## 8. File map (anticipated)
|
||||
|
||||
| File | Change |
|
||||
|------|--------|
|
||||
| `apps/coder/src/services/agent-pool.ts` | NEW — pool + backend interface |
|
||||
| `apps/coder/src/services/backends/opencode-server.ts` | NEW — SDK + SSE demux + dedup |
|
||||
| `apps/coder/src/services/backends/warm-acp.ts` | NEW — persistent ACP connection |
|
||||
| `apps/coder/src/services/dispatcher.ts` | per-chat concurrency; resolve-or-create shared worktree + per-(chat,agent) backend session; no per-turn teardown |
|
||||
| `apps/coder/src/services/worktrees.ts` | chat-keyed create; baseline capture; re-baseline-on-apply |
|
||||
| `apps/coder/src/services/agent-turn-persist.ts` | reused as-is |
|
||||
| `apps/coder/src/schema.sql` | `session_worktrees` + `agent_sessions` (per (chat,agent)) + `pending_changes.agent` column |
|
||||
| `apps/coder/src/routes/sessions|tasks` | chat-close cleanup hook |
|
||||
| `apps/coder/src/routes/pending.ts` | `agent` on `listPending` response; stamp `agent` in queue paths |
|
||||
| `apps/coder/src/routes/agent-sessions.ts` | NEW — `GET /api/sessions/:id/agent-sessions` (§9b) |
|
||||
| `apps/coder/package.json` | add `@opencode-ai/sdk` dep |
|
||||
| `apps/web/src/components/panes/CoderPane.tsx` | `PendingChange.agent`; DiffPanel badges + staging hint; pass `sessionId` to composer |
|
||||
| `apps/web/src/components/AgentComposerBar.tsx` | optional `sessionId` prop; resumed/new chip; export `providerIcon` |
|
||||
| `apps/web/src/hooks/useAgentSessions.ts` | NEW — chat-scoped agent-session fetch |
|
||||
| `apps/web/src/api/client.ts` | `api.coder.agentSessions(sessionId)` |
|
||||
|
||||
## 9. Frontend UX — agent attribution & switch affordances
|
||||
|
||||
The switching model (§3a) is only good if it's **legible**: the user must see which
|
||||
agent did what, and whether switching back resumes or starts fresh. Pure read+display
|
||||
over the new `agent` column and `agent_sessions` — no dispatch-logic change.
|
||||
|
||||
### 9a. Per-change agent attribution (DiffPanel) — Phase 1
|
||||
- **Wire:** `listPending` returns the row; add `agent` to the response and to the
|
||||
frontend `PendingChange` type (`CoderPane.tsx`, today `{id, file_path, operation, diff?, status}`).
|
||||
- **UI:** each DiffPanel row gains a small agent badge before the file path — reuse the
|
||||
`providerIcon()` switch from `AgentComposerBar` (extract to a shared helper / the new
|
||||
`icons/ProviderIcons` module) + the provider label; `agent === null` → a neutral
|
||||
"manual" chip. When the pending set spans >1 distinct agent, a one-line header note
|
||||
("Changes from opencode, boocode") makes mixed provenance obvious.
|
||||
|
||||
### 9b. "Resumed" vs "new session" indicator (AgentComposerBar) — Phase 1
|
||||
- **API:** `GET /api/sessions/:id/agent-sessions` → `[{ agent, status, has_session, last_active_at }]`
|
||||
(reads `agent_sessions` for the chat). Chat-scoped, so it is NOT foldable into the
|
||||
project-level provider snapshot.
|
||||
- **Hook:** `useAgentSessions(sessionId)` — fetch on mount, refetch on `message_complete`
|
||||
(same trigger `usePendingChanges` already uses).
|
||||
- **UI:** a subtle chip right of the Provider picker:
|
||||
- current provider has a live row → muted **"resumed"** (title: "Resuming <agent> · last active <relative>").
|
||||
- native boocode (never has a row) → **"history"** (it reconstructs from the transcript).
|
||||
- otherwise → **"new session"**.
|
||||
- Render only when connected and the chat has ≥1 prior turn; hidden on a fresh chat.
|
||||
- `AgentComposerBar` gains an optional `sessionId?: string` prop (CoderPane has it);
|
||||
absent → render nothing, so BooChat and other callers are unaffected.
|
||||
|
||||
### 9c. Staging-boundary hint (DiffPanel) — Phase 3 polish
|
||||
- When the selected provider is **native boocode** and pending changes were staged by a
|
||||
**worktree agent** (or vice-versa), show a one-line muted caveat:
|
||||
"opencode's edits live in its worktree — boocode won't see them until applied."
|
||||
Derived purely from per-change `agent` + current `value.provider`; no new state.
|
||||
Keeps the §3a staging caveat from biting silently.
|
||||
Reference in New Issue
Block a user