@vertesia/client 1.5.0-dev.20260714.072725Z → 1.5.0-dev.20260717.131047Z

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vertesia/client",
-  "version": "1.5.0-dev.20260714.072725Z",
+  "version": "1.5.0-dev.20260717.131047Z",
   "type": "module",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -12,7 +12,7 @@
   "license": "Apache-2.0",
   "devDependencies": {
     "@types/node": "^24.13.2",
-    "rolldown": "1.1.3",
+    "rolldown": "1.1.4",
     "typescript": "^6.0.3",
     "vitest": "^4.1.9",
     "@vertesia/tsconfig": "0.1.0"
@@ -20,8 +20,8 @@
   "dependencies": {
     "eventsource": "^4.1.0",
     "@llumiverse/common": "1.5.0-dev.20260713.114357Z",
-    "@vertesia/api-fetch-client": "1.5.0-dev.20260714.072725Z",
-    "@vertesia/common": "1.5.0-dev.20260714.072725Z"
+    "@vertesia/common": "1.5.0-dev.20260717.131047Z",
+    "@vertesia/api-fetch-client": "1.5.0-dev.20260717.131047Z"
   },
   "exports": {
     ".": {
@@ -48,6 +48,7 @@
     "ai",
     "typescript"
   ],
+  "gitHead": "8aaad228827b2927db8e6aa75b27bfac90fec36f",
   "scripts": {
     "lint": "biome lint src",
     "clean:lib": "rimraf ./lib ./tsconfig.tsbuildinfo",

package/src/AppsApi.ts

@@ -1,5 +1,9 @@
 import { ApiTopic, type ClientBase, type ServerError } from '@vertesia/api-fetch-client';
 import type {
+    ActivateAppVersionResponse,
+    AppBuildProgress,
+    AppDeleteSummary,
+    AppInspectionResult,
     AppInstallation,
     AppInstallationKind,
     AppInstallationListEntry,
@@ -7,11 +11,21 @@ import type {
     AppInstallationWithManifest,
     AppManifest,
     AppManifestData,
+    AppPackage,
+    AppPackageScope,
+    AppRepoFile,
+    AppRepoRefs,
+    AppRepoTree,
     AppToolCollection,
+    AppVersionListQuery,
+    AppVersionRecord,
     CountResult,
     ProjectRef,
     RequireAtLeastOne,
+    StartAppBuildRequest,
+    StartAppBuildResponse,
     UpdateAppInstallationToolAllowlistPayload,
+    UpsertAppVersionRequest,
     ValidateUrlRequest,
     ValidateUrlResponse,
 } from '@vertesia/common';
@@ -34,14 +48,55 @@ export default class AppsApi extends ApiTopic {
     }
 
     /**
-     * Delete an app manifest by id. The owning account must permit the operation.
-     * Note: also uninstall any existing installations of this manifest before deleting,
-     * otherwise the server may refuse or leave orphaned installation records.
+     * Preview what the cascade delete would remove. Calls DELETE without confirm,
+     * which the server treats as a dry-run and returns counts + paths.
      */
-    delete(id: string): Promise<CountResult> {
+    previewDelete(id: string): Promise<AppDeleteSummary> {
         return this.del(`/${id}`);
     }
 
+    /**
+     * Cascade-delete an app and everything attached to it (versions,
+     * installations + ACEs, git repo on the app-git server). Pass through
+     * the dry-run summary; confirm flag is required server-side.
+     */
+    deleteApp(id: string): Promise<AppDeleteSummary> {
+        return this.del(`/${id}`, { query: { confirm: 'true' } });
+    }
+
+    listVersions(query?: AppVersionListQuery): Promise<AppVersionRecord[]> {
+        return this.get('/versions', {
+            query: {
+                ...(query?.app_id && { app_id: query.app_id }),
+                ...(query?.kind && { kind: query.kind }),
+                ...(query?.include_expired !== undefined && { include_expired: query.include_expired }),
+                ...(query?.limit !== undefined && { limit: query.limit }),
+            },
+        });
+    }
+
+    upsertVersion(payload: UpsertAppVersionRequest): Promise<AppVersionRecord> {
+        return this.post('/versions', { payload });
+    }
+
+    getVersion(recordId: string): Promise<AppVersionRecord> {
+        return this.get(`/versions/${recordId}`);
+    }
+
+    activateVersion(recordId: string): Promise<ActivateAppVersionResponse> {
+        return this.post(`/versions/${recordId}/activate`);
+    }
+
+    startBuild(appIdOrRecordId: string, payload: StartAppBuildRequest): Promise<StartAppBuildResponse> {
+        return this.post(`/${encodeURIComponent(appIdOrRecordId)}/builds`, { payload });
+    }
+
+    getBuildProgress(appIdOrRecordId: string, workflowId: string, runId: string): Promise<AppBuildProgress> {
+        return this.get(
+            `/${encodeURIComponent(appIdOrRecordId)}/builds/${encodeURIComponent(workflowId)}/${encodeURIComponent(runId)}/progress`,
+        );
+    }
+
     /**
      * Get the list if tools provided by the given app.
      * @param appId
@@ -51,6 +106,80 @@ export default class AppsApi extends ApiTopic {
         return this.get(`/installations/${appInstallId}/tools`);
     }
 
+    /**
+     * Inspect an app's registration: resolved manifest state, what the published
+     * package actually exposes per capability, endpoint reachability, install
+     * state, and diagnostics. Use this to verify what an app registers vs what it
+     * declares, instead of inferring it from failed object/import calls.
+     */
+    inspect(appIdOrName: string): Promise<AppInspectionResult> {
+        return this.get(`/${appIdOrName}/inspect`);
+    }
+
+    /**
+     * List files/directories under a prefix in the app's git repository (default
+     * branch unless `ref` is given). Read-only; reads live from the git server
+     * without a clone. Used by the Build > Design view to surface generated `docs/`.
+     */
+    getRepoTree(appIdOrName: string, options?: { prefix?: string; ref?: string }): Promise<AppRepoTree> {
+        return this.get(`/${encodeURIComponent(appIdOrName)}/repo/tree`, {
+            query: { prefix: options?.prefix, ref: options?.ref },
+        });
+    }
+
+    /**
+     * Read the UTF-8 content of a single file in the app's git repository (default
+     * branch unless `ref` is given). Read-only; reads live from the git server.
+     */
+    getRepoFile(appIdOrName: string, path: string, options?: { ref?: string }): Promise<AppRepoFile> {
+        return this.get(`/${encodeURIComponent(appIdOrName)}/repo/file`, {
+            query: { path, ref: options?.ref },
+        });
+    }
+
+    /**
+     * List the branches and tags of the app's git repository, each resolved to its latest commit.
+     * Read-only; reads live from the git server without a clone. Used by the Source view to let a
+     * user pick a ref to build from.
+     */
+    getRepoRefs(appIdOrName: string): Promise<AppRepoRefs> {
+        return this.get(`/${encodeURIComponent(appIdOrName)}/repo/refs`);
+    }
+
+    /**
+     * Get the published package an app exposes, filtered by scope. App-owned (in-code) artifacts are
+     * package-resolved (no per-id route), so this is how a client reads the full definition — type
+     * schema, interaction prompt, process definition, dashboard spec — to visualize an exposed id.
+     */
+    getAppPackage(appIdOrName: string, scope: AppPackageScope | AppPackageScope[] = 'all'): Promise<AppPackage> {
+        return this.get(`/${encodeURIComponent(appIdOrName)}/package`, {
+            query: { scope: Array.isArray(scope) ? scope.join(',') : scope },
+        });
+    }
+
+    /**
+     * Get package capabilities exposed by an app installation.
+     */
+    getAppInstallationPackage(
+        appInstallId: string,
+        scope: AppPackageScope | AppPackageScope[] = 'all',
+    ): Promise<AppPackage> {
+        return this.get(`/installations/${appInstallId}/package`, {
+            query: {
+                scope: Array.isArray(scope) ? scope.join(',') : scope,
+            },
+        });
+    }
+
+    /**
+     * Fetch the always-on system tools package served by studio-server.
+     * Tools and skills (`learn_*`) are returned on separate fields so UIs can
+     * render them distinctly. URLs are already resolved per deployment.
+     */
+    getSystemToolsPackage(scope: string = 'tools'): Promise<AppPackage> {
+        return this.get('/studio-tools/package', { query: { scope } });
+    }
+
     /**
      * @param ids - ids to filter by
      * @returns the app manifests but without the agent.tool property which can be big.

package/src/RunsApi.ts

@@ -115,9 +115,14 @@ export class RunsApi extends ApiTopic {
      * @param payload
      * @returns
      */
-    sendToolResults(payload: ToolResultsPayload): Promise<ExecutionResponse> {
+    sendToolResults(
+        payload: ToolResultsPayload,
+        options?: { timeoutMs?: number | false | null; signal?: AbortSignal },
+    ): Promise<ExecutionResponse> {
         return this.post(`/tool-results`, {
             payload,
+            timeoutMs: options?.timeoutMs,
+            signal: options?.signal,
         });
     }
 
@@ -126,9 +131,14 @@ export class RunsApi extends ApiTopic {
      * @param payload
      * @returns
      */
-    sendUserMessage(payload: UserMessagePayload): Promise<ExecutionResponse> {
+    sendUserMessage(
+        payload: UserMessagePayload,
+        options?: { timeoutMs?: number | false | null; signal?: AbortSignal },
+    ): Promise<ExecutionResponse> {
         return this.post(`/user-message`, {
             payload,
+            timeoutMs: options?.timeoutMs,
+            signal: options?.signal,
         });
     }
 

package/src/client.ts

@@ -1,5 +1,5 @@
 import { AbstractFetchClient, type FETCH_FN, type IRequestRetryPolicy } from '@vertesia/api-fetch-client';
-import type { AuthTokenPayload, AuthTokenResponse } from '@vertesia/common';
+import { APP_VERSION_HEADER, type AuthTokenPayload, type AuthTokenResponse } from '@vertesia/common';
 import AccountApi from './AccountApi.js';
 import AccountsApi from './AccountsApi.js';
 import AnalyticsApi from './AnalyticsApi.js';
@@ -116,7 +116,7 @@ export class VertesiaClient extends AbstractFetchClient<VertesiaClient> {
     static async fromAuthToken(
         token: string,
         payload?: AuthTokenPayload,
-        endpoints?: { studio: string; store: string; token?: string },
+        endpoints?: { studio: string; store: string; token?: string; git?: string },
     ) {
         if (!payload) {
             payload = decodeJWT(token);
@@ -240,6 +240,20 @@ export class VertesiaClient extends AbstractFetchClient<VertesiaClient> {
         return this;
     }
 
+    /**
+     * Pin the app version this client's requests resolve against. A generated app's UI sets this from
+     * its build-time `VITE_APP_VERSION` so studio/zeno resolve its `app:<app>:…` refs against that
+     * published version (candidate testing) instead of current. Pass null/empty to clear (→ current).
+     */
+    withAppVersion(version: string | null | undefined) {
+        if (!version) {
+            delete this.headers[APP_VERSION_HEADER];
+        } else {
+            this.headers[APP_VERSION_HEADER] = String(version);
+        }
+        return this;
+    }
+
     /**
      * Overwrite to keep store and composable clients synchronized on the auth callback
      * @param authCb
@@ -500,6 +514,7 @@ function getEndpointsFromDomain(domain: string) {
             studio: `http://localhost:8091`,
             store: `http://localhost:8092`,
             token: getRuntimeStsUrl() ?? 'https://sts.dev1.vertesia.io',
+            git: 'https://git.dev1.vertesia.io',
         };
     } else {
         const url = `https://${domain}`;
@@ -509,6 +524,7 @@ function getEndpointsFromDomain(domain: string) {
             studio: url,
             store: url,
             token: url.replace('api', 'sts'),
+            git: url.replace('api', 'git'),
         };
     }
 }

package/src/index.ts

@@ -7,6 +7,7 @@ export type { GroupsQueryOptions } from './GroupsApi.js';
 export * from './InteractionBase.js';
 export * from './InteractionOutput.js';
 export { default as InternalSecretsApi } from './InternalSecretsApi.js';
+export * from './managed-sse.js';
 export { default as OAuthClientsApi } from './OAuthClientsApi.js';
 export { default as OAuthGrantsApi } from './OAuthGrantsApi.js';
 export { default as OAuthProvidersApi } from './OAuthProvidersApi.js';

package/src/managed-sse.ts

@@ -0,0 +1,205 @@
+import { EventSourceProvider } from './execute.js';
+
+export type ManagedEventSourceStatus = 'connecting' | 'open' | 'reconnecting' | 'closed';
+
+export interface ManagedEventSourceEvent<T> {
+    data: T;
+    event_type: string;
+    event_id?: string;
+}
+
+export interface ManagedEventSourceConnection {
+    readonly closed: boolean;
+    close(): void;
+}
+
+export interface ManagedEventSourceOptions<T> {
+    url: URL | string | (() => URL | string | Promise<URL | string>);
+    event_types?: string[];
+    signal?: AbortSignal;
+    max_reconnect_attempts?: number;
+    base_reconnect_delay_ms?: number;
+    max_reconnect_delay_ms?: number;
+    last_event_id_query_param?: string;
+    get_access_token?: () => Promise<string | undefined>;
+    parse?: (data: string, eventType: string) => T;
+    get_cursor?: (data: T) => string | undefined;
+    on_event: (event: ManagedEventSourceEvent<T>) => void;
+    on_error?: (error: unknown) => void;
+    on_status?: (status: ManagedEventSourceStatus) => void;
+}
+
+function defaultParse<T>(data: string): T {
+    return JSON.parse(data) as T;
+}
+
+function calculateBackoffDelay(attempts: number, baseDelayMs: number, maxDelayMs: number): number {
+    const exponentialDelay = Math.min(baseDelayMs * 2 ** attempts, maxDelayMs);
+    const jitter = Math.random() * 0.1 * exponentialDelay;
+    return exponentialDelay + jitter;
+}
+
+function withAccessToken(url: URL, bearerToken: string | undefined): void {
+    if (!bearerToken) {
+        return;
+    }
+    const token = bearerToken.startsWith('Bearer ') ? bearerToken.slice('Bearer '.length) : bearerToken;
+    url.searchParams.set('access_token', token);
+}
+
+async function resolveUrl(value: ManagedEventSourceOptions<unknown>['url']): Promise<URL> {
+    const resolved = typeof value === 'function' ? await value() : value;
+    return resolved instanceof URL ? new URL(resolved.href) : new URL(resolved);
+}
+
+export function openManagedEventSource<T>(options: ManagedEventSourceOptions<T>): ManagedEventSourceConnection {
+    const eventTypes = options.event_types?.length ? options.event_types : ['message'];
+    const maxReconnectAttempts = options.max_reconnect_attempts ?? 10;
+    const baseDelayMs = options.base_reconnect_delay_ms ?? 1000;
+    const maxDelayMs = options.max_reconnect_delay_ms ?? 30_000;
+    const parse = options.parse ?? defaultParse<T>;
+
+    let closed = false;
+    let reconnectAttempts = 0;
+    let currentSse: EventSource | null = null;
+    let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+    let abortHandler: (() => void) | null = null;
+    let connectionOpenedAt = 0;
+    let lastEventId: string | undefined;
+
+    const emitStatus = (status: ManagedEventSourceStatus) => {
+        options.on_status?.(status);
+    };
+
+    const cleanupCurrentSource = () => {
+        if (currentSse) {
+            currentSse.close();
+            currentSse = null;
+        }
+        if (reconnectTimer) {
+            clearTimeout(reconnectTimer);
+            reconnectTimer = null;
+        }
+    };
+
+    const close = () => {
+        if (closed) {
+            return;
+        }
+        closed = true;
+        cleanupCurrentSource();
+        if (options.signal && abortHandler) {
+            options.signal.removeEventListener('abort', abortHandler);
+            abortHandler = null;
+        }
+        emitStatus('closed');
+    };
+
+    const scheduleReconnect = (error: unknown) => {
+        if (closed) {
+            return;
+        }
+        cleanupCurrentSource();
+        const connectionDuration = connectionOpenedAt ? Date.now() - connectionOpenedAt : 0;
+        if (connectionDuration > 5000) {
+            reconnectAttempts = 0;
+        }
+        if (reconnectAttempts >= maxReconnectAttempts) {
+            close();
+            options.on_error?.(error);
+            return;
+        }
+        const delay = calculateBackoffDelay(reconnectAttempts, baseDelayMs, maxDelayMs);
+        reconnectAttempts += 1;
+        emitStatus('reconnecting');
+        reconnectTimer = setTimeout(() => {
+            reconnectTimer = null;
+            void connect(true);
+        }, delay);
+    };
+
+    const handleMessage = (eventType: string, ev: MessageEvent) => {
+        if (closed || !ev.data || String(ev.data).startsWith(':')) {
+            return;
+        }
+        try {
+            const data = parse(String(ev.data), eventType);
+            const cursor = options.get_cursor?.(data);
+            lastEventId = ev.lastEventId || cursor || lastEventId;
+            options.on_event({
+                data,
+                event_type: eventType,
+                event_id: ev.lastEventId || cursor,
+            });
+        } catch (err) {
+            options.on_error?.(err);
+        }
+    };
+
+    const connect = async (isReconnect: boolean) => {
+        if (closed) {
+            return;
+        }
+        try {
+            emitStatus(isReconnect ? 'reconnecting' : 'connecting');
+            const EventSourceImpl = await EventSourceProvider();
+            if (closed) {
+                return;
+            }
+            const url = await resolveUrl(options.url);
+            if (
+                lastEventId &&
+                options.last_event_id_query_param &&
+                !url.searchParams.has(options.last_event_id_query_param)
+            ) {
+                url.searchParams.set(options.last_event_id_query_param, lastEventId);
+            }
+            withAccessToken(url, await options.get_access_token?.());
+            if (closed) {
+                return;
+            }
+            const sse = new EventSourceImpl(url.href);
+            currentSse = sse;
+            connectionOpenedAt = 0;
+
+            sse.onopen = () => {
+                connectionOpenedAt = Date.now();
+                emitStatus('open');
+            };
+
+            for (const eventType of eventTypes) {
+                sse.addEventListener(eventType, (ev) => handleMessage(eventType, ev as MessageEvent));
+            }
+
+            sse.onerror = (err: unknown) => {
+                scheduleReconnect(err);
+            };
+        } catch (err) {
+            scheduleReconnect(err);
+        }
+    };
+
+    if (options.signal) {
+        if (options.signal.aborted) {
+            closed = true;
+            emitStatus('closed');
+            return {
+                get closed() {
+                    return closed;
+                },
+                close,
+            };
+        }
+        abortHandler = close;
+        options.signal.addEventListener('abort', abortHandler, { once: true });
+    }
+
+    void connect(false);
+
+    return {
+        get closed() {
+            return closed;
+        },
+        close,
+    };
+}

package/src/store/AgentsApi.ts

@@ -362,6 +362,61 @@ export class AgentsApi extends ApiTopic {
             }
         };
 
+        // SSE reconnection exhausted. The run is durable and still executing
+        // server-side — only the live view dropped. Failing fatally here aborts
+        // headless consumers (CLI `agents stream`, agent test harnesses) before
+        // they can read the result. Instead degrade gracefully: poll GET /updates
+        // for any messages we missed and exit cleanly once the run is terminal,
+        // even if the terminal message never streamed.
+        const POLL_INTERVAL_MS = 5000;
+        const isTerminalStatus = (status: unknown): boolean =>
+            typeof status === 'string' && ['completed', 'failed', 'cancelled'].includes(status);
+        const degradeToPolling = (reason: unknown) => {
+            if (isClosed) return;
+            cleanup();
+            console.warn(
+                `Agent stream ${id}: SSE unavailable after ${maxReconnectAttempts} attempts; falling back to /updates polling.`,
+                reason instanceof Error ? reason.message : reason,
+            );
+            const tick = async () => {
+                if (isClosed) return;
+                try {
+                    const recent = await this.retrieveMessages(id, lastMessageTimestamp || undefined);
+                    for (const msg of recent) {
+                        if (isClosed) return;
+                        if ((msg.timestamp || 0) <= lastMessageTimestamp) continue;
+                        lastMessageTimestamp = msg.timestamp || lastMessageTimestamp;
+                        if (onMessage) onMessage(msg, exit);
+                        if (isClosed) return;
+                        if (shouldCloseAgentRunStream(msg, id)) {
+                            exit(null);
+                            return;
+                        }
+                    }
+                } catch {
+                    // transient poll error — retry next tick
+                }
+                if (isClosed) return;
+                // Exit even when no terminal message ever streams, by reading the run record.
+                try {
+                    const run = (await this.get(`/${id}`)) as { status?: unknown };
+                    if (isTerminalStatus(run?.status)) {
+                        exit(null);
+                        return;
+                    }
+                } catch {
+                    // ignore — retry next tick
+                }
+                if (!isClosed) {
+                    reconnectTimer = setTimeout(() => {
+                        reconnectTimer = null;
+                        void tick();
+                    }, POLL_INTERVAL_MS);
+                }
+            };
+            void tick();
+        };
+
         if (signal) {
             if (signal.aborted) {
                 isClosed = true;
@@ -499,9 +554,7 @@ export class AgentsApi extends ApiTopic {
                             if (!isClosed) void setupStream(true);
                         }, delay);
                     } else {
-                        isClosed = true;
-                        cleanup();
-                        rejectFn(
+                        degradeToPolling(
                             new Error(`SSE connection failed after ${maxReconnectAttempts} reconnection attempts`),
                         );
                     }
@@ -516,9 +569,7 @@ export class AgentsApi extends ApiTopic {
                         if (!isClosed) void setupStream(true);
                     }, delay);
                 } else {
-                    isClosed = true;
-                    cleanup();
-                    rejectFn(err);
+                    degradeToPolling(err);
                 }
             }
         };