Skip to content

Commit f2b1871

Browse files
feat: add reload engine banner (anomalyco#27)
1 parent 2fd5448 commit f2b1871

2 files changed

Lines changed: 399 additions & 6 deletions

File tree

‎pr/reload-engine.md‎

Lines changed: 201 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,201 @@
1+
# PRD — Reload Engine After Plugin / Skill Changes (OpenWork)
2+
3+
## Summary
4+
5+
OpenWork lets users install **skills** (OpenPackage into `.opencode/skill`) and configure **plugins** (via `opencode.json`). Today those changes are visible on disk immediately, but the running OpenCode engine may not pick them up until the **current instance is disposed**.
6+
7+
This PRD adds a calm, premium UX affordance: a contextual **“Reload engine”** button that appears only when OpenWork detects changes that require an engine reload to take effect.
8+
9+
## Problem
10+
11+
Users can:
12+
13+
- add a plugin via the Plugins tab (writes `opencode.json`)
14+
- install/import skills via the Skills tab (writes `.opencode/skill/*`)
15+
16+
…but the agent runtime is often “stale” until the engine reloads its instance:
17+
18+
- npm plugins are loaded/installed at instance startup
19+
- agent skills can be cached by the instance (skill discovery/state)
20+
21+
So the user experiences:
22+
23+
- “I added it, but it doesn’t work”
24+
- no clear feedback about what to do next
25+
26+
## Clarifying Terms
27+
28+
### “Skill added to `opencode.json`”
29+
30+
OpenCode’s config file (`opencode.json`) does **not** declare skills. It declares configuration such as providers/models and **plugins** via the `plugin` key.
31+
32+
In OpenWork UX, users often conflate “skills” (OpenPackage installs) with “plugins” (OpenCode plugins). This feature addresses both:
33+
34+
- **Plugin change**: `opencode.json` changed (project/global)
35+
- **Skill change**: `.opencode/skill/**` changed
36+
37+
In both cases, the fix is the same: **dispose the current OpenCode instance** so the next request recreates it and reloads config/plugins/skills.
38+
39+
## Goals
40+
41+
- Make it obvious when a reload is required.
42+
- Provide a one-click, safe “Reload engine” action.
43+
- Avoid false positives (don’t nag constantly).
44+
- Don’t break running sessions; keep user in control.
45+
- Work across OpenWork’s modes:
46+
- Host mode (engine started by OpenWork)
47+
- Client mode (connected to remote engine)
48+
- Engine source PATH vs Sidecar (Host mode detail)
49+
50+
## Non-goals
51+
52+
- A full plugin installer UI (dependency management, version pins, etc.).
53+
- Hot-reloading plugins/skills without instance disposal.
54+
- Restarting the entire server process unless disposal fails (fallback only).
55+
56+
## Current Behavior (Baseline)
57+
58+
- Plugins tab mutates `opencode.json` via Tauri commands (`read_opencode_config` / `write_opencode_config`).
59+
- Skills tab installs packages via `opkg_install` and reads `.opencode/skill/*/SKILL.md` via the server file API.
60+
- OpenWork does **not** currently tell the engine that config/skill files changed.
61+
62+
## Proposed UX
63+
64+
### Where the reload affordance lives
65+
66+
A lightweight banner component shown in “engine-scoped” surfaces:
67+
68+
- Skills tab
69+
- Plugins tab
70+
- Settings (optional; if we want a central place)
71+
72+
Banner copy:
73+
74+
- Title: “Reload required”
75+
- Body (reason-dependent):
76+
- Plugin: “OpenCode loads plugins on startup. Reload to apply `opencode.json` changes.”
77+
- Skill: “OpenCode caches skill state. Reload to make newly installed skills available.”
78+
79+
Buttons:
80+
81+
- Primary: **Reload engine**
82+
- Secondary: Dismiss (hides banner until next change)
83+
84+
### Interaction flows
85+
86+
#### Flow A — Add plugin
87+
88+
1. User clicks “Add” on a plugin.
89+
2. OpenWork writes updated `opencode.json`.
90+
3. OpenWork shows banner: “Reload required to apply plugin changes.”
91+
4. User clicks “Reload engine”.
92+
5. OpenWork reloads the instance and refreshes:
93+
- providers/models
94+
- plugins list
95+
- skills list
96+
97+
#### Flow B — Install skill (OpenPackage)
98+
99+
1. User installs an OpenPackage source.
100+
2. OpenWork refreshes the file list and shows the installed skill(s).
101+
3. OpenWork shows banner: “Reload required to make skills available to the engine.”
102+
4. User reloads.
103+
104+
#### Flow C — Active run
105+
106+
If any session is currently running (status `running` / `retry`):
107+
108+
- Banner still appears, but reload is **disabled** by default.
109+
- Copy: “A run is in progress. Reloading may interrupt tool execution.”
110+
- Actions:
111+
- Primary disabled: “Reload engine”
112+
- Secondary: “Reload anyway” (optional confirm modal)
113+
114+
MVP choice: disable reload while any session is running.
115+
116+
#### Flow D — Client mode safety
117+
118+
When in Client mode, OpenWork is connected to a server it does not own.
119+
120+
- Banner still appears (because config/skills changed in the workspace), but the reload button is gated:
121+
- If the user is connected to a *remote* host, disposing the instance may affect other clients.
122+
123+
MVP choice:
124+
125+
- Show “Reload engine” only in Host mode.
126+
- In Client mode, show informational text: “Changes will apply after the host reloads.”
127+
128+
## Detection (Reliable, Minimal)
129+
130+
### “Reload needed” state
131+
132+
We track a `reloadRequired` flag with metadata:
133+
134+
- `reasons`: `plugin-config-changed` | `skills-changed`
135+
- `detectedAt`: timestamp
136+
- `scope`: project/global (for plugin changes)
137+
138+
### How we set it (MVP)
139+
140+
Set `reloadRequired = true` whenever OpenWork itself performs a write that we know requires reload:
141+
142+
- after successful `writeOpencodeConfig(...)`
143+
- after successful `opkgInstall(...)`
144+
- after successful `importSkill(...)`
145+
146+
This is reliable for the in-app workflow and avoids expensive filesystem polling.
147+
148+
### Optional: detect out-of-band edits (follow-up)
149+
150+
To catch users editing `opencode.json` in their editor:
151+
152+
- compute a cheap “desired fingerprint”:
153+
- `opencode.json` content hash (project/global)
154+
- `.opencode/skill` directory names + `SKILL.md` mtime/hash
155+
- store the fingerprint at:
156+
- engine start
157+
- after reload
158+
- compare periodically (e.g. when entering Skills/Plugins tab)
159+
160+
If mismatch, set `reloadRequired`.
161+
162+
## Reload Mechanism (Correct mapping to OpenCode)
163+
164+
OpenCode server docs expose:
165+
166+
- `POST /instance/dispose` (dispose current instance)
167+
168+
This is the correct “reload engine” primitive for this UX:
169+
170+
- sessions persist (stored in DB)
171+
- the next request recreates the instance and reloads config/plugins/skills
172+
173+
### Proposed implementation
174+
175+
Preferred path (all modes):
176+
177+
1. Call `client.instance.dispose()` (SDK wrapper for `POST /instance/dispose`).
178+
2. Poll `client.global.health()` until healthy.
179+
3. Refresh UI state:
180+
- `client.config.providers()`
181+
- `refreshPlugins()`
182+
- `refreshSkills()`
183+
184+
Fallback path (Host mode only):
185+
186+
- If disposal fails, perform a hard restart:
187+
- `engineStop()` then `engineStart()` and reconnect.
188+
189+
## Acceptance Criteria
190+
191+
- After adding a plugin via OpenWork, user sees a “Reload required” banner.
192+
- After installing/importing a skill via OpenWork, user sees the banner.
193+
- Clicking “Reload engine” triggers instance disposal and then clears the banner.
194+
- Reload is not offered while a session is actively running (MVP).
195+
- In Client mode, the UI does not dispose remote instances (MVP).
196+
197+
## Open Questions
198+
199+
- Should we show plugin install progress after reload using `installation.updated` SSE events?
200+
- Should reload be auto-triggered when idle (with a toast), instead of manual?
201+
- Do we want to support Client mode reload behind a confirmation gate?

0 commit comments

Comments
 (0)