@ggui-ai/ui-gen 0.20.0 → 0.22.0

package/src/harness/llm-router.ts

@@ -24,17 +24,33 @@ import type {
   GoogleGenAI,
   Interactions,
 } from '@google/genai';
-import type { JsonObject } from '@ggui-ai/protocol';
+import {
+  anthropicRejectsForcedToolChoice,
+  anthropicRejectsSamplingParams,
+  normalizeAnthropicModelId,
+  type JsonObject,
+} from '@ggui-ai/protocol';
 import type { LLMToolDef } from '../llm.js';
 import type { AnthropicBedrock } from '@anthropic-ai/bedrock-sdk';
 import { createAnthropicClient } from '../adapters/claude/client.js';
 import { getBedrockModelId } from '../adapters/provider-router.js';
 import { toolArgsToJsonObject } from '../adapters/tool-bridge.js';
+import { splitCacheInclusiveUsage, splitOpenAiUsage } from '../adapters/openai/tokens.js';
 import {
   emitLlmTraceEvent,
   newLlmTraceId,
   summarizeTools,
 } from './llm-trace-sink.js';
+import {
+  buildLoginQueryOptions,
+  collectLoginTurn,
+  createDenyingIntercept,
+  createLoginToolServer,
+  imageUserMessage,
+  LOGIN_REQUIRED_TOOL_INSTRUCTION,
+  type InterceptedToolCall,
+  type LoginSdk,
+} from './claude-code-login-query.js';
 
 // `LLMToolDef` lives in `@ggui-ai/ui-gen/llm`. This file re-exports it
 // so `../harness/llm-router.js` importers (evaluator.ts,
@@ -76,6 +92,16 @@ export interface AgentConfig {
     readonly apiKey?: string;
     /** Anthropic-only: force the Bedrock-IAM client instead of the direct API client. */
     readonly useBedrock?: boolean;
+    /**
+     * Anthropic-only (ggui#1185): run on the machine's own Claude Code
+     * LOGIN instead of a key — the route decision `auth: 'claude-code-login'`
+     * lands here, and `createAgent` / `createVisionAgent` select
+     * `ClaudeCodeLoginAgent` (one `query()` per call) instead of the raw
+     * API client. Every agent the harness builds — coding, evaluation,
+     * visual judge — takes the same decision. Off unless set; a real key
+     * never coexists with it (the router refuses a non-anthropic route).
+     */
+    readonly claudeCodeLogin?: boolean;
   };
   /**
    * Observer invoked once per retried attempt when `apiCall()` (#489)
@@ -180,6 +206,8 @@ export interface LLMWithToolsResponse {
   inputTokens: number;
   outputTokens: number;
   turnsUsed: number;
+  /** Prompt-cache reads summed over the loop's turns, when the provider reports them (absent = unreported, never zero). */
+  cacheReadTokens?: number;
 }
 
 export interface LLMToolCall {
@@ -195,9 +223,10 @@ export interface LLMToolCallResponse {
   outputTokens: number;
   /**
    * The tool-choice mode the provider ACTUALLY received. Callers ask
-   * for `'required'` (Anthropic `tool_choice: any`); Claude Fable 5.1
-   * rejects forced tool choice with HTTP 400, so the Anthropic adapter
-   * downgrades to `'auto'` for that family and reports it here. A
+   * for `'required'` (Anthropic `tool_choice: any`); Claude Fable 5.1 and
+   * Opus 5.5 reject forced tool choice with HTTP 400, so the Anthropic
+   * and OpenRouter adapters downgrade to `'auto'` for those families and
+   * report it here. A
    * downgraded call may legitimately return zero tool calls — the
    * evaluator's `criteriaCoverage` records that as `skipped`, never as
    * a pass. Absent = predates the field (treat as unknown).
@@ -546,39 +575,6 @@ export abstract class LLMAgent {
 // AnthropicAgent
 // =============================================================================
 
-/**
- * Strip every routing spelling down to the bare Claude API id so the
- * family predicates below see one form: `anthropic/claude-x`,
- * `anthropic.claude-x`, `us.anthropic.claude-x[-vN:M]` and the bare
- * `claude-x` all normalize to `claude-x…`. ARNs are left as-is (they
- * name a profile, not a family) and match no predicate.
- */
-export function normalizeAnthropicModelId(model: string): string {
-  return model
-    .replace(/^anthropic\//, '')
-    .replace(/^(?:[a-z]{2}\.)?anthropic\./, '');
-}
-
-/**
- * Models that reject non-default sampling parameters with HTTP 400:
- * Opus 4.7 and everything after it (Fable 5, Fable 5.1, Opus 5,
- * Sonnet 5). Haiku 4.5 (`claude-haiku-4-5*`) still accepts them.
- * Strings per ggui#706 (platform.claude.com, verified 2026-09-02).
- */
-export function anthropicRejectsSamplingParams(model: string): boolean {
-  return /^claude-(?:opus-4-7|opus-5|sonnet-5|fable-5)(?:-|$)/.test(
-    normalizeAnthropicModelId(model),
-  );
-}
-
-/**
- * Models that reject a FORCED tool choice (`tool_choice: any` / a named
- * tool) with HTTP 400: Claude Fable 5.1 (ggui#706). `auto` is accepted.
- */
-export function anthropicRejectsForcedToolChoice(model: string): boolean {
-  return /^claude-fable-5-1(?:-|$)/.test(normalizeAnthropicModelId(model));
-}
-
 /**
  * Decide what sampling reaches Anthropic for `model` given the caller's
  * `temperature`: pass it through on models that accept it, strip it on
@@ -869,10 +865,10 @@ export class AnthropicAgent extends LLMAgent {
       // want the final-message shape downstream, so use the stream
       // helper's `finalMessage()` which folds the events back to the
       // same `Message` Type the non-streaming path returned.
-      // Fable 5.1 rejects a forced tool choice (400); downgrade to
-      // `auto` for that family and disclose it on the response so a
-      // resulting zero-tool-call reply is never mistaken for a verdict
-      // (ggui#710 / #706).
+      // Fable 5.1 and Opus 5.5 reject a forced tool choice (400);
+      // downgrade to `auto` for those families and disclose it on the
+      // response so a resulting zero-tool-call reply is never mistaken
+      // for a verdict (ggui#710 / #706 / #1254).
       const appliedToolChoice: 'required' | 'auto' =
         toolChoice === 'required' && anthropicRejectsForcedToolChoice(resolvedModel)
           ? 'auto'
@@ -1090,6 +1086,258 @@ export class AnthropicAgent extends LLMAgent {
 // OpenAIAgent
 // =============================================================================
 
+/**
+ * ggui#1185 (B) — the Anthropic model reached through the machine's own
+ * Claude Code LOGIN, for the one path that has no key: every router call
+ * is ONE Agent SDK `query()` (`maxTurns: 1`), the binary PROPOSES tool
+ * calls and ggui's harness executes them — the same one-shot contract as
+ * `AnthropicAgent.callTools`, so everything above the router (the coding
+ * loop, `apply_changes`, the axis checks, the evaluation legs) is
+ * untouched. Selected only when the route decision carries
+ * `routeOverride.claudeCodeLogin`; never by default.
+ *
+ * What it refuses, as behaviour (the carve-out): it writes no key
+ * anywhere (the env the binary inherits is stripped of every provider key
+ * name and `system:init.apiKeySource` must read `"none"` or the run stops
+ * before its first turn); it never runs `--bare`, never loads `~/.claude`,
+ * and never allow-lists a tool (an allow-listed MCP tool executes without
+ * asking). The pure pieces — options, the JSON-Schema→Zod tool bridge, the
+ * stream reader and its error classes — live in
+ * `./claude-code-login-query.ts`; the measurements behind each are cited
+ * there. Rate limits are the plan's: a 429 the binary relays rides the
+ * same `apiCall()` retry seam as the raw client.
+ *
+ * Honest asymmetries, reported rather than hidden: the SDK has no
+ * `tool_choice`, so `appliedToolChoice` is always `'auto'`; the binary
+ * emitted a thinking block despite `thinkingConfig: { type: 'disabled' }`
+ * in the probe (Exp 009 reports thinking tokens as their own column);
+ * `warmCache` is a no-op (a warm-up turn would spend the plan for
+ * nothing); `callWithTools` (an in-client agentic loop) is not offered —
+ * the harness runs the loop.
+ */
+export class ClaudeCodeLoginAgent extends LLMAgent implements VisionAgent {
+  readonly provider = 'anthropic' as const;
+
+  protected resolveModel(model: string): string {
+    return model.startsWith('anthropic/') ? model.slice('anthropic/'.length) : model;
+  }
+
+  protected async createClient(): Promise<LoginSdk> {
+    const { query, tool, createSdkMcpServer } = await import('@anthropic-ai/claude-agent-sdk');
+    return { query, tool, createSdkMcpServer };
+  }
+
+  async callText(
+    model: string,
+    systemPrompt: string,
+    userPrompt: string,
+    _maxTokens?: number,
+    _temperature?: number,
+  ): Promise<LLMResponse> {
+    const sdk = await this.getClient<LoginSdk>();
+    const traceId = newLlmTraceId();
+    const startedAt = Date.now();
+    const resolvedModel = this.resolveModel(model);
+    try {
+      const turn = await this.apiCall(() =>
+        collectLoginTurn(
+          sdk.query({
+            prompt: userPrompt,
+            options: buildLoginQueryOptions({ model: resolvedModel, systemPrompt }),
+          }),
+          { intercepted: [], kind: "callText", choice: "none", log: console.log, warn: console.warn },
+        ),
+      );
+      const usage = turn.result.usage;
+      const endedAt = Date.now();
+      emitLlmTraceEvent({
+        id: traceId,
+        at: startedAt,
+        endedAt,
+        durationMs: endedAt - startedAt,
+        provider: 'claude-code-login',
+        model: resolvedModel,
+        kind: 'callText',
+        systemPrompt,
+        userPrompt,
+        result: {
+          inputTokens: usage.input_tokens,
+          outputTokens: usage.output_tokens,
+          cacheCreated: usage.cache_creation_input_tokens,
+          cacheRead: usage.cache_read_input_tokens,
+          text: turn.text,
+        },
+      });
+      return { text: turn.text, inputTokens: usage.input_tokens, outputTokens: usage.output_tokens };
+    } catch (e) {
+      const endedAt = Date.now();
+      emitLlmTraceEvent({
+        id: traceId,
+        at: startedAt,
+        endedAt,
+        durationMs: endedAt - startedAt,
+        provider: 'claude-code-login',
+        model: resolvedModel,
+        kind: 'callText',
+        systemPrompt,
+        userPrompt,
+        error: { message: e instanceof Error ? e.message : String(e) },
+      });
+      throw e;
+    }
+  }
+
+  async callVision(
+    model: string,
+    systemPrompt: string,
+    userPrompt: string,
+    image: VisionImageInput,
+    _maxTokens?: number,
+  ): Promise<LLMResponse> {
+    const sdk = await this.getClient<LoginSdk>();
+    const traceId = newLlmTraceId();
+    const startedAt = Date.now();
+    const resolvedModel = this.resolveModel(model);
+    try {
+      const turn = await this.apiCall(() =>
+        collectLoginTurn(
+          sdk.query({
+            prompt: imageUserMessage(userPrompt, image),
+            options: buildLoginQueryOptions({ model: resolvedModel, systemPrompt }),
+          }),
+          { intercepted: [], kind: "callVision", choice: "none", log: console.log, warn: console.warn },
+        ),
+      );
+      const usage = turn.result.usage;
+      const endedAt = Date.now();
+      emitLlmTraceEvent({
+        id: traceId,
+        at: startedAt,
+        endedAt,
+        durationMs: endedAt - startedAt,
+        provider: 'claude-code-login',
+        model: resolvedModel,
+        kind: 'callVision',
+        systemPrompt,
+        userPrompt,
+        result: { inputTokens: usage.input_tokens, outputTokens: usage.output_tokens, text: turn.text },
+      });
+      return { text: turn.text, inputTokens: usage.input_tokens, outputTokens: usage.output_tokens };
+    } catch (e) {
+      const endedAt = Date.now();
+      emitLlmTraceEvent({
+        id: traceId,
+        at: startedAt,
+        endedAt,
+        durationMs: endedAt - startedAt,
+        provider: 'claude-code-login',
+        model: resolvedModel,
+        kind: 'callVision',
+        systemPrompt,
+        userPrompt,
+        error: { message: e instanceof Error ? e.message : String(e) },
+      });
+      throw e;
+    }
+  }
+
+  async callTools(
+    model: string,
+    systemPrompt: string,
+    userPrompt: string,
+    tools: LLMToolDef[],
+    toolChoice: 'required' | 'auto' = 'required',
+    _scopedTools?: LLMToolDef[],
+  ): Promise<LLMToolCallResponse> {
+    const sdk = await this.getClient<LoginSdk>();
+    const traceId = newLlmTraceId();
+    const startedAt = Date.now();
+    const resolvedModel = this.resolveModel(model);
+    // ggui#1273 — the Agent SDK has no tool_choice; 'required' is implemented
+    // as rnd's instruction on the USER prompt (never the system prompt) and
+    // disclosed as instructed-not-enforced: appliedToolChoice stays 'auto'.
+    const sentUserPrompt =
+      toolChoice === 'required' ? `${userPrompt}\n\n${LOGIN_REQUIRED_TOOL_INSTRUCTION}` : userPrompt;
+    try {
+      const turn = await this.apiCall(() => {
+        // Fresh per attempt: the SDK connects the server instance per query().
+        const intercepted: InterceptedToolCall[] = [];
+        const server = createLoginToolServer(sdk, tools);
+        return collectLoginTurn(
+          sdk.query({
+            prompt: sentUserPrompt,
+            options: buildLoginQueryOptions({
+              model: resolvedModel,
+              systemPrompt,
+              tools: { server, canUseTool: createDenyingIntercept(intercepted) },
+            }),
+          }),
+          { intercepted, kind: "callTools", choice: toolChoice === 'required' ? "required:instructed" : "auto", log: console.log, warn: console.warn },
+        );
+      });
+      const usage = turn.result.usage;
+      const cacheCreated = usage.cache_creation_input_tokens;
+      const cacheRead = usage.cache_read_input_tokens;
+      if (cacheCreated || cacheRead) {
+        console.log(
+          `[claude-code-login] callTools cache: created=${cacheCreated} read=${cacheRead} input=${usage.input_tokens} output=${usage.output_tokens}`,
+        );
+      }
+      const toolCalls: LLMToolCall[] = turn.toolCalls.map((c) => ({ id: c.id, name: c.name, input: c.input }));
+      const endedAt = Date.now();
+      emitLlmTraceEvent({
+        id: traceId,
+        at: startedAt,
+        endedAt,
+        durationMs: endedAt - startedAt,
+        provider: 'claude-code-login',
+        model: resolvedModel,
+        kind: 'callTools',
+        systemPrompt,
+        userPrompt: sentUserPrompt,
+        tools: summarizeTools(tools),
+        result: {
+          inputTokens: usage.input_tokens,
+          outputTokens: usage.output_tokens,
+          cacheCreated,
+          cacheRead,
+          toolCalls: toolCalls.map((c) => ({ name: c.name, input: c.input })),
+        },
+      });
+      return {
+        toolCalls,
+        inputTokens: usage.input_tokens,
+        outputTokens: usage.output_tokens,
+        cacheReadTokens: cacheRead,
+        cacheCreationTokens: cacheCreated,
+        appliedToolChoice: 'auto',
+      };
+    } catch (e) {
+      const endedAt = Date.now();
+      emitLlmTraceEvent({
+        id: traceId,
+        at: startedAt,
+        endedAt,
+        durationMs: endedAt - startedAt,
+        provider: 'claude-code-login',
+        model: resolvedModel,
+        kind: 'callTools',
+        systemPrompt,
+        userPrompt: sentUserPrompt,
+        tools: summarizeTools(tools),
+        error: { message: e instanceof Error ? e.message : String(e) },
+      });
+      throw e;
+    }
+  }
+
+  async callWithTools(): Promise<LLMWithToolsResponse> {
+    throw new Error(
+      "claude-code-login: callWithTools (an in-client agentic loop) is not part of the login client — ggui's harness runs the loop through callTools",
+    );
+  }
+}
+
 export class OpenAIAgent extends LLMAgent {
   readonly provider = 'openai' as const;
 
@@ -1131,10 +1379,19 @@ export class OpenAIAgent extends LLMAgent {
       }
     }
 
+    // ggui#1186 (second site): `input_tokens` INCLUDES the cached prefix on the
+    // Responses API — report the NON-cached input like every other provider.
+    // The text response carries no cache field, so the cached count is
+    // dropped here rather than double-counted.
+    const textUsage = splitOpenAiUsage(
+      response.usage?.input_tokens ?? 0,
+      response.usage?.output_tokens ?? 0,
+      response.usage?.input_tokens_details?.cached_tokens ?? 0,
+    );
     return {
       text,
-      inputTokens: response.usage?.input_tokens ?? 0,
-      outputTokens: response.usage?.output_tokens ?? 0,
+      inputTokens: textUsage.tokens.input,
+      outputTokens: textUsage.tokens.output,
       sampling: { temperature: temperature ?? 'provider-default' },
     };
   }
@@ -1196,14 +1453,26 @@ export class OpenAIAgent extends LLMAgent {
       (o): o is ResponseFunctionToolCall => o.type === 'function_call',
     );
 
+    // ggui#1186 (second site): the harness coding loop reads THIS per-turn
+    // usage (`run-coding-turn` → `generate-task-runner` telemetry), not the
+    // adapters' results — so the split lives here too: `inputTokens` is the
+    // NON-cached input and `cacheReadTokens` the cached subset, reported (0
+    // when the breakdown says none), so a generation's metadata — and whatever
+    // prices or aggregates it downstream — sees OpenAI cache reads at all.
+    const toolsUsage = splitOpenAiUsage(
+      response.usage?.input_tokens ?? 0,
+      response.usage?.output_tokens ?? 0,
+      response.usage?.input_tokens_details?.cached_tokens ?? 0,
+    );
     return {
       toolCalls: functionCalls.map((fc) => ({
         id: fc.call_id,
         name: fc.name,
         input: JSON.parse(fc.arguments ?? '{}') as JsonObject,
       })),
-      inputTokens: response.usage?.input_tokens ?? 0,
-      outputTokens: response.usage?.output_tokens ?? 0,
+      inputTokens: toolsUsage.tokens.input,
+      outputTokens: toolsUsage.tokens.output,
+      cacheReadTokens: toolsUsage.cacheReadTokens,
     };
   }
 
@@ -1242,6 +1511,7 @@ export class OpenAIAgent extends LLMAgent {
     ];
     let totalIn = 0;
     let totalOut = 0;
+    let totalCacheRead = 0;
     let allText = '';
 
     for (let turn = 0; turn < maxTurns; turn++) {
@@ -1253,8 +1523,15 @@ export class OpenAIAgent extends LLMAgent {
           tools: openaiTools,
         }),
       );
-      totalIn += response.usage?.input_tokens ?? 0;
-      totalOut += response.usage?.output_tokens ?? 0;
+      // ggui#1186 (second site): non-cached input + cached subset, per turn.
+      const turnUsage = splitOpenAiUsage(
+        response.usage?.input_tokens ?? 0,
+        response.usage?.output_tokens ?? 0,
+        response.usage?.input_tokens_details?.cached_tokens ?? 0,
+      );
+      totalIn += turnUsage.tokens.input;
+      totalOut += turnUsage.tokens.output;
+      totalCacheRead += turnUsage.cacheReadTokens;
 
       const functionCalls = response.output.filter(
         (o): o is ResponseFunctionToolCall => o.type === 'function_call',
@@ -1291,6 +1568,7 @@ export class OpenAIAgent extends LLMAgent {
       text: allText,
       inputTokens: totalIn,
       outputTokens: totalOut,
+      cacheReadTokens: totalCacheRead,
       turnsUsed: input.length,
     };
   }
@@ -1339,6 +1617,19 @@ function toUserInputStep(text: string): Interactions.UserInputStep {
   return { type: 'user_input', content: [{ type: 'text', text }] };
 }
 
+/**
+ * ggui#1186 (third site) — an Interactions `usage` split into the shared
+ * convention: `total_input_tokens` includes the cached part of the prompt
+ * (`total_cached_tokens`, per the SDK's own words), so the non-cached prompt
+ * is the input and the cached subset is reported separately.
+ */
+function googleInteractionUsage(
+  usage: { total_input_tokens?: number; total_output_tokens?: number; total_cached_tokens?: number } | undefined,
+): { inputTokens: number; outputTokens: number; cacheReadTokens: number } {
+  const split = splitCacheInclusiveUsage(usage?.total_input_tokens ?? 0, usage?.total_output_tokens ?? 0, usage?.total_cached_tokens ?? 0);
+  return { inputTokens: split.tokens.input, outputTokens: split.tokens.output, cacheReadTokens: split.cacheReadTokens };
+}
+
 export class GoogleAgent extends LLMAgent {
   readonly provider = 'google' as const;
 
@@ -1392,8 +1683,9 @@ export class GoogleAgent extends LLMAgent {
 
     return {
       text: interactionText(interaction),
-      inputTokens: interaction.usage?.total_input_tokens ?? 0,
-      outputTokens: interaction.usage?.total_output_tokens ?? 0,
+      // ggui#1186 (third site): `total_input_tokens` INCLUDES the cached part of the prompt — report the non-cached input.
+      inputTokens: googleInteractionUsage(interaction.usage).inputTokens,
+      outputTokens: googleInteractionUsage(interaction.usage).outputTokens,
       sampling: { temperature: temperature ?? 'provider-default' },
     };
   }
@@ -1435,7 +1727,8 @@ export class GoogleAgent extends LLMAgent {
       const usage = response.usageMetadata;
       const result: LLMResponse = {
         text,
-        inputTokens: usage?.promptTokenCount ?? 0,
+        // ggui#1186 (third site): `promptTokenCount` includes `cachedContentTokenCount` — report the non-cached input.
+        inputTokens: splitCacheInclusiveUsage(usage?.promptTokenCount ?? 0, usage?.candidatesTokenCount ?? 0, usage?.cachedContentTokenCount ?? 0).tokens.input,
         outputTokens: usage?.candidatesTokenCount ?? 0,
       };
 
@@ -1625,8 +1918,8 @@ export class GoogleAgent extends LLMAgent {
 
     return {
       toolCalls,
-      inputTokens: interaction.usage?.total_input_tokens ?? 0,
-      outputTokens: interaction.usage?.total_output_tokens ?? 0,
+      // ggui#1186 (third site): the coding loop reads this per-turn usage — the non-cached prompt as input, the cached subset reported.
+      ...googleInteractionUsage(interaction.usage),
     };
   }
 
@@ -1664,6 +1957,7 @@ export class GoogleAgent extends LLMAgent {
 
     let totalIn = 0;
     let totalOut = 0;
+    let totalCacheRead = 0;
     let allText = '';
     let turnsUsed = 0;
 
@@ -1681,8 +1975,11 @@ export class GoogleAgent extends LLMAgent {
       turnsUsed = turn + 1;
 
       if (interaction.usage) {
-        totalIn += interaction.usage.total_input_tokens ?? 0;
-        totalOut += interaction.usage.total_output_tokens ?? 0;
+        // ggui#1186 (third site): non-cached input + cached subset, per turn.
+        const turnUsage = googleInteractionUsage(interaction.usage);
+        totalIn += turnUsage.inputTokens;
+        totalOut += turnUsage.outputTokens;
+        totalCacheRead += turnUsage.cacheReadTokens;
       }
 
       // Collect text
@@ -1730,6 +2027,7 @@ export class GoogleAgent extends LLMAgent {
       text: allText,
       inputTokens: totalIn,
       outputTokens: totalOut,
+      cacheReadTokens: totalCacheRead,
       turnsUsed,
     };
   }
@@ -1821,12 +2119,25 @@ export class OpenRouterAgent extends LLMAgent {
     }
     this.sessionMessages.push({ role: 'user', content: userPrompt });
 
+    // ggui#1254 — OpenRouter forwards the tool choice to the upstream, so an
+    // Anthropic family that refuses a forced tool choice (Fable 5.1, Opus 5.5;
+    // OpenRouter spells them `anthropic/claude-opus-5.5`) 400s here exactly as
+    // it does direct. Same guard, same disclosure as the Anthropic adapter.
+    const requested = toolChoice ?? 'auto';
+    const appliedToolChoice: 'required' | 'auto' =
+      requested === 'required' && anthropicRejectsForcedToolChoice(resolved) ? 'auto' : requested;
+    if (appliedToolChoice !== requested) {
+      console.warn(
+        `[openrouter] callTools: ${resolved} rejects forced tool_choice (HTTP 400); caller's 'required' downgraded to 'auto'`,
+      );
+    }
+
     const response = await this.apiCall(() =>
       client.chatCompletion({
         model: resolved,
         messages: this.sessionMessages,
         tools: orTools,
-        tool_choice: toolChoice ?? 'auto',
+        tool_choice: appliedToolChoice,
       }),
     );
 
@@ -1850,6 +2161,7 @@ export class OpenRouterAgent extends LLMAgent {
       toolCalls,
       inputTokens: response.usage.prompt_tokens,
       outputTokens: response.usage.completion_tokens,
+      appliedToolChoice,
     };
   }
 
@@ -1962,6 +2274,14 @@ export function createAgent(providerOrConfig: AgentConfig['provider'] | AgentCon
   const routeOverride =
     typeof providerOrConfig === 'string' ? undefined : providerOrConfig.routeOverride;
   const onRetry = typeof providerOrConfig === 'string' ? undefined : providerOrConfig.onRetry;
+  if (routeOverride?.claudeCodeLogin === true) {
+    if (provider !== 'anthropic') {
+      throw new Error(
+        `${provider}: the claude-code-login credential authenticates the Claude Code binary only — pick an anthropic route or supply a ${provider} API key`,
+      );
+    }
+    return new ClaudeCodeLoginAgent(routeOverride, onRetry);
+  }
   switch (provider) {
     case 'anthropic':
       return new AnthropicAgent(routeOverride, onRetry);
@@ -1988,11 +2308,26 @@ export type VisionProvider = 'anthropic' | 'google';
 export function createVisionAgent(
   config: AgentConfig & { provider: VisionProvider },
 ): LLMAgent & VisionAgent {
+  if (config.routeOverride?.claudeCodeLogin === true) {
+    if (config.provider !== 'anthropic') {
+      throw new Error(
+        `${config.provider}: the claude-code-login credential authenticates the Claude Code binary only — pick an anthropic route or supply a ${config.provider} API key`,
+      );
+    }
+    return new ClaudeCodeLoginAgent(config.routeOverride, config.onRetry);
+  }
   switch (config.provider) {
     case 'anthropic':
       return new AnthropicAgent(config.routeOverride, config.onRetry);
     case 'google':
       return new GoogleAgent(config.routeOverride, config.onRetry);
+    default: {
+      // ggui#1248 — refused by NAME, never answered with `undefined`: a caller that
+      // asserted its way past the type got back an agent it could not call, and the
+      // throw surfaced three frames later as "reading 'callVision'".
+      const unreachable: never = config.provider;
+      throw new Error(`createVisionAgent: provider '${String(unreachable)}' has no vision path (anthropic, google)`);
+    }
   }
 }
 

package/src/harness/llm-trace-sink.ts

@@ -32,7 +32,13 @@
 import type { LLMToolDef } from '../llm.js';
 
 /** Provider tag that produced the call. Mirrors {@link AgentConfig.provider}. */
-export type LlmTraceProvider = 'anthropic' | 'openai' | 'google' | 'openrouter';
+/**
+ * `claude-code-login` is the Anthropic model reached through the machine's
+ * own Claude Code login (ggui#1185) rather than a key — a trace reader can
+ * tell the two apart, which the routing vocabulary (`provider: 'anthropic'`)
+ * deliberately does not.
+ */
+export type LlmTraceProvider = 'anthropic' | 'claude-code-login' | 'openai' | 'google' | 'openrouter';
 
 /** Which `LLMAgent` method initiated the call. */
 export type LlmTraceKind =

package/src/harness/result-types.ts

@@ -49,11 +49,25 @@ export type ModelRoles = Partial<Record<ModelRole, string>>;
 // Generation Result
 // =============================================================================
 
+/**
+ * The same-exchange guard (ggui#404) ended this generation: the coding model
+ * made one identical tool exchange (same tool, same input, same result)
+ * `repeats` times, so the loop stopped instead of burning its remaining turns.
+ * Present ONLY when that guard ended the run — whether anything shipped is
+ * the compiled code's to say (the loop falls back to an earlier build).
+ */
+export interface SameExchangeBreak {
+  readonly tool: string;
+  readonly repeats: number;
+}
+
 export interface GenerationResult extends AdapterResult {
   /** Number of generation passes the harness performed */
   passesUsed: number;
   /** Three-tier evaluation result (tier 0 + LLM tier 1+2 + visual) */
   evalResult?: EvalResult;
+  /** Set only when the same-exchange guard ended the run (ggui#404); no key otherwise. */
+  sameExchangeBreak?: SameExchangeBreak;
   /** Whether background improvement should be spawned (auto-improve mode) */
   needsBackgroundImprovement?: boolean;
   /** Whether at least one commit passed the self-check (compile + type check + lint) */

package/src/harness/runtime.ts

@@ -91,6 +91,12 @@ export interface SingleComponentParams {
      * today's single screenshot at `viewport`.
      */
     canvases?: readonly CanvasClass[];
+    /**
+     * ggui#1195 — per-canvas viewport override for the in-loop round: the
+     * box the composer targeted (`rendering.viewport`) so the round judges
+     * the same box. See `VisualEvalConfig.canvasViewports`.
+     */
+    canvasViewports?: Partial<Readonly<Record<CanvasClass, { width: number; height: number }>>>;
     /**
      * The stylesheet the in-loop visual round renders under (a caller's
      * theme composed by `cssTokensForAppTheme`); absent = the design's