privateer-agent 0.1.0

package/src/providers/attestation.ts

@@ -0,0 +1,149 @@
+import { randomBytes } from "node:crypto";
+import type { ProviderConfig } from "../config/schema.ts";
+import { NEARAI_BASE_URL } from "./registry.ts";
+import { authedFetch, serverBaseUrl } from "../auth/privateer.ts";
+
+// ── NEAR AI TEE attestation ──────────────────────────────────────────────────
+// Every NEAR AI Cloud model runs inside a Trusted Execution Environment (Intel TDX
+// confidential VM + NVIDIA confidential-computing GPU). On request, the gateway
+// returns a cryptographic attestation report proving the model is running on
+// genuine TEE hardware, with a signing key that never leaves the enclave bound to
+// a caller-supplied nonce (report_data = signing_address || nonce). That lets us
+// surface a live "this inference is confidential and verifiable" signal.
+//
+// We do a *pragmatic* check suited to a TUI: fetch a fresh report bound to our
+// nonce and confirm it carries a TEE signing key plus hardware evidence. We do NOT
+// re-validate the raw NVIDIA/Intel quote chains here — that's the job of the full
+// verifier (github.com/nearai/cloud-verifier). The /verify command prints the raw
+// report so a user can take it to that verifier.
+
+const TIMEOUT_MS = 12_000;
+
+export type TeePosture = "green" | "yellow" | "red";
+
+export interface Attestation {
+  model: string;
+  nonce: string; // the 32-byte hex nonce we sent (freshness / anti-replay)
+  signingAddress?: string; // TEE-bound key that signs inference responses
+  nonceEchoed: boolean; // our nonce appears in the report → it's fresh, not replayed
+  hardware: string[]; // detected evidence, e.g. ["NVIDIA", "Intel TDX"]
+  raw: unknown; // full report, for /verify display + external verification
+}
+
+function baseFor(cfg: ProviderConfig): string {
+  return (cfg.baseURL ?? NEARAI_BASE_URL).replace(/\/+$/, "");
+}
+
+// A 32-byte (64 hex char) random nonce, per NEAR's attestation API guidance.
+export function randomNonce(): string {
+  return randomBytes(32).toString("hex");
+}
+
+// Recursively find the first string value under any of `keys` (case-insensitive).
+function deepFindString(obj: unknown, keys: string[]): string | undefined {
+  const want = new Set(keys.map((k) => k.toLowerCase()));
+  const stack: unknown[] = [obj];
+  while (stack.length) {
+    const cur = stack.pop();
+    if (Array.isArray(cur)) {
+      stack.push(...cur);
+    } else if (cur && typeof cur === "object") {
+      for (const [k, v] of Object.entries(cur)) {
+        if (typeof v === "string" && want.has(k.toLowerCase()) && v.trim()) return v.trim();
+        if (v && typeof v === "object") stack.push(v);
+      }
+    }
+  }
+  return undefined;
+}
+
+// Fetch and interpret the attestation report for a model. Throws a readable error
+// (mirroring listModels) on missing key / network / HTTP failure so the UI can
+// show a dim "unverified" affordance rather than a colored verdict.
+export async function fetchAttestation(cfg: ProviderConfig, modelId: string): Promise<Attestation> {
+  if (!cfg.apiKey) throw new Error("no API key");
+  const nonce = randomNonce();
+  const url =
+    `${baseFor(cfg)}/attestation/report` +
+    `?model=${encodeURIComponent(modelId)}&signing_algo=ecdsa&nonce=${nonce}`;
+
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), TIMEOUT_MS);
+  let raw: unknown;
+  try {
+    const res = await fetch(url, {
+      headers: { authorization: `Bearer ${cfg.apiKey}` },
+      signal: ac.signal,
+    });
+    if (!res.ok) {
+      const body = await res.text().catch(() => "");
+      const hint = body.slice(0, 200).trim();
+      throw new Error(`HTTP ${res.status} ${res.statusText}${hint ? ` — ${hint}` : ""}`);
+    }
+    raw = await res.json();
+  } catch (err) {
+    if (err instanceof Error && err.name === "AbortError") {
+      throw new Error(`timed out after ${TIMEOUT_MS / 1000}s`);
+    }
+    throw err;
+  } finally {
+    clearTimeout(timer);
+  }
+
+  return interpretReport(modelId, nonce, raw);
+}
+
+// Turn a raw NEAR attestation report into our Attestation posture, independent of
+// how it was fetched (direct nearai gateway, or via the Privateer server proxy).
+function interpretReport(modelId: string, nonce: string, raw: unknown): Attestation {
+  const signingAddress = deepFindString(raw, ["signing_address", "signingAddress", "address"]);
+  // Hardware evidence is detected by scanning the serialized report for the quote
+  // markers each vendor uses — robust to the exact response shape.
+  const blob = JSON.stringify(raw).toLowerCase();
+  const hardware: string[] = [];
+  if (/nvidia|gpu/.test(blob)) hardware.push("NVIDIA");
+  if (/intel|tdx/.test(blob)) hardware.push("Intel TDX");
+  const nonceEchoed = blob.includes(nonce.toLowerCase());
+
+  return { model: modelId, nonce, signingAddress, nonceEchoed, hardware, raw };
+}
+
+// Fetch attestation for an account-billed `privateer:near/...` model through the
+// Privateer server proxy (the NEAR key stays server-side). The server generates
+// the nonce and returns { model, nonce, report, has* booleans }; we interpret the
+// report exactly like the direct path so /verify renders identically. `modelId`
+// is the bare id, still `near/`-prefixed (the server strips it upstream).
+export async function fetchAttestationViaServer(modelId: string): Promise<Attestation> {
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), TIMEOUT_MS);
+  try {
+    const res = await authedFetch(
+      `${serverBaseUrl()}/api/models/near/attestation?model=${encodeURIComponent(modelId)}`,
+      { signal: ac.signal },
+    );
+    if (!res.ok) {
+      const body = await res.text().catch(() => "");
+      const hint = body.slice(0, 200).trim();
+      throw new Error(`HTTP ${res.status} ${res.statusText}${hint ? ` — ${hint}` : ""}`);
+    }
+    const data = (await res.json()) as { nonce?: string; report?: unknown };
+    return interpretReport(modelId, data.nonce ?? "", data.report ?? {});
+  } catch (err) {
+    if (err instanceof Error && err.name === "AbortError") {
+      throw new Error(`timed out after ${TIMEOUT_MS / 1000}s`);
+    }
+    throw err;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// Map an attestation to a status color. GREEN: fresh report bound to our nonce with
+// a TEE signing key and hardware evidence (confidential + verifiable). YELLOW: a
+// report came back but it's missing the signing key, hardware evidence, or nonce
+// echo (attested but not fully confirmable here). RED: no attestation material.
+export function teePosture(att: Attestation): TeePosture {
+  if (!att.signingAddress && att.hardware.length === 0) return "red";
+  if (att.signingAddress && att.hardware.length > 0 && att.nonceEchoed) return "green";
+  return "yellow";
+}

package/src/providers/capabilities.ts

@@ -0,0 +1,104 @@
+import type { Config } from "../config/schema.ts";
+import { KNOWN_PROVIDERS, type ProviderName } from "../config/schema.ts";
+import { PROVIDER_META } from "./catalog.ts";
+import { configuredProviders, parseModelSpec } from "./resolve.ts";
+import type { Modality } from "../util/images.ts";
+
+// Map a provider-reported input modality string (OpenRouter exposes these) onto our
+// taxonomy. "file" is treated as document support since that's what providers use for
+// PDFs; unknown strings are ignored.
+function fromReported(reported: string[]): Set<Modality> {
+  const out = new Set<Modality>();
+  for (const r of reported) {
+    const m = r.toLowerCase();
+    if (m === "image") out.add("image");
+    else if (m === "audio") out.add("audio");
+    else if (m === "video") out.add("video");
+    else if (m === "file" || m === "document" || m === "pdf") out.add("document");
+  }
+  return out;
+}
+
+// Static heuristics per modality, keyed off the model id. Intentionally generous: a
+// false positive surfaces a provider error, a false negative silently drops input.
+function heuristic(modality: Modality, id: string): boolean {
+  switch (modality) {
+    case "image":
+      if (/vision|-vl\b|\bvl-|pixtral|multimodal|maverick|scout/.test(id)) return true;
+      if (/claude-3|claude-(opus|sonnet|haiku)-4|claude-4/.test(id)) return true;
+      if (/gpt-4o|gpt-4\.1|gpt-4\.5|gpt-4-turbo|gpt-5|chatgpt-4o|\bo[134](?:-|$)/.test(id)) return true;
+      if (/gemini/.test(id)) return true;
+      if (/llama-3\.2.*vision|llama-4/.test(id)) return true;
+      if (/grok.*vision|grok-4/.test(id)) return true;
+      return false;
+    case "document": // native PDF input
+      if (/claude-3|claude-(opus|sonnet|haiku)-4|claude-4/.test(id)) return true;
+      if (/gemini/.test(id)) return true;
+      return false;
+    case "audio":
+      if (/gpt-4o-audio|gpt-4o-realtime|gpt-audio|whisper/.test(id)) return true;
+      if (/gemini/.test(id)) return true;
+      return false;
+    case "video":
+      if (/gemini/.test(id)) return true;
+      return false;
+  }
+}
+
+// Whether a model accepts a given input modality. Reported modalities (when the
+// provider supplies them) win over the static heuristic.
+export function modelSupports(
+  modality: Modality,
+  _provider: string,
+  modelId: string,
+  reported?: string[],
+): boolean {
+  if (reported) return fromReported(reported).has(modality);
+  return heuristic(modality, modelId.toLowerCase());
+}
+
+// The full set of input modalities a model accepts.
+export function modalitiesFor(provider: string, modelId: string, reported?: string[]): Set<Modality> {
+  if (reported) return fromReported(reported);
+  const out = new Set<Modality>();
+  for (const m of ["image", "document", "audio", "video"] as Modality[]) {
+    if (heuristic(m, modelId.toLowerCase())) out.add(m);
+  }
+  return out;
+}
+
+// Providers to consider for auto-pick, in preference order: the provider behind the
+// configured default model first, then any other configured providers.
+function providerOrder(config: Config): ProviderName[] {
+  const ready = new Set(configuredProviders(config).filter((p) => p.ready).map((p) => p.name));
+  let primary: ProviderName | undefined;
+  try {
+    const p = parseModelSpec(config.defaultModel).provider;
+    if ((KNOWN_PROVIDERS as readonly string[]).includes(p)) primary = p as ProviderName;
+  } catch {
+    /* malformed defaultModel → no primary */
+  }
+  const rest = KNOWN_PROVIDERS.filter((p) => p !== primary && ready.has(p));
+  return [...(primary && ready.has(primary) ? [primary] : []), ...rest];
+}
+
+// Hybrid auto-pick for a modality route: when no model is configured for `modality`
+// and the default can't handle it, return a known capable "provider:model" from a
+// configured provider, or null if none qualifies. Reuses each provider's catalog
+// default — no network call.
+export function suggestModelFor(modality: Modality, config: Config): string | null {
+  for (const provider of providerOrder(config)) {
+    const spec = PROVIDER_META[provider].defaultModel;
+    const { modelId } = parseModelSpec(spec);
+    if (modelSupports(modality, provider, modelId)) return spec;
+  }
+  return null;
+}
+
+// Back-compat shims for the original vision-only API.
+export function modelSupportsVision(provider: string, modelId: string, reported?: string[]): boolean {
+  return modelSupports("image", provider, modelId, reported);
+}
+export function suggestVisionModel(config: Config): string | null {
+  return suggestModelFor("image", config);
+}

package/src/providers/catalog.ts

@@ -0,0 +1,66 @@
+import { KNOWN_PROVIDERS, type ProviderName } from "../config/schema.ts";
+import { providerRequiresKey } from "./registry.ts";
+
+// Human-facing metadata for each provider, used by the onboarding flow: a display
+// label, where to get an API key, and the model to default to when the provider is
+// chosen first. Keeps the registry (wiring) separate from presentation.
+export interface ProviderMeta {
+  name: ProviderName;
+  label: string;
+  requiresKey: boolean;
+  defaultModel: string; // "provider:model" picked when this provider is selected first
+  keyHint: string; // where to obtain a key, or a note for keyless providers
+  baseURLDefault?: string; // shown as the placeholder for keyless/local providers
+}
+
+export const PROVIDER_META: Record<ProviderName, ProviderMeta> = {
+  anthropic: {
+    name: "anthropic",
+    label: "Anthropic",
+    requiresKey: providerRequiresKey("anthropic"),
+    defaultModel: "anthropic:claude-opus-4-8",
+    keyHint: "console.anthropic.com/settings/keys",
+  },
+  openai: {
+    name: "openai",
+    label: "OpenAI",
+    requiresKey: providerRequiresKey("openai"),
+    defaultModel: "openai:gpt-4o",
+    keyHint: "platform.openai.com/api-keys",
+  },
+  openrouter: {
+    name: "openrouter",
+    label: "OpenRouter",
+    requiresKey: providerRequiresKey("openrouter"),
+    defaultModel: "openrouter:anthropic/claude-opus-4.8",
+    keyHint: "openrouter.ai/keys",
+  },
+  ollama: {
+    name: "ollama",
+    label: "Ollama (local)",
+    requiresKey: providerRequiresKey("ollama"),
+    defaultModel: "ollama:llama3.1",
+    keyHint: "runs locally — no key needed",
+    baseURLDefault: "http://localhost:11434/api",
+  },
+  nearai: {
+    name: "nearai",
+    label: "NEAR AI (private TEE inference)",
+    requiresKey: providerRequiresKey("nearai"),
+    defaultModel: "nearai:zai-org/GLM-5.1-FP8",
+    keyHint: "cloud.near.ai → API Keys",
+  },
+  privateer: {
+    name: "privateer",
+    // Default to a NEAR confidential-compute (TEE) model: it's the strongest
+    // privacy guarantee, runs through the same billed agent endpoint, and was
+    // verified to pass agent tool_calls. Switch to any listed model with /model.
+    label: "Privateer account (billed to your subscription)",
+    requiresKey: providerRequiresKey("privateer"),
+    defaultModel: "privateer:near/deepseek-ai/DeepSeek-V4-Flash",
+    keyHint: "sign in with /login — no API key needed",
+  },
+};
+
+// Provider metadata in display order.
+export const PROVIDER_LIST: ProviderMeta[] = KNOWN_PROVIDERS.map((n) => PROVIDER_META[n]);

package/src/providers/models.ts

@@ -0,0 +1,183 @@
+import type { ProviderConfig, ProviderName } from "../config/schema.ts";
+import { NEARAI_BASE_URL } from "./registry.ts";
+import { authedFetch, serverBaseUrl, DEFAULT_SERVER_URL } from "../auth/privateer.ts";
+
+// A model offered by a provider, as surfaced in the picker. `id` is the bare model
+// id (no "provider:" prefix); `label` is an optional human-friendly name.
+// `inputModalities` (when the provider reports it) lists accepted input kinds —
+// e.g. ["text", "image"] — and lets the router know a model can actually see images.
+export interface ModelInfo {
+  id: string;
+  label?: string;
+  inputModalities?: string[];
+}
+
+const TIMEOUT_MS = 12_000;
+
+// Default API roots per provider. These mirror each SDK's default so the listing
+// endpoint and the actual chat endpoint stay in sync when no baseURL is configured.
+const DEFAULT_BASE: Record<ProviderName, string> = {
+  anthropic: "https://api.anthropic.com",
+  openai: "https://api.openai.com/v1",
+  openrouter: "https://openrouter.ai/api/v1",
+  ollama: "http://localhost:11434/api",
+  nearai: NEARAI_BASE_URL,
+  privateer: DEFAULT_SERVER_URL, // unused by the privateer branch (authed endpoint), kept for type completeness
+};
+
+function baseFor(name: ProviderName, cfg: ProviderConfig): string {
+  return (cfg.baseURL ?? DEFAULT_BASE[name]).replace(/\/+$/, "");
+}
+
+async function getJson(url: string, headers: Record<string, string>): Promise<unknown> {
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), TIMEOUT_MS);
+  try {
+    const res = await fetch(url, { headers, signal: ac.signal });
+    if (!res.ok) {
+      const body = await res.text().catch(() => "");
+      const hint = body.slice(0, 200).trim();
+      throw new Error(`HTTP ${res.status} ${res.statusText}${hint ? ` — ${hint}` : ""}`);
+    }
+    return await res.json();
+  } catch (err) {
+    if (err instanceof Error && err.name === "AbortError") {
+      throw new Error(`timed out after ${TIMEOUT_MS / 1000}s`);
+    }
+    throw err;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// Pull the list of models a provider currently offers, using the credentials the user
+// supplied. Each provider exposes a different listing endpoint and response shape, so
+// this is the second provider-specific seam (alongside the model factory in registry.ts).
+// Throws with a readable message on auth/network failure so the picker can surface it.
+export async function listModels(name: ProviderName, cfg: ProviderConfig): Promise<ModelInfo[]> {
+  const base = baseFor(name, cfg);
+  switch (name) {
+    case "anthropic": {
+      if (!cfg.apiKey) throw new Error("no API key");
+      const json = (await getJson(`${base}/v1/models?limit=1000`, {
+        "x-api-key": cfg.apiKey,
+        "anthropic-version": "2023-06-01",
+      })) as { data?: { id: string; display_name?: string }[] };
+      return (json.data ?? []).map((m) => ({ id: m.id, label: m.display_name }));
+    }
+    case "openai": {
+      if (!cfg.apiKey) throw new Error("no API key");
+      const json = (await getJson(`${base}/models`, {
+        authorization: `Bearer ${cfg.apiKey}`,
+      })) as { data?: { id: string }[] };
+      // Keep chat-capable families; the listing also includes embeddings/tts/whisper.
+      const chat = (json.data ?? []).filter((m) => /^(gpt|o\d|chatgpt)/i.test(m.id));
+      return (chat.length ? chat : (json.data ?? []))
+        .map((m) => ({ id: m.id }))
+        .sort((a, b) => a.id.localeCompare(b.id));
+    }
+    case "openrouter": {
+      // OpenRouter's model list is public; the key is sent when present but optional.
+      const json = (await getJson(
+        `${base}/models`,
+        cfg.apiKey ? { authorization: `Bearer ${cfg.apiKey}` } : {},
+      )) as {
+        data?: { id: string; name?: string; architecture?: { input_modalities?: string[] } }[];
+      };
+      return (json.data ?? [])
+        .map((m) => ({ id: m.id, label: m.name, inputModalities: m.architecture?.input_modalities }))
+        .sort((a, b) => a.id.localeCompare(b.id));
+    }
+    case "ollama": {
+      // Locally installed models, via the Ollama daemon's tags endpoint.
+      const json = (await getJson(`${base}/tags`, {})) as {
+        models?: { name: string }[];
+      };
+      return (json.models ?? []).map((m) => ({ id: m.name }));
+    }
+    case "nearai": {
+      // OpenAI-compatible model list. Every NEAR model runs in a TEE, so there's
+      // no per-model capability to surface here beyond the id itself.
+      if (!cfg.apiKey) throw new Error("no API key");
+      const json = (await getJson(`${base}/models`, {
+        authorization: `Bearer ${cfg.apiKey}`,
+      })) as { data?: { id: string }[] };
+      return (json.data ?? [])
+        .map((m) => ({ id: m.id }))
+        .sort((a, b) => a.id.localeCompare(b.id));
+    }
+    case "privateer": {
+      // The server proxies OpenRouter and bills to the account; list what the
+      // account can use via the authed models endpoint (the JWT is injected by
+      // authedFetch — no API key ever touches the client).
+      const res = await authedFetch(`${serverBaseUrl()}/api/models/openrouter`);
+      if (!res.ok) throw new Error(`HTTP ${res.status} listing account models`);
+      const json = (await res.json()) as {
+        models?: { id: string; name?: string; inputModalities?: string[]; architecture?: { input_modalities?: string[] } }[];
+      };
+      return (json.models ?? [])
+        .map((m) => ({ id: m.id, label: m.name, inputModalities: m.inputModalities ?? m.architecture?.input_modalities }))
+        .sort((a, b) => a.id.localeCompare(b.id));
+    }
+  }
+}
+
+// ── OpenRouter Zero-Data-Retention (ZDR) posture ─────────────────────────────
+// OpenRouter exposes a model's retention story through two authenticated REST
+// endpoints (both need the user's API key). We fold them into a per-account
+// snapshot that the status-bar shield reads against the selected model.
+
+export type ZdrPosture = "green" | "yellow" | "red";
+
+export interface ZdrAccountData {
+  // Models with at least one zero-data-retention endpoint (from /endpoints/zdr).
+  zdrModelIds: Set<string>;
+  // Models usable under the account's privacy settings + guardrails (from /models/user).
+  userModelIds: Set<string>;
+}
+
+// Model ids may carry a variant suffix (":free", ":thinking") that the ZDR/user
+// listings don't use on their permaslug. Strip it and lowercase so the sets,
+// and the lookup against them, compare on the same canonical id.
+function normalizeModelId(id: string): string {
+  const i = id.indexOf(":");
+  return (i === -1 ? id : id.slice(0, i)).trim().toLowerCase();
+}
+
+// Fetch the account's ZDR snapshot. Issues the two authed calls concurrently and
+// reuses getJson's timeout + readable error message. Throws "no API key" (matching
+// listModels) when no key is configured, since both endpoints require auth.
+export async function fetchZdrAccount(cfg: ProviderConfig): Promise<ZdrAccountData> {
+  if (!cfg.apiKey) throw new Error("no API key");
+  const base = baseFor("openrouter", cfg);
+  const headers = { authorization: `Bearer ${cfg.apiKey}` };
+  const [zdr, user] = await Promise.all([
+    getJson(`${base}/endpoints/zdr`, headers) as Promise<{ data?: { model_id?: string }[] }>,
+    getJson(`${base}/models/user`, headers) as Promise<{ data?: { id?: string }[] }>,
+  ]);
+  const zdrModelIds = new Set(
+    (zdr.data ?? []).flatMap((e) => (e.model_id ? [normalizeModelId(e.model_id)] : [])),
+  );
+  const userModelIds = new Set(
+    (user.data ?? []).flatMap((m) => (m.id ? [normalizeModelId(m.id)] : [])),
+  );
+  return { zdrModelIds, userModelIds };
+}
+
+// Decide the shield color for a model against an account snapshot. Pure/synchronous
+// so model switches re-evaluate without a network round-trip. `enforced` is the
+// client's own ZDR-enforcement setting (config.providers.openrouter.enforceZdr):
+// when on, Privateer pins requests to ZDR endpoints, so a ZDR-capable model is
+// guaranteed zero-retention (green) rather than merely able to be (yellow).
+export function zdrPosture(modelId: string, acct: ZdrAccountData, enforced: boolean): ZdrPosture {
+  const id = normalizeModelId(modelId);
+  const inUser = acct.userModelIds.has(id);
+  const inZdr = acct.zdrModelIds.has(id);
+  // RED: blocked by the account's privacy settings (request would 404), or no
+  // zero-retention endpoint exists for the model (data will be retained — and
+  // under enforcement the request would be rejected outright).
+  if (!inUser || !inZdr) return "red";
+  // Usable and a ZDR endpoint exists: GREEN when we force ZDR routing, YELLOW when
+  // ZDR is merely available (a request may still hit a retaining endpoint).
+  return enforced ? "green" : "yellow";
+}

package/src/providers/registry.ts

@@ -0,0 +1,71 @@
+import type { LanguageModel } from "ai";
+import { createAnthropic } from "@ai-sdk/anthropic";
+import { createOpenAI } from "@ai-sdk/openai";
+import { createOpenRouter } from "@openrouter/ai-sdk-provider";
+import { createOllama } from "ollama-ai-provider-v2";
+import type { ProviderConfig, ProviderName } from "../config/schema.ts";
+import { authedFetch, serverBaseUrl } from "../auth/privateer.ts";
+
+// NEAR AI Cloud's OpenAI-compatible gateway. Every model behind it runs inside a
+// Trusted Execution Environment (TEE), so requests are confidential and each one
+// can be cryptographically attested (see ./attestation.ts). It only implements the
+// Chat Completions API, so the factory below pins `.chat()` rather than the SDK's
+// default Responses transport, and supplies this base when the user hasn't set one.
+export const NEARAI_BASE_URL = "https://cloud-api.near.ai/v1";
+
+// Each factory turns provider credentials + a model id into an AI SDK LanguageModel.
+// This is the single seam that makes Privateer provider-agnostic: the agent loop,
+// tools, and UI never know or care which provider is behind the model.
+type Factory = (cfg: ProviderConfig, modelId: string) => LanguageModel;
+
+// Whether a provider requires an API key to be usable (Ollama is local, so it doesn't).
+const REQUIRES_KEY: Record<ProviderName, boolean> = {
+  openrouter: true,
+  anthropic: true,
+  openai: true,
+  ollama: false,
+  nearai: true,
+  // Privateer authenticates via a stored account session, not a typed key, so
+  // there's no key to prompt for. Readiness is "are you logged in?" — see
+  // providers/resolve.ts, which special-cases this against hasCredentials().
+  privateer: false,
+};
+
+const FACTORIES: Record<ProviderName, Factory> = {
+  openrouter: (cfg, modelId) =>
+    // When the user enforces ZDR, pin routing to zero-data-retention endpoints so
+    // prompts can't be retained upstream; OpenRouter rejects models that have none.
+    createOpenRouter({ apiKey: cfg.apiKey, baseURL: cfg.baseURL })(
+      modelId,
+      cfg.enforceZdr ? { provider: { zdr: true } } : {},
+    ),
+  anthropic: (cfg, modelId) =>
+    createAnthropic({ apiKey: cfg.apiKey, baseURL: cfg.baseURL })(modelId),
+  openai: (cfg, modelId) =>
+    createOpenAI({ apiKey: cfg.apiKey, baseURL: cfg.baseURL })(modelId),
+  ollama: (cfg, modelId) =>
+    createOllama({ baseURL: cfg.baseURL })(modelId),
+  nearai: (cfg, modelId) =>
+    // OpenAI-compatible, but Chat-Completions-only — `.chat()` avoids the SDK's
+    // default Responses transport, which NEAR's TEE endpoints don't implement.
+    createOpenAI({ apiKey: cfg.apiKey, baseURL: cfg.baseURL ?? NEARAI_BASE_URL }).chat(modelId),
+  privateer: (cfg, modelId) =>
+    // Routes to the Privateer server's billed, OpenAI-compatible agent endpoint.
+    // `authedFetch` injects the account JWT and refreshes it on 401, so no key is
+    // configured here (apiKey is a placeholder the SDK requires). Chat-Completions
+    // only, hence `.chat()`. The modelId is a normal OpenRouter id, resolved and
+    // billed server-side. Base URL: cfg override → account server → default.
+    createOpenAI({
+      apiKey: "privateer-session",
+      baseURL: `${(cfg.baseURL ?? serverBaseUrl()).replace(/\/$/, "")}/api/agent/v1`,
+      fetch: authedFetch as typeof fetch,
+    }).chat(modelId),
+};
+
+export function providerRequiresKey(name: ProviderName): boolean {
+  return REQUIRES_KEY[name];
+}
+
+export function buildModel(name: ProviderName, cfg: ProviderConfig, modelId: string): LanguageModel {
+  return FACTORIES[name](cfg, modelId);
+}

package/src/providers/resolve.ts

@@ -0,0 +1,78 @@
+import type { LanguageModel } from "ai";
+import type { Config } from "../config/schema.ts";
+import { KNOWN_PROVIDERS, type ProviderName } from "../config/schema.ts";
+import { buildModel, providerRequiresKey } from "./registry.ts";
+import { hasCredentials } from "../auth/privateer.ts";
+
+// Privateer's readiness is session-based, not key-based: ready iff logged in.
+function providerReady(name: ProviderName, cfg: { apiKey?: string }): boolean {
+  if (name === "privateer") return hasCredentials();
+  return providerRequiresKey(name) ? Boolean(cfg.apiKey) : true;
+}
+
+export interface ResolvedModel {
+  spec: string; // original "provider:model" string
+  provider: ProviderName;
+  modelId: string;
+  model: LanguageModel;
+}
+
+function isKnownProvider(name: string): name is ProviderName {
+  return (KNOWN_PROVIDERS as readonly string[]).includes(name);
+}
+
+// Parse a "provider:model" spec. The model id itself may contain ":" or "/"
+// (e.g. "openrouter:anthropic/claude-opus-4.8"), so only the first ":" splits.
+export function parseModelSpec(spec: string): { provider: string; modelId: string } {
+  const idx = spec.indexOf(":");
+  if (idx === -1) {
+    throw new Error(
+      `Invalid model "${spec}". Use "provider:model", e.g. openrouter:anthropic/claude-opus-4.8`,
+    );
+  }
+  return { provider: spec.slice(0, idx).trim(), modelId: spec.slice(idx + 1).trim() };
+}
+
+// A Privateer account model is served over one of two privacy channels: NEAR's
+// confidential-compute TEE (model ids prefixed "near/", cryptographically
+// attestable) or the account's zero-data-retention OpenRouter proxy (every other
+// id, pinned to ZDR endpoints server-side). The picker and the status-bar shield
+// both surface this so the active privacy channel is always visible.
+export type PrivateerChannel = "tee" | "zdr";
+
+export function privateerChannel(modelId: string): PrivateerChannel {
+  return modelId.startsWith("near/") ? "tee" : "zdr";
+}
+
+// Turn a model spec + config into a ready-to-use AI SDK model, validating that the
+// provider is known and configured. Construction does not hit the network.
+export function resolveModel(spec: string, config: Config): ResolvedModel {
+  const { provider, modelId } = parseModelSpec(spec);
+
+  if (!isKnownProvider(provider)) {
+    throw new Error(
+      `Unknown provider "${provider}". Known: ${KNOWN_PROVIDERS.join(", ")}.`,
+    );
+  }
+  if (!modelId) throw new Error(`Missing model id in "${spec}".`);
+
+  const cfg = config.providers[provider] ?? {};
+  if (provider === "privateer" && !hasCredentials()) {
+    throw new Error(`Not signed in to your Privateer account. Run /login first.`);
+  }
+  if (provider !== "privateer" && providerRequiresKey(provider) && !cfg.apiKey) {
+    throw new Error(
+      `No API key for "${provider}". Set ${provider.toUpperCase()}_API_KEY or add it to ~/.privateer/config.json.`,
+    );
+  }
+
+  return { spec, provider, modelId, model: buildModel(provider, cfg, modelId) };
+}
+
+// Which providers currently have working credentials — used by /doctor and provider listing.
+export function configuredProviders(config: Config): { name: ProviderName; ready: boolean }[] {
+  return KNOWN_PROVIDERS.map((name) => {
+    const cfg = config.providers[name] ?? {};
+    return { name, ready: providerReady(name, cfg) };
+  });
+}