@vertesia/client 1.4.0-dev.20260615.051508Z → 1.4.0

package/src/store/WorkflowsApi.ts

@@ -157,8 +157,8 @@ export class WorkflowsApi extends ApiTopic {
         const response = (await this.get(`/runs/${workflowId}/${runId}/updates`, {
             query,
         })) as WorkflowRunUpdatesResponse;
-        // Convert compact messages to AgentMessage for backward compatibility
-        return response.messages.map((m: CompactMessage) => toAgentMessage(m, runId));
+        // Normalize compact and legacy messages to AgentMessage for backward compatibility.
+        return response.messages.map((m) => toAgentMessage(parseMessage(m), runId));
     }
 
     /**
@@ -180,6 +180,7 @@ export class WorkflowsApi extends ApiTopic {
         return new Promise<unknown>((resolve, reject) => {
             let reconnectAttempts = 0;
             let lastMessageTimestamp = since || 0;
+            const historyFetchStartedAt = Date.now();
             let isClosed = false;
             let currentSse: EventSource | null = null;
             let interval: ReturnType<typeof setInterval> | null = null;
@@ -374,19 +375,30 @@ export class WorkflowsApi extends ApiTopic {
                 // 1. Fetch historical messages via GET /updates (gzip-compressed if > 3KB)
                 try {
                     const historical = await this.retrieveMessages(workflowId, runId, since);
-                    for (const msg of historical) {
+                    let shouldCloseAfterHistory = false;
+                    for (let index = 0; index < historical.length; index++) {
+                        const msg = historical[index];
                         lastMessageTimestamp = Math.max(lastMessageTimestamp, msg.timestamp || 0);
                         if (onMessage) {
                             onMessage(msg, exit);
                         }
-                        if (shouldCloseAgentRunStream(msg, runId)) {
-                            exit(null);
-                            return;
-                        }
+                        shouldCloseAfterHistory =
+                            index === historical.length - 1 && shouldCloseAgentRunStream(msg, runId);
+                    }
+                    if (shouldCloseAfterHistory) {
+                        exit(null);
+                        return;
                     }
                 } catch (err) {
                     console.warn('Failed to fetch historical messages, continuing with SSE:', err);
                 }
+                if (!isClosed && lastMessageTimestamp <= 0) {
+                    // The server only replays the GET-to-SSE handoff gap when
+                    // `since > 0`. New runs can have no history at the first
+                    // fetch, so use the GET start time as the cursor to avoid
+                    // dropping messages emitted before the SSE subscription is active.
+                    lastMessageTimestamp = Math.max(1, historyFetchStartedAt - 1);
+                }
 
                 // 2. Connect to SSE
                 void setupStream(false);

package/src/store/client.ts

@@ -22,7 +22,6 @@ import { QueryApi } from './QueryApi.js';
 import { RenderingApi } from './RenderingApi.js';
 import { SchedulesApi } from './SchedulesApi.js';
 import { TaskApi } from './TaskApi.js';
-import { ToolsApi } from './ToolsApi.js';
 import { TypesApi } from './TypesApi.js';
 import { VERSION, VERSION_HEADER } from './version.js';
 import { WorkflowsApi } from './WorkflowsApi.js';
@@ -34,6 +33,7 @@ export interface ZenoClientProps {
     onRequest?: (request: Request) => void;
     onResponse?: (response: Response) => void;
     retryPolicy?: IRequestRetryPolicy;
+    timeout?: number | false | null;
     fetch?: FETCH_FN | Promise<FETCH_FN>;
 }
 
@@ -53,6 +53,9 @@ export class ZenoClient extends AbstractFetchClient<ZenoClient> {
         if (opts.retryPolicy) {
             this.withRetryPolicy(opts.retryPolicy);
         }
+        if (opts.timeout !== undefined) {
+            this.withTimeout(opts.timeout);
+        }
         this.onRequest = opts.onRequest;
         this.onResponse = opts.onResponse;
         this.errorFactory = (err: RequestError) => {
@@ -104,7 +107,6 @@ export class ZenoClient extends AbstractFetchClient<ZenoClient> {
     email = new EmailApi(this);
     pendingAsks = new PendingAsksApi(this);
     data = new DataApi(this);
-    tools = new ToolsApi(this);
     indexing = new IndexingApi(this);
     query = new QueryApi(this);
     hiveMemory = new HiveMemoryApi(this);

package/src/store/stream-gap.test.ts

@@ -0,0 +1,230 @@
+import { type AgentMessage, AgentMessageType } from '@vertesia/common';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { VertesiaClient } from '../client.js';
+
+class FakeEventSource {
+    static readonly CONNECTING = 0;
+    static readonly OPEN = 1;
+    static readonly CLOSED = 2;
+
+    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);
+    }
+
+    close() {
+        this.readyState = FakeEventSource.CLOSED;
+    }
+
+    addEventListener() {}
+
+    removeEventListener() {}
+
+    dispatchEvent() {
+        return true;
+    }
+}
+
+function createClient(): VertesiaClient {
+    const client = new VertesiaClient({
+        serverUrl: 'https://studio.example.test',
+        storeUrl: 'https://store.example.test',
+    });
+    client.withAuthCallback(async () => 'Bearer test-token');
+    return client;
+}
+
+function message(timestamp: number): AgentMessage {
+    return {
+        type: AgentMessageType.THOUGHT,
+        timestamp,
+        workflow_run_id: 'run-1',
+        message: 'historical',
+        workstream_id: 'main',
+    };
+}
+
+function mockApiGet<T extends object>(api: T, response: unknown) {
+    return vi
+        .spyOn(api as unknown as { get: (path: string, options?: unknown) => Promise<unknown> }, 'get')
+        .mockResolvedValue(response);
+}
+
+describe('streamMessages GET-to-SSE handoff', () => {
+    beforeEach(() => {
+        FakeEventSource.urls = [];
+        vi.stubGlobal('EventSource', FakeEventSource);
+    });
+
+    afterEach(() => {
+        vi.unstubAllGlobals();
+        vi.restoreAllMocks();
+    });
+
+    it('uses a positive SSE since cursor for an agent run with empty initial history', async () => {
+        const client = createClient();
+        vi.spyOn(client.agents, 'retrieveMessages').mockResolvedValue([]);
+        const abort = new AbortController();
+
+        const stream = client.agents.streamMessages('agent-run-1', undefined, undefined, abort.signal);
+
+        await vi.waitFor(() => expect(FakeEventSource.urls).toHaveLength(1));
+
+        const streamUrl = new URL(FakeEventSource.urls[0]);
+        expect(streamUrl.searchParams.get('skipHistory')).toBe('true');
+        expect(Number(streamUrl.searchParams.get('since'))).toBeGreaterThan(0);
+
+        abort.abort();
+        await stream;
+    });
+
+    it('keeps the latest historical timestamp as the SSE since cursor for an agent run', async () => {
+        const client = createClient();
+        vi.spyOn(client.agents, 'retrieveMessages').mockResolvedValue([message(1_234)]);
+        const abort = new AbortController();
+
+        const stream = client.agents.streamMessages('agent-run-1', undefined, undefined, abort.signal);
+
+        await vi.waitFor(() => expect(FakeEventSource.urls).toHaveLength(1));
+
+        const streamUrl = new URL(FakeEventSource.urls[0]);
+        expect(streamUrl.searchParams.get('since')).toBe('1234');
+
+        abort.abort();
+        await stream;
+    });
+
+    it('delivers full agent history before closing on a terminal historical message', async () => {
+        const client = createClient();
+        const complete = {
+            ...message(1_000),
+            type: AgentMessageType.COMPLETE,
+            message: 'previous turn complete',
+        };
+        const latest = {
+            ...message(2_000),
+            message: 'newer historical message',
+        };
+        vi.spyOn(client.agents, 'retrieveMessages').mockResolvedValue([complete, latest]);
+        const delivered: AgentMessage[] = [];
+        const abort = new AbortController();
+
+        const stream = client.agents.streamMessages(
+            'agent-run-1',
+            (msg) => {
+                delivered.push(msg);
+            },
+            undefined,
+            abort.signal,
+        );
+
+        await vi.waitFor(() => expect(FakeEventSource.urls).toHaveLength(1));
+
+        expect(delivered.map((msg) => msg.message)).toEqual(['previous turn complete', 'newer historical message']);
+        expect(new URL(FakeEventSource.urls[0]).searchParams.get('since')).toBe('2000');
+
+        abort.abort();
+        await stream;
+    });
+
+    it('normalizes legacy agent history messages before returning them to the UI', async () => {
+        const client = createClient();
+        mockApiGet(client.agents, {
+            messages: [
+                {
+                    type: 8,
+                    timestamp: 1_000,
+                    workflow_run_id: 'legacy-run',
+                    message: 'What are the news headlines in France today?',
+                    workstream_id: 'main',
+                    details: { event_class: 'user_content' },
+                },
+                {
+                    type: 7,
+                    timestamp: 2_000,
+                    workflow_run_id: 'legacy-run',
+                    message: 'Here are the headlines.',
+                    workstream_id: 'main',
+                    details: { streamed: true },
+                },
+            ],
+        });
+
+        const messages = await client.agents.retrieveMessages('agent-run-1');
+
+        expect(messages).toEqual([
+            expect.objectContaining({
+                type: AgentMessageType.QUESTION,
+                timestamp: 1_000,
+                workflow_run_id: 'agent-run-1',
+                message: 'What are the news headlines in France today?',
+                details: { event_class: 'user_content' },
+            }),
+            expect.objectContaining({
+                type: AgentMessageType.ANSWER,
+                timestamp: 2_000,
+                workflow_run_id: 'agent-run-1',
+                message: 'Here are the headlines.',
+                details: { streamed: true },
+            }),
+        ]);
+    });
+
+    it('normalizes legacy workflow history messages before returning them to the UI', async () => {
+        const client = createClient();
+        mockApiGet(client.workflows, {
+            messages: [
+                {
+                    type: 'answer',
+                    timestamp: 3_000,
+                    workflow_run_id: 'legacy-run',
+                    message: 'Workflow answer',
+                    workstream_id: 'main',
+                },
+            ],
+        });
+
+        const messages = await client.workflows.retrieveMessages('workflow-1', 'workflow-run-1');
+
+        expect(messages).toEqual([
+            expect.objectContaining({
+                type: AgentMessageType.ANSWER,
+                timestamp: 3_000,
+                workflow_run_id: 'workflow-run-1',
+                message: 'Workflow answer',
+            }),
+        ]);
+    });
+
+    it('uses a positive SSE since cursor for a workflow run with empty initial history', async () => {
+        const client = createClient();
+        vi.spyOn(client.workflows, 'retrieveMessages').mockResolvedValue([]);
+        const abort = new AbortController();
+
+        const stream = client.workflows.streamMessages(
+            'workflow-1',
+            'workflow-run-1',
+            undefined,
+            undefined,
+            abort.signal,
+        );
+
+        await vi.waitFor(() => expect(FakeEventSource.urls).toHaveLength(1));
+
+        const streamUrl = new URL(FakeEventSource.urls[0]);
+        expect(streamUrl.searchParams.get('skipHistory')).toBe('true');
+        expect(Number(streamUrl.searchParams.get('since'))).toBeGreaterThan(0);
+
+        abort.abort();
+        await stream;
+    });
+});

package/lib/store/ToolsApi.d.ts

@@ -1,14 +0,0 @@
-import { ApiTopic, type ClientBase } from '@vertesia/api-fetch-client';
-import type { BuiltinToolsCatalogResponse } from '@vertesia/common';
-/**
- * API for accessing the builtin tools catalog
- */
-export declare class ToolsApi extends ApiTopic {
-    constructor(parent: ClientBase);
-    /**
-     * Get the builtin tools catalog
-     * @returns List of all available builtin tools with their descriptions and parameter schemas
-     */
-    getBuiltinCatalog(): Promise<BuiltinToolsCatalogResponse>;
-}
-//# sourceMappingURL=ToolsApi.d.ts.map

package/lib/store/ToolsApi.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"ToolsApi.d.ts","sourceRoot":"","sources":["../../src/store/ToolsApi.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,KAAK,UAAU,EAAE,MAAM,4BAA4B,CAAC;AACvE,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,kBAAkB,CAAC;AAEpE;;GAEG;AACH,qBAAa,QAAS,SAAQ,QAAQ;gBACtB,MAAM,EAAE,UAAU;IAI9B;;;OAGG;IACH,iBAAiB,IAAI,OAAO,CAAC,2BAA2B,CAAC;CAG5D"}

package/lib/store/ToolsApi.js

@@ -1,17 +0,0 @@
-import { ApiTopic } from '@vertesia/api-fetch-client';
-/**
- * API for accessing the builtin tools catalog
- */
-export class ToolsApi extends ApiTopic {
-    constructor(parent) {
-        super(parent, '/api/v1/tools');
-    }
-    /**
-     * Get the builtin tools catalog
-     * @returns List of all available builtin tools with their descriptions and parameter schemas
-     */
-    getBuiltinCatalog() {
-        return this.get('/');
-    }
-}
-//# sourceMappingURL=ToolsApi.js.map

package/lib/store/ToolsApi.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"ToolsApi.js","sourceRoot":"","sources":["../../src/store/ToolsApi.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAmB,MAAM,4BAA4B,CAAC;AAGvE;;GAEG;AACH,MAAM,OAAO,QAAS,SAAQ,QAAQ;IAClC,YAAY,MAAkB;QAC1B,KAAK,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IACnC,CAAC;IAED;;;OAGG;IACH,iBAAiB;QACb,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACzB,CAAC;CACJ"}

package/src/store/ToolsApi.ts

@@ -1,19 +0,0 @@
-import { ApiTopic, type ClientBase } from '@vertesia/api-fetch-client';
-import type { BuiltinToolsCatalogResponse } from '@vertesia/common';
-
-/**
- * API for accessing the builtin tools catalog
- */
-export class ToolsApi extends ApiTopic {
-    constructor(parent: ClientBase) {
-        super(parent, '/api/v1/tools');
-    }
-
-    /**
-     * Get the builtin tools catalog
-     * @returns List of all available builtin tools with their descriptions and parameter schemas
-     */
-    getBuiltinCatalog(): Promise<BuiltinToolsCatalogResponse> {
-        return this.get('/');
-    }
-}