openwork/apps/app/pr/openwork-orchestrator.md

PRD: OpenWork Orchestrator (Host-First + Fallback Remote)

Summary

Reframe OpenWork as the lifecycle supervisor for OpenCode. Clients connect to an OpenWork host, which returns the OpenCode connection details for the active workspace. If the host URL is not an OpenWork server, fall back to the existing direct-OpenCode flow so remote workspaces still work.

Simplest design decision: the OpenWork host exposes only the active workspace. No multi-workspace share list. When the host switches workspaces, clients follow it.

Goals

• Host mode: OpenWork starts and supervises OpenCode and exposes a pairing endpoint for clients.
• Client mode: connect to OpenWork host URL + token; host provides OpenCode base URL + directory.
• Fallback: if a user enters a URL that is not an OpenWork host, connect directly to OpenCode as today.
• UI: the connection flow and workspace surfaces reflect OpenWork host vs direct OpenCode.

Non-goals

• Multiple shared workspaces or “pinned” workspace lists.
• Peer discovery or QR pairing (future).
• New auth systems beyond bearer token.
• New OpenCode APIs.

User flows

Host mode

1. User picks a local workspace.
2. OpenWork starts OpenCode (opencode serve).
3. OpenWork starts OpenWork server and registers the active workspace.
4. Settings shows pairing URL + client token.

Client mode (OpenWork host)

1. User enters OpenWork Host URL + token.
2. OpenWork client calls host /health and /workspaces.
3. Host returns active workspace + OpenCode base URL + directory.
4. Client connects to OpenCode using existing SDK flow.
5. Skills/plugins/config actions route to OpenWork host (preferred). If unavailable, fall back to OpenCode or show read-only.

Client mode (fallback to OpenCode)

1. User enters a URL that is not an OpenWork host.
2. Client attempts OpenWork /health and fails with non-OpenWork response.
3. Client treats the URL as OpenCode base URL (existing flow).

API contract (OpenWork host)

Base URL: http(s)://<host>:<port> Auth: Authorization: Bearer <token>

GET /health

Returns { healthy: true, version: string }. If missing or 404, treat as non-OpenWork host and fallback to OpenCode.

GET /workspaces

Returns only the active workspace:

{
  active: {
    id: "ws-123",
    name: "My Workspace",
    opencode: {
      baseUrl: "http://127.0.0.1:4096",
      directory: "/path/to/workspace"
    }
  }
}

GET /workspaces/active

Alias for the active workspace payload (optional).

GET /capabilities

Returns { skills: { read, write }, plugins: { read, write }, mcp: { read, write } }.

Data model changes

WorkspaceInfo (Tauri + UI) must differentiate remote OpenWork vs direct OpenCode:

• remoteType: "openwork" | "opencode"
• openworkHostUrl?: string
• openworkWorkspaceId?: string
• opencodeBaseUrl?: string (existing baseUrl becomes this)
• opencodeDirectory?: string (existing directory becomes this)

Workspace ID

• For OpenWork remote: stable ID should include openworkHostUrl + openworkWorkspaceId.
• For OpenCode remote: keep current stable_workspace_id_for_remote(baseUrl, directory).

UI rewires (specific components)

Onboarding client step

File: packages/app/src/app/pages/onboarding.tsx

• Replace “Remote base URL” with OpenWork Host URL.
• Add Access token input.
• Add “Advanced: Connect directly to OpenCode” toggle that reveals the current baseUrl + directory inputs.
• Submit button calls onConnectClient() which attempts OpenWork first, then fallback.

Create Remote Workspace modal

File: packages/app/src/app/components/create-remote-workspace-modal.tsx

• Primary fields: OpenWork Host URL + Access token.
• Advanced toggle: Direct OpenCode base URL + directory.
• Store remoteType in workspace state based on which input path is used.

Workspace picker + switch overlay

Files:

• packages/app/src/app/components/workspace-picker.tsx
• packages/app/src/app/components/workspace-switch-overlay.tsx Changes:
• Show badge: OpenWork vs OpenCode for remote workspaces.
• Primary line: OpenWork host URL (if OpenWork remote) else OpenCode baseUrl.
• Secondary line: workspace name from host (OpenWork) or directory (OpenCode).

Settings connection card

File: packages/app/src/app/pages/settings.tsx

• Show OpenWork host status when in client mode: URL, connection state, token status.
• Host mode: show pairing URL + client token from OpenWork server.
• Keep OpenCode engine status visible for host mode only.

State + logic rewires (exact mapping)

Workspace connection flow

File: packages/app/src/app/context/workspace.ts

• Split current connectToServer() into:
  • connectToOpenworkHost(hostUrl, token)
  • connectToOpencode(baseUrl, directory) (existing logic)
• Update createRemoteWorkspaceFlow() to:
  1. Try OpenWork host handshake.
  2. If handshake fails (non-OpenWork), fallback to OpenCode base URL path.
• Update activateWorkspace() to branch based on remoteType.

Client + header status

File: packages/app/src/app/app.tsx

• Track OpenWork host connection state alongside OpenCode client state.
• Header status should prefer OpenWork host state in client mode (e.g., “Connected · OpenWork”).

Extensions (skills/plugins/mcp)

File: packages/app/src/app/context/extensions.ts

• If remoteType is openwork and host capabilities allow, use OpenWork server endpoints for:
  • skills list/install/remove
  • plugin list/add/remove (project scope only)
• If remoteType is opencode, keep current OpenCode-only behavior (read-only or host-only).

Host lifecycle changes

OpenWork host must manage OpenWork server alongside OpenCode:

• Start OpenWork server after OpenCode engine starts.
• Update OpenWork server when active workspace changes.
• Expose pairing URL + token to UI.

Files (desktop):

• packages/desktop/src-tauri/src/commands/engine.rs
• packages/desktop/src-tauri/src/lib.rs
• packages/desktop/src-tauri/src/types.rs
• packages/desktop/src-tauri/src/commands/workspace.rs

Fallback behavior (explicit)

• If GET /health fails (404, network error, non-JSON), treat the input as a direct OpenCode base URL.
• The UI should show a small inline hint: “Connected via OpenCode (not OpenWork).”

Migration

• Existing remote workspaces stored as OpenCode remotes remain valid.
• New OpenWork remotes store remoteType = openwork with host URL + workspace ID.
• No changes to local workspaces.

Risks

• Confusing connection state (OpenWork vs OpenCode). Mitigate with badges + status text.
• Host switching workspace unexpectedly disconnects client. Mitigate with a short toast + auto-reconnect.
• Non-OpenWork URLs falsely detected. Mitigate with clear fallback flow.

Open questions

• Do we need a QR pairing artifact now, or later?
• Should host expose a “Read-only mode” toggle for shared clients?
• Should OpenWork server enforce token rotation or persistence?

Acceptance criteria

• Client can connect to OpenWork host and OpenWork supplies OpenCode base URL + directory.
• Entering a non-OpenWork URL still connects via OpenCode with no regression.
• UI clearly distinguishes OpenWork vs OpenCode remote connections.