@worca/app 1.3.0 → 1.4.0

package/src/core/bridge/providers/copilot.mjs

@@ -0,0 +1,269 @@
+// src/core/bridge/providers/copilot.mjs
+// GitHub Copilot as a bridge provider (model-bridge-design.md §7): the device
+// flow sign-in, the GitHub-token → short-lived Copilot-token exchange (cached
+// in memory, never on disk), the request headers Copilot's gateway expects,
+// the models list and the quota snapshot.
+//
+// The client id, the token-exchange endpoint and the editor headers are the
+// values every community bridge sends (ericc-ch/copilot-api, MIT — see
+// THIRD_PARTY_NOTICES.md). Worca identifies itself the same way because the
+// gateway serves no other client; the user acknowledges that once (§8.2).
+//
+// Every network call takes an injectable `fetch` so the whole module is
+// testable against a stub without touching github.com.
+
+export const GITHUB_CLIENT_ID = 'Iv1.b507a08c87ecfe98';
+export const GITHUB_SCOPES = 'read:user';
+export const GITHUB_BASE = 'https://github.com';
+export const GITHUB_API = 'https://api.github.com';
+export const COPILOT_API_VERSION = '2025-04-01';
+const EDITOR_VERSION = 'vscode/1.104.0';
+const PLUGIN_VERSION = 'copilot-chat/0.31.0';
+const USER_AGENT = 'GitHubCopilotChat/0.31.0';
+
+/** The API host for an account type when the token exchange names none. */
+export function copilotApiHost(accountType) {
+  if (accountType === 'business') return 'https://api.business.githubcopilot.com';
+  if (accountType === 'enterprise') return 'https://api.enterprise.githubcopilot.com';
+  return 'https://api.githubcopilot.com';
+}
+
+/** Headers for github.com / api.github.com calls (device flow, exchange, user). */
+export function githubHeaders(githubToken) {
+  return {
+    'content-type': 'application/json',
+    accept: 'application/json',
+    ...(githubToken ? { authorization: `token ${githubToken}` } : {}),
+    'editor-version': EDITOR_VERSION,
+    'editor-plugin-version': PLUGIN_VERSION,
+    'user-agent': USER_AGENT,
+    'x-github-api-version': COPILOT_API_VERSION,
+  };
+}
+
+/**
+ * Headers for a Copilot gateway call (§7.1).
+ * @param {string} copilotToken
+ * @param {{vision?:boolean, initiator?:'user'|'agent', requestId?:string}} [opts]
+ */
+export function copilotHeaders(copilotToken, { vision = false, initiator = 'user', requestId } = {}) {
+  return {
+    authorization: `Bearer ${copilotToken}`,
+    'content-type': 'application/json',
+    'copilot-integration-id': 'vscode-chat',
+    'editor-version': EDITOR_VERSION,
+    'editor-plugin-version': PLUGIN_VERSION,
+    'user-agent': USER_AGENT,
+    'openai-intent': 'conversation-panel',
+    'x-github-api-version': COPILOT_API_VERSION,
+    'x-request-id': requestId || cryptoRandomId(),
+    'x-initiator': initiator === 'agent' ? 'agent' : 'user',
+    ...(vision ? { 'copilot-vision-request': 'true' } : {}),
+  };
+}
+
+function cryptoRandomId() {
+  // UUID v4 without importing crypto at module load (keeps the leaf cheap).
+  const h = [...Array(32)].map(() => Math.floor(Math.random() * 16).toString(16)).join('');
+  return `${h.slice(0, 8)}-${h.slice(8, 12)}-4${h.slice(13, 16)}-a${h.slice(17, 20)}-${h.slice(20)}`;
+}
+
+/** Whether a Messages request carries an image (→ copilot-vision-request). */
+export function bodyHasImage(body) {
+  const msgs = body && Array.isArray(body.messages) ? body.messages : [];
+  for (const m of msgs) {
+    if (!Array.isArray(m?.content)) continue;
+    for (const b of m.content) {
+      if (b?.type === 'image') return true;
+      if (b?.type === 'tool_result' && Array.isArray(b.content) && b.content.some((x) => x?.type === 'image')) return true;
+    }
+  }
+  return false;
+}
+
+/** 'agent' when the last message continues a tool loop, else 'user' (§7.1). */
+export function requestInitiator(body) {
+  const msgs = body && Array.isArray(body.messages) ? body.messages : [];
+  const last = msgs[msgs.length - 1];
+  if (!last) return 'user';
+  if (last.role === 'assistant') return 'agent';
+  if (Array.isArray(last.content) && last.content.some((b) => b?.type === 'tool_result')) return 'agent';
+  return 'user';
+}
+
+// ── device flow ──────────────────────────────────────────────────────────────
+
+/**
+ * Start the GitHub device flow. Returns the code the user types at
+ * github.com/login/device plus the poll interval.
+ * @param {{fetch?:typeof fetch}} [deps]
+ */
+export async function startDeviceFlow({ fetch: f = globalThis.fetch } = {}) {
+  const r = await f(`${GITHUB_BASE}/login/device/code`, {
+    method: 'POST', headers: githubHeaders(),
+    body: JSON.stringify({ client_id: GITHUB_CLIENT_ID, scope: GITHUB_SCOPES }),
+  });
+  if (!r.ok) throw new Error(`GitHub device flow could not start (${r.status})`);
+  const j = await r.json();
+  if (!j.device_code || !j.user_code) throw new Error('GitHub device flow: malformed response');
+  return {
+    deviceCode: j.device_code,
+    userCode: j.user_code,
+    verificationUri: j.verification_uri || `${GITHUB_BASE}/login/device`,
+    interval: Number(j.interval) || 5,
+    expiresIn: Number(j.expires_in) || 900,
+  };
+}
+
+/**
+ * One poll of the device flow. `{pending:true}` while the user has not
+ * approved yet (also for slow_down, with `interval` raised), `{ok:true, token}`
+ * once approved, `{error}` when the code expired or was denied.
+ * @param {string} deviceCode
+ * @param {{fetch?:typeof fetch}} [deps]
+ */
+export async function pollDeviceFlow(deviceCode, { fetch: f = globalThis.fetch } = {}) {
+  const r = await f(`${GITHUB_BASE}/login/oauth/access_token`, {
+    method: 'POST', headers: githubHeaders(),
+    body: JSON.stringify({ client_id: GITHUB_CLIENT_ID, device_code: deviceCode, grant_type: 'urn:ietf:params:oauth:grant-type:device_code' }),
+  });
+  const j = await r.json().catch(() => ({}));
+  if (j.access_token) return { ok: true, token: j.access_token };
+  if (j.error === 'authorization_pending') return { pending: true };
+  if (j.error === 'slow_down') return { pending: true, interval: Number(j.interval) || 10 };
+  if (j.error === 'expired_token') return { error: 'the device code expired — start the sign-in again' };
+  if (j.error === 'access_denied') return { error: 'the sign-in was denied on github.com' };
+  return { error: j.error_description || j.error || `GitHub answered ${r.status}` };
+}
+
+/** The GitHub login of the token's user (display only). */
+export async function githubLogin(githubToken, { fetch: f = globalThis.fetch } = {}) {
+  const r = await f(`${GITHUB_API}/user`, { headers: githubHeaders(githubToken) });
+  if (!r.ok) throw new Error(`GitHub /user answered ${r.status}`);
+  const j = await r.json();
+  return typeof j.login === 'string' ? j.login : '';
+}
+
+// ── token exchange (memory cache) ────────────────────────────────────────────
+
+const REFRESH_MARGIN_S = 60;
+const cache = new Map();   // githubToken -> { token, expiresAt (ms), apiHost }
+
+/**
+ * A live Copilot token for `githubToken`, exchanged on first use and refreshed
+ * before expiry. Returns `{token, apiHost}`; `apiHost` is the gateway the
+ * exchange named (`endpoints.api`) or null.
+ * @param {string} githubToken
+ * @param {{fetch?:typeof fetch, now?:() => number, force?:boolean}} [deps]
+ */
+export async function copilotToken(githubToken, { fetch: f = globalThis.fetch, now = Date.now, force = false } = {}) {
+  if (!githubToken) throw Object.assign(new Error('not signed in to GitHub Copilot'), { code: 'NOT_SIGNED_IN' });
+  const hit = cache.get(githubToken);
+  if (!force && hit && hit.expiresAt - now() > REFRESH_MARGIN_S * 1000) return { token: hit.token, apiHost: hit.apiHost };
+  const r = await f(`${GITHUB_API}/copilot_internal/v2/token`, { headers: githubHeaders(githubToken) });
+  if (r.status === 401 || r.status === 403) {
+    cache.delete(githubToken);
+    throw Object.assign(new Error(`GitHub rejected the stored token (${r.status}) — sign in again`), { code: 'AUTH', status: r.status });
+  }
+  if (!r.ok) throw Object.assign(new Error(`Copilot token exchange answered ${r.status}`), { code: 'EXCHANGE', status: r.status });
+  const j = await r.json();
+  if (!j.token) throw Object.assign(new Error('Copilot token exchange: no token in the response (is Copilot enabled for this account?)'), { code: 'EXCHANGE' });
+  const expiresAt = Number(j.expires_at) > 0 ? Number(j.expires_at) * 1000 : now() + 25 * 60 * 1000;
+  const apiHost = j.endpoints && typeof j.endpoints.api === 'string' ? j.endpoints.api.replace(/\/+$/, '') : null;
+  cache.set(githubToken, { token: j.token, expiresAt, apiHost });
+  return { token: j.token, apiHost };
+}
+
+/** Drop a cached Copilot token (after a 401 from the gateway). */
+export function invalidateCopilotToken(githubToken) { cache.delete(githubToken); }
+/** Test hook. */
+export function _resetCopilotCache() { cache.clear(); }
+
+// ── models + quota ───────────────────────────────────────────────────────────
+
+const REASONING_ID_RE = /^(o\d|gpt-5|codex|.*-thinking|.*reasoning)/i;
+
+/** Normalize one entry of Copilot's /models list to worca's shape (§8.4). */
+export function normalizeCopilotModel(m) {
+  if (!m || typeof m !== 'object' || typeof m.id !== 'string') return null;
+  const caps = m.capabilities && typeof m.capabilities === 'object' ? m.capabilities : {};
+  const supports = caps.supports && typeof caps.supports === 'object' ? caps.supports : {};
+  const limits = caps.limits && typeof caps.limits === 'object' ? caps.limits : {};
+  const vendor = typeof m.vendor === 'string' ? m.vendor : '';
+  const reasoning = supports.reasoning_effort === true || supports.thinking === true || REASONING_ID_RE.test(m.id);
+  return {
+    id: m.id,
+    name: typeof m.name === 'string' && m.name ? m.name : m.id,
+    vendor,
+    family: typeof caps.family === 'string' ? caps.family : '',
+    type: typeof caps.type === 'string' ? caps.type : '',
+    preview: m.preview === true,
+    pickerEnabled: m.model_picker_enabled !== false,
+    policyState: m.policy && typeof m.policy === 'object' && typeof m.policy.state === 'string' ? m.policy.state : 'enabled',
+    toolCalls: supports.tool_calls !== false,
+    vision: supports.vision === true,
+    reasoning,
+    maxPromptTokens: Number(limits.max_prompt_tokens) || null,
+    maxOutputTokens: Number(limits.max_output_tokens) || null,
+    contextWindow: Number(limits.max_context_window_tokens) || null,
+  };
+}
+
+/** Whether a normalized Copilot model is an Anthropic (Claude) one → native passthrough. */
+export function isAnthropicVendor(m) {
+  return /anthropic/i.test(m.vendor || '') || /^claude/i.test(m.id || '');
+}
+
+/** The catalog entry an import creates for a Copilot model (§8.4). */
+export function catalogEntryForCopilotModel(m) {
+  const anthropic = isAnthropicVendor(m);
+  const capabilities = {
+    toolCalls: m.toolCalls, vision: m.vision, reasoning: m.reasoning,
+    ...(m.maxPromptTokens ? { maxPromptTokens: m.maxPromptTokens } : {}),
+    ...(m.maxOutputTokens ? { maxOutputTokens: m.maxOutputTokens } : {}),
+  };
+  return {
+    id: `copilot-${m.id}`,
+    label: `${m.name} (Copilot)`,
+    efforts: anthropic || m.reasoning ? undefined : ['medium'],
+    upstream: { provider: 'copilot', api: anthropic ? 'anthropic' : 'openai-chat', model: m.id, capabilities },
+    cost: { free: true },
+  };
+}
+
+/**
+ * The Copilot models list, normalized. Chat models only.
+ * @param {string} githubToken
+ * @param {{accountType?:string, fetch?:typeof fetch}} [deps]
+ */
+export async function listCopilotModels(githubToken, { accountType = 'individual', fetch: f = globalThis.fetch } = {}) {
+  const { token, apiHost } = await copilotToken(githubToken, { fetch: f });
+  const host = apiHost || copilotApiHost(accountType);
+  const r = await f(`${host}/models`, { headers: copilotHeaders(token) });
+  if (!r.ok) throw Object.assign(new Error(`Copilot /models answered ${r.status}`), { status: r.status });
+  const j = await r.json();
+  const data = Array.isArray(j.data) ? j.data : (Array.isArray(j) ? j : []);
+  return data.map(normalizeCopilotModel).filter((m) => m && (!m.type || m.type === 'chat'));
+}
+
+/**
+ * The premium-request quota snapshot, or null when the account exposes none.
+ * @returns {Promise<{used:number|null, entitlement:number|null, remaining:number|null, percentRemaining:number|null, unlimited:boolean, resetDate:string|null}|null>}
+ */
+export async function copilotUsage(githubToken, { fetch: f = globalThis.fetch } = {}) {
+  const r = await f(`${GITHUB_API}/copilot_internal/user`, { headers: githubHeaders(githubToken) });
+  if (!r.ok) return null;
+  const j = await r.json().catch(() => null);
+  const q = j && j.quota_snapshots && j.quota_snapshots.premium_interactions;
+  if (!q || typeof q !== 'object') return null;
+  const entitlement = Number.isFinite(Number(q.entitlement)) ? Number(q.entitlement) : null;
+  const remaining = Number.isFinite(Number(q.remaining)) ? Number(q.remaining) : null;
+  return {
+    used: entitlement != null && remaining != null ? Math.max(0, entitlement - remaining) : null,
+    entitlement,
+    remaining,
+    percentRemaining: Number.isFinite(Number(q.percent_remaining)) ? Number(q.percent_remaining) : null,
+    unlimited: q.unlimited === true,
+    resetDate: typeof j.quota_reset_date === 'string' ? j.quota_reset_date : null,
+  };
+}

package/src/core/bridge/providers/endpoint.mjs

@@ -0,0 +1,257 @@
+// src/core/bridge/providers/endpoint.mjs
+// Discovery for OpenAI-compatible endpoints (model-bridge-design.md §8.4, the Copilot import's
+// shape for a server you run yourself): ask a base URL what it serves, and turn a pick into a
+// catalog entry. Pure over an injected `fetch`; nothing here reads settings or writes anything.
+//
+// `GET /v1/models` is the only call every server answers, and it carries ids and nothing else —
+// not the context window, not whether the model can call tools, both of which decide whether a
+// Worca pipeline can use it at all. So each server is probed on its own endpoint first and the
+// OpenAI list is the fallback:
+//
+//   llama.cpp   GET {root}/props        default_generation_settings.n_ctx is the window ONE request
+//                                       gets (-c split across --parallel slots), chat_template_caps
+//                                       says whether the template takes tools, modalities vision.
+//               GET {base}/models       data[].meta.n_ctx / n_ctx_train / n_params.
+//   Ollama      GET {root}/api/tags     details.context_length is what the model was TRAINED for;
+//                                       capabilities carries tools / vision / thinking.
+//               GET {root}/api/ps       a loaded model's real context_length, when one is loaded.
+//   LM Studio   GET {root}/api/v0/models  type (llm | vlm | embeddings), state, max_context_length,
+//                                       loaded_context_length.
+//   vLLM / other  GET {base}/models     ids, plus max_model_len where the server sets it.
+//
+// The window a model is SERVED with and the one it was TRAINED for are different numbers, and only
+// the served one may become a prompt limit: Ollama serves 4096 by default however large the model
+// is, and llama.cpp divides -c across its slots. When the served value is unknown the entry is
+// built WITHOUT a prompt limit and the caller's warning says so — a wrong window is worse than
+// none, because the CLI would compact against a number the endpoint never had.
+
+const SERVERS = Object.freeze({
+  'llama.cpp': 'llama.cpp', ollama: 'Ollama', lmstudio: 'LM Studio', vllm: 'vLLM', 'openai-compatible': 'OpenAI-compatible',
+});
+/** The catalog-id prefix per server, so two endpoints' models never collide. */
+const ID_PREFIX = Object.freeze({ 'llama.cpp': 'llama', ollama: 'ollama', lmstudio: 'lmstudio', vllm: 'vllm', 'openai-compatible': 'local' });
+/** Below this a pipeline thrashes the CLI's auto-compact (docs/models.md Troubleshooting). */
+export const MIN_PIPELINE_WINDOW = 65536;
+const DEFAULT_TIMEOUT_MS = 10_000;
+
+/** The server root of a base URL: the same URL without its trailing `/v1` (`/props` lives there). */
+export function endpointRoot(baseUrl) {
+  return String(baseUrl || '').trim().replace(/\/+$/, '').replace(/\/v1$/, '');
+}
+
+const num = (v) => { const n = Number(v); return Number.isInteger(n) && n > 0 ? n : null; };
+const has = (list, name) => Array.isArray(list) && list.includes(name);
+/** `qwen3-coder:30b`, `/models/Qwen3.6-35B.gguf` → a catalog-id stem. */
+export function slugModelId(id) {
+  const base = String(id || '').split(/[\\/]/).pop().replace(/\.gguf$/i, '');
+  return base.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 48) || 'model';
+}
+const GB = (n) => (num(n) ? `${(n / 1e9).toFixed(1)} GB` : null);
+
+/**
+ * One JSON GET (or POST) that never throws: `null` on any failure, so a probe for a server that is
+ * not there costs one request and no error handling at the call sites.
+ */
+async function json(f, url, { timeoutMs, headers = {}, body = null } = {}) {
+  try {
+    const r = await f(url, {
+      ...(body ? { method: 'POST', body: JSON.stringify(body), headers: { 'content-type': 'application/json', ...headers } } : { headers }),
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (!r.ok) return null;
+    return await r.json();
+  } catch { return null; }
+}
+
+function llamaModels(list, props) {
+  const caps = (props && props.chat_template_caps) || {};
+  const modal = (props && props.modalities) || {};
+  const rows = Array.isArray(list && list.data) ? list.data : [];
+  const slots = num(props && props.total_slots);
+  return rows.map((m) => {
+    const meta = m.meta || {};
+    return {
+      id: String(m.id ?? props?.model_alias ?? ''),
+      name: String(m.id ?? props?.model_alias ?? ''),
+      kind: 'llm',
+      servedContext: num(meta.n_ctx),
+      trainedContext: num(meta.n_ctx_train),
+      toolCalls: caps.supports_tools === true || caps.supports_tool_calls === true,
+      vision: modal.vision === true,
+      reasoning: caps.supports_reasoning_effort === true,
+      loaded: true,
+      detail: [meta.ftype, meta.n_params ? `${(meta.n_params / 1e9).toFixed(0)}B` : null, slots > 1 ? `${slots} slots` : null].filter(Boolean).join(' · ') || null,
+    };
+  }).filter((m) => m.id);
+}
+
+function ollamaModels(tags, ps) {
+  const loaded = new Map((Array.isArray(ps && ps.models) ? ps.models : []).map((m) => [String(m.name ?? m.model), num(m.context_length)]));
+  return (Array.isArray(tags && tags.models) ? tags.models : []).map((m) => {
+    const id = String(m.name ?? m.model ?? '');
+    const d = m.details || {};
+    const caps = m.capabilities;
+    return {
+      id,
+      name: id,
+      kind: has(caps, 'embedding') ? 'embedding' : 'llm',
+      servedContext: loaded.get(id) ?? null,
+      trainedContext: num(d.context_length),
+      toolCalls: has(caps, 'tools'),
+      vision: has(caps, 'vision'),
+      reasoning: has(caps, 'thinking'),
+      loaded: loaded.has(id),
+      detail: [d.parameter_size, d.quantization_level, GB(m.size)].filter(Boolean).join(' · ') || null,
+    };
+  }).filter((m) => m.id);
+}
+
+function lmStudioModels(list) {
+  return (Array.isArray(list && list.data) ? list.data : []).map((m) => {
+    const type = String(m.type || '');
+    return {
+      id: String(m.id ?? ''),
+      name: String(m.id ?? ''),
+      kind: type === 'embeddings' ? 'embedding' : 'llm',
+      servedContext: num(m.loaded_context_length),
+      trainedContext: num(m.max_context_length),
+      // LM Studio does not report tool support; its LLMs generally take tools, and a model that
+      // cannot is refused at the first call rather than silently mis-flagged here.
+      toolCalls: type === 'llm' || type === 'vlm',
+      vision: type === 'vlm',
+      reasoning: false,
+      loaded: m.state === 'loaded',
+      detail: [m.quantization, m.arch, m.publisher].filter(Boolean).join(' · ') || null,
+    };
+  }).filter((m) => m.id);
+}
+
+function openAiModels(list) {
+  return (Array.isArray(list && list.data) ? list.data : []).map((m) => ({
+    id: String(m.id ?? ''),
+    name: String(m.id ?? ''),
+    kind: 'llm',
+    // vLLM reports the served length here; nothing else on the generic surface does.
+    servedContext: num(m.max_model_len),
+    trainedContext: null,
+    toolCalls: null,           // unknown, not "no"
+    vision: null,
+    reasoning: null,
+    loaded: null,
+    detail: typeof m.owned_by === 'string' && m.owned_by ? m.owned_by : null,
+  })).filter((m) => m.id);
+}
+
+/** What the caller must know before pinning a prompt limit on what this server reports. */
+function warningsFor(server, models, props) {
+  const w = [];
+  if (server === 'ollama') {
+    w.push('Ollama serves a 4096-token window by default, whatever the model was trained for: start it with OLLAMA_CONTEXT_LENGTH=65536 (or set num_ctx on the model) and load the model, then re-import — otherwise set the prompt limit by hand to what it really serves.');
+  }
+  if (server === 'llama.cpp') {
+    const slots = num(props && props.total_slots);
+    // Not always a split: with a unified KV cache each slot sees the whole -c, and llama reports the
+    // per-request window either way. Say what the number IS rather than claiming arithmetic.
+    if (slots > 1) w.push(`llama-server is serving ${slots} slots in parallel; the window shown is what ONE request gets, which may be less than the -c you passed.`);
+  }
+  if (server === 'lmstudio' && models.some((m) => m.kind !== 'embedding' && !m.servedContext)) {
+    w.push('LM Studio reports a model\'s real window only while it is loaded; for the others the number shown is what the model supports, and the prompt limit is left unset.');
+  }
+  if (server === 'openai-compatible' && models.every((m) => !m.servedContext)) {
+    w.push('This endpoint does not report context windows — set each model\'s prompt limit by hand after importing.');
+  }
+  const small = models.filter((m) => m.kind !== 'embedding' && m.servedContext && m.servedContext < MIN_PIPELINE_WINDOW);
+  if (small.length) w.push(`${small.length === 1 ? 'One model serves' : `${small.length} models serve`} less than ${MIN_PIPELINE_WINDOW} tokens — a pipeline thrashes the CLI's auto-compact below that.`);
+  return w;
+}
+
+/**
+ * Ask an OpenAI-compatible endpoint what it serves.
+ * @param {string} baseUrl  the endpoint's OpenAI base URL (…/v1)
+ * @param {{apiKey?:string, fetch?:typeof fetch, timeoutMs?:number}} [opts]
+ * @returns {Promise<{server:string, serverLabel:string, baseUrl:string, models:Array<object>, warnings:string[]}>}
+ * @throws {Error} when nothing answers at all (the caller shows it as the connection failure it is)
+ */
+export async function listEndpointModels(baseUrl, { apiKey = '', fetch: f = globalThis.fetch, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  const base = String(baseUrl || '').trim().replace(/\/+$/, '');
+  if (!base) throw new Error('baseUrl is required');
+  const root = endpointRoot(base);
+  const headers = apiKey ? { authorization: `Bearer ${apiKey}` } : {};
+  const opt = { timeoutMs, headers };
+  let server = 'openai-compatible';
+  let models = [];
+  let props = null;
+
+  const props0 = await json(f, `${root}/props`, opt);
+  if (props0 && (props0.default_generation_settings || props0.chat_template_caps)) {
+    server = 'llama.cpp';
+    props = props0;
+    models = llamaModels(await json(f, `${base}/models`, opt), props0);
+    if (!models.length) {
+      const n = num(props0.default_generation_settings && props0.default_generation_settings.n_ctx);
+      const id = String(props0.model_alias || props0.model_path || '').split(/[\\/]/).pop();
+      if (id) models = [{ id, name: id, kind: 'llm', servedContext: n, trainedContext: null, toolCalls: props0.chat_template_caps?.supports_tools === true, vision: props0.modalities?.vision === true, reasoning: false, loaded: true, detail: null }];
+    }
+  }
+  if (!models.length) {
+    const tags = await json(f, `${root}/api/tags`, opt);
+    if (tags && Array.isArray(tags.models)) {
+      server = 'ollama';
+      models = ollamaModels(tags, await json(f, `${root}/api/ps`, opt));
+    }
+  }
+  if (!models.length) {
+    const lms = await json(f, `${root}/api/v0/models`, opt);
+    if (lms && Array.isArray(lms.data) && lms.data.some((m) => m && m.type)) {
+      server = 'lmstudio';
+      models = lmStudioModels(lms);
+    }
+  }
+  if (!models.length) {
+    const list = await json(f, `${base}/models`, opt);
+    if (!list) throw new Error(`no OpenAI-compatible model list at ${base}/models — is the server running, and is the base URL right?`);
+    models = openAiModels(list);
+    if (models.some((m) => m.servedContext)) server = 'vllm';
+  }
+  models.sort((a, b) => (Number(b.kind !== 'embedding') - Number(a.kind !== 'embedding')) || (Number(b.loaded === true) - Number(a.loaded === true)) || a.id.localeCompare(b.id));
+  return { server, serverLabel: SERVERS[server], baseUrl: base, models, warnings: warningsFor(server, models, props) };
+}
+
+/**
+ * A discovered model as a catalog entry (§8.4's Copilot shape, for a server you run).
+ * `baseUrl` rides the ENTRY when it differs from the provider's, so one catalog can hold an Ollama
+ * and a llama.cpp model at once. A prompt limit is pinned only from a window the server really
+ * serves; `maxOutputTokens` is never guessed — no local server reports one.
+ * @param {object} m           a row from listEndpointModels
+ * @param {{server:string, baseUrl:string, providerBaseUrl?:string}} ctx
+ */
+export function catalogEntryForEndpointModel(m, { server = 'openai-compatible', baseUrl, providerBaseUrl = '' } = {}) {
+  const capabilities = {
+    ...(m.toolCalls === true || m.toolCalls === false ? { toolCalls: m.toolCalls } : {}),
+    ...(m.vision === true ? { vision: true } : {}),
+    ...(m.reasoning === true ? { reasoning: true } : {}),
+    ...(num(m.servedContext) ? { maxPromptTokens: num(m.servedContext) } : {}),
+  };
+  const own = String(baseUrl || '').replace(/\/+$/, '');
+  const provider = String(providerBaseUrl || '').replace(/\/+$/, '');
+  return {
+    id: `${ID_PREFIX[server] || 'local'}-${slugModelId(m.id)}`,
+    label: `${m.name || m.id} (${SERVERS[server] || 'local'})`,
+    ...(m.reasoning === true ? {} : { efforts: ['medium'] }),
+    upstream: {
+      provider: 'openai', api: 'openai-chat', model: m.id,
+      ...(own && own !== provider ? { baseUrl: own } : {}),
+      ...(Object.keys(capabilities).length ? { capabilities } : {}),
+    },
+    cost: { free: true },       // a model on your own machine bills nothing; never "cost not verified"
+  };
+}
+
+/** Whether a discovered model can carry a pipeline at all (the sheet greys the rest). */
+export function importableModel(m) {
+  if (!m || m.kind === 'embedding') return { ok: false, why: 'an embedding model — not a chat model' };
+  if (m.toolCalls === false) return { ok: false, why: 'no tool calls — a pipeline agent cannot run without them' };
+  return { ok: true };
+}
+
+export { SERVERS as ENDPOINT_SERVERS };

package/src/core/bridge/registry.mjs

@@ -0,0 +1,88 @@
+// src/core/bridge/registry.mjs
+// Which catalog entries are bridged, and with what (model-bridge-design.md
+// §4.2/§6). Import contract: settings.mjs, plugin-models.mjs, the policy
+// cache and the zero-import model-env.mjs leaf only — config.mjs imports the
+// bridge (for resolveModelEnv), so nothing under src/core/bridge/ may import
+// config.mjs.
+
+import { listGlobalModels, providerConfig, providerSecretSet, resolveProviderSecret, copilotTermsAcknowledged } from '../settings.mjs';
+import { listPluginModels } from '../plugin-models.mjs';
+import { policyCatalogModels } from '../policy/cache.mjs';
+import { isLocalBaseUrl } from '../model-env.mjs';
+
+/** An OpenAI-compatible endpoint on this machine / a private network needs no key. */
+export function keyOptional(provider, baseUrl) {
+  return provider === 'openai' && isLocalBaseUrl(baseUrl);
+}
+
+/**
+ * The bridged catalog entry for `id` (user global → plugin → team policy), or
+ * null when the id is unknown or not bridged. Shape:
+ * `{id, label, upstream, cost?, source: 'global'|'plugin'|'policy', plugin?}`.
+ * Synchronous; never throws.
+ */
+export function findBridgedEntry(id) {
+  const key = typeof id === 'string' ? id.trim().toLowerCase() : '';
+  if (!key) return null;
+  const g = listGlobalModels().find((m) => m.id.toLowerCase() === key);
+  if (g) return g.upstream ? { id: g.id, label: g.label, upstream: g.upstream, cost: g.cost, source: 'global' } : null;
+  const p = listPluginModels().find((m) => m.id.toLowerCase() === key);
+  if (p) return p.upstream ? { id: p.id, label: p.label, upstream: p.upstream, cost: p.cost, source: 'plugin', plugin: p.plugin } : null;
+  let t = null;
+  try { t = policyCatalogModels().find((m) => m.id.toLowerCase() === key); } catch { t = null; }
+  if (t && t.upstream) return { id: t.id, label: t.label, upstream: t.upstream, source: 'policy' };
+  return null;
+}
+
+/**
+ * Whether the provider behind `upstream` can be used right now, and if not,
+ * why — the "needs sign-in" state the UI and the spawn fail-fast share (§8.5).
+ * @returns {{ok:true}|{ok:false, reason:'not_signed_in'|'terms'|'no_key', message:string}}
+ */
+export function providerReadiness(upstream) {
+  if (!upstream) return { ok: true };
+  const p = upstream.provider;
+  if (p === 'copilot') {
+    if (!copilotTermsAcknowledged()) {
+      return { ok: false, reason: 'terms', message: 'provider copilot: terms not acknowledged — open Settings › Providers' };
+    }
+    const cfg = providerConfig('copilot');
+    if (!resolveProviderSecret(cfg.githubToken)) {
+      return { ok: false, reason: 'not_signed_in', message: 'provider copilot: not signed in — run `worca models login copilot` or open Settings › Providers' };
+    }
+    return { ok: true };
+  }
+  // openai / anthropic: a per-entry key wins, else the provider's key.
+  const cfg = providerConfig(p);
+  const key = resolveProviderSecret(upstream.apiKey) || resolveProviderSecret(cfg.apiKey);
+  const has = providerSecretSet(p) || !!upstream.apiKey;
+  // No key configured anywhere + a local endpoint = keyless. A configured key
+  // whose ${VAR} is unset still blocks: the user meant to send one.
+  if (!key && (has || !keyOptional(p, upstream.baseUrl || cfg.baseUrl))) {
+    return {
+      ok: false, reason: 'no_key',
+      message: has
+        ? `provider ${p}: the API key's \${VAR} is not set in worca's environment`
+        : `provider ${p}: no API key — open Settings › Providers`,
+    };
+  }
+  return { ok: true };
+}
+
+/** Effective upstream settings for a request: base URL, key, headers, concurrency. */
+export function upstreamSettings(upstream) {
+  const cfg = providerConfig(upstream.provider);
+  const p = upstream.provider;
+  return {
+    provider: p,
+    api: upstream.api,
+    model: upstream.model,
+    baseUrl: upstream.baseUrl || cfg.baseUrl || null,
+    apiKey: p === 'copilot' ? null : (resolveProviderSecret(upstream.apiKey) || resolveProviderSecret(cfg.apiKey) || ''),
+    githubToken: p === 'copilot' ? resolveProviderSecret(cfg.githubToken) : null,
+    accountType: p === 'copilot' ? cfg.accountType : null,
+    headers: upstream.headers || {},
+    capabilities: upstream.capabilities || {},
+    maxConcurrent: cfg.maxConcurrent,
+  };
+}