@visual-z/xeno 0.1.3 → 0.2.0

package/src/core/transcript.ts

@@ -1,25 +1,35 @@
 /** Human history is a separate pure log projection from the model's bounded context (D1, D8). */
 import type { LogEvent } from "./events.ts";
 import { assertNever } from "./exhaustive.ts";
+import type { ImageRef } from "./images.ts";
 
 type Identity = { id: string; revision: string };
 export type TranscriptItem = Identity & (
-  | { kind: "user"; text: string; interrupted: boolean }
+  | { kind: "user"; text: string; interrupted: boolean; images?: readonly ImageRef[] }
   | { kind: "assistant" | "thinking" | "notice"; text: string }
-  | { kind: "tool"; callId: string; name: string; input: unknown; result: { text: string; ok: boolean } | null }
+  | { kind: "custom"; text: string; customType: string; data?: unknown; entry: boolean; timestamp: string }
+  | { kind: "tool"; callId: string; name: string; input: unknown; result: { text: string; ok: boolean; data?: unknown; images?: readonly ImageRef[] } | null }
 );
 
-export function projectTranscript(events: readonly LogEvent[]): TranscriptItem[] {
+export function projectTranscript(events: readonly LogEvent[], entryTypes: ReadonlySet<string> = new Set()): TranscriptItem[] {
   const items: TranscriptItem[] = [];
   const calls = new Map<string, number>();
   const users = new Map<string, number>();
   for (const event of events) {
     const identity = { id: event.id, revision: event.id };
     switch (event.t) {
+      case "extension":
+        if (event.display || !event.inContext && entryTypes.has(event.customType)) items.push({ ...identity, kind: "custom", text: event.content, customType: event.customType,
+          entry: !event.inContext, timestamp: event.at, ...(event.data === undefined ? {} : { data: event.data }) });
+        break;
       case "user":
         users.set(event.id, items.length);
-        items.push({ ...identity, kind: "user", text: event.text, interrupted: false });
+        items.push({ ...identity, kind: "user", text: event.text, interrupted: false, ...(event.images?.length ? { images: event.images } : {}) });
         break;
+      case "user_bash": items.push({ ...identity, kind: "notice",
+        text: `${event.excludeFromContext ? "!!" : "!"}${event.command}\n${event.content}` }); break;
+      case "outcome": items.push({ ...identity, kind: "notice",
+        text: `${event.outcome.status} · ${event.outcome.reason} · ${event.reason}` }); break;
       case "assistant":
         event.blocks.forEach((block, i) => {
           const id = `${event.id}:${i}`;
@@ -33,7 +43,7 @@ export function projectTranscript(events: readonly LogEvent[]): TranscriptItem[]
         const index = calls.get(event.call_id);
         const call = index === undefined ? undefined : items[index];
         if (call?.kind === "tool" && index !== undefined) {
-          items[index] = { ...call, revision: event.id, result: { text: event.content, ok: event.ok } };
+          items[index] = { ...call, revision: event.id, result: { text: event.content, ok: event.ok, ...(event.data === undefined ? {} : { data: event.data }), ...(event.images?.length ? { images: event.images } : {}) } };
         } else items.push({ ...identity, kind: "notice", text: `Unpaired tool result ${event.call_id}: ${event.content}` });
         break;
       }

package/src/runtime/auth.ts

@@ -13,13 +13,13 @@
  *   still winning. pi states this rule outright in its resolver; it is worth
  *   copying verbatim.
  *
- * The order is pi's: command line, then `auth.json`, then the environment.
- * A fourth position belongs to custom providers declared in `models.json`,
- * which this build does not have yet.
+ * The order is command line, auth.json, models.json, then the environment.
  */
 
 import { assertNever } from "../core/exhaustive.ts";
 import type { ModelSpec } from "./model.ts";
+import { providerAccess } from "./provider-access.ts";
+import { SOURCE_PROVIDERS } from "./model-data.ts";
 import {
   refreshOAuthCredential,
   type OAuthCredential,
@@ -40,12 +40,18 @@ export interface AuthFile {
 }
 
 export function storedIsOAuth(stored: AuthFile, provider: string): boolean {
-  const entry = stored[provider];
+  const entry = storedCredential(stored, provider);
   return entry !== undefined && entry.type === "oauth";
 }
 
+function storedCredential(stored: AuthFile, provider: string): StoredCredential | undefined {
+  // Earlier xeno stored Codex subscriptions under openai. Only OAuth gets this read-compatible alias;
+  // API keys and explicit native records retain their own provider and billing account.
+  return stored[provider] ?? (provider === "openai-codex" && stored["openai"]?.type === "oauth" ? stored["openai"] : undefined);
+}
+
 export type Resolved =
-  | { ok: true; key: string; source: "flag" | "auth.json" | "environment" }
+  | { ok: true; key: string; source: "flag" | "auth.json" | "models.json" | "environment" | "ambient" }
   | { ok: false; reason: string };
 
 /** The two effects resolution needs, injected so the rules stay testable. */
@@ -127,21 +133,78 @@ export function resolveKeyValue(
   }
 }
 
+/** Per-provider variables resolve lazily, so order cannot change their meaning or mutate process.env. */
+export function providerEnvironment(spec: ModelSpec, fx: ResolveEffects): { env: Record<string, string>; effects: ResolveEffects } {
+  const configured = providerAccess(spec).env ?? {};
+  const env: Record<string, string> = {};
+  const resolving = new Set<string>();
+  const lookup = (name: string): string | undefined => {
+    if (Object.hasOwn(env, name)) return env[name];
+    const raw = configured[name];
+    if (raw === undefined) return fx.env(name);
+    if (resolving.has(name)) throw new Error(`${spec.provider} env.${name}: cyclic variable reference`);
+    resolving.add(name);
+    try {
+      const got = resolveKeyValue(raw, { ...fx, env: lookup });
+      if (!got.ok) throw new Error(`${spec.provider} env.${name}: could not resolve configured value`);
+      env[name] = got.key;
+      return got.key;
+    } finally { resolving.delete(name); }
+  };
+  for (const name of Object.keys(configured)) lookup(name);
+  const aliases: Record<string, readonly string[]> = {
+    AZURE_OPENAI_API_KEY: ["AZURE_API_KEY"], AZURE_OPENAI_RESOURCE_NAME: ["AZURE_RESOURCE_NAME"], AZURE_OPENAI_BASE_URL: ["AZURE_BASE_URL"],
+    GOOGLE_CLOUD_PROJECT: ["GOOGLE_VERTEX_PROJECT", "GCLOUD_PROJECT"], GOOGLE_CLOUD_LOCATION: ["GOOGLE_VERTEX_LOCATION"],
+  };
+  for (const [target, sources] of Object.entries(aliases)) {
+    const value = lookup(target) ?? sources.map(lookup).find(Boolean);
+    if (value) env[target] = value;
+  }
+  return { env, effects: { ...fx, env: lookup } };
+}
+
+function configuredEffects(spec: ModelSpec, fx: ResolveEffects): { ok: true; effects: ResolveEffects } | { ok: false; reason: string } {
+  if (providerAccess(spec).invalid) return { ok: false, reason: providerAccess(spec).invalid! };
+  try {
+    const scoped = providerEnvironment(spec, fx).effects;
+    const access = providerAccess(spec);
+    if (["google-generative-ai", "google-vertex"].includes(spec.api) && (access.auth === false || access.authHeader === false || typeof access.authHeader === "string")) {
+      return { ok: false, reason: `${spec.api} owns API-key authentication; use apiKey or an OpenAI-compatible local endpoint` };
+    }
+    if (!spec.baseUrl && !["anthropic-messages", "google-generative-ai", "google-vertex", "bedrock-converse-stream", "azure-openai-responses"].includes(spec.api)) {
+      return { ok: false, reason: `${spec.provider}: configure baseUrl for ${spec.api}` };
+    }
+    if (spec.baseUrl?.includes("$")) {
+      const endpoint = resolveKeyValue(spec.baseUrl, scoped);
+      if (!endpoint.ok) return { ok: false, reason: `${spec.provider} baseUrl: ${endpoint.reason}` };
+    }
+    if (spec.api === "azure-openai-responses" && !spec.baseUrl && !scoped.env("AZURE_OPENAI_BASE_URL") && !scoped.env("AZURE_OPENAI_RESOURCE_NAME")) {
+      return { ok: false, reason: `${spec.provider}: configure baseUrl or AZURE_OPENAI_RESOURCE_NAME` };
+    }
+    return { ok: true, effects: scoped };
+  } catch (err) { return { ok: false, reason: err instanceof Error ? err.message : "could not resolve provider environment" }; }
+}
+
 export function resolveCredential(
   spec: ModelSpec,
   stored: AuthFile,
   flagKey: string | undefined,
   fx: ResolveEffects,
 ): Resolved {
+  const access = providerAccess(spec);
+  const configured = configuredEffects(spec, fx);
+  if (!configured.ok) return configured;
+  fx = configured.effects;
   if (flagKey !== undefined && flagKey.length > 0) {
     const got = resolveKeyValue(flagKey, fx);
     return got.ok ? { ok: true, key: got.key, source: "flag" } : got;
   }
 
-  const entry = stored[spec.provider];
+  const entry = storedCredential(stored, spec.provider);
   if (entry !== undefined) {
     // Deliberately no fallback to the environment on failure. See the header.
     if (entry.type === "oauth") {
+      if (spec.provider === "openai" && spec.api !== "openai-codex-responses") return { ok: false, reason: "ChatGPT OAuth belongs to openai-codex; choose an openai-codex model or configure an OpenAI API key" };
       return { ok: true, key: entry.access, source: "auth.json" };
     }
     if (entry.type === "api_key") {
@@ -153,13 +216,33 @@ export function resolveCredential(
     return assertNever(entry, "stored credential");
   }
 
-  for (const variable of envVarsOf(spec.provider)) {
+  if (access.apiKey !== undefined) {
+    const got = resolveKeyValue(access.apiKey, fx);
+    return got.ok ? { ok: true, key: got.key, source: "models.json" }
+      : { ok: false, reason: `${spec.provider} in models.json: could not resolve apiKey` };
+  }
+  if (access.auth === false || access.authHeader === false) return { ok: true, key: "", source: "models.json" };
+  if (access.auth === "ambient") {
+    if (spec.api !== "bedrock-converse-stream" && spec.api !== "google-vertex") return { ok: false, reason: `${spec.api} does not support ambient credentials` };
+    if (spec.api === "google-vertex" && (!fx.env("GOOGLE_CLOUD_PROJECT") || !fx.env("GOOGLE_CLOUD_LOCATION"))) return { ok: false, reason: `${spec.provider}: ambient Vertex authentication requires GOOGLE_CLOUD_PROJECT and GOOGLE_CLOUD_LOCATION` };
+    return { ok: true, key: "", source: "ambient" };
+  }
+  for (const variable of envVarsOf(spec.provider, spec.credentialEnv)) {
     const value = fx.env(variable);
     if (value !== undefined && value.length > 0) {
       return { ok: true, key: value, source: "environment" };
     }
   }
 
+  if (spec.api === "bedrock-converse-stream" && (fx.env("AWS_PROFILE")
+      || (fx.env("AWS_ACCESS_KEY_ID") && fx.env("AWS_SECRET_ACCESS_KEY"))
+      || fx.env("AWS_CONTAINER_CREDENTIALS_RELATIVE_URI") || fx.env("AWS_CONTAINER_CREDENTIALS_FULL_URI") || fx.env("AWS_WEB_IDENTITY_TOKEN_FILE"))) {
+    return { ok: true, key: "", source: "ambient" };
+  }
+  if (spec.api === "google-vertex" && fx.env("GOOGLE_APPLICATION_CREDENTIALS")
+      && (fx.env("GOOGLE_CLOUD_PROJECT") || fx.env("GOOGLE_VERTEX_PROJECT") || fx.env("GCLOUD_PROJECT"))
+      && (fx.env("GOOGLE_CLOUD_LOCATION") || fx.env("GOOGLE_VERTEX_LOCATION"))) return { ok: true, key: "", source: "ambient" };
+
   return { ok: false, reason: describeMissingCredential(spec.provider) };
 }
 
@@ -180,14 +263,32 @@ export const ENV_VAR: Readonly<Record<string, string | readonly string[]>> = {
   zai: "ZHIPU_API_KEY",
   moonshotai: "MOONSHOT_API_KEY",
   together: "TOGETHER_API_KEY",
+  "amazon-bedrock": "AWS_BEARER_TOKEN_BEDROCK",
+  "azure-openai-responses": ["AZURE_OPENAI_API_KEY", "AZURE_API_KEY"],
+  "google-vertex": "GOOGLE_CLOUD_API_KEY",
+  "kimi-coding": ["KIMI_CODING_API_KEY", "KIMI_API_KEY"],
+  "openai-codex": "OPENAI_CODEX_ACCESS_TOKEN",
+  "ant-ling": "ANT_LING_API_KEY",
+  "qwen-token-plan": "QWEN_TOKEN_PLAN_API_KEY",
+  "qwen-token-plan-cn": "QWEN_TOKEN_PLAN_CN_API_KEY",
+  "qwen-token-plan-individual": "QWEN_TOKEN_PLAN_API_KEY",
+  "vercel-ai-gateway": "AI_GATEWAY_API_KEY",
+  "zai-coding-cn": "ZAI_CODING_CN_API_KEY",
+  "fireworks": "FIREWORKS_API_KEY",
+  "typesafe": "TYPESAFE_API_KEY",
+  "radius": "RADIUS_API_KEY",
+  "opencode-go": "OPENCODE_API_KEY",
 };
 
-export function envVarsOf(provider: string): readonly string[] {
+export function envVarsOf(provider: string, additional: readonly string[] = []): readonly string[] {
   const v = ENV_VAR[provider];
   // A provider name is free text in a user catalog; an environment variable
   // is not. `kimi-coding` must become KIMI_CODING, or no shell can set it.
-  if (v === undefined) return [`${provider.toUpperCase().replace(/[^A-Z0-9]+/g, "_")}_API_KEY`];
-  return typeof v === "string" ? [v] : v;
+  const declared = [...additional, ...(SOURCE_PROVIDERS[provider]?.env ?? [])].filter(name => /(?:API_KEY|TOKEN|_KEY)$/.test(name)
+    && !/(?:SECRET_ACCESS_KEY|ACCESS_KEY_ID|RESOURCE|PROJECT|LOCATION)/.test(name));
+  const known = typeof v === "string" ? [v] : v ?? [];
+  const names = [...new Set([...known, ...declared])];
+  return names.length ? names : [`${provider.toUpperCase().replace(/[^A-Z0-9]+/g, "_")}_API_KEY`];
 }
 
 export function envLabel(provider: string): string {
@@ -227,11 +328,15 @@ export async function ensureFreshCredential(
   fx: ResolveEffects,
   oauth: FreshEffects,
 ): Promise<Resolved> {
+  const configured = configuredEffects(spec, fx);
+  if (!configured.ok) return configured;
   if (flagKey !== undefined && flagKey.length > 0) {
     return resolveCredential(spec, stored, flagKey, fx);
   }
-  const entry = stored[spec.provider];
+  const entry = storedCredential(stored, spec.provider);
   if (entry !== undefined && entry.type === "oauth") {
+    const resolved = resolveCredential(spec, stored, flagKey, fx);
+    if (!resolved.ok) return resolved;
     if (oauth.now() < entry.expires) {
       return { ok: true, key: entry.access, source: "auth.json" };
     }

package/src/runtime/catalog.ts

@@ -15,11 +15,17 @@
  */
 
 import { assertNever } from "../core/exhaustive.ts";
+import { modelKey } from "../core/session-position.ts";
+import { mergeCatalogs } from "../core/catalog-merge.ts";
+import { parseModelConfiguration } from "./model-config.ts";
 import type { Settings } from "../core/settings.ts";
-import { CATALOG, type Api, type CacheKind, type CacheRates, type Compat, type ModelSpec, type Price, type Effort } from "./model.ts";
+import { CATALOG, CURATED_CATALOG, type ModelSpec } from "./model.ts";
 import { AnthropicProvider, type Provider, type ProviderConfig } from "./provider.ts";
 import { OpenAICompletionsProvider } from "./openai.ts";
 import { OpenAIResponsesProvider } from "./openai-responses.ts";
+import { PiProvider } from "./pi-provider.ts";
+import { copyProviderAccess, hasProviderAccess } from "./provider-access.ts";
+import type { ResolveEffects } from "./auth.ts";
 
 export type { Settings };
 
@@ -36,149 +42,39 @@ export type CatalogFetch = (input: RequestInfo | URL, init?: RequestInit) => Pro
  * startup-path test can inject one and assert it was never called — a default
  * `refresh: false` flag would not prove that.
  */
-export function loadCatalog(opts: {
-  userText: string | null;
-  fetch?: CatalogFetch;
-}): LoadedCatalog {
+export function loadCatalog(opts: { userText: string | null; cacheText?: string | null; readWarnings?: readonly string[]; fetch?: CatalogFetch }): LoadedCatalog {
   void opts.fetch;
-  if (opts.userText === null || opts.userText.trim().length === 0) {
-    return { models: [...CATALOG], warnings: [] };
-  }
-  let json: unknown;
-  try {
-    json = JSON.parse(opts.userText);
-  } catch (err) {
-    return {
-      models: [...CATALOG],
-      warnings: [`user catalog is not valid JSON: ${(err as Error).message}`],
-    };
-  }
-  const parsed = parseUserCatalog(json);
-  return { models: overlayCatalog(CATALOG, parsed.models), warnings: parsed.errors };
-}
-
-/** Same id: user wins. User-only ids append, in file order. */
-export function overlayCatalog(
-  builtin: readonly ModelSpec[],
-  user: readonly ModelSpec[],
-): ModelSpec[] {
-  const byId = new Map<string, ModelSpec>();
-  for (const spec of builtin) byId.set(spec.id, spec);
-  const extra: ModelSpec[] = [];
-  for (const spec of user) {
-    if (byId.has(spec.id)) byId.set(spec.id, spec);
-    else extra.push(spec);
-  }
-  return [...byId.values(), ...extra];
-}
-
-export function parseUserCatalog(json: unknown): { models: ModelSpec[]; errors: string[] } {
-  const rows = catalogRows(json);
-  if (rows.ok === false) return { models: [], errors: [rows.error] };
-  const models: ModelSpec[] = [];
-  const errors: string[] = [];
-  for (const [i, row] of rows.rows.entries()) {
-    const parsed = parseUserEntry(row, i);
-    if (parsed.ok) models.push(parsed.spec);
-    else errors.push(parsed.error);
-  }
-  return { models, errors };
-}
-
-function catalogRows(json: unknown): { ok: true; rows: unknown[] } | { ok: false; error: string } {
-  if (Array.isArray(json)) return { ok: true, rows: json };
-  if (typeof json === "object" && json !== null && "models" in json) {
-    const models = (json as { models: unknown }).models;
-    if (Array.isArray(models)) return { ok: true, rows: models };
-    return { ok: false, error: "user catalog .models is not an array" };
-  }
-  return { ok: false, error: "user catalog must be an array or { models: [] }" };
-}
-
-function parseUserEntry(
-  row: unknown,
-  index: number,
-): { ok: true; spec: ModelSpec } | { ok: false; error: string } {
-  const where = `entry ${index + 1}`;
-  if (typeof row !== "object" || row === null || Array.isArray(row)) {
-    return { ok: false, error: `${where} is not an object` };
-  }
-  const raw = row as Record<string, unknown>;
-  const id = typeof raw["id"] === "string" && raw["id"].length > 0 ? raw["id"] : null;
-  const label = id ?? where;
-  if (id === null) return { ok: false, error: `${where} has no id` };
-  if (!isApi(raw["api"])) {
-    return { ok: false, error: `${label} has an unknown or missing api` };
-  }
-  if (typeof raw["provider"] !== "string" || raw["provider"].length === 0) {
-    return { ok: false, error: `${label} has no provider` };
+  const warnings: string[] = [...(opts.readWarnings ?? [])];
+  let models = [...CATALOG];
+  if (opts.cacheText?.trim()) {
+    try {
+      const parsed = parseModelConfiguration(JSON.parse(opts.cacheText));
+      const curated = new Map(CURATED_CATALOG.map(spec => [modelKey(spec), spec]));
+      const cached = parsed.models.map(spec => {
+        const known = curated.get(modelKey(spec));
+        if (!known) return spec;
+        // Refresh metadata without replacing already verified wire dialects for existing sessions.
+        const next = { ...spec, api: known.api, reasoning: known.reasoning };
+        delete next.driver; delete next.compat; delete next.nativeCompat; delete next.thinkingLevelMap;
+        if (known.compat) next.compat = known.compat;
+        if (known.thinkingLevelMap) next.thinkingLevelMap = known.thinkingLevelMap;
+        if (known.baseUrl !== undefined) next.baseUrl = known.baseUrl;
+        copyProviderAccess(spec, next);
+        return next;
+      });
+      models = mergeCatalogs(models, cached);
+      warnings.push(...parsed.errors.map(message => "catalog cache: " + message));
+    } catch { warnings.push("catalog cache is not valid JSON; using bundled models"); }
   }
-  // Refused rather than dropped: without its map, an endpoint that accepts
-  // only some effort levels gets the rest verbatim and answers with a 400.
-  if (raw["thinkingLevelMap"] !== undefined && !isEffortMap(raw["thinkingLevelMap"])) {
-    return { ok: false, error: `${label} has an invalid thinkingLevelMap (keys low|medium|high|xhigh|max, values string or null)` };
+  if (opts.userText?.trim()) {
+    try { const parsed = parseModelConfiguration(JSON.parse(opts.userText), models); models = parsed.models; warnings.push(...parsed.errors); }
+    catch { warnings.push("user catalog is not valid JSON; using bundled/cache models"); }
   }
-  const spec: ModelSpec = {
-    id,
-    name: typeof raw["name"] === "string" && raw["name"].length > 0 ? raw["name"] : id,
-    api: raw["api"],
-    provider: raw["provider"],
-    reasoning: raw["reasoning"] === true,
-    ...(typeof raw["baseUrl"] === "string" ? { baseUrl: raw["baseUrl"] } : {}),
-    ...(isCacheKind(raw["cache"]) ? { cache: raw["cache"] } : {}),
-    ...(isCacheRates(raw["rates"]) ? { rates: raw["rates"] } : {}),
-    ...(isPrice(raw["price"]) ? { price: raw["price"] } : {}),
-    ...(typeof raw["contextWindow"] === "number" ? { contextWindow: raw["contextWindow"] } : {}),
-    ...(typeof raw["maxTokens"] === "number" ? { maxTokens: raw["maxTokens"] } : {}),
-    ...(isCompat(raw["compat"]) ? { compat: raw["compat"] } : {}),
-    ...(isEffortMap(raw["thinkingLevelMap"]) ? { thinkingLevelMap: raw["thinkingLevelMap"] } : {}),
-  };
-  return { ok: true, spec };
+  return { models, warnings };
 }
 
-const EFFORTS: readonly string[] = ["low", "medium", "high", "xhigh", "max"];
-function isEffortMap(v: unknown): v is Partial<Record<Effort, string | null>> {
-  if (typeof v !== "object" || v === null || Array.isArray(v)) return false;
-  return Object.entries(v).every(([key, value]) => EFFORTS.includes(key) && (value === null || typeof value === "string"));
-}
-
-function isApi(v: unknown): v is Api {
-  return v === "anthropic-messages" || v === "openai-completions" || v === "openai-responses";
-}
-
-function isCacheKind(v: unknown): v is CacheKind {
-  return v === "explicit" || v === "automatic";
-}
-
-function isCacheRates(v: unknown): v is CacheRates {
-  if (typeof v !== "object" || v === null) return false;
-  const o = v as Record<string, unknown>;
-  return typeof o["read"] === "number" && typeof o["write"] === "number";
-}
-
-function isPrice(v: unknown): v is Price {
-  if (typeof v !== "object" || v === null) return false;
-  const o = v as Record<string, unknown>;
-  if (typeof o["input"] !== "number" || typeof o["output"] !== "number") return false;
-  // Cache slots may be absent. A present non-number is a bad entry, not
-  // "unknown cache" — that would let `{cacheRead: "free"}` through.
-  if ("cacheRead" in o && typeof o["cacheRead"] !== "number") return false;
-  if ("cacheWrite" in o && typeof o["cacheWrite"] !== "number") return false;
-  return true;
-}
-
-function isCompat(v: unknown): v is Compat {
-  if (typeof v !== "object" || v === null) return false;
-  const o = v as Record<string, unknown>;
-  return (
-    typeof o["supportsDeveloperRole"] === "boolean" &&
-    (o["maxTokensField"] === "max_tokens" || o["maxTokensField"] === "max_completion_tokens") &&
-    typeof o["supportsReasoningEffort"] === "boolean" &&
-    typeof o["supportsUsageInStreaming"] === "boolean" &&
-    typeof o["requiresReasoningContentOnAssistantMessages"] === "boolean" &&
-    (o["thinkingFormat"] === "openai" || o["thinkingFormat"] === "deepseek")
-  );
-}
+export function overlayCatalog(builtin: readonly ModelSpec[], user: readonly ModelSpec[]): ModelSpec[] { return mergeCatalogs(builtin, user); }
+export function parseUserCatalog(json: unknown): { models: ModelSpec[]; errors: string[] } { return parseModelConfiguration(json); }
 
 export function findModel(id: string, catalog: readonly ModelSpec[] = CATALOG): ModelSpec | undefined {
   return catalog.find((m) => m.id === id);
@@ -187,7 +83,7 @@ export function findModel(id: string, catalog: readonly ModelSpec[] = CATALOG):
 /**
  * Resolve a typed pattern to one catalog entry.
  *
- * Order is exact id, then `provider/id`, then substring, then subsequence
+ * Order is `provider/id`, then exact id, then substring, then subsequence
  * ("fuzzy"). Each tier is tried only if the one above it matched nothing,
  * so a unique exact id cannot be displaced by a looser match. Several
  * hits at the winning tier is an error that lists the candidates --
@@ -208,12 +104,12 @@ export function findModelByPattern(
     return { ok: false, reason: "empty model pattern", candidates: [] };
   }
 
-  const exactId = catalog.filter((m) => m.id.toLowerCase() === needle);
-  if (exactId.length > 0) return reportPattern(pattern, exactId);
-
   const byRef = catalog.filter((m) => `${m.provider}/${m.id}`.toLowerCase() === needle);
   if (byRef.length > 0) return reportPattern(pattern, byRef);
 
+  const exactId = catalog.filter((m) => m.id.toLowerCase() === needle);
+  if (exactId.length > 0) return reportPattern(pattern, exactId);
+
   const substring = catalog.filter((m) => haystacks(m).some((h) => h.includes(needle)));
   if (substring.length > 0) return reportPattern(pattern, substring);
 
@@ -245,7 +141,7 @@ function reportPattern(pattern: string, matches: readonly ModelSpec[]): ModelPat
   if (matches.length === 0) {
     return { ok: false, reason: `unknown model: ${pattern}. Try --list-models`, candidates: [] };
   }
-  const ids = matches.map((m) => m.id);
+  const ids = matches.map(modelKey);
   return {
     ok: false,
     reason:
@@ -302,11 +198,9 @@ export function selectModel(
   catalog: readonly ModelSpec[] = CATALOG,
 ): Selection {
   if (flags.model !== undefined && flags.model.length > 0) {
-    const spec = findModel(flags.model, catalog);
-    if (spec === undefined) {
-      return { ok: false, reason: `unknown model: ${flags.model}. Try --list-models` };
-    }
-    return { ok: true, spec };
+    const candidates = flags.provider ? modelsOfProvider(flags.provider, catalog) : catalog;
+    const match = findModelByPattern(flags.model, candidates);
+    return match.ok ? { ok: true, spec: match.spec } : { ok: false, reason: `${match.reason}. Try --list-models` };
   }
 
   if (flags.provider !== undefined && flags.provider.length > 0) {
@@ -318,7 +212,9 @@ export function selectModel(
   }
 
   if (settings.defaultModel !== undefined) {
-    const spec = findModel(settings.defaultModel, catalog);
+    const candidates = settings.defaultProvider ? catalog.filter(model => model.provider === settings.defaultProvider) : catalog;
+    const found = findModelByPattern(settings.defaultModel, candidates);
+    const spec = found.ok ? found.spec : undefined;
     if (spec !== undefined) return { ok: true, spec };
     // Not fatal: a settings file naming a model this build dropped should
     // degrade to the normal search, not refuse to start.
@@ -346,9 +242,13 @@ export function createProvider(
   config: ProviderConfig,
   apiKey: string,
   onRetry?: (attempt: number, delayMs: number, error: unknown) => void,
-  opts?: { oauth?: boolean },
+  opts?: { oauth?: boolean; fetch?: typeof fetch; effects?: ResolveEffects },
 ): Provider {
   const oauth = opts?.oauth === true;
+  if (config.spec.driver === "pi" || hasProviderAccess(config.spec)) return new PiProvider(config, apiKey, {
+    oauth,
+    ...(onRetry ? { onRetry } : {}), ...(opts?.fetch ? { fetch: opts.fetch } : {}), ...(opts?.effects ? { effects: opts.effects } : {}),
+  });
   switch (config.spec.api) {
     case "anthropic-messages":
       return new AnthropicProvider(config, apiKey.length > 0 ? apiKey : undefined, {
@@ -359,6 +259,9 @@ export function createProvider(
       return new OpenAICompletionsProvider(config, apiKey, { ...(onRetry ? { onRetry } : {}) });
     case "openai-responses":
       return new OpenAIResponsesProvider(config, apiKey, { ...(onRetry ? { onRetry } : {}) });
+    case "azure-openai-responses": case "openai-codex-responses": case "google-generative-ai": case "google-vertex":
+    case "bedrock-converse-stream": case "mistral-conversations": case "pi-messages":
+      return new PiProvider(config, apiKey, { ...(onRetry ? { onRetry } : {}), ...(opts?.fetch ? { fetch: opts.fetch } : {}), ...(opts?.effects ? { effects: opts.effects } : {}) });
     default:
       return assertNever(config.spec.api, "createProvider");
   }

package/src/runtime/clipboard.ts

@@ -0,0 +1,114 @@
+/** Pi's files → image → text precedence, with native-helper and OS-command fallbacks (MIT, 02eed88). */
+import { fileURLToPath } from "node:url";
+import { getNativeClipboard, type NativeClipboard } from "../vendor/pi-tui/native-platform.ts";
+import { runClipboardCommand } from "../vendor/pi-rich/clipboard-command.ts";
+
+export type ClipboardContent = { files: string[] } | { image: Uint8Array } | { text: string } | null;
+type Run = (command: string, args: readonly string[], options?: { input?: string; timeoutMs?: number }) => Promise<Buffer | undefined>;
+export interface ClipboardOptions {
+  platform?: NodeJS.Platform;
+  env?: NodeJS.ProcessEnv;
+  native?: NativeClipboard | null;
+  run?: Run;
+}
+
+/** Text is transported as data. Clipboard contents must never become PowerShell or shell source. */
+export async function writeClipboard(text: string, options: ClipboardOptions = {}): Promise<boolean> {
+  const platform = options.platform ?? process.platform, env = options.env ?? process.env;
+  const native = options.native === undefined ? getNativeClipboard() : options.native, run = options.run ?? runClipboardCommand;
+  if (native?.setText) {
+    try { await native.setText(text); return true; } catch { /* Continue to the same platform's command transport. */ }
+  }
+  const windows = platform === "win32" || !!(env["WSL_DISTRO_NAME"] || env["WSL_INTEROP"]);
+  const commands: readonly (readonly [string, readonly string[]])[] = windows
+    ? [["powershell.exe", ["-NoProfile", "-STA", "-Command", "Add-Type -AssemblyName System.Windows.Forms; [Console]::InputEncoding = [System.Text.Encoding]::UTF8; $t = [Console]::In.ReadToEnd(); if ($t.Length) { [System.Windows.Forms.Clipboard]::SetText($t) } else { [System.Windows.Forms.Clipboard]::Clear() }"]]]
+    : platform === "darwin" ? [["pbcopy", []]]
+    : env["TERMUX_VERSION"] ? [["termux-clipboard-set", []]]
+    : platform === "linux" ? [
+        ...(env["WAYLAND_DISPLAY"] || env["XDG_SESSION_TYPE"] === "wayland" ? [["wl-copy", ["--type", "text/plain;charset=utf-8"]] as const] : []),
+        ...(env["DISPLAY"] ? [["xclip", ["-selection", "clipboard"]] as const, ["xsel", ["--clipboard", "--input"]] as const] : []),
+      ] : [];
+  for (const [command, args] of commands) {
+    try { if (await run(command, args, { input: text, timeoutMs: 5000 }) !== undefined) return true; } catch { /* Try a same-platform backend. */ }
+  }
+  return false;
+}
+
+// Fixed programs only. Clipboard content is data, never interpolated into a shell or script.
+const MAC_READ = `ObjC.import('AppKit');
+const p = $.NSPasteboard.generalPasteboard;
+const urls = p.readObjectsForClassesOptions([$.NSURL], $({NSPasteboardURLReadingFileURLsOnlyKey: true}));
+const files = [];
+if (urls) for (let i = 0; i < urls.count; i++) files.push(ObjC.unwrap(urls.objectAtIndex(i).path));
+if (files.length) JSON.stringify({files});
+else {
+  const png = p.dataForType('public.png');
+  const tiff = png ? null : p.dataForType('public.tiff');
+  const data = png || (tiff ? $.NSBitmapImageRep.imageRepWithData(tiff).representationUsingTypeProperties($.NSPNGFileType, $({})) : null);
+  if (data) JSON.stringify({image: ObjC.unwrap(data.base64EncodedStringWithOptions(0))});
+  else JSON.stringify({text: ObjC.unwrap(p.stringForType($.NSPasteboardTypeString)) || ''});
+}`;
+const WINDOWS_READ = `Add-Type -AssemblyName System.Windows.Forms; Add-Type -AssemblyName System.Drawing;
+$c = [System.Windows.Forms.Clipboard];
+if ($c::ContainsFileDropList()) { @{files = @($c::GetFileDropList())} | ConvertTo-Json -Compress }
+elseif ($c::ContainsImage()) { $i = $c::GetImage(); $s = New-Object System.IO.MemoryStream; try { $i.Save($s, [System.Drawing.Imaging.ImageFormat]::Png); @{image = [Convert]::ToBase64String($s.ToArray())} | ConvertTo-Json -Compress } finally { $i.Dispose(); $s.Dispose() } }
+else { @{text = $c::GetText()} | ConvertTo-Json -Compress }`;
+
+function decode(bytes: Buffer | undefined): ClipboardContent | undefined {
+  if (bytes === undefined) return undefined;
+  const value = JSON.parse(bytes.toString("utf8")) as { files?: unknown; image?: unknown; text?: unknown };
+  if (Array.isArray(value.files) && value.files.every(p => typeof p === "string") && value.files.length) return { files: value.files };
+  if (typeof value.image === "string" && value.image) return { image: Buffer.from(value.image, "base64") };
+  return typeof value.text === "string" && value.text ? { text: value.text } : null;
+}
+
+export async function readClipboard(options: ClipboardOptions = {}): Promise<ClipboardContent> {
+  const platform = options.platform ?? process.platform, env = options.env ?? process.env;
+  const run = options.run ?? runClipboardCommand;
+  const native = options.native === undefined ? getNativeClipboard() : options.native;
+  const files = await native?.getFilePaths?.();
+  if (files?.length) return { files };
+  if (platform === "darwin" && !native) {
+    const result = decode(await run("osascript", ["-l", "JavaScript", "-e", MAC_READ]));
+    if (result !== undefined) return result;
+  }
+  const wsl = !!(env["WSL_DISTRO_NAME"] || env["WSL_INTEROP"]);
+  if (platform === "win32" || wsl) {
+    const result = decode(await run("powershell.exe", ["-NoProfile", "-STA", "-Command", WINDOWS_READ], { timeoutMs: 5000 }));
+    if (result !== undefined) return result;
+  }
+  if (platform === "linux" && !env["TERMUX_VERSION"]) {
+    const wayland = !!env["WAYLAND_DISPLAY"] || env["XDG_SESSION_TYPE"] === "wayland";
+    const backends = [...(wayland ? ["wayland"] : []), ...(env["DISPLAY"] ? ["x11"] : [])];
+    for (const backend of backends) {
+      const read = (type: string) => backend === "wayland" ? run("wl-paste", ["--type", type, "--no-newline"]) : run("xclip", ["-selection", "clipboard", "-t", type, "-o"]);
+      const available = backend === "wayland" ? await run("wl-paste", ["--list-types"], { timeoutMs: 1000 }) : await read("TARGETS");
+      if (available === undefined) continue;
+      const types = available.toString("utf8").trim().split(/\r?\n/);
+      if (types.includes("text/uri-list")) {
+        const bytes = await read("text/uri-list");
+        if (bytes === undefined) throw new Error("Clipboard file transfer failed");
+        const paths = bytes.toString("utf8").split(/\r?\n/).filter(p => p.startsWith("file://")).map(p => fileURLToPath(p));
+        if (paths.length) return { files: paths };
+      }
+      const type = ["image/png", "image/jpeg", "image/webp", "image/gif", "image/bmp"].find(t => types.includes(t));
+      if (type) {
+        const bytes = await read(type);
+        if (bytes === undefined) throw new Error("Clipboard image transfer failed");
+        return bytes.length ? { image: bytes } : null;
+      }
+      const textType = ["text/plain;charset=utf-8", "UTF8_STRING", "text/plain", "text"].find(t => types.includes(t));
+      if (!textType) return null; // An empty Wayland selection must not reveal stale X11 contents.
+      const bytes = await read(textType);
+      if (bytes === undefined) throw new Error("Clipboard text transfer failed");
+      return bytes.length ? { text: bytes.toString("utf8") } : null;
+    }
+  }
+  const image = await native?.getImage();
+  if (image?.length) return { image };
+  const text = await native?.getText();
+  if (text !== undefined) return text ? { text } : null;
+  const fallback = env["TERMUX_VERSION"] ? await run("termux-clipboard-get", []) : platform === "darwin" ? await run("pbpaste", []) : undefined;
+  if (fallback === undefined) throw new Error("Clipboard unavailable for this terminal session");
+  return fallback.length ? { text: fallback.toString("utf8") } : null;
+}