@visual-z/xeno 0.3.0 → 0.4.0

package/src/runtime/oauth.ts

@@ -15,9 +15,10 @@
 
 import { createServer, type Server } from "node:http";
 import { pollDeviceCode } from "./oauth-device.ts";
+import { parseDeviceAuthorization, parseOAuthTokens } from "../core/oauth-fields.ts";
 
 /** Matches package.json. Sent as User-Agent so the server can see who we are (D18). */
-export const XENO_VERSION = "0.3.0";
+export const XENO_VERSION = "0.4.0";
 
 /**
  * Minutes subtracted from server expiry so a request issued at the edge
@@ -33,6 +34,7 @@ export const SUBSCRIPTION_OPTIONS = [
   { id: "claude-pro", provider: "anthropic", label: "Claude Pro/Max" },
   { id: "codex", provider: "openai-codex", label: "ChatGPT Plus/Pro (Codex)" },
   { id: "github-copilot", provider: "github-copilot", label: "GitHub Copilot" },
+  { id: "grok", provider: "xai-grok", label: "Grok (official account)" },
 ] as const;
 
 export type SubscriptionId = (typeof SUBSCRIPTION_OPTIONS)[number]["id"];
@@ -101,12 +103,83 @@ export const OPENAI_REDIRECT_URI = `http://localhost:${OPENAI_CALLBACK_PORT}${OP
 const OPENAI_SCOPE = "openid profile email offline_access";
 const OPENAI_JWT_CLAIM = "https://api.openai.com/auth";
 
+// Official Grok Build config.rs / device_code.rs, verified 2026-10-07.
+// This is the public first-party client, with xeno attribution retained (D18).
+const GROK_CLIENT_ID = "b1a00492-073a-47ea-816f-4c329264a828";
+const GROK_AUTH_ORIGIN = "https://auth.x.ai";
+const GROK_TOKEN_URL = `${GROK_AUTH_ORIGIN}/oauth2/token`;
+// Only inference and refresh scopes: xeno does not store remote conversations/workspaces.
+const GROK_SCOPE = "openid profile email offline_access grok-cli:access api:access";
+export const GROK_PROVIDER = "xai-grok";
+export const GROK_BASE_URL = "https://cli-chat-proxy.grok.com/v1";
+/** Official HTTP timeout: issuer requests cannot keep a cancelled or expired grant hanging indefinitely. */
+const GROK_REQUEST_TIMEOUT_MS = 15_000;
+
+async function grokPost(url: string, fields: Record<string, string>, effects: Pick<RefreshEffects, "fetch" | "signal">): Promise<{ status: number; json: unknown }> {
+  const timeout = AbortSignal.timeout(GROK_REQUEST_TIMEOUT_MS);
+  const signal = effects.signal ? AbortSignal.any([effects.signal, timeout]) : timeout;
+  try {
+    const response = await effects.fetch(url, { method: "POST", redirect: "error", signal,
+      headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json", "User-Agent": `xeno/${XENO_VERSION}` },
+      body: new URLSearchParams(fields) });
+    let json: unknown;
+    try { json = await response.json(); } catch { json = undefined; }
+    return { status: response.status, json };
+  } catch {
+    // Network errors can include request details; never expose a credential-bearing body.
+    throw new Error(effects.signal?.aborted ? "Login cancelled" : "Grok authentication request failed");
+  }
+}
+
+export async function loginGrok(interaction: OAuthInteraction, sleep?: Parameters<typeof pollDeviceCode>[0]["sleep"]): Promise<OAuthCredential> {
+  const started = await grokPost(`${GROK_AUTH_ORIGIN}/oauth2/device/code`,
+    { client_id: GROK_CLIENT_ID, scope: GROK_SCOPE, referrer: "xeno" }, interaction);
+  if (started.status < 200 || started.status >= 300) throw new Error(`Grok device code request failed (HTTP ${started.status})`);
+  const device = parseDeviceAuthorization(started.json, [GROK_AUTH_ORIGIN, "https://accounts.x.ai"]);
+  if (!device) throw new Error("Grok device code response was incomplete or untrusted");
+  interaction.signal.throwIfAborted();
+  const url = device.verificationUriComplete ?? device.verificationUri;
+  interaction.notify(`Open ${url}\nand enter code: ${device.userCode}`);
+  tryOpen(url, interaction.openBrowser);
+  return pollDeviceCode<OAuthCredential>({
+    expiresInSeconds: device.expiresIn, waitBeforeFirstPoll: true, signal: interaction.signal,
+    ...(device.interval !== undefined ? { intervalSeconds: device.interval } : {}), ...(sleep ? { sleep } : {}),
+    poll: async () => {
+      const got = await grokPost(GROK_TOKEN_URL,
+        { client_id: GROK_CLIENT_ID, device_code: device.deviceCode, grant_type: "urn:ietf:params:oauth:grant-type:device_code" }, interaction);
+      const body = asRecord(got.json);
+      // RFC 8628 errors use HTTP 400; they are polling states, never completed logins.
+      if (got.status === 400 && body?.["error"] === "authorization_pending") return { status: "pending" };
+      if (got.status === 400 && body?.["error"] === "slow_down") return { status: "slow_down" };
+      if (got.status < 200 || got.status >= 300) return { status: "failed", message: `Grok device login failed (HTTP ${got.status})` };
+      const fields = parseOAuthTokens(got.json);
+      if (!fields) return { status: "failed", message: "Grok token response was incomplete" };
+      interaction.signal.throwIfAborted();
+      return { status: "complete", value: { type: "oauth", access: fields.access, refresh: fields.refresh,
+        expires: expiryFromExpiresIn(fields.expiresIn, (interaction.now ?? Date.now)()) } };
+    },
+  });
+}
+
+async function refreshGrok(refresh: string, effects: RefreshEffects): Promise<{ ok: true; credential: OAuthCredential } | { ok: false; reason: string }> {
+  try {
+    const got = await grokPost(GROK_TOKEN_URL, { client_id: GROK_CLIENT_ID, grant_type: "refresh_token", refresh_token: refresh }, effects);
+    if (effects.signal?.aborted) return { ok: false, reason: "Login cancelled" };
+    if (got.status < 200 || got.status >= 300) return { ok: false, reason: `HTTP ${got.status}` };
+    const fields = parseOAuthTokens(got.json, refresh);
+    if (!fields) return { ok: false, reason: "unexpected body" };
+    return { ok: true, credential: { type: "oauth", access: fields.access, refresh: fields.refresh,
+      expires: expiryFromExpiresIn(fields.expiresIn, effects.now()) } };
+  } catch { return { ok: false, reason: "Grok token refresh failed" }; }
+}
+
 export function isSubscriptionLogin(id: string): boolean {
-  return SUBSCRIPTION_OPTIONS.some((o) => o.id === id);
+  return subscriptionById(id) !== undefined;
 }
 
 export function subscriptionById(id: string): (typeof SUBSCRIPTION_OPTIONS)[number] | undefined {
-  return SUBSCRIPTION_OPTIONS.find((o) => o.id === id);
+  // Separate account providers accept their catalog identity too; anthropic still means an API key.
+  return SUBSCRIPTION_OPTIONS.find(o => o.id === id || (o.provider === id && o.provider !== "anthropic"));
 }
 
 export function expiryFromExpiresIn(expiresIn: number, now: number): number {
@@ -505,6 +578,8 @@ export async function refreshOAuthCredential(
       return refreshOpenAI(credential.refresh, opts);
     case "github-copilot":
       return refreshCopilot(credential.refresh, opts, credential.enterpriseUrl);
+    case GROK_PROVIDER:
+      return refreshGrok(credential.refresh, opts);
     default:
       return { ok: false, reason: `no oauth refresh for ${provider}` };
   }
@@ -752,6 +827,8 @@ export async function loginSubscription(
       return { provider: "openai-codex", credential: await loginOpenAICodex(interaction) };
     case "github-copilot":
       return { provider: "github-copilot", credential: await loginGitHubCopilot(interaction) };
+    case "grok":
+      return { provider: GROK_PROVIDER, credential: await loginGrok(interaction) };
     default: {
       const never: never = id;
       throw new Error(`unknown subscription login: ${String(never)}`);

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

@@ -1,5 +1,5 @@
 /**
- * The `models.json` edit `/login` makes for a connected provider, as a pure transform.
+ * 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
@@ -97,7 +97,7 @@ export function applyConnect(json: unknown, request: ConnectRequest, catalog: re
   return root;
 }
 
-/** Remove what `/login` wrote for a provider; other providers and flat rows are untouched. */
+/** 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"])) {

package/src/runtime/provider-presets.ts

@@ -1,5 +1,5 @@
 /**
- * What `/login` offers for custom endpoints before the user types anything.
+ * 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

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: