@vertesia/client 1.5.0-dev.20260807.073259Z → 1.5.0-dev.20260901.005903Z

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

@@ -151,6 +151,62 @@ describe('AgentsApi.streamMessages reconnection', () => {
         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();

package/src/store/AgentsApi.ts

@@ -58,6 +58,8 @@ import { fetchSignedUrl } from './signed-url.js';
 import { shouldCloseAgentRunStream, shouldCloseCompactRunStream } from './stream-termination.js';
 
 export interface AgentRunStreamMessagesOptions {
+    /** Resolve the stream when the root conversation becomes idle. Headless followers should opt in. */
+    closeOnIdle?: boolean;
     onHistoryLoaded?: (messages: AgentMessage[]) => void;
     onHistoryError?: (error: unknown) => void;
 }
@@ -253,7 +255,8 @@ export class AgentsApi extends ApiTopic {
 
     /**
      * Send a signal to a running agent.
-     * Signals: "UserInput", "Stop", "FileUploaded", "FileRemoved"
+     * Signals include "UserInput", "Stop", "ModelConfigChanged", "FileUploaded", "FileRemoved", and
+     * "FileBatchClosed".
      */
     sendSignal(id: string, signalName: string, payload?: SignalAgentPayload): Promise<SignalAgentResponse> {
         return this.post(`/${id}/signal/${signalName}`, { payload });
@@ -421,7 +424,7 @@ export class AgentsApi extends ApiTopic {
                     lastMessageTimestamp = timestamp;
                     if (onMessage) onMessage(msg, exit);
                     if (isClosed) return;
-                    if (shouldCloseAgentRunStream(msg, id)) {
+                    if (shouldCloseAgentRunStream(msg, id, options?.closeOnIdle)) {
                         exit(null);
                         return;
                     }
@@ -512,7 +515,8 @@ export class AgentsApi extends ApiTopic {
                     if (onMessage) onMessage(msg, exit);
                     if (isClosed) break;
 
-                    shouldCloseAfterHistory = index === historical.length - 1 && shouldCloseAgentRunStream(msg, id);
+                    shouldCloseAfterHistory =
+                        index === historical.length - 1 && shouldCloseAgentRunStream(msg, id, options?.closeOnIdle);
                 }
                 if (shouldCloseAfterHistory) {
                     exit(null);
@@ -598,7 +602,7 @@ export class AgentsApi extends ApiTopic {
                             onMessage(agentMessage, exit);
                         }
 
-                        if (shouldCloseCompactRunStream(compactMessage, id)) {
+                        if (shouldCloseCompactRunStream(compactMessage, id, options?.closeOnIdle)) {
                             exit(null);
                         }
                     } catch (err) {

package/src/store/CollectionsApi.ts

@@ -10,7 +10,9 @@ import type {
     ContentObjectStatus,
     CreateCollectionPayload,
     DynamicCollection,
+    FullObjectSearchResponse,
     ObjectSearchResponse,
+    UpdateCollectionPayload,
 } from '@vertesia/common';
 
 export class CollectionsApi extends ApiTopic {
@@ -53,7 +55,7 @@ export class CollectionsApi extends ApiTopic {
         });
     }
 
-    update(collectionId: string, payload: Partial<CreateCollectionPayload>): Promise<{ id: string }> {
+    update(collectionId: string, payload: UpdateCollectionPayload): Promise<{ id: string }> {
         return this.put(`/${collectionId}`, {
             payload,
         });
@@ -90,6 +92,11 @@ export class CollectionsApi extends ApiTopic {
         });
     }
 
+    searchMembers(
+        collectionId: string,
+        payload: ComplexSearchPayload & { select?: undefined },
+    ): Promise<FullObjectSearchResponse>;
+    searchMembers(collectionId: string, payload: ComplexSearchPayload): Promise<ObjectSearchResponse>;
     searchMembers(collectionId: string, payload: ComplexSearchPayload): Promise<ObjectSearchResponse> {
         return this.post(`/${collectionId}/search`, { payload });
     }

package/src/store/EmailApi.ts

@@ -1,109 +1,27 @@
 import { ApiTopic, type ClientBase } from '@vertesia/api-fetch-client';
-import type { EmailRouteData } from '@vertesia/common';
+import type {
+    CreateEmailRouteRequest,
+    CreateEmailRouteResponse,
+    EmailRouteData,
+    EmailRouteResponse,
+    ForwardEmailRequest,
+    ForwardEmailResponse,
+    SendEmailRequest,
+    SendEmailResponse,
+    UpdateEmailRouteRequest,
+    UpdateEmailRouteResponse,
+} from '@vertesia/common';
 
-/**
- * Request payload for sending an email via the agent.
- * Resend configuration is fetched from project settings.
- * From address is constructed as: {project_namespace}+{agent_name}@{email_domain}
- */
-export interface SendEmailRequest {
-    /** Email address to send to */
-    to_email: string;
-    /** Email subject */
-    subject: string;
-    /** Email body in markdown format */
-    body: string;
-    /** Agent/interaction endpoint name (used in from address) */
-    agent_name: string;
-    /** Display name for the sender (overrides project default) */
-    from_name?: string;
-    /** Workflow run ID for routing replies */
-    run_id: string;
-    /** Existing route key (for subsequent emails in same conversation) */
-    route_key?: string;
-    /** Message ID for In-Reply-To header (email threading) */
-    in_reply_to?: string;
-    /** Chain of message IDs for References header */
-    references?: string[];
-}
-
-/**
- * Response from sending an email.
- */
-export interface SendEmailResponse {
-    success: boolean;
-    /** Resend email ID */
-    email_id?: string;
-    /** Message-ID header for threading */
-    message_id?: string;
-    /** Short route key for reply routing */
-    route_key?: string;
-    /** Error message if failed */
-    error?: string;
-}
-
-/**
- * Response from creating an email route.
- */
-export interface CreateRouteResponse {
-    /** The generated route key (8-char alphanumeric) */
-    route_key: string;
-    /** Full reply-to address: r+{route_key}@{email_domain} */
-    reply_to: string;
-    /** The email domain for sending and receiving */
-    email_domain: string;
-}
-
-/**
- * Request to forward an email to a workflow.
- * Used by external services that handle email reception themselves.
- */
-export interface ForwardEmailRequest {
-    /** Email content received by the external service */
-    email: {
-        /** Sender email address */
-        from: string;
-        /** Email subject */
-        subject?: string;
-        /** Plain text body */
-        text: string;
-        /** HTML body (optional) */
-        html?: string;
-        /** Message-ID header for threading */
-        message_id?: string;
-    };
-    /** Custom context data from the external service (e.g., auth tokens, user IDs) */
-    context?: Record<string, unknown>;
-    /** Attachments with download URLs */
-    attachments?: Array<{
-        filename: string;
-        content_type: string;
-        size: number;
-        download_url: string;
-    }>;
-}
-
-/**
- * Response from forwarding an email.
- */
-export interface ForwardEmailResponse {
-    success: boolean;
-    run_id: string;
-    workflow_id: string;
-    route_key: string;
-}
-
-/**
- * Request to create an email route.
- */
-export interface CreateRouteRequest {
-    /** Workflow run ID for routing replies */
-    run_id: string;
-    /** Email address of the user (for context) */
-    user_email: string;
-    /** Subject of the email thread (optional) */
-    thread_subject?: string;
-}
+export type {
+    ForwardEmailRequest,
+    ForwardEmailResponse,
+    SendEmailRequest,
+    SendEmailResponse,
+} from '@vertesia/common';
+/** @deprecated Use CreateEmailRouteRequest from @vertesia/common. */
+export type CreateRouteRequest = CreateEmailRouteRequest;
+/** @deprecated Use CreateEmailRouteResponse from @vertesia/common. */
+export type CreateRouteResponse = CreateEmailRouteResponse;
 
 /**
  * Email API for sending emails from workflows.
@@ -150,21 +68,21 @@ export class EmailApi extends ApiTopic {
      * // Replies will be routed back to the workflow
      * ```
      */
-    createRoute(request: CreateRouteRequest): Promise<CreateRouteResponse> {
+    createRoute(request: CreateEmailRouteRequest): Promise<CreateEmailRouteResponse> {
         return this.post('/routes', { payload: request });
     }
 
     /**
      * Get an email route by key.
      */
-    getRoute(routeKey: string): Promise<EmailRouteData & { route_key: string }> {
+    getRoute(routeKey: string): Promise<EmailRouteResponse> {
         return this.get(`/routes/${routeKey}`);
     }
 
     /**
      * Update an email route (e.g., to update threading info).
      */
-    updateRoute(routeKey: string, updates: Partial<EmailRouteData>): Promise<{ success: boolean; route_key: string }> {
+    updateRoute(routeKey: string, updates: UpdateEmailRouteRequest): Promise<UpdateEmailRouteResponse> {
         return this.put(`/routes/${routeKey}`, { payload: updates });
     }
 

package/src/store/FilesApi.ts

@@ -1,9 +1,12 @@
 import { ApiTopic, type ClientBase, type IRequestRetryPolicy } from '@vertesia/api-fetch-client';
 import type {
+    BucketCreateAccessStatusResponse,
     BucketReadAccessStatusResponse,
     BulkUploadUrlsPayload,
     BulkUploadUrlsResponse,
     DeleteFileResult,
+    EnsureBucketCreateAccessPayload,
+    EnsureBucketCreateAccessResponse,
     EnsureBucketReadAccessPayload,
     EnsureBucketReadAccessResponse,
     FileBucketResponse,
@@ -133,6 +136,15 @@ export class FilesApi extends ApiTopic {
         return this.get('/bucket/read-access', { query: { principal } });
     }
 
+    ensureBucketCreateAccess(principal: string): Promise<EnsureBucketCreateAccessResponse> {
+        const payload: EnsureBucketCreateAccessPayload = { principal };
+        return this.post('/bucket/create-access', { payload });
+    }
+
+    getBucketCreateAccessStatus(principal: string): Promise<BucketCreateAccessStatusResponse> {
+        return this.get('/bucket/create-access', { query: { principal } });
+    }
+
     list(prefix: string): Promise<FileListResponse> {
         return this.get('/list', { query: { prefix } });
     }

package/src/store/ObjectsApi.ts

@@ -26,6 +26,7 @@ import {
     type ExportPropertiesPayload,
     type ExportPropertiesResponse,
     type FindPayload,
+    type FullObjectSearchResponse,
     type GetFileUrlPayload,
     type GetFileUrlResponse,
     type GetRenditionParams,
@@ -36,10 +37,12 @@ import {
     type ObjectSearchPayload,
     type ObjectSearchQuery,
     type ObjectSearchResponse,
+    type ProjectedContentObjectApiResponse,
     type SetObjectEmbeddingsResponse,
     type StartContentObjectExportRequest,
     type StartContentObjectExportResponse,
     type SupportedEmbeddingTypes,
+    type UpdateContentObjectPayload,
     type ZenoBulkContentObjectExportComposeRequest,
     type ZenoBulkContentObjectExportPlanRequest,
     type ZenoBulkContentObjectExportPlanResponse,
@@ -60,10 +63,22 @@ import type { ZenoClient } from './client.js';
 import { fetchSignedUrl } from './signed-url.js';
 import { getUploadMimeTypeHint, resolveUploadMimeType } from './uploadMimeType.js';
 
+/**
+ * The two write payloads, each widened at `content` so callers can hand us a browser `File` or a
+ * `StreamSource` and let the method upload it before sending the wire shape.
+ *
+ * They are separate on purpose: `POST /objects` and `PUT /objects/:id` publish distinct components,
+ * so deriving the update signature from the create payload would silently drift the day the two
+ * schemas diverge.
+ */
 type ContentObjectWritePayload = Omit<CreateContentObjectPayload, 'content'> & {
     content?: ContentSource | File | StreamSource;
 };
 
+type ContentObjectUpdateWritePayload = Omit<UpdateContentObjectPayload, 'content'> & {
+    content?: ContentSource | File | StreamSource;
+};
+
 export class ObjectsApi extends ApiTopic {
     declare client: ZenoClient;
 
@@ -224,7 +239,11 @@ export class ObjectsApi extends ApiTopic {
     }
 
     /** Find object based on query */
-    find(payload: FindPayload): Promise<ContentObject[]> {
+    find(payload: FindPayload & { select?: undefined }): Promise<ContentObject[]>;
+    find(payload: FindPayload & { select: `+${string}` }): Promise<ContentObject[]>;
+    find(payload: FindPayload & { select: string }): Promise<ProjectedContentObjectApiResponse[]>;
+    find(payload: FindPayload): Promise<ContentObject[] | ProjectedContentObjectApiResponse[]>;
+    find(payload: FindPayload): Promise<ContentObject[] | ProjectedContentObjectApiResponse[]> {
         return this.post('/find', {
             payload,
         });
@@ -238,13 +257,18 @@ export class ObjectsApi extends ApiTopic {
     }
 
     /** Search object — different from find because allow full text search */
+    search(payload: ComplexSearchPayload & { select?: undefined }): Promise<FullObjectSearchResponse>;
+    search(payload: ComplexSearchPayload): Promise<ObjectSearchResponse>;
     search(payload: ComplexSearchPayload): Promise<ObjectSearchResponse> {
         return this.post('/search', {
             payload,
         });
     }
 
-    retrieve(id: string, select?: string): Promise<ContentObject> {
+    retrieve(id: string): Promise<ContentObject>;
+    retrieve(id: string, select: `+${string}` | undefined): Promise<ContentObject>;
+    retrieve(id: string, select: string): Promise<ProjectedContentObjectApiResponse>;
+    retrieve(id: string, select?: string): Promise<ContentObject | ProjectedContentObjectApiResponse> {
         return this.get(`/${id}`, {
             query: {
                 select,
@@ -381,7 +405,7 @@ export class ObjectsApi extends ApiTopic {
      */
     async update(
         id: string,
-        payload: Partial<ContentObjectWritePayload>,
+        payload: ContentObjectUpdateWritePayload,
         options?: {
             createRevision?: boolean;
             revisionLabel?: string;
@@ -393,7 +417,7 @@ export class ObjectsApi extends ApiTopic {
         },
     ): Promise<ContentObject> {
         const { content, ...payloadWithoutContent } = payload;
-        const updatePayload: Partial<CreateContentObjectPayload> = {
+        const updatePayload: UpdateContentObjectPayload = {
             ...payloadWithoutContent,
         };
 

package/src/store/PendingAsksApi.ts

@@ -1,61 +1,19 @@
 import { ApiTopic, type ClientBase } from '@vertesia/api-fetch-client';
-import type { ListPendingAsksResponse, PendingAskData, TaskField, UserChannel } from '@vertesia/common';
-
-/**
- * Request to register a pending ask.
- */
-export interface RegisterPendingAskRequest {
-    /** Temporal workflow run ID */
-    runId: string;
-    /** Temporal workflow ID */
-    workflowId: string;
-    /** Name of the agent/interaction */
-    agentName: string;
-    /** Questions asked by the agent */
-    questions: string[];
-    /** Timeout in hours (default 48) */
-    timeoutHours?: number;
-    /** User communication channels */
-    userChannels: UserChannel[];
-    /** Durable task fields shown in task inbox */
-    taskFields?: TaskField[];
-}
-
-/**
- * Response from registering a pending ask.
- */
-export interface RegisterPendingAskResponse {
-    /** Whether registration succeeded */
-    success: boolean;
-    /** Generated ask ID */
-    askId?: string;
-    /** Whether webhook was sent */
-    webhookSent?: boolean;
-    /** Error message if failed */
-    error?: string;
-}
-
-/**
- * Request to resolve a pending ask.
- */
-export interface ResolvePendingAskRequest {
-    /** User's response */
-    response: string;
-}
-
-/**
- * Response from resolving a pending ask.
- */
-export interface ResolvePendingAskResponse {
-    /** Whether resolution succeeded */
-    success: boolean;
-    /** Whether webhook was sent */
-    webhookSent?: boolean;
-    /** How long the user took to respond (ms) */
-    waitDurationMs?: number;
-    /** Error message if failed */
-    error?: string;
-}
+import type {
+    ListPendingAsksResponse,
+    PendingAskData,
+    RegisterPendingAskRequest,
+    RegisterPendingAskResponse,
+    ResolvePendingAskRequest,
+    ResolvePendingAskResponse,
+} from '@vertesia/common';
+
+export type {
+    RegisterPendingAskRequest,
+    RegisterPendingAskResponse,
+    ResolvePendingAskRequest,
+    ResolvePendingAskResponse,
+} from '@vertesia/common';
 
 /**
  * Pending Asks API for tracking ask_user requests.

package/src/store/ProcessApi.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it, vi } from 'vitest';
+import { ZenoClient } from './client.js';
+
+function createClient(requests: Request[]) {
+    return new ZenoClient({
+        serverUrl: 'https://zeno.example.com',
+        fetch: vi.fn(async () => Response.json([])),
+        onRequest: (request) => requests.push(request),
+    });
+}
+
+describe('ProcessApi.list', () => {
+    it.each([
+        ['canonical', { all_versions: true }],
+        ['deprecated', { allVersions: true }],
+    ])('maps the %s all-versions option to the wire query', async (_name, query) => {
+        const requests: Request[] = [];
+        const client = createClient(requests);
+
+        await client.processes.list(query);
+
+        expect(requests[0]?.url).toBe('https://zeno.example.com/api/v1/processes?all_versions=true');
+    });
+});

package/src/store/ProcessApi.ts

@@ -1,20 +1,23 @@
 import { ApiTopic, type ClientBase } from '@vertesia/api-fetch-client';
 import type {
     CreateProcessDefinitionPayload,
+    CreateProcessTestSuitePayload,
+    ListProcessDefinitionsQuery as ListProcessDefinitionsWireQuery,
+    ListProcessTestRunsQuery,
     ProcessDefinition,
+    ProcessTestRun,
+    ProcessTestSuite,
     PublishProcessDefinitionPayload,
     RevertProcessDefinitionPayload,
+    StartProcessTestRunPayload,
     UpdateProcessDefinitionPayload,
+    UpdateProcessTestSuitePayload,
 } from '@vertesia/common';
 
-export interface ListProcessDefinitionsQuery {
-    status?: string;
-    process?: string;
-    limit?: number;
-    offset?: number;
-    /** Include every revision/version instead of only the latest head revision. */
+export type ListProcessDefinitionsQuery = ListProcessDefinitionsWireQuery & {
+    /** @deprecated Use the wire-compatible `all_versions` property. */
     allVersions?: boolean;
-}
+};
 
 export class ProcessApi extends ApiTopic {
     constructor(parent: ClientBase) {
@@ -27,7 +30,7 @@ export class ProcessApi extends ApiTopic {
         if (query?.process) params.process = query.process;
         if (query?.limit != null) params.limit = String(query.limit);
         if (query?.offset != null) params.offset = String(query.offset);
-        if (query?.allVersions) params.all_versions = 'true';
+        if (query?.all_versions || query?.allVersions) params.all_versions = 'true';
         return this.get('/', { query: params });
     }
 
@@ -58,4 +61,42 @@ export class ProcessApi extends ApiTopic {
     delete(id: string): Promise<{ id: string; count: number }> {
         return this.del(`/${id}`);
     }
+
+    listTestSuites(processId: string): Promise<ProcessTestSuite[]> {
+        return this.get(`/${processId}/test-suites`);
+    }
+
+    createTestSuite(processId: string, payload: CreateProcessTestSuitePayload): Promise<ProcessTestSuite> {
+        return this.post(`/${processId}/test-suites`, { payload });
+    }
+
+    updateTestSuite(
+        processId: string,
+        suiteId: string,
+        payload: UpdateProcessTestSuitePayload,
+    ): Promise<ProcessTestSuite> {
+        return this.put(`/${processId}/test-suites/${suiteId}`, { payload });
+    }
+
+    deleteTestSuite(processId: string, suiteId: string): Promise<{ id: string; count: number }> {
+        return this.del(`/${processId}/test-suites/${suiteId}`);
+    }
+
+    startTestRun(processId: string, payload: StartProcessTestRunPayload): Promise<ProcessTestRun> {
+        return this.post(`/${processId}/test-runs`, { payload });
+    }
+
+    listTestRuns(processId: string, query?: ListProcessTestRunsQuery): Promise<ProcessTestRun[]> {
+        return this.get(`/${processId}/test-runs`, {
+            query: query?.limit == null ? undefined : { limit: String(query.limit) },
+        });
+    }
+
+    retrieveTestRun(processId: string, runId: string): Promise<ProcessTestRun> {
+        return this.get(`/${processId}/test-runs/${runId}`);
+    }
+
+    cancelTestRun(processId: string, runId: string): Promise<ProcessTestRun> {
+        return this.post(`/${processId}/test-runs/${runId}/cancel`, {});
+    }
 }

package/src/store/ProcessTestRunApi.ts

@@ -0,0 +1,41 @@
+import { ApiTopic, type ClientBase } from '@vertesia/api-fetch-client';
+import type { ProcessTestRun, SubmitProcessTestRunPayload } from '@vertesia/common';
+
+/**
+ * Run-scoped process test operations.
+ *
+ * Test runs are addressed by their own id here, so these methods work for every run whatever it
+ * was started against — a stored process test suite, an in-code `app:`/`sys:` process, or an
+ * ephemeral definition submitted inline.
+ */
+export class ProcessTestRunApi extends ApiTopic {
+    constructor(parent: ClientBase) {
+        super(parent, '/api/v1/process-test-runs');
+    }
+
+    /**
+     * Start a test run against an in-code process or an inline definition, with the scenarios
+     * supplied in the request instead of a stored suite. Use
+     * `client.store.processes.startTestRun()` for stored process definitions and their suites.
+     */
+    submit(payload: SubmitProcessTestRunPayload): Promise<ProcessTestRun> {
+        // Starting a run is not idempotent and the contract carries no request key, so a replay
+        // would create a second run. Opt out of any client-level retry policy explicitly rather
+        // than relying on POST being absent from its method list. Rate-limiter pacing retries are
+        // unaffected: those happen before the request reaches the handler.
+        return this.post('/', { payload, retryPolicy: false });
+    }
+
+    retrieve(runId: string): Promise<ProcessTestRun> {
+        return this.get(`/${runId}`);
+    }
+
+    cancel(runId: string): Promise<ProcessTestRun> {
+        return this.post(`/${runId}/cancel`, {});
+    }
+
+    /** Deletes a run and its snapshot, cancelling it first when it is still active. */
+    delete(runId: string): Promise<{ id: string; count: number }> {
+        return this.del(`/${runId}`);
+    }
+}