|
| 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