@ggui-ai/ui-gen 0.19.0 → 0.21.0

package/dist/harness/index.js

@@ -1,5 +1,5 @@
 import { LUCIDE_ICON_NAMES } from '@ggui-ai/design';
-import { resolveAppGadgets, listContractGadgets, HOOK_NAME_RE, APP_GENERATION_PROFILE_BOUNDS } from '@ggui-ai/protocol';
+import { resolveAppGadgets, listContractGadgets, HOOK_NAME_RE, anthropicRejectsForcedToolChoice, normalizeAnthropicModelId, isRecord, anthropicRejectsSamplingParams, APP_GENERATION_PROFILE_BOUNDS } from '@ggui-ai/protocol';
 import { createHash } from 'crypto';
 import { readFileSync } from 'fs';
 import { dirname, resolve } from 'path';
@@ -7,7 +7,7 @@ import { fileURLToPath } from 'url';
 import { consumedTokenManifest } from '@ggui-ai/design/themes';
 import ts from 'typescript';
 import Anthropic from '@anthropic-ai/sdk';
-import 'zod';
+import { z } from 'zod';
 
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
@@ -1478,7 +1478,7 @@ function generateBoilerplate(_userPrompt, contract, shellType, screen, composedS
     }
     const toolNote = tool ? ` (label "${label}", nextStep hint \u2192 ${tool})` : "";
     actionTypeAliases.push(
-      `/** Action payload: ${desc || label}${toolNote} */
+      `/** Action payload: ${desc || label}${toolNote} \u2014 control copy: "${label}" VERBATIM */
 type ${typeName} = ${tsType};`
     );
     const callSig = tsType === "void" ? "() => void \u2014 fire and forget" : `(data: ${tsType}) => void`;
@@ -1817,7 +1817,7 @@ Rules:
 1. All request-specific data \u2192 props with defaults. City names, tickers, user names, dates, counts.
 2. Layout and styling are universal. Colors, spacing, structure \u2014 these are the reusable part.
 3. Default values come from the current request \u2014 so the component renders correctly standalone.
-4. Copy comes from the props. NEVER invent display text the contract does not carry \u2014 no eyebrow / kicker / overline (a \`<Text caps>\` label), no helper line, no status text, no tagline. **Do NOT add a caps label above the heading** \u2014 not \`<Text caps>LET'S BEGIN</Text>\`, not \`WELCOME\`, not a section kicker like \`GETTING STARTED\` or \`OVERVIEW\` \u2014 UNLESS a prop supplies that exact text (\`<Text caps>{props.section}</Text>\`). When the request asks for a heading and a line, render the heading and the line and NOTHING above the heading. A heading's fallback is the request's own words, never a slogan of your own. Text the agent cannot change is chatter on every render, and a caps eyebrow you wrote is the most common form of it.
+4. Copy comes from the props. NEVER invent display text the contract does not carry \u2014 no eyebrow / kicker / overline (a \`<Text caps>\` label), no helper line, no status text, no tagline. **Do NOT add a caps label above the heading** \u2014 not \`<Text caps>LET'S BEGIN</Text>\`, not \`WELCOME\`, not a section kicker like \`GETTING STARTED\` or \`OVERVIEW\` \u2014 UNLESS a prop supplies that exact text (\`<Text caps>{props.section}</Text>\`). When the request asks for a heading and a line, render the heading and the line and NOTHING above the heading. A heading's fallback is the request's own words, never a slogan of your own. Text the agent cannot change is chatter on every render, and a caps eyebrow you wrote is the most common form of it. An action's control shows the contract's \`label\` VERBATIM \u2014 every character, including \`&\`, \`/\`, \`\u2013\` and quotes \u2014 never paraphrased, shortened or re-cased (\`"Confirm & Schedule"\` is not \`"Confirm Schedule"\`).
 5. Props interface must be typed and exported.`;
 var TERMINAL_ACTIONS = `## Actions the user means once
 
@@ -3227,6 +3227,25 @@ function createAnthropicClient(rawKey) {
   });
 }
 
+// src/adapters/claude/claude-code-login.ts
+var PROVIDER_KEY_ENV_NAMES = [
+  "ANTHROPIC_API_KEY",
+  "CLAUDE_API_KEY",
+  "ANTHROPIC_AUTH_TOKEN",
+  "ANTHROPIC_BASE_URL"
+];
+function stripProviderKeyEnv(env) {
+  const out = {};
+  const drop = new Set(PROVIDER_KEY_ENV_NAMES);
+  for (const [k, v] of Object.entries(env)) {
+    if (v !== void 0 && !drop.has(k)) out[k] = v;
+  }
+  return out;
+}
+function claudeCodeLoginQueryOptions() {
+  return { tools: [], settingSources: [] };
+}
+
 // src/adapters/provider-router.ts
 function getBedrockModelId(model) {
   const BEDROCK_MAP = {
@@ -3277,6 +3296,26 @@ function toJsonValue(value, path) {
   );
 }
 
+// src/adapters/openai/tokens.ts
+function splitOpenAiUsage(inputTokensInclCached, outputTokens, cachedTokens) {
+  return splitCacheInclusiveUsage(inputTokensInclCached, outputTokens, cachedTokens);
+}
+function splitCacheInclusiveUsage(inputTokensInclCached, outputTokens, cachedTokens) {
+  const cacheRead = Math.min(
+    Math.max(cachedTokens, 0),
+    Math.max(inputTokensInclCached, 0)
+  );
+  const nonCachedInput = Math.max(inputTokensInclCached, 0) - cacheRead;
+  return {
+    tokens: {
+      input: nonCachedInput,
+      output: outputTokens,
+      total: nonCachedInput + cacheRead + outputTokens
+    },
+    cacheReadTokens: cacheRead
+  };
+}
+
 // src/harness/llm-trace-sink.ts
 var activeSink2 = null;
 function setLlmTraceSink(sink) {
@@ -3300,6 +3339,271 @@ function newLlmTraceId() {
   return Date.now().toString(36) + Math.random().toString(36).slice(2, 10);
 }
 
+// src/adapters/claude/tool-bridge.ts
+var MCP_SERVER_NAME = "ggui";
+
+// src/harness/claude-code-login-query.ts
+var MCP_TOOL_PREFIX = `mcp__${MCP_SERVER_NAME}__`;
+function stripMcpToolPrefix(name) {
+  return name.startsWith(MCP_TOOL_PREFIX) ? name.slice(MCP_TOOL_PREFIX.length) : name;
+}
+var LOGIN_API_KEY_SOURCE = "none";
+var ClaudeCodeLoginAuthError = class extends Error {
+  apiKeySource;
+  constructor(apiKeySource) {
+    super(
+      `claude-code-login: the Claude Code binary authenticated from apiKeySource=${apiKeySource}, not from its login \u2014 a provider key reached the spawned process; the run was stopped before it spent a turn`
+    );
+    this.name = "ClaudeCodeLoginAuthError";
+    this.apiKeySource = apiKeySource;
+  }
+};
+var ClaudeCodeLoginResultError = class extends Error {
+  subtype;
+  errors;
+  status;
+  constructor(subtype, errors, status) {
+    super(
+      `claude-code-login: query() ended with ${subtype}` + (status !== void 0 ? ` (api status ${status})` : "") + `: ${errors.length > 0 ? errors.join("; ") : "no detail from the binary"}`
+    );
+    this.name = "ClaudeCodeLoginResultError";
+    this.subtype = subtype;
+    this.errors = errors;
+    this.status = status;
+  }
+};
+function createDenyingIntercept(intercepted) {
+  return async (toolName, input) => {
+    intercepted.push({ name: toolName, input });
+    return {
+      behavior: "deny",
+      message: "ggui executes tools in its harness; the binary only proposes them."
+    };
+  };
+}
+async function* imageUserMessage(text, image) {
+  const message = {
+    role: "user",
+    content: [
+      {
+        type: "image",
+        source: { type: "base64", media_type: image.mediaType, data: image.base64 }
+      },
+      { type: "text", text }
+    ]
+  };
+  yield { type: "user", message, parent_tool_use_id: null };
+}
+function buildLoginQueryOptions(params) {
+  return {
+    model: params.model,
+    systemPrompt: params.systemPrompt,
+    maxTurns: 1,
+    thinking: { type: "disabled" },
+    env: stripProviderKeyEnv(params.env ?? process.env),
+    ...claudeCodeLoginQueryOptions(),
+    ...params.tools !== void 0 ? {
+      mcpServers: { [MCP_SERVER_NAME]: params.tools.server },
+      canUseTool: params.tools.canUseTool
+    } : {}
+  };
+}
+var JSON_SCHEMA_TYPES = [
+  "object",
+  "array",
+  "string",
+  "number",
+  "boolean",
+  "null",
+  "integer"
+];
+function isJsonSchemaType(value) {
+  return typeof value === "string" && JSON_SCHEMA_TYPES.includes(value);
+}
+function isJsonObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function schemaAt(value, path) {
+  if (typeof value === "boolean") return value;
+  if (!isJsonObject(value)) {
+    throw new Error(
+      `claude-code-login: ${path} must be a JSON-Schema object or boolean, got ${JSON.stringify(value)}`
+    );
+  }
+  return toZodJsonSchema(value, path);
+}
+function toZodJsonSchema(parameters, path = "parameters") {
+  const out = {};
+  for (const [key, value] of Object.entries(parameters)) {
+    if (value === void 0) continue;
+    switch (key) {
+      case "type": {
+        if (!isJsonSchemaType(value)) {
+          throw new Error(
+            `claude-code-login: ${path}.type must be one of ${JSON_SCHEMA_TYPES.join("|")}, got ${JSON.stringify(value)}`
+          );
+        }
+        out.type = value;
+        break;
+      }
+      case "properties":
+      case "patternProperties":
+      case "$defs": {
+        if (!isJsonObject(value))
+          throw new Error(`claude-code-login: ${path}.${key} must be an object`);
+        const record = {};
+        for (const [name, sub] of Object.entries(value)) {
+          if (sub === void 0) continue;
+          record[name] = schemaAt(sub, `${path}.${key}.${name}`);
+        }
+        if (key === "$defs") {
+          const defs = {};
+          for (const [name, sub] of Object.entries(record)) {
+            if (typeof sub === "boolean")
+              throw new Error(`claude-code-login: ${path}.$defs.${name} must be an object`);
+            defs[name] = sub;
+          }
+          out.$defs = defs;
+        } else {
+          out[key] = record;
+        }
+        break;
+      }
+      case "items": {
+        out.items = Array.isArray(value) ? value.map((sub, i) => schemaAt(sub, `${path}.items[${i}]`)) : schemaAt(value, `${path}.items`);
+        break;
+      }
+      case "additionalProperties":
+      case "not": {
+        out[key] = schemaAt(value, `${path}.${key}`);
+        break;
+      }
+      case "anyOf":
+      case "oneOf":
+      case "allOf": {
+        if (!Array.isArray(value))
+          throw new Error(`claude-code-login: ${path}.${key} must be an array`);
+        out[key] = value.map((sub, i) => {
+          const s = schemaAt(sub, `${path}.${key}[${i}]`);
+          if (typeof s === "boolean")
+            throw new Error(`claude-code-login: ${path}.${key}[${i}] must be an object`);
+          return s;
+        });
+        break;
+      }
+      case "required": {
+        if (!Array.isArray(value) || !value.every((v) => typeof v === "string")) {
+          throw new Error(`claude-code-login: ${path}.required must be an array of strings`);
+        }
+        out.required = value;
+        break;
+      }
+      case "enum": {
+        if (!Array.isArray(value) || !value.every(
+          (v) => v === null || typeof v === "string" || typeof v === "number" || typeof v === "boolean"
+        )) {
+          throw new Error(`claude-code-login: ${path}.enum must be an array of primitives`);
+        }
+        out.enum = value;
+        break;
+      }
+      default:
+        out[key] = value;
+    }
+  }
+  return out;
+}
+function createLoginToolServer(sdk, tools) {
+  const sdkTools = tools.map((def) => {
+    const schema = z.fromJSONSchema(toZodJsonSchema(def.parameters, `${def.name}.parameters`));
+    if (!(schema instanceof z.ZodObject)) {
+      throw new Error(
+        `claude-code-login: tool ${def.name}'s parameters must be a JSON-Schema object`
+      );
+    }
+    return sdk.tool(def.name, def.description, schema.shape, async () => {
+      throw new Error(
+        `claude-code-login: the binary tried to execute ${def.name} \u2014 ggui's tools are proposed to the harness and never run in the binary (the intercept denies every call)`
+      );
+    });
+  });
+  return sdk.createSdkMcpServer({ name: MCP_SERVER_NAME, version: "1.0.0", tools: sdkTools });
+}
+var LOGIN_REQUIRED_TOOL_INSTRUCTION = "Respond only with tool calls: do not write any text before, between or after them. Text outside a tool call is not read.";
+function describeCalls(calls) {
+  return JSON.stringify(calls.map((c) => ({ name: stripMcpToolPrefix(c.name), input: c.input })));
+}
+async function collectLoginTurn(stream, opts) {
+  let init;
+  const toolCalls = [];
+  let text = "";
+  let thinkingBlocks = 0;
+  let result;
+  try {
+    for await (const msg of stream) {
+      if (msg.type === "system" && msg.subtype === "init") {
+        const measured = msg;
+        init = measured;
+        opts.log(
+          `[claude-code-login] apiKeySource=${measured.apiKeySource} claude_code_version=${measured.claude_code_version} model=${measured.model}`
+        );
+        if (measured.apiKeySource !== LOGIN_API_KEY_SOURCE) {
+          throw new ClaudeCodeLoginAuthError(measured.apiKeySource);
+        }
+      } else if (msg.type === "assistant") {
+        for (const block of msg.message.content) {
+          if (block.type === "tool_use") {
+            toolCalls.push({
+              id: block.id,
+              name: stripMcpToolPrefix(block.name),
+              input: isRecord(block.input) ? toolArgsToJsonObject(block.input) : {}
+            });
+          } else if (block.type === "text") {
+            text += block.text;
+          } else if (block.type === "thinking" || block.type === "redacted_thinking") {
+            thinkingBlocks += 1;
+          }
+        }
+      } else if (msg.type === "result") {
+        result = msg;
+      }
+    }
+  } catch (e) {
+    if (result === void 0) throw e;
+    opts.log(
+      `[claude-code-login] query() threw after its result message \u2014 the result decides (${e instanceof Error ? e.message : String(e)})`
+    );
+  }
+  if (result === void 0) {
+    throw new Error("claude-code-login: query() ended without a result message");
+  }
+  const usage = result.usage;
+  const thinkingTokens = usage.output_tokens_details?.thinking_tokens ?? 0;
+  opts.log(
+    `[claude-code-login] usage kind=${opts.kind} input=${usage.input_tokens} output=${usage.output_tokens} cacheRead=${usage.cache_read_input_tokens} cacheCreated=${usage.cache_creation_input_tokens} thinking=${thinkingTokens} thinkingBlocks=${thinkingBlocks} textChars=${text.length} toolCalls=${toolCalls.length} stop=${result.stop_reason ?? "none"} choice=${opts.choice}`
+  );
+  const streamSaw = describeCalls(toolCalls);
+  const interceptSaw = describeCalls(opts.intercepted);
+  if (streamSaw !== interceptSaw) {
+    opts.warn(
+      `[claude-code-login] intercept/stream disagreement \u2014 the stream's blocks win. intercepted=${interceptSaw} stream=${streamSaw}`
+    );
+  }
+  if (result.subtype === "success") {
+    if (result.is_error) {
+      throw new ClaudeCodeLoginResultError(
+        "success",
+        [result.result],
+        result.api_error_status ?? void 0
+      );
+    }
+  } else if (result.subtype !== "error_max_turns") {
+    const failed = result;
+    throw new ClaudeCodeLoginResultError(failed.subtype, failed.errors, void 0);
+  }
+  return { init, toolCalls, text, result };
+}
+
 // src/harness/llm-router.ts
 function addStrictSchemaConstraints(schema) {
   const result = { ...schema };
@@ -3494,17 +3798,6 @@ var LLMAgent = class {
     }
   }
 };
-function normalizeAnthropicModelId(model) {
-  return model.replace(/^anthropic\//, "").replace(/^(?:[a-z]{2}\.)?anthropic\./, "");
-}
-function anthropicRejectsSamplingParams(model) {
-  return /^claude-(?:opus-4-7|opus-5|sonnet-5|fable-5)(?:-|$)/.test(
-    normalizeAnthropicModelId(model)
-  );
-}
-function anthropicRejectsForcedToolChoice(model) {
-  return /^claude-fable-5-1(?:-|$)/.test(normalizeAnthropicModelId(model));
-}
 function resolveAnthropicSampling(model, temperature) {
   if (temperature === void 0) {
     return { request: {}, applied: { temperature: "provider-default" } };
@@ -3880,6 +4173,200 @@ var AnthropicAgent = class extends LLMAgent {
     }
   }
 };
+var ClaudeCodeLoginAgent = class extends LLMAgent {
+  provider = "anthropic";
+  resolveModel(model) {
+    return model.startsWith("anthropic/") ? model.slice("anthropic/".length) : model;
+  }
+  async createClient() {
+    const { query, tool, createSdkMcpServer } = await import('@anthropic-ai/claude-agent-sdk');
+    return { query, tool, createSdkMcpServer };
+  }
+  async callText(model, systemPrompt, userPrompt, _maxTokens, _temperature) {
+    const sdk = await this.getClient();
+    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, systemPrompt, userPrompt, image, _maxTokens) {
+    const sdk = await this.getClient();
+    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, systemPrompt, userPrompt, tools, toolChoice = "required", _scopedTools) {
+    const sdk = await this.getClient();
+    const traceId = newLlmTraceId();
+    const startedAt = Date.now();
+    const resolvedModel = this.resolveModel(model);
+    const sentUserPrompt = toolChoice === "required" ? `${userPrompt}
+
+${LOGIN_REQUIRED_TOOL_INSTRUCTION}` : userPrompt;
+    try {
+      const turn = await this.apiCall(() => {
+        const intercepted = [];
+        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 = 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() {
+    throw new Error(
+      "claude-code-login: callWithTools (an in-client agentic loop) is not part of the login client \u2014 ggui's harness runs the loop through callTools"
+    );
+  }
+};
 var OpenAIAgent = class extends LLMAgent {
   provider = "openai";
   resolveModel(model) {
@@ -3908,10 +4395,15 @@ var OpenAIAgent = class extends LLMAgent {
         }
       }
     }
+    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" }
     };
   }
@@ -3950,14 +4442,20 @@ var OpenAIAgent = class extends LLMAgent {
     const functionCalls = response.output.filter(
       (o) => o.type === "function_call"
     );
+    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 ?? "{}")
       })),
-      inputTokens: response.usage?.input_tokens ?? 0,
-      outputTokens: response.usage?.output_tokens ?? 0
+      inputTokens: toolsUsage.tokens.input,
+      outputTokens: toolsUsage.tokens.output,
+      cacheReadTokens: toolsUsage.cacheReadTokens
     };
   }
   // Pending tool results — stored by sendToolResult, consumed by next callTools
@@ -3984,6 +4482,7 @@ var OpenAIAgent = class extends LLMAgent {
     ];
     let totalIn = 0;
     let totalOut = 0;
+    let totalCacheRead = 0;
     let allText = "";
     for (let turn = 0; turn < maxTurns; turn++) {
       const response = await this.apiCall(
@@ -3994,8 +4493,14 @@ var OpenAIAgent = class extends LLMAgent {
           tools: openaiTools
         })
       );
-      totalIn += response.usage?.input_tokens ?? 0;
-      totalOut += response.usage?.output_tokens ?? 0;
+      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.type === "function_call"
       );
@@ -4026,6 +4531,7 @@ var OpenAIAgent = class extends LLMAgent {
       text: allText,
       inputTokens: totalIn,
       outputTokens: totalOut,
+      cacheReadTokens: totalCacheRead,
       turnsUsed: input.length
     };
   }
@@ -4051,6 +4557,10 @@ function functionCallSteps(interaction) {
 function toUserInputStep(text) {
   return { type: "user_input", content: [{ type: "text", text }] };
 }
+function googleInteractionUsage(usage) {
+  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 };
+}
 var GoogleAgent = class extends LLMAgent {
   provider = "google";
   resolveModel(model) {
@@ -4080,8 +4590,9 @@ var GoogleAgent = class 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" }
     };
   }
@@ -4113,7 +4624,8 @@ var GoogleAgent = class extends LLMAgent {
       const usage = response.usageMetadata;
       const result = {
         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
       };
       const endedAt = Date.now();
@@ -4257,8 +4769,8 @@ var GoogleAgent = class 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)
     };
   }
   // Pending tool results — stored by sendToolResult, consumed by next callTools
@@ -4282,6 +4794,7 @@ var GoogleAgent = class extends LLMAgent {
     }));
     let totalIn = 0;
     let totalOut = 0;
+    let totalCacheRead = 0;
     let allText = "";
     let turnsUsed = 0;
     let interaction = await this.apiCall(
@@ -4295,8 +4808,10 @@ var GoogleAgent = class extends LLMAgent {
     for (let turn = 0; turn < maxTurns; turn++) {
       turnsUsed = turn + 1;
       if (interaction.usage) {
-        totalIn += interaction.usage.total_input_tokens ?? 0;
-        totalOut += interaction.usage.total_output_tokens ?? 0;
+        const turnUsage = googleInteractionUsage(interaction.usage);
+        totalIn += turnUsage.inputTokens;
+        totalOut += turnUsage.outputTokens;
+        totalCacheRead += turnUsage.cacheReadTokens;
       }
       allText += interactionText(interaction);
       const fnCalls = functionCallSteps(interaction);
@@ -4334,6 +4849,7 @@ var GoogleAgent = class extends LLMAgent {
       text: allText,
       inputTokens: totalIn,
       outputTokens: totalOut,
+      cacheReadTokens: totalCacheRead,
       turnsUsed
     };
   }
@@ -4389,12 +4905,19 @@ var OpenRouterAgent = class extends LLMAgent {
       this.sessionMessages.push({ role: "system", content: systemPrompt });
     }
     this.sessionMessages.push({ role: "user", content: userPrompt });
+    const requested = toolChoice ?? "auto";
+    const appliedToolChoice = 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
       })
     );
     const choice = response.choices[0];
@@ -4413,7 +4936,8 @@ var OpenRouterAgent = class extends LLMAgent {
     return {
       toolCalls,
       inputTokens: response.usage.prompt_tokens,
-      outputTokens: response.usage.completion_tokens
+      outputTokens: response.usage.completion_tokens,
+      appliedToolChoice
     };
   }
   async sendToolResult(results) {
@@ -4484,6 +5008,14 @@ function createAgent(providerOrConfig) {
   const provider = typeof providerOrConfig === "string" ? providerOrConfig : providerOrConfig.provider;
   const routeOverride = typeof providerOrConfig === "string" ? void 0 : providerOrConfig.routeOverride;
   const onRetry = typeof providerOrConfig === "string" ? void 0 : providerOrConfig.onRetry;
+  if (routeOverride?.claudeCodeLogin === true) {
+    if (provider !== "anthropic") {
+      throw new Error(
+        `${provider}: the claude-code-login credential authenticates the Claude Code binary only \u2014 pick an anthropic route or supply a ${provider} API key`
+      );
+    }
+    return new ClaudeCodeLoginAgent(routeOverride, onRetry);
+  }
   switch (provider) {
     case "anthropic":
       return new AnthropicAgent(routeOverride, onRetry);