@tonyclaw/agent-inspector 3.1.19 → 3.1.21

package/src/components/providers/SettingsDialog.tsx

@@ -150,28 +150,72 @@ export function SettingsDialog(): JSX.Element {
 
 type LogStorageStats = {
   memoryCount: number;
-  logDir: string;
-  logFileCount: number;
-  logBytes: number;
-  chunkDir: string;
-  chunkFileCount: number;
-  chunkBytes: number;
-  sessionArchiveDir: string;
-  sessionArchiveFileCount: number;
-  sessionArchiveBytes: number;
+  inventory: {
+    checkedAt: string;
+    totalFiles: number;
+    totalBytes: number;
+    artifacts: StorageArtifactSummary[];
+  };
+  policy: {
+    maxAgeMs: number;
+    maxTotalBytes: number;
+  };
+  reclaimableBytes: number;
+  lastGc: {
+    checkedAt: string;
+    filesDeleted: number;
+    bytesDeleted: number;
+    errors: number;
+    beforeTotalBytes: number;
+    afterTotalBytes: number;
+  } | null;
 };
 
+type StorageArtifactSummary = {
+  kind: string;
+  root: string;
+  sensitivity: string;
+  cleanupBehavior: string;
+  fileCount: number;
+  bytes: number;
+  oldestModifiedAt: string | null;
+  newestModifiedAt: string | null;
+};
+
+const StorageArtifactSummarySchema = z.object({
+  kind: z.string(),
+  root: z.string(),
+  sensitivity: z.string(),
+  cleanupBehavior: z.string(),
+  fileCount: z.number(),
+  bytes: z.number(),
+  oldestModifiedAt: z.string().nullable(),
+  newestModifiedAt: z.string().nullable(),
+});
+
 const LogStorageStatsSchema = z.object({
   memoryCount: z.number(),
-  logDir: z.string(),
-  logFileCount: z.number(),
-  logBytes: z.number(),
-  chunkDir: z.string(),
-  chunkFileCount: z.number(),
-  chunkBytes: z.number(),
-  sessionArchiveDir: z.string(),
-  sessionArchiveFileCount: z.number(),
-  sessionArchiveBytes: z.number(),
+  inventory: z.object({
+    checkedAt: z.string(),
+    totalFiles: z.number(),
+    totalBytes: z.number(),
+    artifacts: z.array(StorageArtifactSummarySchema),
+  }),
+  policy: z.object({
+    maxAgeMs: z.number(),
+    maxTotalBytes: z.number(),
+  }),
+  reclaimableBytes: z.number(),
+  lastGc: z
+    .object({
+      checkedAt: z.string(),
+      filesDeleted: z.number(),
+      bytesDeleted: z.number(),
+      errors: z.number(),
+      beforeTotalBytes: z.number(),
+      afterTotalBytes: z.number(),
+    })
+    .nullable(),
 });
 
 const STORAGE_STATS_FETCH_TIMEOUT_MS = 10_000;
@@ -183,10 +227,16 @@ function formatBytes(bytes: number): string {
   return `${(bytes / 1024 / 1024 / 1024).toFixed(1)} GiB`;
 }
 
+function formatRetention(maxAgeMs: number): string {
+  const days = Math.round(maxAgeMs / 1000 / 60 / 60 / 24);
+  return `${days.toLocaleString()} days`;
+}
+
 function StorageSettingsTab(): JSX.Element {
   const [stats, setStats] = useState<LogStorageStats | null>(null);
   const [error, setError] = useState<string | null>(null);
   const [loading, setLoading] = useState(false);
+  const [gcLoading, setGcLoading] = useState(false);
   const [copiedId, setCopiedId] = useState<string | null>(null);
 
   const refresh = useCallback(async () => {
@@ -194,7 +244,7 @@ function StorageSettingsTab(): JSX.Element {
     setError(null);
     try {
       const data = await fetchJsonWithTimeout(
-        "/api/logs?stats=1",
+        "/api/storage",
         LogStorageStatsSchema,
         STORAGE_STATS_FETCH_TIMEOUT_MS,
         undefined,
@@ -220,68 +270,98 @@ function StorageSettingsTab(): JSX.Element {
     });
   }, []);
 
+  const handleRunGc = useCallback(async () => {
+    setGcLoading(true);
+    setError(null);
+    try {
+      const data = await fetchJsonWithTimeout(
+        "/api/storage",
+        LogStorageStatsSchema,
+        STORAGE_STATS_FETCH_TIMEOUT_MS,
+        { method: "POST" },
+        (response) => `Failed to run storage GC: HTTP ${String(response.status)}`,
+      );
+      setStats(data);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err));
+    } finally {
+      setGcLoading(false);
+    }
+  }, []);
+
   return (
     <div className="space-y-4">
       <div className="flex items-center justify-between gap-3">
         <div className="min-w-0">
-          <h3 className="text-sm font-semibold">Log storage</h3>
+          <h3 className="text-sm font-semibold">Storage lifecycle</h3>
           <p className="text-xs text-muted-foreground">
-            Inspect local log and streaming chunk footprint before exporting or clearing sessions.
+            Inspect local captured-data footprint, retention policy, and safe reclaim actions.
           </p>
         </div>
-        <Button type="button" variant="outline" size="sm" onClick={() => void refresh()}>
-          {loading ? "Refreshing..." : "Refresh"}
-        </Button>
+        <div className="flex shrink-0 items-center gap-2">
+          <Button
+            type="button"
+            variant="outline"
+            size="sm"
+            onClick={() => void handleRunGc()}
+            disabled={gcLoading}
+          >
+            {gcLoading ? "Running..." : "Run GC now"}
+          </Button>
+          <Button type="button" variant="outline" size="sm" onClick={() => void refresh()}>
+            {loading ? "Refreshing..." : "Refresh"}
+          </Button>
+        </div>
       </div>
 
       {stats !== null && (
         <div className="grid gap-2 text-xs">
-          <CopyableSetupValue
-            id="log-dir"
-            label="Log storage path"
-            value={stats.logDir}
-            copiedId={copiedId}
-            onCopy={handleCopy}
-          />
-          <CopyableSetupValue
-            id="chunk-dir"
-            label="Streaming chunks storage path"
-            value={stats.chunkDir}
-            copiedId={copiedId}
-            onCopy={handleCopy}
-          />
-          <CopyableSetupValue
-            id="session-archive-dir"
-            label="Session archive storage path"
-            value={stats.sessionArchiveDir}
-            copiedId={copiedId}
-            onCopy={handleCopy}
-          />
-          <div className="rounded-md bg-muted/20 px-3 py-2">
-            <div className="font-medium">In-memory logs</div>
-            <div className="mt-1 font-mono text-muted-foreground">
-              {stats.memoryCount.toLocaleString()} loaded
-            </div>
-          </div>
-          <div className="rounded-md bg-muted/20 px-3 py-2">
-            <div className="font-medium">Log files</div>
-            <div className="mt-1 font-mono text-muted-foreground">
-              {stats.logFileCount.toLocaleString()} files / {formatBytes(stats.logBytes)}
-            </div>
-          </div>
-          <div className="rounded-md bg-muted/20 px-3 py-2">
-            <div className="font-medium">Streaming chunks</div>
-            <div className="mt-1 font-mono text-muted-foreground">
-              {stats.chunkFileCount.toLocaleString()} files / {formatBytes(stats.chunkBytes)}
-            </div>
-          </div>
-          <div className="rounded-md bg-muted/20 px-3 py-2">
-            <div className="font-medium">Session archives</div>
-            <div className="mt-1 font-mono text-muted-foreground">
-              {stats.sessionArchiveFileCount.toLocaleString()} files /{" "}
-              {formatBytes(stats.sessionArchiveBytes)}
-            </div>
+          <div className="grid gap-2 sm:grid-cols-2">
+            <StorageMetricCard
+              label="Persisted footprint"
+              value={`${stats.inventory.totalFiles.toLocaleString()} files / ${formatBytes(
+                stats.inventory.totalBytes,
+              )}`}
+              detail={`Checked ${new Date(stats.inventory.checkedAt).toLocaleString()}`}
+            />
+            <StorageMetricCard
+              label="Auto-reclaimable"
+              value={formatBytes(stats.reclaimableBytes)}
+              detail={`Retention ${formatRetention(stats.policy.maxAgeMs)} / max ${formatBytes(
+                stats.policy.maxTotalBytes,
+              )}`}
+            />
+            <StorageMetricCard
+              label="In-memory logs"
+              value={`${stats.memoryCount.toLocaleString()} loaded`}
+              detail="Recent completed entries kept hot for the UI"
+            />
+            <StorageMetricCard
+              label="Last GC"
+              value={
+                stats.lastGc === null
+                  ? "Not run yet"
+                  : `${stats.lastGc.filesDeleted.toLocaleString()} files / ${formatBytes(
+                      stats.lastGc.bytesDeleted,
+                    )}`
+              }
+              detail={
+                stats.lastGc === null
+                  ? "Runs at startup, on schedule, or manually here"
+                  : `${new Date(stats.lastGc.checkedAt).toLocaleString()} · ${
+                      stats.lastGc.errors
+                    } errors`
+              }
+            />
           </div>
+          {stats.inventory.artifacts.map((artifact) => (
+            <StorageArtifactRow
+              key={`${artifact.kind}:${artifact.root}`}
+              artifact={artifact}
+              copiedId={copiedId}
+              onCopy={handleCopy}
+            />
+          ))}
         </div>
       )}
 
@@ -290,6 +370,81 @@ function StorageSettingsTab(): JSX.Element {
   );
 }
 
+function cleanupBehaviorLabel(cleanupBehavior: string): string {
+  switch (cleanupBehavior) {
+    case "retention-gc":
+      return "Retention GC";
+    case "orphan-reclaim":
+      return "Orphan reclaim";
+    case "rotation":
+      return "Rotation-owned";
+    case "manual-owner-delete":
+      return "Manual only";
+    default:
+      return cleanupBehavior;
+  }
+}
+
+function StorageMetricCard({
+  label,
+  value,
+  detail,
+}: {
+  label: string;
+  value: string;
+  detail: string;
+}): JSX.Element {
+  return (
+    <div className="rounded-md bg-muted/20 px-3 py-2">
+      <div className="font-medium">{label}</div>
+      <div className="mt-1 font-mono text-muted-foreground">{value}</div>
+      <div className="mt-1 text-[11px] text-muted-foreground">{detail}</div>
+    </div>
+  );
+}
+
+function StorageArtifactRow({
+  artifact,
+  copiedId,
+  onCopy,
+}: {
+  artifact: StorageArtifactSummary;
+  copiedId: string | null;
+  onCopy: (id: string, value: string) => void;
+}): JSX.Element {
+  const id = `storage-${artifact.kind}`;
+  const oldest = artifact.oldestModifiedAt === null ? "none" : new Date(artifact.oldestModifiedAt);
+  const newest = artifact.newestModifiedAt === null ? "none" : new Date(artifact.newestModifiedAt);
+  return (
+    <div className="rounded-md border border-border/45 bg-muted/15 px-3 py-2">
+      <div className="flex flex-wrap items-center justify-between gap-2">
+        <div>
+          <div className="font-medium">{artifact.kind}</div>
+          <div className="mt-1 text-[11px] text-muted-foreground">
+            {cleanupBehaviorLabel(artifact.cleanupBehavior)} · {artifact.sensitivity}
+          </div>
+        </div>
+        <div className="text-right font-mono text-muted-foreground">
+          {artifact.fileCount.toLocaleString()} files / {formatBytes(artifact.bytes)}
+        </div>
+      </div>
+      <div className="mt-2 grid gap-1 text-[11px] text-muted-foreground sm:grid-cols-2">
+        <div>Oldest: {oldest instanceof Date ? oldest.toLocaleString() : oldest}</div>
+        <div>Newest: {newest instanceof Date ? newest.toLocaleString() : newest}</div>
+      </div>
+      <div className="mt-2">
+        <CopyableSetupValue
+          id={id}
+          label="Root path"
+          value={artifact.root}
+          copiedId={copiedId}
+          onCopy={onCopy}
+        />
+      </div>
+    </div>
+  );
+}
+
 function CopyableSetupValue({
   id,
   label,
@@ -330,7 +485,7 @@ function CopyableSetupValue({
   );
 }
 
-function OnboardingSettingsTab(): JSX.Element {
+export function OnboardingSettingsTab(): JSX.Element {
   const [copiedId, setCopiedId] = useState<string | null>(null);
   const [endpoints, setEndpoints] = useState<CodingAgentEndpoints | null>(null);
   useEffect(() => subscribeCodingAgentEndpoints(setEndpoints), []);
@@ -349,6 +504,12 @@ function OnboardingSettingsTab(): JSX.Element {
         value: "agent-inspector onboard --uninstall",
       },
       { id: "claude", label: "Claude Code command", value: "/agent-inspector:onboard" },
+      { id: "doctor", label: "Backend doctor", value: "agent-inspector doctor --verbose" },
+      {
+        id: "support-bundle",
+        label: "Redacted support bundle",
+        value: "agent-inspector doctor --support-bundle",
+      },
       {
         id: "codex",
         label: "Codex prompt",
@@ -432,6 +593,18 @@ function OnboardingSettingsTab(): JSX.Element {
           />
         ))}
       </div>
+      <div className="grid gap-2 rounded-md border border-status-info/25 bg-status-info/10 px-3 py-2 text-xs">
+        <div className="font-medium text-foreground">Verified first trace flow</div>
+        <ol className="ml-4 list-decimal space-y-1 text-muted-foreground">
+          <li>Start Agent Inspector and confirm the application bar shows Live.</li>
+          <li>Copy the Proxy URL or MCP URL that matches your coding agent.</li>
+          <li>Run a tiny coding-agent prompt such as “say hello and stop”.</li>
+          <li>
+            Return to Logs and confirm one new request appears with request, response, tokens, and
+            tool activity when present.
+          </li>
+        </ol>
+      </div>
       <div className="grid gap-2 rounded-md bg-muted/15 px-3 py-2 text-xs text-muted-foreground">
         <div className="flex items-center gap-2">
           <Check className="size-3.5 text-status-success" />
@@ -494,6 +667,24 @@ function OnboardingSettingsTab(): JSX.Element {
             reachable from that tool and verify the network/firewall path.
           </span>
         </div>
+        <div className="flex items-start gap-2">
+          <Check className="mt-0.5 size-3.5 text-status-success" />
+          <span>
+            If the first trace does not appear, run{" "}
+            <code className="rounded bg-muted px-1 py-0.5 font-mono text-[11px] text-foreground">
+              agent-inspector doctor --verbose
+            </code>{" "}
+            and compare the agent base URL with the current Proxy URL. A base-path mismatch such as{" "}
+            <code className="rounded bg-muted px-1 py-0.5 font-mono text-[11px] text-foreground">
+              /
+            </code>{" "}
+            versus{" "}
+            <code className="rounded bg-muted px-1 py-0.5 font-mono text-[11px] text-foreground">
+              /inspector
+            </code>{" "}
+            means the tool is talking to a different Inspector surface.
+          </span>
+        </div>
       </div>
     </div>
   );

package/src/components/proxy-viewer/LogEntry.tsx

@@ -29,9 +29,12 @@ import {
 import type { AnatomySegment } from "./anatomy/types";
 import { useAnatomyJump } from "./anatomy/useAnatomyJump";
 import {
+  deleteHydratedLogFromCache,
   describeFullBodyHydrationError,
   formatBodyHydrationFootprint,
   formatBytes,
+  getOrFetchHydratedLog,
+  readHydratedLogFromCache,
   type FullBodyHydrationError,
 } from "./bodyHydration";
 import { computeHeadersDiff, computeRequestDiff, DiffView } from "./diff";
@@ -874,11 +877,12 @@ export const LogEntry = memo(function ({
 
   const retryFullBodyHydration = useCallback(() => {
     if (bodyHydrationInFlightRef.current) return;
+    deleteHydratedLogFromCache(log.id);
     setHydratedLog(null);
     setBodyHydrationStatus("idle");
     setBodyHydrationError(null);
     setBodyHydrationRetryNonce((current) => current + 1);
-  }, []);
+  }, [log.id]);
 
   const handleToggleExpanded = useCallback(() => {
     const nextExpanded = !expanded;
@@ -931,14 +935,24 @@ export const LogEntry = memo(function ({
     if (!shouldHydrateLogBody(log)) return;
     if (hydratedLog !== null || bodyHydrationInFlightRef.current) return;
 
+    const cached = readHydratedLogFromCache(log.id);
+    if (cached !== null) {
+      setHydratedLog(cached);
+      setBodyHydrationStatus("idle");
+      setBodyHydrationError(null);
+      return;
+    }
+
     let cancelled = false;
     bodyHydrationInFlightRef.current = true;
     setBodyHydrationStatus("loading");
     setBodyHydrationError(null);
-    void fetchJsonWithTimeout(
-      `/api/logs/${String(log.id)}`,
-      CapturedLogSchema,
-      FULL_LOG_HYDRATION_TIMEOUT_MS,
+    void getOrFetchHydratedLog(log.id, () =>
+      fetchJsonWithTimeout(
+        `/api/logs/${String(log.id)}`,
+        CapturedLogSchema,
+        FULL_LOG_HYDRATION_TIMEOUT_MS,
+      ),
     )
       .then((fullLog) => {
         if (cancelled) return;

package/src/components/proxy-viewer/bodyHydration.ts

@@ -1,4 +1,5 @@
 import { ApiTimeoutError } from "../../lib/apiClient";
+import type { CapturedLog } from "../../contracts";
 
 export type FullBodyHydrationError = {
   title: string;
@@ -7,6 +8,10 @@ export type FullBodyHydrationError = {
 
 const DEFAULT_FULL_BODY_HYDRATION_ERROR_DETAIL =
   "The compact log metadata is still available. Retry if the local server was restarting or the body store was briefly unavailable.";
+const DEFAULT_DETAIL_CACHE_LIMIT = 64;
+
+const hydratedLogCache = new Map<number, CapturedLog>();
+const hydratedLogInFlight = new Map<number, Promise<CapturedLog>>();
 
 export function formatBytes(bytes: number): string {
   if (bytes < 1024) return `${bytes.toLocaleString()} B`;
@@ -54,3 +59,65 @@ export function describeFullBodyHydrationError(error: unknown): FullBodyHydratio
     detail: DEFAULT_FULL_BODY_HYDRATION_ERROR_DETAIL,
   };
 }
+
+function detailCacheLimit(): number {
+  const raw = process.env["AGENT_INSPECTOR_UI_DETAIL_CACHE_LIMIT"];
+  if (raw === undefined || raw === "") return DEFAULT_DETAIL_CACHE_LIMIT;
+  const parsed = Number(raw);
+  if (!Number.isSafeInteger(parsed) || parsed < 1 || parsed > 1000) {
+    return DEFAULT_DETAIL_CACHE_LIMIT;
+  }
+  return parsed;
+}
+
+function rememberHydratedLog(log: CapturedLog): CapturedLog {
+  hydratedLogCache.delete(log.id);
+  hydratedLogCache.set(log.id, log);
+  while (hydratedLogCache.size > detailCacheLimit()) {
+    const oldest = hydratedLogCache.keys().next().value;
+    if (typeof oldest !== "number") break;
+    hydratedLogCache.delete(oldest);
+  }
+  return log;
+}
+
+export function readHydratedLogFromCache(logId: number): CapturedLog | null {
+  const cached = hydratedLogCache.get(logId);
+  if (cached === undefined) return null;
+  hydratedLogCache.delete(logId);
+  hydratedLogCache.set(logId, cached);
+  return cached;
+}
+
+export function deleteHydratedLogFromCache(logId: number): void {
+  hydratedLogCache.delete(logId);
+  hydratedLogInFlight.delete(logId);
+}
+
+export function clearHydratedLogCacheForTests(): void {
+  hydratedLogCache.clear();
+  hydratedLogInFlight.clear();
+}
+
+export function getHydratedLogCacheSizeForTests(): number {
+  return hydratedLogCache.size;
+}
+
+export async function getOrFetchHydratedLog(
+  logId: number,
+  fetcher: () => Promise<CapturedLog>,
+): Promise<CapturedLog> {
+  const cached = readHydratedLogFromCache(logId);
+  if (cached !== null) return cached;
+
+  const existing = hydratedLogInFlight.get(logId);
+  if (existing !== undefined) return await existing;
+
+  const pending = fetcher()
+    .then(rememberHydratedLog)
+    .finally(() => {
+      hydratedLogInFlight.delete(logId);
+    });
+  hydratedLogInFlight.set(logId, pending);
+  return await pending;
+}

package/src/components/proxy-viewer/proxyViewerContainerLogic.ts

@@ -31,6 +31,84 @@ export function mergeLogsById(
   return [...byId.values()].toSorted((left, right) => left.id - right.id);
 }
 
+export type IncrementalLogMergeOptions = {
+  recentLimit: number;
+  retainSessionId?: string;
+  retainIds?: ReadonlySet<number>;
+};
+
+export type IncrementalLogMergeResult = {
+  logs: CapturedLog[];
+  index: Map<number, number>;
+};
+
+function shouldRetainLog(log: CapturedLog, options: IncrementalLogMergeOptions): boolean {
+  if (options.retainIds?.has(log.id) === true) return true;
+  if (options.retainSessionId !== undefined && log.sessionId === options.retainSessionId) {
+    return true;
+  }
+  return false;
+}
+
+function trimBoundedLogs(logs: CapturedLog[], options: IncrementalLogMergeOptions): CapturedLog[] {
+  const unretainedCount = logs.reduce(
+    (count, log) => count + (shouldRetainLog(log, options) ? 0 : 1),
+    0,
+  );
+  if (unretainedCount <= options.recentLimit) return logs;
+
+  let unretainedToDrop = unretainedCount - options.recentLimit;
+  const retained: CapturedLog[] = [];
+  for (const log of logs) {
+    if (unretainedToDrop > 0 && !shouldRetainLog(log, options)) {
+      unretainedToDrop -= 1;
+      continue;
+    }
+    retained.push(log);
+  }
+  return retained;
+}
+
+export function buildLogIndexById(logs: readonly CapturedLog[]): Map<number, number> {
+  const index = new Map<number, number>();
+  for (let i = 0; i < logs.length; i += 1) {
+    const log = logs[i];
+    if (log !== undefined) index.set(log.id, i);
+  }
+  return index;
+}
+
+export function mergeLogsIncrementally(
+  previousLogs: readonly CapturedLog[],
+  previousIndex: ReadonlyMap<number, number>,
+  incomingLogs: readonly CapturedLog[],
+  options: IncrementalLogMergeOptions,
+): IncrementalLogMergeResult {
+  if (incomingLogs.length === 0) {
+    const logs = trimBoundedLogs([...previousLogs], options);
+    return { logs, index: buildLogIndexById(logs) };
+  }
+
+  const next = [...previousLogs];
+  let lastId = next.length === 0 ? Number.NEGATIVE_INFINITY : (next.at(-1)?.id ?? 0);
+  let sorted = true;
+
+  for (const log of incomingLogs) {
+    const existingIndex = previousIndex.get(log.id);
+    if (existingIndex !== undefined && existingIndex >= 0 && existingIndex < next.length) {
+      next[existingIndex] = log;
+      continue;
+    }
+    next.push(log);
+    if (log.id < lastId) sorted = false;
+    lastId = Math.max(lastId, log.id);
+  }
+
+  const sortedLogs = sorted ? next : next.toSorted((left, right) => left.id - right.id);
+  const logs = trimBoundedLogs(sortedLogs, options);
+  return { logs, index: buildLogIndexById(logs) };
+}
+
 export function mergeSessionIds(
   previousSessions: readonly string[],
   incomingSessions: readonly string[],

package/src/contracts/index.ts

@@ -9,6 +9,7 @@ export {
   LogBodyPartSchema,
   parseLogId,
   StreamingChunkSchema,
+  StopReasonSchema,
   ToolTraceEventSchema,
 } from "./log";
 export type {
@@ -19,6 +20,7 @@ export type {
   LogId,
   LogBodyPart,
   StreamingChunk,
+  StopReason,
   ToolTraceEvent,
   TokenUsage,
 } from "./log";

package/src/contracts/log.ts

@@ -54,6 +54,10 @@ export const ToolTraceEventSchema = z.object({
 
 export type ToolTraceEvent = z.infer<typeof ToolTraceEventSchema>;
 
+const StopReasonValueSchema = z.enum(["end_turn", "tool_use", "stop", "length"]);
+export const StopReasonSchema = StopReasonValueSchema.nullable();
+export type StopReason = z.infer<typeof StopReasonSchema>;
+
 const StreamingChunksArraySchema = z.object({
   chunks: z.array(StreamingChunkSchema),
   truncated: z.boolean().optional().default(false),
@@ -120,6 +124,7 @@ export const CapturedLogSchema = z.object({
   captureIncompleteReason: CaptureIncompleteReasonSchema.nullable().optional(),
   warnings: z.array(z.string()).optional(),
   toolTraceEvents: z.array(ToolTraceEventSchema).optional(),
+  stopReason: StopReasonSchema.optional(),
   /** Error message from streaming response (e.g., SSE error event) */
   error: z.string().nullable().optional(),
 });