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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vertesia/client",
-  "version": "1.6.0-dev.20261014.015055Z",
+  "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.20261014.012028Z",
-    "@vertesia/api-fetch-client": "1.6.0-dev.20261014.015055Z",
-    "@vertesia/common": "1.6.0-dev.20261014.015055Z",
+    "@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": "468240ecf939f968e1324116be26386cdf5ada49",
+  "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/AppsApi.ts

@@ -6,12 +6,16 @@ import type {
     AppDeleteSummary,
     AppDevelopmentTaskDetails,
     AppDevelopmentTaskList,
+    AppGithubConfiguration,
+    AppGithubRepositoryList,
+    AppGithubRepositorySetup,
     AppInspectionResult,
     AppInstallation,
     AppInstallationKind,
     AppInstallationListEntry,
     AppInstallationPayload,
     AppInstallationWithManifest,
+    AppInstanceAvailability,
     AppManifest,
     AppManifestData,
     AppPackage,
@@ -29,6 +33,7 @@ import type {
     CountResult,
     CreateAppRepoBranchRequest,
     DeleteAppVersionResponse,
+    ExchangeAppGithubAuthorizationResponse,
     McpApiKeyStatus,
     ProjectRef,
     PromoteAppVersionResponse,
@@ -37,6 +42,7 @@ import type {
     StartAppBuildRequest,
     StartAppBuildResponse,
     StartAppDevelopmentTaskRequest,
+    StartAppGithubAuthorizationResponse,
     StartAppScaffoldRequest,
     StartAppScaffoldResponse,
     UpdateAppInstallationOAuthApprovalPayload,
@@ -75,6 +81,27 @@ export default class AppsApi extends ApiTopic {
      * The key is write-only: it is encrypted server-side and never returned by any endpoint,
      * so the response carries only the configured flag and a masked hint.
      */
+    setInstallationMcpApiKey(installationId: string, collectionId: string, apiKey: string): Promise<McpApiKeyStatus> {
+        return this.put(
+            `/installations/${encodeURIComponent(installationId)}/collections/${encodeURIComponent(collectionId)}/api-key`,
+            {
+                payload: { api_key: apiKey },
+            },
+        );
+    }
+
+    getInstallationMcpApiKeyStatus(installationId: string, collectionId: string): Promise<McpApiKeyStatus> {
+        return this.get(
+            `/installations/${encodeURIComponent(installationId)}/collections/${encodeURIComponent(collectionId)}/api-key`,
+        );
+    }
+
+    deleteInstallationMcpApiKey(installationId: string, collectionId: string): Promise<McpApiKeyStatus> {
+        return this.del(
+            `/installations/${encodeURIComponent(installationId)}/collections/${encodeURIComponent(collectionId)}/api-key`,
+        );
+    }
+
     setMcpCollectionApiKey(appId: string, collectionId: string, apiKey: string): Promise<McpApiKeyStatus> {
         return this.put(`/${encodeURIComponent(appId)}/collections/${encodeURIComponent(collectionId)}/api-key`, {
             payload: { api_key: apiKey } satisfies SetMcpApiKeyRequest,
@@ -149,6 +176,63 @@ export default class AppsApi extends ApiTopic {
         return this.get(`/scaffolds/${encodeURIComponent(workflowId)}/${encodeURIComponent(runId)}/progress`);
     }
 
+    /**
+     * Return whether the global App Builder GitHub App is configured, together with its slug and
+     * installation URL when available.
+     */
+    getGithubConfiguration(): Promise<AppGithubConfiguration> {
+        return this.get('/source-providers/github');
+    }
+
+    /**
+     * Start GitHub user authorization. The server creates a short-lived, single-use OAuth state
+     * bound to the current Vertesia user/account/project and returns the GitHub authorization URL.
+     */
+    startGithubAuthorization(): Promise<StartAppGithubAuthorizationResponse> {
+        return this.post('/source-providers/github/authorize', {});
+    }
+
+    /**
+     * Complete GitHub authorization with the callback code and state. The server consumes the state,
+     * verifies the current user's writable GitHub App installations, discards the GitHub user token,
+     * and returns those installations plus an opaque `connection_id`. That id references a
+     * short-lived server-side snapshot of the writable repositories verified for this Vertesia
+     * user/account/project; selecting a repository consumes it once.
+     */
+    exchangeGithubAuthorization(code: string, state: string): Promise<ExchangeAppGithubAuthorizationResponse> {
+        return this.post('/source-providers/github/exchange', { payload: { code, state } });
+    }
+
+    /**
+     * List repositories with push access for one installation verified during authorization. The
+     * connection id is scoped to the current Vertesia user/account/project and expires shortly.
+     */
+    listGithubRepositories(connectionId: string, installationId: string): Promise<AppGithubRepositoryList> {
+        return this.get('/source-providers/github/repositories', {
+            query: { connection_id: connectionId, installation_id: installationId },
+        });
+    }
+
+    /**
+     * List branches and verify whether a selected branch can safely receive generated source.
+     * The verified connection remains reusable until app creation consumes it.
+     */
+    getGithubRepositorySetup(
+        connectionId: string,
+        installationId: string,
+        repository: string,
+        branch: string,
+    ): Promise<AppGithubRepositorySetup> {
+        return this.get('/source-providers/github/repository-setup', {
+            query: {
+                connection_id: connectionId,
+                installation_id: installationId,
+                repository,
+                branch,
+            },
+        });
+    }
+
     /**
      * Get the list if tools provided by the given app.
      * @param appId
@@ -328,14 +412,20 @@ export default class AppsApi extends ApiTopic {
         oauthParams?: Record<string, { client_id?: string; client_secret?: string; scopes?: string[] }>,
         oauthProviderParams?: Record<string, { client_id?: string; client_secret?: string; scopes?: string[] }>,
         apiKeyParams?: AppApiKeyCollectionParams,
+        mcpParameters?: AppInstallationPayload['mcp_parameters'],
+        mcpSharedParameters?: AppInstallationPayload['mcp_shared_parameters'],
+        instance?: Pick<AppInstallationPayload, 'instance_key' | 'display_name' | 'namespace_overrides'>,
     ): Promise<AppInstallation> {
         return this.post(`/install`, {
             payload: {
                 app_id: appId,
+                ...instance,
                 settings,
                 oauth_params: oauthParams,
                 oauth_provider_params: oauthProviderParams,
                 api_key_params: apiKeyParams,
+                mcp_parameters: mcpParameters,
+                mcp_shared_parameters: mcpSharedParameters,
             } satisfies AppInstallationPayload,
         });
     }
@@ -353,6 +443,14 @@ export default class AppsApi extends ApiTopic {
      * get an app unstallation given its name or null if the app is not installed
      * @returns
      */
+    getAppInstanceAvailability(): Promise<AppInstanceAvailability> {
+        return this.get('/instance-availability');
+    }
+
+    getAppInstallation(installationId: string): Promise<AppInstallationWithManifest> {
+        return this.get(`/installations/id/${encodeURIComponent(installationId)}`);
+    }
+
     getAppInstallationByName(appName: string): Promise<AppInstallationWithManifest | null> {
         return this.get<AppInstallationWithManifest>(`/installations/name/${appName}`).catch((err: ServerError) => {
             if (err.status === 404) {
@@ -426,6 +524,14 @@ export default class AppsApi extends ApiTopic {
                 // clear an override). The server uses `'access_control' in payload` to distinguish
                 // "leave unchanged" from "clear", so only spread the key when it was supplied.
                 ...('access_control' in settingsPayload ? { access_control: settingsPayload.access_control } : {}),
+                ...('display_name' in settingsPayload ? { display_name: settingsPayload.display_name } : {}),
+                ...('namespace_overrides' in settingsPayload
+                    ? { namespace_overrides: settingsPayload.namespace_overrides }
+                    : {}),
+                ...('mcp_parameters' in settingsPayload ? { mcp_parameters: settingsPayload.mcp_parameters } : {}),
+                ...('mcp_shared_parameters' in settingsPayload
+                    ? { mcp_shared_parameters: settingsPayload.mcp_shared_parameters }
+                    : {}),
             } satisfies AppInstallationPayload,
         });
     }

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/OAuthServerApi.ts

@@ -9,6 +9,9 @@ import type {
     OAuthGrantableScopesResponse,
     OAuthLoginDecisionResponse,
     OAuthLoginPayload,
+    OAuthTokenExchangeRequest,
+    OAuthTokenExchangeResponse,
+    ProjectRef,
 } from '@vertesia/common';
 
 export default class OAuthServerApi extends ClientBase {
@@ -22,6 +25,30 @@ export default class OAuthServerApi extends ClientBase {
         this.verboseErrors = parent.verboseErrors;
     }
 
+    /** Exchange a signed IdP assertion; optional client authentication follows the connection policy. */
+    exchangeToken(
+        payload: OAuthTokenExchangeRequest,
+        basic?: { client_id: string; client_secret: string },
+    ): Promise<OAuthTokenExchangeResponse> {
+        if (
+            basic &&
+            (payload.client_secret !== undefined ||
+                payload.client_assertion !== undefined ||
+                (payload.client_id !== undefined && payload.client_id !== basic.client_id))
+        )
+            throw new Error('Use exactly one client authentication method');
+        return this.post('/token', {
+            payload,
+            ...(basic
+                ? {
+                      headers: {
+                          Authorization: `Basic ${btoa(`${encodeURIComponent(basic.client_id)}:${encodeURIComponent(basic.client_secret)}`)}`,
+                      },
+                  }
+                : {}),
+        });
+    }
+
     login(requestId: string, payload: OAuthLoginPayload): Promise<OAuthLoginDecisionResponse> {
         return this.post(`/requests/${encodeURIComponent(requestId)}/login`, { payload });
     }
@@ -76,6 +103,10 @@ export default class OAuthServerApi extends ClientBase {
         return this.get(`/requests/${requestId}`);
     }
 
+    retrieveGrantableProjects(requestId: string): Promise<ProjectRef[]> {
+        return this.get(`/requests/${encodeURIComponent(requestId)}/grantable-projects`);
+    }
+
     retrieveGrantableScopes(requestId: string, projectId: string): Promise<OAuthGrantableScopesResponse> {
         return this.get(`/requests/${requestId}/grantable-scopes`, { query: { project_id: projectId } });
     }

package/src/OidcFederationApi.ts

@@ -0,0 +1,23 @@
+import { ApiTopic, type ClientBase } from '@vertesia/api-fetch-client';
+import type { OidcFederationConnection, OidcFederationConnectionPayload, SuccessResponse } from '@vertesia/common';
+
+export default class OidcFederationApi extends ApiTopic {
+    constructor(parent: ClientBase) {
+        super(parent, '/api/v1/oidc-federation');
+    }
+    retrieve(id: string): Promise<OidcFederationConnection> {
+        return this.get(`/${encodeURIComponent(id)}`);
+    }
+    list(): Promise<OidcFederationConnection[]> {
+        return this.get('/');
+    }
+    create(payload: OidcFederationConnectionPayload): Promise<OidcFederationConnection> {
+        return this.post('/', { payload });
+    }
+    update(id: string, payload: OidcFederationConnectionPayload): Promise<OidcFederationConnection> {
+        return this.put(`/${encodeURIComponent(id)}`, { payload });
+    }
+    remove(id: string): Promise<SuccessResponse> {
+        return this.del(`/${encodeURIComponent(id)}`);
+    }
+}

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/client.ts

@@ -18,6 +18,7 @@ import OAuthClientsApi from './OAuthClientsApi.js';
 import OAuthGrantsApi from './OAuthGrantsApi.js';
 import OAuthProvidersApi from './OAuthProvidersApi.js';
 import OAuthServerApi from './OAuthServerApi.js';
+import OidcFederationApi from './OidcFederationApi.js';
 import ProjectsApi from './ProjectsApi.js';
 import PromptsApi from './PromptsApi.js';
 import QuotaApi from './QuotaApi.js';
@@ -120,6 +121,7 @@ export class VertesiaClient extends AbstractFetchClient<VertesiaClient> {
      */
     tokenServerUrl: string;
 
+    oidcFederation: OidcFederationApi;
     oauthClients: OAuthClientsApi;
     oauthGrants: OAuthGrantsApi;
     oauthServer: OAuthServerApi;
@@ -251,6 +253,7 @@ export class VertesiaClient extends AbstractFetchClient<VertesiaClient> {
         this.onRequest = opts.onRequest;
         this.onResponse = opts.onResponse;
         this.sessionTags = opts.sessionTags;
+        this.oidcFederation = new OidcFederationApi(this);
         this.oauthClients = new OAuthClientsApi(this);
         this.oauthGrants = new OAuthGrantsApi(this);
         this.oauthServer = new OAuthServerApi(this, this.tokenServerUrl);

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';
@@ -12,6 +13,7 @@ export { default as OAuthClientsApi } from './OAuthClientsApi.js';
 export { default as OAuthGrantsApi } from './OAuthGrantsApi.js';
 export { default as OAuthProvidersApi } from './OAuthProvidersApi.js';
 export { default as OAuthServerApi } from './OAuthServerApi.js';
+export { default as OidcFederationApi } from './OidcFederationApi.js';
 export type { ComputePromptFacetsResponse, ListInteractionsResponse } from './PromptsApi.js';
 export { default as RemoteMcpConnectionsApi } from './RemoteMcpConnectionsApi.js';
 export type { ComputeRunFacetsResponse, FilterOption } from './RunsApi.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 });
     }
 
     /**