@vertesia/client 1.5.0 → 1.6.0-dev.20260918.061604Z

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vertesia/client",
-  "version": "1.5.0",
+  "version": "1.6.0-dev.20260918.061604Z",
   "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.8",
     "typescript": "7.0.2",
-    "vitest": "^4.1.10",
-    "@vertesia/tsconfig": "0.1.0"
+    "vitest": "5.0.0"
   },
   "dependencies": {
-    "eventsource": "^5.0.0",
-    "@llumiverse/common": "1.5.0",
-    "@vertesia/api-fetch-client": "1.5.0",
-    "@vertesia/common": "1.5.0"
+    "@llumiverse/common": "1.6.0-dev.20260918.055633Z",
+    "@vertesia/api-fetch-client": "1.6.0-dev.20260918.061604Z",
+    "@vertesia/common": "1.6.0-dev.20260918.061604Z",
+    "eventsource": "^5.1.1"
   },
   "exports": {
     ".": {
@@ -48,7 +48,7 @@
     "ai",
     "typescript"
   ],
-  "gitHead": "3485742020066ab1fd3292487cf3a9577b5e4d91",
+  "gitHead": "ea552337206e77c256478b76e19b4235e70bf769",
   "scripts": {
     "lint": "biome lint src",
     "clean:lib": "rimraf ./lib ./tsconfig.tsbuildinfo",

package/src/AccountApi.ts

@@ -13,10 +13,14 @@ import type {
     User,
     UserInviteToken,
 } from '@vertesia/common';
+import AccountApiKeysApi from './AccountApiKeysApi.js';
 
 export default class AccountApi extends ApiTopic {
+    readonly apikeys: AccountApiKeysApi;
+
     constructor(parent: ClientBase) {
         super(parent, '/api/v1/account');
+        this.apikeys = new AccountApiKeysApi(parent);
     }
 
     /**

package/src/AccountApiKeysApi.ts

@@ -0,0 +1,29 @@
+import { ApiTopic, type ClientBase } from '@vertesia/api-fetch-client';
+import type {
+    AccountApiKey,
+    AccountApiKeyWithValue,
+    CreateAccountApiKeyPayload,
+    DeleteOperationResult,
+    UpdateAccountApiKeyPayload,
+} from '@vertesia/common';
+
+export default class AccountApiKeysApi extends ApiTopic {
+    constructor(parent: ClientBase) {
+        super(parent, '/api/v1/account/apikeys');
+    }
+    list(): Promise<AccountApiKey[]> {
+        return this.get('/');
+    }
+    retrieve(id: string): Promise<AccountApiKey> {
+        return this.get(`/${id}`);
+    }
+    create(payload: CreateAccountApiKeyPayload): Promise<AccountApiKeyWithValue> {
+        return this.post('/', { payload });
+    }
+    update(id: string, payload: UpdateAccountApiKeyPayload): Promise<AccountApiKey> {
+        return this.put(`/${id}`, { payload });
+    }
+    delete(id: string): Promise<DeleteOperationResult> {
+        return this.del(`/${id}`);
+    }
+}

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/bundle-isolation.test.ts

@@ -0,0 +1,37 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+
+// Build outputs are required; Turbo runs this package's build before its tests.
+const path = (relative: string) => new URL(relative, import.meta.url).pathname;
+
+const CLIENT_BUNDLE = path('../lib/vertesia-client.js');
+/** `.` and `./node` in the client's exports map — the latter is `lib/nodejs/index.js`, not `lib/index.js`. */
+const CLIENT_ENTRIES = [
+    { label: 'client default entry (.)', file: path('../lib/index.js') },
+    { label: 'client node entry (./node)', file: path('../lib/nodejs/index.js') },
+];
+
+/** Markers that prove a runtime schema import leaked into a browser artifact. */
+const FORBIDDEN = ['zod', '_zod', 'ZodObject', 'api-schemas', 'toOpenApiComponents', 'ApiSchemaComponents'];
+
+function expectNoSchemaRuntime(file: string, label: string): void {
+    const contents = readFileSync(file, 'utf8');
+    for (const marker of FORBIDDEN) {
+        expect(contents, `${label} must not contain '${marker}'`).not.toContain(marker);
+    }
+}
+
+describe('@vertesia/client consumer runtime isolation', () => {
+    it('contains no zod import or schema registry code', () => {
+        // The client is served to the browser the same way common is, so importing
+        // `@vertesia/common/api-schemas` from an SDK method would ship zod to every UI user.
+        expectNoSchemaRuntime(CLIENT_BUNDLE, 'client browser bundle');
+    });
+
+    it.each(CLIENT_ENTRIES)('does not reference the api-schemas subpath from the $label', ({ label, file }) => {
+        // Asserted rather than skipped: a missing artifact means the entry moved or stopped being
+        // built, and silently passing would let a packaging regression through unnoticed.
+        expect(existsSync(file), `${label} not found at ${file} — has the exports map changed?`).toBe(true);
+        expect(readFileSync(file, 'utf8'), `${label} must not import api-schemas`).not.toContain('api-schemas');
+    });
+});

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/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