@ggui-ai/ui-gen 0.24.0 → 0.26.0

package/src/harness/in-loop-evaluation.ts

@@ -0,0 +1,39 @@
+/**
+ * Which in-loop evaluation legs a generation runs (ggui#1513).
+ *
+ * The harness gates its evaluation rounds on this, and nothing else does:
+ * the text evaluator runs when `evaluation.enabled`, and the visual judge
+ * runs when `visualEvaluation.enabled` or when a quality config asks for it
+ * (`qualityConfig.visualEval`). A host that needs to know whether a
+ * generation's token counts (`GenerationMetadata`) can include evaluation
+ * calls reads it here, with the options it configured the generator with,
+ * instead of keeping its own copy of the rule.
+ */
+import type { QualityConfig } from "../evaluation/types-public.js";
+
+/** The switches that turn an in-loop evaluation leg on. */
+export interface InLoopEvaluationSwitches {
+  readonly evaluation?: { readonly enabled: boolean };
+  readonly visualEvaluation?: { readonly enabled: boolean };
+  readonly qualityConfig?: Pick<QualityConfig, "visualEval">;
+}
+
+/** The in-loop evaluation legs these options turn on. */
+export function inLoopEvaluation(options: InLoopEvaluationSwitches): {
+  readonly text: boolean;
+  readonly visual: boolean;
+} {
+  return {
+    text: options.evaluation?.enabled === true,
+    visual: options.visualEvaluation?.enabled === true || options.qualityConfig?.visualEval === true,
+  };
+}
+
+/**
+ * True when these options turn either leg on: a generation built with them
+ * can spend tokens on evaluation calls as well as on its coding turns.
+ */
+export function runsInLoopEvaluation(options: InLoopEvaluationSwitches): boolean {
+  const legs = inLoopEvaluation(options);
+  return legs.text || legs.visual;
+}

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

@@ -33,6 +33,7 @@ import { renderPitfallsBlock } from "./pitfalls.js";
 import type { GadgetDescriptor, DataContract, JsonObject } from "@ggui-ai/protocol";
 import { buildSystemPrompt as buildSystemPromptSkeleton } from "../boilerplate.js";
 import type { AgentConfig } from "./llm-router.js";
+import type { CriteriaBank } from "../evaluation/criteria/bank.js";
 import type { CanvasClass, DesignMode } from "../design-mode.js";
 
 // Re-export the boilerplate generator so existing internal importers
@@ -103,6 +104,19 @@ export interface SingleComponentParams {
      * default tokens. Never part of the prompt or the identity.
      */
     cssTokens?: string;
+    /** ggui#1436 — the visual criteria bank (data, parsed by `parseCriteriaBank`); absent = no block, today's judge. */
+    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/harness-tool-names.ts

@@ -0,0 +1,38 @@
+/**
+ * The coding loop's tool set — the ONE list `createHarness` builds its
+ * coding and scoped tools from, and the identity a build stamp names it
+ * by.
+ *
+ * `harnessToolNames(mode)` returns one entry per tool definition,
+ * `<name>@<digest>`: the tool's own (unprefixed) name and the first 8 hex
+ * of sha256 over `JSON.stringify` of its definition — so a change to a
+ * tool's schema OR its description (prompt text, as output-changing as a
+ * template) moves the entry, and two definitions that share a name (a
+ * scoped variant keeps the name and narrows the grammar) are two entries.
+ * Coding and scoped alike, since the scoped set runs on the
+ * duplicate-fingerprint escape; sorted, de-duplicated, a fresh array. It
+ * reads the same constants the harness is assembled from, so the list can
+ * never drift from what runs; the pin beside it holds the two equal for
+ * every design mode. The design mode is part of the signature because the
+ * tool set is keyed by the harness a mode builds, even while both modes
+ * declare the same tools.
+ */
+import { createHash } from 'node:crypto';
+import type { LLMToolDef } from './llm.js';
+import type { DesignMode } from './design-mode.js';
+import { APPLY_CHANGES_TOOL, APPLY_CHANGES_TOOL_SCOPED } from './tools.js';
+
+/** The coding tools every harness declares (`what.codingTools`). */
+export const HARNESS_CODING_TOOLS: readonly LLMToolDef[] = [APPLY_CHANGES_TOOL];
+/** The scoped fallback the runtime promotes into `codingTools` on a duplicate-fingerprint escape. */
+export const HARNESS_SCOPED_TOOLS: readonly LLMToolDef[] = [APPLY_CHANGES_TOOL_SCOPED];
+
+/** One tool's entry: `<name>@<first 8 hex of sha256(JSON.stringify(def))>`. */
+export function harnessToolEntry(def: LLMToolDef): string {
+  return `${def.name}@${createHash('sha256').update(JSON.stringify(def), 'utf8').digest('hex').slice(0, 8)}`;
+}
+
+export function harnessToolNames(designMode: DesignMode): string[] {
+  void designMode; // one tool set for every mode today; the mode keys the harness, so it stays on the signature
+  return [...new Set([...HARNESS_CODING_TOOLS, ...HARNESS_SCOPED_TOOLS].map(harnessToolEntry))].sort();
+}

package/src/index.ts

@@ -23,6 +23,16 @@ 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';
+// 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
+// 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
@@ -54,6 +64,12 @@ export {
 export type { RenderingContext } from './contract-context.js';
 export { canvasForRenderingContext } from './contract-context.js';
 
+// ── The coding loop's tool set ───────────────────────────────────────
+//
+// The tools the harness declares, by name — the one list `createHarness`
+// builds from, so a build stamp names the same set that runs.
+export { harnessToolEntry, harnessToolNames, HARNESS_CODING_TOOLS, HARNESS_SCOPED_TOOLS } from './harness-tool-names.js';
+
 // ── Design mode ──────────────────────────────────────────────────────
 //
 // `createUiGenerator({ designMode })` — `constrained` (default) or
@@ -88,4 +104,5 @@ export { createAnthropicClient } from './adapters/claude/client.js';
 // login path (`ggui serve --local-cli-login`); never a real key.
 export { CLAUDE_CODE_LOGIN_CREDENTIAL } from './adapters/claude/claude-code-login.js';
 export { AESTHETIC_BRIEF_MAX_CHARS, type GenerationProfileInput } from './boilerplate/styling-profile.js';
+export type { VisualEvalAgentSpec } from './adapters/generation-dispatch.js';
 export { EFFORT_DIALS, EFFORT_TABLE_VERSION, effortDials, type EffortDials } from './effort.js';

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/run-check.ts

@@ -121,6 +121,8 @@ export async function runCheck(input: RunCheckInput): Promise<CheckResult> {
     designMode: harness.designMode,
     // ggui#1117: the canvas the harness was built for, when it has one — never a default.
     ...(harness.canvas !== undefined ? { canvas: harness.canvas } : {}),
+    // ggui#1285: the props the probe and judge rendered with — the fixture-echo check reads them.
+    ...(input.fixtureProps !== undefined ? { fixtureProps: input.fixtureProps } : {}),
   };
   // The one runner `runAxisChecks` shares (ggui#1046 trace prints here, on the served path).
   const axisRun = runGatedAxisChecks(check.axisChecks, axisInput);

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),
+);