@vertesia/client 1.6.0-dev.20261019.172735Z → 1.6.0-dev.20261022.120426Z

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vertesia/client",
-  "version": "1.6.0-dev.20261019.172735Z",
+  "version": "1.6.0-dev.20261022.120426Z",
   "type": "module",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -12,16 +12,16 @@
   ],
   "license": "Apache-2.0",
   "devDependencies": {
-    "@types/node": "^24.19.1",
+    "@types/node": "^24.19.2",
     "@vertesia/tsconfig": "0.1.0",
-    "rolldown": "1.2.12",
+    "rolldown": "1.2.14",
     "typescript": "7.0.2",
-    "vitest": "5.0.3"
+    "vitest": "5.0.4"
   },
   "dependencies": {
-    "@llumiverse/common": "1.6.0-dev.20261019.165531Z",
-    "@vertesia/api-fetch-client": "1.6.0-dev.20261019.172735Z",
-    "@vertesia/common": "1.6.0-dev.20261019.172735Z",
+    "@llumiverse/common": "1.6.0-dev.20261022.120426Z",
+    "@vertesia/api-fetch-client": "1.6.0-dev.20261022.120426Z",
+    "@vertesia/common": "1.6.0-dev.20261022.120426Z",
     "eventsource": "^5.1.2"
   },
   "exports": {
@@ -49,7 +49,12 @@
     "ai",
     "typescript"
   ],
-  "gitHead": "85a3010750ab97192d236928b1fca55015a18000",
+  "gitHead": "bcaa7879b601ce9ccc394bcd3257822da13869cd",
+  "releaseIdentity": {
+    "source_sha": "bcaa7879b601ce9ccc394bcd3257822da13869cd",
+    "dependency_sha": "93466e47b06db23ac3c800e248d170afe65e5006",
+    "lock_sha256": "117e1c8068aa07d59117323a51ceccfc96cab543e50c03eb7efc19709d6f5e6b"
+  },
   "scripts": {
     "lint": "biome lint src",
     "clean:lib": "rimraf ./lib ./tsconfig.tsbuildinfo",

package/src/ApiKeysApi.ts

@@ -1,7 +1,6 @@
 import { ApiTopic, type ClientBase } from '@vertesia/api-fetch-client';
 import type {
     ApiKey,
-    ApiKeyReadResponse,
     ApiKeyWithValue,
     AuthTokenResponse,
     CreateApiKeyPayload,
@@ -42,17 +41,10 @@ export class ApiKeysApi extends ApiTopic {
     }
 
     /**
-     * Retrieve an ApiKey and its value
-     * BE VERY CAREFUL USING THIS API AS IT EXPOSE THE API KEY VALUE
-     * ALL REQUESTS ARE LOGGED IN SECURITY AUDIT LOG
-     * @returns ApiKeyWithValue
-     * */
-    retrieve(id: string, withValue: true): Promise<ApiKeyWithValue>;
-    retrieve(id: string, withValue?: false): Promise<ApiKey>;
-    retrieve(id: string, withValue: boolean = false): Promise<ApiKeyReadResponse> {
-        if (withValue) {
-            return this.get(`/${id}`, { query: { withValue: true } });
-        }
+     * Retrieve an ApiKey without its value. The raw value is returned only once, by `create`.
+     * @returns ApiKey
+     */
+    retrieve(id: string): Promise<ApiKey> {
         return this.get(`/${id}`);
     }
 

package/src/InteractionsApi.ts

@@ -33,7 +33,13 @@ import type {
     ResolveInteractionQuery,
 } from '@vertesia/common';
 import type { VertesiaClient } from './client.js';
-import { checkRateLimit, executeInteraction, executeInteractionAsync, executeInteractionByName } from './execute.js';
+import {
+    checkRateLimit,
+    type ExecuteInteractionRequestOptions,
+    executeInteraction,
+    executeInteractionAsync,
+    executeInteractionByName,
+} from './execute.js';
 import { InteractionCatalogApi } from './InteractionCatalogApi.js';
 import { type EnhancedInteractionExecutionResult, enhanceInteractionExecutionResult } from './InteractionOutput.js';
 
@@ -222,13 +228,14 @@ export default class InteractionsApi extends ApiTopic {
      * @param nameWithTag
      * @param payload
      * @param onChunk
+     * @param requestOptions request options, e.g. `{ query: { include_prompt: false } }` to omit the rendered prompt
      * @returns
      */
     async executeByName<ResultT = unknown, ParamsT = unknown>(
         nameWithTag: string,
         payload: InteractionExecutionPayload = {},
         onChunk?: (chunk: string) => void,
-        requestOptions?: IRequestParams,
+        requestOptions?: ExecuteInteractionRequestOptions,
     ): Promise<EnhancedInteractionExecutionResult<ResultT, ParamsT>> {
         const r = await executeInteractionByName<ParamsT>(
             this.client as VertesiaClient,

package/src/RunsApi.ts

@@ -8,6 +8,7 @@ import type {
     ExecutionRunRef,
     FindPayload,
     FindRunResult,
+    GetRunQuery,
     InteractionExecutionResult,
     PopulatedExecutionRun,
     RunClonePayload,
@@ -67,10 +68,14 @@ export class RunsApi extends ApiTopic {
      * Get a run by id
      *
      * @param id
+     * @param query response options, e.g. `{ include_prompt: false }` to omit the rendered prompt
      * @returns InteractionResult
      **/
-    async retrieve<ResultT = unknown, ParamsT = unknown>(id: string): Promise<EnhancedExecutionRun<ResultT, ParamsT>> {
-        const r = await this.get<ExecutionRun<ParamsT>>(`/${id}`);
+    async retrieve<ResultT = unknown, ParamsT = unknown>(
+        id: string,
+        query?: GetRunQuery,
+    ): Promise<EnhancedExecutionRun<ResultT, ParamsT>> {
+        const r = await this.get<ExecutionRun<ParamsT>>(`/${id}`, { query });
         return enhanceExecutionRun<ResultT, ParamsT>(r);
     }
 

package/src/execute.ts

@@ -2,6 +2,7 @@ import type { IRequestParams } from '@vertesia/api-fetch-client';
 import {
     type AsyncExecutionPayload,
     type AsyncExecutionResult,
+    type ExecuteNamedInteractionQuery,
     ExecutionRunStatus,
     type InteractionExecutionPayload,
     type InteractionExecutionResult,
@@ -23,6 +24,20 @@ const INTERACTION_EXECUTION_TIMEOUT_MS = (() => {
     return Number.isFinite(parsed) && parsed > 0 ? parsed : 30 * 60 * 1000; // 30 minutes
 })();
 
+/**
+ * Per-request options for a synchronous named-interaction execution: the request options this method
+ * can honour, plus the published execute query.
+ *
+ * `reader` and `jsonPayload` are left out: the method parses the JSON execution result and serializes
+ * the payload it builds, so either would break the call. `query` is the typed execute query instead of
+ * a free-form record, so a misspelt parameter fails to compile rather than being ignored by the server.
+ * With `onChunk`, the options apply to the initial request only; the stream that follows is a separate
+ * connection.
+ */
+export type ExecuteInteractionRequestOptions = Omit<IRequestParams, 'reader' | 'jsonPayload' | 'query'> & {
+    query?: ExecuteNamedInteractionQuery;
+};
+
 export async function EventSourceProvider(): Promise<typeof EventSource> {
     if (typeof globalThis.EventSource === 'function') {
         return globalThis.EventSource;
@@ -81,6 +96,7 @@ export async function executeInteraction<P = unknown>(
  * @param interaction
  * @param payload
  * @param onChunk
+ * @param requestOptions request options, e.g. `{ query: { include_prompt: false } }` to omit the rendered prompt
  * @returns
  */
 export async function executeInteractionByName<P = unknown>(
@@ -88,7 +104,7 @@ export async function executeInteractionByName<P = unknown>(
     interaction: string,
     payload: InteractionExecutionPayload = {},
     onChunk?: (chunk: string) => void,
-    requestOptions?: IRequestParams,
+    requestOptions?: ExecuteInteractionRequestOptions,
 ): Promise<InteractionExecutionResult<P>> {
     const stream = !!onChunk;
     const response = await client.post<InteractionExecutionResult<P>>('/api/v1/execute', {
@@ -98,8 +114,14 @@ export async function executeInteractionByName<P = unknown>(
             interaction,
             stream,
         } as NamedInteractionExecutionPayload,
-        // Synchronous interaction execution blocks on the model; keep a long client timeout.
-        timeoutMs: requestOptions?.timeoutMs ?? (stream ? undefined : INTERACTION_EXECUTION_TIMEOUT_MS),
+        // Synchronous interaction execution blocks on the model; keep a long client timeout. An explicit
+        // timeout wins, including `null`, `false` or `0`, which disable it.
+        timeoutMs:
+            requestOptions?.timeoutMs !== undefined
+                ? requestOptions.timeoutMs
+                : stream
+                  ? undefined
+                  : INTERACTION_EXECUTION_TIMEOUT_MS,
     });
     if (stream) {
         if (response.status === ExecutionRunStatus.failed) {
@@ -167,8 +189,13 @@ export async function executeInteractionAsync(
     client: VertesiaClient,
     payload: AsyncExecutionPayload,
 ): Promise<AsyncExecutionResult> {
+    // A conversation starts an agent run: without `idempotency_key` a replay could start a second one,
+    // so opt out of any client-level retry policy (see `AgentsApi.start`). With a key, a replay
+    // returns the run the first request started.
+    const unkeyedConversation = payload.type === 'conversation' && !payload.idempotency_key;
     return await client.post('/api/v1/execute/async', {
         payload,
+        retryPolicy: unkeyedConversation ? false : undefined,
     });
 }
 

package/src/index.ts

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

package/src/nodejs/NodeStreamSource.ts

@@ -1,10 +1,11 @@
 import type { Readable } from 'node:stream';
-import { ReadableStream as NodeReadableStream } from 'node:stream/web';
+import { finished } from 'node:stream/promises';
 import { StreamSource } from '../StreamSource.js';
 
 /**
  * A stream source that wraps a Node.js Readable stream.
  * This class is only works in Node.js environments.
+ * Cancelling the web stream destroys the Node.js stream, releasing its underlying resource (e.g. a file descriptor).
  */
 export class NodeStreamSource extends StreamSource {
     constructor(stream: Readable, name: string, type?: string, id?: string) {
@@ -12,31 +13,34 @@ export class NodeStreamSource extends StreamSource {
     }
 }
 
-function readableToWebStream<T = string | Buffer>(stream: Readable): ReadableStream<T> {
-    if (NodeReadableStream.from) {
-        return NodeReadableStream.from(stream) as ReadableStream<T>;
-    } else {
-        return readableToWebStream_BUN(stream);
-    }
-}
-
 /**
- * Bun implementation since bun is not yet supporting NodeReadableStream.from
- * @returns
+ * Not ReadableStream.from: it cancels by calling return() on the Node.js async iterator, which is a no-op
+ * when nothing was read yet, so the Node.js stream would stay open. Also covers Bun, which lacks ReadableStream.from.
  */
-function readableToWebStream_BUN<T = string | Buffer>(stream: Readable): ReadableStream<T> {
+function readableToWebStream<T = string | Buffer>(stream: Readable): ReadableStream<T> {
+    // Nothing listens until the first read, so an error before it (e.g. a failed lazy file open) would otherwise
+    // crash the process. The iterator still reports the error on the next read.
+    stream.on('error', () => undefined);
     const it = stream[Symbol.asyncIterator]();
-    return new ReadableStream<T>({
-        async pull(controller) {
-            const { value, done } = await it.next();
-            if (done) {
-                controller.close();
-            } else {
-                controller.enqueue(value);
-            }
-        },
-        cancel() {
-            it.return?.();
+    return new ReadableStream<T>(
+        {
+            async pull(controller) {
+                const { value, done } = await it.next();
+                if (done) {
+                    controller.close();
+                } else {
+                    controller.enqueue(value);
+                }
+            },
+            async cancel() {
+                // no error argument: it would emit 'error', which the caller may not listen for
+                stream.destroy();
+                // resolve once the underlying resource is released, so callers can remove the file afterwards;
+                // bounded because some streams never report their close
+                await finished(stream, { signal: AbortSignal.timeout(5_000) }).catch(() => undefined);
+            },
         },
-    });
+        // read on demand, like ReadableStream.from
+        { highWaterMark: 0 },
+    );
 }

package/src/store/AgentsApi.ts

@@ -87,13 +87,22 @@ export class AgentsApi extends ApiTopic {
     /**
      * Create and start a new agent run.
      * Returns the created AgentRun with its stable id.
+     *
+     * Set `idempotency_key` on an agent run to make the call safe to retry: the client's retry policy
+     * then applies, and a replayed request returns the run the first one started.
      */
     start<TData = Record<string, unknown>>(payload: CreateAgentRunPayload<TData>): Promise<AgentRun<TData>>;
     start<TData = Record<string, unknown>>(payload: CreateProcessRunPayload<TData>): Promise<ProcessRun>;
     start<TData = Record<string, unknown>>(
         payload: CreateAgentRunPayload<TData> | CreateProcessRunPayload<TData>,
     ): Promise<AgentRun<TData> | ProcessRun> {
-        return this.post('/', { payload });
+        // Without a key, starting an agent run is not idempotent: a request abandoned client-side can
+        // still complete server-side, so a replay would start 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. Process starts take no key and keep the client's policy.
+        const unkeyedAgentStart = 'interaction' in payload && !payload.idempotency_key;
+        return this.post('/', { payload, retryPolicy: unkeyedAgentStart ? false : undefined });
     }
 
     /**

package/src/store/FilesApi.ts

@@ -258,11 +258,17 @@ export class FilesApi extends ApiTopic {
                 'Content-Type': sourceMimeType,
             },
         }).catch((err) => {
-            console.error('Failed to upload file', { err, url, id, path });
+            console.error('Failed to upload file', { err, location: fileLocationForError(url), id, path });
             throw err;
         });
         if (!res.ok) {
-            console.log(res);
+            console.error('Failed to upload file', {
+                status: res.status,
+                statusText: res.statusText,
+                location: fileLocationForError(url),
+                id,
+                path,
+            });
             throw new Error(`Failed to upload file: ${res.statusText}`);
         }
 

package/src/store/IndexingApi.ts

@@ -27,6 +27,7 @@ import type {
     SwapAliasResult,
     TriggerReindexResult,
 } from '@vertesia/common';
+import { zenoBulkBaseUrl } from './zeno-bulk.js';
 
 /**
  * API for indexing operations on content objects.
@@ -274,30 +275,14 @@ export class IndexingApi extends ApiTopic {
 
     // ========================================================================
     // Zeno Bulk endpoints (Go migration service)
-    // Routes via LB path rules in prod, or derived URL in dev.
+    // Routes via LB path rules in prod, or derived URL in dev (see zenoBulkBaseUrl).
     // ========================================================================
 
-    /**
-     * Get the zeno-bulk base URL.
-     * Dev branches: store URL contains "zeno-server" -> replace with "zeno-bulk".
-     * Production/preview: same domain, LB routes /reindex/* to zeno-bulk.
-     */
-    private get zenoBulkBaseUrl(): string {
-        const storeBaseUrl = this.client.baseUrl;
-        if (storeBaseUrl.includes('localhost:') || storeBaseUrl.includes('127.0.0.1:')) {
-            return 'https://zeno-bulk-dev-main.api.dev1.vertesia.io';
-        }
-        if (storeBaseUrl.includes('zeno-server')) {
-            return storeBaseUrl.replace(/zeno-server/, 'zeno-bulk');
-        }
-        return storeBaseUrl;
-    }
-
     /**
      * POST to a zeno-bulk endpoint. Resolves the path against the zeno-bulk base URL.
      */
     private zenoBulkPost<T>(path: string, body: object): Promise<T> {
-        return this.client.post(this.zenoBulkBaseUrl + path, { payload: body });
+        return this.client.post(zenoBulkBaseUrl(this.client.baseUrl) + path, { payload: body });
     }
 
     /**

package/src/store/ObjectsApi.ts

@@ -63,6 +63,7 @@ import { AnalyzeDocApi } from './AnalyzeDocApi.js';
 import type { ZenoClient } from './client.js';
 import { fetchSignedUrl } from './signed-url.js';
 import { getUploadMimeTypeHint, resolveUploadMimeType } from './uploadMimeType.js';
+import { zenoBulkBaseUrl } from './zeno-bulk.js';
 
 /**
  * The two write payloads, each widened at `content` so callers can hand us a browser `File` or a
@@ -215,24 +216,8 @@ export class ObjectsApi extends ApiTopic {
         return this.zenoBulkPost('/export/compose', payload, timeoutMs);
     }
 
-    /**
-     * Get the zeno-bulk base URL.
-     * Dev branches: store URL contains "zeno-server" -> replace with "zeno-bulk".
-     * Production/preview: same domain, LB routes /export to zeno-bulk.
-     */
-    private get zenoBulkBaseUrl(): string {
-        const storeBaseUrl = this.client.baseUrl;
-        if (storeBaseUrl.includes('localhost:') || storeBaseUrl.includes('127.0.0.1:')) {
-            return 'https://zeno-bulk-dev-main.api.dev1.vertesia.io';
-        }
-        if (storeBaseUrl.includes('zeno-server')) {
-            return storeBaseUrl.replace(/zeno-server/, 'zeno-bulk');
-        }
-        return storeBaseUrl;
-    }
-
     private zenoBulkPost<T>(path: string, body: object, timeoutMs?: number | false | null): Promise<T> {
-        return this.client.post(this.zenoBulkBaseUrl + path, { payload: body, timeoutMs });
+        return this.client.post(zenoBulkBaseUrl(this.client.baseUrl) + path, { payload: body, timeoutMs });
     }
 
     listFolders(_path: string = '/') {

package/src/store/zeno-bulk.ts

@@ -0,0 +1,30 @@
+type RuntimeProcess = {
+    env?: Record<string, string | undefined>;
+};
+
+/** The ZENO_BULK_URL environment variable, in a runtime that has one. */
+function getRuntimeZenoBulkUrl() {
+    const runtimeProcess = (globalThis as typeof globalThis & { process?: RuntimeProcess }).process;
+    return runtimeProcess?.env?.ZENO_BULK_URL || undefined;
+}
+
+/**
+ * The base URL of zeno-bulk, the service behind the bulk export and reindex endpoints, for a store base URL.
+ * - ZENO_BULK_URL, when the runtime sets it: a local stack that runs its own zeno-bulk, or none, points it there.
+ * - A store on localhost: the dev1 zeno-bulk, which serves the database a default local stack uses.
+ * - A dev-branch store, whose host names zeno-server: the matching zeno-bulk host.
+ * - Any other store: its own domain, whose load balancer routes the bulk paths to zeno-bulk.
+ */
+export function zenoBulkBaseUrl(storeBaseUrl: string): string {
+    const override = getRuntimeZenoBulkUrl();
+    if (override) {
+        return override.replace(/\/+$/, '');
+    }
+    if (storeBaseUrl.includes('localhost:') || storeBaseUrl.includes('127.0.0.1:')) {
+        return 'https://zeno-bulk-dev-main.api.dev1.vertesia.io';
+    }
+    if (storeBaseUrl.includes('zeno-server')) {
+        return storeBaseUrl.replace(/zeno-server/, 'zeno-bulk');
+    }
+    return storeBaseUrl;
+}