openwork/prd-authenticated-providers.md

PRD — Authenticated Provider Discovery (Path Engine)

Summary

In OpenWork, when the engine source is set to Path (i.e. OpenWork spawns the user-installed opencode binary), the model picker can incorrectly show only free Zen (opencode) models and omit providers/models the user is already authenticated to.

Users should at minimum see all providers the engine is authenticated to ("connected"), and ideally see the full provider catalog with clear connection status.

This PRD proposes:

1. Parity: Path engine should use the same credentials/config as the user’s normal opencode CLI.
2. Visibility: OpenWork should surface why providers are missing (missing env, missing auth store, wrong binary).
3. Recovery: Provide an in-app way to restore the expected provider list (import env, select auth location, or connect providers).

Problem

What users experience

• Toggle Engine source → Path.
• Connect/start the engine successfully.
• In the model picker, only free Zen models appear.
• Providers/models the user can use in the terminal (OpenAI, Anthropic, etc.) do not appear.

This breaks a core expectation: OpenWork is a UI for OpenCode, not a different runtime.

Why it matters

• The UI appears “broken” or “limited to free”.
• Users can’t pick the model/provider they already pay for.
• It increases support burden (“works in terminal, not in app”).

Root Cause (Current Behavior)

OpenWork’s model list is driven by OpenCode server APIs:

• client.config.providers() (OpenCode GET /config/providers) returns configured/available providers + default model mapping.
  • On the server this uses Provider.list().

OpenCode determines which providers are “connected” primarily via:

• Environment variables (e.g. OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.)
• OpenCode auth store (OpenCode Auth.all() → ${XDG_DATA_HOME}/opencode/auth.json by default)
• Config (opencode.json provider options)

In Path engine mode, OpenWork spawns opencode serve from a GUI process (Tauri). Two common issues arise:

1. GUI apps don’t inherit shell env

   • Provider env vars set in .zshrc, .bashrc, direnv, etc. are not present.
   • Result: providers configured via env are “missing”.

2. XDG path mismatch can hide auth.json

   • If the user’s terminal session sets XDG_DATA_HOME (or related XDG vars) but the GUI app does not, OpenCode looks in a different directory for auth.json.
   • Result: providers configured via opencode auth login appear missing.

Additionally, a third issue can confuse debugging:

3. OpenWork may be running a different opencode binary than the user expects
   • If multiple installs exist (brew vs installer vs older binary), OpenWork may resolve a different executable.
   • The user may have authenticated using a different installation context.

All three present the same symptom: only free Zen models are returned because OpenCode believes it has no provider credentials.

Goals

• In Path engine mode, OpenWork shows all providers the engine is authenticated to.
• OpenWork provides clear feedback when providers are missing:
  • which opencode binary is running
  • which auth/config directories are being used
  • whether any provider credentials were detected
• Users can fix the situation without leaving the app.

Non-Goals

• Implementing a full provider marketplace or registry.
• Replacing OpenCode’s auth/config storage.
• Solving remote (Client mode) provider auth across machines (separate PRD).

Proposed Solution

1) Switch model picker to “provider.list + connected” semantics

Today, config.providers is useful but opaque: it only returns providers the server believes are configured/available.

Instead, OpenWork should prefer:

• client.provider.list() (OpenCode GET /provider) which returns:
  • all: full provider catalog
  • connected: provider IDs that are authenticated
  • default: default model per provider

UI behavior

• Show “Connected” providers first.
• Show non-connected providers as disabled, with a clear “Connect” CTA.
• Preserve “Zen” as the default/fallback (free works out of the box), but don’t hide the rest.

This change ensures the user always sees the catalog and can understand “you’re not connected” vs “OpenWork is broken”.

2) Add a provider/auth diagnostics surface (Settings → Providers)

Add a compact diagnostics block (no secrets displayed):

• Engine source: Path | Sidecar
• Resolved opencode binary (from engine_doctor.resolvedPath)
• Server version (/global/health.version)
• Effective workspace directory (what OpenCode sees via client.path.get())
• Connected providers count + list of IDs
• Detected auth store location (see section 3)

Include a “Refresh providers” action that re-fetches provider.list().

3) Make Path engine use the same auth/config directories as the user’s CLI

3a) Detect likely auth store locations

On start/connect, OpenWork should locate OpenCode’s auth store (without requiring the user to know XDG).

Detection strategy (ordered):

1. If XDG_DATA_HOME is present in the OpenWork process env, use it.
2. If absent, compute default XDG data dir for the platform.
3. Additionally, probe common legacy locations (if any exist) and present the chosen one in diagnostics.

3b) Optional: import XDG env from login shell (user-consented)

If providers are unexpectedly missing, offer a safe recovery step:

• Button: Import shell environment (recommended)
• Explain: “GUI apps don’t inherit shell env. This will read your login shell environment variables and restart the engine. Only provider-related variables are imported.”

Implementation intent:

• Spawn the user’s login shell (e.g. $SHELL -lc env) and parse.
• Import only an allowlist:
  • XDG_* variables
  • Provider key env vars (derived from OpenCode ModelsDev provider env metadata)
• Restart engine with the merged env.

4) Provide an in-app provider connection path

Even with env import, the best long-term UX is first-class provider connection inside OpenWork.

Minimum viable flow:

• For providers that support API key auth:
  • Prompt for key → call client.auth.set({ providerID, type: "api", key })
• For providers that support OAuth:
  • Display guided steps and deep link to authorization URL using client.provider.auth() + OAuth endpoints.

This avoids reliance on shell env and makes Path engine work identically to Sidecar.

User Flows

Flow A — User already has opencode auth credentials

1. User selects Engine source → Path.
2. Starts engine.
3. OpenWork calls provider.list().
4. Connected providers appear.

If connected providers are missing:

5. Settings → Providers shows:
   • binary path
   • auth store location
   • connected providers = 0
6. User clicks “Import shell environment” (or “Select auth store…” if we add it).
7. Engine restarts.
8. Connected providers appear.

Flow B — User relies on env vars only (no auth store)

1. User starts Path engine.
2. Providers show as “Not connected”.
3. OpenWork offers:
   • “Import shell environment” (brings env vars into engine)
   • or “Connect” (stores key via auth.set)

Flow C — Multiple opencode installs

1. OpenWork shows resolved binary path.
2. If it differs from the user’s expected install, user can:
   • set OPENCODE_BIN_PATH (already supported by engine doctor), or
   • choose a binary via a future “Pick engine binary…” UI.

Acceptance Criteria

• With Engine source = Path:
  • If the user has provider credentials configured via opencode auth login, OpenWork shows those providers as connected.
  • If the user has provider credentials configured only via shell env, OpenWork can import those variables (with consent) and providers become connected.
  • If no credentials exist, OpenWork shows the provider catalog but clearly marks providers as “Not connected” (no more “only free exists” ambiguity).
• The model picker includes paid Zen models when the engine has an opencode key.
• Diagnostics page never prints secret values.

Open Questions

• Should OpenWork ever persist imported env vars, or only apply them for the engine process lifetime?
• Where should OpenWork store user-entered keys?
  • In OpenCode’s auth.json via auth.set (simple, portable)
  • In OS keychain, then sync into auth.set on engine start (more secure)
• How should Sidecar and Path engines share auth?
  • Prefer a shared auth store for parity.
  • If isolation is required, provide an explicit “Import credentials from system OpenCode” action.