Skip to content

Commit 8408b96

Browse files
committed
Persist volatile runtime state across v2 reloads and restarts
v2 hosts the plugin per location and rebuilds that graph on plugin file change, so in-memory state died with every reload. The runtime now journals it to a runtime_state SQLite table (extraction buffer and accepted entries, child bookkeeping with buffer snapshots and metrics, wrap-up arms, watcher definitions), written through at the mutation points. On setup, rows written by the current process (a reload) are rehydrated and re-armed; rows from a dead process are pruned unless the session is the -c/-s startup resume, which inherits state (crash recovery - new on v1 too). dispose() deliberately leaves the journal intact; the setup-time partition owns pruning. The embedding model is pooled per db path with a refcount, so the location instances of one v2 serve share a single resident model; it is disposed when the last holder releases (the ONNX sessions must still be closed explicitly before process exit). resumedSession becomes a Set - one instance can serve several resumed sessions (shared-server tabs in one directory). Plan: docs/plans/plugin-state-persistence.md.
1 parent 7d76995 commit 8408b96

9 files changed

Lines changed: 565 additions & 18 deletions

File tree

‎README.md‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -41,9 +41,11 @@ The v2 plugin API is missing a few surfaces the v1 API had. On 2.x:
4141
model-facing nudges they accompanied - watcher and chat wake nudges -
4242
still arrive; the extraction-result and other TUI-only toasts have no
4343
replacement.
44-
- **Reloads drop plugin state.** Editing the plugin (or `opencode plugin
45-
update`) reloads it: in-progress extraction buffers, registered watchers,
46-
and armed wrap-ups are lost and watchers must be re-registered.
44+
- **Plugin state survives reloads.** Editing the plugin (or `opencode
45+
plugin update`) reloads it, but extraction buffers, watcher
46+
registrations, and armed wrap-ups are journaled and restored; a process
47+
restart restores the state of a resumed (`-c`/`-s`) session and prunes
48+
the rest.
4749
- **Extraction children are visible.** The fact-extractor child sessions are
4850
top-level sessions the host cannot delete, so they accumulate in the
4951
session picker, and "continue last session" (`-c`) can land in one after

‎docs/dev/features/opencode-plugin.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -73,7 +73,7 @@ the shared runtime needs. It is the lifecycle-level sibling of `CoreContext`
7373
| compaction trigger | `client.tui.executeCommand("session_compact")` | none | degrade (no `session.compact` on the promise domain's Pick, and the built-in `/compact` is a TUI palette action calling the server endpoint directly - the server command registry only knows config/plugin-registered names; the wrap-up checklist and flush still run, the automatic compaction is skipped) |
7474
| toasts | `client.tui.showToast` | none reachable | degrade (the `tui.toast.show` event has no producer surface from the promise context) |
7575
| TUI app exit | `client.tui.publish` | none | degrade (the wrap-up exit's checklist and flush run; the process exit does not - upstream [anomalyco/opencode#50984](https://github.com/anomalyco/opencode/issues/50984)) |
76-
| dispose | `dispose` hook | cleanup returned from `setup` | must be idempotent: v2 auto-reloads plugins on file change, and a non-idempotent cleanup doubles pollers/pumps/nudges. A reload also re-runs `setup()` from scratch and discards the in-memory state: the watcher registry, extraction buffer, pending wrap-up arms, `pendingInjections`, and `sessionDirs`. Dev-shim users hit this on every plugin file save; npm users on `opencode plugin update`. Persistence of that state is a planned fix (see scratch/main-repo-bugs.md) |
76+
| dispose | `dispose` hook | cleanup returned from `setup` | must be idempotent: v2 auto-reloads plugins on file change, and a non-idempotent cleanup doubles pollers/pumps/nudges. Volatile runtime state (extraction buffer + accepted entries, child bookkeeping, wrap-up arms, watcher definitions) is journaled to the `runtime_state` table and rehydrated on the next `setup()`: rows written by the same process (a reload) all restore; rows from a dead process are pruned unless the session is the `-c`/`-s` startup resume (crash recovery). The embedding model is refcounted per db path, so N location instances share one resident model |
7777

7878
## Live verification and remaining unknowns
7979

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
# Plan: plugin state persistence across restarts and reloads
2+
3+
Status: IMPLEMENTED on branch `opencode-v2-migration` (PR sysread/thatch#16);
4+
graduates at merge with the rest of the v2 plan. Implementation notes below
5+
are the record; the dev feature doc's dispose row carries the user-facing
6+
summary.
7+
8+
## Problem
9+
10+
v2 hosts the plugin per location (`Location.Ref = {directory, workspaceID}`),
11+
and rebuilds that graph on plugin file change (`PluginSupervisor` + the
12+
module file watcher) or config reload. The rebuilt plugin starts from empty
13+
memory. A v1 process restart has the same effect. State the runtime keeps in
14+
memory is therefore lost across both events:
15+
16+
- the extraction buffer and the direct-extraction bookkeeping
17+
(`childToParent`, `parentSnapshots`, `extracting`, `extractionChildren`,
18+
`childMetrics`) - an in-flight extraction child is orphaned, the parent's
19+
buffer never drains, and the parent re-triggers a duplicate extraction on
20+
its next idle;
21+
- watcher registrations - watches vanish silently;
22+
- `pendingWrapUp` - an armed wrap-up never fires;
23+
- `resumedSession` - a scalar ("the" resumed chat session), wrong when one
24+
instance serves multiple sessions (shared-server tabs in one directory).
25+
26+
## Design
27+
28+
### 1. Runtime state journal (SQLite)
29+
30+
New table in ThatchDB:
31+
32+
```sql
33+
CREATE TABLE IF NOT EXISTS runtime_state (
34+
kind TEXT NOT NULL, -- 'buffer' | 'child' | 'wrapup' | ...
35+
session_id TEXT NOT NULL,
36+
seq INTEGER NOT NULL, -- ordering within kind+session
37+
value TEXT NOT NULL, -- JSON
38+
pid INTEGER NOT NULL, -- writer's process id
39+
created_at TEXT NOT NULL DEFAULT (strftime('%s','now'))
40+
);
41+
```
42+
43+
Write-through at the mutation points (buffer push/consume/completeAccepted,
44+
child create/adopt/clear, wrap-up arm/resolve). The `pid` column is the
45+
restart discriminator: v2 reload re-runs `setup()` in the same process, so a
46+
matching pid means "reload - keep and rehydrate"; a different pid means
47+
"restart - the old sessions died with their harness".
48+
49+
### 2. Rehydrate-and-prune on setup
50+
51+
`createRuntime` loads persisted state, then partitions by pid:
52+
53+
- **Same pid (reload)**: restore everything - buffers, child maps,
54+
pendingWrapUp - and re-arm the watchers (recreate their pollers from the
55+
persisted definitions).
56+
- **Different pid (restart)**: keep only state whose session is the startup
57+
session (`-s`/`-c` resolved id; the resumed conversation continues and
58+
inherits its buffer and watches - this also makes crash recovery work on
59+
v1). Everything else is pruned.
60+
61+
This replaces "silent loss" with "reload = resume, restart = intentional
62+
handoff to the resumed session".
63+
64+
### 3. resumedSession scalar -> Set
65+
66+
The startup paths (`-s`, `-c`, and `continuesLastSessionId`) append to a
67+
Set; the ChatPoller's `hostedSessions` reads all of them.
68+
69+
### 4. Shared embedding model, refcounted
70+
71+
`BgeEmbeddingModel` instances are cached per db path at module level with a
72+
refcount. `createRuntime` acquires; `dispose()` releases and only calls
73+
`model.dispose()` at zero (its ONNX sessions must still be explicitly
74+
disposed before process exit - Bun's NAPI finalizers panic otherwise, see
75+
src/embeddings.ts). This removes one model copy per location instance in a
76+
shared v2 server. The MCP server keeps its own (separate process, separate
77+
sideband).
78+
79+
### 5. v1 impact
80+
81+
Write-through and setup pruning add a few local SQLite reads/writes per
82+
lifecycle event - no behavior change. Restore-on-startup is a v1 improvement
83+
in one case: `-c` after a crash inherits the dead process's buffer. The
84+
refcounted model is behaviorally identical for v1's single instance.
85+
86+
## Out of scope (recorded, not fixed here)
87+
88+
- Double-hosting when two instances share a `directory` with different
89+
`workspaceID`s (the runtime's filter ignores workspaceID) - unverified
90+
whether the TUI produces that shape; revisit if seen.
91+
- Sharing the warm model ACROSS processes (the sideband already does this
92+
for MCP hook processes; extending it to plugin instances is a separate
93+
piece of work).

‎src/db.ts‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -322,6 +322,23 @@ export class ThatchDB {
322322
)
323323
`);
324324

325+
// Volatile plugin-runtime state, persisted so a v2 plugin reload (the
326+
// host rebuilds the location graph and re-runs setup) or a process
327+
// restart can rehydrate instead of silently dropping it. The writer's
328+
// pid is the discriminator: a row written by the CURRENT process means
329+
// "reload - keep and rehydrate"; a row from another (dead) pid means
330+
// "restart - prune unless the session was resumed".
331+
this.#db.exec(`
332+
CREATE TABLE IF NOT EXISTS runtime_state (
333+
kind TEXT NOT NULL,
334+
session_id TEXT NOT NULL,
335+
value TEXT NOT NULL,
336+
pid INTEGER NOT NULL,
337+
created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ','now')),
338+
PRIMARY KEY (kind, session_id)
339+
)
340+
`);
341+
325342
this.#migrateColumns();
326343
this.#migrateChatNameCollation();
327344
this.#migrateChatTopic();
@@ -961,6 +978,37 @@ export class ThatchDB {
961978
return this.#chat.unregister(sessionID);
962979
}
963980

981+
/** Persist one runtime-state record (upsert by kind+session). */
982+
runtimeStatePut(kind: string, sessionId: string, value: unknown, pid: number = process.pid) {
983+
this.#db
984+
.query(
985+
`INSERT INTO runtime_state (kind, session_id, value, pid) VALUES (?, ?, ?, ?)
986+
ON CONFLICT (kind, session_id) DO UPDATE SET value = excluded.value, pid = excluded.pid, created_at = excluded.created_at`,
987+
)
988+
.run(kind, sessionId, JSON.stringify(value), pid);
989+
}
990+
991+
/** Drop one runtime-state record. */
992+
runtimeStateDelete(kind: string, sessionId: string) {
993+
this.#db.query(`DELETE FROM runtime_state WHERE kind = ? AND session_id = ?`).run(kind, sessionId);
994+
}
995+
996+
/** Every runtime-state record, oldest first (rehydration source). */
997+
runtimeStateAll(): { kind: string; sessionID: string; value: unknown; pid: number }[] {
998+
return this.#db
999+
.query(`SELECT kind, session_id, value, pid FROM runtime_state ORDER BY created_at, session_id`)
1000+
.all()
1001+
.map((row: any) => {
1002+
let value: unknown;
1003+
try {
1004+
value = JSON.parse(row.value);
1005+
} catch {
1006+
value = null;
1007+
}
1008+
return { kind: row.kind as string, sessionID: row.session_id as string, value, pid: row.pid as number };
1009+
});
1010+
}
1011+
9641012
listChatSessions() {
9651013
return this.#chat.list();
9661014
}

‎src/embeddings.ts‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -159,6 +159,44 @@ export interface BgeEmbeddingModelOptions {
159159
idleTtlMs?: number;
160160
}
161161

162+
/**
163+
* Process-wide model pool, keyed by db path. A v2 serve hosts one plugin
164+
* instance per location and each would otherwise keep its own ONNX model
165+
* resident; the pool refcounts so N instances share one model and it is
166+
* disposed only when the last holder releases (the model's ONNX sessions
167+
* must be explicitly closed before process exit - Bun's NAPI finalizers
168+
* panic otherwise, see BgeEmbeddingModel.dispose).
169+
*/
170+
export class SharedModelPool {
171+
#entries = new Map<string, { model: BgeEmbeddingModel; refs: number }>();
172+
173+
acquire(dbPath: string, modelName: string): BgeEmbeddingModel {
174+
const entry = this.#entries.get(dbPath);
175+
if (entry) {
176+
entry.refs += 1;
177+
return entry.model;
178+
}
179+
const created = { model: new BgeEmbeddingModel(modelName), refs: 1 };
180+
this.#entries.set(dbPath, created);
181+
return created.model;
182+
}
183+
184+
release(dbPath: string): void {
185+
const entry = this.#entries.get(dbPath);
186+
if (!entry) return;
187+
entry.refs -= 1;
188+
if (entry.refs <= 0) {
189+
void entry.model.dispose();
190+
this.#entries.delete(dbPath);
191+
}
192+
}
193+
194+
/** Test/introspection: number of live (held) models. */
195+
get size(): number {
196+
return this.#entries.size;
197+
}
198+
}
199+
162200
/**
163201
* Lazy-loads an embedding model via @huggingface/transformers.
164202
* Model files (~34 MB for the default) are downloaded once and cached by HF Hub.

‎src/extraction.ts‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -84,6 +84,18 @@ export function buildExtractionPayload(
8484
});
8585
}
8686

87+
/**
88+
* Persistence hook: called after every buffer/accepted mutation with the
89+
* session's current state (undefined = the list is gone - drop the record).
90+
* The runtime wires this to the runtime_state journal so a v2 plugin reload
91+
* or process restart can rehydrate the buffer instead of losing it.
92+
*/
93+
export type ExtractionJournal = (
94+
kind: "buffer" | "accepted",
95+
sessionID: string,
96+
value: ToolInteraction[] | undefined,
97+
) => void;
98+
8799
/**
88100
* Per-session in-memory ring buffer used by the opencode plugin path. Claude
89101
* Code's MCP server has no equivalent plugin lifecycle, so its CLI subcommands
@@ -93,12 +105,32 @@ export class ExtractionPipeline {
93105
#buffers = new Map<string, ToolInteraction[]>();
94106
#accepted = new Map<string, ToolInteraction[]>();
95107
#maxBuffer = 20;
108+
#journal?: ExtractionJournal;
109+
110+
constructor(journal?: ExtractionJournal) {
111+
this.#journal = journal;
112+
}
113+
114+
/** Restore persisted state (same-process reload rehydration). */
115+
hydrate(buffers: ToolInteraction[], accepted: ToolInteraction[]): void {
116+
for (const ix of buffers) {
117+
const buf = this.#buffers.get(ix.sessionID) ?? [];
118+
buf.push(ix);
119+
this.#buffers.set(ix.sessionID, buf);
120+
}
121+
for (const ix of accepted) {
122+
const buf = this.#accepted.get(ix.sessionID) ?? [];
123+
buf.push(ix);
124+
this.#accepted.set(ix.sessionID, buf);
125+
}
126+
}
96127

97128
/** Record a tool execution for later extraction. */
98129
push(interaction: ToolInteraction): void {
99130
const buf = this.#buffers.get(interaction.sessionID) ?? [];
100131
buf.push(interaction);
101132
this.#buffers.set(interaction.sessionID, buf.slice(-this.#maxBuffer));
133+
this.#journal?.("buffer", interaction.sessionID, this.#buffers.get(interaction.sessionID));
102134
}
103135

104136
/** Returns the session's buffered interactions without clearing them. */
@@ -109,6 +141,7 @@ export class ExtractionPipeline {
109141
/** Clears the session's buffer. Called when the agent writes a memory. */
110142
consume(sessionID: string): void {
111143
this.#buffers.delete(sessionID);
144+
this.#journal?.("buffer", sessionID, undefined);
112145
}
113146

114147
/**
@@ -124,11 +157,14 @@ export class ExtractionPipeline {
124157
this.#buffers.delete(sessionID);
125158
const existing = this.#accepted.get(sessionID) ?? [];
126159
this.#accepted.set(sessionID, [...existing, ...buf]);
160+
this.#journal?.("buffer", sessionID, this.#buffers.get(sessionID));
161+
this.#journal?.("accepted", sessionID, this.#accepted.get(sessionID));
127162
}
128163

129164
/** Drop accepted entries: the extractor finished (save or no-save). */
130165
completeAccepted(sessionID: string): void {
131166
this.#accepted.delete(sessionID);
167+
this.#journal?.("accepted", sessionID, undefined);
132168
}
133169

134170
/**
@@ -144,6 +180,8 @@ export class ExtractionPipeline {
144180
this.#accepted.delete(sessionID);
145181
const buf = this.#buffers.get(sessionID) ?? [];
146182
this.#buffers.set(sessionID, [...accepted, ...buf]);
183+
this.#journal?.("buffer", sessionID, this.#buffers.get(sessionID));
184+
this.#journal?.("accepted", sessionID, undefined);
147185
}
148186

149187
/** Returns the session's accepted (held) interactions. Test/introspection. */
@@ -166,8 +204,10 @@ export class ExtractionPipeline {
166204
const remaining = buf.filter((ix) => !old.has(ix));
167205
if (remaining.length === 0) {
168206
this.#buffers.delete(sessionID);
207+
this.#journal?.("buffer", sessionID, undefined);
169208
} else {
170209
this.#buffers.set(sessionID, remaining);
210+
this.#journal?.("buffer", sessionID, remaining);
171211
}
172212
}
173213

0 commit comments

Comments
 (0)