@vertesia/client 1.5.0-dev.20260725.083715Z → 1.5.0-dev.20260806.125520Z

package/src/store/AgentsApi.stream.test.ts

@@ -0,0 +1,298 @@
+import { type AgentMessage, AgentMessageType, type CompactMessage } from '@vertesia/common';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { VertesiaClient } from '../client.js';
+
+const AGENT_RUN_ID = 'run-1';
+const STORE_URL = 'https://store.example.test';
+
+class FakeEventSource {
+    static readonly CONNECTING = 0;
+    static readonly OPEN = 1;
+    static readonly CLOSED = 2;
+
+    static instances: FakeEventSource[] = [];
+    static urls: string[] = [];
+
+    readonly url: string;
+    readonly withCredentials = false;
+    readyState = FakeEventSource.CONNECTING;
+    onopen: ((event: Event) => void) | null = null;
+    onmessage: ((event: MessageEvent) => void) | null = null;
+    onerror: ((event: Event) => void) | null = null;
+
+    constructor(url: string) {
+        this.url = url;
+        FakeEventSource.urls.push(url);
+        FakeEventSource.instances.push(this);
+    }
+
+    close() {
+        this.readyState = FakeEventSource.CLOSED;
+    }
+
+    addEventListener() {}
+    removeEventListener() {}
+    dispatchEvent() {
+        return true;
+    }
+
+    fail() {
+        this.onerror?.(new Event('error'));
+    }
+
+    emit(message: CompactMessage) {
+        this.onmessage?.({ data: JSON.stringify(message) } as MessageEvent);
+    }
+}
+
+interface Harness {
+    client: VertesiaClient;
+    /** `since` query value of every GET /updates call after the initial history fetch. */
+    pollSince: number[];
+    setHistory: (messages: CompactMessage[]) => void;
+    setPollResponse: (handler: (since: number) => CompactMessage[]) => void;
+    setRunStatus: (status: string) => void;
+    issuedTokens: string[];
+}
+
+function createHarness(): Harness {
+    let history: CompactMessage[] = [];
+    let pollResponse: (since: number) => CompactMessage[] = () => [];
+    let runStatus = 'running';
+    let historyServed = false;
+    const pollSince: number[] = [];
+    const issuedTokens: string[] = [];
+
+    const fetchMock = vi.fn(async (input: Request | string) => {
+        const url = new URL(typeof input === 'string' ? input : input.url);
+        if (url.pathname.endsWith('/updates')) {
+            if (!historyServed) {
+                historyServed = true;
+                return Response.json({ messages: history });
+            }
+            const since = Number(url.searchParams.get('since') ?? 0);
+            pollSince.push(since);
+            return Response.json({ messages: pollResponse(since) });
+        }
+        if (url.pathname.endsWith(`/${AGENT_RUN_ID}`)) {
+            return Response.json({ id: AGENT_RUN_ID, status: runStatus });
+        }
+        return Response.json({ error: 'not found' }, { status: 404 });
+    });
+
+    const client = new VertesiaClient({
+        serverUrl: 'https://studio.example.test',
+        storeUrl: STORE_URL,
+        fetch: fetchMock as unknown as typeof fetch,
+    });
+
+    // Mimics a refreshing credential provider: every call hands out a newer token.
+    client.withAuthCallback(async () => {
+        const token = `token-${issuedTokens.length + 1}`;
+        issuedTokens.push(token);
+        return `Bearer ${token}`;
+    });
+
+    return {
+        client,
+        pollSince,
+        issuedTokens,
+        setHistory: (messages) => {
+            history = messages;
+        },
+        setPollResponse: (handler) => {
+            pollResponse = handler;
+        },
+        setRunStatus: (status) => {
+            runStatus = status;
+        },
+    };
+}
+
+/** Advance fake timers and drain the microtask queue so awaited fetches settle. */
+async function settle(ms = 0) {
+    await vi.advanceTimersByTimeAsync(ms);
+    for (let i = 0; i < 20; i++) {
+        await Promise.resolve();
+    }
+}
+
+/** Longer than the capped backoff delay (30s + jitter). */
+const BACKOFF_CEILING_MS = 40000;
+
+async function failCurrentConnection() {
+    FakeEventSource.instances[FakeEventSource.instances.length - 1].fail();
+    await settle(BACKOFF_CEILING_MS);
+}
+
+describe('AgentsApi.streamMessages reconnection', () => {
+    let logs: string[];
+    let warnings: string[];
+
+    beforeEach(() => {
+        vi.useFakeTimers();
+        FakeEventSource.instances = [];
+        FakeEventSource.urls = [];
+        logs = [];
+        warnings = [];
+        vi.stubGlobal('EventSource', FakeEventSource);
+        vi.spyOn(console, 'log').mockImplementation((...args: unknown[]) => {
+            logs.push(args.map(String).join(' '));
+        });
+        vi.spyOn(console, 'warn').mockImplementation((...args: unknown[]) => {
+            warnings.push(args.map(String).join(' '));
+        });
+        vi.spyOn(console, 'error').mockImplementation(() => {});
+    });
+
+    afterEach(() => {
+        vi.unstubAllGlobals();
+        vi.restoreAllMocks();
+        vi.useRealTimers();
+    });
+
+    it('resolves a fresh auth token for every reconnection attempt', async () => {
+        const harness = createHarness();
+        const abort = new AbortController();
+        void harness.client.agents.streamMessages(AGENT_RUN_ID, undefined, undefined, abort.signal);
+        await settle();
+
+        expect(FakeEventSource.instances).toHaveLength(1);
+        await failCurrentConnection();
+        await failCurrentConnection();
+        expect(FakeEventSource.instances).toHaveLength(3);
+
+        const tokens = FakeEventSource.urls.map((url) => new URL(url).searchParams.get('access_token'));
+        expect(tokens).toHaveLength(3);
+        expect(new Set(tokens).size).toBe(3);
+        expect(tokens.every((token) => token?.startsWith('token-'))).toBe(true);
+
+        abort.abort();
+        await settle();
+    });
+
+    it('never announces an attempt number above the stated maximum', async () => {
+        const harness = createHarness();
+        const abort = new AbortController();
+        void harness.client.agents.streamMessages(AGENT_RUN_ID, undefined, undefined, abort.signal);
+        await settle();
+
+        // 10 reconnects are allowed; the 11th failure must degrade instead of announcing 11/10.
+        for (let i = 0; i < 11; i++) {
+            await failCurrentConnection();
+        }
+
+        const announced = logs
+            .map((line) => /\(attempt (\d+)\/(\d+)\)/.exec(line))
+            .filter((match): match is RegExpExecArray => match !== null)
+            .map((match) => ({ attempt: Number(match[1]), max: Number(match[2]) }));
+
+        expect(announced).toHaveLength(10);
+        expect(announced.map((entry) => entry.attempt)).toEqual([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
+        expect(announced.every((entry) => entry.attempt <= entry.max)).toBe(true);
+        expect(FakeEventSource.instances).toHaveLength(11);
+        expect(warnings.some((line) => line.includes('SSE unavailable after 10 attempts'))).toBe(true);
+
+        abort.abort();
+        await settle();
+    });
+
+    it('polls GET /updates from the last received timestamp and emits the messages', async () => {
+        const harness = createHarness();
+        harness.setHistory([{ t: AgentMessageType.UPDATE, m: 'history', ts: 1000 }]);
+        harness.setPollResponse((since) =>
+            since < 2000 ? [{ t: AgentMessageType.UPDATE, m: 'polled', ts: 2000 }] : [],
+        );
+
+        const received: AgentMessage[] = [];
+        const abort = new AbortController();
+        void harness.client.agents.streamMessages(
+            AGENT_RUN_ID,
+            (message) => received.push(message),
+            undefined,
+            abort.signal,
+        );
+        await settle();
+
+        for (let i = 0; i < 11; i++) {
+            await failCurrentConnection();
+        }
+        await settle(6000);
+
+        // The first poll resumes at the history cursor, later polls at the last polled message.
+        expect(harness.pollSince[0]).toBe(1000);
+        expect(harness.pollSince[1]).toBe(2000);
+        expect(received.map((message) => message.message)).toEqual(['history', 'polled']);
+        // Polled messages reach the caller as fully-formed AgentMessages, like the SSE path.
+        expect(received[1]).toMatchObject({
+            type: AgentMessageType.UPDATE,
+            workflow_run_id: AGENT_RUN_ID,
+            workstream_id: 'main',
+            timestamp: 2000,
+        });
+
+        abort.abort();
+        await settle();
+    });
+
+    it('warns on every polling failure instead of failing silently', async () => {
+        const harness = createHarness();
+        harness.setHistory([{ t: AgentMessageType.UPDATE, m: 'history', ts: 1000 }]);
+        harness.setPollResponse(() => {
+            throw new Error('boom');
+        });
+
+        const abort = new AbortController();
+        void harness.client.agents.streamMessages(AGENT_RUN_ID, undefined, undefined, abort.signal);
+        await settle();
+
+        for (let i = 0; i < 11; i++) {
+            await failCurrentConnection();
+        }
+        await settle(6000);
+
+        const pollWarnings = warnings.filter((line) => line.includes('GET /updates failed while polling'));
+        expect(pollWarnings.length).toBeGreaterThanOrEqual(2);
+        expect(pollWarnings[0]).toContain('consecutive failures: 1');
+        expect(pollWarnings[1]).toContain('consecutive failures: 2');
+
+        abort.abort();
+        await settle();
+    });
+
+    it('retries SSE after the polling fallback so an outage is not permanent', async () => {
+        const harness = createHarness();
+        const abort = new AbortController();
+        void harness.client.agents.streamMessages(AGENT_RUN_ID, undefined, undefined, abort.signal);
+        await settle();
+
+        for (let i = 0; i < 11; i++) {
+            await failCurrentConnection();
+        }
+        const connectionsBeforeRetry = FakeEventSource.instances.length;
+        expect(warnings.some((line) => line.includes('SSE retried every 60s'))).toBe(true);
+
+        await settle(61000);
+
+        expect(FakeEventSource.instances.length).toBe(connectionsBeforeRetry + 1);
+        expect(logs.some((line) => line.includes('retrying the SSE connection'))).toBe(true);
+
+        abort.abort();
+        await settle();
+    });
+
+    it('closes the stream when polling observes a terminal run status', async () => {
+        const harness = createHarness();
+        const abort = new AbortController();
+        const done = harness.client.agents.streamMessages(AGENT_RUN_ID, undefined, undefined, abort.signal);
+        await settle();
+
+        for (let i = 0; i < 11; i++) {
+            await failCurrentConnection();
+        }
+        harness.setRunStatus('completed');
+        await settle(6000);
+
+        await expect(done).resolves.toBeNull();
+    });
+});

package/src/store/AgentsApi.ts

@@ -143,8 +143,8 @@ export class AgentsApi extends ApiTopic {
         }
         if (query?.interaction) params.interaction = query.interaction;
         if (query?.started_by) params.started_by = query.started_by;
-        if (query?.since) params.since = query.since.toISOString();
-        if (query?.until) params.until = query.until.toISOString();
+        if (query?.since) params.since = query.since;
+        if (query?.until) params.until = query.until;
         if (query?.schedule_id) params.schedule_id = query.schedule_id;
         if (query?.type) params.type = query.type;
         if (query?.run_type)
@@ -172,8 +172,8 @@ export class AgentsApi extends ApiTopic {
         if (query?.categories?.length) params.categories = query.categories.join(',');
         if (query?.tags?.length) params.tags = query.tags.join(',');
         if (query?.content_type_name) params.content_type_name = query.content_type_name;
-        if (query?.since) params.since = query.since.toISOString();
-        if (query?.until) params.until = query.until.toISOString();
+        if (query?.since) params.since = query.since;
+        if (query?.until) params.until = query.until;
         if (query?.limit) params.limit = String(query.limit);
         if (query?.offset) params.offset = String(query.offset);
         if (query?.sort?.length) params.sort = query.sort.join(',');
@@ -326,6 +326,10 @@ export class AgentsApi extends ApiTopic {
         let currentSse: EventSource | null = null;
         let interval: ReturnType<typeof setInterval> | null = null;
         let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+        let pollTimer: ReturnType<typeof setTimeout> | null = null;
+        let sseRetryTimer: ReturnType<typeof setTimeout> | null = null;
+        let isPolling = false;
+        let consecutivePollFailures = 0;
         let abortHandler: (() => void) | null = null;
 
         const maxReconnectAttempts = 10;
@@ -338,11 +342,24 @@ export class AgentsApi extends ApiTopic {
             return exponentialDelay + jitter;
         };
 
+        const stopPolling = () => {
+            isPolling = false;
+            if (pollTimer) {
+                clearTimeout(pollTimer);
+                pollTimer = null;
+            }
+            if (sseRetryTimer) {
+                clearTimeout(sseRetryTimer);
+                sseRetryTimer = null;
+            }
+        };
+
         const cleanup = () => {
             if (reconnectTimer) {
                 clearTimeout(reconnectTimer);
                 reconnectTimer = null;
             }
+            stopPolling();
             if (interval) {
                 clearInterval(interval);
                 interval = null;
@@ -372,52 +389,101 @@ export class AgentsApi extends ApiTopic {
         // for any messages we missed and exit cleanly once the run is terminal,
         // even if the terminal message never streamed.
         const POLL_INTERVAL_MS = 5000;
+        // Polling is a degraded mode: retry the real-time channel periodically so a transient
+        // outage (proxy restart, expired credentials that the auth callback later refreshes)
+        // does not permanently downgrade the stream.
+        const SSE_RETRY_INTERVAL_MS = 60000;
         const isTerminalStatus = (status: unknown): boolean =>
             typeof status === 'string' && ['completed', 'failed', 'cancelled'].includes(status);
-        const degradeToPolling = (reason: unknown) => {
-            if (isClosed) return;
-            cleanup();
+
+        // Never swallow a poll failure: while polling, it is the only channel left, so a silent
+        // catch turns a recoverable error (expired token, network blip) into an endless silence.
+        const warnPollFailure = (what: string, error: unknown) => {
+            consecutivePollFailures++;
             console.warn(
-                `Agent stream ${id}: SSE unavailable after ${maxReconnectAttempts} attempts; falling back to /updates polling.`,
-                reason instanceof Error ? reason.message : reason,
+                `Agent stream ${id}: ${what} failed while polling (consecutive failures: ${consecutivePollFailures}); retrying in ${Math.round(POLL_INTERVAL_MS / 1000)}s:`,
+                error instanceof Error ? error.message : error,
             );
-            const tick = async () => {
-                if (isClosed) return;
-                try {
-                    const recent = await this.retrieveMessages(id, lastMessageTimestamp || undefined);
-                    for (const msg of recent) {
-                        if (isClosed) return;
-                        if ((msg.timestamp || 0) <= lastMessageTimestamp) continue;
-                        lastMessageTimestamp = msg.timestamp || lastMessageTimestamp;
-                        if (onMessage) onMessage(msg, exit);
-                        if (isClosed) return;
-                        if (shouldCloseAgentRunStream(msg, id)) {
-                            exit(null);
-                            return;
-                        }
-                    }
-                } catch {
-                    // transient poll error — retry next tick
-                }
-                if (isClosed) return;
-                // Exit even when no terminal message ever streams, by reading the run record.
-                try {
-                    const run = (await this.get(`/${id}`)) as { status?: unknown };
-                    if (isTerminalStatus(run?.status)) {
+        };
+
+        const pollTick = async () => {
+            if (isClosed || !isPolling) return;
+            let polledMessages = false;
+            try {
+                // Resume from the last message we handed to the caller, whether it came from
+                // history, SSE, or an earlier poll. The server returns messages with ts > since.
+                const recent = await this.retrieveMessages(id, lastMessageTimestamp || undefined);
+                polledMessages = true;
+                for (const msg of recent) {
+                    if (isClosed) return;
+                    const timestamp = msg.timestamp || 0;
+                    if (timestamp <= lastMessageTimestamp) continue;
+                    lastMessageTimestamp = timestamp;
+                    if (onMessage) onMessage(msg, exit);
+                    if (isClosed) return;
+                    if (shouldCloseAgentRunStream(msg, id)) {
                         exit(null);
                         return;
                     }
-                } catch {
-                    // ignore — retry next tick
                 }
-                if (!isClosed) {
-                    reconnectTimer = setTimeout(() => {
-                        reconnectTimer = null;
-                        void tick();
-                    }, POLL_INTERVAL_MS);
+            } catch (err) {
+                warnPollFailure('GET /updates', err);
+            }
+            if (isClosed || !isPolling) return;
+            // Exit even when no terminal message ever streams, by reading the run record.
+            try {
+                const run = (await this.get(`/${id}`)) as { status?: unknown };
+                if (isTerminalStatus(run?.status)) {
+                    exit(null);
+                    return;
                 }
-            };
-            void tick();
+                if (polledMessages) consecutivePollFailures = 0;
+            } catch (err) {
+                warnPollFailure('run status check', err);
+            }
+            if (isClosed || !isPolling) return;
+            pollTimer = setTimeout(() => {
+                pollTimer = null;
+                void pollTick();
+            }, POLL_INTERVAL_MS);
+        };
+
+        const retrySseAfterPolling = () => {
+            sseRetryTimer = null;
+            if (isClosed || !isPolling) return;
+            stopPolling();
+            reconnectAttempts = 0;
+            console.log(`Agent stream ${id}: retrying the SSE connection after the polling fallback.`);
+            void setupStream('resume');
+        };
+
+        const degradeToPolling = (reason: unknown) => {
+            if (isClosed || isPolling) return;
+            cleanup();
+            isPolling = true;
+            consecutivePollFailures = 0;
+            console.warn(
+                `Agent stream ${id}: SSE unavailable after ${maxReconnectAttempts} attempts; falling back to GET /updates polling every ${Math.round(POLL_INTERVAL_MS / 1000)}s (SSE retried every ${Math.round(SSE_RETRY_INTERVAL_MS / 1000)}s).`,
+                reason instanceof Error ? reason.message : reason,
+            );
+            sseRetryTimer = setTimeout(retrySseAfterPolling, SSE_RETRY_INTERVAL_MS);
+            void pollTick();
+        };
+
+        // Schedules attempt N of `maxReconnectAttempts`. `reconnectAttempts` holds the number of
+        // the attempt about to run, so the announced counter never exceeds the announced maximum.
+        const scheduleReconnect = (reason: unknown) => {
+            if (isClosed) return;
+            if (reconnectAttempts >= maxReconnectAttempts) {
+                degradeToPolling(reason);
+                return;
+            }
+            const delay = calculateBackoffDelay(reconnectAttempts);
+            reconnectAttempts++;
+            reconnectTimer = setTimeout(() => {
+                reconnectTimer = null;
+                if (!isClosed) void setupStream('reconnect');
+            }, delay);
         };
 
         if (signal) {
@@ -468,7 +534,7 @@ export class AgentsApi extends ApiTopic {
         }
 
         // 2. Connect to SSE for real-time updates
-        const setupStream = async (isReconnect: boolean = false) => {
+        const setupStream = async (mode: 'initial' | 'reconnect' | 'resume' = 'initial') => {
             if (isClosed) return;
             try {
                 const EventSourceImpl = await EventSourceProvider();
@@ -481,6 +547,10 @@ export class AgentsApi extends ApiTopic {
                 }
                 streamUrl.searchParams.set('skipHistory', 'true');
 
+                // Resolve the credential on every attempt (never reuse the one captured when the
+                // stream started): a stream can stay open far longer than the access token TTL,
+                // so a pinned token makes every reconnect fail with 401/403 until the retry
+                // budget is exhausted. The auth callback owns refreshing.
                 const bearerToken = client._auth ? await client._auth() : undefined;
                 if (isClosed) return;
                 if (!bearerToken) {
@@ -493,9 +563,9 @@ export class AgentsApi extends ApiTopic {
                 const token = bearerToken.split(' ')[1];
                 streamUrl.searchParams.set('access_token', token);
 
-                if (isReconnect) {
+                if (mode === 'reconnect') {
                     console.log(
-                        `Reconnecting to agent stream ${id} (attempt ${reconnectAttempts + 1}/${maxReconnectAttempts})`,
+                        `Reconnecting to agent stream ${id} (attempt ${reconnectAttempts}/${maxReconnectAttempts})`,
                     );
                 }
 
@@ -507,7 +577,7 @@ export class AgentsApi extends ApiTopic {
                 let connectionOpenedAt = 0;
 
                 sse.onopen = () => {
-                    if (isReconnect) console.log(`Reconnected to agent stream ${id}`);
+                    if (mode !== 'initial') console.log(`Reconnected to agent stream ${id}`);
                     connectionOpenedAt = Date.now();
                 };
 
@@ -549,35 +619,17 @@ export class AgentsApi extends ApiTopic {
                         reconnectAttempts = 0;
                     }
 
-                    if (reconnectAttempts < maxReconnectAttempts) {
-                        const delay = calculateBackoffDelay(reconnectAttempts);
-                        reconnectAttempts++;
-                        reconnectTimer = setTimeout(() => {
-                            reconnectTimer = null;
-                            if (!isClosed) void setupStream(true);
-                        }, delay);
-                    } else {
-                        degradeToPolling(
-                            new Error(`SSE connection failed after ${maxReconnectAttempts} reconnection attempts`),
-                        );
-                    }
+                    scheduleReconnect(
+                        new Error(`SSE connection failed after ${maxReconnectAttempts} reconnection attempts`),
+                    );
                 };
             } catch (err) {
                 if (isClosed) return;
-                if (reconnectAttempts < maxReconnectAttempts) {
-                    const delay = calculateBackoffDelay(reconnectAttempts);
-                    reconnectAttempts++;
-                    reconnectTimer = setTimeout(() => {
-                        reconnectTimer = null;
-                        if (!isClosed) void setupStream(true);
-                    }, delay);
-                } else {
-                    degradeToPolling(err);
-                }
+                scheduleReconnect(err);
             }
         };
 
-        void setupStream(false);
+        void setupStream('initial');
         return promise;
     }
 

package/src/store/EventsApi.ts

@@ -1,5 +1,7 @@
 import { ApiTopic, type ClientBase } from '@vertesia/api-fetch-client';
 import type {
+    CancelEventDeliveryIntentsPayload,
+    CancelEventDeliveryIntentsResponse,
     EventDeliveryQueueSummaryPayload,
     EventDeliveryQueueSummaryResponse,
     EventDeliveryStreamEnvelope,
@@ -46,6 +48,12 @@ export class EventsApi extends ApiTopic {
         return this.post('/deliveries/queue-summary', { payload });
     }
 
+    cancelQueuedDeliveries(
+        payload: CancelEventDeliveryIntentsPayload = {},
+    ): Promise<CancelEventDeliveryIntentsResponse> {
+        return this.post('/deliveries/cancel', { payload });
+    }
+
     subscribeDeliveries(options: SubscribeEventDeliveriesOptions): ManagedEventSourceConnection {
         const { signal, max_reconnect_attempts, on_snapshot, on_delivery, on_envelope, on_error, on_status, ...query } =
             options;

package/src/store/FilesApi.test.ts

@@ -1,7 +1,12 @@
-import { describe, expect, it } from 'vitest';
+import { afterEach, describe, expect, it, vi } from 'vitest';
 import { ZenoClient } from './client.js';
 
 describe('FilesApi', () => {
+    afterEach(() => {
+        vi.restoreAllMocks();
+        vi.unstubAllGlobals();
+    });
+
     it('retries signed upload URL creation after a transient connection failure', async () => {
         let attempts = 0;
         const fetchSignedUploadUrl = async (): Promise<Response> => {
@@ -66,4 +71,35 @@ describe('FilesApi', () => {
         expect(result).toEqual({ id: 'file-1', path: 'agents/run/conversation.json', url: 'https://signed' });
         expect(attempts).toBe(2);
     });
+
+    it('does not expose a signed URL when a file download returns 404', async () => {
+        const signedUrl =
+            'https://storage.googleapis.com/test-bucket/agents/run/files/missing.png?X-Goog-Credential=secret&X-Goog-Signature=do-not-log';
+        const fetchDownloadUrl = (): Promise<Response> =>
+            Promise.resolve(
+                new Response(JSON.stringify({ url: signedUrl }), {
+                    status: 200,
+                    headers: { 'content-type': 'application/json' },
+                }),
+            );
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response(null, { status: 404, statusText: 'Not Found' })));
+        const consoleError = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+        const client = new ZenoClient({
+            serverUrl: 'https://store.test',
+            apikey: 'token',
+            fetch: fetchDownloadUrl,
+        });
+
+        const error = await client.files.downloadFile('agents/run/files/missing.png').catch((cause: unknown) => cause);
+
+        expect(error).toMatchObject({
+            name: 'FileDownloadError',
+            status: 404,
+            message: 'File download not found: agents/run/files/missing.png',
+        });
+        expect(String(error)).not.toContain('X-Goog-Credential');
+        expect(String(error)).not.toContain('X-Goog-Signature');
+        expect(String(error)).not.toContain('do-not-log');
+        expect(consoleError).not.toHaveBeenCalled();
+    });
 });