@worca/app 1.3.0 → 1.4.0-rc.1

package/src/core/ask-forms.mjs

@@ -0,0 +1,195 @@
+// src/core/ask-forms.mjs
+// The two host-side gates of an ask form (spec §5).
+//
+//   GATE 2 (ask time, prepareFormAsk): the agent wrote {form, data}. Resolve the
+//     form from its sidecar, cap the data, run P1's checkAskData (the data schema
+//     AND "the auto answer for THIS data must pass gate 3"), snapshot every file
+//     it references, resolve enumFrom/defaultFrom into a CLOSED answer schema, and
+//     hand back the ask the host gates on. A refusal carries the EXACT error list
+//     the agent is resumed with — never a throw.
+//
+//   GATE 3 (answer time, formAnswerValidator): the human sent {values}. Drop the
+//     fields `when` hides, strip unknown keys, validate against the RESOLVED
+//     answer schema, and hand back {form, version, values}. A refusal carries the
+//     error list POST /api/answer returns as 422 — never a throw.
+//
+// Gate 3 runs off the PERSISTED ask alone (layout + answerSchema): by the time a
+// server restart re-runs it, the agent's sidecar may have changed or its plugin
+// been removed (§9). Nothing here reads the registry.
+import { join } from 'node:path';
+
+import { ASK_LIMITS } from '../shared/forms/catalog.mjs';
+import { resolveAnswerSchema } from '../shared/forms/schema.mjs';
+import { checkAskData, autoAnswer, collectAnswer, fileRefs } from '../shared/forms/answer.mjs';
+import { FORM_SURFACES } from '../shared/forms/form-def.mjs';
+import { snapshotAskFiles } from './ask-files.mjs';
+
+/** The snapshot root inside a pipeline dir: <pipelineDir>/ask-files/<askId>/. */
+export const ASK_FILES_DIR = 'ask-files';
+
+/** Depth cap for anything that walks a posted value recursively. P1 caps only
+ *  normalizeAskBlock (256 levels, form-def.mjs); its validate / collectAnswer /
+ *  clone are recursive walkers and native JSON.stringify is one too — on Node 22
+ *  a value ~9 000 levels deep throws RangeError out of collectAnswer, on Node 25
+ *  it sails through into the DB and onto the socket. So BOTH gates count depth
+ *  with a work list (never recursive) BEFORE any recursive step and refuse by
+ *  name. Same figure as P1's block cap; it is not an ASK_LIMITS value. */
+const MAX_JSON_DEPTH = 256;
+
+/** Is `value` nested deeper than `max` object/array levels? Iterative on purpose. */
+function nestsDeeperThan(value, max) {
+  const todo = [[value, 0]];
+  while (todo.length) {
+    const [cur, depth] = todo.pop();
+    if (cur === null || typeof cur !== 'object') continue;
+    if (depth > max) return true;
+    for (const child of Object.values(cur)) todo.push([child, depth + 1]);
+  }
+  return false;
+}
+
+const isObj = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+
+/** The ask id, reduced to the token that is BOTH the snapshot dir name and the
+ *  file route's `:askId` segment. Deterministic and total: the real ask id is
+ *  `questions-x:n_impl:1-r1`, which is neither a legal Windows path segment nor
+ *  something a route may take as a path. */
+export function askIdToken(id) {
+  const token = String(id ?? '').replace(/[^A-Za-z0-9_-]/g, '_').slice(0, 96);
+  return token || 'ask';
+}
+
+/**
+ * Gate 2. Never throws.
+ * @param {{agentMeta: object, payload: {form: string, data: unknown},
+ *          cwd: string, pipelineDir: string, askId: string}} args
+ * @returns {Promise<{ok: true, ask: object, autoValues: object}|{ok: false, errors: Array}>}
+ */
+export async function prepareFormAsk({ agentMeta, payload, cwd, pipelineDir, askId }) {
+  const forms = agentMeta?.ask?.forms || {};
+  const id = typeof payload?.form === 'string' ? payload.form.trim() : '';
+  const def = Object.hasOwn(forms, id) ? forms[id] : null;
+  if (!def) {
+    const known = Object.keys(forms);
+    return { ok: false, errors: [{ path: 'form', code: 'unknown-field',
+      message: `unknown form "${id}" — this agent declares ${known.length ? known.join(', ') : 'none'}` }] };
+  }
+  const data = payload?.data === undefined ? {} : payload.data;
+  // Gate 1 admits only a form with both object schemas; a def grafted past the
+  // registry may lack one, and resolveAnswerSchema(undefined) throws. Never throw.
+  if (!isObj(def.data) || !isObj(def.answer)) {
+    return { ok: false, errors: [{ path: 'form', code: 'unknown-field',
+      message: `form "${id}" has no data or answer schema` }] };
+  }
+
+  // The caps run FIRST, depth before bytes: a schema walk over a 50 MB blob is
+  // the denial of service the byte cap exists to prevent, and JSON.stringify
+  // (the byte count itself) is a recursive walker a deep value overflows on
+  // Node 22 — the depth count is iterative, so it goes first.
+  if (nestsDeeperThan(data, MAX_JSON_DEPTH)) {
+    return { ok: false, errors: [{ path: 'data', code: 'too-big',
+      message: `data is nested deeper than ${MAX_JSON_DEPTH} levels` }] };
+  }
+  let bytes;
+  try {
+    bytes = Buffer.byteLength(JSON.stringify(data ?? null) ?? 'null', 'utf8');
+  } catch {
+    return { ok: false, errors: [{ path: 'data', code: 'type', message: 'data must be JSON-serializable' }] };
+  }
+  if (bytes > ASK_LIMITS.dataBytes) {
+    return { ok: false, errors: [{ path: 'data', code: 'too-big',
+      message: `data is ${bytes} bytes; the limit is ${ASK_LIMITS.dataBytes}` }] };
+  }
+
+  // Ruling X4 / P1 C13: NOT a bare validate(def.data, data). checkAskData also
+  // proves that the auto answer built from THIS data passes gate 3 — which is
+  // what makes autoAnswer() below total, and D10 ("auto can never produce an
+  // invalid answer") true at run time rather than only for `example`. Its error
+  // paths are already prefixed `data.` / `answer.`; never prefix them again.
+  const shape = checkAskData(def, data);
+  if (!shape.ok) return { ok: false, errors: shape.errors };
+
+  const token = askIdToken(askId);
+  // ONE fileRefs() call: its result feeds the snapshot AND becomes the envelope's
+  // `fileRefs` (ruling X16). Calling P1 twice would let the two arrays disagree,
+  // and the renderer's "is this bound value a file?" lookup depends on them
+  // lining up index for index.
+  const refs = fileRefs(def.data, data);
+  const { files, errors } = await snapshotAskFiles({
+    refs,
+    // Resolution order is the spec's: the node's working tree, then the pipeline
+    // dir (§7.1). Both are already absolute.
+    roots: [cwd, pipelineDir].filter(Boolean),
+    destDir: join(pipelineDir, ASK_FILES_DIR, token),
+  });
+  if (errors.length) return { ok: false, errors };
+
+  const ask = {
+    kind: 'form',
+    // The route-safe snapshot token. NOT the question id (ruling X1): the caller
+    // keeps that and passes it as `_ask({ id })`; only this ever reaches a URL.
+    askId: token,
+    form: id,
+    version: Number.isInteger(def.version) ? def.version : 1,
+    title: typeof def.title === 'string' && def.title.trim() ? def.title.trim() : id,
+    // 'any' | 'web' (P1 FORM_SURFACES, C5). P2 never branches on it — it rides the
+    // envelope and the persisted ask so P3 and P4 can. An unrecognized value fails
+    // safe to 'any', the surface that refuses nothing.
+    surface: FORM_SURFACES.includes(def.surface) ? def.surface : 'any',
+    data,
+    layout: Array.isArray(def.layout) ? def.layout : [],
+    // Resolved HERE and stored with the ask, so gate 3 validates against a closed
+    // set even after the sidecar changed (§3.1, §9).
+    answerSchema: resolveAnswerSchema(def.answer, data),
+    // X16: the renderer's file lookup table — every `type:'file'` value's data
+    // path, in the same order as `files`. `accept` is dropped: it is a gate-2
+    // input, not something any surface renders.
+    fileRefs: refs.map((r) => ({ path: r.path, rel: r.rel })),
+    files,
+  };
+  // D10's auto answer travels BESIDE the ask, never inside it: the persisted
+  // shape (§9) is exactly `ask` plus `values`.
+  return { ok: true, ask, autoValues: autoAnswer(def, data) };
+}
+
+/**
+ * Gate 3, bound to one resolved ask. The returned validator is what
+ * RunHarness._ask hands to `pendingQuestion.validate`; a `{ ok: false }` result
+ * keeps the question OPEN and becomes the 422 body.
+ * @param {object} ask the resolved (or persisted) ask
+ * @returns {(payload: unknown) => {ok: true, payload: object}|{ok: false, errors: Array}}
+ */
+export function formAnswerValidator(ask) {
+  // R1: collectAnswer reads only `def.layout`, so a persisted ask is enough.
+  const def = { layout: Array.isArray(ask?.layout) ? ask.layout : [] };
+  const schema = ask?.answerSchema || { type: 'object', properties: {} };
+  const form = ask?.form;
+  const version = ask?.version;
+  return (payload) => {
+    const raw = payload && typeof payload === 'object' && !Array.isArray(payload)
+      && payload.values && typeof payload.values === 'object' && !Array.isArray(payload.values)
+      ? payload.values
+      : null;
+    if (!raw) {
+      return { ok: false, errors: [{ path: '', code: 'type', message: 'an answer is { values: { … } }' }] };
+    }
+    // Depth before collectAnswer: its clone() is a JSON round trip, which a deep
+    // value overflows on Node 22 — a RangeError out of answer(), not a 422.
+    if (nestsDeeperThan(raw, MAX_JSON_DEPTH)) {
+      return { ok: false, errors: [{ path: '', code: 'too-big', message: `values are nested deeper than ${MAX_JSON_DEPTH} levels` }] };
+    }
+    const { values, errors } = collectAnswer(def, schema, raw);
+    if (errors.length) return { ok: false, errors };
+    return { ok: true, payload: { form, version, values } };
+  };
+}
+
+/**
+ * The generic question a twice-refused form downgrades to (§5 gate 2). The text
+ * is the form's own title — the host adds no prose of its own.
+ * @param {{form: string, title?: string}} args
+ */
+export function downgradeQuestion({ form, title }) {
+  const text = typeof title === 'string' && title.trim() ? title.trim() : String(form || 'form');
+  return { id: `form-${askIdToken(form)}`, question: text, options: [], allowFreeText: true };
+}

package/src/core/ask-projection.mjs

@@ -0,0 +1,72 @@
+// src/core/ask-projection.mjs
+// The two caps every non-web ask surface shares, and the one helper that renders a
+// PERSISTED form ask's answer as text (spec D9, §9).
+//
+// The ask BODY is never formatted here: that is src/shared/forms/project.mjs's
+// projectForm(). What lives here is what a pure, browser-safe module may not know —
+// how many characters a chat message or an assistant read may spend — plus the
+// values line, which is the named destination for the crude projection
+// readPriorAnswers carries today.
+import { promptFields, projectForm } from '../shared/forms/project.mjs';
+
+/** Cap for Ask Worca's get_run_progress: an assistant read pays tokens per character. */
+export const PROMPT_PROJECTION_MAX = 2000;
+/** Cap for ONE chat message: Discord's 2000-char limit is the tightest shipped channel. */
+export const CHAT_PROJECTION_MAX = 1400;
+
+/** One answer VALUE as text. A review-list row is `<id>: <verdict> (<note>)`; nothing
+ *  reaches String() as a bare object. */
+function valueText(v) {
+  if (v === null || v === undefined) return '';
+  if (Array.isArray(v)) {
+    const rows = v.some((x) => x && typeof x === 'object' && !Array.isArray(x));
+    return v.map(valueText).join(rows ? '; ' : ', ');
+  }
+  if (typeof v === 'object') {
+    const id = v.id === undefined || v.id === null ? '' : String(v.id);
+    const verdict = v.verdict === undefined || v.verdict === null ? '' : String(v.verdict);
+    const note = v.note !== undefined && v.note !== null && String(v.note).trim()
+      ? ` (${String(v.note).trim()})` : '';
+    return `${id}${id && verdict ? ': ' : ''}${verdict}${note}`;
+  }
+  return String(v);
+}
+
+/**
+ * A persisted form ask (ruling X3) as the two strings Ask Worca's get_run_progress
+ * reports (ruling X17): the text projection, capped at PROMPT_PROJECTION_MAX, and the
+ * answered values. null for a legacy round, whose questions/answers arrays carry
+ * everything as they always have. Unredacted — the tool applies its own `redact`,
+ * because free text from an agent is DATA, never instructions. A projection that
+ * cannot be built (a junk persisted row) degrades to the title, never throws.
+ * @param {object|null} ask
+ * @returns {{projection: string, values: string}|null}
+ */
+export function askProgress(ask) {
+  if (!ask || typeof ask !== 'object' || ask.kind !== 'form') return null;
+  let projection = '';
+  try { projection = projectForm(ask, { maxChars: PROMPT_PROJECTION_MAX }); } catch { projection = String(ask.title || ask.form || ''); }
+  return { projection, values: askValuesText(ask) };
+}
+
+/**
+ * The answered values of a PERSISTED form ask (P2 E13: the resolved ask with `values`
+ * merged in), as `Label: value` lines in promptFields order. Keys promptFields does not
+ * know — a value left over from an older version of the form — are printed last by
+ * their field name rather than dropped. Always a string; '' when nothing was answered.
+ * @param {object|null} ask
+ * @returns {string}
+ */
+export function askValuesText(ask) {
+  const values = ask && typeof ask === 'object' && ask.values && typeof ask.values === 'object'
+    ? ask.values : null;
+  if (!values) return '';
+  let fields = [];
+  try { fields = promptFields(ask); } catch { fields = []; }
+  const labels = new Map(fields.map((f) => [f.field, f.label || f.field]));
+  const ordered = fields.map((f) => f.field).filter((k) => Object.hasOwn(values, k));
+  const rest = Object.keys(values).filter((k) => !labels.has(k));
+  const keys = [...ordered, ...rest];
+  if (!keys.length) return '';
+  return keys.map((k) => `${labels.get(k) || k}: ${valueText(values[k])}`).join('\n');
+}

package/src/core/bridge/errors.mjs

@@ -0,0 +1,84 @@
+// src/core/bridge/errors.mjs
+// Upstream failures -> the Anthropic error envelope the CLI understands
+// (model-bridge-design.md §5.7). The status AND the `error.type` both matter:
+// the CLI's retry/backoff keys on the status, worca's classifyError keys on
+// the message text (auth / rate_limit / ...), and the Test button's hints on
+// both. Pure.
+
+/** Hard payload ceiling before forwarding (Copilot's observed limit). */
+export const PAYLOAD_CEILING_BYTES = 2_500_000;
+
+/** The phrase Claude Code matches on to trigger its own compaction. */
+export const PROMPT_TOO_LONG = 'prompt is too long';
+
+const CONTEXT_RE = /context.?length|too long|maximum context|token limit|exceeds? .*tokens|too many tokens|request too large|payload too large/i;
+
+/** Envelope for a status/type/message triple. */
+export function anthropicError(status, type, message) {
+  return { status, body: { type: 'error', error: { type, message: String(message || type) } } };
+}
+
+/** Pull a human message out of an upstream error body (JSON or text). */
+export function upstreamMessage(text) {
+  if (!text) return '';
+  try {
+    const j = JSON.parse(text);
+    const e = j && (j.error || j);
+    if (e && typeof e === 'object') return e.message || e.msg || e.code || JSON.stringify(e);
+    if (typeof e === 'string') return e;
+  } catch { /* not JSON */ }
+  return String(text).slice(0, 500);
+}
+
+/**
+ * Map an upstream HTTP failure to the envelope.
+ * @param {number} status  upstream status
+ * @param {string} text  upstream body text
+ * @param {{provider?:string, retryAfter?:string}} [meta]
+ */
+export function mapUpstreamError(status, text, { provider = 'upstream', retryAfter } = {}) {
+  const msg = upstreamMessage(text);
+  const who = provider;
+  if (status === 401 || status === 403) {
+    return anthropicError(401, 'authentication_error', `${who}: authentication failed (${status})${msg ? ` — ${msg}` : ''}`);
+  }
+  if (status === 429) {
+    const e = anthropicError(429, 'rate_limit_error', `${who}: rate limited (429)${msg ? ` — ${msg}` : ''}`);
+    if (retryAfter) e.headers = { 'retry-after': String(retryAfter) };
+    return e;
+  }
+  if (status === 413 || (status === 400 && CONTEXT_RE.test(msg))) {
+    return anthropicError(400, 'invalid_request_error', PROMPT_TOO_LONG);
+  }
+  if (status === 404) {
+    return anthropicError(400, 'invalid_request_error', `${who}: model or endpoint not found (404)${msg ? ` — ${msg}` : ''}`);
+  }
+  if (status >= 400 && status < 500) {
+    return anthropicError(400, 'invalid_request_error', `${who}: request rejected (${status})${msg ? ` — ${msg}` : ''}`);
+  }
+  if (status === 503 || status === 529) {
+    return anthropicError(529, 'overloaded_error', `${who}: overloaded (${status})${msg ? ` — ${msg}` : ''}`);
+  }
+  return anthropicError(502, 'api_error', `${who}: upstream error (${status})${msg ? ` — ${msg}` : ''}`);
+}
+
+/** A network-level failure (fetch threw) -> envelope. */
+export function mapNetworkError(err, { provider = 'upstream' } = {}) {
+  const name = err && err.name;
+  if (name === 'AbortError') return anthropicError(499, 'api_error', `${provider}: request aborted`);
+  if (name === 'TimeoutError') return anthropicError(504, 'api_error', `${provider}: upstream timed out`);
+  const detail = err && (err.cause && err.cause.message || err.message) || String(err);
+  return anthropicError(502, 'api_error', `${provider}: endpoint unreachable — ${detail}`);
+}
+
+/** The bridge's own refusals (bad bearer, unknown model, feature gaps). */
+export const bridgeErrors = {
+  unauthorized: () => anthropicError(401, 'authentication_error', 'bridge: invalid bearer token'),
+  unknownModel: (id) => anthropicError(404, 'not_found_error', `bridge: no bridged model ${JSON.stringify(id)} in the catalog`),
+  notSignedIn: (provider, hint) => anthropicError(401, 'authentication_error', `provider ${provider}: not signed in — ${hint}`),
+  termsNotAcknowledged: (provider) => anthropicError(401, 'authentication_error', `provider ${provider}: terms not acknowledged — open Settings › Providers`),
+  tooLarge: () => anthropicError(400, 'invalid_request_error', PROMPT_TOO_LONG),
+  badJson: () => anthropicError(400, 'invalid_request_error', 'bridge: request body is not JSON'),
+  unsupported: (message) => anthropicError(400, 'invalid_request_error', message),
+  notFound: () => anthropicError(404, 'not_found_error', 'bridge: unknown route'),
+};

package/src/core/bridge/provider-ops.mjs

@@ -0,0 +1,281 @@
+// src/core/bridge/provider-ops.mjs
+// The operations the Providers card and `worca models …` share
+// (model-bridge-design.md §8.1, §8.4, §9): sign-in sessions for the Copilot
+// device flow, sign-out, the provider state payload (never a token), the
+// Copilot models list for import, the import itself, and a connection test
+// for the key-based providers. Import contract: settings.mjs + the bridge's
+// own modules; config.mjs imports NOTHING from here (the bridge is below it).
+
+import {
+  providerConfig, allProviders, updateProvider, resolveProviderSecret, providerSecretSet,
+  copilotTermsAcknowledged, acknowledgeCopilotTerms, clearCopilotSignIn,
+  listGlobalModels, addGlobalModel, updateGlobalModel,
+} from '../settings.mjs';
+import { modelEnvRef, maskModelEnvValue, COPILOT_TERMS_VERSION, UPSTREAM_PROVIDERS, isUpstreamBaseUrl } from '../model-env.mjs';
+import {
+  startDeviceFlow, pollDeviceFlow, githubLogin, copilotToken, invalidateCopilotToken,
+  listCopilotModels, copilotUsage, catalogEntryForCopilotModel,
+} from './providers/copilot.mjs';
+import { keyOptional } from './registry.mjs';
+import { listEndpointModels, catalogEntryForEndpointModel, importableModel } from './providers/endpoint.mjs';
+
+// ── Copilot sign-in sessions (in memory; a device code lives ~15 min) ────────
+const sessions = new Map();   // deviceCode -> { startedAt, expiresAt, interval, lastPoll }
+const SESSION_TTL_MS = 20 * 60 * 1000;
+
+function sweepSessions(now = Date.now()) {
+  for (const [k, s] of sessions) if (s.expiresAt < now) sessions.delete(k);
+}
+
+/**
+ * Begin a Copilot sign-in. Refuses until the terms are acknowledged (§8.2).
+ * @returns {Promise<{deviceCode, userCode, verificationUri, interval, expiresIn}>}
+ */
+export async function beginCopilotLogin({ fetch: f } = {}) {
+  if (!copilotTermsAcknowledged()) {
+    throw Object.assign(new Error('acknowledge the GitHub Copilot notice before signing in'), { code: 'TERMS' });
+  }
+  sweepSessions();
+  const flow = await startDeviceFlow({ fetch: f });
+  sessions.set(flow.deviceCode, { startedAt: Date.now(), expiresAt: Date.now() + Math.min(flow.expiresIn * 1000, SESSION_TTL_MS), interval: flow.interval });
+  return flow;
+}
+
+/**
+ * One poll of a sign-in session. On approval the GitHub token and login are
+ * stored and the session ends.
+ * @returns {Promise<{pending:true, interval?:number}|{ok:true, login:string}|{error:string}>}
+ */
+export async function pollCopilotLogin(deviceCode, { fetch: f } = {}) {
+  sweepSessions();
+  const s = sessions.get(deviceCode);
+  if (!s) return { error: 'unknown or expired sign-in session — start again' };
+  const r = await pollDeviceFlow(deviceCode, { fetch: f });
+  if (r.pending) { if (r.interval) s.interval = r.interval; return { pending: true, interval: s.interval }; }
+  sessions.delete(deviceCode);
+  if (r.error) return { error: r.error };
+  let login = '';
+  try { login = await githubLogin(r.token, { fetch: f }); } catch { login = ''; }
+  // Prove the account has Copilot before storing: a token without Copilot
+  // access would only fail later, mid-run.
+  try {
+    await copilotToken(r.token, { fetch: f, force: true });
+  } catch (err) {
+    return { error: err && err.code === 'EXCHANGE' ? `signed in as ${login || 'GitHub user'}, but the account has no Copilot access — ${err.message}` : (err.message || String(err)) };
+  }
+  await updateProvider('copilot', { githubToken: r.token, ...(login ? { login } : {}) });
+  return { ok: true, login };
+}
+
+/** Sign out of Copilot: forget the token, drop the cached exchange. */
+export async function copilotLogout() {
+  const cfg = providerConfig('copilot');
+  const tok = resolveProviderSecret(cfg.githubToken);
+  if (tok) invalidateCopilotToken(tok);
+  await clearCopilotSignIn();
+}
+
+/** Record the terms acknowledgement (§8.2). */
+export async function acknowledgeTerms() { return acknowledgeCopilotTerms(); }
+
+// ── state payloads (never a secret) ──────────────────────────────────────────
+
+const secretSource = (v) => (!v ? null : modelEnvRef(v) ? 'env' : 'stored');
+
+/**
+ * The Providers card payload (§9). `quota` is fetched only when asked — it is
+ * a network call to GitHub — and is null when the account exposes none.
+ * @param {{quota?:boolean, fetch?:typeof fetch}} [opts]
+ */
+export async function providersState({ quota = false, fetch: f } = {}) {
+  const all = allProviders();
+  const c = all.copilot;
+  const token = resolveProviderSecret(c.githubToken);
+  const copilot = {
+    connected: !!token,
+    login: c.login || null,
+    accountType: c.accountType,
+    acknowledgedTerms: c.acknowledgedTerms || null,
+    termsCurrent: copilotTermsAcknowledged(),
+    termsVersion: COPILOT_TERMS_VERSION,
+    maxConcurrent: c.maxConcurrent,
+    tokenSource: secretSource(c.githubToken),
+    tokenRef: modelEnvRef(c.githubToken) ? c.githubToken : null,
+    quota: null,
+  };
+  if (quota && token) {
+    try { copilot.quota = await copilotUsage(token, { fetch: f }); } catch { copilot.quota = null; }
+  }
+  const keyed = (name) => {
+    const p = all[name];
+    return {
+      configured: !!resolveProviderSecret(p.apiKey),
+      keyOptional: keyOptional(name, p.baseUrl),
+      keySet: providerSecretSet(name),
+      keySource: secretSource(p.apiKey),
+      keyRef: modelEnvRef(p.apiKey) ? p.apiKey : null,
+      keyMasked: p.apiKey && !modelEnvRef(p.apiKey) ? maskModelEnvValue(p.apiKey) : null,
+      baseUrl: p.baseUrl,
+      maxConcurrent: p.maxConcurrent,
+    };
+  };
+  return { copilot, openai: keyed('openai'), anthropic: keyed('anthropic') };
+}
+
+/** Patch a provider from the UI/CLI; masked key echoes are dropped ("keep"). */
+export async function patchProvider(name, patch = {}) {
+  if (!UPSTREAM_PROVIDERS.includes(name)) throw new Error(`unknown provider ${JSON.stringify(name)}`);
+  const p = { ...patch };
+  for (const k of ['apiKey', 'githubToken']) if (typeof p[k] === 'string' && p[k].startsWith('••')) delete p[k];
+  return updateProvider(name, p);
+}
+
+// ── Copilot models: list for import, import ─────────────────────────────────
+
+/** Copilot's models for the import sheet, each with `inCatalog` (§8.4). */
+export async function copilotModelsForImport({ fetch: f } = {}) {
+  const c = providerConfig('copilot');
+  const token = resolveProviderSecret(c.githubToken);
+  if (!token) throw Object.assign(new Error('not signed in to GitHub Copilot'), { code: 'NOT_SIGNED_IN' });
+  const list = await listCopilotModels(token, { accountType: c.accountType, fetch: f });
+  const have = new Set(listGlobalModels().map((m) => m.id.toLowerCase()));
+  return list.map((m) => ({ ...m, catalogId: `copilot-${m.id}`, inCatalog: have.has(`copilot-${m.id}`.toLowerCase()) }))
+    .sort((a, b) => (Number(b.pickerEnabled) - Number(a.pickerEnabled)) || a.name.localeCompare(b.name));
+}
+
+/**
+ * Import Copilot models into the catalog (§8.4). A new id gets the full
+ * import shape; an existing `copilot-*` id only has its capabilities (and api,
+ * should the vendor route change) refreshed — a user-edited label, efforts or
+ * pricing is never overwritten.
+ * @param {string[]} ids  Copilot model ids (not catalog ids)
+ * @returns {Promise<{created:string[], updated:string[], skipped:string[]}>}
+ */
+export async function importCopilotModels(ids, { fetch: f } = {}) {
+  const wanted = new Set((Array.isArray(ids) ? ids : []).map((s) => String(s)));
+  if (!wanted.size) throw new Error('pick at least one model to import');
+  const list = await copilotModelsForImport({ fetch: f });
+  const byId = new Map(list.map((m) => [m.id, m]));
+  const created = []; const updated = []; const skipped = [];
+  for (const id of wanted) {
+    const m = byId.get(id);
+    if (!m) { skipped.push(id); continue; }
+    const entry = catalogEntryForCopilotModel(m);
+    if (m.inCatalog) {
+      const current = listGlobalModels().find((x) => x.id.toLowerCase() === entry.id.toLowerCase());
+      if (!current || !current.upstream || current.upstream.provider !== 'copilot') { skipped.push(id); continue; }
+      await updateGlobalModel(current.id, { upstream: { ...current.upstream, api: entry.upstream.api, model: entry.upstream.model, capabilities: entry.upstream.capabilities } });
+      updated.push(current.id);
+    } else {
+      await addGlobalModel(entry);
+      created.push(entry.id);
+    }
+  }
+  return { created, updated, skipped };
+}
+
+// ── OpenAI-compatible endpoints: discovery, import ──────────────────────────
+
+/** The provider's own base URL when the caller names none, trailing slash trimmed. */
+function endpointBase(baseUrl) {
+  const b = String(baseUrl || '').trim() || providerConfig('openai').baseUrl || '';
+  if (!isUpstreamBaseUrl(b)) throw new Error('baseUrl must be an http(s) URL with no query or fragment');
+  return b.replace(/\/+$/, '');
+}
+
+/**
+ * What an OpenAI-compatible endpoint serves, each row with `catalogId` and `inCatalog` (§8.4's
+ * Copilot import, for a server you run: llama.cpp, Ollama, LM Studio, vLLM, a gateway).
+ * @param {{baseUrl?:string, fetch?:typeof fetch}} [opts]
+ */
+export async function endpointModelsForImport({ baseUrl, fetch: f } = {}) {
+  const base = endpointBase(baseUrl);
+  const p = providerConfig('openai');
+  const key = resolveProviderSecret(p.apiKey);
+  const out = await listEndpointModels(base, { apiKey: key, fetch: f });
+  const have = new Set(listGlobalModels().map((m) => m.id.toLowerCase()));
+  return {
+    ...out,
+    models: out.models.map((m) => {
+      const entry = catalogEntryForEndpointModel(m, { server: out.server, baseUrl: out.baseUrl, providerBaseUrl: p.baseUrl });
+      const usable = importableModel(m);
+      return { ...m, catalogId: entry.id, inCatalog: have.has(entry.id.toLowerCase()), importable: usable.ok, ...(usable.ok ? {} : { blocked: usable.why }) };
+    }),
+  };
+}
+
+/**
+ * Import endpoint models into the catalog. A new id gets the full entry; an existing one keeps the
+ * label, efforts and pricing you edited and only has its upstream refreshed — the Copilot rule.
+ * @param {string[]} ids  model ids as the endpoint reports them (not catalog ids)
+ * @returns {Promise<{created:string[], updated:string[], skipped:Array<{id:string, why:string}>, server:string, baseUrl:string}>}
+ */
+export async function importEndpointModels(ids, { baseUrl, fetch: f } = {}) {
+  const wanted = new Set((Array.isArray(ids) ? ids : []).map((s) => String(s)));
+  if (!wanted.size) throw new Error('pick at least one model to import');
+  const out = await endpointModelsForImport({ baseUrl, fetch: f });
+  const byId = new Map(out.models.map((m) => [m.id, m]));
+  const p = providerConfig('openai');
+  const created = []; const updated = []; const skipped = [];
+  for (const id of wanted) {
+    const m = byId.get(id);
+    if (!m) { skipped.push({ id, why: 'the endpoint does not serve it' }); continue; }
+    if (!m.importable) { skipped.push({ id, why: m.blocked || 'not usable in a pipeline' }); continue; }
+    const entry = catalogEntryForEndpointModel(m, { server: out.server, baseUrl: out.baseUrl, providerBaseUrl: p.baseUrl });
+    const current = listGlobalModels().find((x) => x.id.toLowerCase() === entry.id.toLowerCase());
+    if (current) {
+      if (!current.upstream || current.upstream.provider !== 'openai') { skipped.push({ id, why: `"${current.id}" already exists and is not an OpenAI-compatible entry` }); continue; }
+      await updateGlobalModel(current.id, { upstream: { ...current.upstream, model: entry.upstream.model, ...(entry.upstream.baseUrl ? { baseUrl: entry.upstream.baseUrl } : {}), ...(entry.upstream.capabilities ? { capabilities: entry.upstream.capabilities } : {}) } });
+      updated.push(current.id);
+    } else {
+      await addGlobalModel(entry);
+      created.push(entry.id);
+    }
+  }
+  return { created, updated, skipped, server: out.server, serverLabel: out.serverLabel, baseUrl: out.baseUrl, warnings: out.warnings };
+}
+
+// ── key-based providers: connection test ────────────────────────────────────
+
+/**
+ * A cheap reachability + auth check for openai / anthropic (§8.1): GET the models list with the
+ * configured key. Never throws.
+ *
+ * `baseUrl` / `apiKey` test values that are NOT stored yet — what the user has typed into the
+ * Providers card. Testing the stored ones instead made the button lie: type a local llama.cpp URL,
+ * press Test, and the answer was "no API key configured", because it had tested api.openai.com.
+ * A masked echo (••…) means "keep what is stored" exactly as a save does.
+ * @returns {Promise<{ok:true, models?:number}|{ok:false, message:string}>}
+ */
+export async function testProviderConnection(name, { fetch: f = globalThis.fetch, baseUrl = '', apiKey } = {}) {
+  if (name === 'copilot') {
+    const c = providerConfig('copilot');
+    const token = resolveProviderSecret(c.githubToken);
+    if (!token) return { ok: false, message: 'not signed in' };
+    try { await copilotToken(token, { fetch: f, force: true }); return { ok: true }; } catch (err) { return { ok: false, message: err.message || String(err) }; }
+  }
+  if (!UPSTREAM_PROVIDERS.includes(name)) return { ok: false, message: `unknown provider ${name}` };
+  const stored = providerConfig(name);
+  const typedKey = typeof apiKey === 'string' && !apiKey.startsWith('••') ? apiKey.trim() : null;
+  const p = {
+    ...stored,
+    ...(baseUrl && isUpstreamBaseUrl(baseUrl) ? { baseUrl: baseUrl.trim().replace(/\/+$/, '') } : {}),
+    ...(typedKey === null ? {} : { apiKey: typedKey }),
+  };
+  const key = resolveProviderSecret(p.apiKey);
+  const keyIsSet = typedKey === null ? providerSecretSet(name) : !!typedKey;
+  if (!key && (keyIsSet || !keyOptional(name, p.baseUrl))) return { ok: false, message: keyIsSet ? 'the key\'s ${VAR} is not set in worca\'s environment' : `no API key configured for ${p.baseUrl}` };
+  const base = (p.baseUrl || '').replace(/\/+$/, '');
+  const url = name === 'anthropic' ? (/\/v1$/.test(base) ? `${base}/models` : `${base}/v1/models`) : `${base}/models`;
+  const headers = name === 'anthropic' ? { 'x-api-key': key, 'anthropic-version': '2023-06-01' } : (key ? { authorization: `Bearer ${key}` } : {});
+  try {
+    const r = await f(url, { headers, signal: AbortSignal.timeout(15_000) });
+    if (r.status === 401 || r.status === 403) return { ok: false, message: `authentication failed (${r.status})` };
+    if (!r.ok) return { ok: false, message: `endpoint answered ${r.status}` };
+    const j = await r.json().catch(() => null);
+    const n = j && Array.isArray(j.data) ? j.data.length : undefined;
+    return { ok: true, ...(n !== undefined ? { models: n } : {}) };
+  } catch (err) {
+    return { ok: false, message: `endpoint unreachable — ${err && err.message ? err.message : String(err)}` };
+  }
+}