opencode-ext-connector 0.3.2 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## 0.4.0 - 2026-09-11
+
+- Add explicit `ollamaBaseURL` support for trusted remote and self-hosted Ollama
+  daemons across plugin options, `/connect`, provider projection, runtime, and
+  the `opencode-ext-connector/ollama` SDK entry
+- Preserve daemon path prefixes, isolate process state by normalized base URL,
+  and reject Cloud hosts, credentials, redirects, and ambiguous URL forms
+- Add the preferred connector-wide `credentialManagement: "connector" |
+  "external"` authority policy, capability-gated by each provider adapter
+- Map Claude `"connector"` to automatic refresh with a `60_000` ms lead and
+  writeback, and `"external"` to never-refresh/no-write with credential re-read
+  after 401; omitting all credential-policy options preserves automatic refresh
+  with a `60_000` ms lead and no writeback, while legacy options still control
+  behavior when supplied without `credentialManagement`
+- Keep Cursor direct generation and Command Code read-only under both modes:
+  on an exact HTTP 401 before output or effects, re-read only a changed,
+  non-null credential and retry once; this is neither refresh nor writeback.
+  Cursor legacy/compatibility generation remains one-shot; leave Ollama
+  unaffected
+- Reject combining `credentialManagement` with `credentialRefresh` or
+  `writeBackCredentials`; accept those legacy options alone as deprecated for
+  one migration cycle, with custom lead times still using the legacy config
+
+## 0.3.3 - 2026-09-06
+
+- Document official npm package installation through OpenCode's `plugin` field,
+  including pinned installs, deterministic updates, and removal guidance
+- Maintain active branch history by removing obsolete commit attribution
+  trailers while preserving source trees; existing published tags and
+  provenance remain unchanged
+- Exercise package loading through the exact npm package spec from an isolated
+  offline OpenCode cache with no registry access
+- Harden npm publishing with immutable action and toolchain pins, a no-OIDC
+  verification job, and a checksummed tarball-only OIDC publish job
+- Keep provider and runtime behavior unchanged
+
 ## 0.3.2 - 2026-09-06
 
 - Remove the obsolete npm token fallback so releases publish only through

package/README.md

@@ -2,7 +2,7 @@
 
 # OpenCode External Provider Connector
 
-**One OpenCode plugin configuration for Claude, Cursor, Command Code, and Ollama — using existing vendor sessions and the local Ollama daemon. No new OAuth.**
+**One OpenCode plugin configuration for Claude, Cursor, Command Code, and Ollama — using existing vendor sessions and a trusted Ollama daemon. No new OAuth.**
 
 <p>
   <img src="https://img.shields.io/badge/Bun-%3E%3D1.3.14-000000?style=for-the-badge" alt="Bun >=1.3.14" />
@@ -13,15 +13,15 @@
 
 **English** · [한국어](docs/README.ko.md) · [Documentation](#documentation)
 
-[Status](#status) · [Requirements](#requirements) · [Quick Install](#quick-install) · [Configuration](#configuration) · [First-Time Connection](#first-time-connection) · [Providers](#providers) · [Troubleshooting](#troubleshooting) · [Documentation](#documentation) · [Testing](#testing) · [License and Disclaimer](#license-and-disclaimer)
+[Status](#status) · [Requirements](#requirements) · [Quick Install](#quick-install) · [Configuration](#configuration) · [Host/Guest Sandbox Setup](#hostguest-sandbox-setup) · [Update and Remove](#update-and-remove) · [First-Time Connection](#first-time-connection) · [Providers](#providers) · [Troubleshooting](#troubleshooting) · [Documentation](#documentation) · [Testing](#testing) · [License and Disclaimer](#license-and-disclaimer)
 
 </div>
 
 ## Status
 
-> Independent unofficial community plugin, version **0.3.2**. Package E2E tests exercise the legacy multi-function loader with the OpenCode CLI installed in CI. `@opencode-ai/plugin@1.18.18` is the compile-time plugin API target, not a runtime pin. Source is BSD-3-Clause. This project is not affiliated with, endorsed by, sponsored by, or authorized by OpenCode or any provider. Full terms are in [License and Disclaimer](#license-and-disclaimer).
+> Independent unofficial community plugin, version **0.4.0**. Package E2E tests exercise the legacy multi-function loader with the OpenCode CLI installed in CI. `@opencode-ai/plugin@1.18.18` is the compile-time plugin API target, not a runtime pin. Source is BSD-3-Clause. This project is not affiliated with, endorsed by, sponsored by, or authorized by OpenCode or any provider. Full terms are in [License and Disclaimer](#license-and-disclaimer).
 
-Reuse the Claude, Cursor, Command Code, and Ollama sessions you already have. One `opencode.json` plugin entry publishes live catalogs into OpenCode. Claude and Cursor stay disconnected until OpenCode has a marker or OAuth record and the vendor session is present. Command Code may use an OpenCode-stored direct API key or an existing CLI session/key. Ollama requires the exact session marker plus a responsive localhost daemon.
+Reuse the Claude, Cursor, Command Code, and Ollama sessions you already have. One `opencode.json` plugin entry publishes live catalogs into OpenCode. Claude and Cursor stay disconnected until OpenCode has a marker or OAuth record and the vendor session is present. Command Code may use an OpenCode-stored direct API key or an existing CLI session/key. Ollama requires the exact session marker plus a responsive trusted daemon.
 
 ## Requirements
 
@@ -33,119 +33,239 @@ Reuse the Claude, Cursor, Command Code, and Ollama sessions you already have. On
 | Claude | Existing Claude Code credentials (`~/.claude/.credentials.json` and/or macOS Keychain). The `claude` binary is optional. |
 | Cursor | Existing Cursor CLI login (`~/.config/cursor/auth.json` or `CURSOR_ACCESS_TOKEN`) |
 | Command Code | Existing API key (`COMMAND_CODE_API_KEY` or `~/.commandcode/auth.json`). The `command-code` binary is optional. |
-| Ollama | Installed local daemon running on `localhost:11434`; trust that process; run `ollama signin` separately for Cloud |
+| Ollama | A trusted daemon; defaults to `http://localhost:11434`, with explicit remote/self-hosted URLs supported; run `ollama signin` separately for Cloud |
 
 No vendor CLI has to be installed where OpenCode runs. Claude and Command Code requests carry a client version: the connector takes `ANTHROPIC_CLI_VERSION` / `COMMAND_CODE_CLI_VERSION` when set, otherwise an installed `claude` / `command-code` binary, otherwise the latest version published on the npm registry (`@anthropic-ai/claude-code`, `command-code`). Nothing is pinned in the package.
 
 ## Quick Install
 
-Build this repository, then point OpenCode at the compiled module:
+Choose either the global `~/.config/opencode/opencode.json` or project-level `opencode.json`, then add the package to the official singular `plugin` field:
 
-```bash
-bun install
-bun run build
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    "opencode-ext-connector"
+  ]
+}
 ```
 
-In `opencode.json` / `opencode.jsonc` (official `plugin` field):
+OpenCode installs configured npm plugins with Bun at startup and caches them. For a reproducible installation, use an exact published version instead:
 
 ```jsonc
 {
   "$schema": "https://opencode.ai/config.json",
-  "plugin": [
-    "file:///absolute/path/to/opencode-ext-connector/dist/index.js"
-  ]
+  "plugin": ["opencode-ext-connector@0.4.0"]
 }
 ```
 
-Use that direct `dist/index.js` URL from a trusted, user-owned `file://` build. A package-directory URL does not load this connector's named legacy auth hooks.
+Fully quit and restart OpenCode after adding or changing the entry; a reload is not enough.
 
 The one package entry exposes the catalog plugin plus the Claude, Cursor, Command Code, and Ollama auth hooks. Provider ids: `claude`, `cursor`, `command-code`, `ollama`. Model ids come from each provider's live catalog, with documented fallbacks `default` (Cursor) and `Qwen/Qwen3.8-Max` (Command Code) when a live list is empty.
 
 ## Configuration
 
-OpenCode passes plugin options as the second item of a two-element tuple.
+OpenCode passes plugin options as the second item of a two-element tuple. Use the npm package name as the first item.
 
 Omitted `providers` enables all four. An explicit list is a strict allow-list. Explicit `[]` disables all.
 
 | Option | Default | Meaning |
 | --- | --- | --- |
 | `providers` | all four | Provider ids to register: `claude`, `cursor`, `command-code`, `ollama`; explicit `[]` disables all |
-| `writeBackCredentials` | `false` | After Claude OAuth refresh, write tokens to Claude files, Keychain (macOS), and OpenCode `auth.json` |
-| `credentialRefresh.mode` | `"auto"` | `"auto"` refreshes Claude tokens before expiry; `"never"` sends only what the credential file contains and re-reads that file after a 401 |
-| `credentialRefresh.leadMs` | `60000` | How long before expiry `"auto"` starts refreshing |
+| `ollamaBaseURL` | `"http://localhost:11434"` | Absolute `http` or `https` base for the trusted Ollama daemon; path prefixes are preserved |
+| `credentialManagement` | omitted | Preferred authority policy: `"connector"` authorizes refresh and writeback where an adapter supports both; `"external"` prohibits connector refresh and writeback |
+| `writeBackCredentials` | `false` | **Deprecated:** accepted alone for one migration cycle; controls Claude writeback after refresh |
+| `credentialRefresh.mode` | `"auto"` | **Deprecated:** accepted alone for one migration cycle; controls Claude `"auto"` or `"never"` refresh behavior |
+| `credentialRefresh.leadMs` | `60000` | **Deprecated:** accepted alone for one migration cycle; custom lead times still require this legacy configuration |
 | `catalogReloadMs` | `300000` | Re-run catalog snapshots on this interval; `0` disables |
 | `snapshotTimeoutMs` | `30000` | Per-provider snapshot deadline |
 | `health.initialBackoffMs` | `1000` | Health backoff after a failed snapshot |
 | `health.maximumBackoffMs` | `60000` | Health backoff cap |
 
-Writeback is off by default so this plugin does not mutate credential stores unless asked. Enable it explicitly:
+`credentialManagement: "connector"` authorizes the connector to refresh and write back credentials where a provider adapter supports both. Today only Claude has that capability, mapping to automatic refresh with a `60_000` ms lead and writeback enabled:
 
 ```jsonc
 {
   "$schema": "https://opencode.ai/config.json",
   "plugin": [
     [
-      "file:///absolute/path/to/opencode-ext-connector/dist/index.js",
+      "opencode-ext-connector",
       {
-        "writeBackCredentials": true
+        "credentialManagement": "connector"
       }
     ]
   ]
 }
 ```
 
-Enabled providers remain disconnected until their provider-specific auth rule is met: Claude and Cursor need an OpenCode marker or OAuth record plus the vendor session; Command Code may use an OpenCode-stored direct API key or an existing CLI session/key; Ollama needs the exact session marker plus a responsive localhost daemon.
+Use external authority when another process manages credentials:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    [
+      "opencode-ext-connector",
+      {
+        "credentialManagement": "external"
+      }
+    ]
+  ]
+}
+```
+
+`credentialManagement: "external"` prohibits connector refresh and writeback. Today Claude maps to never-refresh/no-write and can re-read externally managed credentials after a 401. When all credential-policy options are omitted, Claude preserves the legacy defaults: automatic refresh with a `60_000` ms lead and no writeback. If only `credentialManagement` is omitted, supplied deprecated `credentialRefresh` or `writeBackCredentials` options still control behavior. Cursor direct generation and Command Code remain read-only under both modes: on an exact pre-output HTTP 401, they re-read a changed, non-null credential and retry once only. This safe reread is not refresh or writeback, so both modes allow it; Cursor legacy/compatibility generation remains one-shot. Ollama is unaffected. This option does not log in, mint OAuth, synchronize machines, or imply that credentials use file storage.
+
+For one migration cycle, `writeBackCredentials` and `credentialRefresh.*` remain accepted when used without `credentialManagement`; custom `credentialRefresh.leadMs` values still require the legacy configuration. Mixing the new option with either legacy option is rejected with: `` `credentialManagement` cannot be combined with deprecated `credentialRefresh` or `writeBackCredentials` ``.
+
+Enabled providers remain disconnected until their provider-specific auth rule is met: Claude and Cursor need an OpenCode marker or OAuth record plus the vendor session; Command Code may use an OpenCode-stored direct API key or an existing CLI session/key; Ollama needs the exact session marker plus a responsive configured daemon.
+
+To use an explicitly selected remote or self-hosted daemon, set the same flat option on the package entry:
+
+```jsonc
+{
+  "plugin": [["opencode-ext-connector", { "ollamaBaseURL": "https://ollama.example.test/team" }]]
+}
+```
+
+The connector appends `/api/tags`, `/api/pull`, and `/api/chat` to that base. It rejects credentials, query strings, fragments, direct API-route bases, and `ollama.com` hosts. It never reads `OLLAMA_HOST`, sends cookies or authorization headers, follows redirects, configures custom CAs, or disables TLS verification. Ollama has no built-in daemon authentication, so use only a daemon and network path you trust; terminate HTTPS and enforce access policy outside this connector. Distinct normalized bases have isolated catalog leases and pull flights, while equivalent normalized bases share process-local state.
 
 The connector always performs one initial catalog refresh. `snapshotTimeoutMs` applies to each provider snapshot, while `catalogReloadMs: 0` disables only periodic refresh. Periodic refreshes are fixed-delay and single-flight: the next delay begins after the current refresh settles. Health backoff suppresses repeated failures; transient failures retain the last-known catalog, while an explicit unavailable snapshot removes only connector-owned provider data.
 
 OpenCode builds its active provider registry during instance setup. Periodic refresh updates the connector's retained catalog and health state, but new authentication or changed model membership becomes visible after normal OpenCode instance reconstruction. The connector never forces reconstruction or writes generated provider configuration. The `@opencode-ai/plugin@1.18.18` package is the plugin API this connector targets; it is not an OpenCode runtime pin.
 
-With writeback off, refreshed Claude tokens stay in memory only. A stored refresh token that rotates can then stop working on the next process start — set `writeBackCredentials: true` if you want the files updated too.
+With all credential-policy options omitted, refreshed Claude tokens stay in memory only. A stored refresh token that rotates can then stop working on the next process start — choose `credentialManagement: "connector"` if the connector should have authority to write updates too. If only `credentialManagement` is omitted, supplied deprecated options still control refresh and writeback.
 
 ### Sharing one Claude login across machines
 
 Anthropic rotates the refresh token on every refresh and invalidates the previous one. Two copies of `~/.claude/.credentials.json` that both refresh will therefore break each other. Copying the file works only if exactly one machine refreshes and every other machine receives the result before its own copy expires:
 
-- **Owner** (where you log in): `writeBackCredentials: true` and a lead time large enough to publish the file before the copies expire, for example `credentialRefresh: { mode: "auto", leadMs: 1800000 }`.
-- **Every copy**: `credentialRefresh: { mode: "never" }`. That machine never contacts the OAuth endpoint; when a request returns 401 it re-reads the file and retries once with whatever the owner pushed.
-- Push `~/.claude/.credentials.json` from the owner to each copy whenever it changes (a file watcher is enough). OpenCode's own `auth.json` only needs the `anthropic` record once; leave its other providers alone.
+- **Refresh authority** (where you log in): `credentialManagement: "connector"`. If you need a custom publication window, use the deprecated legacy options alone for this migration cycle, for example `writeBackCredentials: true` with `credentialRefresh: { mode: "auto", leadMs: 1800000 }`.
+- **External-authority machines**: `credentialManagement: "external"`. They never contact the OAuth endpoint; when a request returns 401 they re-read externally managed credentials and retry once.
+- Synchronize the externally managed credential material from the refresh-authority machine whenever it changes. The option itself does not synchronize machines or require file storage; if you copy `~/.claude/.credentials.json`, OpenCode's own `auth.json` only needs the `anthropic` record once and its other providers should remain untouched.
 
 Machines that refresh on their own — including a Claude Code install that is used interactively — must not share the file. Log in separately there.
 
+## Host/Guest Sandbox Setup
+
+When OpenCode runs in a container, VM, or another sandbox, treat that runtime as the **guest** and the machine that owns the vendor logins and Ollama daemon as the **host**. The guest has its own `localhost`, home directory, environment, keychains, filesystem permissions, and network namespace. Host sessions are not visible unless you mount their files or inject their environment values explicitly.
+
+The safest shared-session layout keeps each vendor login owned and refreshed by the host, mounts only the required vendor credential source read-only, and gives the guest a separate writable persistent OpenCode data directory:
+
+| Provider | Host | Guest |
+| --- | --- | --- |
+| Claude | Own and refresh the Claude Code login | Mount the Claude credential directory read-only, set `CLAUDE_CONFIG_DIR` to that guest path, and use `credentialManagement: "external"`; a host macOS Keychain is not available inside a Linux guest; resolve the client version with `ANTHROPIC_CLI_VERSION`, an installed `claude` binary, or npm registry access |
+| Cursor | Own the Cursor CLI login | Mount the credential file at the guest's `${HOME}/.config/cursor/auth.json` read-only, or inject `CURSOR_ACCESS_TOKEN` through the sandbox's secret mechanism; install Node.js 22 or later in the guest |
+| Command Code | Own the CLI login or API key | Mount `${HOME}/.commandcode/auth.json` read-only, or inject `COMMAND_CODE_API_KEY`; resolve the client version with `COMMAND_CODE_CLI_VERSION`, an installed `command-code` binary, or npm registry access |
+| Ollama | Run the trusted daemon and run `ollama signin` there when Cloud access is needed | Copy no Ollama credential; connect only to the daemon selected by `ollamaBaseURL` |
+
+For example, a Linux guest can use these paths and optional secret/version overrides; adapt the mount source and destination to the sandbox runtime:
+
+```dotenv
+HOME=/home/sandbox
+XDG_DATA_HOME=/home/sandbox/.local/share
+CLAUDE_CONFIG_DIR=/run/host-credentials/claude
+CURSOR_ACCESS_TOKEN=<optional-sandbox-secret>
+COMMAND_CODE_API_KEY=<optional-sandbox-secret>
+ANTHROPIC_CLI_VERSION=<optional-compatible-version>
+COMMAND_CODE_CLI_VERSION=<optional-compatible-version>
+```
+
+Set a writable persistent `XDG_DATA_HOME` for the guest. `/connect` writes OpenCode auth state to `${XDG_DATA_HOME}/opencode/auth.json`, or on Linux to `${HOME}/.local/share/opencode/auth.json` when `XDG_DATA_HOME` is unset. That file may contain a secret Claude OAuth record or Command Code API key; Cursor and Ollama use non-secret CLI-session markers, and Command Code can use either a marker or a key. Protect it as a secret-bearing file. Do not mount the entire host OpenCode data directory read-only when guest `/connect` or Claude writeback must update it.
+
+Use this complete guest `opencode.json` when all four providers are enabled and the host owns the shared credentials:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    [
+      "opencode-ext-connector",
+      {
+        "providers": ["claude", "cursor", "command-code", "ollama"],
+        "ollamaBaseURL": "http://host.docker.internal:11434",
+        "credentialManagement": "external",
+        "catalogReloadMs": 300000,
+        "snapshotTimeoutMs": 30000,
+        "health": {
+          "initialBackoffMs": 1000,
+          "maximumBackoffMs": 60000
+        }
+      }
+    ]
+  ]
+}
+```
+
+`ollamaBaseURL` is a flat connector option in the package tuple, not an OpenCode provider option. The numeric values above are the connector defaults; `credentialManagement: "external"` and the host daemon URL are deliberate overrides for read-only host-owned credentials. Do not put vendor tokens in `opencode.json`; pass them through read-only mounts or the sandbox's secret injection mechanism.
+
+For Docker Desktop, `host.docker.internal` normally resolves to the host. A Linux Docker bridge may also need `--add-host=host.docker.internal:host-gateway` or the Compose equivalent:
+
+```yaml
+extra_hosts:
+  - "host.docker.internal:host-gateway"
+```
+
+Ollama normally listens on host loopback. For bridge networking, the host may need to start it with `OLLAMA_HOST=0.0.0.0:11434`; restrict the exposed port with host firewall and sandbox network policy. `OLLAMA_HOST` configures the host daemon, while `ollamaBaseURL` configures this connector in the guest. Host networking makes guest `localhost` reach the host but reduces isolation and should be an explicit choice. Other sandbox runtimes need an equivalent host route and must allow outbound access to each enabled provider; allow `registry.npmjs.org` only when Claude or Command Code cannot resolve its client version from an environment value or installed binary.
+
+Alternatively, the guest can own its vendor logins in persistent guest storage. In that mode, run vendor login flows in the guest instead of mounting host credentials. A guest that is the sole Claude refresh owner may use `credentialManagement: "connector"`. Never let the host and guest independently refresh credentials descended from the same Claude refresh token.
+
+## Update and Remove
+
+To update deterministically, check the desired published version, replace the `plugin` entry with that exact spec, then fully restart OpenCode:
+
+```bash
+npm view opencode-ext-connector version
+```
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["opencode-ext-connector@<version>"]
+}
+```
+
+Do not rely on an unpinned entry to refresh its cached package automatically on restart. To remove the connector, remove its entry from `plugin` and fully restart OpenCode. Cached package files are inert when the package is not configured.
+
 ## First-Time Connection
 
-1. **Fully restart OpenCode** after adding the plugin URL. Quit the process and start it again so the named legacy auth hooks load. A reload or periodic catalog refresh is not instance reconstruction.
-2. **Confirm local prerequisites** for the providers you enabled. Claude and Cursor need their vendor sessions. Command Code needs either an API key you will store in OpenCode or an existing CLI session/key. Ollama needs a process you trust on `http://localhost:11434`; Cloud still requires a separate `ollama signin`.
-3. **Run `/connect`** for each provider you want. Claude and Cursor record a marker or OAuth entry only after the vendor session is available. Command Code can store a direct API key in OpenCode or reuse an existing CLI session/key. Ollama stores the exact session marker only when the localhost daemon responds. Models publish only after that provider-specific rule is met.
+If OpenCode runs in a sandbox, complete [Host/Guest Sandbox Setup](#hostguest-sandbox-setup), including writable OpenCode auth storage and host networking, before `/connect`.
+
+1. **Fully restart OpenCode** after adding the npm package entry or version spec. Quit the process and start it again so the named legacy auth hooks load. A reload or periodic catalog refresh is not instance reconstruction.
+2. **Confirm local prerequisites** for the providers you enabled. Claude and Cursor need their vendor sessions. Command Code needs either an API key you will store in OpenCode or an existing CLI session/key. Ollama needs a daemon you trust at the configured `ollamaBaseURL`; Cloud still requires a separate `ollama signin`.
+3. **Run `/connect`** for each provider you want. Claude and Cursor record a marker or OAuth entry only after the vendor session is available. Command Code can store a direct API key in OpenCode or reuse an existing CLI session/key. Ollama stores the exact session marker only when the configured daemon responds. Models publish only after that provider-specific rule is met.
 4. **Verify the catalogs.** Confirm Claude, Cursor, and Command Code models appear in OpenCode. For Ollama, run `opencode models ollama` and confirm locally pulled models plus Cloud tags discovered unauthenticated, without connector-supplied credentials.
 
-Ollama `/connect` probes the local daemon and stores the exact session marker. It does not run `ollama signin` or handle Ollama credentials.
+Ollama `/connect` probes the configured daemon and stores the exact session marker. It does not run `ollama signin` or handle Ollama credentials.
 
 ## Providers
 
 | Provider | What it does |
 | --- | --- |
-| **Claude** | Reuses existing Claude Code credentials. Does not mint OAuth. Compatibility fetch sends CLI-compatible request metadata and streams Anthropic SSE on the built-in `anthropic` path. `writeBackCredentials` defaults to `false` (in-memory refresh only); `true` writes refreshed tokens to Claude files, macOS Keychain, and OpenCode `auth.json`. |
-| **Cursor** | Calls Cursor's unpublished client protocol (`api2.cursor.sh` `AgentService`, Connect+protobuf over HTTP/2) with the CLI access token. A plugin-owned Node child communicates over private stdio, keeps tool results on the same bidi Run, never replays parked calls, opens no user-facing daemon, and never spawns `cursor-agent` for generation. Unofficial; not a public Cursor API. After protocol drift there is no implicit fallback — that provider fails. Requires Node.js 22 or later. Live catalog ids are used when present; otherwise the documented fallback is `default`. |
-| **Command Code** | Calls `/alpha/generate` with CLI-compatible request metadata and streams provider-local NDJSON text and tool events. The client version comes from `COMMAND_CODE_CLI_VERSION`, an installed `command-code` binary, or the npm registry. Request metadata includes Node.js version, platform, architecture, and the absolute working directory. Live catalog ids are used when present; otherwise the documented fallback is `Qwen/Qwen3.8-Max`. |
-| **Ollama** | Uses only the local daemon at `http://localhost:11434` with fixed `/api/tags`, `/api/pull`, and `/api/chat`. Trust the process bound to that port. Publishes models already pulled locally, plus exact Cloud tags discovered unauthenticated from Ollama's official Cloud search and library pages, without connector-supplied credentials. Local entries win exact duplicates. Incomplete Cloud refreshes retain the last complete list. Selecting an absent authorized Cloud tag pulls its lightweight remote reference on first use; concurrent pulls of the same tag share one in-flight request, and a failed pull can be retried later. The local daemon may then proxy Cloud-tag prompts under the user's Ollama Cloud subscription. The connector never uses an Ollama API key, the usage-billed direct Cloud API, `OLLAMA_HOST`, or a remote Cloud generation endpoint. |
+| **Claude** | Reuses existing Claude Code credentials. Does not mint OAuth. Compatibility fetch sends CLI-compatible request metadata and streams Anthropic SSE on the built-in `anthropic` path. `credentialManagement: "connector"` maps to auto-refresh with a `60_000` ms lead and writeback; `"external"` maps to never-refresh/no-write with a credential re-read after 401. Omitting all credential-policy options preserves legacy auto/`60_000` behavior without writeback; if only `credentialManagement` is omitted, supplied deprecated options still control behavior. |
+| **Cursor** | Calls Cursor's unpublished client protocol (`api2.cursor.sh` `AgentService`, Connect+protobuf over HTTP/2) with the CLI access token. Credentials remain read-only under both credential-management modes. Direct generation may re-read a changed, non-null credential and retry once only on an exact HTTP 401 before output or effects; this is not refresh or writeback. Legacy/compatibility generation remains one-shot. A plugin-owned Node child communicates over private stdio, keeps tool results on the same bidi Run, never replays parked calls, opens no user-facing daemon, and never spawns `cursor-agent` for generation. Unofficial; not a public Cursor API. After protocol drift there is no implicit fallback — that provider fails. Requires Node.js 22 or later. Live catalog ids are used when present; otherwise the documented fallback is `default`. |
+| **Command Code** | Calls `/alpha/generate` with CLI-compatible request metadata and streams provider-local NDJSON text and tool events. Credentials remain read-only under both credential-management modes. On an exact HTTP 401 before output or effects, it may re-read a changed, non-null credential and retry once only; this is not refresh or writeback. The client version comes from `COMMAND_CODE_CLI_VERSION`, an installed `command-code` binary, or the npm registry. Request metadata includes Node.js version, platform, architecture, and the absolute working directory. Live catalog ids are used when present; otherwise the documented fallback is `Qwen/Qwen3.8-Max`. |
+| **Ollama** | Unaffected by `credentialManagement`. Uses the trusted daemon selected by `ollamaBaseURL` (default `http://localhost:11434`) with `/api/tags`, `/api/pull`, and `/api/chat`; path prefixes are preserved. Publishes models already pulled there, plus exact Cloud tags discovered anonymously from Ollama's official Cloud search and library pages, without connector-supplied credentials. Local entries win exact duplicates. Incomplete Cloud refreshes retain the last complete list. Selecting an absent authorized Cloud tag pulls its lightweight remote reference on first use; concurrent pulls of the same tag and normalized base share one in-flight request, and a failed pull can be retried later. The daemon may then proxy Cloud-tag prompts under the user's Ollama Cloud subscription. The connector never uses an Ollama API key, the usage-billed direct Cloud API, `OLLAMA_HOST`, credentials, custom headers, cookies, or a direct Cloud generation endpoint. |
 
 Provider health is isolated: one provider failing does not remove the others.
 
-The standalone SDK entry is `opencode-ext-connector/ollama`. It can generate with models already present in the local daemon; connector-managed Cloud auto-pull requires an active Ollama catalog lease.
+The standalone SDK entry is `opencode-ext-connector/ollama`; pass `{ ollamaBaseURL }` to select the same trusted daemon. It can generate with models already present there; connector-managed Cloud auto-pull requires an active Ollama catalog lease for that normalized base.
 
 ## Troubleshooting
 
 | Symptom | What to check |
 | --- | --- |
-| `/connect` methods missing | The plugin URL must be a trusted, user-owned `file:///absolute/path/to/opencode-ext-connector/dist/index.js`. A package-directory URL does not load named legacy auth hooks. Fully restart OpenCode after changing it. |
-| Provider enabled but no models | Omitted `providers` enables all four; an explicit list is a strict allow-list. Claude and Cursor need a marker or OAuth record plus the vendor session; Command Code may use an OpenCode-stored API key or a CLI session/key; Ollama needs the exact marker plus a responsive localhost daemon. Fully restart after `/connect` so instance reconstruction picks up new membership. |
-| Claude works until the next start | Default `writeBackCredentials: false` keeps refreshed tokens in memory. A rotated refresh token then fails on the next process start unless writeback is enabled. |
-| Claude reports `invalid_grant` on a copied credential file | Another copy of the same login already refreshed and rotated the refresh token. Give one machine ownership of refresh and set `credentialRefresh: { mode: "never" }` on the others, or log in separately. |
+| `/connect` methods missing | Confirm `plugin` contains `"opencode-ext-connector"` or an exact published `"opencode-ext-connector@<version>"` spec, then fully restart OpenCode. |
+| Provider enabled but no models | Omitted `providers` enables all four; an explicit list is a strict allow-list. Claude and Cursor need a marker or OAuth record plus the vendor session; Command Code may use an OpenCode-stored API key or a CLI session/key; Ollama needs the exact marker plus a responsive configured daemon. Fully restart after `/connect` so instance reconstruction picks up new membership. |
+| Claude works until the next start | Omitting all credential-policy options preserves legacy in-memory refresh without writeback. A rotated refresh token can then fail on the next process start; use `credentialManagement: "connector"` when the connector should refresh and write back. If only `credentialManagement` is omitted, check supplied deprecated refresh/writeback options instead. |
+| Claude reports `invalid_grant` on shared credentials | Another machine with the same login already refreshed and rotated the refresh token. Give one machine refresh authority with `credentialManagement: "connector"` and use `"external"` on the others, or log in separately. |
+| Configuration rejects credential options | Do not combine the new and legacy options; the exact error is: `` `credentialManagement` cannot be combined with deprecated `credentialRefresh` or `writeBackCredentials` ``. Legacy options remain accepted alone for one migration cycle. |
 | `Claude Code client version is unavailable` | No `ANTHROPIC_CLI_VERSION`, no `claude` binary, and `registry.npmjs.org` was unreachable. Set the variable or allow registry access. |
 | Cursor generation fails | Node.js 22 or later is required. Generation uses the unpublished protocol through a private Node child, not `cursor-agent`. Protocol drift fails that provider; there is no implicit fallback. |
 | Command Code generation fails | The client version could not be resolved: set `COMMAND_CODE_CLI_VERSION`, install `command-code`, or allow access to `registry.npmjs.org`. Request metadata includes Node.js version, platform, architecture, and the absolute working directory. |
-| Ollama missing from `opencode models ollama` | Start a process you trust on `localhost:11434`, then `/connect` so the exact session marker can be stored. Cloud tags are unauthenticated catalog entries without connector-supplied credentials; the local daemon may proxy Cloud-tag prompts. `OLLAMA_HOST`, API keys, and direct Cloud generation are not used. |
+| Ollama missing from `opencode models ollama` | Start a daemon you trust at `ollamaBaseURL` (or the default `localhost:11434`), then `/connect` so the exact session marker can be stored. Confirm any path prefix reaches Ollama's `/api/*` routes. Cloud tags are anonymous catalog entries; `OLLAMA_HOST`, API keys, credential headers, redirects, and direct Cloud generation are not used. |
+| Host credentials exist but the guest provider is disconnected | Check the mount target and permissions, the guest's `HOME`, `CLAUDE_CONFIG_DIR`, injected secret environment, writable guest OpenCode `auth.json`, and whether `/connect` completed inside the guest. |
+| Ollama works on the host but not in the guest | Guest `localhost` is usually not the host. Check `host.docker.internal` resolution, Linux `host-gateway` mapping, the daemon bind address, firewall and sandbox egress, and whether any base path prefix reaches Ollama's `/api/*` routes. |
 | One provider is down | Failures are isolated. Transient snapshot failures keep the last-known catalog; an unavailable snapshot removes only that connector-owned provider. |
 
 ## Documentation

package/dist/core/options.d.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import type { HealthPolicy } from "./health.js";
 export type CredentialRefreshMode = "auto" | "never";
+export type CredentialManagement = "connector" | "external";
 export type CredentialRefreshPolicy = {
     readonly mode: CredentialRefreshMode;
     readonly leadMs: number;
@@ -8,7 +9,10 @@ export type CredentialRefreshPolicy = {
 export type ConnectorOptionsInput = {
     readonly providers?: readonly ("claude" | "cursor" | "command-code" | "ollama")[] | undefined;
     readonly snapshotTimeoutMs?: number | undefined;
+    readonly credentialManagement?: CredentialManagement | undefined;
+    /** @deprecated Use credentialManagement instead. */
     readonly writeBackCredentials?: boolean | undefined;
+    /** @deprecated Use credentialManagement instead. */
     readonly credentialRefresh?: {
         readonly mode?: CredentialRefreshMode | undefined;
         readonly leadMs?: number | undefined;

package/dist/core/options.js

@@ -4,16 +4,40 @@ const PositiveSafeIntegerSchema = z.number().int().positive().max(MaximumTimerMs
 const NonNegativeSafeIntegerSchema = z.number().int().nonnegative().max(MaximumTimerMs);
 const ProviderSchema = z.enum(["claude", "cursor", "command-code", "ollama"]);
 const CredentialRefreshModeSchema = z.enum(["auto", "never"]);
+const CredentialManagementSchema = z.enum(["connector", "external"]);
 const DefaultProviders = [
     "claude",
     "cursor",
     "command-code",
     "ollama",
 ];
+function resolveCredentialOptions(input) {
+    switch (input.credentialManagement) {
+        case undefined:
+            return {
+                credentialRefresh: Object.freeze({
+                    mode: input.credentialRefresh?.mode ?? "auto",
+                    leadMs: input.credentialRefresh?.leadMs ?? 60_000,
+                }),
+                writeBackCredentials: input.writeBackCredentials ?? false,
+            };
+        case "connector":
+            return {
+                credentialRefresh: Object.freeze({ mode: "auto", leadMs: 60_000 }),
+                writeBackCredentials: true,
+            };
+        case "external":
+            return {
+                credentialRefresh: Object.freeze({ mode: "never", leadMs: 60_000 }),
+                writeBackCredentials: false,
+            };
+    }
+}
 const ConnectorOptionsInputSchema = z
     .object({
     providers: z.array(ProviderSchema).optional(),
     snapshotTimeoutMs: PositiveSafeIntegerSchema.optional(),
+    credentialManagement: CredentialManagementSchema.optional(),
     writeBackCredentials: z.boolean().optional(),
     credentialRefresh: z
         .object({
@@ -33,6 +57,14 @@ const ConnectorOptionsInputSchema = z
 })
     .strict()
     .superRefine((input, context) => {
+    if (input.credentialManagement !== undefined &&
+        (input.credentialRefresh !== undefined || input.writeBackCredentials !== undefined)) {
+        context.addIssue({
+            code: "custom",
+            path: ["credentialManagement"],
+            message: "`credentialManagement` cannot be combined with deprecated `credentialRefresh` or `writeBackCredentials`",
+        });
+    }
     const initialBackoffMs = input.health?.initialBackoffMs ?? 1_000;
     const maximumBackoffMs = input.health?.maximumBackoffMs ?? 60_000;
     if (initialBackoffMs > maximumBackoffMs) {
@@ -44,15 +76,12 @@ export const ConnectorOptionsSchema = ConnectorOptionsInputSchema.transform((inp
         initialBackoffMs: input.health?.initialBackoffMs ?? 1_000,
         maximumBackoffMs: input.health?.maximumBackoffMs ?? 60_000,
     });
-    const credentialRefresh = Object.freeze({
-        mode: input.credentialRefresh?.mode ?? "auto",
-        leadMs: input.credentialRefresh?.leadMs ?? 60_000,
-    });
+    const credentialOptions = resolveCredentialOptions(input);
     return Object.freeze({
         providers: Object.freeze(input.providers ?? DefaultProviders),
         snapshotTimeoutMs: input.snapshotTimeoutMs ?? 30_000,
-        writeBackCredentials: input.writeBackCredentials ?? false,
-        credentialRefresh,
+        writeBackCredentials: credentialOptions.writeBackCredentials,
+        credentialRefresh: credentialOptions.credentialRefresh,
         catalogReloadMs: input.catalogReloadMs ?? 300_000,
         health,
     });

package/dist/opencode/host-options.d.ts

@@ -1,2 +1,9 @@
 import type { ConnectorOptionsInput } from "../core/options.js";
-export declare function pickConnectorOptionsInput(input: unknown): ConnectorOptionsInput;
+type HostConnectorOptionsInput = Omit<ConnectorOptionsInput, "credentialManagement" | "credentialRefresh" | "writeBackCredentials"> & {
+    readonly credentialManagement?: unknown;
+    readonly credentialRefresh?: unknown;
+    readonly writeBackCredentials?: unknown;
+};
+export declare function pickConnectorOptionsInput(input: unknown): HostConnectorOptionsInput;
+export declare function pickOllamaBaseURL(input: unknown): unknown;
+export {};

package/dist/opencode/host-options.js

@@ -11,9 +11,6 @@ function pickCredentialRefresh(value) {
     const rawMode = "mode" in value ? value.mode : undefined;
     const mode = rawMode === "auto" || rawMode === "never" ? rawMode : undefined;
     const leadMs = "leadMs" in value ? nonNegativeInteger(value.leadMs) : undefined;
-    if (mode === undefined && leadMs === undefined) {
-        return undefined;
-    }
     return { mode, leadMs };
 }
 function pickHealth(value) {
@@ -31,6 +28,20 @@ export function pickConnectorOptionsInput(input) {
     if (typeof input !== "object" || input === null) {
         return {};
     }
+    const preservesCredentialPolicy = "credentialManagement" in input &&
+        (input.credentialManagement === "connector" || input.credentialManagement === "external");
+    const writeBackCredentials = "writeBackCredentials" in input && input.writeBackCredentials !== undefined
+        ? preservesCredentialPolicy
+            ? input.writeBackCredentials
+            : typeof input.writeBackCredentials === "boolean"
+                ? input.writeBackCredentials
+                : undefined
+        : undefined;
+    const credentialRefresh = "credentialRefresh" in input && input.credentialRefresh !== undefined
+        ? preservesCredentialPolicy
+            ? input.credentialRefresh
+            : pickCredentialRefresh(input.credentialRefresh)
+        : undefined;
     return {
         providers: "providers" in input && Array.isArray(input.providers)
             ? input.providers.filter((provider) => provider === "claude" ||
@@ -39,11 +50,17 @@ export function pickConnectorOptionsInput(input) {
                 provider === "ollama")
             : undefined,
         snapshotTimeoutMs: "snapshotTimeoutMs" in input ? positiveInteger(input.snapshotTimeoutMs) : undefined,
-        writeBackCredentials: "writeBackCredentials" in input && typeof input.writeBackCredentials === "boolean"
-            ? input.writeBackCredentials
-            : undefined,
-        credentialRefresh: "credentialRefresh" in input ? pickCredentialRefresh(input.credentialRefresh) : undefined,
+        ...(writeBackCredentials === undefined ? {} : { writeBackCredentials }),
+        ...(!("credentialManagement" in input) || input.credentialManagement === undefined
+            ? {}
+            : { credentialManagement: input.credentialManagement }),
+        ...(credentialRefresh === undefined ? {} : { credentialRefresh }),
         catalogReloadMs: "catalogReloadMs" in input ? nonNegativeInteger(input.catalogReloadMs) : undefined,
         health: "health" in input ? pickHealth(input.health) : undefined,
     };
 }
+export function pickOllamaBaseURL(input) {
+    return typeof input === "object" && input !== null && "ollamaBaseURL" in input
+        ? input.ollamaBaseURL
+        : undefined;
+}

package/dist/opencode/language-factory.d.ts

@@ -7,7 +7,7 @@ export type ConnectorLanguageDeps = {
     readonly transport: HttpTransport;
     readonly readClaudeToken: (signal: AbortSignal) => Promise<string | null>;
     readonly cursorRuntime: CursorDirectRuntime;
-    readonly ollamaRuntime: OllamaRuntime;
+    readonly ollamaRuntime?: OllamaRuntime;
     readonly commandCodeApiKey?: string;
 };
 export declare function createConnectorLanguage(deps: ConnectorLanguageDeps): (providerID: string, modelId: string) => LanguageModelV3 | null;

package/dist/opencode/language-factory.js

@@ -30,6 +30,9 @@ export function createConnectorLanguage(deps) {
             });
         }
         if (providerID === "ollama") {
+            if (deps.ollamaRuntime === undefined) {
+                return null;
+            }
             return createOllamaLanguageModel({ modelId, runtime: deps.ollamaRuntime });
         }
         return null;

package/dist/opencode/ollama-probe.d.ts

@@ -1,2 +1,3 @@
+import type { OllamaEndpoints } from "../providers/ollama/endpoints.js";
 import type { OllamaFetch } from "../providers/ollama/http.js";
-export declare function probeLocalOllama(fetch: OllamaFetch): Promise<boolean>;
+export declare function probeLocalOllama(fetch: OllamaFetch, endpoints: OllamaEndpoints): Promise<boolean>;

package/dist/opencode/ollama-probe.js

@@ -2,9 +2,9 @@ import { OperationCancelledError } from "../core/errors.js";
 import { OllamaCatalogError } from "../providers/ollama/errors.js";
 import { listLocalOllamaModels } from "../providers/ollama/local-catalog.js";
 const OLLAMA_PROBE_TIMEOUT_MS = 5_000;
-export async function probeLocalOllama(fetch) {
+export async function probeLocalOllama(fetch, endpoints) {
     try {
-        await listLocalOllamaModels(fetch, AbortSignal.timeout(OLLAMA_PROBE_TIMEOUT_MS));
+        await listLocalOllamaModels(fetch, AbortSignal.timeout(OLLAMA_PROBE_TIMEOUT_MS), endpoints);
         return true;
     }
     catch (error) {

package/dist/opencode/ollama-production.d.ts

@@ -1,4 +1,11 @@
 import { type OllamaCatalogState } from "../providers/ollama/catalog-state.js";
+import { type OllamaEndpoints } from "../providers/ollama/endpoints.js";
 import { type OllamaRuntime } from "../providers/ollama/runtime.js";
+export type ProductionOllamaBundle = {
+    readonly endpoints: OllamaEndpoints;
+    readonly catalog: OllamaCatalogState;
+    readonly runtime: OllamaRuntime;
+};
+export declare function getProductionOllamaBundle(input?: unknown): ProductionOllamaBundle;
 export declare const productionOllamaCatalog: OllamaCatalogState;
 export declare const productionOllamaRuntime: OllamaRuntime;

package/dist/opencode/ollama-production.js

@@ -1,10 +1,22 @@
 import { createOllamaCatalogState, } from "../providers/ollama/catalog-state.js";
+import { parseOllamaEndpoints } from "../providers/ollama/endpoints.js";
 import { productionOllamaFetch } from "../providers/ollama/http.js";
 import { createOllamaRuntime } from "../providers/ollama/runtime.js";
-export const productionOllamaCatalog = createOllamaCatalogState({
-    fetch: productionOllamaFetch,
-});
-export const productionOllamaRuntime = createOllamaRuntime({
-    catalog: productionOllamaCatalog,
-    fetch: productionOllamaFetch,
-});
+const bundles = new Map();
+export function getProductionOllamaBundle(input) {
+    const endpoints = parseOllamaEndpoints(input);
+    const existing = bundles.get(endpoints.baseURL);
+    if (existing !== undefined)
+        return existing;
+    const catalog = createOllamaCatalogState({ fetch: productionOllamaFetch });
+    const bundle = Object.freeze({
+        endpoints,
+        catalog,
+        runtime: createOllamaRuntime({ endpoints, catalog, fetch: productionOllamaFetch }),
+    });
+    bundles.set(endpoints.baseURL, bundle);
+    return bundle;
+}
+const defaultBundle = getProductionOllamaBundle();
+export const productionOllamaCatalog = defaultBundle.catalog;
+export const productionOllamaRuntime = defaultBundle.runtime;