Skip to content

Commit ea37f97

Browse files
authored
feat(pruning): restore opt-in selective deletion through native plugin RPC (#686)
## Summary Restore selective deletion of completed assistant tool/reasoning content after OpenCode removed `session.messageUpdate`, without forking OpenCode or opening a generic RPC proxy. The original draft's unconditional `maintenance_required` stub is replaced by a working **experimental, explicit opt-in** plugin path for the audited `0.0.0-beta-19419` runtime. The default remains read-only. Unknown runtimes/storage and active native execution fail closed. Nothing is installed or enabled on app startup. ## Implementation - Keep individual/message/group/session cleanup entry points. Send selected technical indices and a canonical SHA-256 revision, never arbitrary replacement content, SQL, database filenames or caller-selected locations. - Use an ownership-checked CodeNomad broker with a fixed RPC ID/method/location and worktree-deletion fence. Keep the removed PATCH and generic RPC routes blocked. - Bind the plugin's explicitly configured database connection to the actual daemon DB with a fresh `ctx.storage` challenge. Inside a synchronous SQLite write transaction, recheck directory/project/workspace ownership, native durable execution claim, staged revert/compaction state, event ownership and retained payloads. - Rely on the audited native **write-ahead execution claim before runner history reads**, not an `idle` check, plugin mutex or `BEGIN IMMEDIATE` alone. Never set or release the native claim ourselves. - CAS only the completed assistant's content array. Preserve IDs, ordering, text, snapshots, usage and metadata. Commit a content-free idempotency receipt atomically with the change; identical retries cannot delete a second shifted block. - Emit the custom invalidation after commit. Re-read via the native API, invalidate the SDK transcript and pending rotations, and fence late reads against newer invalidations. Add a public-API TUI cache companion and reconnect handling. - Correct native Windows path encoding; support more than 4,096 selected parts within explicit request/message budgets. - Provide an independently packable plugin with main and `./tui` entrypoints, deployment/safety docs, and a Windows/Linux/macOS native package CI matrix. Plugin installation remains manual and separately approved. ## Validation performed locally | Check | Result | |---|---| | Server/plugin/SQLite/broker/proxy tests | 72 passed | | UI actions, events, SDK projection and stale-read tests | 60 passed | | Plugin/SQLite/TUI-companion tests under Node 22 | 30 passed | | Server and UI TypeScript checks | Passed | | Production UI build | Passed; existing large-chunk warnings | | Official Windows x64 beta-19419 executable | Passed on a private daemon and generated DB | | Independently packed and installed plugin | Same native test passed, outside the checkout | The native integration test uses the real beta-19271 network client against the official beta-19419 runtime, with a local synthetic provider and no credentials. It verifies actual preview/prune RPC, refusal while a primary generation holds the native claim, both prompt/transaction orderings, idempotent retry, two event subscribers, native re-reading, the subsequent primary model payload, fork isolation, pre-compaction history without summary changes, and persistence after server restart. The new three-OS native CI matrix must pass on this head before merge. No CI result is inferred from the local Windows run. ## Boundaries and remaining validation - This is a reviewable opt-in implementation, **not general availability across OpenCode versions/providers/platforms**. Exact runtime gating is intentional; don't widen it without re-auditing/testing. - Interactive official TUI, two native CodeNomad windows/scroll behavior, WSL, provider-specific continuation state and budget/token estimates are not claimed as validated. TUI companion tests use its cache contract, not an interactive terminal. Two HTTP subscribers are not two GUI windows. - Existing bulk cleanup is per-message and reports failure counts; dedicated installation/capability and bulk progress/cancel UI are not added here. - Existing summaries/native checkpoints, fork copies and already assembled/sent requests are not retroactively scrubbed. Historical usage remains historical usage; mock token values are not a token-savings measurement. - This changes persisted V2 content, not only visibility. It frees reusable SQLite pages but does **not** promise a smaller physical file. No VACUUM, V1 cleanup, durable-event rewriting, automatic backup restoration or universal repair is included. - No active user DB was changed, no shared-daemon plugin installed, no shared OpenCode service stopped/upgraded, and no native desktop executable/profile rebuilt or replaced. Tests use isolated synthetic data only. ## Documentation - [Request flow and validation](dev-docs/SESSION_PRUNING_RPC.md) - [Audited safety boundary](dev-docs/SESSION_PRUNING_SAFETY.md) - [Explicit deployment and recovery](dev-docs/SESSION_PRUNING_DEPLOYMENT.md) References: anomalyco/opencode#44984, anomalyco/opencode#48043, anomalyco/opencode#48090 and the maintainer's plugin/RPC direction. No upstream API or distribution fork is introduced.
1 parent ca04bff commit ea37f97

71 files changed

Lines changed: 7014 additions & 301 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/pr-build.yml‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,7 @@ jobs:
5151
- tests
5252
- tests-tauri-windows
5353
- tests-opencode-compatibility
54+
- tests-session-pruning-native
5455
- tests-tauri-macos
5556
if: ${{ needs.authorize.outputs.allowed == 'true' && !github.event.pull_request.draft }}
5657
uses: ./.github/workflows/build-and-upload.yml
@@ -62,6 +63,60 @@ jobs:
6263
actions_artifacts_name_prefix: pr-${{ github.event.pull_request.number }}-${{ github.event.pull_request.head.sha }}-
6364
set_versions: false
6465

66+
tests-session-pruning-native:
67+
needs: authorize
68+
if: ${{ needs.authorize.outputs.allowed == 'true' && !github.event.pull_request.draft }}
69+
strategy:
70+
fail-fast: false
71+
matrix:
72+
os: [windows-latest, ubuntu-latest, macos-latest]
73+
runs-on: ${{ matrix.os }}
74+
timeout-minutes: 15
75+
steps:
76+
- uses: actions/checkout@v4
77+
with:
78+
ref: ${{ github.event.pull_request.head.sha }}
79+
- uses: actions/setup-node@v4
80+
with:
81+
node-version: 22
82+
cache: npm
83+
- run: npm ci --ignore-scripts
84+
- name: Install browser for native pruning UI checks
85+
run: npx --workspace @codenomad/ui playwright install --with-deps chromium
86+
- name: Pack and install outside the checkout
87+
shell: pwsh
88+
run: |
89+
$sandbox = Join-Path $env:RUNNER_TEMP 'pruning-native-install'
90+
New-Item -ItemType Directory -Force $sandbox | Out-Null
91+
$package = npm pack ./packages/server/src/opencode/session-pruning --pack-destination $sandbox --json | ConvertFrom-Json
92+
if ($LASTEXITCODE) { exit $LASTEXITCODE }
93+
npm install --prefix $sandbox (Join-Path $sandbox $package.filename) '@opencode/cli@beta' --ignore-scripts --no-audit --no-fund
94+
if ($LASTEXITCODE) { exit $LASTEXITCODE }
95+
"PRUNING_NATIVE_INSTALL=$sandbox" >> $env:GITHUB_ENV
96+
- name: Test the installed plugin with an isolated official runtime
97+
shell: pwsh
98+
run: |
99+
$platform = node -p "process.platform === 'win32' ? 'windows' : process.platform"
100+
$arch = node -p "process.arch"
101+
$extension = node -p "process.platform === 'win32' ? '.exe' : ''"
102+
$cli = Join-Path $env:PRUNING_NATIVE_INSTALL "node_modules/@opencode/cli-$platform-$arch/bin/opencode2$extension"
103+
$plugin = Join-Path $env:PRUNING_NATIVE_INSTALL 'node_modules/@neuralnomads/codenomad-session-pruning'
104+
node scripts/test-session-pruning-native.mjs $cli $plugin
105+
if ($LASTEXITCODE) { exit $LASTEXITCODE }
106+
npm run build:pruning --workspace @neuralnomads/codenomad
107+
if ($LASTEXITCODE) { exit $LASTEXITCODE }
108+
node --import tsx --test packages/server/src/opencode/pruning-installation.test.ts
109+
if ($LASTEXITCODE) { exit $LASTEXITCODE }
110+
node scripts/test-session-pruning-native.mjs $cli --ui
111+
- name: Upload opt-in plugin package
112+
if: success()
113+
uses: actions/upload-artifact@v4
114+
with:
115+
name: session-pruning-plugin-${{ matrix.os }}
116+
path: ${{ runner.temp }}/pruning-native-install/*.tgz
117+
if-no-files-found: error
118+
retention-days: 7
119+
65120
tests:
66121
needs: authorize
67122
if: ${{ needs.authorize.outputs.allowed == 'true' && !github.event.pull_request.draft }}
@@ -175,9 +230,13 @@ jobs:
175230
packages/ui/src/stores/forms.test.ts
176231
packages/ui/src/stores/instances-restore-ownership.test.ts
177232
packages/ui/src/stores/opencode-data.test.ts
233+
packages/ui/src/stores/message-v2/empty-content.test.ts
178234
packages/ui/src/stores/permission-lifecycle.test.ts
179235
packages/ui/src/stores/shell-store-reactivity.test.ts
180236
packages/ui/src/stores/session-actions.test.ts
237+
packages/ui/src/stores/session-pruning-events.test.ts
238+
packages/ui/src/stores/session-pruning-projection.test.ts
239+
packages/ui/src/stores/session-pruning-pagination.test.ts
181240
packages/ui/src/stores/session-native-events.test.ts
182241
packages/ui/src/stores/session-move-restore.test.ts
183242
packages/ui/src/stores/session-request-authority.test.ts

‎AGENTS.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,8 @@
1111
- Document any new styling conventions or directory additions in this file so future changes remain consistent.
1212

1313
## Coding Principles
14+
15+
- Session pruning is a narrow V2 plugin/RPC exception under `packages/server/src/opencode/session-pruning/`; see `dev-docs/SESSION_PRUNING_RPC.md`. Bundle it with the shared server for both desktop hosts and provision through normal native plugin discovery. RPC registrations follow backend presence; clean shutdown removes that backend's lease and crashes expire. Loading never deletes content. Deletion occurs only on an explicit pruning request, without an extra enable-write switch or beta-number gate. Keep generic RPC proxy access closed. Writes validate actual storage, a fresh daemon-storage identity challenge and the native durable execution claim inside a synchronous SQLite transaction. Run isolated native concurrency/payload and client-cache regressions; tests must never target the shared daemon or a user's database.
1416
- Favor KISS by keeping modules narrowly scoped and limiting public APIs to what callers actually need.
1517
- Uphold DRY: share helpers via dedicated modules before copy/pasting logic across stores, components, or scripts.
1618
- Enforce single responsibility; split large files when concerns diverge (state, actions, API, events, etc.).

‎MIGRATION_V2.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,19 @@ The incremental comparison with official OpenCode Desktop V2, including closed f
1212

1313
## Native V2 Adoption
1414

15+
### Bundled session-pruning replacement
16+
17+
This branch replaces the removed `session.messageUpdate` callers with the narrow
18+
CodeNomad plugin RPC described in [SESSION_PRUNING_RPC.md](dev-docs/SESSION_PRUNING_RPC.md).
19+
The historical capability tables below describe the earlier beta integration, not
20+
current deletion availability. Once the native plugin is loaded, a pruning request
21+
requires compatible native storage, the execution-claim fence and a matching
22+
daemon DB. Official Windows runtime tests use synthetic data only. WSL, interactive
23+
TUI and desktop release checks remain documented separately. CodeNomad ships the
24+
plugin and provisions its native entry at startup. RPC registrations follow the
25+
presence of CodeNomad backends, with automatic expiry after a crash; OpenCode's
26+
shared daemon is never stopped by this lifecycle.
27+
1528
- Use native locations and `SessionInfo.location` as the authority for workspace, session, file, event, Shell, PTY, and Git worktree ownership.
1629
- Use native APIs for projects, sessions, messages, prompts, commands, models, agents, providers, MCP, permissions, Forms, files, VCS, instructions, Shells, and PTYs.
1730
- Use native session lifecycle and output events, including `session.created`, `session.renamed`, `session.moved`, `session.status`, `session.idle`, `session.execution.*`, `session.compaction.*`, `session.text.*`, `session.reasoning.*`, and `session.tool.*`.
Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
# Bundled pruning-plugin lifecycle
2+
3+
CodeNomad ships its pruning plugin with the shared server used by Tauri and
4+
Electron. No user npm install, beta-number allowlist or write-enable option is
5+
required. Loading the plugin does not delete anything.
6+
7+
## Build and automatic provisioning
8+
9+
`npm run build:pruning --workspace @neuralnomads/codenomad` bundles the native
10+
plugin and its dependencies into `packages/server/dist/plugins/session-pruning/plugin.mjs`.
11+
The normal server build includes this step. Both desktop packagers copy the same
12+
artifact into `resources/server/dist/plugins/session-pruning/`.
13+
14+
At server startup, CodeNomad copies this immutable, content-addressed payload to
15+
the CodeNomad data directory (`~/.local/share/codenomad/session-pruning/`, respecting
16+
`XDG_DATA_HOME`). It provisions a small managed entry at
17+
`~/.config/opencode/plugins/codenomad-session-pruning.ts`, respecting
18+
`XDG_CONFIG_HOME` and `OPENCODE_CONFIG_DIR`. Existing user-authored entries are
19+
preserved. No configuration document is rewritten.
20+
21+
The entry imports the copied payload, never a checkout, worktree or application
22+
installation path. CodeNomad upgrades publish a new hash-named payload and
23+
atomically update the entry. Identical launches do not rewrite it. Normal OpenCode
24+
plugin discovery/reload handles the entry; CodeNomad never restarts the shared daemon.
25+
26+
For a WSL workspace, the same backend provisions inside the selected distro's
27+
Linux directories before opening the native location. Windows uses UNC filesystem
28+
access; the native entry contains Linux paths. WSL runtime validation remains a
29+
separate release check.
30+
31+
## Presence and shutdown
32+
33+
- Each CodeNomad backend owns a unique presence file outside watched config paths,
34+
refreshed every 2 seconds. All windows of that backend share it.
35+
- The native module registers pruning RPCs when at least one fresh presence exists.
36+
- Closing one window/backend leaves other backends' presence intact. Closing the
37+
last backend removes its presence; RPC disposal follows within the 2-second check.
38+
- A crash leaves a stale file: it expires after 15 seconds, plus up to one check
39+
interval. Reopening CodeNomad automatically registers RPC again.
40+
- Plugin unload serializes pending registration and disposal, so it cannot recreate
41+
RPC after cleanup. Lease expiration never modifies content or stops OpenCode.
42+
43+
The small module remains visible in OpenCode's plugin list while inactive. It
44+
registers no model tools, commands or model hooks. While active its RPCs belong to
45+
the shared daemon and are discoverable by its other clients. Deletions affect the
46+
shared session; third-party clients may need to reload their cached transcript.
47+
48+
## Database selection and mutations
49+
50+
The plugin resolves the daemon-side path from `XDG_DATA_HOME`, `OPENCODE_DB`,
51+
channel-specific filenames and `OPENCODE_DISABLE_CHANNEL_DB`. No per-project path
52+
is normally needed. A fresh `ctx.storage` challenge verifies the selected file
53+
before a write. The only mutation trigger is an explicit pruning request.
54+
55+
Selection revisions, session ownership and native execution claims are checked in
56+
the transaction. A committed receipt makes retrying the same selection idempotent.
57+
Pruning never interrupts native execution, clears claims or rewrites checkpoints.
58+
It does not run VACUUM or restore databases.
59+
60+
## Isolated verification
61+
62+
```powershell
63+
npm run build:pruning --workspace @neuralnomads/codenomad
64+
node --import tsx --test packages/server/src/opencode/pruning-installation.test.ts
65+
node scripts/test-session-pruning-native.mjs C:/isolated-cli/opencode2.exe
66+
```
67+
68+
The native fixture uses a private daemon, config, database and mock provider. It
69+
exercises the shipped bundle through automatic discovery, then preview/prune,
70+
concurrent execution, receipts, subscribers, payloads, history, forks, restart and
71+
the presence lifecycle. An optional second argument tests an independently packed
72+
source plugin directory instead. Tests never discover or modify the shared daemon.
73+
74+
To exercise the rendered UI through the real HTTP broker and bundled plugin:
75+
76+
```powershell
77+
# Use an installed Playwright Chromium, or set CODENOMAD_BROWSER_PATH to Edge/Chrome.
78+
node scripts/test-session-pruning-native.mjs C:/isolated-cli/opencode2.exe --ui
79+
```
80+
81+
The UI fixture seeds only workspace chrome/preferences. Native messages, selection,
82+
deletion handlers, RPC writes and reloads use the private runtime. Screenshots are
83+
retained with the isolated fixture. A busy native execution claim refuses cleanup;
84+
the UI displays that reason rather than suggesting the plugin is disabled. The
85+
session-wide action retains distinct failure details as well as the failed count.
86+
87+
The UI store distinguishes omitted parts (metadata-only updates) from an explicit
88+
empty parts array (authoritative replacement). Both direct post-prune reads and
89+
history hydration clear the last tool/reasoning when the native content is empty.
90+
Retained reasoning-only messages stay visible when thoughts are enabled, even
91+
though the navigation timeline does not create a separate tick for them.

0 commit comments

Comments
 (0)