@ggui-ai/ui-gen 0.27.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/assemble-result.ts

@@ -132,6 +132,7 @@ export async function assembleGenerationResult(
         : telemetry.evalResult,
     // ggui#404 — present only when the same-exchange guard ended the run.
     ...(telemetry.sameExchangeBreak !== undefined ? { sameExchangeBreak: telemetry.sameExchangeBreak } : {}),
+    ...(telemetry.sameFailureBreak !== undefined ? { sameFailureBreak: telemetry.sameFailureBreak } : {}),
     needsBackgroundImprovement,
     selfCheckPassed: telemetry.selfCheckPassed,
     timing,

package/src/harness/coding/dupe-break.ts

@@ -102,6 +102,11 @@ export interface DupeBreakState {
    *  information-free — the model learned nothing it didn't already
    *  have. 1 = first occurrence; 2 = one repeat (nudge); 3 = break. */
   consecutiveIdenticalExchanges: number;
+  /** ggui#1791 — for each failure signature ({@link failureSignatures}), how
+   *  many failed writes (`apply_changes` / `rewrite`) have reported it since
+   *  the last write that passed, whatever the patch and whatever failed in
+   *  between. Cleared when a write passes. */
+  failureCounts: Map<string, number>;
 }
 
 /**
@@ -147,6 +152,70 @@ export const SAME_EXCHANGE_NUDGE =
   "you already have and emit an apply_changes (or scoped) call now; one " +
   "more identical repeat terminates the run.";
 
+/**
+ * ggui#1791 — the failures a failed write reported, one signature per failing
+ * check, with what changes between two identical failures removed: every
+ * digit (line and column numbers, counts) and runs of whitespace.
+ *
+ * A self-check result lists its violations as `[category] description` lines;
+ * each one is its own signature, so a check that fails on every turn reads as
+ * the same failure whether or not another check fails beside it. A result with
+ * no violation line (a build error, a rejected patch) is one signature: its
+ * text without the `Committed <oid>: "<message>"` line, which carries a fresh
+ * oid and the model's own message every turn.
+ *
+ * The patch fingerprint above keys on the PATCH, so the same failure under a
+ * different patch each turn (a reworded comment, a moved line) never reads as
+ * stuck, and a run goes to the turn cap. These key on the FAILURE.
+ */
+export function failureSignatures(resultText: string): string[] {
+  const norm = (text: string): string => text.replace(/[0-9]+/g, "#").replace(/\s+/g, " ").trim();
+  const violations = [...resultText.matchAll(/^\[[^\]\n]+\] [^\n]+/gm)].map((m) => norm(m[0]));
+  if (violations.length > 0) return [...new Set(violations)];
+  const rest = norm(resultText.replace(/^Committed [^\n]*\n/, ""));
+  return rest.length > 0 ? [rest] : [];
+}
+
+/** The failure a write has reported most often since the last pass, and how often. */
+export interface RepeatedFailure {
+  readonly signature: string;
+  readonly repeats: number;
+}
+
+/**
+ * ggui#1791 — record one failed write: count each of its signatures once, and
+ * return the one now reported most often since the last passing write
+ * (undefined when the result carried no recognisable failure).
+ */
+export function recordWriteFailure(state: DupeBreakState, resultText: string): RepeatedFailure | undefined {
+  let top: RepeatedFailure | undefined;
+  for (const signature of failureSignatures(resultText)) {
+    const repeats = (state.failureCounts.get(signature) ?? 0) + 1;
+    state.failureCounts.set(signature, repeats);
+    if (top === undefined || repeats > top.repeats) top = { signature, repeats };
+  }
+  return top;
+}
+
+/** ggui#1791 — a write passed: every count starts over. */
+export function clearWriteFailures(state: DupeBreakState): void {
+  state.failureCounts.clear();
+}
+
+/** A failure reported for the third time since the last pass ⇒ one explicit nudge. */
+export const SAME_FAILURE_NUDGE_AT = 3;
+
+/** A failure reported for the fifth time since the last pass ⇒ the loop is not
+ *  converging; the caller ends the run, which ships what the turn cap would
+ *  have shipped. */
+export const SAME_FAILURE_BREAK_AT = 5;
+
+/** Appended to the tool result of the {@link SAME_FAILURE_NUDGE_AT}th identical failure. */
+export const SAME_FAILURE_NUDGE =
+  "\n\n[harness] This same failure has now been reported for three of your " +
+  "patches. Changing other code does not clear it: re-read that check above and " +
+  "change exactly what it names. Two more reports of it end the run.";
+
 export function createDupeBreakState(): DupeBreakState {
   return {
     lastFailedPatchFingerprint: null,
@@ -164,6 +233,7 @@ export function createDupeBreakState(): DupeBreakState {
     consecutiveNoToolCalls: 0,
     lastExchangeKey: null,
     consecutiveIdenticalExchanges: 0,
+    failureCounts: new Map(),
   };
 }
 

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

@@ -25,7 +25,7 @@ import {
 import { runEvalRound } from "./run-eval-round.js";
 import type { TokenUsage } from "./run-eval-round.js";
 import type { VisualLegTokens } from "../../evaluation/visual-evaluator.js";
-import type { SameExchangeBreak } from "../result-types.js";
+import type { SameExchangeBreak, SameFailureBreak } from "../result-types.js";
 
 type PreWarmedEvalContext =
   import("../../evaluation/llm-evaluator.js").PreWarmedEvalContext;
@@ -105,6 +105,8 @@ export interface GenerateTelemetry {
    * undefined unless that guard is what stopped the loop.
    */
   sameExchangeBreak: SameExchangeBreak | undefined;
+  /** ggui#1791 — set when the same-failure guard ended the run. */
+  sameFailureBreak: SameFailureBreak | undefined;
   /** Latest compiled code — empty string until the first self-check pass. */
   compiledCode: string;
   /**
@@ -147,6 +149,7 @@ export function createTelemetry(): GenerateTelemetry {
     probeRepairTrigger: undefined,
     contractFeedback: undefined,
     sameExchangeBreak: undefined,
+    sameFailureBreak: undefined,
     compiledCode: "",
     pairedSource: "",
     selfCheckPassed: false,
@@ -223,6 +226,7 @@ export function absorbTurn(telemetry: GenerateTelemetry, turn: CodingTurnResult)
     else telemetry.counters.outcomes.selfCheckFail++;
   }
   if (turn.sameExchangeBreak !== undefined) telemetry.sameExchangeBreak = turn.sameExchangeBreak;
+  if (turn.sameFailureBreak !== undefined) telemetry.sameFailureBreak = turn.sameFailureBreak;
 }
 
 export interface CreateGenerateRunnerInput {
@@ -297,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

@@ -21,7 +21,7 @@ import { executeTool } from "../../coding-agent/tools.js";
 import type { CostTracker } from "../../evaluation/cost-tracker.js";
 import type { LLMAgent } from "../llm-router.js";
 import type { Harness } from "../types-public.js";
-import type { SameExchangeBreak } from "../result-types.js";
+import type { SameExchangeBreak, SameFailureBreak } from "../result-types.js";
 import {
   APPLY_CHANGES_HASHLINE_TOOL,
   APPLY_CHANGES_HASHLINE_TOOL_FLAT,
@@ -38,10 +38,16 @@ import {
 import { LUCIDE_ICON_NAMES } from "@ggui-ai/design";
 import { formatWithHashlines } from "../hashline.js";
 import {
+  clearWriteFailures,
   recordToolExchange,
+  recordWriteFailure,
   SAME_EXCHANGE_BREAK_AT,
   SAME_EXCHANGE_NUDGE,
+  SAME_FAILURE_BREAK_AT,
+  SAME_FAILURE_NUDGE,
+  SAME_FAILURE_NUDGE_AT,
 } from "./dupe-break.js";
+import type { RepeatedFailure } from "./dupe-break.js";
 
 /** Staged process-mode phase machine — also defined in runtime.ts. */
 export type A1Phase = "scaffold" | "fill" | "post";
@@ -183,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;
 }
 
 /**
@@ -254,6 +262,11 @@ export interface CodingTurnResult {
    * control value many exits share. No key on any other turn.
    */
   readonly sameExchangeBreak?: SameExchangeBreak;
+  /**
+   * Set only on the `break` the same-failure guard returns (ggui#1791). No
+   * key on any other turn.
+   */
+  readonly sameFailureBreak?: SameFailureBreak;
 }
 
 /**
@@ -533,6 +546,7 @@ ${closingInstruction}`;
     planFirstTurn,
     codeFormat,
   );
+  ctx.onPrompt?.({ turn: turnsUsed, systemPrompt, userPrompt });
   const llmStart = Date.now();
   const response = await codingAgent.callTools(
     codingModel,
@@ -952,6 +966,26 @@ ${closingInstruction}`;
     }
   }
 
+  // ggui#1791 same-failure guard — the patch fingerprint above keys on the
+  // PATCH, so the same failure under a different patch each turn (a reworded
+  // comment, a moved line) never counts as stuck. This keys on the FAILURE:
+  // each failing check a write reports is counted since the last passing
+  // write, whatever failed in between. The third report of one gets a nudge,
+  // the fifth ends the run. A passing write clears the counts; a non-write
+  // tool (cat, icons) changes nothing and leaves them as they were.
+  const isWrite = call.name === "apply_changes" || call.name === "rewrite";
+  let repeatedFailure: RepeatedFailure | undefined;
+  if (ctx.dupeBreak && isWrite) {
+    if (result.done) {
+      clearWriteFailures(ctx.dupeBreak);
+    } else {
+      repeatedFailure = recordWriteFailure(ctx.dupeBreak, result.result);
+      if (repeatedFailure?.repeats === SAME_FAILURE_NUDGE_AT) {
+        augmentedResultText += SAME_FAILURE_NUDGE;
+      }
+    }
+  }
+
   // Send tool result back to close the API contract (Google/OpenAI/OpenRouter)
   // This enables proper session chaining on the next callTools() invocation.
   await codingAgent.sendToolResult([{
@@ -984,6 +1018,30 @@ ${closingInstruction}`;
     };
   }
 
+  if (repeatedFailure !== undefined && repeatedFailure.repeats >= SAME_FAILURE_BREAK_AT) {
+    const signature = repeatedFailure.signature.slice(0, 160);
+    console.log(
+      `[coding-agent] SAME_FAILURE_BREAK | tool=${call.name} | repeats=${repeatedFailure.repeats} | failure=${JSON.stringify(signature.slice(0, 80))} — terminating run (ggui#1791)`,
+    );
+    return {
+      control: "break",
+      compiledCode: "",
+      selfCheckPassed: false,
+      outcome: undefined,
+      phase: undefined,
+      tokens,
+      ...cacheTokens,
+      llmMs,
+      toolMs,
+      lastResultText: augmentedResultText,
+      lastDiffFailed: false,
+      isEvalFeedback: false,
+      iconNamesCache,
+      preWarmedContext,
+      sameFailureBreak: { signature, repeats: repeatedFailure.repeats },
+    };
+  }
+
   // Track whether the diff itself failed to apply (vs applied but had violations)
   const turnDiffFailed = !!result.error && result.result.includes("DIFF");
 

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/result-types.ts

@@ -62,6 +62,16 @@ export interface SameExchangeBreak {
   readonly repeats: number;
 }
 
+/**
+ * ggui#1791 — the same-failure guard ended the run: one failing check
+ * (`signature`, its first 160 characters) was reported by this many failed
+ * writes since the last passing one, whatever the patch.
+ */
+export interface SameFailureBreak {
+  readonly signature: string;
+  readonly repeats: number;
+}
+
 export interface GenerationResult extends AdapterResult {
   /** Number of generation passes the harness performed */
   passesUsed: number;
@@ -77,6 +87,8 @@ export interface GenerationResult extends AdapterResult {
   inLoopVisualTokens?: VisualLegTokens;
   /** Set only when the same-exchange guard ended the run (ggui#404); no key otherwise. */
   sameExchangeBreak?: SameExchangeBreak;
+  /** ggui#1791 — set only when the same-failure guard ended the run. */
+  sameFailureBreak?: SameFailureBreak;
   /** 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

@@ -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,7 +22,16 @@ 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 type { GenerationResult, SameExchangeBreak } from './harness/result-types.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
 // either design mode — so a harness definition can carry both modes' digests