rocketride 1.0.6 → 1.1.1

package/dist/esm/client.js

@@ -23,8 +23,13 @@
  */
 import { TransportWebSocket } from './core/TransportWebSocket.js';
 import { DAPClient } from './core/DAPClient.js';
+import { TraceType } from './types/index.js';
 import { CONST_DEFAULT_WEB_CLOUD, CONST_DEFAULT_WEB_PROTOCOL, CONST_DEFAULT_WEB_PORT } from './constants.js';
-import { AuthenticationException } from './exceptions/index.js';
+import { AccountApi } from './account.js';
+import { BillingApi } from './billing.js';
+import { DatabaseApi } from './database.js';
+import { DeployApi } from './deploy.js';
+import { AuthenticationException, ConnectionException, PipeException } from './exceptions/index.js';
 // Global counter for generating unique client IDs
 let clientId = 0;
 /**
@@ -97,7 +102,8 @@ export class DataPipe {
      * unique pipe ID that is used for subsequent operations.
      *
      * @returns This DataPipe instance (for method chaining)
-     * @throws Error if the pipe is already opened or if the pipeline is not running
+     * @throws Error if the pipe is already opened
+     * @throws PipeException if the server rejects the open request
      */
     async open() {
         if (this._opened) {
@@ -114,15 +120,32 @@ export class DataPipe {
         });
         const response = await this._client.request(request);
         if (this._client.didFail(response)) {
-            throw new Error(response.message || 'Your pipeline is not currently running.');
+            const base = response.message || 'Failed to open a data pipe.';
+            const msg = `${base}\n\n` + 'Common causes:\n' + "- Pipeline isn't running (wrong token or task terminated)\n" + "- Pipeline source is 'chat' (use client.chat()), not webhook/dropper\n" + "- MIME type doesn't match the source lane (try mimeType='text/plain')\n";
+            throw new PipeException({ ...response, message: msg });
         }
         this._pipeId = response.body?.pipe_id;
-        this._opened = true;
         // If an SSE callback was provided, subscribe and register for this pipe
         if (this._onSSE !== undefined && this._pipeId !== undefined) {
-            await this._client.setEvents(this._token, ['SSE'], this._pipeId);
+            try {
+                await this._client.setEvents(this._token, ['SSE'], this._pipeId);
+            }
+            catch (err) {
+                // Roll back: don't leave the pipe half-open on the server.
+                try {
+                    await this.close();
+                }
+                catch {
+                    // Best-effort cleanup
+                }
+                const errMsg = err instanceof Error ? err.message : String(err);
+                const msg = `Failed to subscribe to SSE events for this data pipe.\n\n${errMsg}`;
+                throw new PipeException({ message: msg });
+            }
             this._client._ssePipeCallbacks.set(this._pipeId, this._onSSE);
         }
+        // Only mark opened after the server-side pipe is fully consistent (including SSE setup).
+        this._opened = true;
         return this;
     }
     /**
@@ -132,7 +155,8 @@ export class DataPipe {
      * multiple times to stream large datasets. The pipe must be opened first.
      *
      * @param buffer - Data to write, must be a Uint8Array
-     * @throws Error if the pipe is not opened, buffer is invalid, or write fails
+     * @throws Error if the pipe is not opened or buffer is invalid
+     * @throws PipeException if the server reports a write failure
      */
     async write(buffer) {
         if (!this._opened) {
@@ -151,7 +175,8 @@ export class DataPipe {
         });
         const response = await this._client.request(request);
         if (this._client.didFail(response)) {
-            throw new Error(response.message || 'Failed to write to pipe');
+            const msg = response.message || 'Failed to write to a data pipe.';
+            throw new PipeException({ ...response, message: msg });
         }
     }
     /**
@@ -162,10 +187,12 @@ export class DataPipe {
      * the pipe cannot be reopened or written to again.
      *
      * @returns The processing result from the server, or undefined if already closed
-     * @throws Error if closing the pipe fails
+     * @throws PipeException if the server reports a failure while finalizing the pipe
      */
     async close() {
-        if (!this._opened || this._closed) {
+        // Allow closing after a failed open() path where the server assigned a pipe_id
+        // but we never flipped _opened=true (e.g., SSE subscription failure).
+        if (this._closed || (this._pipeId === undefined && !this._opened)) {
             return;
         }
         try {
@@ -178,12 +205,14 @@ export class DataPipe {
             });
             const response = await this._client.request(request);
             if (this._client.didFail(response)) {
-                throw new Error(response.message || 'Failed to close pipe');
+                const msg = response.message || 'Failed to close a data pipe.';
+                throw new PipeException({ ...response, message: msg });
             }
             return response.body;
         }
         finally {
             this._closed = true;
+            this._opened = false;
             // Unregister SSE callback and scoped monitor subscription
             if (this._onSSE !== undefined && this._pipeId !== undefined) {
                 this._client._ssePipeCallbacks.delete(this._pipeId);
@@ -197,24 +226,6 @@ export class DataPipe {
         }
     }
 }
-/**
- * Main RocketRide client for connecting to RocketRide servers and services.
- *
- * This client provides a comprehensive API for interacting with RocketRide services,
- * including connection management, pipeline execution, data operations, AI chat,
- * event handling, and server connectivity testing.
- *
- * Key features:
- * - Single shared WebSocket connection for all operations
- * - Connection management (connect/disconnect) with optional persistence
- * - Automatic reconnection when persist mode is enabled
- * - Pipeline execution (use, terminate, getTaskStatus)
- * - Data operations (send, sendFiles, pipe)
- * - AI chat functionality (chat)
- * - Event handling (setEvents, event callbacks)
- * - Server connectivity testing (ping)
- * - Full TypeScript type safety
- */
 export class RocketRideClient extends DAPClient {
     /**
      * Creates a new RocketRideClient instance.
@@ -277,24 +288,26 @@ export class RocketRideClient extends DAPClient {
                 }
             }
         }
-        const { auth = config.auth || clientEnv.ROCKETRIDE_APIKEY, uri = config.uri || clientEnv.ROCKETRIDE_URI || CONST_DEFAULT_WEB_CLOUD, onEvent, onConnected, onDisconnected, onConnectError, persist, maxRetryTime, module, } = config;
+        const { auth = config.auth, uri = config.uri || clientEnv.ROCKETRIDE_URI || CONST_DEFAULT_WEB_CLOUD, onEvent, onConnected, onDisconnected, onConnectError, persist, module } = config;
         // Create unique client identifier
         const clientName = module || `CLIENT-${clientId++}`;
-        // Initialize the DAPClient without a transport; transport is created in _internalConnect (CONNECTION_LOGIC.md §3)
+        // Initialize the DAPClient without a transport; transport is created in _internalAttach
         super(clientName, undefined, config);
         this._dapAttempted = false;
         this._nextChatId = 1;
         /** Maps pipe_id → SSE callback for pipe-scoped real-time event dispatch. */
         this._ssePipeCallbacks = new Map();
-        // Persistence properties for automatic reconnection
+        // Desired state model — replaces old flag soup
+        this._desiredState = 'detached';
+        this._authenticated = false;
         this._persist = false;
-        this._manualDisconnect = false;
         this._currentReconnectDelay = 250;
-        /** True after onConnected has been invoked; used to only invoke onDisconnected when we had a connection. */
-        this._didNotifyConnected = false;
+        /** Reference-counted monitor subscriptions: keyString → Map<eventType, refCount> */
+        this._monitorKeys = new Map();
         // Store connection details and environment
+        this._wsPath = config.wsPath;
         this._setUri(uri);
-        this._setAuth(auth);
+        this._setAuth(auth ?? '');
         this._env = clientEnv;
         // Set up callbacks if provided
         if (onEvent)
@@ -305,9 +318,11 @@ export class RocketRideClient extends DAPClient {
             this._callerOnDisconnected = onDisconnected;
         if (onConnectError)
             this._callerOnConnectError = onConnectError;
+        if (config.onTrace)
+            this._onTrace = config.onTrace;
         // Set up persistence options
         this._persist = persist ?? false;
-        this._maxRetryTime = maxRetryTime;
+        // maxRetryTime accepted for backward compat but ignored (linear backoff never gives up)
     }
     /**
      * Normalize a user-provided URI into a fully-formed HTTP/HTTPS URL.
@@ -325,7 +340,16 @@ export class RocketRideClient extends DAPClient {
         }
         try {
             const url = new URL(normalized);
-            if (!url.port && !url.hostname.includes('rocketride.ai')) {
+            // The URL API silently strips ports that are default-for-scheme
+            // (e.g. :443 on https, :80 on http), so url.port alone cannot
+            // distinguish "no port given" from "scheme-default port given".
+            // Check the raw input for an explicit `:digits` after the scheme.
+            const withoutScheme = normalized.replace(/^[a-zA-Z][a-zA-Z\d+\-.]*:\/\//, '');
+            const authority = withoutScheme.split(/[/?#]/, 1)[0] ?? '';
+            const hasExplicitPort = authority.startsWith('[')
+                ? /\]:\d+$/.test(authority) // IPv6 literal with explicit port
+                : /:\d+$/.test(authority); // hostname/IPv4 with explicit port
+            if (!url.port && !hasExplicitPort && !url.hostname.includes('rocketride.ai')) {
                 url.port = CONST_DEFAULT_WEB_PORT;
             }
             return `${url.protocol}//${url.host}`;
@@ -334,19 +358,57 @@ export class RocketRideClient extends DAPClient {
             return normalized;
         }
     }
+    /**
+     * Probe a server for its capabilities without authenticating.
+     *
+     * Creates a temporary public connection and sends an
+     * ``rrext_public_probe`` command. The server responds with version,
+     * capabilities, platform, and public apps without requiring credentials.
+     *
+     * @param uri - Server URI (e.g. ``"localhost:5565"``, ``"https://cloud.rocketride.ai"``)
+     * @param timeout - Optional timeout in ms for the entire operation
+     * @returns Server info including version and capability tags
+     * @throws Error if the server is unreachable or does not support probes
+     *
+     * @example
+     * ```typescript
+     * const info = await RocketRideClient.getServerInfo('localhost:5565');
+     * if (info.capabilities.includes('saas')) {
+     *   // Show cloud sign-in options
+     * }
+     * ```
+     */
+    static async getServerInfo(uri, timeout) {
+        const client = new RocketRideClient({ uri, persist: false });
+        try {
+            // Open a public connection (no auth handshake)
+            await client.attach(uri, { timeout });
+            // Send rrext_public_probe — allowed on unauthenticated connections
+            const message = client.buildRequest('rrext_public_probe', {});
+            const response = await client.request(message, timeout);
+            if (response.success === false) {
+                throw new Error(response.message || 'Server info request failed');
+            }
+            return (response.body ?? {});
+        }
+        finally {
+            await client.disconnect();
+        }
+    }
     /**
      * Normalize a user-provided URI into a fully-formed WebSocket address.
      * Builds on normalizeUri, then converts to ws/wss and appends /task/service.
      */
     _getWebsocketUri(uri) {
         const httpUrl = RocketRideClient.normalizeUri(uri);
+        const path = this._wsPath ?? '/task/service';
         try {
             const url = new URL(httpUrl);
-            const wsScheme = (url.protocol === 'https:' || url.protocol === 'wss:') ? 'wss:' : 'ws:';
-            return `${wsScheme}//${url.host}/task/service`;
+            const wsScheme = url.protocol === 'https:' || url.protocol === 'wss:' ? 'wss:' : 'ws:';
+            return `${wsScheme}//${url.host}${path}`;
         }
         catch {
-            return `${httpUrl}/task/service`;
+            return `${httpUrl}${path}`;
         }
     }
     /**
@@ -361,182 +423,318 @@ export class RocketRideClient extends DAPClient {
     _setAuth(auth) {
         this._apikey = auth;
     }
-    /**
-     * Clear any pending reconnection timeout.
-     */
-    _clearReconnectTimeout() {
-        if (this._reconnectTimeout) {
-            clearTimeout(this._reconnectTimeout);
-            this._reconnectTimeout = undefined;
-        }
-    }
     // ============================================================================
-    // CONNECTION METHODS
+    // INTERNAL CONNECTION HELPERS
     // ============================================================================
     /**
-     * Single place for physical connection. Creates transport if needed, then
-     * calls DAPClient.connect (transport connect + auth handshake + onConnected).
+     * Create transport if needed and open the WebSocket. No auth.
      */
-    async _internalConnect(timeout) {
+    async _internalAttach(timeout) {
         if (!this._transport) {
-            const transport = new TransportWebSocket(this._uri, this._apikey);
+            const transport = new TransportWebSocket(this._uri);
             this._bindTransport(transport);
         }
-        await super.connect(timeout);
+        await super._dapConnect(timeout);
+    }
+    /**
+     * Send the ``auth`` DAP command over the open transport.
+     * Sets ``_authenticated`` and ``_connectResult`` on success.
+     * Throws ``AuthenticationException`` on failure (transport stays open).
+     */
+    async _internalLogin(timeout) {
+        // Build auth args with credential + client identification
+        const authArgs = { auth: this._apikey ?? '' };
+        if (this._clientDisplayName)
+            authArgs.clientName = this._clientDisplayName;
+        if (this._clientDisplayVersion)
+            authArgs.clientVersion = this._clientDisplayVersion;
+        const resp = await this.request({ type: 'request', command: 'auth', seq: 0, arguments: authArgs }, timeout);
+        const success = resp.success;
+        if (!success) {
+            throw new AuthenticationException(resp);
+        }
+        this._connectResult = resp.body;
+        this._authenticated = true;
+        // Store userToken for future reconnects
+        if (this._connectResult?.userToken) {
+            this._apikey = this._connectResult.userToken;
+        }
+        // Resubscribe monitors and notify
+        await this._resubscribeAllMonitors();
+        const connectionInfo = this._transport?.getConnectionInfo() ?? '';
+        if (this._callerOnConnected) {
+            try {
+                await this._callerOnConnected(connectionInfo);
+            }
+            catch (e) {
+                this.debugMessage(`Error in user onConnected handler: ${e}`);
+            }
+        }
+        await super.onConnected(connectionInfo);
+        return this._connectResult;
     }
     /**
-     * Single place for physical disconnect. Closes the transport directly,
-     * which triggers onDisconnected via the transport callback.
+     * Send the ``deauth`` DAP command to revert to unauthenticated.
      */
-    async _internalDisconnect(reason, hasError) {
+    async _internalLogout() {
+        if (!this._authenticated || !this._transport?.isConnected())
+            return;
+        try {
+            await this.request({ type: 'request', command: 'deauth', seq: 0, arguments: {} });
+        }
+        catch {
+            // Best-effort — server may have already disconnected
+        }
+        this._connectResult = undefined;
+        this._authenticated = false;
+    }
+    /**
+     * Close the transport. Triggers onDisconnected via the transport callback.
+     */
+    async _internalDisconnect() {
         if (!this._transport)
             return;
-        await this._transport.disconnect(reason, hasError);
+        await this._transport.disconnect();
     }
     /**
-     * Try to connect; on auth error notify and stop; on other error notify and
-     * reschedule with exponential backoff. Used by persist-mode connect() and
-     * by the reconnect timer.
+     * Clear the reconnect timer if active.
      */
-    async _attemptConnection(timeout) {
-        try {
-            await this._internalConnect(timeout);
-            this._reconnectTimeout = undefined;
-            this.debugMessage('Connection successful');
+    _clearReconnectTimer() {
+        if (this._reconnectTimer) {
+            clearTimeout(this._reconnectTimer);
+            this._reconnectTimer = undefined;
         }
-        catch (error) {
-            const err = error instanceof Error ? error : new Error(String(error));
-            this.debugMessage(`Connection failed: ${err}`);
-            await this.onConnectError(err);
-            if (error instanceof AuthenticationException) {
-                return;
-            }
-            if (this._retryStartTime === undefined) {
-                this._retryStartTime = Date.now();
+    }
+    /**
+     * Reconnect engine driven by ``_desiredState``.
+     *
+     * Schedules a timer that re-attaches (and re-logins if the user had
+     * been authenticated). Checks ``_desiredState`` after every await so
+     * user actions mid-reconnect are respected immediately.
+     *
+     * Linear backoff: 250ms → 500ms → ... → 15 000ms cap.
+     */
+    _scheduleReconnect() {
+        this.debugMessage(`Scheduling reconnect in ${this._currentReconnectDelay}ms`);
+        this._reconnectTimer = setTimeout(async () => {
+            try {
+                // Re-attach transport
+                await this._internalAttach();
+                if (this._desiredState === 'detached') {
+                    this._reconnectTimer = undefined;
+                    return;
+                }
+                // Re-login if the user was authenticated
+                if (this._desiredState === 'authenticated') {
+                    await this._internalLogin();
+                    if (this._desiredState === 'detached') {
+                        this._reconnectTimer = undefined;
+                        return;
+                    }
+                }
+                // Success — reset backoff
+                this._reconnectTimer = undefined;
+                this._currentReconnectDelay = 250;
+                this.debugMessage('Reconnect successful');
             }
-            if (this._maxRetryTime !== undefined) {
-                if (Date.now() - this._retryStartTime >= this._maxRetryTime) {
+            catch (err) {
+                // User changed intent — stop (desiredState may have been changed by detach() during await)
+                if (this._desiredState === 'detached') {
+                    this._reconnectTimer = undefined;
+                    return;
+                }
+                // Auth rejected — downgrade to attached, stop retrying auth
+                if (err instanceof AuthenticationException) {
+                    this._desiredState = 'attached';
+                    this._reconnectTimer = undefined;
+                    await this.onConnectError(err);
                     return;
                 }
+                // Transient failure — linear backoff, cap at 15s
+                this._currentReconnectDelay = Math.min(this._currentReconnectDelay + 250, 15000);
+                const error = err instanceof Error ? err : new Error(String(err));
+                await this.onConnectError(error);
+                this._scheduleReconnect(); // replaces timer with new delay
             }
-            this._currentReconnectDelay = Math.min(this._currentReconnectDelay * 2, 2500);
-            this._scheduleReconnect();
-        }
+        }, this._currentReconnectDelay);
     }
+    // ============================================================================
+    // PUBLIC API — TRANSPORT
+    // ============================================================================
     /**
-     * Schedule a reconnection attempt with exponential backoff.
+     * Attach to a RocketRide server (open WebSocket, no auth).
+     *
+     * If ``uri`` is provided and differs from the current URI, detaches
+     * first. If already attached to the same URI, this is a no-op.
+     *
+     * After attach, public APIs (``rrext_public_*``) are available.
+     *
+     * @param uri - Server URI override. Updates the stored URI if provided.
+     * @param options - Optional timeout for the WebSocket handshake.
      */
-    _scheduleReconnect() {
-        this._clearReconnectTimeout();
-        if (this._maxRetryTime !== undefined && this._retryStartTime !== undefined) {
-            if (Date.now() - this._retryStartTime >= this._maxRetryTime) {
-                this.onConnectError(new Error('Max retry time exceeded'));
-                return;
+    async attach(uri, options) {
+        // URI change → detach first, then update
+        if (uri) {
+            const normalised = this._getWebsocketUri(uri);
+            if (normalised !== this._uri) {
+                if (this.isAttached())
+                    await this.detach();
+                this._setUri(uri);
             }
         }
-        this.debugMessage(`Scheduling reconnection in ${this._currentReconnectDelay}ms`);
-        this._reconnectTimeout = setTimeout(async () => {
-            if (this._persist && !this._manualDisconnect) {
-                this.debugMessage('Attempting to reconnect...');
-                await this._attemptConnection();
-            }
-        }, this._currentReconnectDelay);
+        // Already attached → no-op
+        if (this.isAttached()) {
+            this._desiredState = this._desiredState === 'detached' ? 'attached' : this._desiredState;
+            return;
+        }
+        this._desiredState = 'attached';
+        await this._internalAttach(options?.timeout);
     }
     /**
-     * Check if the client is currently connected to the RocketRide server.
+     * Detach from the server (close WebSocket, cancel reconnection).
+     *
+     * Sets ``_desiredState`` to ``'detached'`` so the reconnect engine
+     * stops and ``onDisconnected`` does not restart it.
      */
-    isConnected() {
+    async detach() {
+        this._desiredState = 'detached';
+        this._clearReconnectTimer();
+        this._authenticated = false;
+        this._connectResult = undefined;
+        if (this._transport?.isConnected()) {
+            await this._internalDisconnect();
+        }
+    }
+    /**
+     * True when the WebSocket transport is connected (regardless of auth).
+     */
+    isAttached() {
         return this._transport?.isConnected() || false;
     }
+    // ============================================================================
+    // PUBLIC API — AUTH
+    // ============================================================================
     /**
-     * Connect to the RocketRide server.
+     * Authenticate over an attached transport.
      *
-     * Must be called before executing pipelines or other operations.
-     * In persist mode, enables automatic reconnection on disconnect and on initial failure
-     * (calls onConnectError on each failed attempt and keeps retrying).
-     * @param options - Optional timeout (number) or connection parameters object with uri, auth, and timeout.
+     * If ``uri`` is provided and differs, detaches and re-attaches first.
+     * If ``auth`` is provided and differs from the current credential,
+     * logs out (best-effort) before logging in with the new credential.
+     * If already authenticated with the same credential, this is a no-op.
+     *
+     * @param credential - API key, rr_ token, or PKCE code object.
+     * @param options - Optional URI override and/or timeout.
+     * @returns ConnectResult with user identity on success.
+     * @throws AuthenticationException on auth failure (transport stays attached).
      */
-    async connect(options) {
-        let uri;
-        let auth;
-        let timeout;
-        if (typeof options === 'number') {
-            timeout = options;
-        }
-        else if (options) {
-            ({ uri, auth, timeout } = options);
+    async login(credential, options) {
+        // Resolve credential
+        let resolvedCredential;
+        if (credential && typeof credential === 'object') {
+            resolvedCredential = 'cd_' + btoa(JSON.stringify(credential));
         }
-        // Apply optional overrides so they're used for this connect
-        if (uri !== undefined) {
-            this._setUri(uri);
-        }
-        if (auth !== undefined) {
-            this._setAuth(auth);
+        else {
+            const envKey = this._env['ROCKETRIDE_APIKEY'];
+            const envCredential = typeof envKey === 'string' && envKey.trim() !== '' ? envKey : undefined;
+            resolvedCredential = credential ?? envCredential ?? this._apikey ?? '';
+        }
+        // URI change → detach + re-attach
+        if (options?.uri) {
+            const normalised = this._getWebsocketUri(options.uri);
+            if (normalised !== this._uri) {
+                await this.detach();
+                this._setUri(options.uri);
+                await this._internalAttach(options.timeout);
+            }
         }
-        this._manualDisconnect = false;
-        this._currentReconnectDelay = 250;
-        this._retryStartTime = undefined;
-        // If already connected, disconnect first without setting _manualDisconnect
-        if (this.isConnected()) {
-            await this._internalDisconnect();
+        // Ensure attached
+        if (!this.isAttached()) {
+            await this._internalAttach(options?.timeout);
         }
-        if (this._persist) {
-            this._clearReconnectTimeout();
-            await this._attemptConnection(timeout);
+        // Auth change → logout first (best-effort)
+        if (resolvedCredential !== this._apikey && this._authenticated) {
+            try {
+                await this._internalLogout();
+            }
+            catch { }
         }
-        else {
-            await this._internalConnect(timeout);
+        this._setAuth(resolvedCredential);
+        // Already authenticated with same credential → no-op
+        if (this._authenticated) {
+            this._desiredState = 'authenticated';
+            return this._connectResult ?? {};
         }
+        this._desiredState = 'authenticated';
+        return this._internalLogin(options?.timeout);
     }
     /**
-     * Disconnect from the RocketRide server and stop automatic reconnection.
+     * Deauthenticate: sends ``deauth`` to the server, clears client auth state.
+     * The transport stays attached — public APIs continue to work.
+     */
+    async logout() {
+        await this._internalLogout();
+        this._desiredState = 'attached';
+    }
+    /**
+     * True when the auth handshake has succeeded on the current connection.
+     */
+    isAuthenticated() {
+        return this._authenticated;
+    }
+    // ============================================================================
+    // COMPAT API — connect() / disconnect()
+    // ============================================================================
+    /**
+     * Check if the client is currently connected to the RocketRide server.
+     * Equivalent to ``isAttached()`` — kept for backward compatibility.
+     */
+    isConnected() {
+        return this.isAttached();
+    }
+    /**
+     * Connect to the RocketRide server and authenticate in a single call.
+     *
+     * Backward-compatible wrapper around ``attach()`` + ``login()``.
+     * Sends the credential as the first DAP message and returns the full
+     * ConnectResult (user identity + organizations + teams) on success.
      *
-     * Should be called when finished with the client to clean up resources.
+     * @param credential - API key / Zitadel access_token / rr_ user token / PKCE code object.
+     * @param options - Optional overrides: uri and/or timeout.
      */
-    async disconnect() {
-        this._manualDisconnect = true;
-        this._clearReconnectTimeout();
-        if (this._transport && this.isConnected()) {
-            await this._internalDisconnect();
-        }
+    async connect(credential, options) {
+        this._currentReconnectDelay = 250;
+        await this.attach(options?.uri, { timeout: options?.timeout });
+        return this.login(credential, options);
     }
     /**
-     * Update server URI and/or auth at runtime. If currently connected,
-     * disconnects and reconnects with the new params. In persist mode,
-     * reconnection is scheduled only if we were connected.
+     * Get the ConnectResult from the last successful connect().
+     * Returns undefined if not connected or not yet authenticated.
      */
-    async setConnectionParams(options) {
-        if (options.uri !== undefined) {
-            this._setUri(options.uri);
-        }
-        if (options.auth !== undefined) {
-            this._setAuth(options.auth);
-        }
-        const wasAlreadyConnected = this.isConnected();
-        this._manualDisconnect = true;
-        this._clearReconnectTimeout();
-        if (wasAlreadyConnected) {
-            await this._internalDisconnect();
-        }
-        // Destroy transport so next connect() creates a new one with updated uri/auth (CONNECTION_LOGIC.md §2c)
-        if (options.uri !== undefined || options.auth !== undefined) {
-            this._transport = undefined;
-        }
-        if (this._persist && wasAlreadyConnected) {
-            this._manualDisconnect = false;
-            this._scheduleReconnect();
-        }
-        else if (wasAlreadyConnected) {
-            this._manualDisconnect = false;
-            await this._internalConnect();
-        }
-        else {
-            this._manualDisconnect = false;
-        }
+    getAccountInfo() {
+        return this._connectResult;
+    }
+    /**
+     * Returns the ID of the user's primary organization.
+     */
+    getOrgId() {
+        return this._connectResult?.organizations?.[0]?.id;
+    }
+    /**
+     * Disconnect from the RocketRide server and stop automatic reconnection.
+     * Backward-compatible wrapper around ``logout()`` + ``detach()``.
+     */
+    async disconnect() {
+        await this.logout();
+        await this.detach();
     }
+    /**
+     * Update the environment variables used for pipeline substitution.
+     *
+     * The env dictionary is used by {@link use} and {@link validate} to replace
     // ============================================================================
     // PING METHODS
     // ============================================================================
+
     /**
      * Test connectivity to the RocketRide server.
      *
@@ -545,59 +743,16 @@ export class RocketRideClient extends DAPClient {
      * and measuring response times.
      */
     async ping(token) {
-        // Build ping request
-        const request = this.buildRequest('rrext_ping', { token });
-        // Send to server and wait for response
-        const response = await this.request(request);
-        // Check if ping failed
-        if (this.didFail(response)) {
-            const errorMsg = response.message || 'Ping failed';
-            throw new Error(`Ping failed: ${errorMsg}`);
+        try {
+            await this.call('rrext_ping', undefined, { token });
+        }
+        catch (err) {
+            throw new Error(`Ping failed: ${err instanceof Error ? err.message : err}`);
         }
     }
     // ============================================================================
     // EXECUTION METHODS
     // ============================================================================
-    /**
-     * Substitute environment variables in a string.
-     * Replaces ${ROCKETRIDE_*} patterns with values from client's env dictionary.
-     * If variable is not found, leaves it unchanged.
-     */
-    substituteEnvVars(value) {
-        // Match ${ROCKETRIDE_*} patterns
-        return value.replace(/\$\{(ROCKETRIDE_[^}]+)\}/g, (match, varName) => {
-            // Check if variable exists in client's env
-            if (varName in this._env) {
-                return String(this._env[varName]);
-            }
-            // If not found, leave as is
-            return match;
-        });
-    }
-    /**
-     * Recursively process an object/array to substitute environment variables.
-     * Only processes string values, leaving other types unchanged.
-     */
-    processEnvSubstitution(obj) {
-        if (typeof obj === 'string') {
-            // If it's a string, perform substitution
-            return this.substituteEnvVars(obj);
-        }
-        else if (Array.isArray(obj)) {
-            // If it's an array, process each element
-            return obj.map(item => this.processEnvSubstitution(item));
-        }
-        else if (obj !== null && typeof obj === 'object') {
-            // If it's an object, process each property
-            const result = {};
-            for (const [key, value] of Object.entries(obj)) {
-                result[key] = this.processEnvSubstitution(value);
-            }
-            return result;
-        }
-        // For other types (number, boolean, null), return as is
-        return obj;
-    }
     /**
      * Load Node.js fs/promises at runtime without static imports.
      * This keeps browser bundles free of Node built-ins while preserving Node features.
@@ -657,19 +812,16 @@ export class RocketRideClient extends DAPClient {
      */
     async validate(options) {
         const { pipeline, source } = options;
-        const arguments_ = { pipeline };
+        const args = { pipeline };
         if (source !== undefined) {
-            arguments_.source = source;
+            args.source = source;
         }
-        const request = this.buildRequest('rrext_validate', {
-            arguments: arguments_
-        });
-        const response = await this.request(request);
-        if (this.didFail(response)) {
-            const errorMsg = response.message || 'Validation failed';
-            throw new Error(`Pipeline validation failed: ${errorMsg}`);
+        try {
+            return await this.call('rrext_validate', args);
+        }
+        catch (err) {
+            throw new Error(`Pipeline validation failed: ${err instanceof Error ? err.message : err}`);
         }
-        return response.body || {};
     }
     // ============================================================================
     // PIPELINE EXECUTION METHODS
@@ -718,7 +870,7 @@ export class RocketRideClient extends DAPClient {
      * ```
      */
     async use(options = {}) {
-        const { token, filepath, pipeline, source, threads, useExisting, args, ttl, pipelineTraceLevel } = options;
+        const { token, filepath, pipeline, source, threads, useExisting, args, ttl, pipelineTraceLevel, name, env, teamId } = options;
         // Validate required parameters
         if (!pipeline && !filepath) {
             throw new Error('Pipeline configuration or file path is required and must be specified');
@@ -741,9 +893,7 @@ export class RocketRideClient extends DAPClient {
             pipelineConfig = pipeline;
         }
         // Create a deep copy of the pipeline config to avoid modifying the original
-        let processedConfig = JSON.parse(JSON.stringify(pipelineConfig));
-        // Perform environment variable substitution on the pipeline configuration
-        processedConfig = this.processEnvSubstitution(processedConfig);
+        const processedConfig = JSON.parse(JSON.stringify(pipelineConfig));
         // Override source if specified (after substitution)
         if (source !== undefined) {
             processedConfig.source = source;
@@ -770,54 +920,135 @@ export class RocketRideClient extends DAPClient {
         if (pipelineTraceLevel !== undefined) {
             arguments_.pipelineTraceLevel = pipelineTraceLevel;
         }
+        // Build ROCKETRIDE_* env from client's .env + caller overrides
+        const rocketEnv = {};
+        for (const [k, v] of Object.entries(this._env)) {
+            if (k.startsWith('ROCKETRIDE_'))
+                rocketEnv[k] = v;
+        }
+        if (env)
+            Object.assign(rocketEnv, env);
+        if (Object.keys(rocketEnv).length > 0) {
+            arguments_.env = rocketEnv;
+        }
+        // Derive display name from filepath if not explicitly provided
+        const effectiveName = name ?? (filepath ? filepath.replace(/^.*[\\/]/, '').replace(/\.pipe(?:\.json)?$/, '') : undefined);
+        if (effectiveName !== undefined) {
+            arguments_.name = effectiveName;
+        }
+        if (teamId !== undefined) {
+            arguments_.teamId = teamId;
+        }
         // Send execution request to server
-        const request = this.buildRequest('execute', { arguments: arguments_ });
-        const response = await this.request(request);
-        // Check for execution errors
-        if (this.didFail(response)) {
-            const errorMsg = response.message || 'Unknown execution error';
-            this.debugMessage(`Pipeline execution failed: ${errorMsg}`);
-            throw new Error(errorMsg);
+        try {
+            const body = await this.call('execute', arguments_);
+            // Extract and validate response
+            const responseBody = body || {};
+            const taskToken = responseBody.token;
+            if (!taskToken) {
+                throw new Error('Server did not return a task token in successful response');
+            }
+            this.debugMessage(`Pipeline execution started successfully, task token: ${taskToken}`);
+            // Type assertion to ensure token is present
+            return responseBody;
         }
-        // Extract and validate response
-        const responseBody = response.body || {};
-        const taskToken = responseBody.token;
-        if (!taskToken) {
-            throw new Error('Server did not return a task token in successful response');
+        catch (err) {
+            const errorMsg = err instanceof Error ? err.message : String(err);
+            this.debugMessage(`Pipeline execution failed: ${errorMsg}`);
+            throw err;
         }
-        this.debugMessage(`Pipeline execution started successfully, task token: ${taskToken}`);
-        // Type assertion to ensure token is present
-        return responseBody;
     }
     /**
      * Terminate a running pipeline.
      */
     async terminate(token) {
-        // Send termination request
-        const request = this.buildRequest('terminate', { token });
-        const response = await this.request(request);
-        // Check for termination errors
-        if (this.didFail(response)) {
-            const errorMsg = response.message || 'Unknown termination error';
+        try {
+            await this.call('terminate', undefined, { token });
+        }
+        catch (err) {
+            const errorMsg = err instanceof Error ? err.message : String(err);
             this.debugMessage(`Pipeline termination failed: ${errorMsg}`);
             throw new Error(errorMsg);
         }
     }
+    /**
+     * Restart a running pipeline with a new configuration.
+     *
+     * Looks up the existing task by project/source, terminates it, and
+     * starts a new execution in one server round-trip.
+     *
+     * @param options.token - Existing task token (optional, resolved server-side if omitted).
+     * @param options.projectId - The project identifier.
+     * @param options.source - The source component identifier.
+     * @param options.pipeline - The pipeline configuration to restart with.
+     */
+    async restart(options) {
+        try {
+            await this.call('restart', {
+                token: options.token,
+                projectId: options.projectId,
+                source: options.source,
+                pipeline: options.pipeline,
+            }, { token: '*' });
+        }
+        catch (err) {
+            const errorMsg = err instanceof Error ? err.message : String(err);
+            this.debugMessage(`Pipeline restart failed: ${errorMsg}`);
+            throw new Error(errorMsg);
+        }
+    }
     /**
      * Get the current status of a running pipeline.
+     *
+     * By default this call is bounded to 15s so callers/tests don't hang forever if the engine
+     * stops responding mid-request (especially important in CI). Pass `{ timeout: false }` to
+     * restore the previous behavior of using only the client-level request timeout (if any).
      */
-    async getTaskStatus(token) {
-        // Send status request
-        const request = this.buildRequest('rrext_get_task_status', { token });
-        const response = await this.request(request);
-        // Check for status retrieval errors
-        if (this.didFail(response)) {
-            const errorMsg = response.message || 'Unknown status retrieval error';
+    async getTaskStatus(token, options) {
+        try {
+            const callOptions = { token };
+            if (options?.timeout === false) {
+                // Intentionally omit per-call timeout override.
+            }
+            else {
+                callOptions.timeout = options?.timeout ?? 15000;
+            }
+            return await this.call('rrext_get_task_status', undefined, callOptions);
+        }
+        catch (err) {
+            const errorMsg = err instanceof Error ? err.message : String(err);
             this.debugMessage(`Pipeline status retrieval failed: ${errorMsg}`);
             throw new Error(errorMsg);
         }
-        // Return status information
-        return response.body || {};
+    }
+    /**
+     * Resolve a running task's token from its project ID and source component.
+     *
+     * The token is required for operations like terminate and restart.
+     * Returns undefined if no task is currently running for the given project/source.
+     *
+     * @param options.projectId - The project identifier.
+     * @param options.source - The source component identifier.
+     */
+    async getTaskToken(options) {
+        const body = await this.call('rrext_get_token', {
+            projectId: options.projectId,
+            source: options.source,
+        });
+        return body?.token;
+    }
+    /**
+     * Returns the unresolved pipeline for a running task.
+     *
+     * The pipeline is returned exactly as stored — ${ROCKETRIDE_*} placeholders are
+     * NOT substituted, so no secrets are included in the response.
+     *
+     * @param token - Task token returned by {@link getTaskToken}.
+     * @returns The unresolved pipeline dict, or undefined if the task is not found.
+     */
+    async getTaskPipeline(token) {
+        const body = await this.call('rrext_get_pipeline', undefined, { token });
+        return body?.pipeline;
     }
     // ============================================================================
     // DATA METHODS
@@ -912,7 +1143,7 @@ export class RocketRideClient extends DAPClient {
                 event: 'apaevt_status_upload',
                 body: body,
                 seq: 0,
-                type: 'event'
+                type: 'event',
             };
             this.onEvent(eventMessage);
         };
@@ -1004,7 +1235,7 @@ export class RocketRideClient extends DAPClient {
             results[index] = finalResult;
         };
         // Create a promise for every file - let server handle queuing
-        const uploadPromises = files.map((fileData, index) => uploadFile(fileData, index).catch(err => {
+        const uploadPromises = files.map((fileData, index) => uploadFile(fileData, index).catch((err) => {
             // Ensure errors don't kill the whole batch
             console.error(`Upload failed for ${fileData.file.name}:`, err);
         }));
@@ -1106,6 +1337,13 @@ export class RocketRideClient extends DAPClient {
         const seqNum = message.seq || 0;
         // Forward to debugging interface if available
         this._sendVSCodeEvent(eventType, eventBody);
+        // Update cached ConnectResult when the server pushes a full account refresh
+        if (eventType === 'apaext_account') {
+            this._connectResult = eventBody;
+            if (this._connectResult?.userToken) {
+                this._apikey = this._connectResult.userToken;
+            }
+        }
         // Dispatch pipe-scoped SSE events to the registered DataPipe callback
         if (eventType === 'apaevt_sse') {
             const pipeId = eventBody?.pipe_id;
@@ -1142,7 +1380,8 @@ export class RocketRideClient extends DAPClient {
     async onConnectError(error) {
         if (this._callerOnConnectError) {
             try {
-                await this._callerOnConnectError(error instanceof Error ? error.message : String(error));
+                const connectionError = error instanceof ConnectionException ? error : new ConnectionException({ message: String(error) });
+                await this._callerOnConnectError(connectionError);
             }
             catch (e) {
                 this.debugMessage(`Error in user onConnectError handler: ${e}`);
@@ -1151,564 +1390,697 @@ export class RocketRideClient extends DAPClient {
         await super.onConnectError(error);
     }
     /**
-     * Handle connected events from the RocketRide server.
+     * Handle transport-level connected event.
+     *
+     * With the attach/login split, this fires when the WebSocket opens
+     * (before auth). The ``_internalLogin`` method handles the auth
+     * notification separately, so this is intentionally minimal.
      */
     async onConnected(connectionInfo) {
-        this._manualDisconnect = false;
-        this._didNotifyConnected = true;
-        this._clearReconnectTimeout();
-        this._currentReconnectDelay = 250;
-        this._retryStartTime = undefined;
-        // Call user-provided event handler if available
-        if (this._callerOnConnected) {
-            try {
-                await this._callerOnConnected(connectionInfo);
-            }
-            catch (error) {
-                // Log errors but don't let user code break the connection
-                this.debugMessage(`Error in user onConnected handler for ${connectionInfo}: ${error}`);
-            }
-        }
         await super.onConnected(connectionInfo);
     }
     /**
-     * Handle disconnected events from the RocketRide server.
-     * Only invokes the user's onDisconnected if onConnected had previously been called
-     * (so "disconnect without ever connecting" does not fire the user callback).
+     * Handle transport disconnection.
+     *
+     * Clears transport and auth state, notifies the user callback,
+     * then consults ``_desiredState`` to decide whether to reconnect.
      */
     async onDisconnected(reason, hasError) {
-        if (this._didNotifyConnected) {
-            this._didNotifyConnected = false;
-            if (this._callerOnDisconnected) {
-                try {
-                    await this._callerOnDisconnected(reason, hasError);
-                }
-                catch (error) {
-                    // Log errors but don't let user code break the connection
-                    this.debugMessage(`Error in user onDisconnected handler for ${reason}: ${error}`);
-                }
+        // Transport is gone — clear so next attach creates a fresh one
+        this._transport = undefined;
+        this._connectResult = undefined;
+        this._authenticated = false;
+        // Notify user callback
+        if (this._callerOnDisconnected) {
+            try {
+                await this._callerOnDisconnected(reason, hasError);
+            }
+            catch (error) {
+                this.debugMessage(`Error in user onDisconnected handler for ${reason}: ${error}`);
             }
-            // Chain to parent to clear pending requests
-            await super.onDisconnected(reason, hasError);
         }
-        // Schedule reconnection if persist is enabled and not a manual disconnect
-        if (this._persist && !this._manualDisconnect) {
-            this._scheduleReconnect();
+        // Chain to parent to clear pending requests
+        await super.onDisconnected(reason, hasError);
+        // Reconnect engine: honour _desiredState
+        if (this._desiredState === 'detached')
+            return;
+        if (!this._persist) {
+            this._desiredState = 'detached';
+            return;
         }
+        if (this._reconnectTimer)
+            return; // engine already active
+        this._currentReconnectDelay = 250;
+        this._scheduleReconnect();
     }
     /**
      * Subscribe to specific types of events from the server.
+     * @deprecated Use {@link addMonitor} / {@link removeMonitor} instead.
      */
     async setEvents(token, eventTypes, pipeId) {
-        // Build event subscription request
+        // Build event subscription args
         const args = { types: eventTypes };
         if (pipeId !== undefined)
             args.pipeId = pipeId;
-        const request = this.buildRequest('rrext_monitor', {
-            arguments: args,
-            token,
-        });
-        // Send to server
-        const response = await this.request(request);
-        // Check for errors
-        if (this.didFail(response)) {
-            const errorMsg = response.message || 'Event subscription failed';
-            throw new Error(errorMsg);
+        try {
+            await this.call('rrext_monitor', args, { token });
+        }
+        catch (err) {
+            throw new Error(`Event subscription failed: ${err instanceof Error ? err.message : err}`);
         }
     }
     // ============================================================================
-    // PROJECT STORAGE MANAGEMENT
+    // MONITOR SUBSCRIPTION MANAGEMENT
     // ============================================================================
     /**
-     * Save or update a project pipeline.
+     * Add a monitor subscription. If the key already exists, the new types are
+     * merged via reference counting and the merged set is sent to the server.
      *
-     * Stores a project pipeline configuration on the server. If the project
-     * already exists, it will be updated. Use expectedVersion to ensure
-     * you're updating the version you expect (prevents conflicts).
-     *
-     * @param options - Save project options
-     * @param options.projectId - Unique identifier for the project
-     * @param options.pipeline - Pipeline configuration object
-     * @param options.expectedVersion - Expected current version for atomic updates (optional)
-     * @returns Promise resolving to save result with success status, projectId, and new version
-     * @throws Error if save fails due to version mismatch, storage error, or invalid input
-     *
-     * @example
-     * ```typescript
-     * // Save a new project
-     * const result = await client.saveProject({
-     *   projectId: 'proj-123',
-     *   pipeline: {
-     *     name: 'Data Processor',
-     *     source: 'source_1',
-     *     components: [...]
-     *   }
-     * });
-     * console.log(`Saved version: ${result.version}`);
-     *
-     * // Update existing project with version check
-     * const existing = await client.getProject({ projectId: 'proj-123' });
-     * existing.name = 'Updated Name';
-     * const updated = await client.saveProject({
-     *   projectId: 'proj-123',
-     *   pipeline: existing,
-     *   expectedVersion: existing.version
-     * });
-     * ```
+     * @param key - Monitor key: `{ token }` for a running task, or `{ projectId, source }` for a project.
+     * @param types - Event types to subscribe to (e.g. `['summary', 'flow']`).
      */
-    async saveProject(options) {
-        const { projectId, pipeline, expectedVersion } = options;
-        // Validate inputs
-        if (!projectId) {
-            throw new Error('projectId is required');
-        }
-        if (!pipeline || typeof pipeline !== 'object') {
-            throw new Error('pipeline must be a non-empty object');
+    async addMonitor(key, types) {
+        const keyStr = this._monitorKeyToString(key);
+        let refCounts = this._monitorKeys.get(keyStr);
+        if (!refCounts) {
+            refCounts = new Map();
+            this._monitorKeys.set(keyStr, refCounts);
+        }
+        // Increment reference counts
+        for (const t of types) {
+            refCounts.set(t, (refCounts.get(t) ?? 0) + 1);
+        }
+        // Send merged types to server — rollback on failure
+        try {
+            await this._syncMonitor(key, refCounts);
         }
-        // Build request arguments
-        const args = {
-            subcommand: 'save_project',
-            projectId,
-            pipeline,
-        };
-        // Add optional version for atomic updates
-        if (expectedVersion !== undefined) {
-            args.expectedVersion = expectedVersion;
-        }
-        // Send request to server
-        const request = this.buildRequest('rrext_store', { arguments: args });
-        const response = await this.request(request);
-        // Check for errors
-        if (this.didFail(response)) {
-            const errorMsg = response.message || 'Unknown error saving project';
-            this.debugMessage(`Project save failed: ${errorMsg}`);
-            throw new Error(errorMsg);
+        catch (error) {
+            for (const t of types) {
+                const current = refCounts.get(t) ?? 0;
+                if (current <= 1) {
+                    refCounts.delete(t);
+                }
+                else {
+                    refCounts.set(t, current - 1);
+                }
+            }
+            if (refCounts.size === 0) {
+                this._monitorKeys.delete(keyStr);
+            }
+            throw error;
         }
-        // Extract and return response
-        this.debugMessage(`Project saved successfully: ${projectId}, version: ${response.body?.version}`);
-        return response.body;
     }
     /**
-     * Retrieve a project by its ID.
-     *
-     * Fetches the complete pipeline configuration and current version for
-     * the specified project. Use this before updating to get the current
-     * version for atomic updates.
-     *
-     * @param options - Get project options
-     * @param options.projectId - Unique identifier of the project to retrieve
-     * @returns Promise resolving to project data with success status, pipeline, and version
-     * @throws Error if project doesn't exist or retrieval fails
-     *
-     * @example
-     * ```typescript
-     * // Get a project
-     * try {
-     *   const project = await client.getProject({ projectId: 'proj-123' });
-     *   console.log(`Project: ${project.name}`);
-     *   console.log(`Version: ${project.version}`);
-     * } catch (error) {
-     *   if (error.message.includes('NOT_FOUND')) {
-     *     console.log("Project doesn't exist");
-     *   }
-     * }
+     * Remove a monitor subscription. Decrements reference counts for the given
+     * types. Only unsubscribes a type from the server when its count reaches 0.
      *
-     * // Before updating - get current version
-     * const project = await client.getProject({ projectId: 'proj-123' });
-     * project.name = 'Updated';
-     * await client.saveProject({
-     *   projectId: 'proj-123',
-     *   pipeline: project,
-     *   expectedVersion: project.version
-     * });
-     * ```
+     * @param key - Monitor key (must match the key used in addMonitor).
+     * @param types - Event types to unsubscribe from.
      */
-    async getProject(options) {
-        const { projectId } = options;
-        // Validate inputs
-        if (!projectId) {
-            throw new Error('projectId is required');
+    async removeMonitor(key, types) {
+        const keyStr = this._monitorKeyToString(key);
+        const refCounts = this._monitorKeys.get(keyStr);
+        if (!refCounts)
+            return;
+        // Decrement reference counts
+        for (const t of types) {
+            const current = refCounts.get(t) ?? 0;
+            if (current <= 1) {
+                refCounts.delete(t);
+            }
+            else {
+                refCounts.set(t, current - 1);
+            }
         }
-        // Build request
-        const args = {
-            subcommand: 'get_project',
-            projectId,
-        };
-        // Send request to server
-        const request = this.buildRequest('rrext_store', { arguments: args });
-        const response = await this.request(request);
-        // Check for errors
-        if (this.didFail(response)) {
-            const errorMsg = response.message || 'Unknown error retrieving project';
-            this.debugMessage(`Project retrieval failed: ${errorMsg}`);
-            throw new Error(errorMsg);
+        // Send merged types (or unsubscribe if empty)
+        await this._syncMonitor(key, refCounts);
+        // Clean up empty keys
+        if (refCounts.size === 0) {
+            this._monitorKeys.delete(keyStr);
         }
-        // Extract and return response
-        this.debugMessage(`Project retrieved successfully: ${projectId}`);
-        return response.body;
     }
     /**
-     * Delete a project by its ID.
-     *
-     * Permanently removes a project from storage. Optionally verify the
-     * version before deletion to ensure you're deleting the version you
-     * expect (prevents accidental deletion of modified projects).
-     *
-     * @param options - Delete project options
-     * @param options.projectId - Unique identifier of the project to delete
-     * @param options.expectedVersion - Expected current version for atomic deletion (required)
-     * @returns Promise resolving to deletion result with success status and message
-     * @throws Error if project doesn't exist, version mismatch, or deletion fails
-     *
-     * @example
-     * ```typescript
-     * // Safe deletion with version check
-     * const project = await client.getProject({ projectId: 'proj-123' });
-     * try {
-     *   const result = await client.deleteProject({
-     *     projectId: 'proj-123',
-     *     expectedVersion: project.version
-     *   });
-     *   console.log('Project deleted successfully');
-     * } catch (error) {
-     *   if (error.message.includes('CONFLICT')) {
-     *     console.log('Project was modified, deletion cancelled');
-     *   }
-     * }
-     * ```
+     * Send the merged type list for a monitor key to the server.
      */
-    async deleteProject(options) {
-        const { projectId, expectedVersion } = options;
-        // Validate inputs
-        if (!projectId) {
-            throw new Error('projectId is required');
+    async _syncMonitor(key, refCounts) {
+        if (!this.isConnected())
+            return;
+        const mergedTypes = Array.from(refCounts.keys());
+        if ('token' in key) {
+            await this.call('rrext_monitor', { types: mergedTypes }, { token: key.token });
         }
-        // Build request
-        const args = {
-            subcommand: 'delete_project',
-            projectId,
-        };
-        // Add optional version for atomic deletion
-        if (expectedVersion !== undefined) {
-            args.expectedVersion = expectedVersion;
-        }
-        // Send request to server
-        const request = this.buildRequest('rrext_store', { arguments: args });
-        const response = await this.request(request);
-        // Check for errors
-        if (this.didFail(response)) {
-            const errorMsg = response.message || 'Unknown error deleting project';
-            this.debugMessage(`Project deletion failed: ${errorMsg}`);
-            throw new Error(errorMsg);
+        else {
+            const args = {
+                projectId: key.projectId,
+                source: key.source,
+                types: mergedTypes,
+            };
+            if (key.pipeId !== undefined) {
+                args.pipeId = key.pipeId;
+            }
+            await this.call('rrext_monitor', args);
         }
-        // Extract and return response
-        this.debugMessage(`Project deleted successfully: ${projectId}`);
-        return response.body;
     }
     /**
-     * List all projects for the current user.
-     *
-     * Retrieves a summary of all projects stored for the authenticated user.
-     * Each project summary includes the ID, name, list of data sources, and total component count.
-     *
-     * @returns Promise resolving to list result with success status, projects array, and count
-     * @throws Error if retrieval fails
-     *
-     * @example
-     * ```typescript
-     * // List all projects
-     * const result = await client.getAllProjects();
-     * console.log(`Found ${result.count} projects:`);
-     * for (const project of result.projects) {
-     *   console.log(`- ${project.id}: ${project.name} (${project.totalComponents} components)`);
-     *   for (const source of project.sources) {
-     *     console.log(`  * ${source.name} (${source.provider})`);
-     *   }
-     * }
-     *
-     * // Find specific project
-     * const result = await client.getAllProjects();
-     * const myProject = result.projects.find(p => p.id === 'proj-123');
-     * ```
+     * Replay all active monitor subscriptions to the server.
+     * Called automatically after reconnection.
      */
-    async getAllProjects() {
-        // Build request
-        const args = {
-            subcommand: 'get_all_projects',
-        };
-        // Send request to server
-        const request = this.buildRequest('rrext_store', { arguments: args });
-        const response = await this.request(request);
-        // Check for errors
-        if (this.didFail(response)) {
-            const errorMsg = response.message || 'Unknown error listing projects';
-            this.debugMessage(`Project list retrieval failed: ${errorMsg}`);
-            throw new Error(errorMsg);
+    async _resubscribeAllMonitors() {
+        for (const [keyStr, refCounts] of this._monitorKeys) {
+            if (refCounts.size === 0)
+                continue;
+            const key = this._monitorStringToKey(keyStr);
+            if (key) {
+                try {
+                    await this._syncMonitor(key, refCounts);
+                }
+                catch (error) {
+                    this.debugMessage(`Failed to resubscribe monitor ${keyStr}: ${error}`);
+                }
+            }
+        }
+    }
+    /**
+     * Convert a MonitorKey to a stable string for map lookup.
+     */
+    _monitorKeyToString(key) {
+        if ('token' in key) {
+            return `t:${key.token}`;
         }
-        // Extract and return response
-        const projectCount = response.body?.count || 0;
-        this.debugMessage(`Projects retrieved successfully: ${projectCount} projects`);
-        return response.body;
+        let s = `p:${key.projectId}.${key.source}`;
+        if (key.pipeId !== undefined) {
+            s += `.${key.pipeId}`;
+        }
+        return s;
+    }
+    /**
+     * Reverse a key-string back to a MonitorKey (for resubscribeAll).
+     */
+    _monitorStringToKey(keyStr) {
+        if (keyStr.startsWith('t:')) {
+            return { token: keyStr.slice(2) };
+        }
+        if (keyStr.startsWith('p:')) {
+            const rest = keyStr.slice(2);
+            const dotIdx = rest.indexOf('.');
+            if (dotIdx === -1)
+                return null;
+            const projectId = rest.slice(0, dotIdx);
+            const remaining = rest.slice(dotIdx + 1);
+            const parts = remaining.split('.');
+            if (parts.length === 2 && !isNaN(Number(parts[1]))) {
+                return { projectId, source: parts[0], pipeId: Number(parts[1]) };
+            }
+            return { projectId, source: remaining };
+        }
+        return null;
     }
     // ============================================================================
-    // TEMPLATE STORAGE MANAGEMENT (System-wide templates)
+    // TEMPLATE STORAGE MANAGEMENT (convenience wrappers using fsReadJson/fsWriteJson)
     // ============================================================================
     /**
-     * Save or update a template pipeline.
+     * Persist a pipeline configuration as a named template in the account store.
      *
-     * Stores a template pipeline configuration on the server. Templates are system-wide
-     * and accessible to all users. If the template already exists, it will be updated.
-     * Use expectedVersion to ensure you're updating the version you expect.
+     * Templates are stored as JSON files under `.templates/<templateId>.json`.
+     * Saving a template with an existing ID overwrites the previous version.
      *
-     * @param options - Save template options
-     * @param options.templateId - Unique identifier for the template
-     * @param options.pipeline - Pipeline configuration object
-     * @param options.expectedVersion - Expected current version for atomic updates (optional)
-     * @returns Promise resolving to save result with success status, templateId, and new version
-     * @throws Error if save fails due to version mismatch, storage error, or invalid input
+     * @param options.templateId - Unique identifier for the template (no path separators)
+     * @param options.pipeline - Pipeline configuration object to save
+     * @throws Error if templateId is invalid or pipeline is not a non-empty object
      */
     async saveTemplate(options) {
-        const { templateId, pipeline, expectedVersion } = options;
-        // Validate inputs
-        if (!templateId) {
-            throw new Error('templateId is required');
-        }
-        if (!pipeline || typeof pipeline !== 'object') {
+        // Validate the template ID to prevent path traversal or invalid filenames
+        this.validateId(options.templateId, 'templateId');
+        // Ensure the pipeline payload is a non-null object before writing
+        if (!options.pipeline || typeof options.pipeline !== 'object')
             throw new Error('pipeline must be a non-empty object');
-        }
-        // Build request arguments
-        const args = {
-            subcommand: 'save_template',
-            templateId,
-            pipeline,
-        };
-        // Add optional version for atomic updates
-        if (expectedVersion !== undefined) {
-            args.expectedVersion = expectedVersion;
-        }
-        // Send request to server
-        const request = this.buildRequest('rrext_store', { arguments: args });
-        const response = await this.request(request);
-        // Check for errors
-        if (this.didFail(response)) {
-            const errorMsg = response.message || 'Unknown error saving template';
-            this.debugMessage(`Template save failed: ${errorMsg}`);
-            throw new Error(errorMsg);
-        }
-        // Extract and return response
-        this.debugMessage(`Template saved successfully: ${templateId}, version: ${response.body?.version}`);
-        return response.body;
+        // Serialise and write the pipeline under the .templates virtual directory
+        await this.fsWriteJson(`.templates/${options.templateId}.json`, options.pipeline);
     }
     /**
-     * Retrieve a template by its ID.
+     * Retrieve a previously saved pipeline template from the account store.
+     *
+     * @param options.templateId - Unique identifier of the template to retrieve
+     * @returns The pipeline configuration object that was saved
+     * @throws Error if the template does not exist or templateId is invalid
      */
     async getTemplate(options) {
-        const { templateId } = options;
-        // Validate inputs
-        if (!templateId) {
-            throw new Error('templateId is required');
-        }
-        // Build request
-        const args = {
-            subcommand: 'get_template',
-            templateId,
-        };
-        // Send request to server
-        const request = this.buildRequest('rrext_store', { arguments: args });
-        const response = await this.request(request);
-        // Check for errors
-        if (this.didFail(response)) {
-            const errorMsg = response.message || 'Unknown error retrieving template';
-            this.debugMessage(`Template retrieval failed: ${errorMsg}`);
-            throw new Error(errorMsg);
-        }
-        // Extract and return response
-        this.debugMessage(`Template retrieved successfully: ${templateId}`);
-        return response.body;
+        // Validate the ID before constructing the storage path
+        this.validateId(options.templateId, 'templateId');
+        // Read and parse the JSON file from the .templates virtual directory
+        return this.fsReadJson(`.templates/${options.templateId}.json`);
     }
     /**
-     * Delete a template by its ID.
+     * Delete a pipeline template from the account store.
+     *
+     * @param options.templateId - Unique identifier of the template to delete
+     * @throws Error if the template does not exist or templateId is invalid
      */
     async deleteTemplate(options) {
-        const { templateId, expectedVersion } = options;
-        // Validate inputs
-        if (!templateId) {
-            throw new Error('templateId is required');
-        }
-        // Build request
-        const args = {
-            subcommand: 'delete_template',
-            templateId,
-        };
-        // Add optional version for atomic deletion
-        if (expectedVersion !== undefined) {
-            args.expectedVersion = expectedVersion;
-        }
-        // Send request to server
-        const request = this.buildRequest('rrext_store', { arguments: args });
-        const response = await this.request(request);
-        // Check for errors
-        if (this.didFail(response)) {
-            const errorMsg = response.message || 'Unknown error deleting template';
-            this.debugMessage(`Template deletion failed: ${errorMsg}`);
-            throw new Error(errorMsg);
-        }
-        // Extract and return response
-        this.debugMessage(`Template deleted successfully: ${templateId}`);
-        return response.body;
+        // Validate the ID before constructing the storage path
+        this.validateId(options.templateId, 'templateId');
+        // Delete the JSON file from the .templates virtual directory
+        await this.fsDelete(`.templates/${options.templateId}.json`);
     }
     /**
-     * List all templates.
+     * List all pipeline templates stored in the account store.
+     *
+     * Reads the `.templates` directory, parses each `.json` file, and extracts
+     * a summary for each template. Files that cannot be parsed are silently
+     * skipped so a single corrupt template does not break the entire listing.
+     *
+     * @returns Array of template summaries sorted in directory-listing order.
+     *          Each entry contains the template ID, display name, source components,
+     *          and total component count.
      */
     async getAllTemplates() {
-        // Build request
-        const args = {
-            subcommand: 'get_all_templates',
-        };
-        // Send request to server
-        const request = this.buildRequest('rrext_store', { arguments: args });
-        const response = await this.request(request);
-        // Check for errors
-        if (this.didFail(response)) {
-            const errorMsg = response.message || 'Unknown error listing templates';
-            this.debugMessage(`Template list retrieval failed: ${errorMsg}`);
-            throw new Error(errorMsg);
+        // Fetch the list of entries under the .templates virtual directory
+        const dir = await this.fsListDir('.templates');
+        const templates = [];
+        for (const entry of dir.entries) {
+            // Skip directories and any non-JSON files (e.g. temp files)
+            if (entry.type !== 'file' || !entry.name.endsWith('.json'))
+                continue;
+            try {
+                // Derive the template ID by stripping the .json extension
+                const id = entry.name.slice(0, -5);
+                // Load and parse the template JSON
+                const pipeline = await this.fsReadJson(`.templates/${entry.name}`);
+                // Extract Source-mode components to populate the sources summary list
+                const sources = (pipeline.components || []).filter((c) => c.config?.mode === 'Source').map((c) => ({ id: c.id, provider: c.provider, name: c.config?.name || c.id }));
+                // Push the summary (use template ID as display name)
+                templates.push({ id, name: id, sources, totalComponents: (pipeline.components || []).length });
+            }
+            catch (err) {
+                // Log the failure but continue so one bad file doesn't block others
+                console.debug(`[RocketRideClient] Failed to read .templates/${entry.name}:`, err);
+                continue;
+            }
         }
-        // Extract and return response
-        const templateCount = response.body?.count || 0;
-        this.debugMessage(`Templates retrieved successfully: ${templateCount} templates`);
-        return response.body;
+        return templates;
     }
     // ============================================================================
-    // LOG STORAGE MANAGEMENT (Per-project log files for historical tracking)
+    // LOG STORAGE MANAGEMENT (convenience wrappers using fsReadJson/fsWriteJson)
     // ============================================================================
     /**
-     * Save a log file for a source run.
+     * Persist a pipeline execution log to the account store.
+     *
+     * Logs are stored under `.logs/<projectId>/<source>-<startTime>.log`.
+     * The filename is derived from `contents.body.startTime` so logs are
+     * naturally sortable by execution start time.
+     *
+     * @param options.projectId - Project identifier that owns this log
+     * @param options.source - Source component identifier the log is associated with
+     * @param options.contents - Log payload; must contain `body.startTime`
+     * @returns The generated filename (e.g. `"ingest-1714000000000.log"`)
+     * @throws Error if any ID is invalid, contents is not an object, or startTime is missing
      */
     async saveLog(options) {
-        const { projectId, source, contents } = options;
-        // Validate inputs
-        if (!projectId) {
-            throw new Error('projectId is required');
-        }
-        if (!source) {
-            throw new Error('source is required');
-        }
-        if (!contents || typeof contents !== 'object') {
+        // Validate identifiers to prevent path traversal
+        this.validateId(options.projectId, 'projectId');
+        this.validateId(options.source, 'source');
+        // Ensure the contents payload is a non-null object
+        if (!options.contents || typeof options.contents !== 'object')
             throw new Error('contents must be a non-empty object');
-        }
-        // Build request arguments
-        const args = {
-            subcommand: 'save_log',
-            projectId,
-            source,
-            contents,
-        };
-        // Send request to server
-        const request = this.buildRequest('rrext_store', { arguments: args });
-        const response = await this.request(request);
-        // Check for errors
-        if (this.didFail(response)) {
-            const errorMsg = response.message || 'Unknown error saving log';
-            this.debugMessage(`Log save failed: ${errorMsg}`);
-            throw new Error(errorMsg);
-        }
-        // Extract and return response
-        this.debugMessage(`Log saved successfully: ${response.body?.filename}`);
-        return response.body;
+        // startTime is required; it forms part of the filename for chronological ordering.
+        // Reject anything other than a non-empty number or numeric-looking string to
+        // prevent path-separator chars from slipping into the generated filename.
+        const startTime = options.contents?.body?.startTime;
+        if (startTime === undefined || startTime === null)
+            throw new Error('contents must contain body.startTime');
+        if (typeof startTime !== 'number' && typeof startTime !== 'string') {
+            throw new Error('contents.body.startTime must be a number or string');
+        }
+        const startTimeStr = String(startTime);
+        if (!startTimeStr || /[\\/]/.test(startTimeStr)) {
+            throw new Error('contents.body.startTime must not be empty or contain path separators');
+        }
+        // Construct a deterministic filename from source and start time
+        const filename = `${options.source}-${startTimeStr}.log`;
+        // Write the log JSON to the per-project logs directory
+        await this.fsWriteJson(`.logs/${options.projectId}/${filename}`, options.contents);
+        return filename;
     }
     /**
-     * Get a log file by source name and start time.
+     * Retrieve a previously saved pipeline execution log from the account store.
+     *
+     * @param options.projectId - Project identifier that owns the log
+     * @param options.name - Filename of the log (as returned by saveLog)
+     * @returns The log payload that was saved
+     * @throws Error if the log does not exist or projectId is invalid
      */
     async getLog(options) {
-        const { projectId, source, startTime } = options;
-        // Validate inputs
-        if (!projectId) {
-            throw new Error('projectId is required');
-        }
-        if (!source) {
-            throw new Error('source is required');
-        }
-        if (startTime === undefined || startTime === null) {
-            throw new Error('startTime is required');
-        }
-        // Build request
-        const args = {
-            subcommand: 'get_log',
-            projectId,
-            source,
-            startTime,
-        };
-        // Send request to server
-        const request = this.buildRequest('rrext_store', { arguments: args });
-        const response = await this.request(request);
-        // Check for errors
-        if (this.didFail(response)) {
-            const errorMsg = response.message || 'Unknown error retrieving log';
-            this.debugMessage(`Log retrieval failed: ${errorMsg}`);
-            throw new Error(errorMsg);
-        }
-        // Extract and return response
-        this.debugMessage(`Log retrieved successfully: ${projectId}/${source}`);
-        return response.body;
+        // Validate the project ID before constructing the storage path
+        this.validateId(options.projectId, 'projectId');
+        if (!options.name)
+            throw new Error('name is required');
+        // Read and parse the log JSON from the per-project logs directory
+        return this.fsReadJson(`.logs/${options.projectId}/${options.name}`);
     }
     /**
-     * List log files for a project.
+     * Delete a pipeline execution log from the account store.
+     *
+     * @param options.projectId - Project identifier that owns the log
+     * @param options.name - Filename of the log to delete
+     * @throws Error if the log does not exist or projectId is invalid
+     */
+    async deleteLog(options) {
+        // Validate the project ID before constructing the storage path
+        this.validateId(options.projectId, 'projectId');
+        if (!options.name)
+            throw new Error('name is required');
+        // Delete the log file from the per-project logs directory
+        await this.fsDelete(`.logs/${options.projectId}/${options.name}`);
+    }
+    /**
+     * List pipeline execution logs stored for a project, optionally filtered by source.
+     *
+     * Results are sorted ascending by `modified` timestamp so the oldest log
+     * appears first. The caller can page through or slice the array as needed.
+     *
+     * @param options.projectId - Project identifier whose logs to list
+     * @param options.source - Optional source component filter; when set, only logs
+     *                         whose filename starts with `<source>-` are returned
+     * @returns Array of log name and optional modified timestamp, sorted oldest-first
+     * @throws Error if projectId (or source when provided) is invalid
      */
     async listLogs(options) {
-        const { projectId, source, page } = options;
-        // Validate inputs
-        if (!projectId) {
-            throw new Error('projectId is required');
-        }
-        // Build request
-        const args = {
-            subcommand: 'list_logs',
-            projectId,
-        };
-        // Add optional parameters
-        if (source !== undefined) {
-            args.source = source;
+        // Validate identifiers before constructing the storage path
+        this.validateId(options.projectId, 'projectId');
+        if (options.source)
+            this.validateId(options.source, 'source');
+        // List all entries in the per-project logs directory
+        const dir = await this.fsListDir(`.logs/${options.projectId}`);
+        // Keep only .log files and map to the public shape (name + modified)
+        let logs = dir.entries.filter((e) => e.type === 'file' && e.name.endsWith('.log')).map((e) => ({ name: e.name, modified: e.modified }));
+        // Apply optional source prefix filter when a source was specified
+        if (options.source) {
+            logs = logs.filter((l) => l.name.startsWith(`${options.source}-`));
+        }
+        // Sort ascending by modified timestamp; treat missing timestamps as epoch 0
+        logs.sort((a, b) => (a.modified || 0) - (b.modified || 0));
+        return logs;
+    }
+    // ============================================================================
+    // HANDLE-BASED FILE STORE OPERATIONS
+    // ============================================================================
+    /**
+     * Open a file handle for reading or writing.
+     *
+     * @param path - Relative path within the account store
+     * @param mode - 'r' for read, 'w' for write (default: 'r')
+     * @param offset - Initial byte offset (read mode only)
+     * @returns Object with 'handle' (string). Read mode also includes 'size' (number).
+     */
+    async fsOpen(path, mode = 'r') {
+        this.validateStorePath(path);
+        return this.call('rrext_store', { subcommand: 'fs_open', path, mode });
+    }
+    /**
+     * Read data from an open read handle.
+     *
+     * @param handle - Handle ID returned by fsOpen
+     * @param offset - Byte offset to read from
+     * @param length - Max bytes to read (default 4 MB). Empty Uint8Array indicates EOF.
+     * @returns The bytes read
+     */
+    async fsRead(handle, offset = 0, length = 4194304) {
+        // Bypass call() which unwraps response.body, losing response.arguments
+        // where the server places the binary data payload.
+        const message = this.buildRequest('rrext_store', {
+            arguments: { subcommand: 'fs_read', handle, offset, length },
+        });
+        this._onTrace?.(TraceType.Request, message);
+        const response = await this.request(message);
+        if (response.success === false) {
+            this._onTrace?.(TraceType.Error, response);
+            throw new Error(response.message ?? 'fs_read failed');
+        }
+        this._onTrace?.(TraceType.Success, response);
+        return response.arguments?.data || new Uint8Array(0);
+    }
+    /**
+     * Write data to an open write handle.
+     *
+     * @param handle - Handle ID returned by fsOpen
+     * @param data - Raw bytes to write
+     * @returns Number of bytes written
+     */
+    async fsWrite(handle, data) {
+        const body = await this.call('rrext_store', { subcommand: 'fs_write', handle, data });
+        return body?.bytesWritten ?? 0;
+    }
+    /**
+     * Close a file handle.
+     *
+     * @param handle - Handle ID returned by fsOpen
+     * @param mode - 'r' or 'w' (must match the mode used in fsOpen)
+     */
+    async fsClose(handle, mode) {
+        await this.call('rrext_store', { subcommand: 'fs_close', handle, mode });
+    }
+    /**
+     * Delete a file.
+     *
+     * @param path - Relative path within the account store
+     * @throws Error if file does not exist or delete fails
+     */
+    async fsDelete(path) {
+        this.validateStorePath(path);
+        await this.call('rrext_store', { subcommand: 'fs_delete', path });
+    }
+    /**
+     * List immediate children of a directory.
+     *
+     * @param path - Relative directory path (default: account root)
+     * @returns Directory entries with name and type (file or dir)
+     */
+    async fsListDir(path = '') {
+        if (path)
+            this.validateStorePath(path);
+        return this.call('rrext_store', { subcommand: 'fs_list_dir', path });
+    }
+    /**
+     * Create a directory.
+     *
+     * @param path - Relative directory path
+     */
+    async fsMkdir(path) {
+        this.validateStorePath(path);
+        await this.call('rrext_store', { subcommand: 'fs_mkdir', path });
+    }
+    /**
+     * Remove a directory.
+     *
+     * @param path - Relative directory path
+     * @param recursive - If true, delete contents recursively (default: false)
+     * @throws Error if directory is not empty (when recursive is false) or delete fails
+     */
+    async fsRmdir(path, recursive = false) {
+        this.validateStorePath(path);
+        await this.call('rrext_store', { subcommand: 'fs_rmdir', path, recursive });
+    }
+    /**
+     * Get file or directory metadata.
+     *
+     * @param path - Relative path within the account store
+     * @returns Metadata including existence, type, size (bytes), and modified epoch timestamp (for files)
+     */
+    async fsStat(path) {
+        this.validateStorePath(path);
+        return this.call('rrext_store', { subcommand: 'fs_stat', path });
+    }
+    /**
+     * Rename a file or directory.
+     *
+     * On object stores this is implemented as copy + delete. For directories,
+     * all contents are moved recursively.
+     *
+     * @param oldPath - Current relative path within the account store
+     * @param newPath - New relative path within the account store
+     * @throws Error if oldPath does not exist or rename fails
+     */
+    async fsRename(oldPath, newPath) {
+        this.validateStorePath(oldPath);
+        this.validateStorePath(newPath);
+        await this.call('rrext_store', { subcommand: 'fs_rename', old_path: oldPath, new_path: newPath });
+    }
+    // ============================================================================
+    // CONVENIENCE WRAPPERS (text/JSON over binary, handle open/close internally)
+    // ============================================================================
+    /** Read a file as a UTF-8 string. */
+    async fsReadString(path) {
+        const { handle } = await this.fsOpen(path, 'r');
+        try {
+            const chunks = [];
+            let offset = 0;
+            while (true) {
+                const chunk = await this.fsRead(handle, offset);
+                if (chunk.length === 0)
+                    break;
+                chunks.push(chunk);
+                offset += chunk.length;
+            }
+            const total = new Uint8Array(offset);
+            let pos = 0;
+            for (const chunk of chunks) {
+                total.set(chunk, pos);
+                pos += chunk.length;
+            }
+            return new TextDecoder().decode(total);
         }
-        if (page !== undefined) {
-            args.page = page;
+        finally {
+            await this.fsClose(handle, 'r');
         }
-        // Send request to server
-        const request = this.buildRequest('rrext_store', { arguments: args });
-        const response = await this.request(request);
-        // Check for errors
-        if (this.didFail(response)) {
-            const errorMsg = response.message || 'Unknown error listing logs';
-            this.debugMessage(`Log list retrieval failed: ${errorMsg}`);
-            throw new Error(errorMsg);
+    }
+    /** Write a UTF-8 string to a file. */
+    async fsWriteString(path, text) {
+        const { handle } = await this.fsOpen(path, 'w');
+        try {
+            await this.fsWrite(handle, new TextEncoder().encode(text));
+            await this.fsClose(handle, 'w');
+        }
+        catch (err) {
+            try {
+                await this.fsClose(handle, 'w');
+            }
+            catch {
+                /* best-effort */
+            }
+            throw err;
+        }
+    }
+    /** Read a JSON file. */
+    async fsReadJson(path) {
+        const text = await this.fsReadString(path);
+        return JSON.parse(text);
+    }
+    /** Write an object as JSON. */
+    async fsWriteJson(path, obj) {
+        await this.fsWriteString(path, JSON.stringify(obj, null, 2));
+    }
+    /**
+     * Validate a relative path intended for the account file store.
+     *
+     * Splits the path on `/` (after normalising backslashes) and checks every
+     * segment for path-traversal attempts (`..`) and forbidden characters.
+     * Empty segments (from leading/trailing/double slashes) are skipped because
+     * they carry no security risk on the server side.
+     *
+     * @param path - Relative path to validate (e.g. `.templates/my-pipe.json`)
+     * @throws Error if any segment is `..` or contains illegal characters
+     */
+    validateStorePath(path) {
+        // Normalise Windows-style backslashes to forward slashes before splitting
+        for (const segment of path.replace(/\\/g, '/').split('/')) {
+            // Reject parent-directory traversal attempts in any position of the path
+            if (segment === '..')
+                throw new Error(`Path traversal not allowed: ${path}`);
+            // Only validate non-empty segments (empty ones arise from leading/trailing slashes)
+            if (segment) {
+                for (const ch of segment) {
+                    // Reject forbidden metacharacters and ASCII control characters (< 0x20)
+                    if (RocketRideClient.INVALID_PATH_CHARS.has(ch) || ch.charCodeAt(0) < 0x20) {
+                        throw new Error(`Path contains invalid characters: ${path}`);
+                    }
+                }
+            }
+        }
+    }
+    /**
+     * Validate a single identifier (projectId, source, templateId, etc.) used
+     * to construct store paths.
+     *
+     * IDs must be non-empty strings that contain no path separators and no
+     * characters from the forbidden set. This prevents an ID from escaping its
+     * intended directory when interpolated into a path.
+     *
+     * @param value - The identifier string to validate
+     * @param name - Human-readable field name used in error messages (e.g. `"projectId"`)
+     * @throws Error if value is empty, contains path separators, or contains illegal characters
+     */
+    validateId(value, name) {
+        // Require a non-empty value
+        if (!value)
+            throw new Error(`${name} is required`);
+        // Reject forward and backward slashes to prevent path injection
+        if (value.includes('/') || value.includes('\\'))
+            throw new Error(`${name} must not contain path separators`);
+        // Reject any forbidden metacharacter or ASCII control character
+        for (const ch of value) {
+            if (RocketRideClient.INVALID_PATH_CHARS.has(ch) || ch.charCodeAt(0) < 0x20) {
+                throw new Error(`${name} contains invalid characters: ${value}`);
+            }
         }
-        // Extract and return response
-        const logCount = response.body?.total_count || 0;
-        this.debugMessage(`Logs retrieved successfully: ${logCount} logs`);
-        return response.body;
     }
     // ============================================================================
-    // RAW REQUEST METHOD
+    // DASHBOARD METHODS
     // ============================================================================
     /**
-     * Send an arbitrary DAP command with command name, arguments, and optional token.
+     * Retrieve a server dashboard snapshot.
      *
-     * This is a convenience method for callers that don't want to construct
-     * full DAPMessage objects. It builds the request internally and delegates
-     * to the underlying request() method.
+     * Returns the current state of all connections, tasks, and aggregate
+     * metrics from the server. Requires 'task.monitor' permission.
      *
-     * @param command - The DAP command name (e.g., 'rrext_services', 'rrext_monitor')
-     * @param args - Optional arguments for the command
-     * @param token - Optional task/session token
-     * @param timeout - Optional per-request timeout in ms
-     * @returns The response DAPMessage from the server
+     * @returns DashboardResponse containing overview, connections, and tasks
      */
-    async dapRequest(command, args, token, timeout) {
-        const message = this.buildRequest(command, {
-            arguments: args,
-            token,
-        });
-        return await this.request(message, timeout);
+    async getDashboard() {
+        return this.call('rrext_dashboard', {});
+    }
+    // ============================================================================
+    // CPROFILE PROFILING
+    // ============================================================================
+    /**
+     * Start a cProfile profiling session on the server process or a pipeline.
+     *
+     * @param target  - Task token to profile a pipeline subprocess, or
+     *                  undefined/null to profile the server process itself.
+     * @param session - Optional human-readable session name.
+     * @returns Status object with session info and start time.
+     */
+    async cprofileStart(target, session) {
+        const args = {};
+        if (target)
+            args.target = target;
+        if (session)
+            args.session = session;
+        return this.call('rrext_cprofile_start', args);
+    }
+    /**
+     * Stop the active cProfile profiling session.
+     *
+     * @param target - Task token if profiling a pipeline, or undefined for server.
+     * @returns Result with session name and runtime.
+     */
+    async cprofileStop(target) {
+        const args = {};
+        if (target)
+            args.target = target;
+        return this.call('rrext_cprofile_stop', args);
+    }
+    /**
+     * Get the current cProfile profiling status.
+     *
+     * @param target - Task token if querying a pipeline, or undefined for server.
+     * @returns Status indicating active/inactive, owner, runtime.
+     */
+    async cprofileStatus(target) {
+        const args = {};
+        if (target)
+            args.target = target;
+        return this.call('rrext_cprofile_status', args);
+    }
+    /**
+     * Get the full cProfile report from the last completed session.
+     *
+     * @param target - Task token if querying a pipeline, or undefined for server.
+     * @returns Object containing the full pstats text report.
+     */
+    async cprofileReport(target) {
+        const args = {};
+        if (target)
+            args.target = target;
+        return this.call('rrext_cprofile_report', args);
     }
     // ============================================================================
     // CONTEXT MANAGER SUPPORT - Python-style async context manager
@@ -1727,7 +2099,7 @@ export class RocketRideClient extends DAPClient {
     static async withConnection(config, callback) {
         const client = new RocketRideClient(config);
         try {
-            await client.connect();
+            await client.connect(config.auth);
             return await callback(client);
         }
         finally {
@@ -1764,17 +2136,7 @@ export class RocketRideClient extends DAPClient {
      * ```
      */
     async getServices() {
-        // Build services request (no service argument = get all)
-        const request = this.buildRequest('rrext_services', {});
-        // Send to server and wait for response
-        const response = await this.request(request);
-        // Check if request failed
-        if (this.didFail(response)) {
-            const errorMsg = response.message || 'Failed to retrieve services';
-            throw new Error(`Failed to retrieve services: ${errorMsg}`);
-        }
-        // Return the body containing all service definitions
-        return response.body || {};
+        return this.call('rrext_services', {});
     }
     /**
      * Retrieve a specific service definition from the server.
@@ -1802,19 +2164,7 @@ export class RocketRideClient extends DAPClient {
         if (!service) {
             throw new Error('Service name is required');
         }
-        // Build services request with specific service name
-        const request = this.buildRequest('rrext_services', {
-            arguments: { service }
-        });
-        // Send to server and wait for response
-        const response = await this.request(request);
-        // Check if request failed
-        if (this.didFail(response)) {
-            const errorMsg = response.message || `Service '${service}' not found`;
-            throw new Error(`Failed to retrieve service '${service}': ${errorMsg}`);
-        }
-        // Return the body containing the service definition
-        return response.body;
+        return this.call('rrext_services', { service });
     }
     // ============================================================================
     // ADDITIONAL CONVENIENCE METHODS
@@ -1835,6 +2185,126 @@ export class RocketRideClient extends DAPClient {
     getApiKey() {
         return this._apikey;
     }
+    // ============================================================================
+    // ACCOUNT, BILLING & DEPLOY NAMESPACES
+    // ============================================================================
+    /**
+     * Lazily-initialised account API namespace.
+     *
+     * Provides typed methods for managing the authenticated user's profile,
+     * API keys, organization, members, and teams.
+     *
+     * @example
+     * ```typescript
+     * const profile = await client.account.getProfile();
+     * ```
+     */
+    get account() {
+        if (!this._account) {
+            this._account = new AccountApi(this);
+        }
+        return this._account;
+    }
+    /**
+     * Lazily-initialised billing API namespace.
+     *
+     * Provides typed methods for managing subscriptions, Stripe checkout
+     * sessions, billing portal access, and compute credit wallets.
+     *
+     * @example
+     * ```typescript
+     * const details = await client.billing.getDetails(orgId);
+     * ```
+     */
+    get billing() {
+        if (!this._billing) {
+            this._billing = new BillingApi(this);
+        }
+        return this._billing;
+    }
+    /**
+     * Lazily-initialised database API namespace.
+     *
+     * Provides direct SQL/Cypher execution against database pipelines, bypassing
+     * the LLM translation layer that {@link RocketRideClient.chat} uses.
+     *
+     * @example
+     * ```typescript
+     * const result = await client.database.query({ token, sql: 'SELECT 1' });
+     * ```
+     */
+    get database() {
+        if (!this._database) {
+            this._database = new DatabaseApi(this);
+        }
+        return this._database;
+    }
+    /**
+     * Lazily-initialised deploy API namespace.
+     *
+     * Provides typed methods for managing server-side pipeline deployments:
+     * add, remove, list, status, and update.
+     *
+     * @example
+     * ```typescript
+     * const rec = await client.deploy.add(pipeline, { schedule: '0/15 * * * *' });
+     * ```
+     */
+    get deploy() {
+        if (!this._deploy) {
+            this._deploy = new DeployApi(this);
+        }
+        return this._deploy;
+    }
+    // ============================================================================
+    // CALL — PUBLIC DAP COMMAND INTERFACE
+    // ============================================================================
+    /**
+     * Sends a DAP command, unwraps the response body, and throws on failure.
+     *
+     * This is the single public entry point for all typed DAP operations.
+     * The {@link AccountApi} and {@link BillingApi} namespaces delegate here.
+     *
+     * If an `onTrace` callback was provided in the constructor config, it is
+     * invoked before the request (TraceType.Request) and after completion
+     * (TraceType.Success or TraceType.Error).
+     *
+     * @param command - DAP command name (e.g. "rrext_account_me").
+     * @param args    - Key/value arguments forwarded in the request.
+     * @param options - Optional token (for task-scoped calls) and timeout in ms.
+     * @returns The `body` field of a successful DAP response.
+     * @throws Error if the server signals failure.
+     */
+    async call(command, args, options) {
+        // Build the raw DAP request
+        const message = this.buildRequest(command, {
+            arguments: args,
+            token: options?.token,
+        });
+        // Trace: outbound request
+        this._onTrace?.(TraceType.Request, message);
+        const response = await this.request(message, options?.timeout);
+        // Throw on server-reported failure
+        if (response.success === false) {
+            this._onTrace?.(TraceType.Error, response);
+            throw new Error(response.message ?? `${command} failed`);
+        }
+        // Trace: success response
+        this._onTrace?.(TraceType.Success, response);
+        // Unwrap the body envelope
+        return (response.body ?? response);
+    }
 }
+// ============================================================================
+// PATH AND ID VALIDATION
+// ============================================================================
+/**
+ * Characters that are illegal in store paths and IDs on all supported
+ * platforms (Windows, Linux, macOS, and object-storage back-ends).
+ *
+ * `\x00` is the null byte; the rest are shell/filesystem metacharacters
+ * that would cause ambiguous or dangerous behaviour in path construction.
+ */
+RocketRideClient.INVALID_PATH_CHARS = new Set(['*', '?', '<', '>', '|', '"', '\x00']);
 export { RocketRideClient as default };
 //# sourceMappingURL=client.js.map