@visual-z/xeno 0.3.0 → 0.5.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

@@ -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:

package/src/runtime/session-control.ts

@@ -0,0 +1,198 @@
+/** Q24: one controller per live Session, shared by the TUI and structured adapters. */
+import { createHash, randomUUID } from "node:crypto";
+import { resolve } from "node:path";
+import { goalView, contextLens, type GoalView, type ContextLens } from "../core/control-view.ts";
+import { DEFAULT_CONTEXT_POLICY } from "../core/context-policy.ts";
+import { userInputData, type UserInput } from "../core/images.ts";
+import type { Phase } from "../core/queue.ts";
+import type { PermissionRequest } from "../core/permissions.ts";
+import type { ExecutionOutcome } from "../core/outcome.ts";
+import type { LogEvent } from "../core/events.ts";
+import { readNodeHistory } from "../store/restore.ts";
+import type { Session, LoopEvent } from "./loop.ts";
+import type { ApprovalChoice } from "./tools.ts";
+
+export type ControlNotice = { method: string; params: { threadId: string; streamId: string; sequence: number; turnId?: string; [key: string]: unknown } };
+export type PendingApproval = { id: string; turnId: string; request: PermissionRequest };
+export type ControlSnapshot = {
+  version: "xeno-control/0.1"; threadId: string; streamId: string; sequence: number; node: number;
+  activeTurnId: string | null; goal: GoalView | null; context: ContextLens;
+  waiting: "permission" | "question" | "auth" | null; approvals: PendingApproval[];
+};
+
+export class SessionControl {
+  readonly session: Session;
+  readonly threadId: string;
+  readonly streamId = randomUUID();
+  private sequence = 0;
+  private listeners = new Set<(event: ControlNotice) => void>();
+  private active: { id: string; abort: AbortController; queue: UserInput[] } | null = null;
+  private task: Promise<void> | null = null;
+  private approvals = new Map<string, { data: PendingApproval; resolve: (choice: ApprovalChoice) => void }>();
+  private waiting: ControlSnapshot["waiting"] = null;
+  private changing = false;
+  private inputSource: ((phase: Phase) => Promise<UserInput | null>) | undefined;
+
+  constructor(session: Session) {
+    this.session = session;
+    // Same identity rule as provider affinity; no new durable identity store (D8).
+    this.threadId = createHash("sha256").update(resolve(session.config.logDir)).digest("hex");
+    session.subscribeRecords(item => this.emit("item/completed", { item }));
+  }
+  get activeTurnId(): string | null { return this.active?.id ?? null; }
+  get busy(): boolean { return this.changing || this.active !== null || this.session.running; }
+
+  subscribe(listener: (event: ControlNotice) => void): () => void {
+    this.listeners.add(listener); return () => { this.listeners.delete(listener); };
+  }
+  /** The attached editor owns retractable drafts even when an adapter starts the turn. */
+  attachInput(pull: (phase: Phase) => Promise<UserInput | null>): () => void {
+    if (this.inputSource) throw Error("the session already has an attached input owner");
+    this.inputSource = pull;
+    return () => { if (this.inputSource === pull) this.inputSource = undefined; };
+  }
+  private emit(method: string, data: Record<string, unknown> = {}): void {
+    const event: ControlNotice = { method, params: { ...data, threadId: this.threadId, streamId: this.streamId,
+      sequence: ++this.sequence, ...(this.active ? { turnId: this.active.id } : {}) } };
+    for (const listener of this.listeners) {
+      // Observers are outside the evidence owner: mutations and failures cannot alter execution.
+      try { listener(structuredClone(event)); } catch { /* the transport owns delivery errors */ }
+    }
+  }
+  async snapshot(observe = true): Promise<ControlSnapshot> {
+    if (observe && !this.busy) await this.session.acceptanceState();
+    const node = this.session.state.node;
+    const history = await readNodeHistory(this.session.config.logDir, node, undefined, "context");
+    if (!history.ok) throw Error(history.error);
+    if (node !== this.session.state.node) throw Error("session changed while reading; refresh the snapshot");
+    const s = this.session;
+    // Ancestors are sealed. The live segment must share the cursor's publication
+    // boundary: a disk read can finish between append and in-memory publication.
+    const parts = history.nodes.map(part => part.node === node ? { node, events: structuredClone(s.state.events) } : part);
+    const projectedGoal = goalView(parts);
+    const goal = this.active && projectedGoal?.state.request.event !== this.active.id ? null : projectedGoal;
+    return { version: "xeno-control/0.1", threadId: this.threadId, streamId: this.streamId, sequence: this.sequence, node,
+      activeTurnId: this.activeTurnId, goal, waiting: this.waiting,
+      approvals: structuredClone([...this.approvals.values()].map(item => item.data)),
+      context: contextLens({ ...s.contextInput(), anchor: s.state.anchor, policy: s.config.contextPolicy ?? DEFAULT_CONTEXT_POLICY,
+        contextWindow: s.provider.config.spec.contextWindow, outputReserve: s.provider.config.maxTokens,
+        ...(s.config.counter ? { counter: s.config.counter } : {}), ...(s.config.boundary ? { boundary: s.config.boundary } : {}) }) };
+  }
+  async items(): Promise<{ node: number; event: LogEvent }[]> {
+    const node = this.session.state.node;
+    const history = await readNodeHistory(this.session.config.logDir, node, undefined, "context");
+    if (!history.ok) throw Error(history.error);
+    if (node !== this.session.state.node) throw Error("session changed while reading; refresh the snapshot");
+    return history.nodes.flatMap(part => (part.node === node ? structuredClone(this.session.state.events) : part.events)
+      .map(event => ({ node: part.node, event })));
+  }
+
+  /** Both local and remote turns pass through this iterator; Session remains the execution owner. */
+  async *send(input: UserInput, signal?: AbortSignal, pull?: (phase: Phase) => Promise<UserInput | null>): AsyncGenerator<LoopEvent> {
+    if (this.busy) throw Error("a turn is already running");
+    const active = { id: this.session.clock.nextId(), abort: new AbortController(), queue: [] as UserInput[] };
+    this.active = active;
+    const signals = signal ? AbortSignal.any([signal, active.abort.signal]) : active.abort.signal;
+    let outcome: ExecutionOutcome | undefined;
+    try {
+      this.emit("turn/started");
+      const steering = async (phase: Phase): Promise<UserInput | null> => {
+        const external = active.queue.splice(0), local = await (pull ?? this.inputSource)?.(phase);
+        if (local) external.push(local);
+        const data = external.map(value => userInputData(value));
+        const text = data.map(value => value.text).join("\n\n"), images = data.flatMap(value => value.images ?? []);
+        return images.length ? { text, images } : text || null;
+      };
+      for await (const event of this.session.send(input, signals, steering, active.id)) {
+        this.emit("turn/event", { event });
+        if (event.kind === "done") outcome = event.outcome;
+        yield event;
+      }
+    } catch (error) {
+      // Raw provider errors may contain credentials. The owner can report a sanitized error separately.
+      this.emit("turn/error", { message: "turn failed; inspect the session outcome" });
+      throw error;
+    } finally {
+      for (const approval of [...this.approvals.values()]) approval.resolve("deny");
+      this.waiting = null;
+      // A thrown provider error also appends an outcome. Clients must be able to discover it.
+      try {
+        if (!outcome) {
+          const state = (await this.snapshot(false)).goal?.state;
+          if (state?.request.event === active.id) outcome = state.execution;
+        }
+      } catch { /* unreadable storage stays unknown, never an invented completion */ }
+      this.emit("turn/completed", { ...(outcome ? { outcome } : {}), steeringUndelivered: active.queue.length });
+      this.active = null;
+    }
+  }
+  start(input: UserInput): string {
+    if (this.busy) throw Error("a turn is already running");
+    this.task = (async () => { for await (const _event of this.send(input)) { /* notices are the client stream */ } })();
+    void this.task.catch(() => {});
+    return this.active!.id;
+  }
+  async whenIdle(): Promise<void> { await this.task; await this.session.whenIdle(); }
+  private current(turnId: string): NonNullable<SessionControl["active"]> {
+    if (!this.active || this.active.id !== turnId) throw Error("stale or unknown turnId");
+    return this.active;
+  }
+  steer(turnId: string, input: UserInput): void {
+    const turn = this.current(turnId);
+    // Assumed ingress bound, not an execution policy. Keep a client from queuing unbounded work.
+    if (turn.queue.length >= 32) throw Error("steering queue is full");
+    turn.queue.push(structuredClone(input));
+    this.emit("turn/steeringQueued", { count: turn.queue.length });
+  }
+  interrupt(turnId: string): void {
+    this.current(turnId).abort.abort();
+    for (const approval of [...this.approvals.values()]) approval.resolve("deny");
+    this.session.cancel();
+  }
+  setWaiting(kind: ControlSnapshot["waiting"]): void {
+    this.waiting = this.approvals.size ? "permission" : kind;
+    this.emit("thread/statusChanged", { waiting: this.waiting });
+  }
+  ask(request: PermissionRequest, present?: (id: string, resolve: (choice: ApprovalChoice) => void) => (() => void)): Promise<ApprovalChoice> {
+    if (!this.active) return Promise.resolve("deny");
+    const data = { id: randomUUID(), turnId: this.active.id, request: structuredClone(request) };
+    return new Promise(resolveChoice => {
+      let close: (() => void) | undefined;
+      const resolveOnce = (choice: ApprovalChoice) => {
+        if (!this.approvals.delete(data.id)) return;
+        close?.(); this.waiting = this.approvals.size ? "permission" : null;
+        this.emit("approval/resolved", { approvalId: data.id }); resolveChoice(choice);
+      };
+      this.approvals.set(data.id, { data, resolve: resolveOnce }); this.waiting = "permission";
+      this.emit("approval/request", { approval: data });
+      if (this.approvals.has(data.id)) {
+        try { close = present?.(data.id, resolveOnce); }
+        catch { resolveOnce("deny"); }
+      }
+    });
+  }
+  respond(turnId: string, id: string, choice: ApprovalChoice): void {
+    this.current(turnId);
+    const approval = this.approvals.get(id);
+    if (!approval || approval.data.turnId !== turnId) throw Error("stale or unknown approvalId");
+    approval.resolve(choice);
+  }
+  denyApprovals(): void { for (const approval of [...this.approvals.values()]) approval.resolve("deny"); }
+  async accept(requestId: string, criterion: string): Promise<void> {
+    if (this.busy) throw Error("acceptance requires an idle session");
+    this.changing = true;
+    try {
+      const state = await this.session.requestState();
+      if (state?.request.event !== requestId) throw Error("stale or unknown requestId");
+      await this.session.acceptCriterion(criterion);
+      this.emit("thread/statusChanged");
+    } finally { this.changing = false; }
+  }
+}
+
+const controls = new WeakMap<Session, SessionControl>();
+export function sessionControl(session: Session): SessionControl {
+  let control = controls.get(session);
+  if (!control) { control = new SessionControl(session); controls.set(session, control); }
+  return control;
+}