@ggui-ai/ui-gen 0.25.0 → 0.26.0

package/src/harness/llm-router.ts

@@ -161,6 +161,50 @@ export interface LLMResponse {
    * requested".
    */
   sampling?: AppliedSampling;
+  /**
+   * Why the provider stopped, normalized (ggui#1127): `length` = it hit the output cap, `stop` = it ended its
+   * answer, `content-filter` = a safety stop, `other` = anything else it reported. Set by the vision calls of
+   * providers that report one (Anthropic `stop_reason`, Google `finishReason`); absent when the provider or route
+   * said nothing — read absence as unknown, never as `stop`.
+   */
+  finishReason?: VisionFinishReason;
+  /**
+   * The model that answered, in the provider's own words (ggui#1687): Anthropic's `model`, Google's `modelVersion`.
+   * The request names an alias or a resolved id; this is what the provider says served it. Absent when it said
+   * nothing — read absence as unknown, never as the requested model.
+   */
+  servedModel?: string;
+}
+
+/** The `servedModel` field to spread into an {@link LLMResponse}: present only when the provider named one. */
+export function servedModelOf(name: string | null | undefined): { servedModel?: string } {
+  return typeof name === 'string' && name.length > 0 ? { servedModel: name } : {};
+}
+
+/** The normalized stop reason a vision call reports (ggui#1127). */
+export type VisionFinishReason = 'stop' | 'length' | 'content-filter' | 'other';
+
+/** Anthropic's `stop_reason`, normalized; absent stays absent. */
+export function anthropicFinishReason(stopReason: string | null | undefined): VisionFinishReason | undefined {
+  if (stopReason === null || stopReason === undefined) return undefined;
+  if (stopReason === 'end_turn' || stopReason === 'stop_sequence') return 'stop';
+  if (stopReason === 'max_tokens') return 'length';
+  if (stopReason === 'refusal') return 'content-filter';
+  return 'other';
+}
+
+/** Gemini's `finishReason`, normalized; absent stays absent. */
+export function googleFinishReason(finishReason: string | null | undefined): VisionFinishReason | undefined {
+  if (finishReason === null || finishReason === undefined) return undefined;
+  if (finishReason === 'STOP') return 'stop';
+  if (finishReason === 'MAX_TOKENS') return 'length';
+  if (['SAFETY', 'RECITATION', 'BLOCKLIST', 'PROHIBITED_CONTENT', 'SPII', 'IMAGE_SAFETY'].includes(finishReason)) return 'content-filter';
+  return 'other';
+}
+
+/** The `finishReason` field to spread into an {@link LLMResponse}: present only when the provider said. */
+function visionFinish(finishReason: VisionFinishReason | undefined): { finishReason?: VisionFinishReason } {
+  return finishReason !== undefined ? { finishReason } : {};
 }
 
 /**
@@ -806,6 +850,8 @@ export class AnthropicAgent extends LLMAgent {
         text,
         inputTokens: response.usage.input_tokens,
         outputTokens: response.usage.output_tokens,
+        ...visionFinish(anthropicFinishReason(response.stop_reason)),
+        ...servedModelOf(response.model),
       };
     } catch (e) {
       const endedAt = Date.now();
@@ -1575,6 +1621,15 @@ export class OpenAIAgent extends LLMAgent {
 }
 
 // =============================================================================
+/**
+ * `Interactions.GenerationConfig` as the Interactions API accepts it (ggui#1579). The SDK's type (@google/genai 2.15.0)
+ * omits `temperature`, but the API takes `generation_config.temperature` and forwards it to the request's own: it
+ * range-checks the value (2.5 is refused with "GenerateContentRequest.generation_config.temperature: temperature must be
+ * in the range [0.0, 2.0]", 0 is accepted), while a key the API does not know is refused as "Unknown parameter". The
+ * field is declared here so the call is built against a type that carries it, not left to a spread of an undeclared key.
+ */
+type InteractionsGenerationConfig = Interactions.GenerationConfig & { readonly temperature?: number };
+
 // GoogleAgent — uses Interactions API (server-side state, automatic caching)
 // =============================================================================
 
@@ -1666,7 +1721,7 @@ export class GoogleAgent extends LLMAgent {
   ): Promise<LLMResponse> {
     const client = await this.getClient<GoogleGenAI>();
 
-    const generationConfig: Interactions.GenerationConfig = {
+    const generationConfig: InteractionsGenerationConfig = {
       ...(maxTokens ? { max_output_tokens: maxTokens } : {}),
       ...(temperature !== undefined ? { temperature } : {}),
     };
@@ -1730,6 +1785,8 @@ export class GoogleAgent extends LLMAgent {
         // 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,
+        ...visionFinish(googleFinishReason(response.candidates?.[0]?.finishReason)),
+        ...servedModelOf(response.modelVersion),
       };
 
       const endedAt = Date.now();

package/src/harness/result-types.ts

@@ -13,6 +13,7 @@ import type { DataContract, JsonObject } from "@ggui-ai/protocol";
 import type { AdapterResult } from "../adapters/types.js";
 import type { RenderingContext } from "../contract-context.js";
 import type { EvalResult } from "../evaluation/types-public.js";
+import type { VisualLegTokens } from "../evaluation/visual-evaluator.js";
 import type { CanvasClass, DesignMode } from "../design-mode.js";
 
 // =============================================================================
@@ -66,6 +67,14 @@ export interface GenerationResult extends AdapterResult {
   passesUsed: number;
   /** Three-tier evaluation result (tier 0 + LLM tier 1+2 + visual) */
   evalResult?: EvalResult;
+  /**
+   * ggui#1522 — what the IN-LOOP visual judge spent during this generation (its scoring calls, and its report-only
+   * criteria calls apart), priced at the visual agent's model. NOT inside `tokens`, which covers the coding turns
+   * and the text evaluator. And NOT the same calls as a post-generation judge's own visual pass (a benchmark
+   * report's `meta.costs.visualUsd`): a cost rule that adds both is correct, one read as the other double-counts.
+   * Absent when no in-loop visual leg ran or it reported no tokens.
+   */
+  inLoopVisualTokens?: VisualLegTokens;
   /** 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) */

package/src/harness/runtime.ts

@@ -108,6 +108,15 @@ export interface SingleComponentParams {
     criteriaBank?: CriteriaBank;
     /** ggui#1436 — the caller's item kind for the selector (a bootstrap mint's `hello`); absent = not gated by kind. */
     criteriaKind?: string;
+    /**
+     * ggui#1542 — which of the VISUAL leg's own findings may start another eval round when the quality mode is `fast`.
+     * `'critical'` (the default, today's behaviour): only a critical finding, which the harness makes a blocking fail.
+     * `'major'`: the visual JUDGE's major findings (tier-2 warns) too. The fit measurement's own warn-level overflow is
+     * not among them (fit runs with or without a judge, so it is its own feedback source), and neither are the text
+     * evaluator's warns. The other quality modes already act on every warn, so the setting changes nothing there. The
+     * fix turn is fed as any continuing round is (fails first, then warns).
+     */
+    actOn?: "critical" | "major";
   };
   onProgress?: (event: unknown) => void;
   onInitialResult?: (result: {

package/src/harness/types-public.ts

@@ -21,7 +21,14 @@
 import type { GenerationProfileInput } from "../boilerplate/styling-profile.js";
 import type { GadgetDescriptor, DataContract, JsonValue } from "@ggui-ai/protocol";
 import type { Classification } from "../classifier/axes.js";
-import type { EvalIssue, EvalTier, AxisCheck, ProbeHostLoad, RuntimeProbeStatus } from "../evaluation/types-public.js";
+import type {
+  EvalIssue,
+  EvalTier,
+  AxisCheck,
+  ProbeHostLoad,
+  ProbePendingAffordance,
+  RuntimeProbeStatus,
+} from "../evaluation/types-public.js";
 import type { LLMToolDef } from "../llm.js";
 import type { CacheTier, HarnessFragment } from "../fragments/index.js";
 import type { HarnessPolicy, ProcessMode } from "../policy.js";
@@ -160,6 +167,8 @@ export interface RuntimeRenderOutcome {
   readonly hostLoad?: ProbeHostLoad;
   /** Time the check waited for a probe slot before it started, ms; present only when > 0 (ggui#1380 C2b). */
   readonly queuedMs?: number;
+  /** `ran` only: the pending-affordance walk (ggui#1398), report-only; absent when no action walk ran. */
+  readonly pendingAffordance?: ProbePendingAffordance;
 }
 
 export interface RuntimeRenderCheck {

package/src/index.ts

@@ -28,6 +28,11 @@ export type { GenerationResult, SameExchangeBreak } from './harness/result-types
 // either design mode — so a harness definition can carry both modes' digests
 // while a run's metadata carries only the mode that ran.
 export { generatorBuild } from './generator-build.js';
+// ggui#1513 — which in-loop evaluation legs a generation runs: the harness's
+// own gate, for a host that needs to know whether a generation's token
+// counts can include evaluation calls.
+export { inLoopEvaluation, runsInLoopEvaluation } from './harness/in-loop-evaluation.js';
+export type { InLoopEvaluationSwitches } from './harness/in-loop-evaluation.js';
 export type { UiGenBuild } from './generator-build.js';
 
 // Generator registry seam re-export. The interface + slug helpers live

package/src/internal/verdict-line.ts

@@ -0,0 +1,33 @@
+/**
+ * How an isolated worker that runs generated component code (the
+ * runtime-render check's, the render smoke test's) hands its verdict to its
+ * host.
+ *
+ * The worker's stdout is shared with the component: card code runs in the
+ * worker's own realm with Node's `console`, so a card that logs even one line
+ * would corrupt a verdict read as "the whole of stdout". The verdict
+ * therefore goes out on one line carrying {@link VERDICT_PREFIX}, and the
+ * host reads the LAST such line, ignoring everything else.
+ */
+
+/** The prefix of the verdict line. Not a string a card would print by accident. */
+export const VERDICT_PREFIX = '@@ggui-render-check-verdict@@';
+
+/** The worker's verdict line, newline-terminated. */
+export function formatVerdictLine(value: unknown): string {
+  return `${VERDICT_PREFIX} ${JSON.stringify(value)}\n`;
+}
+
+/**
+ * The value on the last verdict line in `stdout`, or `undefined` when no
+ * line carries the prefix. A prefixed line that is not JSON throws, so the
+ * host can report it as such.
+ */
+export function parseVerdictLine<Verdict>(stdout: string): Verdict | undefined {
+  const lines = stdout.split('\n');
+  for (let i = lines.length - 1; i >= 0; i -= 1) {
+    const line = lines[i]!;
+    if (line.startsWith(`${VERDICT_PREFIX} `)) return JSON.parse(line.slice(VERDICT_PREFIX.length + 1)) as Verdict;
+  }
+  return undefined;
+}

package/src/taught-tokens.ts

@@ -0,0 +1,32 @@
+// The consumed-token names the generator may TEACH — the manifest minus the names a card may not
+// reference yet.
+//
+// A card is minted by one release and rendered by whichever runtime serves it: during a rolling
+// deploy, or after a rollback, that runtime can be the previous release, which neither declares
+// nor completes a key derived for the first time in this one. A bare `var(--new-key)` then
+// resolves to nothing — a `border` shorthand drops whole — and the no-fallback rule leaves the
+// card nothing to fall back on. So a new derived key ships in two steps: the renderers that
+// declare and complete it serve first (the design package's own primitives read it behind a
+// fallback), and the release AFTER takes it out of this set, in the same change as the prompt
+// guidance that teaches it.
+
+import { consumedTokenManifest } from "@ggui-ai/design/themes";
+
+/**
+ * Manifest names held back from every surface that teaches the model a name — the free prompt's
+ * colour vocabulary and token reference, and the self-check's nearest-name suggestions. The
+ * closed-set check still admits them: a card that references one is valid wherever this release
+ * renders it.
+ *
+ * - ggui#1494 — the control edges (`controlOutline`, `controlAccentOutline`): derived and completed
+ *   from this release; taught from the next.
+ */
+export const NOT_YET_TAUGHT_TOKENS: ReadonlySet<string> = new Set([
+  "--ggui-color-controlAccentOutline",
+  "--ggui-color-controlOutline",
+]);
+
+/** The manifest as the model is taught it. */
+export const taughtTokenManifest: readonly string[] = consumedTokenManifest.filter(
+  (token) => !NOT_YET_TAUGHT_TOKENS.has(token),
+);

package/src/tools/render-check-worker.ts

@@ -43,6 +43,7 @@ import * as esbuild from 'esbuild';
 import type { JsonObject } from '@ggui-ai/protocol';
 import { evaluateComponentSource } from '../internal/evaluate-component-source.js';
 import { hostGlobals } from '../internal/open-record.js';
+import { formatVerdictLine } from '../internal/verdict-line.js';
 
 interface WorkerInput {
   readonly sourceCode: string;
@@ -212,7 +213,7 @@ async function renderOnce(input: WorkerInput): Promise<WorkerOutput> {
 }
 
 function emit(output: WorkerOutput): void {
-  process.stdout.write(JSON.stringify(output));
+  process.stdout.write(formatVerdictLine(output));
 }
 
 async function readAllStdin(): Promise<string> {

package/src/tools/render-check.ts

@@ -28,6 +28,7 @@ import { existsSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { pathToFileURL, fileURLToPath } from 'node:url';
 import { runSandboxed } from '@ggui-ai/sandbox';
+import { parseVerdictLine } from '../internal/verdict-line.js';
 import type {
   JsonObject,
 } from '@ggui-ai/protocol';
@@ -168,20 +169,20 @@ export async function tryRender(
     return `Render error: worker exited ${result.exitCode}${tail ? ` — ${tail}` : ''}`;
   }
 
-  const stdout = result.stdout.trim();
-  if (stdout.length === 0) {
-    return 'Render error: worker exited without producing a verdict.';
-  }
-
   type Verdict = { ok: true } | { ok: false; error: string };
-  let verdict: Verdict;
+  let verdict: Verdict | undefined;
   try {
-    verdict = JSON.parse(stdout) as Verdict;
+    // The verdict rides its own prefixed line, so a component that logs to
+    // stdout while it renders cannot corrupt it.
+    verdict = parseVerdictLine<Verdict>(result.stdout);
   } catch (err) {
     return `Render error: malformed worker verdict — ${
       err instanceof Error ? err.message : String(err)
     }`;
   }
+  if (verdict === undefined) {
+    return 'Render error: worker exited without producing a verdict.';
+  }
 
   return verdict.ok ? null : verdict.error;
 }