@ggui-ai/ui-gen 0.24.0 → 0.26.0

package/dist/types-public-B7wn4ce5.d.ts

@@ -0,0 +1,959 @@
+import { JsonObject, DataContract } from '@ggui-ai/protocol';
+import { LLMToolDef } from './llm.js';
+import { GenerationRuntimeProbeStatus, GenerationRuntimeProbeOutcome } from '@ggui-ai/mcp-server-core';
+import { C as CanvasClass, D as DesignMode } from './design-mode-DGWN_Gkm.js';
+import { R as RiskTier, a as RenderShape, S as StateShape, W as WriteShape, F as FetchShape, L as LayoutShape, C as Classification, A as AxisVector } from './axes-CKVCzR_x.js';
+import { A as AxisKey } from './types-Dh1s4K9j.js';
+
+interface AgentConfig {
+    provider: 'anthropic' | 'openai' | 'google' | 'openrouter';
+    model: string;
+    /**
+     * Sampling temperature. When defined it is threaded into the provider
+     * request; when undefined the provider default is used (unchanged
+     * behavior for all existing callers).
+     *
+     * Capability is the ROUTER's: Anthropic Opus 4.7+ and the 5-family
+     * (`claude-opus-4-7*`, `claude-fable-5*`, `claude-opus-5*`,
+     * `claude-sonnet-5*`, incl. Bedrock ids) return HTTP 400 on a
+     * non-default `temperature`/`top_p`/`top_k`, so the Anthropic adapter
+     * STRIPS the value for those ids (one log line naming model + param)
+     * and reports the effective sampling on `LLMResponse.sampling`. Callers
+     * keep expressing intent; disclosure reads the applied value.
+     */
+    temperature?: number;
+    /**
+     * Explicit per-call credentials/routing, bypassing `process.env`
+     * entirely when supplied. Absent (default) preserves today's
+     * behavior — each agent falls back to reading its provider's env
+     * var(s) directly, so existing callers (including self-hosters who
+     * set env vars once at process start) are unaffected. Use this to
+     * run concurrent generations safely in one process: two simultaneous
+     * calls with different `routeOverride`s never race on shared
+     * `process.env` state.
+     */
+    routeOverride?: {
+        readonly apiKey?: string;
+        /** Anthropic-only: force the Bedrock-IAM client instead of the direct API client. */
+        readonly useBedrock?: boolean;
+        /**
+         * Anthropic-only (ggui#1185): run on the machine's own Claude Code
+         * LOGIN instead of a key — the route decision `auth: 'claude-code-login'`
+         * lands here, and `createAgent` / `createVisionAgent` select
+         * `ClaudeCodeLoginAgent` (one `query()` per call) instead of the raw
+         * API client. Every agent the harness builds — coding, evaluation,
+         * visual judge — takes the same decision. Off unless set; a real key
+         * never coexists with it (the router refuses a non-anthropic route).
+         */
+        readonly claudeCodeLogin?: boolean;
+    };
+    /**
+     * Observer invoked once per retried attempt when `apiCall()` (#489)
+     * retries a rate-limited (HTTP 429) provider call. Fires AFTER the
+     * retry decision is made and BEFORE the delay is awaited — never on
+     * the terminal failure/success of the whole call. Purely an
+     * observability hook: it never influences whether or how long
+     * `apiCall()` retries. If the observer itself throws, `apiCall()`
+     * catches it, logs a `console.warn`, and proceeds to the retry
+     * delay unaffected — a broken observer cannot turn a recoverable
+     * 429 into an unrelated hard failure. Absent (default) is a no-op;
+     * `apiCall()` still logs every retry via `console.warn` regardless.
+     */
+    onRetry?: (info: ProviderRetryInfo) => void;
+}
+/** One retried attempt's context — passed to `AgentConfig.onRetry`. */
+interface ProviderRetryInfo {
+    readonly provider: AgentConfig['provider'];
+    /** 1-based index of this retry (1 = first retry, 2 = second, …). */
+    readonly attempt: number;
+    /** Total retries `apiCall()` will attempt before giving up. */
+    readonly maxAttempts: number;
+    /** HTTP status of the failed call, when the caught error carries one. */
+    readonly status: number | undefined;
+    /** Provider-supplied `Retry-After` value in seconds, when present and within the cap. */
+    readonly retryAfterSec: number | undefined;
+    /** Delay actually awaited before the next attempt. */
+    readonly delayMs: number;
+    /** One-line error summary (same shape as the existing `console.error` line). */
+    readonly message: string;
+}
+/**
+ * What sampling the provider ACTUALLY received for a text call — so a
+ * caller that asked for `temperature: 0` (a disclosed reproducibility
+ * property, e.g. the benchmark judge panel) can record the effective
+ * value instead of the requested one. `'provider-default'` means no
+ * temperature reached the provider: either the caller passed none, or
+ * the adapter stripped it because the model rejects sampling params
+ * (Anthropic Opus 4.7+ / 5-family → HTTP 400 on non-default
+ * `temperature`/`top_p`/`top_k`); `strippedReason` names the second case.
+ */
+interface AppliedSampling {
+    readonly temperature: number | 'provider-default';
+    readonly strippedReason?: string;
+}
+interface LLMResponse {
+    text: string;
+    inputTokens: number;
+    outputTokens: number;
+    /**
+     * Effective sampling for this call (see {@link AppliedSampling}).
+     * Every provider's `callText` sets it; absent only on paths that
+     * predate the field — treat absence as unknown, never as "as
+     * 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 normalized stop reason a vision call reports (ggui#1127). */
+type VisionFinishReason = 'stop' | 'length' | 'content-filter' | 'other';
+interface LLMTool {
+    name: string;
+    description: string;
+    parameters: JsonObject;
+    handler: (args: JsonObject) => Promise<{
+        content: Array<{
+            text: string;
+        }>;
+        isError?: boolean;
+    }>;
+}
+interface LLMWithToolsResponse {
+    text: string;
+    inputTokens: number;
+    outputTokens: number;
+    turnsUsed: number;
+    /** Prompt-cache reads summed over the loop's turns, when the provider reports them (absent = unreported, never zero). */
+    cacheReadTokens?: number;
+}
+interface LLMToolCall {
+    /** Provider-specific call ID (for sendToolResult) */
+    id?: string;
+    name: string;
+    input: JsonObject;
+}
+interface LLMToolCallResponse {
+    toolCalls: LLMToolCall[];
+    inputTokens: number;
+    outputTokens: number;
+    /**
+     * The tool-choice mode the provider ACTUALLY received. Callers ask
+     * for `'required'` (Anthropic `tool_choice: any`); Claude Fable 5.1 and
+     * Opus 5.5 reject forced tool choice with HTTP 400, so the Anthropic
+     * and OpenRouter adapters downgrade to `'auto'` for those families and
+     * report it here. A
+     * downgraded call may legitimately return zero tool calls — the
+     * evaluator's `criteriaCoverage` records that as `skipped`, never as
+     * a pass. Absent = predates the field (treat as unknown).
+     */
+    appliedToolChoice?: 'required' | 'auto';
+    /**
+     * Tokens read from / written to the prompt cache, when the provider
+     * reports them. Optional because not every provider exposes
+     * prompt-cache accounting — absent means "unreported", never zero.
+     */
+    cacheReadTokens?: number;
+    cacheCreationTokens?: number;
+}
+/** Result of executing a tool — passed to sendToolResult to close the API contract. */
+interface LLMToolResult {
+    /** Tool call ID from the response (for providers that need it) */
+    callId?: string;
+    /** Tool name */
+    name: string;
+    /** Text result of executing the tool */
+    result: string;
+    /** Whether the tool execution failed */
+    isError?: boolean;
+}
+declare abstract class LLMAgent {
+    abstract readonly provider: AgentConfig['provider'];
+    private client;
+    protected lastSessionId: string | undefined;
+    /**
+     * Explicit per-call routing override — see `AgentConfig.routeOverride`.
+     * Absent when constructed via the bare `new XAgent()` form (every
+     * existing call site), so `createClient()`/`resolveModel()` fall
+     * back to `process.env` exactly as before.
+     */
+    protected readonly routeOverride: AgentConfig['routeOverride'];
+    /** See `AgentConfig.onRetry` (#489). Absent is a no-op. */
+    protected readonly onRetry: AgentConfig['onRetry'];
+    constructor(routeOverride?: AgentConfig['routeOverride'], onRetry?: AgentConfig['onRetry']);
+    protected abstract resolveModel(model: string): string;
+    protected abstract createClient(): Promise<unknown>;
+    protected getClient<T>(): Promise<T>;
+    /** Text-only call — no tools */
+    abstract callText(model: string, systemPrompt: string, userPrompt: string, maxTokens?: number, temperature?: number): Promise<LLMResponse>;
+    /**
+     * Single-turn function calling — returns tool calls without executing them.
+     * Each provider uses its native function/tool calling:
+     *   - Anthropic: tool_use blocks
+     *   - OpenAI: function_call output items
+     *   - Google: functionCall parts
+     * SDK handles JSON escaping — safe for code, diffs, and other content.
+     */
+    abstract callTools(model: string, systemPrompt: string, userPrompt: string, tools: LLMToolDef[], toolChoice?: 'required' | 'auto', 
+    /**
+     * Optional scoped fallback tools. If the primary tools fail with a
+     * transport-class error (e.g. `malformed_tool_call` on Gemini after
+     * retry exhaustion), the provider may retry once with these narrower
+     * tools before throwing. Universal signal — not provider-gated.
+     */
+    scopedTools?: LLMToolDef[]): Promise<LLMToolCallResponse>;
+    /** Multi-turn agentic loop — executes tools internally */
+    abstract callWithTools(model: string, systemPrompt: string, userPrompt: string, tools: LLMTool[], maxTurns: number): Promise<LLMWithToolsResponse>;
+    /**
+     * Pre-warm cache for repeated callTools() calls with the same system prompt + tools.
+     * Override in providers that support server-side context caching (e.g., Google).
+     * No-op by default (Anthropic/OpenAI handle caching automatically per-request).
+     */
+    warmCache(_model: string, _systemPrompt: string, _tools: LLMToolDef[], _toolChoice?: 'required' | 'auto'): Promise<void>;
+    /** Cleanup any cached resources. Call after generation completes. No-op by default. */
+    cleanup(): Promise<void>;
+    /** Reset session state between independent generation runs. */
+    resetSession(): void;
+    /**
+     * Send tool execution results back to the provider to close the API contract.
+     * Call this after executing tools from callTools() and before the next callTools().
+     *
+     * For providers with server-side state (Google, OpenAI), this sends the
+     * function results so the next callTools() can chain properly.
+     * For stateless providers (Anthropic), this is a no-op.
+     *
+     * Override in providers that need it.
+     */
+    sendToolResult(_results: LLMToolResult[]): Promise<void>;
+    /**
+     * Execute an API call, retrying once or twice on HTTP 429
+     * (rate-limited) before giving up (#489).
+     *
+     * Policy: on a 429, honor the provider's `Retry-After` header when
+     * present (capped at `RETRY_AFTER_CAP_SEC` — a provider asking for a
+     * longer wait is treated as "don't retry", not "wait longer": making
+     * the caller sit through 15+ more seconds on a single failed call is
+     * a bad experience regardless of what's driving the request);
+     * otherwise fall back to exponential backoff with jitter, capped at
+     * `DEFAULT_BACKOFF_MAX_MS` per attempt. Stops after
+     * `MAX_RETRY_ATTEMPTS` retries OR once the cumulative delay would
+     * exceed `MAX_TOTAL_RETRY_DELAY_MS`, whichever comes first. Any
+     * non-429 error, or a 429 with no attempts left, is logged and
+     * re-thrown immediately — unchanged from the pre-#489 behavior.
+     *
+     * **Budget scope (final-review correction):** `MAX_TOTAL_RETRY_DELAY_MS`
+     * bounds a single `apiCall()` invocation, not a whole generation. A
+     * generation issues many sequential `apiCall()` calls (coding turns,
+     * tool-result round-trips, eval rounds); under sustained throttling
+     * each one can independently add up to `MAX_TOTAL_RETRY_DELAY_MS`, so
+     * a generation with k rate-limited calls can add up to roughly `k *
+     * MAX_TOTAL_RETRY_DELAY_MS` to how long it holds its caller's
+     * resources (e.g. the caller's concurrency slot) — not a flat 20s
+     * ceiling. No shared per-generation budget is threaded here by
+     * design (accepted ruling, not an oversight): the caller's own
+     * queue/admission backstop is what bounds how long other
+     * queued work waits, independent of any one generation's retry
+     * total.
+     */
+    protected apiCall<T>(fn: () => Promise<T>): Promise<T>;
+}
+/**
+ * Create a fresh agent instance for the given provider.
+ * Each call returns a new instance — no shared state between callers.
+ *
+ * Accepts either a bare provider string (every pre-existing call
+ * site — the agent falls back to reading its provider's env var(s)
+ * directly) or a full {@link AgentConfig}, whose `routeOverride`
+ * (when present) is threaded into the constructed agent so it never
+ * touches `process.env`.
+ */
+declare function createAgent(provider: AgentConfig['provider']): LLMAgent;
+declare function createAgent(config: AgentConfig): LLMAgent;
+/** Providers whose agent implements {@link VisionAgent}. */
+type VisionProvider = 'anthropic' | 'google';
+declare function callLLM(config: AgentConfig, systemPrompt: string, userPrompt: string, maxTokens?: number): Promise<LLMResponse>;
+
+type Priority = "P0" | "P1" | "P2";
+
+type EvalTier = 0 | 1 | 2;
+type EvalOutcome = "fail" | "warn" | "pass";
+type EvalCategory = "compile" | "security" | "contract" | "types" | "imports" | "tokens" | "mode" | "functionality" | "crash" | "interactivity" | "accessibility" | "layout" | "loading" | "visual";
+interface EvalIssue {
+    tier: EvalTier;
+    result: EvalOutcome;
+    category: EvalCategory;
+    /**
+     * Priority tier — threaded through to the retry formatter so the LLM can
+     * rank its next patch against the prompt's P0/P1/P2 priority schema.
+     * Derived from (category, result) via {@link priorityForIssue} when not
+     * explicitly set. Optional on construction; check-runners typically
+     * populate it before returning.
+     */
+    priority?: Priority;
+    subcategory?: string;
+    severity?: "critical" | "major";
+    description: string;
+    fix: string;
+    line?: number;
+    /**
+     * The visual leg's provenance (ggui#1545): `judge` (the model's finding) or `instrument` (a deterministic
+     * measurement). Absent on every other leg's issues. `visualEvaluation.actOn` acts on `judge` only.
+     */
+    origin?: "judge" | "instrument";
+}
+/**
+ * Runtime-render probe execution status — four-valued so "the probe
+ * never ran" is never conflated with "the probe ran clean". ONE union: the
+ * same values a generation's metadata reports (`GenerationRuntimeProbeStatus`
+ * in `@ggui-ai/mcp-server-core`), declared there and named here.
+ *
+ *   - `ran`           — probe executed; its findings (possibly none) are
+ *                       in the issue stream under `runtime:*` subcategories.
+ *   - `infra-skipped` — probe could NOT execute (environment failure:
+ *                       happy-dom load, user-event document capture,
+ *                       ESM/CJS interop). Carries ZERO probe evidence;
+ *                       consumers MUST NOT count it as a pass.
+ *   - `not-applicable`— nothing to probe (no compiled code, no contract
+ *                       surface, or no runtimeRender check configured).
+ *   - `timed-out`     — probe started but did not finish inside its
+ *                       wall-clock bound (ggui#1299). Carries ZERO
+ *                       evidence about the component: on a contended
+ *                       host an ordinary component crosses the bound.
+ *                       Consumers MUST NOT count it as a pass, and MUST
+ *                       NOT count it as a crash either. `elapsedMs` and
+ *                       `hostLoad` say how long it ran and how busy the
+ *                       host was, so a reader can tell the two cases apart.
+ */
+type RuntimeProbeStatus = GenerationRuntimeProbeStatus;
+/**
+ * The host's 1-minute load average at a probe's start and end, beside the
+ * number of CPUs the process can use (ggui#1299). A load well above
+ * `cores` means the probe competed for CPU; a wall-clock bound crossed
+ * there says more about the host than about the component.
+ */
+interface ProbeHostLoad {
+    readonly start: number;
+    readonly end: number;
+    readonly cores: number;
+}
+/**
+ * ggui#1398 — whether the controls the probe clicked showed they were
+ * working once their action was pending. Report-only: it is read by the
+ * benchmark and never counted into the probe's warnings or fed back to
+ * the coding loop.
+ */
+interface ProbePendingAffordance {
+    /** Controls the pending phase marked pending: those whose click dispatched their action (click or submit wiring) and that were still in the page. `visible + missing.length === dispatched`. */
+    readonly dispatched: number;
+    /** Of those, how many visibly changed while pending (disabled, busy, text, or replaced). */
+    readonly visible: number;
+    /** The actions whose control did not visibly change, including one whose card threw while pending. */
+    readonly missing: readonly string[];
+    /** Actions whose control was no longer in the page when its turn came (the card replaced it, or blanked after a throw): never marked, not counted as dispatched. */
+    readonly gone: readonly string[];
+}
+/**
+ * The engine's own fields on a probe's meta, beside the outcome a
+ * generation's metadata reports: why a probe did not finish, its render
+ * time, the host's load around it. Present on every arm of
+ * {@link RuntimeProbeMeta}; each is absent when the probe had nothing to
+ * say about it.
+ */
+interface RuntimeProbeMetaDetail {
+    /** Populated for `infra-skipped` / `not-applicable` / `timed-out` — why the probe didn't finish. */
+    readonly reason?: string;
+    /** `ran` only: the check's own render time, inside `elapsedMs`. */
+    readonly renderMs?: number;
+    /** Host load around the probe, when it ran isolated (absent for an in-process probe). */
+    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). Absent when no
+     * action walk ran, so "no data" and "0 of 0" read differently.
+     */
+    readonly pendingAffordance?: ProbePendingAffordance;
+}
+/**
+ * Probe execution meta stamped onto an `EvalResult` at the exit-decision
+ * points that invoke the probe. Absence of this field means the eval
+ * path never reached a probe invocation at all — consumers treat that
+ * the same as not-run, never as a pass.
+ *
+ * ONE union with the generation metadata's probe outcome
+ * (`GenerationRuntimeProbeOutcome` in `@ggui-ai/mcp-server-core`, declared
+ * there and carried here with {@link RuntimeProbeMetaDetail} on every arm),
+ * so the round's stamp and the metadata's record cannot say different
+ * things (ggui#1380):
+ *
+ *   - `ran` + `verdict: 'pass'` — the probe executed and no check failed;
+ *   - `ran` + `verdict: 'fail'` — ANY check failed; `failChecks` lists the
+ *     distinct check kinds that did (`RenderCheckKind`, the engine's name
+ *     for the same union), never empty, in the order `RENDER_CHECK_KINDS`
+ *     declares them, parsed from the probe's own
+ *     `runtime:<check>[:<subject>]` issues;
+ *   - `timed-out` / `infra-skipped` / `not-applicable` — no verdict, and the
+ *     type carries none. `elapsedMs` (on every status that reached the
+ *     check) and `hostLoad` say how long it ran and how busy the host was.
+ *
+ * The verdict and the repair trigger are two different questions. The
+ * verdict is `fail` on any failing check. The one repair turn a probe-only
+ * round buys fires on a `render-no-throw` fail the engine recognises
+ * (`isRecoverableRenderCrash`) and on nothing else: on the PROBE-ONLY round a
+ * `fail` verdict whose checks are `prop-sensitivity`, `action-wiring` or any
+ * other kind is recorded here and never fed back. The same meta is stamped on
+ * the EVALUATION lane, where a `prop-sensitivity` fail buys that lane's own
+ * contract-feedback round (ggui#1261, `FEEDBACK_PROBE_CHECKS`) — a different
+ * turn under a different rule, not the repair turn.
+ */
+type RuntimeProbeMeta = GenerationRuntimeProbeOutcome & RuntimeProbeMetaDetail;
+/**
+ * The one repair turn a probe-only round buys (ggui#1380). A serving
+ * deployment that wires the runtime probe and configures no evaluator runs
+ * the probe once after the coding turns; a render crash the engine
+ * recognises buys exactly one repair turn, then one re-probe. This records
+ * what came of it:
+ *   - `compiled: false` — the repair turn's code did not pass self-check, so
+ *     no re-probe ran (there is no `after`) and the pre-repair card is the
+ *     one served;
+ *   - `compiled: true` — the re-probe ran and `after` is its whole meta:
+ *     its status, its verdict when it ran, and the checks that still fail.
+ *     Whether the crash class the turn was bought for is still there is
+ *     `after.verdict === 'fail' && after.failChecks.includes('render-no-throw')`.
+ * The two arms are exclusive by type.
+ */
+type RuntimeProbeRepair = {
+    readonly attempted: true;
+    readonly compiled: false;
+    readonly trigger?: never;
+} | {
+    readonly attempted: true;
+    readonly compiled: true;
+    readonly trigger: RuntimeProbeMeta;
+};
+/**
+ * Per-criterion execution status — three-valued so "the criterion
+ * silently produced no verdict" is never conflated with "the criterion
+ * ran clean", and neither is conflated with "not evaluated by design".
+ * Same doctrine and vocabulary family as `RuntimeProbeStatus` above.
+ *
+ *   - `ran`            — the LLM call completed and returned a verdict
+ *                        for this criterion; its findings (possibly
+ *                        none) are in `issues`.
+ *   - `skipped`        — the call errored or returned no tool call. The
+ *                        criterion carries ZERO evidence; the evaluator
+ *                        fail-opens it into `pass` to avoid blocking
+ *                        generation on flaky LLM calls, so consumers
+ *                        MUST consult this field before treating `pass`
+ *                        membership as a verdict. Counts AGAINST
+ *                        coverage.
+ *   - `not-applicable` — the evaluator was bypassed by design for this
+ *                        cell (e.g. the same-image low-risk bypass:
+ *                        axis checks clean, tier-1/2 never invoked).
+ *                        `reason` names the bypass. Excluded from
+ *                        coverage denominators — it is neither evidence
+ *                        nor a silent absence.
+ */
+type CriterionRunStatus = "ran" | "skipped" | "not-applicable";
+/** Coverage row for one evaluation criterion of one eval run. */
+interface CriterionCoverage {
+    readonly criterion: string;
+    readonly tier: 1 | 2;
+    readonly status: CriterionRunStatus;
+    /** Populated for `skipped` / `not-applicable` — why no verdict. */
+    readonly reason?: string;
+}
+/**
+ * Coverage of the screenshot JUDGE leg for one eval round (ggui#1221) — a
+ * different surface from the `visual` CRITERION in `criteriaCoverage` (the
+ * LLM evaluator's read of the source). `ran` = a frame was captured and
+ * judged; `skipped` = the leg was configured but produced no verdict
+ * (no browser, a launch or in-page failure, an unbundlable component, an
+ * unparsable judge answer) with `reason` naming why; `not-applicable` =
+ * the round had no visual leg configured. Before this row a skipped leg
+ * left NO trace on the result — `{ issues: [] }` read exactly like a
+ * clean run, and every bootstrap mint on a browserless runtime "passed"
+ * its visual round that way.
+ */
+interface VisualCoverage {
+    readonly status: CriterionRunStatus;
+    /** Populated for `skipped` / `not-applicable` — why no verdict. */
+    readonly reason?: string;
+}
+/**
+ * The static criteria `runLLMEvaluation` runs, in stamp order — the
+ * ONE list both the evaluator's coverage stamp and the harness's
+ * bypass stamp derive from, so the two can never disagree on the set.
+ * Tier 1 = binary pass/fail gates; tier 2 = fail/warn/pass quality.
+ */
+declare const LLM_EVAL_STATIC_CRITERIA: ReadonlyArray<{
+    readonly criterion: string;
+    readonly tier: 1 | 2;
+}>;
+/**
+ * Coverage rows for a cell where the evaluator was BYPASSED BY DESIGN
+ * (never invoked) — one `not-applicable` row per static criterion, all
+ * carrying `reason`. Harness exits that skip tier-1/2 evaluation stamp
+ * this so the cell is neither a silent absence (field missing) nor
+ * evidence. Same shape contract as `runLLMEvaluation`'s stamp: always
+ * every criterion. Lives here (not in llm-evaluator) because the bypass
+ * exit runs before the evaluator module is lazily loaded.
+ */
+declare function notApplicableCoverage(reason: string): CriterionCoverage[];
+/** One contract-feedback round (ggui#1261): what bought it, and the source it was fed back on. */
+interface ContractFeedbackRecord {
+    /** The exit-probe issue subcategories that bought the round, e.g. `runtime:prop-sensitivity:currentUser`. */
+    readonly firedOn: readonly string[];
+    /** The component source as it stood when the model was told — the round's BEFORE. */
+    readonly sourceBefore: string;
+}
+interface EvalResult {
+    issues: EvalIssue[];
+    pass: string[];
+    /**
+     * Per-criterion coverage for this eval run — one row per static
+     * criterion, ALWAYS all of them when present. Stamped by
+     * `runLLMEvaluation` (`ran` / `skipped`) and by the harness on
+     * evaluator-bypass exits (`not-applicable` + reason). The harness
+     * carries it unchanged through every later re-stamp of this result.
+     * Absent = coverage UNKNOWN (paths that predate the instrument, e.g.
+     * `parseEvalResponse` replays) — never assume `ran`, never assume
+     * bypass.
+     */
+    criteriaCoverage?: CriterionCoverage[];
+    /**
+     * Runtime-render probe execution meta. Stamped by the exit-decision
+     * probe runner; absent on eval paths that never invoke the probe.
+     */
+    runtimeProbe?: RuntimeProbeMeta;
+    /**
+     * The probe-only round's repair record (ggui#1380) — present only when a
+     * recoverable render crash bought the one repair turn. See
+     * {@link RuntimeProbeRepair}. `runtimeProbe` beside it is the re-probe's
+     * verdict when the repair compiled, else the pre-repair probe's.
+     */
+    runtimeProbeRepair?: RuntimeProbeRepair;
+    /**
+     * The contract-feedback round, when one fired this generation (ggui#1261):
+     * which exit-probe findings bought it and the source as it stood when the
+     * model was told. `runtimeProbe` and the `runtime:*` issues on this result
+     * are the probe's verdict AFTER that round; `sourceBefore` beside the final
+     * source is the round's before/after. Absent when no such round fired.
+     */
+    contractFeedback?: ContractFeedbackRecord;
+    /**
+     * Per-canvas visual verdicts. Stamped by the harness ONLY when the
+     * visual leg ran with `visualEvaluation.canvases` set (arm-neutral —
+     * the same judge in every design mode); absent on the single-shot
+     * visual path and whenever the visual leg did not run. PNGs stay on
+     * `runVisualEvaluation`'s own result (`VisualEvaluationResult.canvases[*].screenshotPng`),
+     * never here — this object is serialized into reports.
+     */
+    visual?: VisualEvalSummary;
+    /**
+     * Whether the screenshot judge leg ran, was skipped (with the reason) or
+     * was not configured — ALWAYS stamped by the harness's eval round
+     * (ggui#1221), so a consumer can tell a clean visual run from a leg
+     * that silently could not run. See {@link VisualCoverage}.
+     */
+    visualCoverage?: VisualCoverage;
+}
+/** One canvas's visual verdict, PNG-free — see `EvalResult.visual`. */
+/**
+ * How one canvas's `score` was reached (ggui#1072): `k` vision calls on the
+ * SAME captured frame, aggregated by `rule`. Always present — `k: 1` ⇒
+ * `samples: [score]`, `sigma: 0`, `notes: [critique]` — so one shape serves
+ * a single judgement and a median of many. `samples`/`notes` carry only the
+ * calls the judge could parse (in call order); `k` stays the requested count,
+ * so a short `samples` is visible on the row rather than filled in.
+ */
+interface CanvasJudgeRecord {
+    readonly k: number;
+    readonly rule: 'median';
+    readonly samples: number[];
+    /** Population σ of `samples` (0 when one sample). */
+    readonly sigma: number;
+    /** The judge's per-canvas critique per sample — the words beside a swing. */
+    readonly notes: string[];
+    /**
+     * ggui#1127 — the cause of each scoring sample whose answer failed to parse and was SALVAGED: its four dimensions
+     * were recovered from the closed prefix, its issues kept only as far as they closed, its critique lost. One entry
+     * per salvaged sample; absent when every sample parsed. The salvaged sample's score still counts.
+     */
+    readonly salvaged?: readonly JudgeSalvageCause[];
+    /**
+     * ggui#1127 — the criteria call's answer was salvaged. A salvage keeps no criteria, so that frame's judge rows read
+     * "not answered" with this cause rather than a clean `n/a`. Absent when the call parsed or was not asked.
+     */
+    readonly criteriaSalvaged?: JudgeSalvageCause;
+    /**
+     * ggui#1687 — the model asked for, and every model the provider said answered this canvas's calls (scoring and
+     * criteria), deduplicated. `served` is empty when no provider named one: unknown, never "the requested model".
+     */
+    readonly models?: {
+        readonly requested: string;
+        readonly served: readonly string[];
+    };
+}
+/**
+ * ggui#1687 — what the criteria call's answer held, before resolution. A row the judge left unanswered reads `n/a`
+ * either way; this says whether the call came back empty, cut, or with entries the parser had to drop.
+ */
+interface CriteriaAnswerCounts {
+    /** The answer carried a `criteria` array. `false`: absent or not an array, so no row was read from it. */
+    readonly array: boolean;
+    /** Entries in the array. */
+    readonly received: number;
+    /** Entries kept: an object with a string id and a verdict of pass, fail or n/a. */
+    readonly kept: number;
+    /** Entries dropped, by why. */
+    readonly dropped: {
+        readonly notObject: number;
+        readonly badId: number;
+        readonly badVerdict: number;
+    };
+}
+/**
+ * ggui#1127 — why a judge answer that failed to parse had to be salvaged. `output-cap`: the provider reported it
+ * stopped at the output cap. `malformed`: the provider reported a normal stop, so the answer ended but did not
+ * parse. `stopped`: the provider stopped it for another reason it named (a safety stop, or one it reports as
+ * other), so it is cut, not malformed. `unknown`: the provider or route reported no stop reason. Never inferred
+ * from the answer's length.
+ */
+type JudgeSalvageCause = "output-cap" | "malformed" | "stopped" | "unknown";
+/** ggui#1127 — salvaged judge answers across a canvas run, per leg, as N of M. */
+interface JudgeSalvageCounts {
+    /** Scoring answers: `answers` = samples that parsed or were salvaged, `salvaged` = those salvaged. */
+    readonly scoring: {
+        readonly salvaged: number;
+        readonly answers: number;
+    };
+    /** Criteria calls: `answered` = calls that parsed or were salvaged, `salvaged` = those salvaged (criteria lost). */
+    readonly criteria: {
+        readonly salvaged: number;
+        readonly answered: number;
+    };
+}
+
+type CriteriaSeverity = "must" | "should";
+type CriteriaVerdict = "pass" | "fail" | "n/a";
+/** The method that produces a verdict: an instrument's measurement, the vision judge off the frame, or a person's eye. */
+type CriteriaMethod = "instrument" | "judge" | "human";
+/** The method's readiness, as the bank's author wrote it — the only source of an `n/a` that is not the judge's own. */
+type CriteriaStatus = "live" | "reference" | "planned" | "manual";
+/**
+ * How a criterion entered the selection: bank-level (`static`, an empty scope) or by the selector's
+ * rules for this card (`context`). A model PROPOSING a criterion at judge time is RESERVED and not a
+ * member until a consumer exists — it would be `should`-only, recorded verbatim, never a gate.
+ */
+type CriteriaSource = "static" | "context";
+type CriteriaChroma = "achromatic" | "chromatic" | "unknown";
+/** The classifier's shape axes, as hashed into the set id. */
+interface CriteriaAxes {
+    render: RenderShape;
+    state: StateShape;
+    writes: WriteShape;
+    fetch: FetchShape;
+    layout: LayoutShape;
+}
+/** The selector's inputs, stored with the verdict so a reader recomputes `criteriaSetId` from the record alone. */
+interface CriteriaContext {
+    canvas: CanvasClass;
+    hasActions: boolean;
+    riskTier: RiskTier;
+    axes: CriteriaAxes;
+    chroma: CriteriaChroma;
+    profilePresent: boolean;
+    /** The harness's shell as named; `unknown` when the round carries none. */
+    shell: string;
+    /** The caller's item kind (a bootstrap mint's `hello`); hashed when present. */
+    kind?: string;
+    /** The styling preset in force (the profile's aesthetic id); a recipe is selected only under its preset. */
+    preset?: string;
+}
+/** What was asked and why — recorded BEFORE the judge runs. Omission is the selector's decision. */
+interface CriteriaSelection {
+    id: string;
+    source: CriteriaSource;
+    reason: string;
+}
+/** One criterion's verdict; `n/a` is the judge's answer ("cannot read this off the frame"), an unanswered id, a tie, or a method whose `status` is not live. */
+interface CriterionVerdict {
+    id: string;
+    severity: CriteriaSeverity;
+    method: CriteriaMethod;
+    status: CriteriaStatus;
+    source: CriteriaSource;
+    verdict: CriteriaVerdict;
+    evidence: string;
+    /**
+     * ggui#1663 — a measured reading beside a judge row, REPORT-ONLY: the row's `verdict` stays the judge's, so this
+     * changes no verdict, score or bar. Present only on rows an instrument answers beside the judge (`space.edge`).
+     */
+    instrument?: {
+        verdict: CriteriaVerdict;
+        evidence: string;
+    };
+}
+/** ggui#1687 — the criteria call as it came back: its answer's counts, ids it answered outside the bank, its stop. */
+interface CriteriaCallRecord {
+    readonly answer: CriteriaAnswerCounts;
+    /** Kept entries whose id names no row of the bank. */
+    readonly unknownIds: number;
+    /** The provider's normalized stop reason (`length` = the output cap); absent when it reported none. */
+    readonly finishReason?: VisionFinishReason;
+}
+interface CriteriaBlock {
+    /** sha256(bank version | selector version | canonical context), 16 hex — the block's own digest. */
+    criteriaSetId: string;
+    bankVersion: string;
+    selectorVersion: string;
+    context: CriteriaContext;
+    selection: CriteriaSelection[];
+    verdicts: CriterionVerdict[];
+    /** ggui#1687 — the call that answered this block, when one did. Absent for a block resolved with no call. */
+    call?: CriteriaCallRecord;
+}
+/** The roll-up across canvases; a `must` at `n/a` is listed, never counted as a pass. */
+interface CriteriaRollup {
+    mustFailed: string[];
+    shouldFailed: string[];
+    mustNa: string[];
+}
+/** ggui#1492 — a host"s frame round the inline card, as data. Colours are `#rrggbb`; the ring"s `alpha` is 0..1. */
+interface HostInlineFrame {
+    /** The frame"s surface — what shows behind a transparent card, and under the floor"s residual. */
+    readonly surface: string;
+    /** The room the frame sits in (the page ground round it). */
+    readonly ground: string;
+    readonly ring: {
+        readonly widthPx: number;
+        readonly color: string;
+        readonly alpha: number;
+    };
+    readonly radiusPx: number;
+    /** The host"s minimum frame height: a card shorter than it sits in a frame this tall, and the visitor sees the rest as void. */
+    readonly minHeightPx?: number;
+}
+/** ggui#1492 — how a host presents one canvas: the label the judge is told, the page ground, and (the inline card only) its frame. */
+interface CanvasHostPresentation {
+    readonly label: string;
+    /** The page ground under a fill canvas"s panel; the inline card"s ground lives on its {@link HostInlineFrame}. */
+    readonly ground?: string;
+    readonly frame?: HostInlineFrame;
+}
+/** ggui#1492 — why the judge did not draw a canvas's host presentation. The codes are the lane reader's own. */
+type HostPresentationIgnoredReason = "label_missing" | "color_not_hex" | "frame_off_inline" | "frame_malformed" | "ground_on_inline";
+/**
+ * ggui#1492 — what the judge DID with a canvas's host presentation, read from the judge itself: `applied` carries
+ * the presentation it drew, `ignored` the reason it drew none. Absent when the caller supplied no presentation.
+ */
+type CanvasPresentationOutcome = {
+    readonly status: "applied";
+    readonly applied: CanvasHostPresentation;
+} | {
+    readonly status: "ignored";
+    readonly reason: HostPresentationIgnoredReason;
+};
+interface CanvasVisualSummary {
+    canvas: CanvasClass;
+    viewport: {
+        width: number;
+        height: number;
+    };
+    /** The judge's weighted score at this canvas (0-100). */
+    score: number;
+    /** `score >= passThreshold`, and on the inline card: no overflow (ggui#1027). */
+    passed: boolean;
+    /** The document's scroll height at this canvas, CSS px; `null` when unmeasurable (ggui#1027). */
+    contentHeight: number | null;
+    /** `contentHeight > viewport.height` — measured on every canvas, judged per `canvasFitPolicy`. */
+    overflow: boolean;
+    /**
+     * ggui#1120 — how far down the capture anything was painted: the last inked row over the measured
+     * region's height (inside a drawn host panel's chrome on md/lg/xl), read from the screenshot's
+     * pixels against their dominant colour. `0` is the blank the judge fails (`canvas-blank`); every
+     * other value is reported, never scored. `null` when the capture could not be read.
+     */
+    inkRatio: number | null;
+    /** How `score` was reached — always present (ggui#1072). */
+    judge: CanvasJudgeRecord;
+    /** ggui#1436 — the typed criteria block, when a bank was configured; report-only. */
+    criteria?: CriteriaBlock;
+    /** ggui#1492 — what the judge did with this canvas's host presentation, when one was supplied. */
+    presentation?: CanvasPresentationOutcome;
+    /**
+     * How the judge composed the mount (ggui#1100): `'fill'` on every
+     * fullscreen canvas — the served runtime's fit, the root stretched to
+     * the frame; absent on the inline card, which keeps its natural height.
+     */
+    fit?: 'fill';
+}
+/**
+ * ggui#1195 — the fit reading on the canvas whose policy FAILS an overflow
+ * (the inline chat card): the box it was judged at (`ceiling` — the order's
+ * declared viewport when one was carried, else the class box), whether that
+ * box was declared, and how many px of content sit below it (0 = fits).
+ * Present only when such a canvas was judged with a measurable height, so
+ * the bar and the ledger read one number for "does the hello fit".
+ */
+interface VisualFitStamp {
+    readonly canvas: CanvasClass;
+    readonly ceiling: {
+        readonly width: number;
+        readonly height: number;
+    };
+    readonly declared: boolean;
+    readonly overflowPx: number;
+}
+/** The visual leg's per-canvas summary — see `EvalResult.visual`. */
+interface VisualEvalSummary {
+    /** Mean of the canvas scores (rounded). */
+    score: number;
+    /** Every canvas passed. */
+    passed: boolean;
+    canvases: CanvasVisualSummary[];
+    /** ggui#1195 — see {@link VisualFitStamp}; absent when no fail-policy canvas was judged. */
+    fit?: VisualFitStamp;
+    /** The design tree the judge painted with (ggui#1042): `src` + `srcSha256` — `design@judge`. */
+    design?: {
+        readonly src: string;
+        readonly srcSha256: string;
+    };
+    /** The mode the judge's tokens were composed in, when the caller said (ggui#1076). */
+    themeMode?: 'light' | 'dark';
+    /** ggui#1436 — the criteria roll-up across canvases, when any canvas carries a block; report-only. */
+    criteria?: CriteriaRollup;
+}
+type QualityMode = "fast" | "auto-improve" | "high-quality";
+interface QualityConfig {
+    quality: QualityMode;
+    visualEval: boolean;
+    maxCostPerGeneration: number;
+    model?: {
+        provider?: string;
+        model?: string;
+    };
+}
+declare const DEFAULT_QUALITY_CONFIG: QualityConfig;
+
+interface AxisCheckInput {
+    sourceCode: string;
+    compiledCode: string | null;
+    contract?: DataContract;
+    originalPrompt: string;
+    /** Full classification — checks may read sibling axes. */
+    classification: Classification;
+    /**
+     * Which triad produced the source. Checks that assert a design-package
+     * component (e.g. `layout.multi_step.stepper_adopted`) read it and
+     * stand down in `free` mode, where the primitive is optional. Absent
+     * means `constrained`.
+     */
+    designMode?: DesignMode;
+    /**
+     * The rendering canvas the source is judged FOR (ggui#1117). A width cap on
+     * the outermost element is a defect on a fullscreen canvas and a no-op in a
+     * chat bubble, so a check that reads width must know the surface. Populated
+     * where the harness is built (`Harness.canvas`); ABSENT for callers with no
+     * rendering context — a check handles `undefined`, it never assumes a
+     * default (a silent `lg` would be the same guess with a nicer face).
+     */
+    canvas?: CanvasClass;
+    /**
+     * The props the probe and the judge RENDERED the source with (ggui#1285) — a bootstrap order's
+     * `sampleProps`, the bench commit's fixture. They are judging data, not the request: a literal in
+     * the source that equals one of these values, and that the request never stated, is baked copy a
+     * visitor sees whenever the agent leaves the prop out. Populated on the served loop and at
+     * auto-commit; ABSENT where the caller has none — the check stands down, it never guesses.
+     */
+    fixtureProps?: JsonObject;
+}
+/**
+ * A gated check. Runs only when the classification's axis value matches
+ * one of the gate's accepted values. Multiple gates (implicit AND) support
+ * cross-axis combinations.
+ */
+interface AxisCheck {
+    /** Stable id used in issue subcategories. */
+    id: string;
+    /** Primary axis this check gates on. */
+    axis: AxisKey;
+    /** Which values of that axis activate the check. */
+    values: readonly string[];
+    /** Optional extra gate on a sibling axis (e.g., only when state=merge AND writes=per-item). */
+    and?: {
+        axis: AxisKey;
+        values: readonly string[];
+    };
+    /** Execute the check and emit zero or more issues. */
+    run(input: AxisCheckInput): EvalIssue[];
+}
+/**
+ * Whether a check's gate(s) match the given axis vector. Pure function,
+ * no issue emission.
+ */
+declare function matches(vector: AxisVector, check: AxisCheck): boolean;
+/**
+ * Map a tier-0 issue category to the canonical P0/P1/P2 priority.
+ *
+ * Sourced from the criteria priority assignments:
+ *   - P0 (must): compile, security, imports, contract, types, mode
+ *   - P1 (safety): tokens, crash, functionality
+ *   - P2 (quality): interactivity, accessibility, layout, loading, visual
+ */
+declare function priorityForIssue(category: EvalCategory): Priority;
+/** Whether any issue blocks shipping (has result = 'fail'). */
+declare function isBlocked(result: EvalResult): boolean;
+/**
+ * Return the issues the agent should act on, depending on quality mode.
+ * - fast: only fails (blocking issues)
+ * - auto-improve / high-quality: fails + warns
+ */
+declare function getActionableIssues(result: EvalResult, mode: QualityMode): EvalIssue[];
+interface EvalCriterion {
+    /** Unique identifier matching the eval tool name (e.g., 'functionality') */
+    id: string;
+    /** Human-readable name shown to both agents */
+    name: string;
+    /** Priority tier — P0 must, P1 should, P2 nice */
+    priority: Priority;
+    /** What the coding agent should DO to satisfy this criterion */
+    codingGuidance: string;
+    /** What the eval agent should CHECK — the evaluation prompt */
+    evalInstruction: string;
+    /** Tier 0 = programmatic, Tier 1 = LLM critical, Tier 2 = LLM quality */
+    tier: 0 | 1 | 2;
+    /** Eval outcome when this criterion fails */
+    failOutcome: "fail" | "warn";
+}
+declare const CRITERIA: readonly EvalCriterion[];
+/**
+ * The criteria registry for a design mode. `constrained` IS `CRITERIA`
+ * (same array, byte-identical summary); `free` swaps in the two
+ * overrides above by id, preserving order.
+ */
+declare function criteriaFor(designMode?: DesignMode): readonly EvalCriterion[];
+/** Get all criteria for a specific priority level */
+declare function getCriteriaByPriority(priority: Priority, designMode?: DesignMode): EvalCriterion[];
+/** Get a specific criterion by ID */
+declare function getCriterionById(id: string, designMode?: DesignMode): EvalCriterion | undefined;
+/** Get all LLM-evaluated criteria (tier 1 + 2) */
+declare function getLLMCriteria(designMode?: DesignMode): EvalCriterion[];
+/**
+ * Build the coding agent's criteria summary from the single source of truth.
+ * Grouped by priority for the P0→P1→P2 hierarchy.
+ */
+declare function buildCodingCriteriaSummary(designMode?: DesignMode): string;
+
+export { type AxisCheck as A, type EvalOutcome as B, type CriteriaAnswerCounts as C, DEFAULT_QUALITY_CONFIG as D, type EvalIssue as E, type HostPresentationIgnoredReason as F, LLM_EVAL_STATIC_CRITERIA as G, type HostInlineFrame as H, type Priority as I, type JudgeSalvageCounts as J, type QualityMode as K, type LLMResponse as L, buildCodingCriteriaSummary as M, criteriaFor as N, getActionableIssues as O, type ProviderRetryInfo as P, type QualityConfig as Q, type RuntimeProbeStatus as R, getCriteriaByPriority as S, getCriterionById as T, getLLMCriteria as U, type VisionProvider as V, isBlocked as W, notApplicableCoverage as X, priorityForIssue as Y, type AxisCheckInput as a, type AgentConfig as b, callLLM as c, createAgent as d, type EvalResult as e, type ProbeHostLoad as f, type ProbePendingAffordance as g, type CriteriaContext as h, type CriteriaChroma as i, type CanvasJudgeRecord as j, type CriteriaBlock as k, type CanvasPresentationOutcome as l, matches as m, type CanvasHostPresentation as n, type VisualEvalSummary as o, type VisualCoverage as p, type EvalTier as q, type CriteriaSelection as r, type VisionFinishReason as s, CRITERIA as t, type CanvasVisualSummary as u, type ContractFeedbackRecord as v, type CriterionCoverage as w, type CriterionRunStatus as x, type EvalCategory as y, type EvalCriterion as z };