agent-accelerator 0.3.0 → 0.4.5

package/src/models/catalog.ts

@@ -39,12 +39,6 @@ const MODALITY_OVERRIDES: Record<string, { input?: string[]; output?: string[] }
   // OpenRouter routes this free model to an endpoint that parses PDFs,
   // verified end-to-end via examples/08. If routing changes, the runtime
   // 404 still surfaces as a one-line error.
-  "openrouter/nvidia/nemotron-3.5-lightning:free": { input: ["text", "pdf"] },
-  // Live-verified 2026-09-24: `stealth/space-bunny-alpha` accepts PDF
-  // `input_file` over Responses and PDFs via the file-parser plugin over Chat
-  // Completions (Berkshire letter + sample-files PDF both completed), though
-  // models.dev lists text/image/video only.
-  "openrouter/stealth/space-bunny-alpha": { input: ["text", "image", "video", "pdf"] },
 };
 
 function applyModalityOverrides(provider: string, modelId: string, base: ModelModalities): ModelModalities {
@@ -68,10 +62,72 @@ function normalizeModelIdForLookup(modelId: string): string {
 
 // ---------------------------------------------------------------------------
 // Internal cache — battle-tested: avoid repeated global scans (7487 models)
+// Bound lookupCache to 1000 entries LRU (Q-33): evict oldest on overflow.
 // ---------------------------------------------------------------------------
 const lookupCache = new Map<string, ModelSpec | undefined>();
 const providerModelsCache = new Map<string, ModelSpec[]>();
 
+/** Bounded LRU set for lookupCache (Q-33): keeps at most 1000 entries. */
+function setLookupCache(key: string, value: ModelSpec | undefined): void {
+  if (lookupCache.has(key)) lookupCache.delete(key);
+  else if (lookupCache.size >= 1000) {
+    const oldest = lookupCache.keys().next();
+    if (!oldest.done) lookupCache.delete(oldest.value);
+  }
+  lookupCache.set(key, value);
+}
+
+// Custom-registered models (Q-33): checked first in getModelFromCatalog.
+const customModelRegistry = new Map<string, ModelSpec>();
+
+function customRegistryKey(provider: string, modelId: string): string {
+  return `${provider.toLowerCase()}::${modelId.toLowerCase()}`;
+}
+
+/**
+ * Registers a custom model spec that takes precedence over the catalog (Q-33).
+ * Stored in a separate map, checked first in `getModelFromCatalog`.
+ */
+export function registerModel(spec: ModelSpec): void {
+  if (!spec || typeof spec.id !== "string" || typeof spec.provider !== "string") {
+    throw new Error("[Agent Accelerator] registerModel requires spec.id and spec.provider strings");
+  }
+  customModelRegistry.set(customRegistryKey(String(spec.provider), String(spec.id)), { ...spec });
+  // Invalidate derived caches so the custom model is visible immediately.
+  lookupCache.clear();
+  providerModelsCache.clear();
+  globalIndex = null;
+}
+
+/** Clears custom-registered models (primarily for tests). */
+export function clearCustomModels(): void {
+  customModelRegistry.clear();
+  lookupCache.clear();
+  providerModelsCache.clear();
+  globalIndex = null;
+}
+
+/**
+ * Returns where a model resolves from without touching frozen types (Q-33):
+ * `"override"` for custom-registered or MODALITY_OVERRIDES-covered models,
+ * `"catalog"` for plain catalog hits, `"unknown"` when unresolvable.
+ */
+export function getModelSource(provider: string, modelId: string): "catalog" | "override" | "unknown" {
+  const p = String(provider ?? "").toLowerCase();
+  const m = String(modelId ?? "");
+  const norm = normalizeModelIdForLookup(m);
+  if (customModelRegistry.has(customRegistryKey(p, m)) || customModelRegistry.has(customRegistryKey(p, norm))) {
+    return "override";
+  }
+  if (
+    MODALITY_OVERRIDES[`${p}/${m}`] !== undefined ||
+    MODALITY_OVERRIDES[`${p}/${norm}`] !== undefined
+  ) {
+    return "override";
+  }
+  return getModelFromCatalog(provider, modelId) ? "catalog" : "unknown";
+}
+
 function mapCapabilities(raw: any, cost: ModelCost, reasoning: boolean, toolCall: boolean, modalities: ModelModalities) {
   return {
     supportsThinking: reasoning,
@@ -82,6 +138,7 @@ function mapCapabilities(raw: any, cost: ModelCost, reasoning: boolean, toolCall
     supportsExplicitCaching: cost.cache_read !== undefined,
     supportsParallelToolCalls: toolCall,
     supportsStreaming: true,
+    supportsStructuredOutput: raw.structured_output === undefined ? true : !!raw.structured_output,
     supportsReasoningToggle: Array.isArray(raw.reasoning_options) && raw.reasoning_options.some((o: any) => o.type === "toggle"),
     supportsReasoningEffort: Array.isArray(raw.reasoning_options) && raw.reasoning_options.some((o: any) => o.type === "effort"),
     modalities: [...(modalities.input || []), ...(modalities.output || [])].filter((v: any, i: any, a: any) => a.indexOf(v) === i),
@@ -180,6 +237,16 @@ export function getModelFromCatalog(providerInput: string, modelIdInput: string)
   const modelId = modelIdInput.trim();
   let result: ModelSpec | undefined;
 
+  // Q-33: custom-registered models win over the catalog.
+  const customHit =
+    customModelRegistry.get(customRegistryKey(provider, modelId)) ??
+    customModelRegistry.get(customRegistryKey(provider, normalizeModelIdForLookup(modelId)));
+  if (customHit) {
+    result = { ...customHit };
+    setLookupCache(cacheKey, result);
+    return result;
+  }
+
   const aliasProviders = PROVIDER_ALIASES[provider] || [provider];
   const tryProviders = [...new Set([...aliasProviders, provider, provider.replace("-zen", ""), provider.replace("-go", "")])];
   const catalog = getActiveCatalog();
@@ -197,14 +264,17 @@ export function getModelFromCatalog(providerInput: string, modelIdInput: string)
       const raw = providerData.models[cand];
       if (raw) {
         result = mapModelSpec(p as ProviderId, cand, raw);
-        lookupCache.set(cacheKey, result);
+        setLookupCache(cacheKey, result);
         return result;
       }
     }
+    // Q-33: tightened fuzzy match — exact, `endsWith("/"+modelId)` boundary,
+    // or normalized equality. The old loose `modelId.endsWith(key)` is removed
+    // (e.g. "gpt-4o-mini-extra" must not match "mini").
     for (const [key, raw] of Object.entries(providerData.models as Record<string, any>)) {
-      if (key === modelId || key.endsWith(`/${modelId}`) || modelId.endsWith(key) || normalizeModelIdForLookup(key) === normalizeModelIdForLookup(modelId)) {
+      if (key === modelId || key.endsWith(`/${modelId}`) || normalizeModelIdForLookup(key) === normalizeModelIdForLookup(modelId)) {
         result = mapModelSpec(p as ProviderId, key, raw as any);
-        lookupCache.set(cacheKey, result);
+        setLookupCache(cacheKey, result);
         return result;
       }
     }
@@ -217,11 +287,11 @@ export function getModelFromCatalog(providerInput: string, modelIdInput: string)
   const hit = index.get(lowerModelId) || index.get(strippedLower);
   if (hit) {
     result = mapModelSpec(hit.provider, hit.key, hit.raw);
-    lookupCache.set(cacheKey, result);
+    setLookupCache(cacheKey, result);
     return result;
   }
 
-  lookupCache.set(cacheKey, undefined);
+  setLookupCache(cacheKey, undefined);
   return undefined;
 }
 
@@ -349,16 +419,16 @@ export class ThinkingLevelError extends Error {
     remedy?: string;
   }) {
     const remedyLines = opts.remedy
-      ? `\n\n  \x1b[36m💡 How to fix:\x1b[0m\n    ${opts.remedy}`
+      ? `\n\n  How to fix:\n    ${opts.remedy}`
       : "";
     const allowedLine = opts.allowedLevels.length > 0
-      ? `\n  \x1b[1mAllowed Levels:\x1b[0m  [${opts.allowedLevels.map((l) => `"${l}"`).join(", ")}]`
+      ? `\n  Allowed Levels:  [${opts.allowedLevels.map((l) => `"${l}"`).join(", ")}]`
       : "";
 
     const formattedMessage =
-      `\x1b[31m[Agent Accelerator] ThinkingLevel Mismatch for "${opts.provider}/${opts.modelId}":\x1b[0m\n` +
-      `  \x1b[1mRequested Level:\x1b[0m "${opts.requestedLevel}"\n` +
-      `  \x1b[1mIssue:\x1b[0m           ${opts.reason}` +
+      `[Agent Accelerator] ThinkingLevel Mismatch for "${opts.provider}/${opts.modelId}":\n` +
+      `  Requested Level: "${opts.requestedLevel}"\n` +
+      `  Issue:           ${opts.reason}` +
       allowedLine +
       remedyLines;
 
@@ -454,7 +524,7 @@ export function validateModelThinking(provider: string, modelId: string, request
  * @example `const googleModels = getModelsForProvider("google");`
  */
 export function getModelsForProvider(provider: string): ModelSpec[] {
-  if (providerModelsCache.has(provider)) return providerModelsCache.get(provider)!;
+  if (providerModelsCache.has(provider)) return [...providerModelsCache.get(provider)!];
   const aliases = PROVIDER_ALIASES[provider] || [provider];
   const seen = new Set<string>();
   const out: ModelSpec[] = [];
@@ -468,9 +538,19 @@ export function getModelsForProvider(provider: string): ModelSpec[] {
       out.push(mapModelSpec(alias as ProviderId, key, raw));
     }
   }
+  // Q-33: include custom-registered models for this provider/alias set.
+  for (const spec of customModelRegistry.values()) {
+    if (aliases.includes(String(spec.provider)) || String(spec.provider) === provider) {
+      if (!seen.has(spec.id)) {
+        seen.add(spec.id);
+        out.push({ ...spec });
+      }
+    }
+  }
   // Also include our internal provider id mapping
+  // Q-33: return copies — cache the canonical array, hand out a fresh copy.
   providerModelsCache.set(provider, out);
-  return out;
+  return [...out];
 }
 
 export const GOOGLE_MODELS: ModelSpec[] = [...getModelsForProvider("google")];
@@ -509,6 +589,30 @@ export {
   type RefreshCatalogOptions,
 } from "./catalog-cache.ts";
 
+/**
+ * True when the model can enforce `response_format`/`text.format` natively.
+ * Unknown models (custom endpoints, dynamic routers) count as capable —
+ * the provider verdict stands, matching `assertModalitiesSupported`.
+ * Models with catalog `structured_output: false` return false so callers can
+ * emulate via prompt instruction + client validation instead of 400ing.
+ *
+ * @example `modelSupportsStructuredOutput("openrouter", "inclusionai/ling-3.0-flash-sante:free")`
+ */
+export function modelSupportsStructuredOutput(provider: string, modelId: string): boolean {
+  try {
+    const spec = getModelFromCatalog(provider, modelId);
+    if (!spec) return true;
+    if (typeof spec.capabilities?.supportsStructuredOutput === "boolean") {
+      return spec.capabilities.supportsStructuredOutput;
+    }
+    const raw = (spec as { raw?: { structured_output?: unknown } }).raw;
+    if (raw && typeof raw.structured_output === "boolean") return raw.structured_output;
+    return true;
+  } catch {
+    return true;
+  }
+}
+
 /**
  * Permissive placeholder so custom endpoints never fail preflight:
  * allows every ThinkingLevel (none -> max + dynamic).
@@ -543,6 +647,7 @@ export function createGenericModelSpec(provider: string, modelId: string): Model
       supportsLongCacheRetention: false,
       supportsParallelToolCalls: true,
       supportsStreaming: true,
+      supportsStructuredOutput: true,
       modalities: ["text"],
     },
     pricing: {},

package/src/providers/google.ts

@@ -40,8 +40,19 @@ import { safeStringify } from "../utils/serialization.ts";
 import { stripSchemaForGoogle } from "../tools/schema.ts";
 import { toConciseProviderError, assertModalitiesSupported } from "../utils/errors.ts";
 import { withRetries } from "../utils/retry.ts";
+import { setHeaderCaseInsensitive, shouldEchoSignature } from "../utils/headers.ts";
+import {
+  newToolCallId,
+  redactedHeaders,
+  readErrorPayload,
+  incompleteStreamError,
+  combinedSignal,
+  timeoutFor,
+  hasAuthHeader,
+  clampToolCallId,
+} from "./shared.ts";
 import { createGenericModelSpec } from "../models/catalog.ts";
-import { getModelFromCatalog, getModelsForProvider } from "../models/catalog.ts";
+import { getModelFromCatalog, getModelsForProvider, modelSupportsStructuredOutput } from "../models/catalog.ts";
 import {
   mapThinkingLevelToGoogle,
   mapServiceTierToGoogle,
@@ -50,6 +61,10 @@ import {
   lastProviderFor,
   noteProviderTurn,
   parseStreamedToolArguments,
+  mapOutputToGoogle,
+  normalizeStructuredOutput,
+  augmentSystemPromptWithStructuredOutput,
+  emitProviderWarning,
 } from "../providers.ts";
 
 // ---------------------------------------------------------------------------
@@ -167,7 +182,10 @@ function resolveBaseUrl(options?: ProviderRequestOptions): string {
 }
 
 function resolveApiKey(options?: ProviderRequestOptions): string | undefined {
-  return options?.apiKey || getApiKey("google", undefined, options?.env);
+  const key = getApiKey("google", options?.apiKey, options?.env);
+  if (key) return key;
+  if (hasAuthHeader(options?.headers)) return "unused";
+  return undefined;
 }
 
 function cleanModelId(model: string | ModelSpec): string {
@@ -304,9 +322,16 @@ async function fullHistorySteps(context: ProviderContext): Promise<InteractionIn
       const texts: string[] = [];
       for (const part of m.content) {
         if (part.type === "thinking" && part.thinking) {
+          // Q-18: preserve namespaced signatures only — foreign-provider
+          // signatures never echo here; untagged legacy echoes (compat).
+          const partProvider = (part as { thoughtSignatureProvider?: unknown }).thoughtSignatureProvider;
+          const msgProvider = (m as { thoughtSignatureProvider?: unknown }).thoughtSignatureProvider;
+          const sig = shouldEchoSignature(partProvider ?? msgProvider, "google")
+            ? part.thoughtSignature || m.thoughtSignature || ""
+            : "";
           steps.push({
             type: "thought",
-            signature: part.thoughtSignature || m.thoughtSignature || "",
+            signature: sig,
             summary: [{ type: "text", text: part.thinking }],
           });
         } else if (part.type === "tool_call") {
@@ -328,7 +353,11 @@ async function fullHistorySteps(context: ProviderContext): Promise<InteractionIn
       } else if (m.thoughtSignature && !steps.some((s) => s.type === "thought")) {
         // Preserve a signature-only thought so stateless chaining keeps
         // reasoning continuity even when no summary text was retained.
-        steps.push({ type: "thought", signature: m.thoughtSignature });
+        // Q-18: only for google/untagged signatures.
+        const msgProvider = (m as { thoughtSignatureProvider?: unknown }).thoughtSignatureProvider;
+        if (shouldEchoSignature(msgProvider, "google")) {
+          steps.push({ type: "thought", signature: m.thoughtSignature });
+        }
       }
     } else if (m.role === "tool") {
       if (!Array.isArray(m.content)) continue;
@@ -408,7 +437,7 @@ function parseInteraction(
       const args =
         step.arguments && typeof step.arguments === "object" ? step.arguments : { raw: step.arguments };
       toolCalls.push({
-        id: step.id || `call_${Math.random().toString(36).slice(2, 9)}`,
+        id: step.id || newToolCallId(),
         name: step.name || "unknown",
         arguments: args as Record<string, unknown>,
         rawArguments: JSON.stringify(args),
@@ -431,26 +460,11 @@ function parseInteraction(
   };
 }
 
-function redactedHeaders(headers: Record<string, string>): Record<string, string> {
-  const out: Record<string, string> = {};
-  for (const [k, v] of Object.entries(headers)) {
-    out[k] = k.toLowerCase() === "x-goog-api-key" ? "[REDACTED]" : v;
-  }
-  return out;
-}
-
-function readErrorPayload(bodyText: string): { message: string; code?: string | number } {
-  try {
-    const parsed: unknown = JSON.parse(bodyText);
-    const first = Array.isArray(parsed) ? parsed[0] : parsed;
-    const err = (first as { error?: { message?: string; code?: string | number; status?: string } })?.error;
-    if (err && typeof err.message === "string") {
-      return { message: err.message, code: err.code ?? err.status };
-    }
-    return { message: bodyText.slice(0, 300) };
-  } catch {
-    return { message: bodyText.slice(0, 300) };
-  }
+/** Local per-provider signature tag (Q-18): google history preserves only
+ * google/untagged signatures; foreign-provider signatures never echo here. */
+function withGoogleSignature(sig: string | undefined): { thoughtSignature?: string; thoughtSignatureProvider?: string } {
+  if (!sig) return {};
+  return { thoughtSignature: sig, thoughtSignatureProvider: "google" };
 }
 
 // ---------------------------------------------------------------------------
@@ -512,11 +526,43 @@ export class GoogleInteractionsProvider implements Provider {
         input: "",
         ...(stream ? { stream: true } : {}),
       };
-      if (context.systemPrompt) body.system_instruction = context.systemPrompt;
+      // Structured outputs: native `response_format` when supported, else
+      // emulated via system instruction (catalog `structured_output: false`
+      // would 400 on the wire shape).
+      let outputEmulated = false;
+      let outputSpec: import("../types/model.ts").StructuredOutputSpec | undefined;
+      try {
+        outputSpec = normalizeStructuredOutput(options?.output ?? (options as { outputSchema?: unknown })?.outputSchema);
+      } catch {
+        outputSpec = undefined;
+      }
+      let effectiveSystemPrompt = context.systemPrompt;
+      if (outputSpec && !modelSupportsStructuredOutput("google", modelId)) {
+        outputEmulated = true;
+        effectiveSystemPrompt = augmentSystemPromptWithStructuredOutput(context.systemPrompt, outputSpec);
+        emitProviderWarning({
+          provider: "google",
+          capability: "structured output",
+          requested: `${outputSpec.name} (google/${modelId})`,
+          reason: "the catalog reports structured_output: false for this model, so native response_format is unsupported.",
+          fallback: "emulated JSON instruction + client validation (no response_format is sent)",
+        });
+      }
+      if (effectiveSystemPrompt) body.system_instruction = effectiveSystemPrompt;
       const googleTools = toGoogleTools(tools);
       if (googleTools) body.tools = googleTools;
       if (Object.keys(generationConfig).length > 0) body.generation_config = generationConfig;
       if (serviceTier) body.service_tier = serviceTier;
+      // Structured outputs: Interactions `response_format{type:text,mime_type:application/json,schema}`.
+      // Skipped when emulated (instruction already in `system_instruction`).
+      if (outputSpec && !outputEmulated) {
+        try {
+          const mapped = mapOutputToGoogle(outputSpec);
+          if (mapped) (body as unknown as Record<string, unknown>)["response_format"] = mapped.responseFormat;
+        } catch {
+          // why: invalid output shapes fail fast at Agent construction/loop validation.
+        }
+      }
 
       const prevProvider = lastProviderFor(sessionId);
       const switched = !!prevProvider && prevProvider !== "google";
@@ -557,7 +603,11 @@ export class GoogleInteractionsProvider implements Provider {
     for (const [k, v] of Object.entries(options?.headers ?? {})) {
       if (!INTERNAL_HEADERS.has(k.toLowerCase())) headers[k] = v;
     }
-    headers["x-goog-api-key"] = apiKey;
+    // Q-17: key travels as the `x-goog-api-key` header (never `?key=` in the
+    // URL, which would leak into logs). Case-insensitive merge so a custom
+    // `X-Goog-Api-Key` never duplicates the canonical header. Proxy flows
+    // (`apiKey === "unused"`) preserve custom auth instead of overwriting.
+    if (apiKey !== "unused") setHeaderCaseInsensitive(headers, "x-goog-api-key", apiKey);
     return { method: "POST", headers, body: JSON.stringify(body), signal };
   }
 
@@ -568,13 +618,18 @@ export class GoogleInteractionsProvider implements Provider {
     apiKey: string,
     signal?: AbortSignal
   ): Promise<{ status: number; statusText: string; headers: Record<string, string>; text: string }> {
-    const res = await fetch(url, this.requestInit(body, options, apiKey, signal));
-    const text = await res.text();
-    const headers: Record<string, string> = {};
-    res.headers.forEach((v, k) => {
-      headers[k] = v;
-    });
-    return { status: res.status, statusText: res.statusText, headers, text };
+    const { signal: effective, cleanup } = combinedSignal(signal, timeoutFor(options as { timeoutMs?: number } | undefined));
+    try {
+      const res = await fetch(url, this.requestInit(body, options, apiKey, effective));
+      const text = await res.text();
+      const headers: Record<string, string> = {};
+      res.headers.forEach((v, k) => {
+        headers[k] = v;
+      });
+      return { status: res.status, statusText: res.statusText, headers, text };
+    } finally {
+      cleanup();
+    }
   }
 
   private throwIfError(
@@ -585,13 +640,21 @@ export class GoogleInteractionsProvider implements Provider {
     modelId: string
   ): void {
     if (status >= 200 && status < 300) return;
-    const { message, code } = readErrorPayload(bodyText);
-    const err: Record<string, unknown> & Error = new Error(message) as Record<string, unknown> & Error;
+    const { message, code, errorType, raw } = readErrorPayload(bodyText);
+    const hint =
+      status === 401
+        ? " Check GEMINI_API_KEY/GOOGLE_API_KEY (no quotes/spaces, correct provider), GOOGLE_BASE_URL, and that the key is loaded (bun --env-file=.env.local)."
+        : "";
+    const fullMessage = `${message}${hint}`;
+    const err: Record<string, unknown> & Error = new Error(fullMessage) as Record<string, unknown> & Error;
     (err as Record<string, unknown>)["statusCode"] = status;
     (err as Record<string, unknown>)["status"] = status;
     (err as Record<string, unknown>)["responseBody"] = bodyText.slice(0, 500);
     (err as Record<string, unknown>)["url"] = url.split("?")[0];
+    (err as Record<string, unknown>)["data"] = { error: { message: fullMessage } };
     if (code !== undefined) (err as Record<string, unknown>)["code"] = code;
+    if (errorType) (err as Record<string, unknown>)["errorType"] = errorType;
+    if (raw) (err as Record<string, unknown>)["raw"] = raw;
     throw toConciseProviderError(err, "google", modelId);
   }
 
@@ -733,7 +796,21 @@ export class GoogleInteractionsProvider implements Provider {
           body,
         };
 
-        const res = await fetch(url, this.requestInit(body, options, apiKey, linked.signal));
+        const streamTimeoutMs = timeoutFor(options as { timeoutMs?: number } | undefined);
+        const streamTimeoutTimer =
+          streamTimeoutMs && streamTimeoutMs > 0
+            ? setTimeout(() => {
+                try {
+                  linked.abort();
+                } catch {}
+              }, streamTimeoutMs)
+            : undefined;
+        let res: Response;
+        try {
+          res = await fetch(url, this.requestInit(body, options, apiKey, linked.signal));
+        } finally {
+          if (streamTimeoutTimer) clearTimeout(streamTimeoutTimer);
+        }
         if (!res.ok || !res.body) {
           const text = !res.ok ? await res.text().catch(() => "") : "";
           if (!res.ok) this.throwIfError(res.status, res.statusText, url, text, clean);
@@ -743,7 +820,7 @@ export class GoogleInteractionsProvider implements Provider {
         res.headers.forEach((v, k) => {
           responseHeaders[k] = v;
         });
-        const responseMeta = { status: res.status, statusText: res.statusText, headers: responseHeaders };
+        const responseMeta: Record<string, unknown> & { status: number; statusText: string; headers: Record<string, string> } = { status: res.status, statusText: res.statusText, headers: responseHeaders };
         eventStream.push({ type: "start", raw: { request: rawRequest } } as never);
 
         const parser = new SSEParser();
@@ -755,6 +832,10 @@ export class GoogleInteractionsProvider implements Provider {
         const calls = new Map<number, { id: string; name: string; startArgs: string; deltaArgs: string }>();
         let usage: TokenUsage = { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
         let finishReason = "stop";
+        let sawFinishReason = false;
+        let sawUsage = false;
+        let badFrames = 0;
+        let framesSeen = 0;
         let responseId: string | undefined;
         let completedBody: unknown = undefined;
         let aborted = false;
@@ -770,11 +851,17 @@ export class GoogleInteractionsProvider implements Provider {
         );
 
         const handleMessage = (event: string | undefined, data: string): void => {
-          if (!data || data === "[DONE]") return;
+          if (!data) return;
+          if (data === "[DONE]") {
+            sawFinishReason = sawFinishReason || completedBody !== undefined || sawUsage;
+            return;
+          }
           let msg: Record<string, unknown>;
           try {
             msg = JSON.parse(data) as Record<string, unknown>;
+            framesSeen += 1;
           } catch {
+            badFrames += 1;
             return;
           }
           const type = (msg["event_type"] as string) || event;
@@ -826,7 +913,7 @@ export class GoogleInteractionsProvider implements Provider {
               const args = step["arguments"];
               const startArgs = typeof args === "string" ? args : args ? JSON.stringify(args) : "";
               calls.set(index, {
-                id: (step["id"] as string) || `call_${Math.random().toString(36).slice(2, 9)}`,
+                id: (step["id"] as string) || newToolCallId(),
                 name: (step["name"] as string) || "unknown",
                 startArgs,
                 deltaArgs: "",
@@ -836,8 +923,12 @@ export class GoogleInteractionsProvider implements Provider {
             const interaction = (msg["interaction"] as InteractionObject) ?? {};
             completedBody = msg["interaction"];
             if (interaction.id) responseId = interaction.id;
-            if (interaction.usage) usage = mapUsage(interaction.usage);
+            if (interaction.usage) {
+              usage = mapUsage(interaction.usage);
+              sawUsage = true;
+            }
             finishReason = mapFinishReason(interaction.status);
+            sawFinishReason = true;
             eventStream.push({ type: "usage", usage });
           }
         };
@@ -882,10 +973,25 @@ export class GoogleInteractionsProvider implements Provider {
         }
         noteProviderTurn(sessionId, "google");
 
+        // Q-23: terminal-state guard — fail `incomplete_stream` (retryable)
+        // instead of resolving empty success. Skipped for non-SSE payloads
+        // (JSON mocks) where no SSE frames were ever seen.
+        const hasTerminal = completedBody !== undefined || sawFinishReason || sawUsage;
         // Trim provider trailing blank lines from finalized thinking (live
         // deltas already emitted raw; display collapse happens in the
         // wrapThinking presentation layer). Stateful bodies unaffected.
-        const cleanThinking = thinking.replace(/\n{3,}/g, "\n\n").trim();
+        const cleanThinkingEarly = thinking.replace(/\n{3,}/g, "\n\n").trim();
+        const ctEntry = Object.entries(responseHeaders).find(([k]) => k.toLowerCase() === "content-type");
+        const isSSEPayload =
+          (typeof ctEntry?.[1] === "string" && ((ctEntry[1] as string).includes("event-stream") || (ctEntry[1] as string).startsWith("text/"))) ||
+          framesSeen > 0 ||
+          badFrames > 0;
+        if (!hasTerminal && !text && !cleanThinkingEarly && toolCalls.length === 0 && isSSEPayload) {
+          eventStream.fail(incompleteStreamError("google", clean));
+          return;
+        }
+
+        const cleanThinking = cleanThinkingEarly;
         const finalResponse = new AgentResponse({
           text,
           thinking: cleanThinking || undefined,
@@ -896,7 +1002,10 @@ export class GoogleInteractionsProvider implements Provider {
           responseId,
           model: clean,
           provider: "google",
-          raw: { request: rawRequest, response: { ...responseMeta, body: completedBody } },
+          raw: {
+            request: rawRequest,
+            response: { ...responseMeta, body: completedBody, badFrames } as unknown as ProviderRawData["response"],
+          },
           durationMs: Date.now() - startTime,
         });
         eventStream.push({ type: "done", delta: "", usage, finishReason, responseId });