Python
Add custom OpenAI-compatible providers
Mumit Khane9777cbb1baa
diff --git a/README.md b/README.mdindex b5281a55..c6db7374 100644--- a/README.md+++ b/README.md@@ -91,6 +91,8 @@ Model access is yours: pick a provider, paste your key, switch anytime. SupporteA curated model list marks what we've verified for tool-calling work. Adding any model string works at your own risk.+Need another Chat Completions gateway? In **Settings → Models**, choose **Custom provider** and enter its endpoint, Bearer API key, and a short route prefix. Add the gateway's model IDs manually; for example, an OpenRouter route named `openrouter` uses `openrouter:anthropic/claude-…`. This supports standard OpenAI-compatible APIs without OpenWorker maintaining their full catalog.+## PrivacyOpenWorker is local-first. Everything lives on your machine: the agent loop, your conversations, connector tokens, and model keys - all in the app's local secret store. The only cloud piece is a small service that brokers OAuth handshakes for connectors. You can always use the App without signing-in - use the connectors via manually-created credentials/API-keys.diff --git a/coworker/providers/__init__.py b/coworker/providers/__init__.pyindex d38da557..d154b4d1 100644--- a/coworker/providers/__init__.py+++ b/coworker/providers/__init__.py@@ -19,6 +19,8 @@ from .registry import (descriptor_configured,detect_provider,get_descriptor,+ is_custom_provider,+ is_removed_custom_provider,provider_descriptors,provider_names,verify_provider_key,@@ -47,6 +49,8 @@ __all__ = ["provider_descriptors","provider_names","get_descriptor",+ "is_custom_provider",+ "is_removed_custom_provider","build_provider_client","descriptor_configured","detect_provider",diff --git a/coworker/providers/registry.py b/coworker/providers/registry.pyindex 6dc5a6df..32f39efa 100644--- a/coworker/providers/registry.py+++ b/coworker/providers/registry.py@@ -31,6 +31,9 @@ from .openai_responses import OpenAIResponsesProviderfrom .vertex_provider import VertexProviderDEFAULT_OLLAMA_URL = "http://localhost:11434"+# The index deliberately lives in the SecretStore too: it names profiles which contain+# credentials, and keeping the two together makes a future secure-store backend a drop-in.+CUSTOM_PROVIDERS_PROFILE = "providers:custom"@dataclass(frozen=True)@@ -380,6 +383,50 @@ def _responses_compat()+def _custom_provider_descriptor(name: str, title: str) -> ProviderDescriptor:+ """Descriptor synthesized for a user-defined OpenAI-compatible endpoint.++ Unlike the built-ins there is no catalog or capability claim here. The endpoint and+ bearer key are required; model ids are supplied separately by the user.+ """+ return ProviderDescriptor(+ name=name,+ title=title,+ needs_key=True,+ fields=[+ ProviderField("api_key", f"{title} API key", secret=True),+ ProviderField(+ "base_url",+ "Endpoint",+ required=True,+ placeholder="https://…/v1",+ help="An HTTPS OpenAI-compatible API base URL ending in /v1. HTTP is allowed only for local gateways.",+ ),+ ],+ build=_openai_compat(title, ""),+ blurb="Uses the standard OpenAI Chat Completions API. Add model IDs manually below.",+ )+++def _disabled_custom_provider_descriptor(name: str, title: str) -> ProviderDescriptor:+ """Keep a removed route recognizable so old sessions fail closed, never reroute."""++ def build(profile: dict[str, Any], secrets: Any) -> ProviderClient:+ raise RuntimeError(+ f"{title} was removed from Settings ▸ Models. Configure that provider again "+ "before continuing this session."+ )++ return ProviderDescriptor(+ name=name,+ title=title,+ needs_key=True,+ fields=[],+ build=build,+ blurb="Removed custom provider.",+ )++DESCRIPTORS: list[ProviderDescriptor] = [ProviderDescriptor(name="openai",@@ -894,23 +941,78 @@ DESCRIPTORS: list[ProviderDescriptor] = [_BY_NAME = {d.name: d for d in DESCRIPTORS}-def provider_descriptors() -> list[ProviderDescriptor]:- return list(DESCRIPTORS)---def provider_names() -> list[str]:- return [d.name for d in DESCRIPTORS]---def get_descriptor(name: str) -> Optional[ProviderDescriptor]:- return _BY_NAME.get(name)+def _custom_provider_titles(secrets: Any = None) -> dict[str, str]:+ """Return the validated custom-provider index without exposing credentials."""+ if secrets is None:+ return {}+ raw = secrets.get(CUSTOM_PROVIDERS_PROFILE) or {}+ providers = raw.get("providers") if isinstance(raw, dict) else None+ if not isinstance(providers, dict):+ return {}+ return {+ name: title+ for name, title in providers.items()+ if isinstance(name, str)+ and isinstance(title, str)+ and name not in _BY_NAME+ and title.strip()+ }+++def _removed_custom_provider_titles(secrets: Any = None) -> dict[str, str]:+ """Routes kept as tombstones after deletion to protect existing sessions."""+ if secrets is None:+ return {}+ raw = secrets.get(CUSTOM_PROVIDERS_PROFILE) or {}+ removed = raw.get("removed") if isinstance(raw, dict) else None+ if not isinstance(removed, dict):+ return {}+ return {+ name: title+ for name, title in removed.items()+ if isinstance(name, str)+ and isinstance(title, str)+ and name not in _BY_NAME+ and title.strip()+ }+++def is_custom_provider(name: str, secrets: Any = None) -> bool:+ return name in _custom_provider_titles(secrets)+++def is_removed_custom_provider(name: str, secrets: Any = None) -> bool:+ return name in _removed_custom_provider_titles(secrets)+++def provider_descriptors(secrets: Any = None) -> list[ProviderDescriptor]:+ custom = [+ _custom_provider_descriptor(name, title)+ for name, title in _custom_provider_titles(secrets).items()+ ]+ return [*DESCRIPTORS, *custom]+++def provider_names(secrets: Any = None) -> list[str]:+ return [d.name for d in provider_descriptors(secrets)]+++def get_descriptor(name: str, secrets: Any = None) -> Optional[ProviderDescriptor]:+ builtin = _BY_NAME.get(name)+ if builtin is not None:+ return builtin+ title = _custom_provider_titles(secrets).get(name)+ if title:+ return _custom_provider_descriptor(name, title)+ title = _removed_custom_provider_titles(secrets).get(name)+ return _disabled_custom_provider_descriptor(name, title) if title else Nonedef build_provider_client(name: str, profile: dict[str, Any], secrets: Any) -> ProviderClient:"""Build a `ProviderClient` for `name` from its stored profile. Unknown → OpenAI default."""- descriptor = _BY_NAME.get(name) or _BY_NAME["openai"]+ descriptor = get_descriptor(name, secrets) or _BY_NAME["openai"]return descriptor.build(profile or {}, secrets)@@ -1180,6 +1282,7 @@ def verify_provider_key(base_url: Optional[str] = None,fields: Optional[dict[str, Any]] = None,timeout: float = 10.0,+ descriptor: Optional[ProviderDescriptor] = None,) -> dict[str, Any]:"""Validate a provider's credentials with one cheap call — usually list models.@@ -1190,7 +1293,7 @@ def verify_provider_key("""import httpx- d = _BY_NAME.get(name) or _BY_NAME["openai"]+ d = descriptor or _BY_NAME.get(name) or _BY_NAME["openai"]key = (api_key or "").strip()if d.auth == "oauth":# OAuth providers verify from their stored tokens (needs the SecretStore),@@ -1306,6 +1409,14 @@ def verify_provider_key(if resp.status_code < 300:return {"ok": True}+ if resp.status_code in (404, 405) and d.name not in _BY_NAME:+ # Chat Completions compatibility does not require the optional model-list+ # endpoint. The gateway was reached, so do not call a usable custom route+ # invalid merely because it cannot provide a catalog.+ return {+ "ok": True,+ "warning": "Endpoint reached, but it does not expose /models. Add a model ID and try a chat to finish checking it.",+ }if resp.status_code in (401, 403):if name == "ollama":return {"ok": False, "error": "Server rejected the request."}diff --git a/coworker/providers/router.py b/coworker/providers/router.pyindex c2c56c47..4a6d7f19 100644--- a/coworker/providers/router.py+++ b/coworker/providers/router.py@@ -51,7 +51,7 @@ class ProviderRouter(ProviderClient):"""if ":" in model:prefix = model.split(":", 1)[0]- if get_descriptor(prefix) is not None:+ if get_descriptor(prefix, getattr(self, "_secrets", None)) is not None:return prefixreturn self._default@@ -68,14 +68,14 @@ class ProviderRouter(ProviderClient):return client@staticmethod- def _bare(model: str) -> str:+ def _bare(model: str, secrets: Any = None) -> str:"""Strip a KNOWN provider prefix; the underlying SDK wants the bare model name. A modelwhose first segment isn't a provider (e.g. `qwen2.5-coder:32b` — a version tag, not aprefix) is returned unchanged, so the colon isn't mistaken for a provider separator."""if ":" in model:prefix, rest = model.split(":", 1)- if get_descriptor(prefix) is not None:+ if get_descriptor(prefix, secrets) is not None:return restreturn model@@ -98,7 +98,7 @@ class ProviderRouter(ProviderClient):):self._note_use(model)return self._client_for(model).complete(- model=self._bare(model), messages=messages, tools=tools, **settings+ model=self._bare(model, self._secrets), messages=messages, tools=tools, **settings)def stream(@@ -111,7 +111,7 @@ class ProviderRouter(ProviderClient):):self._note_use(model)return self._client_for(model).stream(- model=self._bare(model), messages=messages, tools=tools, **settings+ model=self._bare(model, self._secrets), messages=messages, tools=tools, **settings)def capabilities(self, model: str):diff --git a/coworker/server/app.py b/coworker/server/app.pyindex c4d4f672..d32b38b5 100644--- a/coworker/server/app.py+++ b/coworker/server/app.py@@ -2393,6 +2393,13 @@ def create_app(manager: SessionManager) -> FastAPI:return manager.set_provider(name, (body or {}).get("fields"))return await asyncio.to_thread(manager.set_provider, name, (body or {}).get("fields"))+ @app.post("/v1/providers/custom")+ def providers_custom_create(body: dict) -> dict[str, Any]:+ body = body or {}+ return manager.create_custom_provider(+ body.get("name", ""), body.get("title", ""), body.get("fields")+ )+@app.delete("/v1/providers/{name}")async def providers_remove(name: str) -> dict[str, Any]:if name == "openrouter-account":diff --git a/coworker/server/manager.py b/coworker/server/manager.pyindex 12a4939f..8b75a8ea 100644--- a/coworker/server/manager.py+++ b/coworker/server/manager.py@@ -8,6 +8,7 @@ sessions span folders.from __future__ import annotationsimport asyncio+import ipaddressimport threadingimport jsonimport logging@@ -21,6 +22,7 @@ import timeimport uuidfrom pathlib import Pathfrom typing import Any, Optional+from urllib.parse import urlsplitfrom .. import model_config as _model_configfrom ..agent import build_engine@@ -84,9 +86,12 @@ from ..providers import (ProviderRouter,descriptor_configured,get_descriptor,+ is_custom_provider,+ is_removed_custom_provider,provider_descriptors,verify_provider_key,)+from ..providers.registry import CUSTOM_PROVIDERS_PROFILEfrom ..secrets import SecretStore, state_dirfrom ..sessions import SessionRecord, usage_totalsfrom ..teams import Actor as TeamActor@@ -115,6 +120,28 @@ _SCOPES = {s.value for s in Scope}logger = logging.getLogger("coworker.manager")+def _custom_endpoint_error(url: str) -> Optional[str]:+ """Allow HTTPS everywhere; plaintext HTTP only for an explicitly local gateway."""+ try:+ parsed = urlsplit((url or "").strip())+ except ValueError:+ return "Enter a valid HTTPS endpoint."+ if parsed.scheme == "https" and parsed.hostname:+ return None+ if parsed.scheme != "http" or not parsed.hostname:+ return "Endpoint must be an HTTPS URL (for example, https://gateway.example/v1)."+ host = parsed.hostname.lower()+ if host == "localhost":+ return None+ try:+ address = ipaddress.ip_address(host)+ except ValueError:+ return "HTTP endpoints are allowed only for localhost or a private IP address."+ if address.is_loopback or address.is_private:+ return None+ return "HTTP endpoints are allowed only for localhost or a private IP address."++def _grants_of(engine) -> dict[str, Any]:"""The engine's session-scoped "Always allow" approvals, in persistable shape."""tools = sorted(getattr(engine.permissions, "session_allow_tools", None) or ())@@ -4162,7 +4189,7 @@ class SessionManager:non-secret field values (e.g. the Ollama base URL) ARE returned so the form can prefill."""out: list[dict[str, Any]] = []- for d in provider_descriptors():+ for d in provider_descriptors(self.secrets):profile = self.secrets.get(f"provider:{d.name}") or {}configured = descriptor_configured(d, profile)values = {@@ -4189,6 +4216,7 @@ class SessionManager:"last_used_at": (self._prefs.get("provider_last_used") or {}).get(d.name),+ "is_custom": is_custom_provider(d.name, self.secrets),}if d.kind == "local":# A keyless server is "connected" when it answers (cached probes), not@@ -4207,6 +4235,51 @@ class SessionManager:out.append(row)return out+ def create_custom_provider(+ self, name: str, title: str, fields: Optional[dict[str, Any]]+ ) -> dict[str, Any]:+ """Create a named OpenAI-compatible provider, then save its first credentials.++ The short slug is the stable model-route prefix (``slug:model-id``), so it is+ deliberately immutable and restricted to a transport-safe subset.+ """+ name = (name or "").strip().lower()+ title = (title or "").strip()+ if not re.fullmatch(r"[a-z][a-z0-9_-]{0,31}", name):+ return {+ "ok": False,+ "error": "Route prefix must start with a letter and use only lowercase letters, numbers, - or _.",+ }+ if not title or len(title) > 80:+ return {"ok": False, "error": "Enter a provider name (up to 80 characters)."}+ if get_descriptor(name) is not None or is_custom_provider(name, self.secrets):+ return {"ok": False, "error": "That route prefix is already in use."}+ fields = fields or {}+ base_url = str(fields.get("base_url") or "").strip()+ endpoint_error = _custom_endpoint_error(base_url)+ if endpoint_error:+ return {"ok": False, "error": endpoint_error}+ if not str(fields.get("api_key") or "").strip():+ return {"ok": False, "error": "Enter an API key."}++ index = dict(self.secrets.get(CUSTOM_PROVIDERS_PROFILE) or {})+ providers = dict(index.get("providers") or {})+ removed = dict(index.get("removed") or {})+ previous_removed = dict(removed)+ providers[name] = title+ removed.pop(name, None) # re-creating a route clears its fail-closed tombstone+ self.secrets.put(+ CUSTOM_PROVIDERS_PROFILE, {"providers": providers, "removed": removed}+ )+ saved = self.set_provider(name, fields)+ if not saved.get("ok"):+ providers.pop(name, None)+ self.secrets.put(+ CUSTOM_PROVIDERS_PROFILE,+ {"providers": providers, "removed": previous_removed},+ )+ return saved+def pick_native_folder(self) -> dict[str, Any]:"""Open the OS folder picker FROM THE SIDECAR — the browser GUI can't obtain absolutepaths from web file dialogs, but the sidecar is local and can (the desktop shell uses@@ -4303,9 +4376,11 @@ class SessionManager:) -> dict[str, Any]:"""Store a provider's config in its `provider:<name>` SecretStore profile and rebuildits cached client. Merges provided fields into any existing profile."""- d = get_descriptor(name)+ d = get_descriptor(name, self.secrets)if d is None:return {"ok": False, "error": f"unknown provider: {name}"}+ if is_removed_custom_provider(name, self.secrets):+ return {"ok": False, "error": "provider was removed; create it again first"}fields = fields or {}profile = dict(self.secrets.get(f"provider:{name}") or {})for f in d.fields:@@ -4321,6 +4396,10 @@ class SessionManager:missing = [f.label for f in d.fields if f.required and not profile.get(f.key)]if missing:return {"ok": False, "error": "missing: " + ", ".join(missing)}+ if is_custom_provider(name, self.secrets):+ endpoint_error = _custom_endpoint_error(str(profile.get("base_url") or ""))+ if endpoint_error:+ return {"ok": False, "error": endpoint_error}# A (re)pasted key stamps its save date — Settings shows "key added <date>" so stale# keys are visible. Endpoint-only saves keep the original stamp.if isinstance(fields.get("api_key"), str) and fields["api_key"].strip():@@ -4366,7 +4445,7 @@ class SessionManager:"""Forget a provider's stored config (Settings ▸ Models "Remove key"). The whole`provider:<name>` profile goes — key, endpoint, key_set_at — so the provider readsas never configured. Curated models stay; they just gray out until a new key."""- d = get_descriptor(name)+ d = get_descriptor(name, self.secrets)if d is None:return {"ok": False, "error": f"unknown provider: {name}"}env_var = d.env_key if (d.env_key and os.environ.get(d.env_key)) else None@@ -4385,6 +4464,31 @@ class SessionManager:),}self.secrets.delete(f"provider:{name}")+ if is_custom_provider(name, self.secrets):+ index = dict(self.secrets.get(CUSTOM_PROVIDERS_PROFILE) or {})+ providers = dict(index.get("providers") or {})+ removed = dict(index.get("removed") or {})+ title = providers.pop(name, d.title)+ removed[name] = title+ self.secrets.put(+ CUSTOM_PROVIDERS_PROFILE,+ {"providers": providers, "removed": removed},+ )+ # A deleted custom route must not remain selectable and accidentally fall+ # through to the default OpenAI provider as an unknown ``prefix:model``.+ prefix = name + ":"+ self._prefs["models"] = [+ m for m in self._prefs.get("models", []) if not str(m).startswith(prefix)+ ]+ self._prefs["hidden_models"] = [+ m+ for m in self._prefs.get("hidden_models", [])+ if not str(m).startswith(prefix)+ ]+ if str(self.model).startswith(prefix):+ self.model = "gpt-5.6-sol"+ self._prefs["default_model"] = self.model+ self._save_prefs()self._refresh_provider(name)out: dict[str, Any] = {"ok": True, "provider": name}if env_var:@@ -4453,7 +4557,7 @@ class SessionManager:a field blank (e.g. testing an already-configured provider)."""import os- d = get_descriptor(name)+ d = get_descriptor(name, self.secrets)if d is None:return {"ok": False, "error": f"unknown provider: {name}"}if d.auth == "oauth":@@ -4482,20 +4586,27 @@ class SessionManager:missing = [f.label for f in d.fields if f.required and not merged.get(f.key)]if missing:return {"ok": False, "error": "missing: " + ", ".join(missing)}+ # A verification call sends the key to the supplied endpoint too. Apply the+ # same transport policy as Save so an unsaved edit cannot accidentally+ # send a credential over plaintext to a remote host.+ if is_custom_provider(name, self.secrets):+ endpoint_error = _custom_endpoint_error(merged.get("base_url", ""))+ if endpoint_error:+ return {"ok": False, "error": endpoint_error}return verify_provider_key(- name, api_key=api_key, base_url=merged.get("base_url", ""), fields=merged+ name, api_key=api_key, base_url=merged.get("base_url", ""), fields=merged, descriptor=d)def _model_provider(self, model: str) -> str:"""The provider a model string routes to (known `prefix:` or the OpenAI default)."""if ":" in (model or ""):prefix = model.split(":", 1)[0]- if get_descriptor(prefix) is not None:+ if get_descriptor(prefix, self.secrets) is not None:return prefixreturn "openai"def _provider_configured(self, name: str) -> bool:- d = get_descriptor(name)+ d = get_descriptor(name, self.secrets)if d is None:return Falsereturn descriptor_configured(d, self.secrets.get(f"provider:{name}") or {})diff --git a/surfaces/gui/src/api.ts b/surfaces/gui/src/api.tsindex 1a9cf81b..fe5b0df1 100644--- a/surfaces/gui/src/api.ts+++ b/surfaces/gui/src/api.ts@@ -2517,6 +2517,7 @@ export interface ProviderInfo {// How Models & Keys groups it: a server on the user's own hardware, a plan signed// into, or an API key. Absent on an older backend → treated as an API key.kind?: "local" | "subscription" | "api_key";+ is_custom?: boolean; // user-created OpenAI-compatible provider// Local servers only: whether the server answers right now (cached probe).alive?: boolean;signed_in?: boolean;@@ -2737,6 +2738,20 @@ export async function setProvider(return res.json();}+/** Create a named, user-configured OpenAI-compatible provider. */+export async function createCustomProvider(+ name: string,+ title: string,+ fields: Record<string, string>,+): Promise<{ ok: boolean; error?: string; provider?: string }> {+ const res = await fetch(`${httpBase()}/v1/providers/custom`, {+ method: "POST",+ headers: { "Content-Type": "application/json" },+ body: JSON.stringify({ name, title, fields }),+ });+ return res.json();+}+/** Forget a provider's stored config (Settings ▸ Models "Remove key…"). */export async function removeProvider(name: string): Promise<{ ok: boolean; error?: string }> {const res = await fetch(`${httpBase()}/v1/providers/${encodeURIComponent(name)}`, {@@ -2749,7 +2764,7 @@ export async function removeProvider(name: string): Promise<{ ok: boolean; errorexport async function verifyProvider(name: string,fields: Record<string, string>,-): Promise<{ ok: boolean; error?: string }> {+): Promise<{ ok: boolean; error?: string; warning?: string }> {const res = await fetch(`${httpBase()}/v1/providers/verify`, {method: "POST",headers: { "Content-Type": "application/json" },diff --git a/surfaces/gui/src/components/ManageTabs.test.tsx b/surfaces/gui/src/components/ManageTabs.test.tsxnew file mode 100644index 00000000..39f4072d--- /dev/null+++ b/surfaces/gui/src/components/ManageTabs.test.tsx@@ -0,0 +1,92 @@+import { afterEach, expect, it, vi } from "vitest";+import { cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react";+import { ModelsTab } from "./ManageTabs";++afterEach(() => {+ cleanup();+ vi.unstubAllGlobals();+});++it("creates a custom provider and opens its manual-model configuration", async () => {+ let created = false;+ const calls: Array<{ url: string; method: string; body?: unknown }> = [];+ vi.stubGlobal(+ "fetch",+ vi.fn(async (url: string, init?: RequestInit) => {+ const method = (init?.method || "GET").toUpperCase();+ calls.push({+ url,+ method,+ body: init?.body ? JSON.parse(String(init.body)) : undefined,+ });+ if (url.includes("/v1/providers/custom") && method === "POST") {+ created = true;+ return { json: async () => ({ ok: true, provider: "openrouter" }) } as Response;+ }+ if (url.includes("/v1/providers")) {+ const providers: any[] = [+ {+ name: "openai",+ title: "OpenAI",+ needs_key: true,+ fields: [{ key: "api_key", label: "OpenAI API key", secret: true, required: true }],+ configured: false,+ values: {},+ suggested_models: [],+ recommended_model: "gpt-5.6-sol",+ },+ ];+ if (created) {+ providers.push({+ name: "openrouter",+ title: "OpenRouter",+ needs_key: true,+ fields: [+ { key: "api_key", label: "OpenRouter API key", secret: true, required: true },+ { key: "base_url", label: "Endpoint", secret: false, required: true, placeholder: "https://…/v1" },+ ],+ configured: true,+ values: { base_url: "https://openrouter.ai/api/v1" },+ suggested_models: [],+ recommended_model: null,+ is_custom: true,+ });+ }+ return { json: async () => providers } as Response;+ }+ if (url.includes("/v1/settings")) {+ return {+ json: async () => ({+ model: "gpt-5.6-sol",+ models: ["gpt-5.6-sol"],+ model_labels: {},+ source: null,+ }),+ } as Response;+ }+ return { json: async () => ({ ok: true }) } as Response;+ }),+ );++ render(<ModelsTab />);+ fireEvent.click(await screen.findByTestId("set-provider-custom-add"));+ fireEvent.change(screen.getByLabelText("Provider name"), { target: { value: "OpenRouter" } });+ fireEvent.change(screen.getByLabelText("Route prefix"), { target: { value: "openrouter" } });+ fireEvent.change(screen.getByLabelText("Endpoint"), { target: { value: "https://openrouter.ai/api/v1" } });+ fireEvent.change(screen.getByLabelText("API key"), { target: { value: "or-test" } });+ fireEvent.click(screen.getByRole("button", { name: "Add provider" }));++ await waitFor(() => {+ expect(calls.find((c) => c.url.includes("/v1/providers/custom")))?.toMatchObject({+ method: "POST",+ body: {+ name: "openrouter",+ title: "OpenRouter",+ fields: { base_url: "https://openrouter.ai/api/v1", api_key: "or-test" },+ },+ });+ });+ expect((await screen.findByTestId("set-field-base_url") as HTMLInputElement).value).toBe(+ "https://openrouter.ai/api/v1",+ );+});diff --git a/surfaces/gui/src/components/ManageTabs.tsx b/surfaces/gui/src/components/ManageTabs.tsxindex 920b7f68..96f46a9c 100644--- a/surfaces/gui/src/components/ManageTabs.tsx+++ b/surfaces/gui/src/components/ManageTabs.tsx@@ -6,6 +6,7 @@ import {connectConnector,connectManaged,connectMcpBacked,+ createCustomProvider,disallowUser,getSettings,getSubscriptions,@@ -47,6 +48,7 @@ const relTime = (epoch?: number | null): string | null => {// when Settings/Activity became full-page surfaces): ModelsTab → Settings ▸ Models; ConnectorsTab →// Integrations ▸ Connectors (the MCP tab retired into the Connectors page, UX-034).const SEC_H = "text-label text-faint font-medium";+const CARD = "rounded-xl2 border border-line bg-panel";const BTN_BORDERED ="text-ui px-3 py-1.5 rounded-lg border border-line bg-paper hover:border-lineStrong shrink-0";const BTN_ACCENT = "text-ui px-3 py-1.5 rounded-lg bg-accent text-white shrink-0 disabled:opacity-50";@@ -78,10 +80,11 @@ export function ProviderKeyFooter({className="text-ui text-danger/80 hover:text-danger hover:underline underline-offset-2"data-testid="set-remove-key"onClick={() => {- if (window.confirm(t("manage.remove_key_confirm", { title: info?.title || "" }))) onRemove();+ const key = info?.is_custom ? "manage.remove_provider_confirm" : "manage.remove_key_confirm";+ if (window.confirm(t(key, { title: info?.title || "" }))) onRemove();}}>- {t("manage.remove_key")}+ {t(info?.is_custom ? "manage.remove_provider" : "manage.remove_key")}</button>);}@@ -97,6 +100,8 @@ export function ModelsTab() {// The Pick a model dialog (UX-055): "" closed, "+" picking, else the model to configure.const [dialog, setDialog] = useState<string>("");const [settingsError, setSettingsError] = useState(false);+ const [addingCustom, setAddingCustom] = useState(false);+ const [openCustom, setOpenCustom] = useState<string | null>(null);const refreshSettings = () => {setSettingsError(false);getSettings()@@ -118,6 +123,13 @@ export function ModelsTab() {} catch { /* private window */ }}, []);+ useEffect(() => {+ if (openCustom && ps.providers.some((p) => p.name === openCustom)) {+ setOpenCustom(null);+ ps.openProvider(openCustom);+ }+ }, [openCustom, ps.providers]);+// #43: a failed or hung settings fetch says so and offers Retry (same shape as the// local-models status line below) instead of sitting on "Loading…" forever.if (settingsError) {@@ -152,7 +164,19 @@ export function ModelsTab() {if (ps.sel === null) {return (<div>- <ProviderGroups ps={ps} tp="set" models={settings.models} />+ {addingCustom ? (+ <CustomProviderForm+ onCancel={() => setAddingCustom(false)}+ onCreated={async (name) => {+ setAddingCustom(false);+ setOpenCustom(name);+ await ps.refreshProviders();+ refreshSettings();+ }}+ />+ ) : (+ <ProviderGroups ps={ps} tp="set" models={settings.models} onAddCustom={() => setAddingCustom(true)} />+ )}<ComposerPickerCard settings={settings} providers={ps.providers} onChanged={refreshSettings} onPick={() => setDialog("+")} onConfigure={(m) => setDialog(m)} />{dialogEl}</div>@@ -237,6 +261,63 @@ export function ModelsTab() {);}+/** First-run form for a generic OpenAI-compatible provider. It intentionally does+ * not fetch a model catalog: users add the exact model ids their gateway exposes. */+function CustomProviderForm({+ onCancel,+ onCreated,+}: {+ onCancel: () => void;+ onCreated: (name: string) => Promise<void>;+}) {+ const [title, setTitle] = useState("");+ const [name, setName] = useState("");+ const [baseUrl, setBaseUrl] = useState("");+ const [apiKey, setApiKey] = useState("");+ const [error, setError] = useState<string | null>(null);+ const [saving, setSaving] = useState(false);+ const input = "w-full px-3 py-2 rounded-lg border border-line bg-panel text-[13.5px] outline-none focus:border-accent";++ const save = async () => {+ setSaving(true);+ setError(null);+ const result: { ok: boolean; error?: string; provider?: string } = await createCustomProvider(+ name,+ title,+ { base_url: baseUrl, api_key: apiKey },+ ).catch(() => ({ ok: false, error: "unreachable" }));+ setSaving(false);+ if (!result.ok || !result.provider) {+ setError(result.error || "Couldn’t add provider.");+ return;+ }+ await onCreated(result.provider);+ };++ return (+ <div className={CARD + " p-4 max-w-xl"} data-testid="set-custom-provider-form">+ <div className="text-[15px] font-semibold">Add OpenAI-compatible provider</div>+ <p className="text-[12px] text-muted mt-1 leading-relaxed">+ This provider uses Chat Completions with Bearer authentication. Use HTTPS unless the gateway is local; you’ll add its model IDs manually next.+ </p>+ <label className="block text-[12px] text-muted mt-3 mb-1" htmlFor="custom-provider-title">Provider name</label>+ <input id="custom-provider-title" className={input} value={title} placeholder="OpenRouter" onChange={(e) => setTitle(e.target.value)} />+ <label className="block text-[12px] text-muted mt-3 mb-1" htmlFor="custom-provider-route">Route prefix</label>+ <input id="custom-provider-route" className={input} value={name} placeholder="openrouter" spellCheck={false} autoCapitalize="none" onChange={(e) => setName(e.target.value.toLowerCase())} />+ <p className="text-[11.5px] text-faint mt-1">Models will be selected as <code>openrouter:model-id</code>.</p>+ <label className="block text-[12px] text-muted mt-3 mb-1" htmlFor="custom-provider-endpoint">Endpoint</label>+ <input id="custom-provider-endpoint" className={input} value={baseUrl} placeholder="https://…/v1" spellCheck={false} autoCapitalize="none" onChange={(e) => setBaseUrl(e.target.value)} />+ <label className="block text-[12px] text-muted mt-3 mb-1" htmlFor="custom-provider-key">API key</label>+ <input id="custom-provider-key" className={input} type="password" value={apiKey} placeholder="…" autoComplete="off" onChange={(e) => setApiKey(e.target.value)} />+ {error && <div className="text-[12.5px] text-warnInk mt-3">{error}</div>}+ <div className="flex gap-2 mt-4">+ <button className={BTN_ACCENT} disabled={saving} onClick={() => void save()}>{saving ? "Adding…" : "Add provider"}</button>+ <button className={BTN_BORDERED} onClick={onCancel}>Cancel</button>+ </div>+ </div>+ );+}+// The gallery view's "In the composer's picker" card: every curated model across providers,// with its provider tag. Unticking removes it from the picker; adding happens from a// provider's card (the ModelChecklist there has the suggested list + free-type add).diff --git a/surfaces/gui/src/components/models/ProviderGroups.tsx b/surfaces/gui/src/components/models/ProviderGroups.tsxindex cba51e8b..5aa26bbd 100644--- a/surfaces/gui/src/components/models/ProviderGroups.tsx+++ b/surfaces/gui/src/components/models/ProviderGroups.tsx@@ -39,10 +39,12 @@ export function ProviderGroups({ps,tp,models,+ onAddCustom,}: {ps: ProviderSetupState;tp: string;models: string[]; // the picker's models, for the count on each card+ onAddCustom?: () => void; // Settings: the "Custom provider" card at the end of the API-keys group}) {const { t } = useTranslation();const [query, setQuery] = useState("");@@ -110,6 +112,19 @@ export function ProviderGroups({{/* A long group (API keys) shows two rows, then a "Show N more" line expands it in place. */}<div className="grid grid-cols-2 xl:grid-cols-3 gap-3" data-testid={`provider-grid-${kind}`}>{(expanded.has(kind) || q ? cards : cards.slice(0, FOLD)).map(cardFor)}+ {kind === "api_key" && onAddCustom && (expanded.has(kind) || q || cards.length <= FOLD) && (+ <button+ className={card + " border-dashed bg-transparent text-muted hover:text-ink"}+ data-testid={`${tp}-provider-custom-add`}+ onClick={onAddCustom}+ >+ <span className="rounded-lg border border-line grid place-items-center shrink-0 text-[20px]" style={{ width: 32, height: 32 }}>+ ++ </span>+ <span className="min-w-0 flex-1 text-ui font-semibold">{t("manage.custom_provider_card")}</span>+ <span className="text-faint text-body">›</span>+ </button>+ )}</div>{!q && cards.length > FOLD && (<buttondiff --git a/surfaces/gui/src/locales/en.json b/surfaces/gui/src/locales/en.jsonindex c1fecfe0..0d82c75a 100644--- a/surfaces/gui/src/locales/en.json+++ b/surfaces/gui/src/locales/en.json@@ -1347,6 +1347,9 @@"remove_from_picker": "Remove from the picker","remove_key": "Remove key…","remove_key_confirm": "Remove the {{title}} key from this computer?",+ "remove_provider": "Remove provider…",+ "remove_provider_confirm": "Remove the {{title}} provider and its key from this computer?",+ "custom_provider_card": "Custom provider","signin_unlocks": "Sign-in unlocks the one-click {{title}} connect — or connect manually below.","tool_asks_approval": "{{name}} · {{kind}} · asks approval","tools_exposed": "Tools exposed to OpenWorker",diff --git a/surfaces/gui/src/locales/zh.json b/surfaces/gui/src/locales/zh.jsonindex fa111121..04fee473 100644--- a/surfaces/gui/src/locales/zh.json+++ b/surfaces/gui/src/locales/zh.json@@ -1330,6 +1330,9 @@"remove_from_picker": "从选择器中移除","remove_key": "移除密钥…","remove_key_confirm": "从本机移除 {{title}} 密钥?",+ "remove_provider": "移除提供商…",+ "remove_provider_confirm": "从本机移除 {{title}} 提供商及其密钥?",+ "custom_provider_card": "自定义提供商","signin_unlocks": "登录即可解锁 {{title}} 一键连接 —— 或在下方手动连接。","tool_asks_approval": "{{name}} · {{kind}} · 需审批","tools_exposed": "向 OpenWorker 提供的工具",diff --git a/surfaces/gui/src/providers/ProviderSetup.tsx b/surfaces/gui/src/providers/ProviderSetup.tsxindex 1227b51f..e7992287 100644--- a/surfaces/gui/src/providers/ProviderSetup.tsx+++ b/surfaces/gui/src/providers/ProviderSetup.tsx@@ -162,7 +162,9 @@ export function useProviderSetup(opts?: { onSaved?: () => void }): ProviderSetupsetFields(next);setDirty(!!draft && Object.values(draft).some(Boolean));setVerify({ state: "idle" });- setShowEndpoint(false);+ // A custom provider cannot work without its endpoint, so keep that field+ // visible instead of hiding it behind the built-ins' expert disclosure.+ setShowEndpoint(!!p?.fields.find((f) => f.key === "base_url")?.required);};const backToGallery = () => {@@ -180,14 +182,16 @@ export function useProviderSetup(opts?: { onSaved?: () => void }): ProviderSetupconst runTestAndSave = async (): Promise<boolean> => {if (!sel) return false;setVerify({ state: "testing" });- const res = await verifyProvider(sel, fields).catch(() => ({ ok: false, error: t("provider.err_unreachable") }));+ const res: { ok: boolean; error?: string; warning?: string } = await verifyProvider(sel, fields).catch(+ () => ({ ok: false, error: t("provider.err_unreachable") }),+ );if (!res.ok) {setVerify({ state: "error", msg: res.error || t("provider.err_couldnt_verify") });return false;}if (dirty || !info?.configured) await setProvider(sel, fields).catch(() => {});if (!info?.needs_key) setKeylessOk((s) => new Set(s).add(sel));- setVerify({ state: "ok" });+ setVerify({ state: "ok", msg: res.warning });setDirty(false);setDrafts((d) => ({ ...d, [sel]: {} }));await refreshProviders();@@ -196,11 +200,15 @@ export function useProviderSetup(opts?: { onSaved?: () => void }): ProviderSetup// the timeout would fire its stale closure (dirty/fields from before the save) and// re-stash the just-saved key as a draft — the state-restore bug (owner catch// 2026-07-19). This return path clears the draft unconditionally.- backTimer.current = window.setTimeout(() => {- setDrafts((d) => ({ ...d, [sel]: {} }));- setSel(null);- setVerify({ state: "idle" });- }, 900);+ // A catalog-less gateway is still usable, but its warning contains the next action;+ // leave the form open instead of making it disappear after the usual success animation.+ if (!res.warning) {+ backTimer.current = window.setTimeout(() => {+ setDrafts((d) => ({ ...d, [sel]: {} }));+ setSel(null);+ setVerify({ state: "idle" });+ }, 900);+ }return true;};@@ -413,11 +421,13 @@ export function ProviderCards({tp,gridClass = "grid grid-cols-2 gap-2.5",lastUsed = false,+ onAddCustom,}: {ps: ProviderSetupState;tp: string; // testid prefix ("ob" onboarding, "set" settings)gridClass?: string;lastUsed?: boolean;+ onAddCustom?: () => void;}) {const card ="flex items-center gap-2.5 rounded-xl border border-line bg-panel px-3 py-2.5 text-left hover:border-lineStrong transition-colors";@@ -438,6 +448,19 @@ export function ProviderCards({<span className="text-faint text-body">›</span></button>))}+ {onAddCustom && (+ <button+ className={card + " border-dashed text-muted hover:text-ink"}+ data-testid={`${tp}-provider-custom-add`}+ onClick={onAddCustom}+ >+ <span className="rounded-lg border border-line grid place-items-center shrink-0 text-[20px]" style={{ width: 32, height: 32 }}>+ ++ </span>+ <span className="min-w-0 flex-1 text-[13px] font-semibold">Custom provider</span>+ <span className="text-faint text-[14px]">›</span>+ </button>+ )}</div>);}@@ -700,6 +723,7 @@ export function ProviderForm({{/* Error line: fixed height so failures never reflow the form. */}<div className="mt-3 min-h-[19px] text-ui">{ps.verify.state === "error" && <span className="text-warnInk">{ps.verify.msg}</span>}+ {ps.verify.state === "ok" && ps.verify.msg && <span className="text-muted">{ps.verify.msg}</span>}</div>{info?.auth === "oauth" ? null : footer}</div>diff --git a/tests/test_provider_router.py b/tests/test_provider_router.pyindex ccf9bdd8..3781f449 100644--- a/tests/test_provider_router.py+++ b/tests/test_provider_router.py@@ -5,6 +5,8 @@ from __future__ import annotationsfrom types import SimpleNamespace+import pytest+from coworker.providers import (AssistantTurn,ModelCapabilities,@@ -391,6 +393,110 @@ def test_manager_provider_config(tmp_path, monkeypatch):assert mgr.set_provider("nope", {})["ok"] is False # unknown provider rejected+def test_custom_openai_compatible_provider_routes_and_persists(tmp_path, monkeypatch):+ """A custom route owns its key/endpoint and strips only its own prefix. The slug+ must not be a built-in provider's name (openrouter is one now), so a neutral one."""+ monkeypatch.setenv("COWORKER_STATE_DIR", str(tmp_path / "state"))+ from coworker.server.manager import SessionManager++ mgr = SessionManager(data_dir=tmp_path)+ created = mgr.create_custom_provider(+ "acme",+ "Acme Gateway",+ {"api_key": "acme-test", "base_url": "https://llm.acme.example/v1"},+ )+ assert created["ok"] is True and created["provider"] == "acme"++ providers = {p["name"]: p for p in mgr.get_providers()}+ assert providers["acme"]["is_custom"] is True+ assert providers["acme"]["values"] == {+ "base_url": "https://llm.acme.example/v1"+ }+ assert "acme-test" not in str(providers)++ router = mgr.provider+ assert router._provider_name("acme:anthropic/claude-example") == "acme"+ assert (+ router._bare("acme:anthropic/claude-example", mgr.secrets)+ == "anthropic/claude-example"+ )+ client = router._client_for("acme:anthropic/claude-example")+ assert client._api_key == "acme-test" and client._base_url == "https://llm.acme.example/v1"++ mgr.add_model("acme:anthropic/claude-example")+ assert "acme:anthropic/claude-example" in mgr.get_settings()["models"]+ assert mgr.remove_provider("acme")["ok"] is True+ assert "acme" not in {p["name"] for p in mgr.get_providers()}+ assert "acme:anthropic/claude-example" not in mgr.get_settings()["models"]+ # Existing sessions retain the full routed model id. After removal that must+ # fail locally, never fall through to whichever provider is now the default.+ assert router._provider_name("acme:anthropic/claude-example") == "acme"+ with pytest.raises(RuntimeError, match="was removed"):+ router.complete(model="acme:anthropic/claude-example", messages=[])++ # Re-creating the same route intentionally clears its tombstone.+ assert mgr.create_custom_provider(+ "acme",+ "Acme Gateway",+ {"api_key": "acme-recreated", "base_url": "https://llm.acme.example/v1"},+ )["ok"]+ assert router._client_for("acme:anthropic/claude-example")._api_key == "acme-recreated"+++def test_custom_provider_requires_safe_route_and_complete_config(tmp_path, monkeypatch):+ monkeypatch.setenv("COWORKER_STATE_DIR", str(tmp_path / "state"))+ from coworker.server.manager import SessionManager++ mgr = SessionManager(data_dir=tmp_path)+ assert not mgr.create_custom_provider("Bad Name", "Gateway", {})["ok"]+ assert not mgr.create_custom_provider(+ "gateway", "Gateway", {"api_key": "x", "base_url": "gateway.example/v1"}+ )["ok"]+ assert not mgr.create_custom_provider(+ "remote-http", "Remote HTTP", {"api_key": "x", "base_url": "http://example.com/v1"}+ )["ok"]+ assert mgr.create_custom_provider(+ "local-http", "Local HTTP", {"api_key": "x", "base_url": "http://127.0.0.1:8000/v1"}+ )["ok"]+++def test_custom_provider_verify_allows_missing_models_endpoint(tmp_path, monkeypatch):+ monkeypatch.setenv("COWORKER_STATE_DIR", str(tmp_path / "state"))+ from coworker.server.manager import SessionManager++ mgr = SessionManager(data_dir=tmp_path)+ assert mgr.create_custom_provider(+ "gateway", "Gateway", {"api_key": "test", "base_url": "https://gateway.example/v1"}+ )["ok"]++ monkeypatch.setattr(+ "httpx.get", lambda *args, **kwargs: SimpleNamespace(status_code=404)+ )+ checked = mgr.verify_provider("gateway", {})+ assert checked["ok"] is True and "does not expose /models" in checked["warning"]+++def test_custom_provider_verify_applies_endpoint_transport_policy(tmp_path, monkeypatch):+ monkeypatch.setenv("COWORKER_STATE_DIR", str(tmp_path / "state"))+ from coworker.server.manager import SessionManager++ mgr = SessionManager(data_dir=tmp_path)+ assert mgr.create_custom_provider(+ "gateway", "Gateway", {"api_key": "test", "base_url": "https://gateway.example/v1"}+ )["ok"]++ # Verify accepts unsaved form fields, so it must independently reject an+ # unsafe replacement URL before it makes any request with the key.+ monkeypatch.setattr(+ "httpx.get", lambda *args, **kwargs: pytest.fail("unsafe endpoint was requested")+ )+ checked = mgr.verify_provider(+ "gateway", {"base_url": "http://example.com/v1", "api_key": "test"}+ )+ assert checked["ok"] is False+ assert "localhost or a private IP" in checked["error"]++def test_manager_curated_models(tmp_path, monkeypatch):"""No seed list: the picker is the curated matrix filtered to key-holding providers,plus user-added custom ids. A fresh install shows only the (not-yet-usable) default.diff --git a/tests/test_server.py b/tests/test_server.pyindex 75b50807..1786ce8c 100644--- a/tests/test_server.py+++ b/tests/test_server.py@@ -1125,6 +1125,32 @@ def test_provider_set_and_remove_roundtrip(tmp_path):assert not client.delete("/v1/providers/nope").json()["ok"]+def test_custom_provider_rest_create_and_delete(tmp_path, monkeypatch):+ """The public Settings API creates a separately-routed custom provider."""+ monkeypatch.setenv("COWORKER_STATE_DIR", str(tmp_path / "state"))+ manager = SessionManager(workspace=tmp_path, provider=ScriptedProvider([]))+ client = TestClient(create_app(manager))++ created = client.post(+ "/v1/providers/custom",+ json={+ "name": "acme",+ "title": "Acme Gateway",+ "fields": {+ "api_key": "acme-test",+ "base_url": "https://llm.acme.example/v1",+ },+ },+ ).json()+ assert created == {"ok": True, "provider": "acme", "recommended_model": None}+ provider = {p["name"]: p for p in client.get("/v1/providers").json()}["acme"]+ assert provider["is_custom"] is True and provider["values"]["base_url"].endswith("/v1")+ assert "acme-test" not in str(provider)++ assert client.delete("/v1/providers/acme").json()["ok"] is True+ assert "acme" not in {p["name"] for p in client.get("/v1/providers").json()}++def test_always_allow_grants_survive_restart(tmp_path):""""Always allow" is session-scoped, and the session outlives the process — a restart(fresh manager over the same store) must not re-ask for an approved command