@vertesia/client 1.4.0-dev.20260615.042549Z → 1.4.0-dev.20260629.130134Z

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vertesia/client",
-  "version": "1.4.0-dev.20260615.042549Z",
+  "version": "1.4.0-dev.20260629.130134Z",
   "type": "module",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -14,17 +14,17 @@
     "@rollup/plugin-commonjs": "^29.0.3",
     "@rollup/plugin-node-resolve": "^16.0.3",
     "@rollup/plugin-terser": "^1.0.0",
-    "@types/node": "^24.12.4",
-    "rollup": "^4.61.0",
+    "@types/node": "^24.13.2",
+    "rollup": "^4.61.1",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.8",
+    "vitest": "^4.1.9",
     "@vertesia/tsconfig": "0.1.0"
   },
   "dependencies": {
     "eventsource": "^4.1.0",
-    "@llumiverse/common": "1.3.0",
-    "@vertesia/api-fetch-client": "1.4.0-dev.20260615.042549Z",
-    "@vertesia/common": "1.4.0-dev.20260615.042549Z"
+    "@llumiverse/common": "1.4.0-dev.20260629.090753Z",
+    "@vertesia/common": "1.4.0-dev.20260629.130134Z",
+    "@vertesia/api-fetch-client": "1.4.0-dev.20260629.130134Z"
   },
   "exports": {
     ".": {
@@ -53,8 +53,9 @@
   ],
   "scripts": {
     "lint": "biome lint src",
-    "build": "rm -rf ./lib ./tsconfig.tsbuildinfo && tsc && pnpm exec rollup -c",
-    "clean": "rm -rf ./node_modules ./lib ./tsconfig.tsbuildinfo",
+    "clean:lib": "rimraf ./lib ./tsconfig.tsbuildinfo",
+    "build": "pnpm run clean:lib && tsc -p tsconfig.json && pnpm exec rollup -c",
+    "clean": "rimraf ./node_modules ./lib ./tsconfig.tsbuildinfo",
     "test": "vitest run",
     "typecheck:test": "tsc -p tsconfig.test.json --noEmit"
   }

package/src/AppsApi.ts

@@ -1,9 +1,5 @@
 import { ApiTopic, type ClientBase, type ServerError } from '@vertesia/api-fetch-client';
 import type {
-    ActivateAppVersionResponse,
-    AppBuildProgress,
-    AppDeleteSummary,
-    AppInspectionResult,
     AppInstallation,
     AppInstallationKind,
     AppInstallationListEntry,
@@ -11,18 +7,11 @@ import type {
     AppInstallationWithManifest,
     AppManifest,
     AppManifestData,
-    AppPackage,
-    AppPackageScope,
     AppToolCollection,
-    AppVersionListQuery,
-    AppVersionRecord,
     CountResult,
     ProjectRef,
     RequireAtLeastOne,
-    StartAppBuildRequest,
-    StartAppBuildResponse,
     UpdateAppInstallationToolAllowlistPayload,
-    UpsertAppVersionRequest,
     ValidateUrlRequest,
     ValidateUrlResponse,
 } from '@vertesia/common';
@@ -45,55 +34,14 @@ export default class AppsApi extends ApiTopic {
     }
 
     /**
-     * Preview what the cascade delete would remove. Calls DELETE without confirm,
-     * which the server treats as a dry-run and returns counts + paths.
+     * 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.
      */
-    previewDelete(id: string): Promise<AppDeleteSummary> {
+    delete(id: string): Promise<CountResult> {
         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
@@ -103,39 +51,6 @@ 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`);
-    }
-
-    /**
-     * 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/IamApi.ts

@@ -7,6 +7,7 @@ import type {
     DeleteByIdResult,
     PrincipalIdentity,
     RoleDefinition,
+    SystemRoleDefinition,
 } from '@vertesia/common';
 import { GroupsApi } from './GroupsApi.js';
 
@@ -42,9 +43,19 @@ export class RolesApi extends ApiTopic {
         super(parent, '/roles');
     }
 
+    /** List every built-in role across all partitions. Permissions are loosely typed (`string[]`). */
     list(): Promise<RoleDefinition[]> {
         return this.get('/');
     }
+
+    /**
+     * List system-domain roles only. Permissions are tightly typed as `Permission[]` —
+     * suited for client-side permission gating (button visibility, route guards).
+     * ABAC roles are excluded and must be consumed via the JWT `content_security` claim.
+     */
+    listSystem(): Promise<SystemRoleDefinition[]> {
+        return this.get('/system');
+    }
 }
 
 export class AcesApi extends ApiTopic {

package/src/RemoteMcpConnectionsApi.ts

@@ -7,6 +7,7 @@ import type {
     OAuthAuthorizeResponse,
     OAuthAuthStatus,
     OAuthMetadataResponse,
+    OAuthProviderExchangePayload,
 } from '@vertesia/common';
 
 export default class RemoteMcpConnectionsApi extends ApiTopic {
@@ -30,6 +31,12 @@ export default class RemoteMcpConnectionsApi extends ApiTopic {
         return this.get(`/authorize/${appInstallId}/${collectionId}`);
     }
 
+    exchange(code: string, state: string): Promise<McpOAuthConnectResponse> {
+        return this.post('/exchange', {
+            payload: { code, state } satisfies OAuthProviderExchangePayload,
+        });
+    }
+
     connect(appInstallId: string, collectionId: string): Promise<McpOAuthConnectResponse> {
         return this.post(`/connect/${appInstallId}/${collectionId}`, {});
     }

package/src/RunsApi.ts

@@ -90,6 +90,7 @@ export class RunsApi extends ApiTopic {
 
     async create<ResultT = unknown, ParamsT = unknown>(
         payload: RunCreatePayload,
+        options?: { timeoutMs?: number | false | null; signal?: AbortSignal },
     ): Promise<EnhancedExecutionRun<ResultT, ParamsT>> {
         const sessionTags = (this.client as VertesiaClient).sessionTags;
         if (sessionTags) {
@@ -103,6 +104,8 @@ export class RunsApi extends ApiTopic {
         }
         const r = await this.post<ExecutionRun<ParamsT>>('/', {
             payload,
+            timeoutMs: options?.timeoutMs,
+            signal: options?.signal,
         });
         return enhanceExecutionRun<ResultT, ParamsT>(r);
     }

package/src/ToolsApi.ts

@@ -13,9 +13,7 @@ import type {
  *  - `GET  /api/v1/tools`         — list every tool visible to the current principal across all sources
  *  - `POST /api/v1/tools/validate` — resolve a list of names against the same registry
  *
- * Note: this is distinct from `client.store.tools` (the static builtin catalog exposed by zeno-server)
- * — that one is global and source-incomplete (no app/interaction tools). Use this client for anything
- * project-aware.
+ * This is the canonical client for tool discovery and validation.
  */
 export default class ToolsApi extends ApiTopic {
     constructor(parent: ClientBase) {
@@ -42,6 +40,13 @@ export default class ToolsApi extends ApiTopic {
         return this.get('/', { query: Object.keys(params).length > 0 ? params : undefined });
     }
 
+    /**
+     * List only Vertesia-provided builtin tools and system skills.
+     */
+    listBuiltins(): Promise<AggregatedTool[]> {
+        return this.list({ sources: ['builtin'] });
+    }
+
     /**
      * Validate a list of tool names. Each result reports validity, source, app provenance,
      * and (for invalid names) a closest-match suggestion.

package/src/client.test.ts

@@ -59,7 +59,8 @@ describe('Test Vertesia Client', () => {
         expect(client).toBeDefined();
         expect(client.baseUrl).toBe('https://api-preview.vertesia.io');
         expect(client.storeUrl).toBe('https://api-preview.vertesia.io');
-        expect(client.tokenServerUrl).toBe('https://sts.vertesia.io');
+        // preview keeps its env segment: api-preview → sts-preview (its own STS)
+        expect(client.tokenServerUrl).toBe('https://sts-preview.vertesia.io');
     });
 
     test('Initialization with site api.dev1.vertesia.io', () => {
@@ -81,7 +82,8 @@ describe('Test Vertesia Client', () => {
         expect(client).toBeDefined();
         expect(client.baseUrl).toBe('https://api-preview.dev1.vertesia.io');
         expect(client.storeUrl).toBe('https://api-preview.dev1.vertesia.io');
-        expect(client.tokenServerUrl).toBe('https://sts.dev1.vertesia.io');
+        // preview keeps its env segment: api-preview → sts-preview (its own STS)
+        expect(client.tokenServerUrl).toBe('https://sts-preview.dev1.vertesia.io');
     });
 
     test('Initialization with regional serverUrl (api.us1)', () => {
@@ -116,8 +118,8 @@ describe('Test Vertesia Client', () => {
 
         expect(client).toBeDefined();
         expect(client.baseUrl).toBe('https://api-preview.us1.vertesia.io');
-        // preview strips -preview., then api → sts: sts.us1.vertesia.io
-        expect(client.tokenServerUrl).toBe('https://sts.us1.vertesia.io');
+        // preview keeps its env segment: api-preview → sts-preview (its own versioned STS)
+        expect(client.tokenServerUrl).toBe('https://sts-preview.us1.vertesia.io');
     });
 
     test('Initialization with site localhost', () => {

package/src/client.ts

@@ -65,6 +65,12 @@ export type VertesiaClientProps = {
     onRequest?: (request: Request) => void;
     onResponse?: (response: Response) => void;
     retryPolicy?: IRequestRetryPolicy;
+    /**
+     * Default request timeout in ms applied to every request (studio + store) unless overridden
+     * per-request via `timeoutMs`. `false`/`null`/`0` disables it. Aborts the whole request
+     * (connection + headers + body) via AbortSignal — browser + Node safe.
+     */
+    timeout?: number | false | null;
     fetch?: FETCH_FN | Promise<FETCH_FN>;
 };
 
@@ -107,7 +113,7 @@ export class VertesiaClient extends AbstractFetchClient<VertesiaClient> {
     static async fromAuthToken(
         token: string,
         payload?: AuthTokenPayload,
-        endpoints?: { studio: string; store: string; token?: string; git?: string },
+        endpoints?: { studio: string; store: string; token?: string },
     ) {
         if (!payload) {
             payload = decodeJWT(token);
@@ -152,14 +158,17 @@ export class VertesiaClient extends AbstractFetchClient<VertesiaClient> {
         if (opts.tokenServerUrl) {
             this.tokenServerUrl = opts.tokenServerUrl;
         } else if (opts.site) {
-            // Strip -preview (preview uses the same STS as production for the same region),
-            // then replace api prefix with sts.
+            // Replace the leading api prefix with sts, preserving the env segment so each
+            // environment hits its own STS. preview/preprod run a separately versioned STS
+            // (sts-preview / sts-preprod); collapsing them onto the production sts.<region>
+            // can route to an older STS that rejects scopes the env-matched STS supports
+            // (e.g. `offline_access`).
             // Examples:
-            //   api.vertesia.io          -> sts.vertesia.io
-            //   api-preview.vertesia.io  -> sts.vertesia.io
-            //   api.us1.vertesia.io      -> sts.us1.vertesia.io
-            //   api-preview.eu1.vertesia.io -> sts.eu1.vertesia.io
-            const stsHost = opts.site.replace('api-preview.', 'api.').replace(/^api/, 'sts');
+            //   api.vertesia.io             -> sts.vertesia.io
+            //   api-preview.vertesia.io     -> sts-preview.vertesia.io
+            //   api.us1.vertesia.io         -> sts.us1.vertesia.io
+            //   api-preview.eu1.vertesia.io -> sts-preview.eu1.vertesia.io
+            const stsHost = opts.site.replace(/^api/, 'sts');
             this.tokenServerUrl = `https://${stsHost}`;
         } else if (opts.serverUrl || opts.storeUrl) {
             // Determine STS URL based on environment in serverUrl or storeUrl
@@ -167,11 +176,12 @@ export class VertesiaClient extends AbstractFetchClient<VertesiaClient> {
             try {
                 const url = new URL(urlToCheck);
                 if (url.hostname.startsWith('api')) {
-                    // Strip -preview and replace api with sts.
+                    // Replace the leading api prefix with sts, preserving the env segment so
+                    // preview/preprod hit their own STS rather than production's.
                     // api.us1.vertesia.io         -> sts.us1.vertesia.io
-                    // api-preview.us1.vertesia.io -> sts.us1.vertesia.io
+                    // api-preview.us1.vertesia.io -> sts-preview.us1.vertesia.io
                     // api.vertesia.io             -> sts.vertesia.io
-                    const stsHost = url.hostname.replace('api-preview.', 'api.').replace(/^api/, 'sts');
+                    const stsHost = url.hostname.replace(/^api/, 'sts');
                     this.tokenServerUrl = `https://${stsHost}`;
                 } else {
                     this.tokenServerUrl = 'https://sts.dev1.vertesia.io';
@@ -190,6 +200,7 @@ export class VertesiaClient extends AbstractFetchClient<VertesiaClient> {
             onRequest: opts.onRequest,
             onResponse: opts.onResponse,
             retryPolicy: opts.retryPolicy,
+            timeout: opts.timeout,
             fetch: opts.fetch,
         });
 
@@ -197,6 +208,10 @@ export class VertesiaClient extends AbstractFetchClient<VertesiaClient> {
             this.withRetryPolicy(opts.retryPolicy);
         }
 
+        if (opts.timeout !== undefined) {
+            this.withTimeout(opts.timeout);
+        }
+
         if (opts.apikey) {
             void this.withApiKey(opts.apikey);
         }
@@ -236,6 +251,11 @@ export class VertesiaClient extends AbstractFetchClient<VertesiaClient> {
         return super.withRetryPolicy(policy);
     }
 
+    withTimeout(timeoutMs?: number | false | null) {
+        this.store.withTimeout(timeoutMs);
+        return super.withTimeout(timeoutMs);
+    }
+
     async withApiKey(apiKey: string | null) {
         return this.withAuthCallback(
             apiKey
@@ -471,7 +491,6 @@ 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}`;
@@ -481,7 +500,6 @@ function getEndpointsFromDomain(domain: string) {
             studio: url,
             store: url,
             token: url.replace('api', 'sts'),
-            git: url.replace('api', 'git'),
         };
     }
 }

package/src/execute.ts

@@ -10,6 +10,18 @@ import {
 } from '@vertesia/common';
 import type { VertesiaClient } from './client.js';
 
+/**
+ * Client-side timeout for a synchronous (non-streaming) interaction execution. The request blocks on
+ * studio-server until the model finishes — and the LLM (e.g. image generation) can legitimately take
+ * minutes — so the per-request timeout here is long, overriding any short client default. Override
+ * via the VERTESIA_INTERACTION_TIMEOUT_MS env var.
+ */
+const INTERACTION_EXECUTION_TIMEOUT_MS = (() => {
+    const raw = typeof process !== 'undefined' ? process.env?.VERTESIA_INTERACTION_TIMEOUT_MS : undefined;
+    const parsed = raw ? Number.parseInt(raw, 10) : NaN;
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : 30 * 60 * 1000; // 30 minutes
+})();
+
 export async function EventSourceProvider(): Promise<typeof EventSource> {
     if (typeof globalThis.EventSource === 'function') {
         return globalThis.EventSource;
@@ -35,11 +47,16 @@ export async function executeInteraction<P = unknown>(
     onChunk?: (chunk: string) => void,
 ): Promise<InteractionExecutionResult<P>> {
     const stream = !!onChunk;
-    const response = (await client.runs.create({
-        ...payload,
-        interaction: interactionId,
-        stream,
-    })) as unknown as InteractionExecutionResult<P>;
+    const response = (await client.runs.create(
+        {
+            ...payload,
+            interaction: interactionId,
+            stream,
+        },
+        // Synchronous interaction execution blocks on the model; keep a long client timeout.
+        // (Streaming returns the run immediately, then streams over a separate channel — see below.)
+        { timeoutMs: stream ? undefined : INTERACTION_EXECUTION_TIMEOUT_MS },
+    )) as unknown as InteractionExecutionResult<P>;
     if (stream) {
         if (response.status === ExecutionRunStatus.failed) {
             return response;
@@ -78,6 +95,8 @@ export async function executeInteractionByName<P = unknown>(
             interaction,
             stream,
         } as NamedInteractionExecutionPayload,
+        // Synchronous interaction execution blocks on the model; keep a long client timeout.
+        timeoutMs: stream ? undefined : INTERACTION_EXECUTION_TIMEOUT_MS,
     });
     if (stream) {
         if (response.status === ExecutionRunStatus.failed) {

package/src/store/AgentsApi.ts

@@ -10,7 +10,6 @@ import {
     type AgentRunResponse,
     type AgentRunUpdatesResponse,
     type BindRunWorkflowPayload,
-    type CompactMessage,
     type CreateAgentRunPayload,
     type CreateProcessRunPayload,
     type ErrorAnalyticsResponse,
@@ -55,6 +54,11 @@ import { EventSourceProvider } from '../execute.js';
 import { fetchSignedUrl } from './signed-url.js';
 import { shouldCloseAgentRunStream, shouldCloseCompactRunStream } from './stream-termination.js';
 
+export interface AgentRunStreamMessagesOptions {
+    onHistoryLoaded?: (messages: AgentMessage[]) => void;
+    onHistoryError?: (error: unknown) => void;
+}
+
 export class AgentsApi extends ApiTopic {
     constructor(parent: ClientBase) {
         super(parent, '/api/v1/agents');
@@ -278,7 +282,7 @@ export class AgentsApi extends ApiTopic {
     async retrieveMessages(id: string, since?: number): Promise<AgentMessage[]> {
         const query = since ? { since } : undefined;
         const response = (await this.get(`/${id}/updates`, { query })) as AgentRunUpdatesResponse;
-        return response.messages.map((m: CompactMessage) => toAgentMessage(m, id));
+        return response.messages.map((m) => toAgentMessage(parseMessage(m), id));
     }
 
     /**
@@ -303,6 +307,7 @@ export class AgentsApi extends ApiTopic {
         onMessage?: (message: AgentMessage, exitFn?: (payload: unknown) => void) => void,
         since?: number,
         signal?: AbortSignal,
+        options?: AgentRunStreamMessagesOptions,
     ): Promise<unknown> {
         let resolveFn: (value: unknown) => void = () => {};
         let rejectFn: (reason?: unknown) => void = () => {};
@@ -313,6 +318,7 @@ export class AgentsApi extends ApiTopic {
 
         let reconnectAttempts = 0;
         let lastMessageTimestamp = since || 0;
+        const historyFetchStartedAt = Date.now();
         let isClosed = false;
         let currentSse: EventSource | null = null;
         let interval: ReturnType<typeof setInterval> | null = null;
@@ -356,61 +362,6 @@ 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;
@@ -428,23 +379,35 @@ export class AgentsApi extends ApiTopic {
         try {
             if (!isClosed) {
                 const historical = await this.retrieveMessages(id, since);
-                for (const msg of historical) {
+                options?.onHistoryLoaded?.(historical);
+                let shouldCloseAfterHistory = false;
+                for (let index = 0; index < historical.length; index++) {
+                    const msg = historical[index];
                     if (isClosed) break;
                     lastMessageTimestamp = Math.max(lastMessageTimestamp, msg.timestamp || 0);
                     if (onMessage) onMessage(msg, exit);
                     if (isClosed) break;
 
-                    if (shouldCloseAgentRunStream(msg, id)) {
-                        exit(null);
-                        return promise;
-                    }
+                    shouldCloseAfterHistory = index === historical.length - 1 && shouldCloseAgentRunStream(msg, id);
+                }
+                if (shouldCloseAfterHistory) {
+                    exit(null);
+                    return promise;
                 }
             }
         } catch (err) {
             if (!isClosed) {
+                options?.onHistoryError?.(err);
                 console.warn('Failed to fetch historical messages, continuing with SSE:', err);
             }
         }
+        if (!isClosed && lastMessageTimestamp <= 0) {
+            // The server only replays the GET-to-SSE handoff gap when `since > 0`.
+            // New runs often have no history yet, so use the GET start time as the
+            // cursor to avoid dropping messages emitted before the SSE subscription
+            // is active.
+            lastMessageTimestamp = Math.max(1, historyFetchStartedAt - 1);
+        }
 
         // 2. Connect to SSE for real-time updates
         const setupStream = async (isReconnect: boolean = false) => {
@@ -536,7 +499,9 @@ export class AgentsApi extends ApiTopic {
                             if (!isClosed) void setupStream(true);
                         }, delay);
                     } else {
-                        degradeToPolling(
+                        isClosed = true;
+                        cleanup();
+                        rejectFn(
                             new Error(`SSE connection failed after ${maxReconnectAttempts} reconnection attempts`),
                         );
                     }
@@ -551,7 +516,9 @@ export class AgentsApi extends ApiTopic {
                         if (!isClosed) void setupStream(true);
                     }, delay);
                 } else {
-                    degradeToPolling(err);
+                    isClosed = true;
+                    cleanup();
+                    rejectFn(err);
                 }
             }
         };

package/src/store/DataApi.ts

@@ -12,6 +12,8 @@ import {
     type DataStoreArchiveResult,
     type DataStoreDownloadInfo,
     type DataStoreItem,
+    type DataStoreMutateRowsPayload,
+    type DataStoreMutateRowsResult,
     type DataStoreTableDetail,
     type DataStoreTableDropResult,
     type DataStoreVersion,
@@ -393,6 +395,20 @@ export class DataApi extends ApiTopic {
         return this.post(`/${id}/query/batch`, { payload: { queries }, headers: this.storeHeaders(id) });
     }
 
+    /**
+     * Execute a single row mutation statement against the data store.
+     *
+     * Only UPDATE and DELETE statements are accepted. The mutation is versioned
+     * and rolled back automatically if the statement or subsequent persistence fails.
+     *
+     * @param id - Data store ID
+     * @param payload - Mutation SQL and commit message
+     * @returns Resulting version ID and affected table row counts
+     */
+    mutateRows(id: string, payload: DataStoreMutateRowsPayload): Promise<DataStoreMutateRowsResult> {
+        return this.post(`/${id}/mutate`, { payload, headers: this.storeHeaders(id) });
+    }
+
     /**
      * Validate SQL queries without executing them.
      *