@visual-z/xeno 0.2.1 → 0.3.0

package/src/runtime/model-discovery.ts

@@ -0,0 +1,208 @@
+/**
+ * Live model discovery: ask the provider which models this key can use.
+ *
+ * Wire vocabulary (URLs, auth headers, response shapes) belongs to runtime,
+ * not the SDK-free core (D13). Everything except `discoverModels` is pure so
+ * the URL and parsing rules are unit tested without a network.
+ *
+ * Endpoints, per the vendors' own list APIs and what magpie / CC Switch /
+ * Crush converged on (docs/tasks/feat-provider-connect.md):
+ *   OpenAI-compatible  GET {base}/models                Authorization: Bearer
+ *   Anthropic          GET {root}/v1/models             x-api-key + anthropic-version
+ *                      (paged: has_more / last_id → ?after_id=)
+ *   Gemini             GET {base}/models                x-goog-api-key
+ *                      (paged: nextPageToken → ?pageToken=; keep generateContent)
+ *
+ * A pasted full endpoint (…/chat/completions, …/v1/messages) is cut back to
+ * its base, and a base without a version segment also tries `/v1`, because
+ * gateways disagree on where the version lives. Anthropic-compatible
+ * gateways often want Bearer instead of x-api-key; both are sent (magpie).
+ */
+import type { ProviderApi } from "./provider-protocols.ts";
+
+export type DiscoveryFamily = "openai" | "anthropic" | "google";
+
+export interface DiscoveredModel {
+  id: string;
+  name?: string;
+  contextWindow?: number;
+  maxTokens?: number;
+}
+
+export type DiscoveryResult =
+  | { ok: true; models: DiscoveredModel[]; url: string }
+  | { ok: false; reason: string; status?: number };
+
+export function discoveryFamily(api: ProviderApi): DiscoveryFamily | undefined {
+  switch (api) {
+    case "openai-completions":
+    case "openai-responses":
+    case "mistral-conversations":
+      return "openai";
+    case "anthropic-messages":
+      return "anthropic";
+    case "google-generative-ai":
+      return "google";
+    default:
+      // Vertex, Bedrock, Azure, Codex and Pi need cloud auth or have no
+      // listing endpoint; their catalog entries stay authoritative.
+      return undefined;
+  }
+}
+
+const ENDPOINT_SUFFIXES = [/\/chat\/completions\/?$/, /\/responses\/?$/, /\/completions\/?$/, /\/messages\/?$/, /\/models\/?$/];
+
+/** Strip whitespace, trailing slashes and a pasted operation path. */
+export function normalizeBaseUrl(raw: string): string {
+  let url = raw.trim().replace(/\/+$/, "");
+  for (const suffix of ENDPOINT_SUFFIXES) url = url.replace(suffix, "");
+  return url.replace(/\/+$/, "");
+}
+
+const VERSIONED = /\/v\d+(beta\d*|alpha\d*)?$/;
+
+export function discoveryUrls(family: DiscoveryFamily, baseUrl: string): string[] {
+  const base = normalizeBaseUrl(baseUrl);
+  const urls: string[] = [];
+  const add = (url: string) => { if (!urls.includes(url)) urls.push(url); };
+  switch (family) {
+    case "openai":
+      add(`${base}/models`);
+      if (!VERSIONED.test(base)) add(`${base}/v1/models`);
+      break;
+    case "anthropic": {
+      const root = base.replace(/\/v1$/, "");
+      add(`${root}/v1/models`);
+      add(`${base}/models`);
+      break;
+    }
+    case "google":
+      add(VERSIONED.test(base) ? `${base}/models` : `${base}/v1beta/models`);
+      break;
+  }
+  return urls;
+}
+
+export function discoveryHeaders(family: DiscoveryFamily, key: string): Record<string, string> {
+  if (key.length === 0) return {};
+  switch (family) {
+    case "openai": return { authorization: `Bearer ${key}` };
+    case "anthropic": return { "x-api-key": key, authorization: `Bearer ${key}`, "anthropic-version": "2023-06-01" };
+    case "google": return { "x-goog-api-key": key };
+  }
+}
+
+function record(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function positive(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : undefined;
+}
+function text(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+
+/** One page of a list response. `next` is the query to append for the following page. */
+export function parseModelPage(family: DiscoveryFamily, json: unknown): { models: DiscoveredModel[]; next?: string } {
+  if (!record(json)) return { models: [] };
+  const rows = Array.isArray(json["data"]) ? json["data"] : Array.isArray(json["models"]) ? json["models"] : [];
+  const models: DiscoveredModel[] = [];
+  for (const row of rows) {
+    if (!record(row)) continue;
+    if (family === "google") {
+      const methods = row["supportedGenerationMethods"];
+      if (Array.isArray(methods) && !methods.includes("generateContent")) continue;
+      const id = text(row["name"])?.replace(/^models\//, "") ?? text(row["id"]);
+      if (!id) continue;
+      models.push(compact({ id, name: text(row["displayName"]), contextWindow: positive(row["inputTokenLimit"]), maxTokens: positive(row["outputTokenLimit"]) }));
+      continue;
+    }
+    const id = text(row["id"]) ?? text(row["name"]);
+    if (!id) continue;
+    // OpenRouter and several gateways publish limits on the listing itself.
+    const top = record(row["top_provider"]) ? row["top_provider"] : {};
+    models.push(compact({
+      id,
+      name: text(row["display_name"]) ?? (text(row["name"]) !== id ? text(row["name"]) : undefined),
+      contextWindow: positive(row["context_length"]) ?? positive(row["context_window"]) ?? positive(top["context_length"]),
+      maxTokens: positive(row["max_output_tokens"]) ?? positive(top["max_completion_tokens"]),
+    }));
+  }
+  if (family === "anthropic" && json["has_more"] === true && text(json["last_id"])) return { models, next: `after_id=${encodeURIComponent(String(json["last_id"]))}` };
+  if (family === "google" && text(json["nextPageToken"])) return { models, next: `pageToken=${encodeURIComponent(String(json["nextPageToken"]))}` };
+  return { models };
+}
+
+function compact(model: { id: string; name: string | undefined; contextWindow: number | undefined; maxTokens: number | undefined }): DiscoveredModel {
+  return { id: model.id, ...(model.name !== undefined ? { name: model.name } : {}),
+    ...(model.contextWindow !== undefined ? { contextWindow: model.contextWindow } : {}),
+    ...(model.maxTokens !== undefined ? { maxTokens: model.maxTokens } : {}) };
+}
+
+/**
+ * `/models` on OpenAI-style endpoints also lists embeddings, speech, image and
+ * moderation models. They can never run a coding turn, so the picker should
+ * not offer them. Pattern list, not a guess per model: ids that match are
+ * still shown in the wizard under "other", just not preselected.
+ */
+const NON_CHAT = /(^|[-_/.:])(embed|embedding|embeddings|tts|whisper|transcribe|dall-e|dalle|moderation|image|imagen|audio|realtime|speech|rerank|reranker|search|veo|sora|davinci|babbage)([-_/.:]|\d|$)/i;
+export function likelyChatModel(id: string): boolean {
+  return !NON_CHAT.test(id);
+}
+
+/**
+ * Network IO. Candidates are tried in order; 404/405 moves on, an auth
+ * failure stops (another URL will not make a wrong key right), and any
+ * other failure is reported with the URL that produced it.
+ * Timeout 10s per request: assumed; long enough for a slow gateway's first
+ * response, short enough that a dead host is reported while the user waits.
+ */
+const DISCOVERY_TIMEOUT_MS = 10_000;
+/** Pagination bound: Anthropic pages at 20 by default; 25 pages covers every known list. Assumed. */
+const MAX_PAGES = 25;
+
+export async function discoverModels(opts: {
+  family: DiscoveryFamily;
+  baseUrl: string;
+  key: string;
+  headers?: Record<string, string>;
+  fetch: (input: string, init?: RequestInit) => Promise<Response>;
+  signal?: AbortSignal;
+  timeoutMs?: number;
+}): Promise<DiscoveryResult> {
+  const headers = { accept: "application/json", ...discoveryHeaders(opts.family, opts.key), ...opts.headers };
+  let last: DiscoveryResult = { ok: false, reason: "no discovery URL" };
+  for (const url of discoveryUrls(opts.family, opts.baseUrl)) {
+    const models: DiscoveredModel[] = [];
+    let query: string | undefined;
+    let failed: DiscoveryResult | undefined;
+    for (let page = 0; page < MAX_PAGES; page++) {
+      const target = query ? `${url}${url.includes("?") ? "&" : "?"}${query}` : url;
+      let response: Response;
+      try {
+        const timeout = AbortSignal.timeout(opts.timeoutMs ?? DISCOVERY_TIMEOUT_MS);
+        response = await opts.fetch(target, { headers, signal: opts.signal ? AbortSignal.any([opts.signal, timeout]) : timeout });
+      } catch (error) {
+        if (opts.signal?.aborted) return { ok: false, reason: "cancelled" };
+        failed = { ok: false, reason: `${url}: ${error instanceof Error && error.name === "TimeoutError" ? "timed out" : error instanceof Error ? error.message : String(error)}` };
+        break;
+      }
+      if (response.status === 401 || response.status === 403) {
+        return { ok: false, status: response.status, reason: `${url}: authentication failed (HTTP ${response.status}); check the API key` };
+      }
+      if (!response.ok) { failed = { ok: false, status: response.status, reason: `${url}: HTTP ${response.status}` }; break; }
+      let json: unknown;
+      try { json = await response.json(); } catch { failed = { ok: false, reason: `${url}: response is not JSON` }; break; }
+      const parsed = parseModelPage(opts.family, json);
+      models.push(...parsed.models);
+      if (!parsed.next) break;
+      query = parsed.next;
+    }
+    if (!failed && models.length > 0) {
+      const seen = new Set<string>();
+      return { ok: true, url, models: models.filter(model => !seen.has(model.id) && seen.add(model.id)) };
+    }
+    last = failed ?? { ok: false, reason: `${url}: the provider returned no models` };
+  }
+  return last;
+}

package/src/runtime/native-eval-fixtures.ts

@@ -0,0 +1,33 @@
+/** Q.20: a synthetic wire peer validates the native path without spending model quota. */
+import { nativeWire } from "./native-eval.ts";
+import { toolModeBackend } from "./tool-mode-eval.ts";
+import type { EvalFixture } from "./harness-eval.ts";
+
+export function nativeFixtureFetch(fixture: EvalFixture): typeof fetch {
+  const backend = toolModeBackend(fixture);
+  return (async (input: RequestInfo | URL, init?: RequestInit) => {
+    const request = new Request(input, init), payload = await nativeWire(request);
+    const tools = payload["tools"] as { name: string; parameters: unknown }[];
+    const source = payload["input"] as Record<string, unknown>[];
+    const response = await backend({ tools: tools.map(tool => ({ function: tool })),
+      messages: source.filter(item => item["type"] === "function_call_output").map(item => ({ role: "tool", content: item["output"] })) }, request.signal) as {
+        id: string; choices: { message: { content: string | null; tool_calls?: { id: string; function: { name: string; arguments: string } }[] } }[] };
+    const message = response.choices[0]!.message, events: unknown[] = [], output: unknown[] = [];
+    for (const [index, call] of (message.tool_calls ?? []).entries()) {
+      const item = { type: "function_call", id: "fc_" + call.id, call_id: call.id, name: call.function.name, arguments: call.function.arguments, status: "completed" };
+      events.push({ type: "response.output_item.added", output_index: index, item: { ...item, arguments: "" } },
+        { type: "response.function_call_arguments.delta", output_index: index, delta: call.function.arguments },
+        { type: "response.output_item.done", output_index: index, item }); output.push(item);
+    }
+    if (message.content) {
+      const item = { type: "message", id: "msg_" + response.id, role: "assistant", content: [{ type: "output_text", text: message.content, annotations: [] }], status: "completed" };
+      events.push({ type: "response.output_item.added", output_index: 0, item: { ...item, content: [] } },
+        { type: "response.content_part.added", output_index: 0, content_index: 0, part: { type: "output_text", text: "", annotations: [] } },
+        { type: "response.output_text.delta", output_index: 0, content_index: 0, delta: message.content },
+        { type: "response.output_item.done", output_index: 0, item }); output.push(item);
+    }
+    events.push({ type: "response.completed", response: { id: response.id, model: "gpt-6-luna", status: "completed", output,
+      usage: { input_tokens: 200, output_tokens: 32, input_tokens_details: { cached_tokens: 50, cache_write_tokens: 20 }, total_tokens: 232 } } });
+    return new Response(events.map(event => "data: " + JSON.stringify(event) + "\n\n").join(""), { headers: { "content-type": "text/event-stream" } });
+  }) as typeof fetch;
+}

package/src/runtime/native-eval.ts

@@ -0,0 +1,143 @@
+/** Q.20: meter the production Responses adapter without translating its wire protocol. */
+import { createHash } from "node:crypto";
+import { nativeMeasured, nativeReservation, nativeUsage } from "../core/native-eval.ts";
+import type { BenchmarkPrice } from "../core/benchmark.ts";
+import type { FrozenPrefix, Message } from "../core/project.ts";
+import type { Provider, ProviderConfig } from "./provider.ts";
+import { PiProvider } from "./pi-provider.ts";
+import type { ComparisonLedger, GatewayRecord } from "./harness-comparison.ts";
+
+const digest = (body: string) => createHash("sha256").update(body).digest("hex");
+const bytes = (body: string) => new TextEncoder().encode(body);
+const noEffects = { env: () => undefined, run: () => { throw Error("evaluation forbids credential commands"); } };
+// Offline replay only. It has the SDK's required claim shape, no signature or authority.
+export const NATIVE_EVAL_TEST_KEY = "offline." + btoa(JSON.stringify({ "https://api.openai.com/auth": { chatgpt_account_id: "offline-evaluation" } })) + ".unsigned";
+
+export async function nativeWire(request: Request): Promise<Record<string, unknown>> {
+  const raw = new Uint8Array(await request.clone().arrayBuffer());
+  if (raw.length > 8 * 1024 * 1024) throw Error("native eval wire exceeds archive bound");
+  const body = request.headers.get("content-encoding") === "zstd" ? Bun.zstdDecompressSync(raw) : raw;
+  if (body.length > 8 * 1024 * 1024) throw Error("native eval wire exceeds archive bound");
+  return JSON.parse(new TextDecoder().decode(body)) as Record<string, unknown>;
+}
+/** Running the same serializer with a local fetch prevents a second, approximate wire builder. */
+export async function nativePayload(config: ProviderConfig, frozen: FrozenPrefix, messages: Message[]): Promise<Record<string, unknown>> {
+  let payload: Record<string, unknown> | undefined;
+  const capture = (async (input: RequestInfo | URL, init?: RequestInit) => {
+    payload = await nativeWire(new Request(input, init));
+    return new Response(null, { status: 400 });
+  }) as typeof fetch;
+  const provider = new PiProvider(config, NATIVE_EVAL_TEST_KEY, { oauth: true, effects: noEffects, fetch: capture, retry: { maxRetries: 0, maxRetryDelayMs: 0 } });
+  await provider.send(frozen, messages, 0).catch(() => {});
+  if (!payload) throw Error("native offline wire was not produced");
+  return payload;
+}
+export function nativeInput(payload: Record<string, unknown>): { bytes: Uint8Array; messages: unknown[] } {
+  if (!Array.isArray(payload["input"])) throw Error("native input is missing");
+  return { bytes: bytes(JSON.stringify([payload["instructions"], payload["tools"] ?? [], payload["input"]])), messages: payload["input"] };
+}
+export interface NativeResponse { model: unknown; usage: unknown; status: unknown; service_tier: unknown }
+
+/** Forward unchanged chunks with backpressure; retain only a terminal receipt, never headers. */
+export function nativeResponseTap(body: ReadableStream<Uint8Array>, terminal: (response: NativeResponse) => Promise<void>) {
+  const decoder = new TextDecoder(); let pending = "", observed = false;
+  const line = async (text: string) => {
+    if (!text.startsWith("data:") || text.slice(5).trim() === "[DONE]") return;
+    const event = JSON.parse(text.slice(5)) as Record<string, unknown>;
+    if (!["response.completed", "response.done", "response.incomplete"].includes(String(event["type"]))) return;
+    if (observed) throw Error("duplicate native terminal response");
+    observed = true;
+    const response = event["response"] as Record<string, unknown> | undefined;
+    await terminal({ model: response?.["model"] ?? null, usage: response?.["usage"] ?? null,
+      status: response?.["status"] ?? null, service_tier: response?.["service_tier"] ?? null });
+  };
+  return body.pipeThrough(new TransformStream<Uint8Array, Uint8Array>({
+    async transform(chunk, controller) {
+      pending += decoder.decode(chunk, { stream: true });
+      // The completed event repeats output. Bound this framing buffer separately from the saved receipt.
+      if (pending.length > 8 * 1024 * 1024) throw Error("native SSE frame exceeds archive bound");
+      let at: number;
+      while ((at = pending.indexOf("\n")) >= 0) { await line(pending.slice(0, at).replace(/\r$/, "")); pending = pending.slice(at + 1); }
+      controller.enqueue(chunk);
+    },
+    async flush() { pending += decoder.decode(); if (pending.trim()) await line(pending.trim()); },
+  }));
+}
+
+export function nativeEvalTransport(options: {
+  config: ProviderConfig; key: string; price: BenchmarkPrice; ledger: ComparisonLedger; maxRequests: number;
+  fetch?: typeof fetch;
+  record: (row: GatewayRecord) => Promise<void>;
+  wire: (payload: Record<string, unknown>, request: number) => Promise<void>;
+  response: (receipt: NativeResponse, request: number) => Promise<void>;
+}) {
+  const { config, ledger, price } = options;
+  if (config.spec.api !== "openai-codex-responses" || !config.spec.maxTokens || config.maxTokens !== config.spec.maxTokens)
+    throw Error("native eval must reserve the full subscription model output ceiling");
+  const controller = new AbortController();
+  let requests = 0, stopped: "budget" | "balance" | "error" | "limit" | null = null;
+  let previous: ReturnType<typeof nativeInput> | null = null;
+  let current: { row: GatewayRecord; started: number; terminal: NativeResponse | null; httpStatus: number | null } | undefined;
+  let active = false, idle = Promise.resolve();
+  const observedFetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
+    if (!active || current || controller.signal.aborted || ledger.halted || stopped) throw Error("native eval refused an extra request");
+    if (requests >= options.maxRequests) { stopped = "limit"; throw Error("native request limit"); }
+    const request = new Request(input, init), payload = await nativeWire(request), wire = JSON.stringify(payload);
+    if (payload["model"] !== (config.spec.wireId ?? config.spec.id) || payload["store"] !== false || payload["previous_response_id"] !== undefined || payload["stream"] !== true)
+      throw Error("native wire differs from frozen stateless policy");
+    const reservation = nativeReservation(bytes(wire).length, config.spec.maxTokens!, price);
+    if (ledger.budget === null || ledger.charged + reservation > ledger.budget) { stopped = "budget"; throw Error("native eval budget exhausted"); }
+    const inputState = nativeInput(payload); let shared = 0;
+    if (previous) while (shared < Math.min(previous.bytes.length, inputState.bytes.length) && previous.bytes[shared] === inputState.bytes[shared]) shared++;
+    const unchanged = previous === null ? null : JSON.stringify(inputState.messages.slice(0, previous.messages.length)) === JSON.stringify(previous.messages);
+    previous = inputState;
+    ledger.charged += reservation;
+    const row: GatewayRecord = { kind: "reserved", request: ++requests, inputSha256: digest(wire), inputBytes: inputState.bytes.length,
+      sharedInputBytes: shared, prefixUnchanged: unchanged, hasTools: Array.isArray(payload["tools"]) && payload["tools"].length > 0,
+      reservation, charge: reservation, measured: null, ledgerCharged: ledger.charged, usage: null, failure: null, responseModel: null, wallMs: 0 };
+    const state = { row, started: performance.now(), terminal: null as NativeResponse | null, httpStatus: null as number | null };
+    current = state;
+    await options.record(row); await options.wire(payload, requests);
+    const response = await (options.fetch ?? fetch)(new Request(request, { redirect: "error", signal: AbortSignal.any([controller.signal, request.signal]) }));
+    state.httpStatus = response.status;
+    if (!response.ok || !response.body) { await response.body?.cancel(); throw Error("native upstream response failed"); }
+    return new Response(nativeResponseTap(response.body, async terminal => {
+      state.terminal = terminal; await options.response(terminal, row.request);
+    }), { status: response.status, headers: response.headers });
+  }) as typeof fetch;
+  const actual = new PiProvider(config, options.key, { oauth: true, effects: noEffects, fetch: observedFetch, retry: { maxRetries: 0, maxRetryDelayMs: 0 } });
+  const provider: Provider = { config, async send(frozen, messages, node, signal, onDelta) {
+    if (active) throw Error("native eval model requests must be sequential");
+    active = true; current = undefined;
+    let finish = () => {}; idle = new Promise<void>(resolve => { finish = resolve; });
+    let failed = false;
+    try {
+      const turn = await actual.send(frozen, messages, node, AbortSignal.any([controller.signal, ...(signal ? [signal] : [])]), onDelta);
+      const state = current as { terminal: NativeResponse | null } | undefined;
+      const observed = nativeUsage(state?.terminal);
+      const same = observed && Object.entries(observed).every(([key, count]) => turn.usage[key as keyof typeof observed] === count);
+      const model = state?.terminal?.model;
+      if (!same || typeof model !== "string" || !(model === config.spec.id || new RegExp("^" + config.spec.id + "-\\d{4}-\\d{2}-\\d{2}$").test(model)))
+        throw Error("native model or usage differs from the production adapter");
+      return turn;
+    } catch {
+      failed = true; stopped ??= "error";
+      throw Error("native eval request failed; inspect status and retained usage");
+    } finally {
+      try {
+        const state = current as { row: GatewayRecord; started: number; terminal: NativeResponse | null; httpStatus: number | null } | undefined;
+        if (state) {
+          const usage = nativeUsage(state.terminal), measured = nativeMeasured(state.terminal, price), charge = measured ?? state.row.reservation;
+          ledger.charged += charge - state.row.reservation;
+          if (failed || measured === null || charge > state.row.reservation) { ledger.halted = true; stopped ??= "error"; }
+          await options.record({ ...state.row, kind: "settled", usage, measured, charge, ledgerCharged: ledger.charged,
+            responseModel: typeof state.terminal?.model === "string" ? state.terminal.model : null,
+            failure: failed ? { kind: [402, 429].includes(state.httpStatus ?? 0) ? "balance" : "provider", status: state.httpStatus } : null,
+            wallMs: performance.now() - state.started });
+        }
+      } catch { ledger.halted = true; throw Error("native eval ledger could not be persisted"); }
+      finally { active = false; finish(); }
+    }
+  } };
+  return { provider, get requests() { return requests; }, get stopped() { return stopped; }, async close() { controller.abort(); await idle; } };
+}

package/src/runtime/oauth.ts

@@ -17,7 +17,7 @@ import { createServer, type Server } from "node:http";
 import { pollDeviceCode } from "./oauth-device.ts";
 
 /** Matches package.json. Sent as User-Agent so the server can see who we are (D18). */
-export const XENO_VERSION = "0.2.1";
+export const XENO_VERSION = "0.3.0";
 
 /**
  * Minutes subtracted from server expiry so a request issued at the edge

package/src/runtime/provider-connect.ts

@@ -0,0 +1,109 @@
+/**
+ * The `models.json` edit `/login` makes for a connected provider, as a pure transform.
+ *
+ * The file stays the single source of model configuration and keeps the
+ * documented `providers.<id>` shape (docs/providers.md), so a connected
+ * provider is indistinguishable from a hand-written one and `/reload`,
+ * startup and `--list-models` need no second code path. Secrets never enter
+ * it: keys go to `auth.json` (0600) or stay `$ENV` references.
+ *
+ * - Catalog provider: `allowlist` is the chosen ids, so the picker offers
+ *   exactly what the user enabled; ids the live listing has but the catalog
+ *   lacks are added under `models`.
+ * - Custom endpoint: `api` + `baseUrl` + `models`. Limits/capabilities are
+ *   copied from a catalog model with the same id when the listing lacks
+ *   them (a gateway serving `claude-sonnet-4-5` has that model's limits);
+ *   price never is, because gateway billing is not the vendor's.
+ */
+import type { ModelSpec } from "./model.ts";
+import type { ProviderApi } from "./provider-protocols.ts";
+import type { DiscoveredModel } from "./model-discovery.ts";
+
+export interface ConnectRequest {
+  id: string;
+  name: string;
+  api: ProviderApi;
+  baseUrl: string;
+  /** True when the provider ships in the catalog with its own models. */
+  catalog: boolean;
+  /** Catalog default base URL; an equal value is not written as an override. */
+  catalogBaseUrl?: string;
+  keyless: boolean;
+  /** `$VAR` / `{env:VAR}` reference kept in config instead of a stored key. */
+  keyReference?: string;
+  chosen: readonly DiscoveredModel[];
+}
+
+function record(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/** The bare model name a gateway may prefix: `anthropic/claude-x` → `claude-x`. */
+function bare(id: string): string {
+  return id.slice(id.lastIndexOf("/") + 1).toLowerCase();
+}
+
+export function catalogTwin(id: string, catalog: readonly ModelSpec[]): ModelSpec | undefined {
+  const exact = catalog.find(model => model.id === id);
+  if (exact) return exact;
+  const name = bare(id);
+  return catalog.find(model => bare(model.id) === name);
+}
+
+export function modelEntry(model: DiscoveredModel, catalog: readonly ModelSpec[]): Record<string, unknown> {
+  const twin = catalogTwin(model.id, catalog);
+  const entry: Record<string, unknown> = {};
+  const name = model.name ?? twin?.name;
+  if (name && name !== model.id) entry["name"] = name;
+  const contextWindow = model.contextWindow ?? twin?.contextWindow;
+  const maxTokens = model.maxTokens ?? twin?.maxTokens;
+  if (contextWindow) entry["contextWindow"] = contextWindow;
+  if (maxTokens) entry["maxTokens"] = maxTokens;
+  if (twin?.reasoning) entry["reasoning"] = true;
+  if (twin?.input?.includes("image")) entry["input"] = [...twin.input];
+  return entry;
+}
+
+export function applyConnect(json: unknown, request: ConnectRequest, catalog: readonly ModelSpec[]): Record<string, unknown> {
+  // The legacy flat array form is still a valid file; keep its rows.
+  const root: Record<string, unknown> = Array.isArray(json) ? { models: json } : record(json) ? { ...json } : {};
+  const providers = record(root["providers"]) ? { ...root["providers"] } : {};
+  const previous = record(providers[request.id]) ? providers[request.id] as Record<string, unknown> : {};
+  const known = new Set(catalog.filter(model => model.provider === request.id).map(model => model.id));
+  const entry: Record<string, unknown> = { ...previous };
+  for (const key of ["allowlist", "whitelist", "models", "disabled", "enabled"]) delete entry[key];
+  if (!request.catalog) {
+    entry["name"] = request.name;
+    entry["api"] = request.api;
+    // Unknown Chat Completions gateways: the lowest common denominator. The
+    // `developer` role, `store` and `max_completion_tokens` are OpenAI-only
+    // and are the usual 400s from DeepSeek-, vLLM- and one-api-style servers.
+    if (request.api === "openai-completions" && !record(entry["compat"])) entry["compat"] = { supportsDeveloperRole: false, supportsStore: false, maxTokensField: "max_tokens" };
+  }
+  if (!request.catalog || request.baseUrl !== request.catalogBaseUrl) entry["baseUrl"] = request.baseUrl;
+  else delete entry["baseUrl"];
+  if (request.keyless) entry["auth"] = false;
+  else if (entry["auth"] === false) delete entry["auth"];
+  if (request.keyReference) entry["apiKey"] = request.keyReference;
+  const models: Record<string, unknown> = {};
+  for (const model of request.chosen) {
+    if (request.catalog && known.has(model.id)) continue;
+    models[model.id] = modelEntry(model, catalog);
+  }
+  if (Object.keys(models).length) entry["models"] = models;
+  if (request.catalog) entry["allowlist"] = request.chosen.map(model => model.id);
+  providers[request.id] = entry;
+  root["providers"] = providers;
+  return root;
+}
+
+/** Remove what `/login` wrote for a provider; other providers and flat rows are untouched. */
+export function applyDisconnect(json: unknown, id: string): Record<string, unknown> {
+  const root: Record<string, unknown> = Array.isArray(json) ? { models: json } : record(json) ? { ...json } : {};
+  if (record(root["providers"])) {
+    const providers = { ...root["providers"] };
+    delete providers[id];
+    root["providers"] = providers;
+  }
+  return root;
+}

package/src/runtime/provider-presets.ts

@@ -0,0 +1,87 @@
+/**
+ * What `/login` offers for custom endpoints before the user types anything.
+ *
+ * A preset names a catalog provider (whose API, base URL and model metadata
+ * already ship in model-data) or a custom endpoint family. Order is the
+ * "Popular" section, modelled on OpenCode's PROVIDER_PRIORITY and magpie's
+ * vendor list; everything else in the catalog stays reachable by search.
+ * Key URLs are where a user actually gets a key, shown as a hint.
+ */
+import { SOURCE_PROVIDERS } from "./model-data.ts";
+import type { ProviderApi } from "./provider-protocols.ts";
+
+export interface ProviderPreset {
+  /** Catalog provider id, or the suggested id for a custom endpoint. */
+  id: string;
+  label: string;
+  api: ProviderApi;
+  baseUrl: string;
+  /** Present for catalog providers: their models carry metadata already. */
+  catalog: boolean;
+  /** Custom endpoints ask for id and URL; keyless ones skip the key. */
+  custom: boolean;
+  keyless?: boolean;
+  keyUrl?: string;
+  hint?: string;
+}
+
+const POPULAR: readonly { id: string; keyUrl?: string; hint?: string }[] = [
+  { id: "anthropic", keyUrl: "https://console.anthropic.com/settings/keys" },
+  { id: "openai", keyUrl: "https://platform.openai.com/api-keys" },
+  { id: "google", keyUrl: "https://aistudio.google.com/apikey", hint: "Gemini API" },
+  { id: "deepseek", keyUrl: "https://platform.deepseek.com/api_keys" },
+  { id: "openrouter", keyUrl: "https://openrouter.ai/keys", hint: "one key, many vendors" },
+  { id: "moonshotai-cn", keyUrl: "https://platform.moonshot.cn/console/api-keys", hint: "Kimi" },
+  { id: "kimi-coding", keyUrl: "https://www.kimi.com/coding", hint: "Kimi Coding plan" },
+  { id: "zhipuai", keyUrl: "https://open.bigmodel.cn/usercenter/apikeys", hint: "GLM" },
+  { id: "zhipuai-coding-plan", keyUrl: "https://open.bigmodel.cn/usercenter/apikeys", hint: "GLM Coding plan" },
+  { id: "siliconflow-cn", keyUrl: "https://cloud.siliconflow.cn/account/ak" },
+  { id: "alibaba-cn", keyUrl: "https://bailian.console.aliyun.com/?apiKey=1", hint: "Qwen / DashScope" },
+  { id: "volcengine", keyUrl: "https://console.volcengine.com/ark", hint: "Doubao / Ark" },
+  { id: "minimax-cn", keyUrl: "https://platform.minimaxi.com/user-center/basic-information/interface-key" },
+  { id: "xai", keyUrl: "https://console.x.ai" },
+  { id: "groq", keyUrl: "https://console.groq.com/keys" },
+  { id: "mistral", keyUrl: "https://console.mistral.ai/api-keys" },
+];
+
+/** Custom families: the four wire formats a generic endpoint can speak. */
+export const CUSTOM_PRESETS: readonly ProviderPreset[] = [
+  { id: "custom-openai", label: "OpenAI-compatible endpoint", api: "openai-completions", baseUrl: "https://", catalog: false, custom: true, hint: "Chat Completions · /v1/chat/completions" },
+  { id: "custom-responses", label: "OpenAI Responses endpoint", api: "openai-responses", baseUrl: "https://", catalog: false, custom: true, hint: "Responses API · /v1/responses" },
+  { id: "custom-anthropic", label: "Anthropic-compatible endpoint", api: "anthropic-messages", baseUrl: "https://", catalog: false, custom: true, hint: "Messages API · /v1/messages" },
+  { id: "custom-gemini", label: "Gemini-compatible endpoint", api: "google-generative-ai", baseUrl: "https://generativelanguage.googleapis.com/v1beta", catalog: false, custom: true, hint: "generateContent" },
+  { id: "ollama", label: "Ollama (local)", api: "openai-completions", baseUrl: "http://127.0.0.1:11434/v1", catalog: false, custom: true, keyless: true, hint: "no key needed" },
+  { id: "lmstudio", label: "LM Studio (local)", api: "openai-completions", baseUrl: "http://127.0.0.1:1234/v1", catalog: false, custom: true, keyless: true, hint: "no key needed" },
+];
+
+function fromCatalog(id: string, extra: { keyUrl?: string; hint?: string } = {}): ProviderPreset | undefined {
+  const source = SOURCE_PROVIDERS[id];
+  if (!source?.api || !source.baseUrl) return undefined;
+  return { id, label: source.name, api: source.api, baseUrl: source.baseUrl, catalog: true, custom: false,
+    ...(extra.keyUrl ? { keyUrl: extra.keyUrl } : {}), ...(extra.hint ? { hint: extra.hint } : {}) };
+}
+
+export function popularPresets(): ProviderPreset[] {
+  return POPULAR.flatMap(entry => fromCatalog(entry.id, entry) ?? []);
+}
+
+export function presetById(id: string): ProviderPreset | undefined {
+  return CUSTOM_PRESETS.find(preset => preset.id === id) ?? fromCatalog(id, POPULAR.find(entry => entry.id === id));
+}
+
+/** Provider ids are config keys and auth.json keys: OpenCode's rule. */
+export function validProviderId(id: string): boolean {
+  return /^[a-z0-9][a-z0-9_-]{0,63}$/.test(id);
+}
+
+/** A readable default id from a URL host: api.example.com → example. */
+export function suggestProviderId(baseUrl: string, taken: ReadonlySet<string>): string {
+  let host = "custom";
+  try { host = new URL(baseUrl).hostname; } catch { /* keep default */ }
+  const parts = host.split(".").filter(part => !["api", "www", "openai", "gateway", "com", "cn", "net", "io", "ai", "org", "dev", "co"].includes(part));
+  let base = (parts.at(-1) ?? "custom").toLowerCase().replace(/[^a-z0-9_-]/g, "-").replace(/^-+/, "") || "custom";
+  if (/^\d/.test(base) || base === "127" || host === "localhost") base = "local";
+  let id = base, n = 2;
+  while (taken.has(id)) id = `${base}-${n++}`;
+  return id;
+}

package/src/runtime/query-eval-verifier.ts

@@ -0,0 +1,28 @@
+/** Q.21: emit the isolated Bun verifier; it owns file I/O and process exit. */
+import type { queryEvalContract } from "../core/query-eval-contract.ts";
+
+export function queryEvalVerifier(contract: ReturnType<typeof queryEvalContract>): string {
+  // The standalone fixture carries only shape expectations and a one-way oracle
+  // digest. Diagnostics never expose expected numeric values to the model.
+  return `import { createHash } from "node:crypto";
+const paths = ${JSON.stringify(contract.paths)}, columns = ${JSON.stringify(contract.columns)}, rowCount = ${contract.rowCount};
+const fail = (reason, detail = {}) => { console.error(JSON.stringify({ok:false, reason, ...detail})); process.exit(1); };
+const body = await Bun.file("answer.txt").text().catch(() => fail("answer_missing"));
+let value; try { value = JSON.parse(body); } catch { fail("invalid_json"); }
+if (!Array.isArray(value) || value.length !== paths.length) fail("source_count", {expected:paths.length, actual:Array.isArray(value)?value.length:null});
+for (let i = 0; i < paths.length; i++) {
+  const item = value[i];
+  if (!item || typeof item !== "object" || JSON.stringify(Object.keys(item)) !== '["path","rows"]') fail("item_columns", {index:i, expected:["path","rows"]});
+  if (item.path !== paths[i]) fail("source_order", {index:i, expected:paths[i]});
+  if (!Array.isArray(item.rows) || item.rows.length !== rowCount) fail("row_count", {path:paths[i], expected:rowCount, actual:Array.isArray(item.rows)?item.rows.length:null});
+  for (let row = 0; row < item.rows.length; row++) {
+    const record = item.rows[row];
+    if (!record || typeof record !== "object" || JSON.stringify(Object.keys(record)) !== JSON.stringify(columns)) fail("result_columns", {path:paths[i], row, expected:columns, actual:record&&typeof record==="object"?Object.keys(record):null});
+    if (columns.some(column => column === "team" ? typeof record[column] !== "string" : !Number.isFinite(record[column]))) fail("result_type", {path:paths[i], row});
+  }
+}
+if (body !== JSON.stringify(value) + "\\n") fail("serialization", {expected:"compact JSON with one trailing newline"});
+if (createHash("sha256").update(body).digest("hex") !== ${JSON.stringify(contract.answerSha256)}) fail("value_mismatch", {next:"Recheck the original task, source rows, filter and aggregation. The result shape is correct; at least one value or row order differs."});
+console.log(JSON.stringify({ok:true}));
+`;
+}