@ggui-ai/ui-gen 0.28.0 → 0.29.0

package/src/harness/check/runtime-render/render-check.ts

@@ -21,6 +21,20 @@ import type { DataContract, JsonObject, PropsSpec } from "@ggui-ai/protocol";
 import { HOOK_NAME_RE, listContractGadgets } from "@ggui-ai/protocol";
 import { createProbe, createProbeWireConfig, type ActionFiredEvent, type Probe } from "./probe.js";
 import { loadComponent } from "./load-component.js";
+import { ASSET_SHIM_FOR_SPECIFIER } from "@ggui-ai/design/rendering";
+
+/**
+ * ggui#1934 — the design specifiers production's import rewrite serves, each paired with the module
+ * that backs it here. `templates` is backed by the barrel: the renderer's templates shim serves every
+ * layer (compositions, then primitives and components). `app-components` is the operator's own registry, never a design-package module, so it is not
+ * pre-resolved; a card importing it fails with the sandbox's "not available" reason.
+ */
+export function sandboxDesignModules(): ReadonlyArray<readonly [specifier: string, moduleId: string]> {
+  return Object.keys(ASSET_SHIM_FOR_SPECIFIER)
+    .filter((id) => id === "@ggui-ai/design" || id.startsWith("@ggui-ai/design/"))
+    .filter((id) => id !== "@ggui-ai/design/app-components")
+    .map((id) => [id, id === "@ggui-ai/design/templates" ? "@ggui-ai/design" : id] as const);
+}
 import { findWiring, type WiringDetection } from "./find-wiring.js";
 import { installProductionActShim } from "./production-act-shim.js";
 // All happy-dom / RTL / user-event narrowing flows through the typed
@@ -290,27 +304,12 @@ export async function runRenderCheckInProcess(
       "@ggui-ai/wire": Wire,
     };
 
-    // Pre-load the @ggui-ai/design specifiers the boilerplate may import.
-    // Post-D1, generated code imports the single bare `@ggui-ai/design`
-    // barrel — that MUST be pre-resolved here: the package is ESM-only
-    // with no `require` export condition, so `loadComponent`'s
-    // `createRequire` fallback cannot load it (it would crash:fail the
-    // render check). The subpaths stay for any legacy/first-party code.
-    // Per-specifier failures are swallowed — the sandbox throws its own
-    // clear error if the component actually needs a missing one.
-    const designSpecifiers = [
-      "@ggui-ai/design",
-      "@ggui-ai/design/primitives",
-      "@ggui-ai/design/components",
-      "@ggui-ai/design/compositions",
-      "@ggui-ai/design/interact",
-    ];
-    for (const id of designSpecifiers) {
-      try {
-        moduleResolutions[id] = await import(id);
-      } catch {
-        /* skip — sandbox will report a clear error if the component imports it */
-      }
+    // Pre-load every @ggui-ai/design specifier production serves (ggui#1934). The package is ESM-only
+    // with no `require` export condition, so `loadComponent`'s `createRequire` fallback can load none
+    // of them: a specifier missing here fails the probe while the served card renders. The list is
+    // the renderer's own map, so a subpath production starts serving is served here too.
+    for (const [id, moduleId] of sandboxDesignModules()) {
+      moduleResolutions[id] = await import(moduleId);
     }
 
     // Pre-load `@ggui-ai/gadgets` for components that declare

package/src/harness/claude-agent-sdk-loader.ts

@@ -0,0 +1,93 @@
+/**
+ * The one runtime load of `@anthropic-ai/claude-agent-sdk` (ggui#1951).
+ *
+ * The SDK is an OPTIONAL peer of this package, not a dependency. Its
+ * per-platform native binary is about 300 MB, and only the Claude Code
+ * login route (`routeOverride.claudeCodeLogin`, `ggui serve
+ * --local-cli-login`), the `sdk`-mode Claude adapter and the
+ * `./evaluation` loop run it. A plain install therefore does not carry
+ * it, and every one of those paths loads it through
+ * {@link loadClaudeAgentSdk}: a missing SDK fails with one
+ * {@link ClaudeAgentSdkMissingError} that names the install line for
+ * each way of installing ggui, and every other failure keeps its own
+ * shape.
+ *
+ * `preloadProviderSdks` (in `./llm-router.ts`) imports the SDK directly
+ * on purpose: it reports a missing SDK in its `missing` list and never
+ * throws.
+ */
+
+/** The package specifier, as it is imported and installed. */
+export const CLAUDE_AGENT_SDK_SPECIFIER = '@anthropic-ai/claude-agent-sdk';
+
+/**
+ * The exact version this package's `peerDependencies` names. The install
+ * lines in {@link ClaudeAgentSdkMissingError} use it; a test pins it to
+ * `package.json`.
+ */
+export const CLAUDE_AGENT_SDK_VERSION = '0.3.229';
+
+export type ClaudeAgentSdk = typeof import('@anthropic-ai/claude-agent-sdk');
+
+/** The SDK is not installed where this package can import it. */
+export class ClaudeAgentSdkMissingError extends Error {
+  constructor(cause: Error) {
+    const pin = `${CLAUDE_AGENT_SDK_SPECIFIER}@${CLAUDE_AGENT_SDK_VERSION}`;
+    super(
+      `${CLAUDE_AGENT_SDK_SPECIFIER} is not installed. It is an optional peer of @ggui-ai/ui-gen, ` +
+        `needed only to generate with the Claude Code login (and by the Agent SDK adapter and evaluation loop). ` +
+        `Install it beside ggui:\n` +
+        `  npm install ${pin}            (ggui installed in a project)\n` +
+        `  npm install -g ${pin}         (ggui installed with -g)\n` +
+        `  npx -p @ggui-ai/cli -p ${pin} ggui serve --local-cli-login   (ggui run with npx)`,
+      { cause },
+    );
+    this.name = 'ClaudeAgentSdkMissingError';
+  }
+}
+
+function isMissingSdk(err: unknown): err is Error {
+  if (!(err instanceof Error)) return false;
+  const code: unknown = Reflect.get(err, 'code');
+  if (code !== 'ERR_MODULE_NOT_FOUND' && code !== 'MODULE_NOT_FOUND') return false;
+  // A package the SDK itself imports can be missing too; that failure names
+  // its own package and is not this one.
+  return err.message.includes(`'${CLAUDE_AGENT_SDK_SPECIFIER}'`);
+}
+
+function missingOrRethrow(err: unknown): never {
+  if (isMissingSdk(err)) throw new ClaudeAgentSdkMissingError(err);
+  throw err;
+}
+
+/**
+ * Import the Claude Agent SDK. A missing SDK rejects with
+ * {@link ClaudeAgentSdkMissingError}; any other failure rejects unchanged.
+ * `importer` is for tests. Package-internal: its return type names the
+ * SDK's types, which a consumer without the SDK cannot resolve.
+ */
+export async function loadClaudeAgentSdk(
+  importer: () => Promise<ClaudeAgentSdk> = () => import('@anthropic-ai/claude-agent-sdk'),
+): Promise<ClaudeAgentSdk> {
+  try {
+    return await importer();
+  } catch (err) {
+    return missingOrRethrow(err);
+  }
+}
+
+/**
+ * Check that the Claude Agent SDK loads, with the same errors as
+ * {@link loadClaudeAgentSdk}, for a host that wants to say so at boot
+ * (`ggui serve --local-cli-login`). Its signature names none of the SDK's
+ * types, so the package's main entry can export it. `importer` is for tests.
+ */
+export async function ensureClaudeAgentSdk(
+  importer: () => Promise<unknown> = () => import('@anthropic-ai/claude-agent-sdk'),
+): Promise<void> {
+  try {
+    await importer();
+  } catch (err) {
+    missingOrRethrow(err);
+  }
+}

package/src/harness/claude-code-login-query.ts

@@ -39,7 +39,7 @@ import type {
 } from "@anthropic-ai/claude-agent-sdk";
 import type { MessageParam } from "@anthropic-ai/sdk/resources";
 import { isRecord, type JsonObject, type JsonValue } from "@ggui-ai/protocol";
-import { z } from "zod";
+import * as z from "zod";
 import type { LLMToolDef } from "../llm.js";
 import {
   claudeCodeLoginQueryOptions,

package/src/harness/coding/generate-task-runner.ts

@@ -301,6 +301,7 @@ export function createGenerateTaskRunner(input: CreateGenerateRunnerInput): Task
           // place (fingerprint + cooldown + forceEscape +
           // scopedEscapeUsedCount).
           dupeBreak: session.dupeBreak,
+          ...(params.onCodingTurnPrompt !== undefined ? { onPrompt: params.onCodingTurnPrompt } : {}),
         },
         {
           turnsUsed: telemetry.turnsUsed,

package/src/harness/coding/run-coding-turn.ts

@@ -189,6 +189,8 @@ export interface CodingTurnContext {
    * `breakDuplicatePatch` policy flag gates whether this turn reads it.
    */
   readonly dupeBreak?: import("./dupe-break.js").DupeBreakState;
+  /** Told the system prompt and user message this turn hands the coding agent, just before the call. */
+  readonly onPrompt?: (sent: import("../runtime.js").CodingTurnPrompt) => void;
 }
 
 /**
@@ -544,6 +546,7 @@ ${closingInstruction}`;
     planFirstTurn,
     codeFormat,
   );
+  ctx.onPrompt?.({ turn: turnsUsed, systemPrompt, userPrompt });
   const llmStart = Date.now();
   const response = await codingAgent.callTools(
     codingModel,

package/src/harness/coding/run-eval-round.ts

@@ -1462,6 +1462,15 @@ export async function runEvalRound(
     console.log(
       `[simple] eval round ${evalRoundsUsed}: ${allActionable.length} issues (${blocking.length} fail, ${warns.length} warn) → feeding back to coding loop`,
     );
+    // ggui#1981 — one line per deterministic (tier-0) finding on a feedback round, and whether it took one of the
+    // MAX_FEEDBACK_ISSUES slots, so a bench read can count a warn that displaced a repair instead of inferring it.
+    for (const issue of evalResult.issues) {
+      if (issue.tier !== 0 || (issue.result !== "fail" && issue.result !== "warn")) continue;
+      console.log(
+        `[simple] eval round ${evalRoundsUsed}: tier0 ${issue.result} ${issue.subcategory ?? issue.category} ` +
+          `delivered=${allActionable.includes(issue)}`,
+      );
+    }
     // ggui#1542 — WHY this round continued, for a caller that set `actOn`: the manipulation check of an experiment on
     // the setting reads this line. `visual majors acted` counts the judge's majors only (fit's are never acted on).
     if (visualEvaluation?.actOn !== undefined) {

package/src/harness/llm-router.ts

@@ -36,6 +36,7 @@ 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 { loadClaudeAgentSdk } from './claude-agent-sdk-loader.js';
 import {
   emitLlmTraceEvent,
   newLlmTraceId,
@@ -252,6 +253,8 @@ export interface LLMWithToolsResponse {
   turnsUsed: number;
   /** Prompt-cache reads summed over the loop's turns, when the provider reports them (absent = unreported, never zero). */
   cacheReadTokens?: number;
+  /** ggui#1957 — prompt-cache writes summed over the loop's turns, when the provider reports them (absent = unreported). */
+  cacheCreationTokens?: number;
 }
 
 export interface LLMToolCall {
@@ -1169,7 +1172,7 @@ export class ClaudeCodeLoginAgent extends LLMAgent implements VisionAgent {
   }
 
   protected async createClient(): Promise<LoginSdk> {
-    const { query, tool, createSdkMcpServer } = await import('@anthropic-ai/claude-agent-sdk');
+    const { query, tool, createSdkMcpServer } = await loadClaudeAgentSdk();
     return { query, tool, createSdkMcpServer };
   }
 
@@ -1428,11 +1431,14 @@ 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.
+    // dropped here rather than double-counted. Cache writes (ggui#1957) stay
+    // inside `inputTokens` on this path for the same reason: with no
+    // cache-write term to carry them, subtracting them would drop them.
     const textUsage = splitOpenAiUsage(
       response.usage?.input_tokens ?? 0,
       response.usage?.output_tokens ?? 0,
       response.usage?.input_tokens_details?.cached_tokens ?? 0,
+      0,
     );
     return {
       text,
@@ -1509,6 +1515,7 @@ export class OpenAIAgent extends LLMAgent {
       response.usage?.input_tokens ?? 0,
       response.usage?.output_tokens ?? 0,
       response.usage?.input_tokens_details?.cached_tokens ?? 0,
+      response.usage?.input_tokens_details?.cache_write_tokens ?? 0,
     );
     return {
       toolCalls: functionCalls.map((fc) => ({
@@ -1519,6 +1526,7 @@ export class OpenAIAgent extends LLMAgent {
       inputTokens: toolsUsage.tokens.input,
       outputTokens: toolsUsage.tokens.output,
       cacheReadTokens: toolsUsage.cacheReadTokens,
+      cacheCreationTokens: toolsUsage.cacheCreationTokens,
     };
   }
 
@@ -1558,6 +1566,7 @@ export class OpenAIAgent extends LLMAgent {
     let totalIn = 0;
     let totalOut = 0;
     let totalCacheRead = 0;
+    let totalCacheWrite = 0;
     let allText = '';
 
     for (let turn = 0; turn < maxTurns; turn++) {
@@ -1574,10 +1583,12 @@ export class OpenAIAgent extends LLMAgent {
         response.usage?.input_tokens ?? 0,
         response.usage?.output_tokens ?? 0,
         response.usage?.input_tokens_details?.cached_tokens ?? 0,
+        response.usage?.input_tokens_details?.cache_write_tokens ?? 0,
       );
       totalIn += turnUsage.tokens.input;
       totalOut += turnUsage.tokens.output;
       totalCacheRead += turnUsage.cacheReadTokens;
+      totalCacheWrite += turnUsage.cacheCreationTokens;
 
       const functionCalls = response.output.filter(
         (o): o is ResponseFunctionToolCall => o.type === 'function_call',
@@ -1615,6 +1626,7 @@ export class OpenAIAgent extends LLMAgent {
       inputTokens: totalIn,
       outputTokens: totalOut,
       cacheReadTokens: totalCacheRead,
+      cacheCreationTokens: totalCacheWrite,
       turnsUsed: input.length,
     };
   }
@@ -2435,3 +2447,39 @@ export async function callLLMWithTools(
   return result;
 }
 
+
+/** What {@link preloadProviderSdks} loaded, and what it could not, by specifier. */
+export interface ProviderSdkPreload {
+  readonly ms: number;
+  readonly loaded: readonly string[];
+  readonly missing: ReadonlyArray<{ readonly specifier: string; readonly reason: string }>;
+}
+
+/**
+ * ggui#1769 — load the provider SDKs this router imports lazily, once, before a long-lived host takes traffic.
+ *
+ * Each agent imports its SDK on first use. Cold, `@anthropic-ai/claude-agent-sdk` alone compiles for ~0.9 s
+ * synchronously, so a host's first generation stalls the event loop for that long mid-request. A host awaits
+ * this at boot instead; afterwards every `import()` below resolves from the module cache.
+ *
+ * Never rejects: an SDK that is not installed (an optional provider a deployment does not use) is reported in
+ * `missing` with its reason, and its agent fails on first use exactly as it would without the preload.
+ */
+export async function preloadProviderSdks(): Promise<ProviderSdkPreload> {
+  const start = Date.now();
+  const attempts: ReadonlyArray<readonly [string, () => Promise<object>]> = [
+    ['@anthropic-ai/claude-agent-sdk', () => import('@anthropic-ai/claude-agent-sdk')],
+    ['openai', () => import('openai')],
+    ['@google/genai', () => import('@google/genai')],
+    ['@anthropic-ai/bedrock-sdk', () => import('@anthropic-ai/bedrock-sdk')],
+  ];
+  const settled = await Promise.allSettled(attempts.map(([, load]) => load()));
+  const loaded: string[] = [];
+  const missing: { specifier: string; reason: string }[] = [];
+  settled.forEach((r, i) => {
+    const specifier = attempts[i]?.[0] ?? '';
+    if (r.status === 'fulfilled') loaded.push(specifier);
+    else missing.push({ specifier, reason: r.reason instanceof Error ? r.reason.message : String(r.reason) });
+  });
+  return { ms: Date.now() - start, loaded, missing };
+}

package/src/harness/runtime.ts

@@ -66,6 +66,18 @@ export interface AgentSpec {
   onRetry?: AgentConfig["onRetry"];
 }
 
+/**
+ * One coding turn's prompt, exactly as handed to the coding agent's tool call: the system prompt (after every
+ * policy swap, e.g. the condensed component reference) and the turn's user message. Lets a caller audit the
+ * prompt a generation actually sent rather than the templates it was built from.
+ */
+export interface CodingTurnPrompt {
+  /** 1-indexed coding turn. */
+  readonly turn: number;
+  readonly systemPrompt: string;
+  readonly userPrompt: string;
+}
+
 export interface SingleComponentParams {
   userPrompt: string;
   contract?: DataContract;
@@ -119,6 +131,11 @@ export interface SingleComponentParams {
     actOn?: "critical" | "major";
   };
   onProgress?: (event: unknown) => void;
+  /**
+   * Observer of what each coding turn sends the model — see {@link CodingTurnPrompt}. Read-only: the generation is
+   * byte-identical with or without it. Absent = nothing reported.
+   */
+  onCodingTurnPrompt?: (sent: CodingTurnPrompt) => void;
   onInitialResult?: (result: {
     componentCode: string;
     sourceCode?: string;

package/src/index.ts

@@ -22,6 +22,15 @@ export {
 export type { CreateUiGeneratorOptions } from './create-ui-generator.js';
 export type { RuntimeRenderProbeConfig } from './harness/check/runtime-render/adapter.js';
 export type { ProviderRetryInfo } from './harness/llm-router.js';
+export { preloadProviderSdks, type ProviderSdkPreload } from './harness/llm-router.js';
+// ggui#1951: the Agent SDK is an optional peer. Only what names none of
+// its types is exported here, so this entry type-checks without it.
+export {
+  CLAUDE_AGENT_SDK_SPECIFIER,
+  CLAUDE_AGENT_SDK_VERSION,
+  ClaudeAgentSdkMissingError,
+  ensureClaudeAgentSdk,
+} from './harness/claude-agent-sdk-loader.js';
 export type { GenerationResult, SameExchangeBreak, SameFailureBreak } from './harness/result-types.js';
 // The build identity a stamp outside this package can name: the same
 // digests `createUiGenerator` puts on every result's `metadata.build`, for

package/src/providers/anthropic-tool-call.ts

@@ -0,0 +1,263 @@
+/**
+ * The one Anthropic structured call: a single `/v1/messages` request
+ * that asks for one tool call and returns that tool's input.
+ *
+ * Every structured caller that speaks to Anthropic goes through
+ * {@link anthropicToolCall}, so the request shape and the failure
+ * names live in one place (ggui#1271): the negotiator's LLM seam in
+ * `@ggui-ai/mcp-server` (rerank judge + contract synthesizer), the
+ * judge the live match probes drive in `@ggui-ai/mcp-server-handlers`,
+ * and the negotiator's dev benches.
+ *
+ * It lives here because every production caller already depends on
+ * `@ggui-ai/ui-gen`. The day a production caller lives in a package that
+ * does not (`@ggui-ai/negotiator`, `@ggui-ai/protocol`), the home becomes
+ * `@ggui-ai/mcp-server-core`, which every one of them reaches.
+ *
+ * It is a standalone function rather than a `ProviderAdapter`
+ * method on purpose. Adapters return a result union and never throw;
+ * every structured caller here wants the throw, because its consumers
+ * (the rerank judge, the synthesizer) already collapse a throw to
+ * their null-decision fallback and carry the message into their
+ * reason. A transport failure keeps its own type: a network failure
+ * rejects with `fetch`'s `TypeError`, an abort with the signal's
+ * `AbortError`, and a 2xx body that is not JSON with `SyntaxError`.
+ *
+ * Two request shapes, chosen by the shared model rule
+ * (`@ggui-ai/protocol` `anthropicRejectsForcedToolChoice`, the same list
+ * the generation router reads):
+ *
+ *   - A model that accepts a forced tool gets
+ *     `tool_choice: {type: 'tool', name}` and the caller's budget.
+ *   - A model that refuses one (the always-thinking family answers a
+ *     forced tool with HTTP 400) gets `tool_choice: auto` with at most
+ *     one call, an instruction naming the tool appended to the system
+ *     prompt, and {@link ALWAYS_THINKING_HEADROOM_TOKENS} added to the
+ *     caller's budget. `strict: true` is not sent: the callers' schemas
+ *     carry keywords strict tool use rejects (`minimum`/`maximum`,
+ *     map-shaped `additionalProperties`), and every caller validates
+ *     the input it gets back.
+ *
+ * No `temperature` is sent: newer tool-use models reject it with
+ * HTTP 400, so callers tolerate paraphrase in field values instead.
+ */
+import { anthropicRejectsForcedToolChoice, isRecord } from '@ggui-ai/protocol';
+
+const DEFAULT_ENDPOINT = 'https://api.anthropic.com/v1/messages';
+const DEFAULT_API_VERSION = '2023-06-01';
+const DEFAULT_ANSWER_BUDGET = 1024;
+
+/**
+ * Thinking budget added to the caller's ANSWER budget when the model
+ * refuses a forced tool. Those models always think, their thinking
+ * counts against `max_tokens`, and it comes before the tool call, so a
+ * small answer budget (the rerank judge asks for 512) would be spent
+ * before the `tool_use` block exists. `max_tokens` is a ceiling, not
+ * spend.
+ */
+export const ALWAYS_THINKING_HEADROOM_TOKENS = 16_000;
+
+/**
+ * The one tool the call asks for: the Messages API's own wire shape for a
+ * tool (`name`, `description`, `input_schema`), sent as-is under a raw
+ * `fetch`. It is not an SDK type and does not stand in for one; this
+ * package takes no Anthropic SDK dependency.
+ */
+export interface AnthropicTool {
+  readonly name: string;
+  readonly description: string;
+  /** The tool's input JSON Schema, sent verbatim. */
+  readonly input_schema: Readonly<Record<string, unknown>>;
+}
+
+export interface AnthropicToolCallRequest {
+  readonly apiKey: string;
+  /** The wire model id, sent verbatim. */
+  readonly model: string;
+  readonly systemPrompt: string;
+  readonly userPrompt: string;
+  readonly tool: AnthropicTool;
+  /** The answer budget. Absent ⇒ 1024. Headroom is added on top where the model needs it. */
+  readonly maxTokens?: number;
+  /** Cancels the request. */
+  readonly signal?: AbortSignal;
+  /** Override for tests and instrumentation. Absent ⇒ the global `fetch` at call time. */
+  readonly fetch?: typeof globalThis.fetch;
+  /** Override for a proxy endpoint. */
+  readonly endpoint?: string;
+}
+
+/** The tool input, with the response's token usage when it reported one. */
+export interface AnthropicToolCallResult {
+  readonly input: unknown;
+  /**
+   * `usage.input_tokens` / `usage.output_tokens` when both are numbers;
+   * absent otherwise. An unmetered response reports no usage, never
+   * zeros. No `cache_control` is sent, so there are no cache counts.
+   */
+  readonly usage?: { readonly input: number; readonly output: number };
+}
+
+/**
+ * How a structured call ended without the tool input it asked for:
+ *
+ *   - `max_tokens`: the budget ran out (`stop_reason: max_tokens`) before
+ *     the tool call.
+ *   - `no_tool_call`: the model finished without calling the tool
+ *     (possible under `auto`).
+ *   - `refusal`: the model declined (`stop_reason: refusal`).
+ *   - `http`: the API answered non-2xx.
+ *   - `malformed`: the body was JSON but not a Messages response.
+ */
+export const ANTHROPIC_STRUCTURED_CALL_FAILURE_KINDS = [
+  'max_tokens',
+  'no_tool_call',
+  'refusal',
+  'http',
+  'malformed',
+] as const;
+
+export type AnthropicStructuredCallFailureKind =
+  (typeof ANTHROPIC_STRUCTURED_CALL_FAILURE_KINDS)[number];
+
+/**
+ * A structured call that returned no tool input, NAMED by why. The kind
+ * is in the message too (`[max_tokens]` …), so a consumer that only
+ * surfaces the message (the rerank judge's `reason`) still reports
+ * which failure it was.
+ */
+export class AnthropicStructuredCallError extends Error {
+  readonly kind: AnthropicStructuredCallFailureKind;
+  readonly status: number | undefined;
+  readonly stopReason: string | undefined;
+  constructor(
+    kind: AnthropicStructuredCallFailureKind,
+    detail: string,
+    extra: { readonly status?: number; readonly stopReason?: string } = {},
+  ) {
+    super(`anthropic structured call [${kind}]: ${detail}`);
+    this.name = 'AnthropicStructuredCallError';
+    this.kind = kind;
+    this.status = extra.status;
+    this.stopReason = extra.stopReason;
+  }
+}
+
+/**
+ * Whether `err` is an {@link AnthropicStructuredCallError}, by its shape:
+ * an `Error` named `AnthropicStructuredCallError` whose `kind` is one of
+ * {@link ANTHROPIC_STRUCTURED_CALL_FAILURE_KINDS}.
+ *
+ * Prefer this to `instanceof`. An `instanceof` check holds only while one
+ * copy of this package is installed: a consumer that resolves a second
+ * copy (its own `@ggui-ai/ui-gen` at a different version from the one
+ * `@ggui-ai/mcp-server` depends on) gets errors from a class it did not
+ * import, and every one of them fails the check.
+ */
+export function isAnthropicStructuredCallError(
+  err: unknown,
+): err is AnthropicStructuredCallError {
+  if (!(err instanceof Error) || err.name !== 'AnthropicStructuredCallError') {
+    return false;
+  }
+  const kind: unknown = Reflect.get(err, 'kind');
+  return ANTHROPIC_STRUCTURED_CALL_FAILURE_KINDS.some((known) => known === kind);
+}
+
+/**
+ * Send one structured call and return the named tool's input. Every way
+ * the turn ends without that input throws an
+ * {@link AnthropicStructuredCallError} whose kind says which.
+ */
+export async function anthropicToolCall(
+  request: AnthropicToolCallRequest,
+): Promise<AnthropicToolCallResult> {
+  const answerBudget = request.maxTokens ?? DEFAULT_ANSWER_BUDGET;
+  const refusesForcedTool = anthropicRejectsForcedToolChoice(request.model);
+  const maxTokens = refusesForcedTool
+    ? answerBudget + ALWAYS_THINKING_HEADROOM_TOKENS
+    : answerBudget;
+  const toolName = request.tool.name;
+  const body = {
+    model: request.model,
+    max_tokens: maxTokens,
+    system: refusesForcedTool
+      ? `${request.systemPrompt}\n\nAnswer by calling the \`${toolName}\` tool exactly once. Do not answer in text.`
+      : request.systemPrompt,
+    messages: [{ role: 'user', content: request.userPrompt }],
+    tools: [
+      {
+        name: toolName,
+        description: request.tool.description,
+        input_schema: request.tool.input_schema,
+      },
+    ],
+    tool_choice: refusesForcedTool
+      ? { type: 'auto', disable_parallel_tool_use: true }
+      : { type: 'tool', name: toolName },
+  };
+  const fetchImpl = request.fetch ?? globalThis.fetch;
+  const response = await fetchImpl(request.endpoint ?? DEFAULT_ENDPOINT, {
+    method: 'POST',
+    headers: {
+      'x-api-key': request.apiKey,
+      'anthropic-version': DEFAULT_API_VERSION,
+      'content-type': 'application/json',
+    },
+    body: JSON.stringify(body),
+    ...(request.signal !== undefined ? { signal: request.signal } : {}),
+  });
+  if (!response.ok) {
+    const text = await response.text();
+    throw new AnthropicStructuredCallError(
+      'http',
+      `HTTP ${response.status}: ${text.slice(0, 500)}`,
+      { status: response.status },
+    );
+  }
+  const json: unknown = await response.json();
+  if (!isRecord(json) || !Array.isArray(json['content'])) {
+    throw new AnthropicStructuredCallError(
+      'malformed',
+      'response body is not a Messages response',
+    );
+  }
+  const stopReason =
+    typeof json['stop_reason'] === 'string' ? json['stop_reason'] : undefined;
+  const toolUse = json['content'].find(
+    (block: unknown): block is Record<string, unknown> =>
+      isRecord(block) && block['type'] === 'tool_use' && block['name'] === toolName,
+  );
+  if (toolUse !== undefined && toolUse['input'] !== undefined) {
+    const usage = readUsage(json['usage']);
+    return { input: toolUse['input'], ...(usage !== undefined ? { usage } : {}) };
+  }
+  if (stopReason === 'max_tokens') {
+    throw new AnthropicStructuredCallError(
+      'max_tokens',
+      `stop_reason=max_tokens before the "${toolName}" tool_use block (max_tokens=${maxTokens})`,
+      { stopReason },
+    );
+  }
+  if (stopReason === 'refusal') {
+    throw new AnthropicStructuredCallError(
+      'refusal',
+      'the model declined (stop_reason=refusal)',
+      { stopReason },
+    );
+  }
+  throw new AnthropicStructuredCallError(
+    'no_tool_call',
+    `the turn ended (stop_reason=${stopReason ?? 'absent'}) without a "${toolName}" tool_use block`,
+    stopReason !== undefined ? { stopReason } : {},
+  );
+}
+
+function readUsage(usage: unknown): AnthropicToolCallResult['usage'] {
+  if (!isRecord(usage)) return undefined;
+  const input = usage['input_tokens'];
+  const output = usage['output_tokens'];
+  return typeof input === 'number' && typeof output === 'number'
+    ? { input, output }
+    : undefined;
+}

package/src/providers/index.ts

@@ -62,6 +62,19 @@ export type { OpenRouterAdapterOptions } from './openrouter.js';
 export { createBedrockAdapter } from './bedrock.js';
 export type { BedrockAdapterOptions } from './bedrock.js';
 
+export {
+  ANTHROPIC_STRUCTURED_CALL_FAILURE_KINDS,
+  AnthropicStructuredCallError,
+  anthropicToolCall,
+  isAnthropicStructuredCallError,
+} from './anthropic-tool-call.js';
+export type {
+  AnthropicStructuredCallFailureKind,
+  AnthropicTool,
+  AnthropicToolCallRequest,
+  AnthropicToolCallResult,
+} from './anthropic-tool-call.js';
+
 import type { LlmProvider } from '@ggui-ai/mcp-server-core';
 import type { ProviderAdapter } from '../provider-adapter.js';
 import { createAnthropicAdapter } from './anthropic.js';