@ggui-ai/ui-gen 0.9.0 → 0.10.0

package/dist/harness/index.d.ts

@@ -1,7 +1,7 @@
 import { Harness } from './types-public.js';
 export { CheckLeg, CheckResult, CreateHarnessInput, DefaultTaskRunner, HarnessConstructionContext, HarnessId, HarnessMeta, HarnessName, HarnessOverrides, HarnessRevision, HowLeg, IterationRecord, LLMEvaluator, PatchFn, Phase, PhaseRunResult, PlannerDecision, PlannerFn, ProcessLeg, PromptBuilder, RetryPolicy, RunCheckInput, RunHarnessInput, RunHarnessReason, RunHarnessResult, RunWorkflowInput, Task, TaskContext, TaskRunner, TierCheck, WhatLeg, Workflow, WorkflowRunResult, createHarness, runCheck, runHarness, runWorkflow } from './types-public.js';
 export { applyLineRanges, defaultApplyPatch } from '../patch.js';
-export { A as AgentConfig, L as LLMResponse, c as callLLM, a as createAgent } from '../llm-router-1TyI0_TV.js';
+export { A as AgentConfig, L as LLMResponse, P as ProviderRetryInfo, c as callLLM, a as createAgent } from '../llm-router-BEVtbAb9.js';
 export { WORKFLOWS, WorkflowId, pickWorkflow } from '../workflows.js';
 export { LlmTraceEvent, LlmTraceKind, LlmTraceProvider, LlmTraceSink, getLlmTraceSink, setLlmTraceSink } from './llm-trace-sink.js';
 export { ValidatorTraceEvent, ValidatorTraceSink, getValidatorTraceSink, setValidatorTraceSink } from './validator-trace-sink.js';
@@ -9,7 +9,7 @@ export { ProcessMode } from '../policy.js';
 export { computeHarnessId, computeHarnessName, hashClassification } from '../hash.js';
 import '@ggui-ai/protocol';
 import '../axes-CzLEMDeB.js';
-import '../types-public-C36k1q6s.js';
+import '../types-public-DIpjC-OA.js';
 import '../types-BOvHNG7K.js';
 import '../llm.js';
 

package/dist/harness/index.js

@@ -27,14 +27,16 @@ var OpenRouterError;
 var init_types = __esm({
   "src/adapters/openrouter/types.ts"() {
     OpenRouterError = class extends Error {
-      constructor(message, status, code) {
+      constructor(message, status, code, headers) {
         super(message);
         this.status = status;
         this.code = code;
+        this.headers = headers;
         this.name = "OpenRouterError";
       }
       status;
       code;
+      headers;
       get isTransient() {
         return this.status === 408 || this.status === 429 || this.status === 502 || this.status === 503;
       }
@@ -79,7 +81,7 @@ var init_client = __esm({
         if (!response.ok) {
           const errorBody = await response.json().catch(() => ({ error: { message: response.statusText } }));
           const message = errorBody.error?.message ?? response.statusText;
-          throw new OpenRouterError(message, response.status);
+          throw new OpenRouterError(message, response.status, void 0, response.headers);
         }
         return response.json();
       }
@@ -97,7 +99,7 @@ var init_client = __esm({
         if (!response.ok) {
           const errorBody = await response.json().catch(() => ({ error: { message: response.statusText } }));
           const message = errorBody.error?.message ?? response.statusText;
-          throw new OpenRouterError(message, response.status);
+          throw new OpenRouterError(message, response.status, void 0, response.headers);
         }
         if (!response.body) {
           throw new OpenRouterError("No response body for streaming request", 500);
@@ -883,6 +885,15 @@ function jsonSchemaTypeToTs(schema) {
   if (schema.enum?.length) {
     return schema.enum.map((v) => typeof v === "string" ? `'${v}'` : String(v)).join(" | ");
   }
+  if (Array.isArray(schema.type)) {
+    const { nullable: _nullable, ...rest } = schema;
+    const members = [...new Set(schema.type)].map(
+      (member) => jsonSchemaTypeToTs({ ...rest, type: member })
+    );
+    const unique = [...new Set(members)];
+    if (schema.nullable && !unique.includes("null")) unique.push("null");
+    return unique.join(" | ");
+  }
   let result;
   switch (schema.type) {
     case "string":
@@ -900,7 +911,8 @@ function jsonSchemaTypeToTs(schema) {
     case "array": {
       if (schema.items) {
         const itemType = jsonSchemaTypeToTs(schema.items);
-        result = schema.items.type === "object" && schema.items.properties ? `Array<${itemType}>` : itemType.includes("|") ? `(${itemType})[]` : `${itemType}[]`;
+        const itemsDeclareObject = Array.isArray(schema.items.type) ? schema.items.type.includes("object") : schema.items.type === "object";
+        result = itemsDeclareObject && schema.items.properties ? `Array<${itemType}>` : itemType.includes("|") ? `(${itemType})[]` : `${itemType}[]`;
       } else {
         result = "unknown[]";
       }
@@ -1033,13 +1045,14 @@ function generateBoilerplate(_userPrompt, contract, shellType, screen, composedS
   const propsFields = [];
   const propsProperties = contract?.propsSpec?.properties ?? {};
   for (const [key, entry] of Object.entries(propsProperties)) {
-    const required = entry.required !== false;
+    const required = entry.required === true;
     const nullable = entry.schema.nullable === true;
     const tsType = jsonSchemaTypeToTs(entry.schema);
     const fullType = nullable ? `${tsType} | null` : tsType;
     const parts = [];
     if (entry.description) parts.push(entry.description);
     if (entry.default !== void 0) parts.push(`(default: ${JSON.stringify(entry.default)})`);
+    if (!required) parts.push("(optional \u2014 the agent may omit it; guard or fall back)");
     const desc = parts.length > 0 ? ` // ${parts.join(" ")}` : "";
     propsFields.push(`  ${key}${required ? "" : "?"}: ${fullType};${desc}`);
   }
@@ -1787,6 +1800,7 @@ A \`DataContract\` declares everything a GguiSession exchanges with the outside
 
 Props arrive at mount and may be partial on first render; later prop changes reach the SAME mounted component via \`ggui_amend\` (in-place repaint) on the live channel. Stream channels start empty and fill over time. Context slots start at their declared default (often \`null\`). **Never assume a field exists before you read it.**
 
+- **Optional contract props**: a \`Props\` field marked \`?\` in the boilerplate may be omitted by the agent ENTIRELY \u2014 the wire gate only enforces \`required: true\` entries, and the harness verifies your component with those props stripped. Guard them (\`?? default\`, \`?.\`, or an empty-state branch) from the FIRST render.
 - **Array iteration**: always default to \`[]\` before \`.map\`/\`.filter\`/\`.length\`. Use \`(props.items ?? []).map(...)\` not \`props.items.map(...)\`. Same for stream.all, stream.latest, etc.
 - **Object access**: optional-chain through nested fields. \`props.user?.name ?? 'Anonymous'\` not \`props.user.name\`.
 - **Number ops**: default before arithmetic. \`(props.count ?? 0) + 1\` not \`props.count + 1\`.
@@ -2816,6 +2830,34 @@ function errorSummary(e) {
   }
   return `${e.constructor.name}${status}${code}: ${e.message.slice(0, 120)}${body}`;
 }
+function isRateLimited(e) {
+  if (!(e instanceof Error) || !("status" in e)) return false;
+  return e.status === 429;
+}
+function extractStatus(e) {
+  if (!(e instanceof Error) || !("status" in e)) return void 0;
+  const status = e.status;
+  return typeof status === "number" ? status : void 0;
+}
+function extractRetryAfterSec(e) {
+  if (!(e instanceof Error) || !("headers" in e)) return void 0;
+  const headers = e.headers;
+  if (headers === null || typeof headers !== "object" || !("get" in headers) || typeof headers.get !== "function") {
+    return void 0;
+  }
+  const raw = headers.get("retry-after");
+  if (raw === null) return void 0;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) && parsed >= 0 ? Math.floor(parsed) : void 0;
+}
+function sleep(ms) {
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
+}
+var MAX_RETRY_ATTEMPTS = 2;
+var RETRY_AFTER_CAP_SEC = 15;
+var DEFAULT_BACKOFF_BASE_MS = 1e3;
+var DEFAULT_BACKOFF_MAX_MS = 8e3;
+var MAX_TOTAL_RETRY_DELAY_MS = 2e4;
 var LLMAgent = class {
   client = null;
   // ── Session state for server-side chaining ──────────────
@@ -2830,8 +2872,11 @@ var LLMAgent = class {
    * back to `process.env` exactly as before.
    */
   routeOverride;
-  constructor(routeOverride) {
+  /** See `AgentConfig.onRetry` (#489). Absent is a no-op. */
+  onRetry;
+  constructor(routeOverride, onRetry) {
     this.routeOverride = routeOverride;
+    this.onRetry = onRetry;
   }
   async getClient() {
     if (!this.client) {
@@ -2866,17 +2911,83 @@ var LLMAgent = class {
   async sendToolResult(_results) {
   }
   /**
-   * Execute an API call. No retry — if it fails, it fails.
-   * Logs the error with provider context and re-throws.
+   * 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.
    */
   async apiCall(fn) {
     const start = Date.now();
-    try {
-      return await fn();
-    } catch (e) {
-      const ms = Date.now() - start;
-      console.error(`[${this.provider}] API error after ${ms}ms: ${errorSummary(e)}`);
-      throw e;
+    let totalDelayMs = 0;
+    for (let attempt = 0; ; attempt++) {
+      try {
+        return await fn();
+      } catch (e) {
+        const ms = Date.now() - start;
+        if (attempt >= MAX_RETRY_ATTEMPTS || !isRateLimited(e)) {
+          console.error(`[${this.provider}] API error after ${ms}ms: ${errorSummary(e)}`);
+          throw e;
+        }
+        const retryAfterSec = extractRetryAfterSec(e);
+        if (retryAfterSec !== void 0 && retryAfterSec > RETRY_AFTER_CAP_SEC) {
+          console.error(
+            `[${this.provider}] API error after ${ms}ms (retry-after ${retryAfterSec}s exceeds ${RETRY_AFTER_CAP_SEC}s cap, not retrying): ${errorSummary(e)}`
+          );
+          throw e;
+        }
+        const delayMs = retryAfterSec !== void 0 ? retryAfterSec * 1e3 : Math.min(DEFAULT_BACKOFF_BASE_MS * 2 ** attempt, DEFAULT_BACKOFF_MAX_MS) + Math.floor(Math.random() * 250);
+        if (totalDelayMs + delayMs > MAX_TOTAL_RETRY_DELAY_MS) {
+          console.error(
+            `[${this.provider}] API error after ${ms}ms (retry budget exhausted, not retrying): ${errorSummary(e)}`
+          );
+          throw e;
+        }
+        totalDelayMs += delayMs;
+        const info = {
+          provider: this.provider,
+          attempt: attempt + 1,
+          maxAttempts: MAX_RETRY_ATTEMPTS,
+          status: extractStatus(e),
+          retryAfterSec,
+          delayMs,
+          message: errorSummary(e)
+        };
+        console.warn(
+          `[${this.provider}] rate-limited (attempt ${info.attempt}/${info.maxAttempts}), retrying in ${delayMs}ms`
+        );
+        try {
+          this.onRetry?.(info);
+        } catch (observerError) {
+          console.warn(
+            `[${this.provider}] onRetry observer threw (ignored, retry proceeds): ${errorSummary(observerError)}`
+          );
+        }
+        await sleep(delayMs);
+      }
     }
   }
 };
@@ -2969,6 +3080,73 @@ var AnthropicAgent = class extends LLMAgent {
       throw e;
     }
   }
+  async callVision(model, systemPrompt, userPrompt, image, maxTokens) {
+    const client = await this.getClient();
+    const traceId = newLlmTraceId();
+    const startedAt = Date.now();
+    const resolvedModel = this.resolveModel(model);
+    const imageBlock = {
+      type: "image",
+      source: {
+        type: "base64",
+        media_type: image.mediaType,
+        data: image.base64
+      }
+    };
+    try {
+      const response = await this.apiCall(
+        () => client.messages.create({
+          model: resolvedModel,
+          max_tokens: maxTokens ?? 1500,
+          system: systemPrompt,
+          messages: [
+            {
+              role: "user",
+              content: [imageBlock, { type: "text", text: userPrompt }]
+            }
+          ]
+        })
+      );
+      const text = response.content.filter((block) => block.type === "text").map((block) => block.text).join("");
+      const endedAt = Date.now();
+      emitLlmTraceEvent({
+        id: traceId,
+        at: startedAt,
+        endedAt,
+        durationMs: endedAt - startedAt,
+        provider: "anthropic",
+        model: resolvedModel,
+        kind: "callVision",
+        systemPrompt,
+        userPrompt,
+        result: {
+          inputTokens: response.usage.input_tokens,
+          outputTokens: response.usage.output_tokens,
+          text
+        }
+      });
+      return {
+        text,
+        inputTokens: response.usage.input_tokens,
+        outputTokens: response.usage.output_tokens
+      };
+    } catch (e) {
+      const endedAt = Date.now();
+      emitLlmTraceEvent({
+        id: traceId,
+        at: startedAt,
+        endedAt,
+        durationMs: endedAt - startedAt,
+        provider: "anthropic",
+        model: resolvedModel,
+        kind: "callVision",
+        systemPrompt,
+        userPrompt,
+        error: { message: e instanceof Error ? e.message : String(e) }
+      });
+      throw e;
+    }
+  }
   async callTools(model, systemPrompt, userPrompt, tools, toolChoice = "required", _scopedTools) {
     const client = await this.getClient();
     const traceId = newLlmTraceId();
@@ -3364,6 +3542,72 @@ var GoogleAgent = class extends LLMAgent {
       outputTokens: interaction.usage?.total_output_tokens ?? 0
     };
   }
+  async callVision(model, systemPrompt, userPrompt, image, maxTokens) {
+    const client = await this.getClient();
+    const traceId = newLlmTraceId();
+    const startedAt = Date.now();
+    const resolvedModel = this.resolveModel(model);
+    try {
+      const response = await this.apiCall(
+        () => client.models.generateContent({
+          model: resolvedModel,
+          contents: [
+            {
+              role: "user",
+              parts: [
+                { inlineData: { mimeType: image.mediaType, data: image.base64 } },
+                { text: userPrompt }
+              ]
+            }
+          ],
+          config: {
+            systemInstruction: systemPrompt,
+            ...maxTokens ? { maxOutputTokens: maxTokens } : {}
+          }
+        })
+      );
+      const text = response.candidates?.[0]?.content?.parts?.map((p) => p.text || "").join("") || "";
+      const usage = response.usageMetadata;
+      const result = {
+        text,
+        inputTokens: usage?.promptTokenCount ?? 0,
+        outputTokens: usage?.candidatesTokenCount ?? 0
+      };
+      const endedAt = Date.now();
+      emitLlmTraceEvent({
+        id: traceId,
+        at: startedAt,
+        endedAt,
+        durationMs: endedAt - startedAt,
+        provider: "google",
+        model: resolvedModel,
+        kind: "callVision",
+        systemPrompt,
+        userPrompt,
+        result: {
+          inputTokens: result.inputTokens,
+          outputTokens: result.outputTokens,
+          text
+        }
+      });
+      return result;
+    } catch (e) {
+      const endedAt = Date.now();
+      emitLlmTraceEvent({
+        id: traceId,
+        at: startedAt,
+        endedAt,
+        durationMs: endedAt - startedAt,
+        provider: "google",
+        model: resolvedModel,
+        kind: "callVision",
+        systemPrompt,
+        userPrompt,
+        error: { message: e instanceof Error ? e.message : String(e) }
+      });
+      throw e;
+    }
+  }
   async callTools(model, systemPrompt, userPrompt, tools, _toolChoice = "required", scopedTools) {
     const client = await this.getClient();
     const interactionTools = tools.map((t) => ({
@@ -3695,15 +3939,16 @@ var OpenRouterAgent = class extends LLMAgent {
 function createAgent(providerOrConfig) {
   const provider = typeof providerOrConfig === "string" ? providerOrConfig : providerOrConfig.provider;
   const routeOverride = typeof providerOrConfig === "string" ? void 0 : providerOrConfig.routeOverride;
+  const onRetry = typeof providerOrConfig === "string" ? void 0 : providerOrConfig.onRetry;
   switch (provider) {
     case "anthropic":
-      return new AnthropicAgent(routeOverride);
+      return new AnthropicAgent(routeOverride, onRetry);
     case "openai":
-      return new OpenAIAgent(routeOverride);
+      return new OpenAIAgent(routeOverride, onRetry);
     case "google":
-      return new GoogleAgent(routeOverride);
+      return new GoogleAgent(routeOverride, onRetry);
     case "openrouter":
-      return new OpenRouterAgent(routeOverride);
+      return new OpenRouterAgent(routeOverride, onRetry);
   }
 }
 async function callLLM(config, systemPrompt, userPrompt, maxTokens) {