openwork/pr/reload-engine.md

PRD — Reload Engine After Plugin / Skill Changes (OpenWork)

Summary

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.

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.

Problem

Users can:

• add a plugin via the Plugins tab (writes opencode.json)
• install/import skills via the Skills tab (writes .opencode/skill/*)

…but the agent runtime is often “stale” until the engine reloads its instance:

• npm plugins are loaded/installed at instance startup
• agent skills can be cached by the instance (skill discovery/state)

So the user experiences:

• “I added it, but it doesn’t work”
• no clear feedback about what to do next

Clarifying Terms

“Skill added to opencode.json”

OpenCode’s config file (opencode.json) does not declare skills. It declares configuration such as providers/models and plugins via the plugin key.

In OpenWork UX, users often conflate “skills” (OpenPackage installs) with “plugins” (OpenCode plugins). This feature addresses both:

• Plugin change: opencode.json changed (project/global)
• Skill change: .opencode/skill/** changed

In both cases, the fix is the same: dispose the current OpenCode instance so the next request recreates it and reloads config/plugins/skills.

Goals

• Make it obvious when a reload is required.
• Provide a one-click, safe “Reload engine” action.
• Avoid false positives (don’t nag constantly).
• Don’t break running sessions; keep user in control.
• Work across OpenWork’s modes:
  • Host mode (engine started by OpenWork)
  • Client mode (connected to remote engine)
  • Engine source PATH vs Sidecar (Host mode detail)

Non-goals

• A full plugin installer UI (dependency management, version pins, etc.).
• Hot-reloading plugins/skills without instance disposal.
• Restarting the entire server process unless disposal fails (fallback only).

Current Behavior (Baseline)

• Plugins tab mutates opencode.json via Tauri commands (read_opencode_config / write_opencode_config).
• Skills tab installs packages via opkg_install and reads .opencode/skill/*/SKILL.md via the server file API.
• OpenWork does not currently tell the engine that config/skill files changed.

Proposed UX

Where the reload affordance lives

A lightweight banner component shown in “engine-scoped” surfaces:

• Skills tab
• Plugins tab
• Settings (optional; if we want a central place)

Banner copy:

• Title: “Reload required”
• Body (reason-dependent):
  • Plugin: “OpenCode loads plugins on startup. Reload to apply opencode.json changes.”
  • Skill: “OpenCode caches skill state. Reload to make newly installed skills available.”

Buttons:

• Primary: Reload engine
• Secondary: Dismiss (hides banner until next change)

Interaction flows

Flow A — Add plugin

1. User clicks “Add” on a plugin.
2. OpenWork writes updated opencode.json.
3. OpenWork shows banner: “Reload required to apply plugin changes.”
4. User clicks “Reload engine”.
5. OpenWork reloads the instance and refreshes:
   • providers/models
   • plugins list
   • skills list

Flow B — Install skill (OpenPackage)

1. User installs an OpenPackage source.
2. OpenWork refreshes the file list and shows the installed skill(s).
3. OpenWork shows banner: “Reload required to make skills available to the engine.”
4. User reloads.

Flow C — Active run

If any session is currently running (status running / retry):

• Banner still appears, but reload is disabled by default.
• Copy: “A run is in progress. Reloading may interrupt tool execution.”
• Actions:
  • Primary disabled: “Reload engine”
  • Secondary: “Reload anyway” (optional confirm modal)

MVP choice: disable reload while any session is running.

Flow D — Client mode safety

When in Client mode, OpenWork is connected to a server it does not own.

• Banner still appears (because config/skills changed in the workspace), but the reload button is gated:
  • If the user is connected to a remote host, disposing the instance may affect other clients.

MVP choice:

• Show “Reload engine” only in Host mode.
• In Client mode, show informational text: “Changes will apply after the host reloads.”

Detection (Reliable, Minimal)

“Reload needed” state

We track a reloadRequired flag with metadata:

• reasons: plugin-config-changed | skills-changed
• detectedAt: timestamp
• scope: project/global (for plugin changes)

How we set it (MVP)

Set reloadRequired = true whenever OpenWork itself performs a write that we know requires reload:

• after successful writeOpencodeConfig(...)
• after successful opkgInstall(...)
• after successful importSkill(...)

This is reliable for the in-app workflow and avoids expensive filesystem polling.

Optional: detect out-of-band edits (follow-up)

To catch users editing opencode.json in their editor:

• compute a cheap “desired fingerprint”:
  • opencode.json content hash (project/global)
  • .opencode/skill directory names + SKILL.md mtime/hash
• store the fingerprint at:
  • engine start
  • after reload
• compare periodically (e.g. when entering Skills/Plugins tab)

If mismatch, set reloadRequired.

Reload Mechanism (Correct mapping to OpenCode)

OpenCode server docs expose:

• POST /instance/dispose (dispose current instance)

This is the correct “reload engine” primitive for this UX:

• sessions persist (stored in DB)
• the next request recreates the instance and reloads config/plugins/skills

Proposed implementation

Preferred path (all modes):

1. Call client.instance.dispose() (SDK wrapper for POST /instance/dispose).
2. Poll client.global.health() until healthy.
3. Refresh UI state:
   • client.config.providers()
   • refreshPlugins()
   • refreshSkills()

Fallback path (Host mode only):

• If disposal fails, perform a hard restart:
  • engineStop() then engineStart() and reconnect.

Acceptance Criteria

• After adding a plugin via OpenWork, user sees a “Reload required” banner.
• After installing/importing a skill via OpenWork, user sees the banner.
• Clicking “Reload engine” triggers instance disposal and then clears the banner.
• Reload is not offered while a session is actively running (MVP).
• In Client mode, the UI does not dispose remote instances (MVP).

Open Questions

• Should we show plugin install progress after reload using installation.updated SSE events?
• Should reload be auto-triggered when idle (with a toast), instead of manual?
• Do we want to support Client mode reload behind a confirmation gate?