@vertesia/client 1.6.0-dev.20260923.085325Z → 1.6.0-dev.20261008.064737Z

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

@@ -1,119 +0,0 @@
-import { afterEach, describe, expect, it, vi } from 'vitest';
-import { escapeArtifactPathDelimiters } from './AgentsApi.js';
-import { ZenoClient } from './client.js';
-
-const SERVER_URL = 'https://store.test';
-const RUN_ID = 'run-1';
-
-/**
- * A client whose injected fetch records the URL of every request it is handed. The URL is read off
- * the Request object, so the assertions see the path after WHATWG URL parsing — which is where an
- * unescaped `#` was being dropped.
- */
-function clientRecordingUrls(body: unknown = { url: 'https://signed', path: 'p' }) {
-    const urls: string[] = [];
-    const client = new ZenoClient({
-        serverUrl: SERVER_URL,
-        apikey: 'token',
-        fetch: async (input: RequestInfo) => {
-            urls.push(input instanceof Request ? input.url : String(input));
-            return new Response(JSON.stringify(body), {
-                status: 200,
-                headers: { 'content-type': 'application/json' },
-            });
-        },
-    });
-    return { client, urls };
-}
-
-/** The artifact path the server reconstructs: the URL path after the route prefix, decoded per segment. */
-function serverPath(url: string, prefix: string): string {
-    const tail = new URL(url).pathname.split(`/${prefix}/`)[1] ?? '';
-    return tail.split('/').map(decodeURIComponent).join('/');
-}
-
-describe('escapeArtifactPathDelimiters', () => {
-    it('escapes the two characters that truncate a path', () => {
-        expect(escapeArtifactPathDelimiters('files/tpl (YYYY-0#).docx')).toBe('files/tpl (YYYY-0%23).docx');
-        expect(escapeArtifactPathDelimiters('files/report?v2.docx')).toBe('files/report%3Fv2.docx');
-    });
-
-    // Scope guard. Anything this helper touches changes the bytes on the wire for filenames that
-    // work today, so it must leave everything except `#` and `?` exactly as it found it.
-    it.each([
-        ['percent', 'files/100% done.docx'],
-        ['spaces', 'files/MHA - Client IQ FSD.docx'],
-        ['non-ascii and accents', 'files/café résumé.docx'],
-        ['backslash', 'files/back\\slash.docx'],
-        ['segment separators', 'files/nested/a b.txt'],
-        ['already-encoded sequence', 'files/report%23.md'],
-    ])('leaves %s untouched', (_label, path) => {
-        expect(escapeArtifactPathDelimiters(path)).toBe(path);
-    });
-});
-
-describe('AgentsApi artifact paths', () => {
-    afterEach(() => {
-        vi.restoreAllMocks();
-        vi.unstubAllGlobals();
-    });
-
-    // A `#` in an uploaded filename used to be parsed as the URL fragment, so the server saw a
-    // truncated path and stored the object under a key nothing could read back.
-    it('uploadArtifact preserves a path containing #', async () => {
-        vi.stubGlobal(
-            'fetch',
-            vi.fn(async () => new Response(null, { status: 200 })),
-        );
-        const { client, urls } = clientRecordingUrls();
-        const path = 'files/Design Template (YYYY-0#).docx';
-
-        await client.agents.uploadArtifact(RUN_ID, path, 'content');
-
-        expect(urls).toHaveLength(1);
-        expect(urls[0]).not.toContain('#');
-        expect(serverPath(urls[0], 'artifacts')).toBe(path);
-    });
-
-    // The query is concatenated onto the path, so an unescaped delimiter took it down too.
-    it.each([
-        ['hash', 'files/Design (YYYY-0#).docx'],
-        ['question mark', 'files/report?v2.docx'],
-    ])('getArtifactUrl round-trips %s and keeps the query intact', async (_label, path) => {
-        const { client, urls } = clientRecordingUrls();
-
-        await client.agents.getArtifactUrl(RUN_ID, path, 'attachment', 'download-name.docx');
-
-        const url = new URL(urls[0]);
-        expect(serverPath(urls[0], 'artifacts')).toBe(path);
-        expect(url.hash).toBe('');
-        expect(url.searchParams.get('url')).toBe('1');
-        expect(url.searchParams.get('disposition')).toBe('attachment');
-        expect(url.searchParams.get('filename')).toBe('download-name.docx');
-    });
-
-    // Pins the scope boundary: `%` must go on the wire exactly as it does with no escaping at all.
-    it('sends a path containing % exactly as it did before, unescaped', async () => {
-        const { client, urls } = clientRecordingUrls();
-        const path = 'files/100% done.docx';
-
-        await client.agents.getArtifactUrl(RUN_ID, path);
-
-        const unescaped = new URL(`${SERVER_URL}/api/v1/agents/${RUN_ID}/artifacts/${path}?url=1`);
-        expect(new URL(urls[0]).pathname).toBe(unescaped.pathname);
-        expect(new URL(urls[0]).pathname).toContain('100%%20done.docx');
-    });
-
-    it('getArtifactContent and updateArtifactContent preserve a path containing #', async () => {
-        const { client, urls } = clientRecordingUrls({ content: '', generation: '1' });
-        const path = 'files/notes (v0#1).md';
-
-        await client.agents.getArtifactContent(RUN_ID, path);
-        await client.agents.updateArtifactContent(RUN_ID, path, { content: 'x', generation: '1' });
-
-        expect(urls).toHaveLength(2);
-        for (const url of urls) {
-            expect(serverPath(url, 'artifact-content')).toBe(path);
-        }
-    });
-});

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

@@ -1,29 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { VertesiaClient } from '../client.js';
-
-describe('agent history cursor transport', () => {
-    it('passes the cursor and response metadata through for main and child details', async () => {
-        const urls: URL[] = [];
-        const response = { history: { type: 'agent', mode: 'delta', next_from: 'next', agentTasks: [] } };
-        const client = new VertesiaClient({
-            serverUrl: 'https://studio.test',
-            storeUrl: 'https://store.test',
-            fetch: (async (input: Request | string) => {
-                urls.push(new URL(typeof input === 'string' ? input : input.url));
-                return Response.json(response);
-            }) as typeof fetch,
-        });
-        const options = { includeHistory: true, hydratePayloads: true, from: 'opaque/+=' };
-        expect(await client.agents.getRunDetails('agent', options)).toEqual(response);
-        expect(await client.agents.getChildDetails('agent', 'child', options)).toEqual(response);
-        expect(urls.map((url) => url.pathname)).toEqual([
-            '/api/v1/agents/agent/details',
-            '/api/v1/agents/agent/children/child/details',
-        ]);
-        for (const url of urls) {
-            expect(url.searchParams.get('from')).toBe(options.from);
-            expect(url.searchParams.get('include_history')).toBe('true');
-            expect(url.searchParams.get('hydrate_payloads')).toBe('true');
-        }
-    });
-});

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

@@ -1,386 +0,0 @@
-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);
-            try {
-                return Response.json({ messages: pollResponse(since) });
-            } catch (err) {
-                // A thrown error carrying `status` models an HTTP error response (e.g. 404).
-                const status = (err as { status?: unknown }).status;
-                if (typeof status === 'number') {
-                    return Response.json({ error: (err as Error).message }, { status });
-                }
-                throw err;
-            }
-        }
-        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('keeps interactive streams open on root IDLE by default', async () => {
-        const harness = createHarness();
-        const settled = vi.fn();
-        const received: AgentMessage[] = [];
-        const done = harness.client.agents
-            .streamMessages(AGENT_RUN_ID, (message) => received.push(message))
-            .then(settled);
-        await settle();
-
-        FakeEventSource.instances[0].emit({
-            t: AgentMessageType.IDLE,
-            m: 'Waiting for your command...',
-            w: 'main',
-            ts: 1_000,
-        });
-        await settle();
-        expect(settled).not.toHaveBeenCalled();
-
-        FakeEventSource.instances[0].emit({
-            t: AgentMessageType.ANSWER,
-            m: 'Follow-up response',
-            w: 'main',
-            ts: 1_500,
-        });
-        await settle();
-        expect(received.map((message) => message.message)).toEqual([
-            'Waiting for your command...',
-            'Follow-up response',
-        ]);
-
-        FakeEventSource.instances[0].emit({
-            t: AgentMessageType.COMPLETE,
-            m: 'Conversation complete',
-            w: 'main',
-            ts: 2_000,
-        });
-        await expect(done).resolves.toBeUndefined();
-    });
-
-    it('lets headless followers opt into closing on root IDLE', async () => {
-        const harness = createHarness();
-        const done = harness.client.agents.streamMessages(AGENT_RUN_ID, undefined, undefined, undefined, {
-            closeOnIdle: true,
-        });
-        await settle();
-
-        FakeEventSource.instances[0].emit({
-            t: AgentMessageType.IDLE,
-            m: 'Waiting for your command...',
-            w: 'main',
-            ts: 1_000,
-        });
-
-        await expect(done).resolves.toBeNull();
-    });
-
-    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('stops the polling fallback when the run no longer exists (404)', async () => {
-        const harness = createHarness();
-        harness.setHistory([{ t: AgentMessageType.UPDATE, m: 'history', ts: 1000 }]);
-        harness.setPollResponse(() => {
-            throw Object.assign(new Error('Not Found: Agent run not found'), { status: 404 });
-        });
-
-        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();
-        }
-        await settle(6000);
-
-        await expect(done).resolves.toBeNull();
-        expect(warnings.some((line) => line.includes('the run no longer exists (404)'))).toBe(true);
-        // A single 404 ends the loop: no retry warning, no further poll after the exit.
-        expect(warnings.filter((line) => line.includes('GET /updates failed while polling'))).toEqual([]);
-        expect(harness.pollSince).toHaveLength(1);
-    });
-
-    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/DataApi.test.ts

@@ -1,42 +0,0 @@
-import type { ImportDataPayload } from '@vertesia/common';
-import { describe, expect, it } from 'vitest';
-import { ZenoClient } from './client.js';
-
-describe('DataApi', () => {
-    // `import` is the name applications built against the 1.4 SDK call, through the client the
-    // platform serves them rather than one they bundle -- so renaming it (as 1.5 briefly did, to
-    // `importData`) breaks them at deploy time rather than at their next upgrade. This pins both
-    // the name and the request it issues.
-    it('exposes `import` as POST {store}/import with the data store header', async () => {
-        const requests: { url: string; method: string; storeHeader: string | null; body: string }[] = [];
-        const fetchImport = async (input: RequestInfo | URL, init?: RequestInit): Promise<Response> => {
-            const request = new Request(input, init);
-            requests.push({
-                url: request.url,
-                method: request.method,
-                storeHeader: request.headers.get('x-data-store-id'),
-                body: await request.text(),
-            });
-            return new Response(JSON.stringify({ id: 'import-1', status: 'completed' }), {
-                status: 200,
-                headers: { 'content-type': 'application/json' },
-            });
-        };
-
-        const client = new ZenoClient({ serverUrl: 'https://store.test', apikey: 'token', fetch: fetchImport });
-        const payload: ImportDataPayload = {
-            mode: 'append',
-            message: 'test import',
-            tables: { customers: { source: 'inline', data: [{ id: 1 }] } },
-        };
-
-        const job = await client.data.import('store-1', payload);
-
-        expect(job).toEqual({ id: 'import-1', status: 'completed' });
-        expect(requests).toHaveLength(1);
-        expect(requests[0].method).toBe('POST');
-        expect(requests[0].url).toBe('https://store.test/api/v1/data/store-1/import');
-        expect(requests[0].storeHeader).toBe('store-1');
-        expect(JSON.parse(requests[0].body)).toEqual(payload);
-    });
-});

package/src/store/EmbeddingsApi.test.ts

@@ -1,31 +0,0 @@
-import { SupportedEmbeddingTypes } from '@vertesia/common';
-import { describe, expect, it, vi } from 'vitest';
-import { ZenoClient } from './client.js';
-
-describe('EmbeddingsApi', () => {
-    it('omits the mode by default and sends the explicit sync override when requested', async () => {
-        const requests: Request[] = [];
-        const client = new ZenoClient({
-            serverUrl: 'https://store.example.com',
-            apikey: 'token',
-            fetch: vi.fn(
-                async () =>
-                    new Response(JSON.stringify({ status: 'success', message: 'started' }), {
-                        status: 200,
-                        headers: { 'content-type': 'application/json' },
-                    }),
-            ),
-            onRequest: (request) => requests.push(request),
-        });
-
-        await client.embeddings.recalculate(SupportedEmbeddingTypes.text);
-        await client.embeddings.recalculate(SupportedEmbeddingTypes.text, { mode: 'sync' });
-        await client.embeddings.recalculate(SupportedEmbeddingTypes.image, { force: true });
-
-        expect(requests.map(({ url }) => url)).toEqual([
-            'https://store.example.com/api/v1/embeddings/text/recalculate',
-            'https://store.example.com/api/v1/embeddings/text/recalculate?mode=sync',
-            'https://store.example.com/api/v1/embeddings/image/recalculate?force=true',
-        ]);
-    });
-});