@vertesia/client 1.5.0-dev.20260910.052912Z → 1.6.0-dev.20260912.110338Z

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vertesia/client",
-  "version": "1.5.0-dev.20260910.052912Z",
+  "version": "1.6.0-dev.20260912.110338Z",
   "type": "module",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -12,16 +12,16 @@
   "license": "Apache-2.0",
   "devDependencies": {
     "@types/node": "^24.13.3",
-    "rolldown": "1.2.4",
+    "@vertesia/tsconfig": "0.1.0",
+    "rolldown": "1.2.6",
     "typescript": "7.0.2",
-    "vitest": "^4.1.10",
-    "@vertesia/tsconfig": "0.1.0"
+    "vitest": "^4.1.11"
   },
   "dependencies": {
-    "eventsource": "^5.0.0",
-    "@vertesia/api-fetch-client": "1.5.0-dev.20260910.052912Z",
-    "@vertesia/common": "1.5.0-dev.20260910.052912Z",
-    "@llumiverse/common": "1.5.0-dev.20260910.044936Z"
+    "@llumiverse/common": "1.6.0-dev.20260912.104205Z",
+    "@vertesia/api-fetch-client": "1.6.0-dev.20260912.110338Z",
+    "@vertesia/common": "1.6.0-dev.20260912.110338Z",
+    "eventsource": "^5.1.1"
   },
   "exports": {
     ".": {
@@ -48,7 +48,7 @@
     "ai",
     "typescript"
   ],
-  "gitHead": "95d481ca856012cd67b501b901dc365afeb7cf81",
+  "gitHead": "504e8df031c3950ec324c865385caf460b1c1cd7",
   "scripts": {
     "lint": "biome lint src",
     "clean:lib": "rimraf ./lib ./tsconfig.tsbuildinfo",

package/src/DelegationGrantsApi.ts

@@ -0,0 +1,22 @@
+import { ApiTopic, type ClientBase } from '@vertesia/api-fetch-client';
+import type { CreateDelegationGrantPayload, DelegationGrant } from '@vertesia/common';
+export default class DelegationGrantsApi extends ApiTopic {
+    constructor(parent: ClientBase) {
+        super(parent, '/api/v1/iam/delegation-grants');
+    }
+    create(payload: CreateDelegationGrantPayload): Promise<DelegationGrant> {
+        return this.post('/', { payload });
+    }
+    list(): Promise<DelegationGrant[]> {
+        return this.get('/');
+    }
+    mine(): Promise<DelegationGrant[]> {
+        return this.get('/me');
+    }
+    retrieve(id: string): Promise<DelegationGrant> {
+        return this.get(`/${id}`);
+    }
+    revoke(id: string): Promise<DelegationGrant> {
+        return this.post(`/${id}/revoke`);
+    }
+}

package/src/InteractionsApi.ts

@@ -227,12 +227,14 @@ export default class InteractionsApi extends ApiTopic {
         nameWithTag: string,
         payload: InteractionExecutionPayload = {},
         onChunk?: (chunk: string) => void,
+        requestOptions?: IRequestParams,
     ): Promise<EnhancedInteractionExecutionResult<ResultT, ParamsT>> {
         const r = await executeInteractionByName<ParamsT>(
             this.client as VertesiaClient,
             nameWithTag,
             payload,
             onChunk,
+            requestOptions,
         ).catch((err) => {
             if (err instanceof ServerError && hasIdPayload(err.payload)) {
                 throw err.updateDetails({ run_id: err.payload.id });

package/src/RunsApi.test.ts

@@ -0,0 +1,24 @@
+import type { ToolResultsPayload, UserMessagePayload } from '@vertesia/common';
+import { describe, expect, it, vi } from 'vitest';
+import { VertesiaClient } from './client.js';
+
+describe('RunsApi resume request options', () => {
+    it('sends private headers on tool-result and user-message resumes', async () => {
+        const requests: Request[] = [];
+        const client = new VertesiaClient({
+            serverUrl: 'https://studio.example.com',
+            storeUrl: 'https://zeno.example.com',
+            fetch: vi.fn(async () => Response.json({ result: [], prompt: [] })),
+            onRequest: (request) => requests.push(request),
+        });
+        const options = { headers: { 'x-vertesia-required-tool-name': 'write_artifact' } };
+
+        await client.runs.sendToolResults({} as ToolResultsPayload, options);
+        await client.runs.sendUserMessage({} as UserMessagePayload, options);
+
+        expect(requests.map((request) => request.headers.get('x-vertesia-required-tool-name'))).toEqual([
+            'write_artifact',
+            'write_artifact',
+        ]);
+    });
+});

package/src/RunsApi.ts

@@ -1,5 +1,5 @@
 import type { ExecutionResponse } from '@llumiverse/common';
-import { ApiTopic, type ClientBase } from '@vertesia/api-fetch-client';
+import { ApiTopic, type ClientBase, type IRequestParams } from '@vertesia/api-fetch-client';
 import type {
     ComputeRunFacetPayload,
     ComputeRunFacetsResponse,
@@ -34,6 +34,8 @@ export interface FilterOption {
 
 export type { ComputeRunFacetsResponse } from '@vertesia/common';
 
+type ResumeRequestOptions = Pick<IRequestParams, 'headers' | 'signal' | 'timeoutMs'>;
+
 export class RunsApi extends ApiTopic {
     constructor(parent: ClientBase) {
         super(parent, '/api/v1/runs');
@@ -116,12 +118,10 @@ export class RunsApi extends ApiTopic {
      * @param payload
      * @returns
      */
-    sendToolResults(
-        payload: ToolResultsPayload,
-        options?: { timeoutMs?: number | false | null; signal?: AbortSignal },
-    ): Promise<ExecutionResponse> {
+    sendToolResults(payload: ToolResultsPayload, options?: ResumeRequestOptions): Promise<ExecutionResponse> {
         return this.post(`/tool-results`, {
             payload,
+            headers: options?.headers,
             timeoutMs: options?.timeoutMs,
             signal: options?.signal,
         });
@@ -132,12 +132,10 @@ export class RunsApi extends ApiTopic {
      * @param payload
      * @returns
      */
-    sendUserMessage(
-        payload: UserMessagePayload,
-        options?: { timeoutMs?: number | false | null; signal?: AbortSignal },
-    ): Promise<ExecutionResponse> {
+    sendUserMessage(payload: UserMessagePayload, options?: ResumeRequestOptions): Promise<ExecutionResponse> {
         return this.post(`/user-message`, {
             payload,
+            headers: options?.headers,
             timeoutMs: options?.timeoutMs,
             signal: options?.signal,
         });

package/src/client.ts

@@ -7,6 +7,7 @@ import { ApiKeysApi } from './ApiKeysApi.js';
 import AppsApi from './AppsApi.js';
 import AuditTrailApi from './AuditTrailApi.js';
 import CommandsApi from './CommandsApi.js';
+import DelegationGrantsApi from './DelegationGrantsApi.js';
 import EnvironmentsApi from './EnvironmentsApi.js';
 import { IamApi } from './IamApi.js';
 import InteractionsApi from './InteractionsApi.js';
@@ -450,6 +451,7 @@ export class VertesiaClient extends AbstractFetchClient<VertesiaClient> {
     analytics = new AnalyticsApi(this);
     auditTrail = new AuditTrailApi(this);
     training = new TrainingApi(this);
+    delegationGrants = new DelegationGrantsApi(this);
     users = new UsersApi(this);
     iam = new IamApi(this);
     refs = new RefsApi(this);

package/src/execute.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { VertesiaClient } from './client.js';
+import { executeInteractionByName } from './execute.js';
+
+describe('executeInteractionByName', () => {
+    it('forwards private per-request headers without placing them in the execution payload', async () => {
+        const post = vi.fn().mockResolvedValue({ id: 'run-1', status: 'completed' });
+        const client = { post } as unknown as VertesiaClient;
+
+        await executeInteractionByName(client, 'sys:test', { data: { message: 'hello' } }, undefined, {
+            headers: { 'x-vertesia-required-tool-name': 'app_workspace_init' },
+        });
+
+        expect(post).toHaveBeenCalledWith(
+            '/api/v1/execute',
+            expect.objectContaining({
+                headers: { 'x-vertesia-required-tool-name': 'app_workspace_init' },
+                payload: expect.not.objectContaining({ required_tool_name: expect.anything() }),
+            }),
+        );
+    });
+});

package/src/execute.ts

@@ -1,3 +1,4 @@
+import type { IRequestParams } from '@vertesia/api-fetch-client';
 import {
     type AsyncExecutionPayload,
     type AsyncExecutionResult,
@@ -87,16 +88,18 @@ export async function executeInteractionByName<P = unknown>(
     interaction: string,
     payload: InteractionExecutionPayload = {},
     onChunk?: (chunk: string) => void,
+    requestOptions?: IRequestParams,
 ): Promise<InteractionExecutionResult<P>> {
     const stream = !!onChunk;
     const response = await client.post<InteractionExecutionResult<P>>('/api/v1/execute', {
+        ...requestOptions,
         payload: {
             ...payload,
             interaction,
             stream,
         } as NamedInteractionExecutionPayload,
         // Synchronous interaction execution blocks on the model; keep a long client timeout.
-        timeoutMs: stream ? undefined : INTERACTION_EXECUTION_TIMEOUT_MS,
+        timeoutMs: requestOptions?.timeoutMs ?? (stream ? undefined : INTERACTION_EXECUTION_TIMEOUT_MS),
     });
     if (stream) {
         if (response.status === ExecutionRunStatus.failed) {

package/src/index.ts

@@ -3,6 +3,7 @@ import type { AsyncExecutionResult } from '@vertesia/common';
 export type { EnableEnvironmentModelPayload, OrphanedAppInstallation } from '@vertesia/common';
 export { getOAuthPermissionScopes, Permission } from '@vertesia/common';
 export * from './client.js';
+export { default as DelegationGrantsApi } from './DelegationGrantsApi.js';
 export type { GroupsQueryOptions } from './GroupsApi.js';
 export * from './InteractionBase.js';
 export * from './InteractionOutput.js';

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

@@ -0,0 +1,29 @@
+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.ts

@@ -7,6 +7,8 @@ import {
     type AgentMessage,
     type AgentRun,
     type AgentRunDetailsStreamEvent,
+    type AgentRunFeedbackPayload,
+    type AgentRunFeedbackResponse,
     type AgentRunInternals,
     type AgentRunResponse,
     type AgentRunUpdatesResponse,
@@ -165,9 +167,25 @@ export class AgentsApi extends ApiTopic {
         if (query?.cursor) params.cursor = query.cursor;
         if (query?.sort) params.sort = query.sort;
         if (query?.order) params.order = query.order;
+        if (query?.evaluation_severity?.length) params.evaluation_severity = query.evaluation_severity.join(',');
+        if (query?.evaluation_flag?.length) params.evaluation_flag = query.evaluation_flag.join(',');
+        if (query?.feedback_rating) params.feedback_rating = query.feedback_rating;
+        if (query?.contradicted !== undefined) params.contradicted = String(query.contradicted);
         return params;
     }
 
+    /**
+     * Rate an agent run: thumbs up or down, with an optional reason code and comment.
+     *
+     * `feedback_id` is the client's idempotency key: a retried request with the same id is a no-op.
+     * `status: 'replaced'` means an earlier rating by the same user on the same scope was
+     * superseded; `disabled` means this deployment does not record feedback. All answer 200 because
+     * a rating is never the user's error.
+     */
+    recordFeedback(id: string, payload: AgentRunFeedbackPayload): Promise<AgentRunFeedbackResponse> {
+        return this.post(`/${id}/feedback`, { payload });
+    }
+
     /**
      * Search agent runs via Elasticsearch (full-text + filters).
      */
@@ -666,11 +684,13 @@ export class AgentsApi extends ApiTopic {
         options?: {
             includeHistory?: boolean;
             hydratePayloads?: boolean;
+            from?: string;
         },
     ): Promise<WorkflowRunWithDetails> {
         const query: Record<string, string> = {};
         if (options?.includeHistory) query.include_history = 'true';
         if (options?.hydratePayloads) query.hydrate_payloads = 'true';
+        if (options?.from !== undefined) query.from = options.from;
         return this.get(`/${id}/details`, { query });
     }
 
@@ -777,11 +797,12 @@ export class AgentsApi extends ApiTopic {
     getChildDetails(
         id: string,
         childWorkflowId: string,
-        options?: { includeHistory?: boolean; hydratePayloads?: boolean },
+        options?: { includeHistory?: boolean; hydratePayloads?: boolean; from?: string },
     ): Promise<WorkflowRunWithDetails> {
         const query: Record<string, string> = {};
         if (options?.includeHistory) query.include_history = 'true';
         if (options?.hydratePayloads) query.hydrate_payloads = 'true';
+        if (options?.from !== undefined) query.from = options.from;
         return this.get(`/${id}/children/${childWorkflowId}/details`, { query });
     }
 

package/src/store/ObjectsApi.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it, vi } from 'vitest';
+import { ZenoClient } from './client.js';
+
+describe('ObjectsApi revision labels', () => {
+    it.each(['v1.2', 'Review — 日本語', 'Révision – café', '100% complete & reviewed + approved'])(
+        'preserves the revision label %s through the query contract',
+        async (revisionLabel) => {
+            const requests: Request[] = [];
+            const client = new ZenoClient({
+                serverUrl: 'https://api.example.com',
+                fetch: vi.fn(async () => Response.json({ id: 'document-id' })),
+                onRequest: (request) => requests.push(request),
+            });
+
+            await client.objects.update(
+                'document-id',
+                { name: 'Updated document' },
+                {
+                    createRevision: true,
+                    revisionLabel,
+                    ifMatch: 'previous-etag',
+                },
+            );
+
+            expect(requests).toHaveLength(1);
+            const request = requests[0];
+            expect(request.method).toBe('PUT');
+            expect(new URL(request.url).searchParams.get('revision_label')).toBe(revisionLabel);
+            expect(request.headers.has('x-revision-label')).toBe(false);
+            expect(request.headers.get('x-create-revision')).toBe('true');
+            expect(request.headers.get('if-match')).toBe('previous-etag');
+            expect(await request.clone().json()).toEqual({ name: 'Updated document' });
+        },
+    );
+
+    it('does not send a label when updating in place', async () => {
+        const requests: Request[] = [];
+        const client = new ZenoClient({
+            serverUrl: 'https://api.example.com',
+            fetch: vi.fn(async () => Response.json({ id: 'document-id' })),
+            onRequest: (request) => requests.push(request),
+        });
+
+        await client.objects.update('document-id', {}, { revisionLabel: 'Unused — label' });
+
+        expect(new URL(requests[0].url).searchParams.has('revision_label')).toBe(false);
+        expect(requests[0].headers.has('x-create-revision')).toBe(false);
+        expect(requests[0].headers.has('x-revision-label')).toBe(false);
+    });
+});

package/src/store/ObjectsApi.ts

@@ -437,9 +437,6 @@ export class ObjectsApi extends ApiTopic {
         }
         if (options?.createRevision) {
             headers[ContentObjectApiHeaders.CREATE_REVISION] = 'true';
-            if (options.revisionLabel) {
-                headers[ContentObjectApiHeaders.REVISION_LABEL] = options.revisionLabel;
-            }
         }
         if (options?.suppressWorkflows) {
             headers[ContentObjectApiHeaders.SUPPRESS_WORKFLOWS] = 'true';
@@ -447,6 +444,11 @@ export class ObjectsApi extends ApiTopic {
 
         return this.put(`/${id}`, {
             payload: updatePayload,
+            // The existing query contract preserves Unicode labels; HTTP headers only accept ByteString values.
+            query:
+                options?.createRevision && options.revisionLabel
+                    ? { revision_label: options.revisionLabel }
+                    : undefined,
             headers,
         });
     }

package/src/store/SchedulesApi.ts

@@ -8,9 +8,9 @@ import type {
 } from '@vertesia/common';
 
 /**
- * Client API for managing agent schedules.
+ * Client API for managing recurring schedules.
  *
- * Schedules allow agents to run on a recurring basis using cron expressions.
+ * Schedules allow agents or processes to run on a recurring basis using cron expressions.
  */
 export class SchedulesApi extends ApiTopic {
     constructor(parent: ClientBase) {
@@ -35,7 +35,7 @@ export class SchedulesApi extends ApiTopic {
     /**
      * Create a new schedule.
      *
-     * @param payload - Schedule configuration including name, interaction, and cron expression
+     * @param payload - Agent or process schedule configuration
      * @returns The created schedule
      *
      * @example
@@ -48,6 +48,18 @@ export class SchedulesApi extends ApiTopic {
      *   vars: { reportType: 'summary' }
      * });
      * ```
+     *
+     * @example
+     * ```typescript
+     * const schedule = await client.schedules.create({
+     *   name: 'Nightly Refresh',
+     *   target: 'process',
+     *   process: '68c01a23456789abcdef0123',
+     *   cron_expression: '0 2 * * *',
+     *   timezone: 'UTC',
+     *   context: { collection: 'reports' }
+     * });
+     * ```
      */
     create(payload: CreateSchedulePayload): Promise<AgentSchedule> {
         return this.post('/', { payload });
@@ -77,9 +89,9 @@ export class SchedulesApi extends ApiTopic {
     }
 
     /**
-     * Trigger an immediate execution of the scheduled agent.
+     * Trigger an immediate execution of the scheduled workflow.
      *
-     * This runs the agent immediately without waiting for the next scheduled time.
+     * This runs the agent or process immediately without waiting for the next scheduled time.
      *
      * @param id - Schedule ID
      * @returns Success message

package/src/store/signed-url.test.ts

@@ -173,10 +173,32 @@ describe('fetchSignedUrl', () => {
 
     it('honors a numeric Retry-After header when scheduling the retry', async () => {
         fetchMock
-            .mockResolvedValueOnce(response(503, 'slow down', { 'retry-after': '2' }))
+            .mockResolvedValueOnce(response(503, 'slow down', { 'retry-after': '30' }))
             .mockResolvedValueOnce(response(200, 'ok'));
-        const res = await runAllTimers(fetchSignedUrl('https://storage/x'));
+        const pending = fetchSignedUrl('https://storage/x');
+        await vi.advanceTimersByTimeAsync(29999);
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+        await vi.advanceTimersByTimeAsync(1);
+        const res = await pending;
         expect(res.status).toBe(200);
         expect(fetchMock).toHaveBeenCalledTimes(2);
     });
 });
+
+describe('Retry-After request budget', () => {
+    it.each(['3600', '2147484', '1e308', new Date(Date.now() + 3600000).toUTCString()])(
+        'returns the intact response without an early retry for %s',
+        async (retryAfter) => {
+            const res = new Response('retry later', { status: 503, headers: { 'Retry-After': retryAfter } });
+            const fetch = vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(res);
+            try {
+                const result = await fetchSignedUrl('https://storage/x');
+                expect(result).toBe(res);
+                expect(await result.text()).toBe('retry later');
+                expect(fetch).toHaveBeenCalledTimes(1);
+            } finally {
+                fetch.mockRestore();
+            }
+        },
+    );
+});

package/src/store/signed-url.ts

@@ -20,6 +20,7 @@ const DEFAULT_RETRYABLE_STATUSES: ReadonlySet<number> = new Set([429, 500, 502,
 const DEFAULT_ATTEMPTS = 4;
 const DEFAULT_BASE_DELAY_MS = 500;
 const DEFAULT_MAX_DELAY_MS = 8_000;
+const MAX_RETRY_AFTER_MS = 60_000;
 
 export interface SignedUrlFetchOptions {
     method?: string;
@@ -29,7 +30,7 @@ export interface SignedUrlFetchOptions {
     attempts?: number;
     /** Base delay for exponential backoff, in milliseconds. Defaults to 500. */
     baseDelayMs?: number;
-    /** Upper bound for a single backoff delay, in milliseconds. Defaults to 8000. */
+    /** Upper bound for exponential backoff, in milliseconds. Defaults to 8000. Retry-After takes precedence. */
     maxDelayMs?: number;
     /** HTTP statuses to retry on. Defaults to 429, 500, 502, 503, 504. */
     retryableStatuses?: ReadonlySet<number>;
@@ -58,7 +59,7 @@ function retryAfterMs(res: Response): number | undefined {
 function backoffMs(attempt: number, baseDelayMs: number, maxDelayMs: number, res?: Response): number {
     const retryAfter = res ? retryAfterMs(res) : undefined;
     if (retryAfter !== undefined) {
-        return Math.min(maxDelayMs, retryAfter);
+        return retryAfter;
     }
     // Exponential backoff with full jitter.
     const capped = Math.min(maxDelayMs, baseDelayMs * 2 ** attempt);
@@ -141,7 +142,8 @@ async function toReplayableBody(body: BodyInit | null | undefined): Promise<Body
 /**
  * `fetch()` a cloud-storage signed URL, retrying transient failures (connection
  * errors and retryable HTTP statuses) with exponential backoff. Honors a
- * `Retry-After` response header when present.
+ * `Retry-After` response header up to 60 seconds. Longer delays return the response
+ * without retrying so the caller can schedule recovery outside this request.
  *
  * The returned `Response` is only guaranteed to be retried while it carries a
  * retryable status; a non-retryable error response (e.g. 403, 404) is returned
@@ -167,6 +169,9 @@ export async function fetchSignedUrl(url: string, options: SignedUrlFetchOptions
             if (res.ok || !retryableStatuses.has(res.status) || isLastAttempt) {
                 return res;
             }
+            // Do not retry earlier than requested or park the caller beyond the retry budget.
+            // Returning the response also avoids overflowing JavaScript's timer range.
+            if ((retryAfterMs(res) ?? 0) > MAX_RETRY_AFTER_MS) return res;
             // Retryable status: drain the body so the connection can be reused, then back off.
             await res.body?.cancel().catch(() => undefined);
             await sleep(backoffMs(attempt, baseDelayMs, maxDelayMs, res));