@visual-z/xeno 0.2.1 → 0.4.0

package/src/runtime/pi-provider.ts

@@ -12,15 +12,17 @@ import { bedrockConverseStreamApi } from "@earendil-works/pi-ai/api/bedrock-conv
 import { mistralConversationsApi } from "@earendil-works/pi-ai/api/mistral-conversations.lazy";
 import { piMessagesApi } from "@earendil-works/pi-ai/api/pi-messages.lazy";
 import { assertNever } from "../core/exhaustive.ts";
+import { completedToolInput } from "../core/tool-input.ts";
 import type { AssistantBlock } from "../core/events.ts";
-import type { FrozenPrefix, Message } from "../core/project.ts";
+import { toolCallIdentityViolations, type FrozenPrefix, type Message } from "../core/project.ts";
 import type { Api, ModelSpec } from "./model.ts";
 import { providerRequest } from "./provider-request.ts";
 import type { ResolveEffects } from "./auth.ts";
 import { imageData } from "./images.ts";
-import type { OnDelta, Provider, ProviderConfig, ToolSchema, Turn } from "./provider.ts";
+import { FailedResponseError, type OnDelta, type Provider, type ProviderConfig, type ToolSchema, type Turn } from "./provider.ts";
 import { DEFAULT_RETRY, withRetry, type RetryPolicy } from "./retry.ts";
 import { HttpError, StreamError } from "./openai.ts";
+import type { UsageSample } from "./usage.ts";
 
 const APIS: Record<Api, ProviderStreams> = {
   "anthropic-messages": anthropicMessagesApi(), "openai-completions": openAICompletionsApi(),
@@ -32,6 +34,141 @@ const APIS: Record<Api, ProviderStreams> = {
 function record(value: unknown): value is Record<string, unknown> { return value !== null && typeof value === "object" && !Array.isArray(value); }
 const EMPTY_USAGE: AssistantMessage["usage"] = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } };
 
+/** D11: SDK defaults cannot certify a receipt; native input/output counters can, including measured zeros. */
+function nativeUsageReported(api: Api, event: unknown): boolean {
+  if (!record(event)) return false;
+  let usage: unknown;
+  if (api.includes("responses")) {
+    if (event["type"] !== "response.completed" && event["type"] !== "response.incomplete") return false;
+    usage = record(event["response"]) ? event["response"]["usage"] : undefined;
+  } else if (api === "anthropic-messages") {
+    if (event["type"] === "message_start") usage = record(event["message"]) ? event["message"]["usage"] : undefined;
+    else if (event["type"] === "message_delta") usage = event["usage"];
+    else return false;
+  } else if (api === "openai-completions" || api === "mistral-conversations") usage = event["usage"];
+  else return false;
+  if (!record(usage)) return false;
+  const fields = api === "openai-completions" || api === "mistral-conversations" ? ["prompt_tokens", "completion_tokens"] : ["input_tokens", "output_tokens"];
+  return fields.some(field => typeof usage[field] === "number" && Number.isSafeInteger(usage[field]) && usage[field] >= 0);
+}
+
+/** O.3: Pi's streaming repair is presentation, never evidence that final arguments were valid JSON. */
+class OriginalToolArguments {
+  readonly values = new Map<string, string>();
+  private readonly slots = new Map<string, { id: unknown; argumentId: string | null; raw: string; position: number }>();
+  private readonly faults = new Set<string>();
+  private readonly api: Api;
+  constructor(api: Api) { this.api = api; }
+
+  private slotKey(index: unknown, id?: unknown): string | null {
+    if (typeof index === "number" && Number.isSafeInteger(index) && index >= 0) return `index:${index}`;
+    // Mistral accepts a complete call keyed by ID without an index. A fragment
+    // with neither cannot be assigned to a call without inventing its identity.
+    if (this.api === "mistral-conversations" && typeof id === "string" && id.trim() && id !== "null") return `id:${id}`;
+    this.faults.add("native tool call has no stable stream slot");
+    return null;
+  }
+
+  private slot(key: string, id: unknown, argumentId: string | null, supplied: boolean) {
+    const existing = this.slots.get(key);
+    if (existing) {
+      if (supplied && id !== existing.id) this.faults.add(`native call ID changed in stream slot ${existing.position}`);
+      if (argumentId !== null && argumentId !== existing.argumentId) this.faults.add(`native argument identity changed in stream slot ${existing.position}`);
+      return existing;
+    }
+    const slot = { id, argumentId, raw: "", position: this.slots.size };
+    this.slots.set(key, slot);
+    return slot;
+  }
+
+  private publish(slot: { argumentId: string | null; raw: string }): void {
+    if (slot.argumentId !== null) this.values.set(slot.argumentId, slot.raw);
+  }
+
+  observe(value: unknown): void {
+    if (!record(value)) return;
+    if (this.api.includes("responses")) {
+      const item = value["item"];
+      if (record(item) && (item["type"] === "function_call" || item["type"] === "custom_tool_call")) {
+        const key = this.slotKey(value["output_index"]);
+        if (key === null) return;
+        const id = item["call_id"], argumentId = typeof id === "string" ? `${id}|${String(item["id"])}` : null;
+        const slot = this.slot(key, id, argumentId, true);
+        if (item["type"] === "function_call") {
+          if (typeof item["arguments"] === "string") slot.raw = item["arguments"];
+          this.publish(slot);
+        }
+      }
+      const slot = typeof value["output_index"] === "number" ? this.slots.get(`index:${value["output_index"]}`) : undefined;
+      if (slot && value["type"] === "response.function_call_arguments.delta" && typeof value["delta"] === "string") slot.raw += value["delta"];
+      if (slot && value["type"] === "response.function_call_arguments.done" && typeof value["arguments"] === "string") slot.raw = value["arguments"];
+      if (slot && ["response.function_call_arguments.delta", "response.function_call_arguments.done"].includes(String(value["type"]))) this.publish(slot);
+      return;
+    }
+    if (this.api === "anthropic-messages") {
+      const block = value["content_block"];
+      const index = value["index"];
+      if (record(block) && block["type"] === "tool_use") {
+        const key = this.slotKey(index);
+        if (key === null) return;
+        const id = block["id"], slot = this.slot(key, id, typeof id === "string" ? id : null, true);
+        if (slot.argumentId !== null) this.values.set(slot.argumentId, JSON.stringify(block["input"] ?? {}));
+      }
+      const slot = typeof index === "number" ? this.slots.get(`index:${index}`) : undefined, delta = value["delta"];
+      if (slot && record(delta) && delta["type"] === "input_json_delta" && typeof delta["partial_json"] === "string") {
+        slot.raw += delta["partial_json"];
+        this.publish(slot);
+      }
+      return;
+    }
+    // Mistral's native adapter uses the same completions stream vocabulary.
+    if (this.api !== "openai-completions" && this.api !== "mistral-conversations") return;
+    const choice = Array.isArray(value["choices"]) ? value["choices"][0] : undefined;
+    const delta = record(choice) && record(choice["delta"]) ? choice["delta"] : undefined;
+    if (!delta || !Array.isArray(delta["tool_calls"])) return;
+    // One native delta contains one entry per slot. Continuations may reuse a
+    // slot in later chunks, but merging two entries here could execute neither
+    // original declaration's arguments under a silently collapsed identity.
+    const chunkSlots = new Set<string>();
+    for (const call of delta["tool_calls"]) {
+      if (!record(call)) continue;
+      const id = call["id"], key = this.slotKey(call["index"], id);
+      if (key === null) continue;
+      if (chunkSlots.has(key)) { this.faults.add("native stream chunk repeats a tool call slot"); continue; }
+      chunkSlots.add(key);
+      // Native continuation chunks may spell omitted IDs as null. An indexed
+      // slot retains its original identity; a first slot still needs a real ID.
+      const supplied = id !== null && id !== undefined;
+      const slot = this.slot(key, id, typeof id === "string" ? id : null, supplied);
+      if (!record(call["function"])) continue;
+      const fragment = call["function"]["arguments"];
+      if (typeof fragment === "string") slot.raw += fragment;
+      else if (this.api === "mistral-conversations" && fragment !== undefined) slot.raw += JSON.stringify(fragment);
+      this.publish(slot);
+    }
+  }
+
+  identityErrors(): string[] {
+    // D5: SDK block IDs may merge Completions calls or replace missing Mistral
+    // IDs. Only the protocol's original slots can prove one receipt per call.
+    const native = [...this.slots.values()].map(slot => slot.id);
+    const malformed = native.flatMap((id, index) => typeof id === "string" && !(this.api === "mistral-conversations" && id === "null")
+      ? [] : [`native call ID at slot ${index} must be a real string identity`]);
+    const calls: AssistantBlock[] = native.filter((id): id is string => typeof id === "string")
+      .map(call_id => ({ type: "tool_use", call_id, name: "", input: null }));
+    return [...this.faults, ...malformed, ...toolCallIdentityViolations(calls).map(violation => violation.detail)];
+  }
+}
+
+/** Complete usage survives a rejected response without making malformed calls durable conversation history. */
+export class ProviderIntegrityError extends FailedResponseError {
+  readonly code = "invalid_tool_call_identity";
+  constructor(details: readonly string[], usage?: UsageSample) {
+    super(`Invalid provider tool call identity: ${details.join("; ")}`, usage);
+    this.name = "ProviderIntegrityError";
+  }
+}
+
 /** Native envelopes keep their SDK-owned tools/system/signal when adding nested generation options. */
 function mergePayload(payload: Record<string, unknown>, patch: Record<string, unknown>): Record<string, unknown> {
   const next = { ...payload };
@@ -109,13 +246,20 @@ export function piContext(frozen: FrozenPrefix, messages: readonly Message[], sp
         timestamp: 0, usage: structuredClone(EMPTY_USAGE), stopReason: content.some(block => block.type === "toolCall") ? "toolUse" : "stop" });
     } else {
       let content: Extract<PiMessage, { role: "user" }>["content"] = [];
+      let result: Extract<PiMessage, { role: "toolResult" }> | undefined;
       const flush = () => { if (content.length) out.push({ role: "user", content, timestamp: 0 }); content = []; };
       for (const block of message.content) {
         if (block.type === "tool_result") {
-          flush(); out.push({ role: "toolResult", toolCallId: ids.get(block.tool_use_id) ?? block.tool_use_id, toolName: names.get(block.tool_use_id) ?? "tool",
-            content: [{ type: "text", text: block.content }], isError: block.is_error ?? false, timestamp: 0 });
-        } else if (block.type === "text") content.push({ type: "text", text: block.text });
-        else if (block.type === "image") content.push({ type: "image", data: imageData(block), mimeType: block.image.mimeType });
+          flush(); result = { role: "toolResult", toolCallId: ids.get(block.tool_use_id) ?? block.tool_use_id, toolName: names.get(block.tool_use_id) ?? "tool",
+            content: [{ type: "text", text: block.content }], isError: block.is_error ?? false, timestamp: 0 };
+          out.push(result);
+        } else if (block.type === "text") { content.push({ type: "text", text: block.text }); result = undefined; }
+        else if (block.type === "image") {
+          // D5: the projection puts each image after its paired text receipt. Keep that ownership;
+          // Pi emits complete result batches before fallback user images when a protocol requires it.
+          const image = { type: "image" as const, data: imageData(block), mimeType: block.image.mimeType };
+          if (result) result.content.push(image); else content.push(image);
+        }
       }
       flush();
     }
@@ -126,7 +270,7 @@ export function piContext(frozen: FrozenPrefix, messages: readonly Message[], sp
   }) };
 }
 
-export function piBlocks(message: AssistantMessage): AssistantBlock[] {
+export function piBlocks(message: AssistantMessage, originalArguments: ReadonlyMap<string, string> = new Map()): AssistantBlock[] {
   return message.content.map((block): AssistantBlock => {
     switch (block.type) {
       case "text": return { type: "text", text: block.text, ...(block.textSignature ? { wire: { textSignature: block.textSignature } } : {}) };
@@ -142,7 +286,8 @@ export function piBlocks(message: AssistantMessage): AssistantBlock[] {
         }
         return { type: "thinking", text: block.thinking, raw };
       }
-      case "toolCall": return { type: "tool_use", call_id: block.id, name: block.name, input: structuredClone(block.arguments),
+      case "toolCall": return { type: "tool_use", call_id: block.id, name: block.name,
+        input: originalArguments.has(block.id) ? completedToolInput(originalArguments.get(block.id)!) : structuredClone(block.arguments),
         ...(block.thoughtSignature || block.namespace ? { wire: { pi: { thoughtSignature: block.thoughtSignature, namespace: block.namespace } } } : {}) };
       default: return assertNever(block, "pi response block");
     }
@@ -153,7 +298,8 @@ export class PiProvider implements Provider {
   readonly config: ProviderConfig;
   private readonly apiKey: string;
   private readonly options: {
-    fetch?: typeof fetch; effects?: ResolveEffects; oauth?: boolean; retry?: RetryPolicy; onRetry?: (attempt: number, delayMs: number, error: unknown) => void;
+    fetch?: typeof fetch; effects?: ResolveEffects; oauth?: boolean; sessionId?: string;
+    retry?: RetryPolicy; onRetry?: (attempt: number, delayMs: number, error: unknown) => void;
   };
   constructor(config: ProviderConfig, apiKey: string, options: PiProvider["options"] = {}) {
     this.config = config; this.apiKey = apiKey; this.options = options;
@@ -179,10 +325,18 @@ export class PiProvider implements Provider {
       return response;
     }) as typeof fetch;
     const nativeHttp = ["google-generative-ai", "google-vertex", "bedrock-converse-stream"].includes(model.api);
+    const originalArguments = new OriginalToolArguments(model.api);
+    let hasKnownUsage = false;
     const options: SimpleStreamOptions = { ...request.options, ...(request.key ? { apiKey: request.key } : {}),
+      // Cache routing follows a root session and its forks without introducing server transcript state (D8).
+      ...(this.options.sessionId === undefined ? {} : { sessionId: this.options.sessionId }),
       env: request.env, headers: request.headers, ...(nativeHttp ? {} : { fetch: observedFetch }), maxRetries: 0, transport: "sse",
       maxTokens: this.config.maxTokens, ...(this.config.effort !== "off" ? { reasoning: this.config.effort } : {}),
       ...(signal ? { signal } : {}), onResponse: response => { status = response.status; responseHeaders = new Headers(response.headers); },
+      onProviderStreamEvent: event => {
+        originalArguments.observe(event);
+        hasKnownUsage ||= nativeUsageReported(model.api, event);
+      },
       onPayload: payload => {
         if (!record(payload)) return payload;
         const next = mergePayload(payload, request.body);
@@ -226,10 +380,13 @@ export class PiProvider implements Provider {
     }
     signal?.throwIfAborted();
     if (!completed || completed.stopReason === "deferred") throw new StreamError("Provider did not complete a synchronous agent turn");
+    const usage: UsageSample = { input_tokens: completed.usage.input, output_tokens: completed.usage.output,
+      cache_read_input_tokens: completed.usage.cacheRead, cache_creation_input_tokens: completed.usage.cacheWrite, node, ms: Date.now() - started };
+    const identityErrors = originalArguments.identityErrors();
+    if (identityErrors.length) throw new ProviderIntegrityError(identityErrors, hasKnownUsage ? usage : undefined);
     // The SDK has already classified native STOP/end_turn/toolUse/length values. The loop consumes
     // xeno's closed completion vocabulary, never a raw native spelling that could skip tool execution.
-    return { blocks: piBlocks(completed), stopReason: completed.stopReason === "length" ? "max_tokens" : completed.stopReason === "toolUse" ? "tool_use" : "end_turn",
-      usage: { input_tokens: completed.usage.input, output_tokens: completed.usage.output, cache_read_input_tokens: completed.usage.cacheRead,
-        cache_creation_input_tokens: completed.usage.cacheWrite, node, ms: Date.now() - started } };
+    return { blocks: piBlocks(completed, originalArguments.values), stopReason: completed.stopReason === "length" ? "max_tokens" : completed.stopReason === "toolUse" ? "tool_use" : "end_turn",
+      usage };
   }
 }

package/src/runtime/program-status.ts

@@ -0,0 +1,38 @@
+import { encodeProgramStatus, PROGRAM_STATUS_QUERY, programStatusReply, type ProgramStatus } from "../core/program-status.ts";
+
+/** Terminal transport only. Capability detection has no relationship to agent evidence. */
+export class ProgramStatusReporter {
+  private readonly write: (text: string) => void;
+  private readonly id: string;
+  private readonly mode: "auto" | "on" | "off";
+  private supported = false;
+  private started = false;
+  private closed = false;
+  private last: ProgramStatus = { state: "idle" };
+  private emitted = "";
+  constructor(options: { write: (text: string) => void; id: string; tty: boolean; mode?: string; multiplexed?: boolean }) {
+    this.write = options.write; this.id = options.id;
+    this.mode = !options.tty || options.mode === "0" ? "off" : options.mode === "1" ? "on" : options.multiplexed ? "off" : "auto";
+  }
+  start(): void {
+    if (this.started || this.closed) return; this.started = true;
+    if (this.mode === "auto") this.write(PROGRAM_STATUS_QUERY);
+    if (this.mode === "on") { this.supported = true; this.flush(); }
+  }
+  receive(sequence: string): void {
+    if (this.closed || !this.started || this.mode !== "auto" || !programStatusReply(sequence)) return;
+    this.supported = true; this.flush();
+  }
+  update(status: ProgramStatus): void { this.last = { ...status }; if (this.started) this.flush(); }
+  private flush(): void {
+    if (this.closed || !this.supported) return;
+    const sequence = encodeProgramStatus(this.last, this.id);
+    if (sequence !== this.emitted) { this.emitted = sequence; this.write(sequence); }
+  }
+  close(): void {
+    if (this.closed) return;
+    // done/error are durable terminal records. Clear only our own transient record.
+    if (this.supported && this.last.state !== "done" && this.last.state !== "error") this.write(encodeProgramStatus({ state: "clear" }, this.id));
+    this.closed = true;
+  }
+}

package/src/runtime/provider-connect.ts

@@ -0,0 +1,109 @@
+/**
+ * The `models.json` edit `/provider` 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 `/provider` 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 `/provider` 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/provider-request.ts

@@ -1,7 +1,7 @@
 import { providerEnvironment, resolveKeyValue, type ResolveEffects } from "./auth.ts";
 import { providerAccess } from "./provider-access.ts";
 import type { ModelSpec } from "./model.ts";
-import { XENO_VERSION } from "./oauth.ts";
+import { XENO_VERSION, GROK_PROVIDER, GROK_BASE_URL } from "./oauth.ts";
 
 const SDK_IDENTITY_HEADERS = ["x-app", "editor-version", "editor-plugin-version", "copilot-integration-id", "http-referer", "x-title"];
 
@@ -40,6 +40,12 @@ export function providerRequest(spec: ModelSpec, key: string, effects: ResolveEf
   if (baseUrl && !/^https?:\/\//.test(baseUrl)) throw new Error(`${spec.provider} baseUrl must use http or https`);
   const headers: Record<string, string | null> = { ...spec.defaultHeaders };
   for (const [name, value] of Object.entries(access.headers ?? {})) headers[name] = value === null ? null : resolve(value, `headers.${name}`);
+  if (spec.provider === GROK_PROVIDER) {
+    if (baseUrl.replace(/\/$/, "") !== GROK_BASE_URL) throw new Error("Grok account tokens require the official inference proxy");
+    // These select the auth protocol and backend; the User-Agent still identifies xeno (D18).
+    headers["X-XAI-Token-Auth"] = "xai-grok-cli";
+    headers["x-grok-model-override"] = spec.wireId ?? spec.id;
+  }
   const anthropicOAuth = spec.api === "anthropic-messages" && spec.provider !== "github-copilot" && (oauth || key.includes("sk-ant-oat"));
   const noAutomaticAuth = access.auth === false || access.authHeader === false || typeof access.authHeader === "string" || anthropicOAuth;
   if (noAutomaticAuth && (spec.api === "google-generative-ai" || spec.api === "google-vertex")) {
@@ -63,11 +69,16 @@ export function providerRequest(spec: ModelSpec, key: string, effects: ResolveEf
   const privateKey = noAutomaticAuth ? "xeno-keyless-local" : key || undefined;
   const transport = (async (input: RequestInfo | URL, init?: RequestInit) => {
     const request = new Request(input, init);
+    const grokAccount = spec.provider === GROK_PROVIDER;
+    // Check the SDK's final target too, and never forward an account token through a redirect.
+    if (grokAccount && new URL(request.url).origin !== new URL(GROK_BASE_URL).origin) {
+      throw new Error("Grok account tokens require the official inference proxy");
+    }
     const nextHeaders = new Headers(request.headers);
     if (noAutomaticAuth) for (const name of ["authorization", "x-api-key", "api-key", "x-goog-api-key"]) nextHeaders.delete(name);
     for (const [name, value] of Object.entries(headers)) { if (value === null) nextHeaders.delete(name); else nextHeaders.set(name, value); }
     clientIdentity(nextHeaders);
-    return fetchImpl(new Request(request, { headers: nextHeaders }));
+    return fetchImpl(new Request(request, { headers: nextHeaders, ...(grokAccount ? { redirect: "error" } : {}) }));
   }) as typeof fetch;
   return { baseUrl, env, headers, fetch: transport, options: access.options ?? {}, body: access.body ?? {}, ...(privateKey ? { key: privateKey } : {}) };
 }

package/src/runtime/provider.ts

@@ -144,13 +144,24 @@ export interface Turn {
   usage: UsageSample;
 }
 
+/** D11: a rejected response can still prove usage; arbitrary errors cannot prove a billable receipt. */
+export class FailedResponseError extends Error {
+  readonly usage: UsageSample | undefined;
+
+  constructor(message: string, usage?: UsageSample) {
+    super(message);
+    this.name = "FailedResponseError";
+    this.usage = usage === undefined ? undefined : { ...usage };
+  }
+}
+
 /** Thrown for a refusal, which arrives as HTTP 200 rather than an error. */
-export class RefusalError extends Error {
+export class RefusalError extends FailedResponseError {
   readonly category: string | null;
   readonly explanation: string | null;
 
-  constructor(category: string | null, explanation: string | null) {
-    super(`model refused the request${category ? ` (${category})` : ""}`);
+  constructor(category: string | null, explanation: string | null, usage?: UsageSample) {
+    super(`model refused the request${category ? ` (${category})` : ""}`, usage);
     this.name = "RefusalError";
     this.category = category;
     this.explanation = explanation;
@@ -283,6 +294,7 @@ export class AnthropicProvider implements Provider {
           blocks: response.content.map(fromWireBlock),
           stopReason: response.stop_reason,
           stopDetails: response.stop_details ?? null,
+          usageKnown: true,
           usage: {
             input_tokens: response.usage.input_tokens,
             output_tokens: response.usage.output_tokens,
@@ -290,23 +302,20 @@ export class AnthropicProvider implements Provider {
             cache_read_input_tokens: response.usage.cache_read_input_tokens ?? 0,
           },
         };
+    const usage = { ...assembled.usage, node, ms: Date.now() - started };
 
     // A refusal is HTTP 200 with stop_reason "refusal", so content must not be
     // trusted after it. Anything already painted has to go with it.
     if (assembled.stopReason === "refusal") {
       onDelta?.({ kind: "discard" });
       const details = assembled.stopDetails;
-      throw new RefusalError(details?.category ?? null, details?.explanation ?? null);
+      throw new RefusalError(details?.category ?? null, details?.explanation ?? null, assembled.usageKnown ? usage : undefined);
     }
 
     return {
       blocks: assembled.blocks,
       stopReason: assembled.stopReason,
-      usage: {
-        ...assembled.usage,
-        node,
-        ms: Date.now() - started,
-      },
+      usage,
     };
   }
 }
@@ -326,6 +335,8 @@ interface AssembledTurn {
   blocks: AssistantBlock[];
   stopReason: string | null;
   stopDetails: { category?: string | null; explanation?: string | null } | null;
+  /** Provider receipt presence distinguishes a measured zero from absent usage (D11). */
+  usageKnown: boolean;
   usage: {
     input_tokens: number;
     output_tokens: number;
@@ -382,6 +393,7 @@ async function consumeAnthropicStream(
     blocks: [],
     stopReason: null,
     stopDetails: null,
+    usageKnown: false,
     usage: {
       input_tokens: 0,
       output_tokens: 0,
@@ -411,6 +423,7 @@ async function consumeAnthropicStream(
     switch (event.type) {
       case "message_start":
         takeUsage(assembled.usage, event.message?.usage);
+        if (event.message?.usage !== undefined) assembled.usageKnown = true;
         break;
       case "content_block_start": {
         const index = event.index ?? content.length;
@@ -456,6 +469,7 @@ async function consumeAnthropicStream(
           assembled.stopDetails = event.delta.stop_details;
         }
         takeUsage(assembled.usage, event.usage);
+        if (event.usage !== undefined) assembled.usageKnown = true;
         break;
       }
       default: