@ggui-ai/ui-gen 0.7.0 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ggui-ai/ui-gen",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "UI generation harness for ggui — the LLM system prompt, multi-turn coding loop, and evaluation engine that turn a DataContract into a React component. Implements the UiGenerator contract from @ggui-ai/mcp-server-core; consumed by @ggui-ai/mcp-server.",
   "license": "Apache-2.0",
   "keywords": [
@@ -185,12 +185,12 @@
   "peerDependencies": {
     "@google/adk": "^0.5.0",
     "@openai/agents": "^0.7.1",
-    "puppeteer-core": "^24.40.0",
+    "puppeteer-core": "^24.40.0 || ^25.0.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0",
-    "@ggui-ai/mcp-server-core": "0.7.0",
-    "@ggui-ai/protocol": "0.7.0",
-    "@ggui-ai/project-config": "0.7.0"
+    "@ggui-ai/mcp-server-core": "0.9.0",
+    "@ggui-ai/protocol": "0.9.0",
+    "@ggui-ai/project-config": "0.9.0"
   },
   "peerDependenciesMeta": {
     "@google/adk": {
@@ -210,9 +210,9 @@
     }
   },
   "dependencies": {
-    "@anthropic-ai/bedrock-sdk": "^0.29.0",
-    "@anthropic-ai/claude-agent-sdk": "0.2.76",
-    "@anthropic-ai/sdk": "^0.91.1",
+    "@anthropic-ai/bedrock-sdk": "^0.32.1",
+    "@anthropic-ai/claude-agent-sdk": "0.3.229",
+    "@anthropic-ai/sdk": "^0.116.0",
     "@google/genai": "^2.8.0",
     "@testing-library/dom": "^10.4.0",
     "@testing-library/react": "^16.0.0",
@@ -229,28 +229,28 @@
     "openai": "^6.29.0",
     "typescript": "^5.0.0",
     "zod": "^4.3.6",
-    "@ggui-ai/gadgets": "0.7.0",
-    "@ggui-ai/wire": "0.7.0",
-    "@ggui-ai/design": "0.7.0",
-    "@ggui-ai/sandbox": "0.7.0",
-    "@ggui-ai/ui-visual-tester": "0.7.0"
+    "@ggui-ai/design": "0.9.0",
+    "@ggui-ai/gadgets": "0.9.0",
+    "@ggui-ai/ui-visual-tester": "0.9.0",
+    "@ggui-ai/wire": "0.9.0",
+    "@ggui-ai/sandbox": "0.9.0"
   },
   "devDependencies": {
     "@google/adk": "^0.5.0",
     "@openai/agents": "^0.7.1",
-    "@sparticuz/chromium": "^143.0.4",
+    "@sparticuz/chromium": "^149.0.0",
     "@types/eslint": "^9.6.1",
     "@types/node": "^22.0.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
-    "puppeteer-core": "^24.40.0",
+    "puppeteer-core": "^25.6.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "tsup": "^8.5.0",
     "vitest": "^3.2.6",
-    "@ggui-ai/mcp-server-core": "0.7.0",
-    "@ggui-ai/project-config": "0.7.0",
-    "@ggui-ai/protocol": "0.7.0"
+    "@ggui-ai/project-config": "0.9.0",
+    "@ggui-ai/mcp-server-core": "0.9.0",
+    "@ggui-ai/protocol": "0.9.0"
   },
   "engines": {
     "node": ">=20.0.0"

package/src/adapters/generation-dispatch.ts

@@ -53,6 +53,7 @@ import type {
 } from "../harness/result-types.js";
 import type { AdapterResult, ProviderName, ToolDefinition } from "./types.js";
 import type { QualityConfig } from "../evaluation/types-public.js";
+import type { AgentConfig } from "../harness/llm-router.js";
 import {
   type GadgetDescriptor,
   type JsonObject,
@@ -147,6 +148,14 @@ export interface GenerationDispatchParams {
    * STDLIB-only / bench / direct callers.
    */
   gadgetTypes?: Readonly<Record<string, string>>;
+  /**
+   * Explicit per-call credentials/routing (#484) — see
+   * `AgentConfig.routeOverride`. Threaded onto the coding + evaluation
+   * agent specs so `resolveSessionAgents` → `createAgent` never falls
+   * back to reading `process.env`. Absent (default) preserves
+   * existing behavior for callers that don't set it.
+   */
+  routeOverride?: AgentConfig["routeOverride"];
 }
 
 /**
@@ -186,9 +195,17 @@ export async function dispatchGeneration(
 
   const routerProvider = mapProviderForLLMRouter(params.provider);
   const resolvedModel = params.models?.coding ?? params.models?.default ?? params.model;
-  const codingAgent = { provider: routerProvider, model: resolvedModel };
+  const codingAgent = {
+    provider: routerProvider,
+    model: resolvedModel,
+    routeOverride: params.routeOverride,
+  };
   const evaluationAgent = params.models?.evaluation
-    ? { provider: routerProvider, model: params.models.evaluation }
+    ? {
+        provider: routerProvider,
+        model: params.models.evaluation,
+        routeOverride: params.routeOverride,
+      }
     : undefined;
   // ModelRoles doesn't currently expose a visualEval slot — falls through
   // to the documented evaluation → coding chain inside resolveSessionAgents.

package/src/boilerplate/system-prompt.ts

@@ -347,13 +347,14 @@ A \`DataContract\` declares everything a GguiSession exchanges with the outside
 
 ## Defensive coding for absent / late-arriving data
 
-Props arrive via \`ggui_update\` and may be partial on first render. 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.**
+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.**
 
 - **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\`.
 - **Stream latest**: \`useStream\` returns \`{latest: T | null, all: T[], isComplete: boolean}\`. The default \`all\` is \`[]\` so it's safe to map; \`latest\` is null until the first frame arrives — guard before reading \`.foo\`.
 - **Stream reconciliation**: when a stream event carries an \`action\` discriminant (e.g. \`create | move | edit | delete\`), the channel is a CRUD feed — your handler MUST branch on EVERY value: append on \`create\`, drop on \`delete\`, replace-by-id on \`move\` / \`edit\`. Merging only the "edit" case silently loses created and deleted items. Reconcile into the SAME state that seeds from \`props\` (e.g. \`useState(() => props.tasks ?? [])\`) so the seed data and the live feed render as one list — and handle an event whose id is not yet present (a \`create\` for an unknown item) by inserting it, not ignoring it.
+- **Props re-sync on repaint**: props the agent owns are the source of truth for display — prefer rendering DIRECTLY from \`props\` (controlled, no local copy). When local optimistic state genuinely needs a prop seed (a click bumps a count before the agent confirms), it MUST re-sync on prop change — \`useEffect(() => setCount(props.count ?? 0), [props.count])\` — or a \`ggui_amend\` repaint applies the new props while the display keeps the stale local value. BAD: \`const [count, setCount] = useState(props.count ?? 0)\` alone. GOOD: the same seed + the one-line re-sync effect.
 - **Loading state**: while data is still absent, render \`<Skeleton>\` placeholders — never a blank screen. \`<Skeleton variant="text" />\` for a text line, \`variant="circle"\` for an avatar slot, default \`rect\` for a block.
 - **Empty state**: when a list or results array is empty, render \`<EmptyState title="…" description="…" />\` — a region that renders nothing when empty looks broken to the user.
 
@@ -481,7 +482,7 @@ Every value change is mirrored to the host LLM's context automatically (debounce
 
 **When NOT to use it.** Local UI state the contract did NOT declare — \`isDropdownOpen\`, hover flags, animation phase, ephemeral toggles. For those, use a plain \`useState\` directly. The runtime ignores undeclared state.
 
-**\`contextSpec\` direction is one-way: client → agent.** The agent uses \`propsSpec\` (via \`ggui_update\`) and \`streamSpec\` (via the live channel) to push state TO the client. Don't try to write to the agent via \`contextSpec\` — there is no return path.
+**\`contextSpec\` direction is one-way: client → agent.** The agent uses \`propsSpec\` (via \`ggui_amend\` for in-place repaints of this mount, or \`ggui_update\` when it mints a new history card) and \`streamSpec\` (via the live channel) to push state TO the client. Don't try to write to the agent via \`contextSpec\` — there is no return path.
 
 **Schema mismatches drop silently.** If you set a value that doesn't match the slot's schema (e.g. a string into a \`{type: 'number'}\` slot), the runtime logs a dev \`console.warn\` and skips the post. Make sure your setter calls produce values that match the declared shape.
 

package/src/create-ui-generator.ts

@@ -138,6 +138,19 @@ export interface CreateUiGeneratorOptions {
    * `appGadgets` themselves; the legacy handler path stays unchanged.
    */
   readonly gadgetCatalog?: GadgetCatalogAdapter;
+  /**
+   * When `true`, `generate()` never mutates `process.env` — the
+   * resolved provider route is threaded structurally into the
+   * dispatch call instead of being written to and restored from the
+   * process environment. Use this when running concurrent
+   * generations in one process (the default backup/mutate/restore
+   * dance is NOT concurrency-safe: two simultaneous calls race on
+   * the shared `process.env`).
+   *
+   * Default `false` — preserves the original env-mutation behavior
+   * for callers that don't need concurrent generations in-process.
+   */
+  readonly disableEnvMutation?: boolean;
 }
 
 export function createUiGenerator(
@@ -149,6 +162,7 @@ export function createUiGenerator(
     maxEvalRounds,
     qualityConfig,
     gadgetCatalog,
+    disableEnvMutation = false,
   } = options;
 
   const identity = resolveIdentity(options);
@@ -193,19 +207,37 @@ export function createUiGenerator(
       }
 
       const envBackup: Record<string, string | undefined> = {};
-      for (const k of Object.keys(route.env)) envBackup[k] = process.env[k];
-      const baseEnvForApply: Record<string, string> = {};
-      for (const [k, v] of Object.entries(process.env)) {
-        if (v !== undefined) baseEnvForApply[k] = v;
-      }
-      const routedEnv = applyRouteToEnv(baseEnvForApply, route);
-      for (const [k, v] of Object.entries(routedEnv)) process.env[k] = v;
-      // Also delete any keys the route asked to clear (route.env values
-      // marked undefined).
-      for (const [k, v] of Object.entries(route.env)) {
-        if (v === undefined) delete process.env[k];
+      if (!disableEnvMutation) {
+        for (const k of Object.keys(route.env)) envBackup[k] = process.env[k];
+        const baseEnvForApply: Record<string, string> = {};
+        for (const [k, v] of Object.entries(process.env)) {
+          if (v !== undefined) baseEnvForApply[k] = v;
+        }
+        const routedEnv = applyRouteToEnv(baseEnvForApply, route);
+        for (const [k, v] of Object.entries(routedEnv)) process.env[k] = v;
+        // Also delete any keys the route asked to clear (route.env values
+        // marked undefined).
+        for (const [k, v] of Object.entries(route.env)) {
+          if (v === undefined) delete process.env[k];
+        }
       }
 
+      // #484 — when `disableEnvMutation` is set, skip the process-env
+      // mutation above entirely and thread the resolved route
+      // structurally into the dispatch call instead. `route.env`
+      // already carries exactly the key(s) that would have gone into
+      // `process.env`, so no extra resolution work is needed here.
+      const routeOverride = disableEnvMutation
+        ? {
+            apiKey:
+              route.env['ANTHROPIC_API_KEY'] ??
+              route.env['OPENAI_API_KEY'] ??
+              route.env['GEMINI_API_KEY'] ??
+              route.env['OPENROUTER_API_KEY'],
+            useBedrock: route.env['CLAUDE_CODE_USE_BEDROCK'] === '1',
+          }
+        : undefined;
+
       try {
         const tools = createGeneratorTools({
           ...(input.contract ? { contract: input.contract } : {}),
@@ -269,6 +301,7 @@ export function createUiGenerator(
             ? { gadgetTypes: input.gadgetTypes }
             : {}),
           enableRuntimeRender,
+          ...(routeOverride !== undefined ? { routeOverride } : {}),
         });
 
         const metadata: GenerationMetadata = {

package/src/evaluation/axis-checks/checks/state-merge.ts

@@ -29,7 +29,7 @@ function runStateSeededFromProps(input: AxisCheckInput): EvalIssue[] {
       mkIssue(
         "state.merge.seeded_from_props",
         `Entity collection "${e.name}" is not seeded from props — no useState initializer reads props.${e.name}.`,
-        `Add \`const [${e.name}, set${cap(e.name)}] = useState(props.${e.name});\` so stream/action updates can merge into live state.`,
+        `Add \`const [${e.name}, set${cap(e.name)}] = useState(props.${e.name});\` paired with \`useEffect(() => set${cap(e.name)}(props.${e.name}), [props.${e.name}]);\` so stream/action updates merge into live state AND agent repaints (ggui_amend) re-seed it (#480).`,
       ),
     );
   }

package/src/evaluation/axis-checks/checks/universal.ts

@@ -86,6 +86,39 @@ function runNoPhantomUseState(input: AxisCheckInput): EvalIssue[] {
   return issues;
 }
 
+function runPropSeedNoResync(input: AxisCheckInput): EvalIssue[] {
+  if (input.compiledCode === null) return [];
+  const src = input.sourceCode;
+  const issues: EvalIssue[] = [];
+  const re =
+    /const\s*\[\s*(\w+)\s*,\s*(\w+)\s*\]\s*=\s*useState(?:<[^>]*>)?\s*\(\s*props\??\.(\w+)/g;
+  for (const m of src.matchAll(re)) {
+    const [full, stateVar, setter, propName] = m;
+    const idx = m.index ?? 0;
+    const after = src.slice(idx + full.length);
+    // Never-called setter is `no_prop_mirror`'s case — this check is
+    // its #480 complement: the setter IS used (real optimistic state)
+    // but nothing re-seeds when the agent repaints the prop.
+    if (!new RegExp(`\\b${setter}\\s*\\(`).test(after)) continue;
+    // A re-seed effect names the prop in a dependency array. Bracket
+    // shape is the pragmatic signal (same looseness as the sibling
+    // checks): any `[... props.X ...]` array in the source counts.
+    const resync = new RegExp(
+      `\\[[^\\[\\]]*props\\??\\.${propName}\\b[^\\[\\]]*\\]`,
+    );
+    if (resync.test(src)) continue;
+    issues.push(
+      mkIssue(
+        "universal.prop_seed_no_resync",
+        `useState(props.${propName}) seeds "${stateVar}" and mutates it, but no effect depends on [props.${propName}] — a ggui_amend repaint pushes new props that never reach this display (#480).`,
+        `Add \`useEffect(() => ${setter}(props.${propName}), [props.${propName}]);\` so agent repaints re-seed the state, or derive the display directly from props.${propName}.`,
+        "warn",
+      ),
+    );
+  }
+  return issues;
+}
+
 export const UNIVERSAL_CHECKS: readonly AxisCheck[] = [
   {
     id: "universal.prop_coverage",
@@ -105,4 +138,10 @@ export const UNIVERSAL_CHECKS: readonly AxisCheck[] = [
     values: ALL_RENDER_VALUES,
     run: runNoPhantomUseState,
   },
+  {
+    id: "universal.prop_seed_no_resync",
+    axis: "render",
+    values: ALL_RENDER_VALUES,
+    run: runPropSeedNoResync,
+  },
 ];

package/src/evaluation/llm-evaluator.ts

@@ -16,7 +16,7 @@
 
 import type { EvalIssue, EvalResult, EvalCategory } from './types-public.js';
 import { createAgent } from '../harness/llm-router';
-import type { LLMToolDef, LLMAgent } from '../harness/llm-router';
+import type { AgentConfig, LLMToolDef, LLMAgent } from '../harness/llm-router';
 import type { JsonObject } from '@ggui-ai/protocol';
 import { getCriterionById } from './types-public.js';
 
@@ -64,6 +64,13 @@ export interface LLMEvalContext {
 export interface LLMEvalConfig {
   provider: 'claude' | 'openai' | 'google' | 'openrouter';
   model?: string;
+  /**
+   * Explicit per-call credentials/routing (#484) — see
+   * `AgentConfig.routeOverride`. Threaded onto the agent this
+   * evaluator constructs so it never falls back to reading
+   * `process.env`. Absent (default) preserves existing behavior.
+   */
+  routeOverride?: AgentConfig['routeOverride'];
 }
 
 /** A request-specific evaluation criterion generated by the LLM. */
@@ -745,8 +752,11 @@ export async function runLLMEvaluation(
     .map((line, i) => `${String(i + 1).padStart(4)} | ${line}`)
     .join('\n');
 
-  // Create a single agent — all calls share the same client + cache
-  const agent = createAgent(routerProvider);
+  // Create a single agent — all calls share the same client + cache.
+  // Pass the full config (not just the bare provider string) so a
+  // caller-supplied `routeOverride` (#484) reaches the constructed
+  // `LLMAgent` instance and it never falls back to `process.env`.
+  const agent = createAgent({ provider: routerProvider, model, routeOverride: config.routeOverride });
 
   // Dynamic criteria removed — they generated overly strict edge-case checks
   // that wasted coding turns on nitpicks. Will be replaced by a holistic

package/src/evaluation/visual-evaluator.ts

@@ -185,7 +185,11 @@ async function captureScreenshot(
     const browser = await puppeteer.default.launch(launchOptions);
     try {
       const page = await browser.newPage();
-      await page.setContent(html, { waitUntil: 'networkidle0', timeout: 15000 });
+      // puppeteer ≥24.43 narrowed setContent's waitUntil to
+      // 'load' | 'domcontentloaded'; waitForNetworkIdle (0 connections
+      // for 500ms) reproduces the old 'networkidle0' semantics.
+      await page.setContent(html, { waitUntil: 'load', timeout: 15000 });
+      await page.waitForNetworkIdle({ idleTime: 500, timeout: 15000 }).catch(() => {});
       await page.waitForSelector('#root > *', { timeout: 10000 }).catch(() => {});
       // Wait a bit for CSS/fonts to settle
       await new Promise(r => setTimeout(r, 1000));

package/src/fragments/realtime.ts

@@ -16,14 +16,14 @@ export const realtimeFragments: Record<string, HarnessFragment> = {
     value: "merge",
     cacheTier: "axisDelta",
     promptText:
-      "## Realtime: merge\nStream events carry an id; merge into LOCAL STATE. Subscribing alone is not enough — the local list must update on each event for the DOM to re-render.\n\n```tsx\nconst stream = useStream<UpdateT>('streamName');\nconst [items, setItems] = useState(props.items);\nuseEffect(() => {\n  if (!stream.latest) return;\n  setItems((prev) => prev.map((it) => it.id === stream.latest!.id ? { ...it, ...stream.latest } : it));\n}, [stream.latest]);\n// Render `items.map(...)` — NOT props.items, NOT stream.all.\n```\n\nNever append — stream=merge means the entity already exists locally.",
+      "## Realtime: merge\nStream events carry an id; merge into LOCAL STATE. Subscribing alone is not enough — the local list must update on each event for the DOM to re-render.\n\n```tsx\nconst stream = useStream<UpdateT>('streamName');\nconst [items, setItems] = useState(props.items);\nuseEffect(() => setItems(props.items), [props.items]); // re-seed on ggui_amend repaint — props stay the source of truth\nuseEffect(() => {\n  if (!stream.latest) return;\n  setItems((prev) => prev.map((it) => it.id === stream.latest!.id ? { ...it, ...stream.latest } : it));\n}, [stream.latest]);\n// Render `items.map(...)` — NOT props.items, NOT stream.all.\n```\n\nNever append — stream=merge means the entity already exists locally.",
   },
   append: {
     axis: "realtime",
     value: "append",
     cacheTier: "axisDelta",
     promptText:
-      "## Realtime: append\nStream events are new entities; APPEND to local state. Subscribing alone is not enough — the local list must update for the DOM to re-render.\n\n```tsx\nconst stream = useStream<EventT>('streamName');\nconst [items, setItems] = useState(props.items);\nuseEffect(() => {\n  if (!stream.latest) return;\n  setItems((prev) => [...prev, stream.latest!]);\n}, [stream.latest]);\n// Render `items.map(...)` — NOT props.items, NOT stream.all (which accumulates only post-mount).\n```\n\nUse head for newest-first, tail for chat-style. Cap list length if needed. Do not dedupe unless the contract guarantees at-most-once.",
+      "## Realtime: append\nStream events are new entities; APPEND to local state. Subscribing alone is not enough — the local list must update for the DOM to re-render.\n\n```tsx\nconst stream = useStream<EventT>('streamName');\nconst [items, setItems] = useState(props.items);\nuseEffect(() => setItems(props.items), [props.items]); // re-seed on ggui_amend repaint — props stay the source of truth\nuseEffect(() => {\n  if (!stream.latest) return;\n  setItems((prev) => [...prev, stream.latest!]);\n}, [stream.latest]);\n// Render `items.map(...)` — NOT props.items, NOT stream.all (which accumulates only post-mount).\n```\n\nUse head for newest-first, tail for chat-style. Cap list length if needed. Do not dedupe unless the contract guarantees at-most-once.",
   },
   status: {
     axis: "realtime",
@@ -44,7 +44,7 @@ export const realtimeFragments: Record<string, HarnessFragment> = {
     value: "mixed",
     cacheTier: "axisDelta",
     promptText:
-      "## Realtime: mixed\nMultiple stream channels with DIFFERENT semantics. Each `streamKinds` entry in the contract maps to one of: merge, append, status, presence. Subscribe + sync to local state PER CHANNEL — subscribing alone never re-renders the DOM.\n\nExample (chat-interface — message=append, typing=presence):\n\n```tsx\nconst messages = useStream<MessageT>('message');\nconst typing = useStream<TypingT>('typing');\nconst [messageList, setMessageList] = useState(props.messages);\nconst [typingUsers, setTypingUsers] = useState<Set<string>>(new Set());\n\nuseEffect(() => {\n  if (!messages.latest) return;\n  setMessageList((prev) => [...prev, messages.latest!]);\n}, [messages.latest]);\n\nuseEffect(() => {\n  if (!typing.latest) return;\n  setTypingUsers((prev) => {\n    const next = new Set(prev);\n    if (typing.latest!.active) next.add(typing.latest!.sender);\n    else next.delete(typing.latest!.sender);\n    return next;\n  });\n}, [typing.latest]);\n```\n\nDo NOT treat all events the same. Do NOT skip the local-state sync — `useStream` alone won't trigger DOM updates of your derived view.",
+      "## Realtime: mixed\nMultiple stream channels with DIFFERENT semantics. Each `streamKinds` entry in the contract maps to one of: merge, append, status, presence. Subscribe + sync to local state PER CHANNEL — subscribing alone never re-renders the DOM.\n\nExample (chat-interface — message=append, typing=presence):\n\n```tsx\nconst messages = useStream<MessageT>('message');\nconst typing = useStream<TypingT>('typing');\nconst [messageList, setMessageList] = useState(props.messages);\nconst [typingUsers, setTypingUsers] = useState<Set<string>>(new Set());\n\nuseEffect(() => setMessageList(props.messages), [props.messages]); // re-seed on ggui_amend repaint\n\nuseEffect(() => {\n  if (!messages.latest) return;\n  setMessageList((prev) => [...prev, messages.latest!]);\n}, [messages.latest]);\n\nuseEffect(() => {\n  if (!typing.latest) return;\n  setTypingUsers((prev) => {\n    const next = new Set(prev);\n    if (typing.latest!.active) next.add(typing.latest!.sender);\n    else next.delete(typing.latest!.sender);\n    return next;\n  });\n}, [typing.latest]);\n```\n\nDo NOT treat all events the same. Do NOT skip the local-state sync — `useStream` alone won't trigger DOM updates of your derived view.",
     boilerplateMarker: [
       "",
       "  // ── Mixed stream handlers ──",

package/src/fragments/state.ts

@@ -24,11 +24,11 @@ export const stateFragments: Record<string, HarnessFragment> = {
     value: "merge",
     cacheTier: "axisDelta",
     promptText:
-      "## State: merge (live entity reconciliation)\n1. Seed `const [items, setItems] = useState(props.items ?? [])`.\n2. On stream updates: `setItems(prev => prev.map(it => it.id === event.id ? { ...it, ...event } : it))` — merge by id, do NOT append.\n3. Memoize derived views (grouping/sorting/filtering) with useMemo.\n4. Per-item actions pass `{ id, ... }` in the payload.\n5. Never push the stream payload into an append-only list unless realtime=append.",
+      "## State: merge (live entity reconciliation)\n1. Seed `const [items, setItems] = useState(props.items ?? [])` AND re-seed on prop change: `useEffect(() => setItems(props.items ?? []), [props.items])` — a `ggui_amend` repaint must move the list.\n2. On stream updates: `setItems(prev => prev.map(it => it.id === event.id ? { ...it, ...event } : it))` — merge by id, do NOT append.\n3. Memoize derived views (grouping/sorting/filtering) with useMemo.\n4. Per-item actions pass `{ id, ... }` in the payload.\n5. Never push the stream payload into an append-only list unless realtime=append.",
     boilerplateMarker: [
       "",
       "  // ── Live entity state (merge-by-id) ──",
-      "  // useState(props.items ?? []); merge stream events by item.id; never append.",
+      "  // useState(props.items ?? []); re-seed via useEffect on [props.items]; merge stream events by item.id; never append.",
       "",
     ].join("\n"),
   },

package/src/harness/coding/init-session.ts

@@ -144,7 +144,10 @@ export async function initSession(input: {
   const systemPrompt = input.systemPromptOverride ?? harness.how.systemPrompt;
 
   // ── Create + warm-cache the coding agent ──
-  const codingAgent = createAgent(agents.coding.provider);
+  // Pass the full spec (not just `.provider`) so a caller-supplied
+  // `routeOverride` (#484) reaches the constructed `LLMAgent` instance
+  // and it never falls back to reading `process.env`.
+  const codingAgent = createAgent(agents.coding);
   await codingAgent.warmCache(
     agents.coding.model,
     systemPrompt,

package/src/harness/coding/run-eval-round.ts

@@ -418,6 +418,12 @@ export async function runEvalRound(
             {
               provider: mapProviderForEvaluator(evaluationAgent.provider),
               model: evaluationAgent.model,
+              // #484 — thread the coding-agent's routing override
+              // through to the evaluator so its LLM call never falls
+              // back to `process.env` either (the eval calls run
+              // inside the same concurrent generation, so the race is
+              // real here too, not just on the coding turn).
+              routeOverride: evaluationAgent.routeOverride,
             },
             preWarmedContext,
           )

package/src/harness/llm-router.ts

@@ -53,6 +53,21 @@ export interface AgentConfig {
    * behavior for all existing callers).
    */
   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;
+  };
 }
 
 export interface LLMResponse {
@@ -181,6 +196,17 @@ export abstract class LLMAgent {
   // Call resetSession() between independent generation runs.
   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'];
+
+  constructor(routeOverride?: AgentConfig['routeOverride']) {
+    this.routeOverride = routeOverride;
+  }
 
   protected abstract resolveModel(model: string): string;
   protected abstract createClient(): Promise<unknown>;
@@ -294,7 +320,9 @@ export class AnthropicAgent extends LLMAgent {
   protected resolveModel(model: string): string {
     // Bedrock IAM path — the upstream model id must be the cross-region
     // inference-profile form (`us.anthropic.*`), not the bare API id.
-    if (process.env.CLAUDE_CODE_USE_BEDROCK === '1') {
+    const useBedrock =
+      this.routeOverride?.useBedrock ?? process.env.CLAUDE_CODE_USE_BEDROCK === '1';
+    if (useBedrock) {
       return getBedrockModelId(model);
     }
     return model.startsWith('anthropic/')
@@ -308,7 +336,9 @@ export class AnthropicAgent extends LLMAgent {
     // pool-funded cloud pod. Auth is the pod's IRSA role — no API key.
     // `AnthropicBedrock` is wire-compatible with `Anthropic` for the
     // `.messages` API this agent uses.
-    if (process.env.CLAUDE_CODE_USE_BEDROCK === '1') {
+    const useBedrock =
+      this.routeOverride?.useBedrock ?? process.env.CLAUDE_CODE_USE_BEDROCK === '1';
+    if (useBedrock) {
       const { AnthropicBedrock } = await import('@anthropic-ai/bedrock-sdk');
       return new AnthropicBedrock({
         awsRegion:
@@ -319,8 +349,10 @@ export class AnthropicAgent extends LLMAgent {
     }
     // SDK construction lives in `adapters/claude/client.ts`. The BYOK
     // resolver writes the raw key into `process.env.ANTHROPIC_API_KEY`
-    // before this runs (see `applyRouteToEnv` in provider-router).
-    return createAnthropicClient(process.env.ANTHROPIC_API_KEY);
+    // before this runs (see `applyRouteToEnv` in provider-router) —
+    // `routeOverride.apiKey`, when supplied, skips that env round-trip
+    // entirely.
+    return createAnthropicClient(this.routeOverride?.apiKey ?? process.env.ANTHROPIC_API_KEY);
   }
 
   async callText(
@@ -670,7 +702,7 @@ export class OpenAIAgent extends LLMAgent {
 
   protected async createClient(): Promise<OpenAI> {
     const { default: OpenAISDK } = await import('openai');
-    return new OpenAISDK({ apiKey: process.env.OPENAI_API_KEY });
+    return new OpenAISDK({ apiKey: this.routeOverride?.apiKey ?? process.env.OPENAI_API_KEY });
   }
 
   async callText(
@@ -928,7 +960,8 @@ export class GoogleAgent extends LLMAgent {
   protected async createClient(): Promise<GoogleGenAI> {
     const { GoogleGenAI: GoogleGenAISDK } = await import('@google/genai');
     return new GoogleGenAISDK({
-      apiKey: process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY,
+      apiKey:
+        this.routeOverride?.apiKey ?? (process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY),
       httpOptions: { timeout: 300_000 }, // 5 min — Pro models can be slow
     });
   }
@@ -1248,7 +1281,7 @@ export class OpenRouterAgent extends LLMAgent {
   protected async createClient(): Promise<unknown> {
     const { OpenRouterClient } = await import('../adapters/openrouter/client');
     return new OpenRouterClient({
-      apiKey: process.env.OPENROUTER_API_KEY!,
+      apiKey: this.routeOverride?.apiKey ?? process.env.OPENROUTER_API_KEY!,
     });
   }
 
@@ -1432,17 +1465,29 @@ export class OpenRouterAgent extends LLMAgent {
 /**
  * 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`.
  */
-export function createAgent(provider: AgentConfig['provider']): LLMAgent {
+export function createAgent(provider: AgentConfig['provider']): LLMAgent;
+export function createAgent(config: AgentConfig): LLMAgent;
+export function createAgent(providerOrConfig: AgentConfig['provider'] | AgentConfig): LLMAgent {
+  const provider =
+    typeof providerOrConfig === 'string' ? providerOrConfig : providerOrConfig.provider;
+  const routeOverride =
+    typeof providerOrConfig === 'string' ? undefined : providerOrConfig.routeOverride;
   switch (provider) {
     case 'anthropic':
-      return new AnthropicAgent();
+      return new AnthropicAgent(routeOverride);
     case 'openai':
-      return new OpenAIAgent();
+      return new OpenAIAgent(routeOverride);
     case 'google':
-      return new GoogleAgent();
+      return new GoogleAgent(routeOverride);
     case 'openrouter':
-      return new OpenRouterAgent();
+      return new OpenRouterAgent(routeOverride);
   }
 }
 
@@ -1457,7 +1502,7 @@ export async function callLLM(
   maxTokens?: number,
 ): Promise<LLMResponse> {
   const start = Date.now();
-  const agent = createAgent(config.provider);
+  const agent = createAgent(config);
   const result = await agent.callText(
     config.model,
     systemPrompt,
@@ -1479,7 +1524,7 @@ export async function callLLMWithTools(
   maxTurns: number = 10,
 ): Promise<LLMWithToolsResponse> {
   const start = Date.now();
-  const agent = createAgent(config.provider);
+  const agent = createAgent(config);
   const result = await agent.callWithTools(
     config.model,
     systemPrompt,

package/src/harness/runtime.ts

@@ -31,6 +31,7 @@ import { WIRE_DOCUMENTATION } from "../tools/get-wire.js";
 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";
 
 // Re-export the boilerplate generator so existing internal importers
 // (create-harness.ts, benchmarks/preview-boilerplate.ts) keep working.
@@ -46,6 +47,13 @@ type Provider = "anthropic" | "openai" | "google" | "openrouter";
 export interface AgentSpec {
   provider: Provider;
   model: string;
+  /**
+   * Explicit per-call credentials/routing (#484) — see
+   * `AgentConfig.routeOverride`. Threaded through unchanged so
+   * `createAgent()` can bypass `process.env` when the caller supplies
+   * it. Absent for every pre-existing caller.
+   */
+  routeOverride?: AgentConfig["routeOverride"];
 }
 
 export interface SingleComponentParams {