@datalayer/agent-runtimes 1.0.4 → 1.0.6

package/lib/client/IAgentRuntimesClient.d.ts

@@ -0,0 +1,215 @@
+/**
+ * Domain-level interface abstracting every operation the chat component and
+ * hooks need against the Datalayer agent runtime platform.
+ *
+ * Two concrete implementations are expected:
+ *
+ * 1. `SdkAgentRuntimesClient` — the default browser / Node implementation
+ *    that delegates to a `DatalayerClient` composed with `AgentsMixin`.
+ *    Makes real HTTP calls against the configured service URLs.
+ *
+ * 2. A bridge implementation hosted inside the VSCode webview sandbox (lives
+ *    in the `vscode-datalayer` extension, not in this package). It implements
+ *    the same interface but tunnels every call to the extension host via
+ *    `postMessage` correlation IDs. The extension host answers the calls
+ *    using its own `SdkAgentRuntimesClient` so the webview never touches the
+ *    network or the auth token directly.
+ *
+ * The interface is deliberately transport-agnostic: consumers depend on
+ * semantic method names (`listRunningAgents`, `getAgentStatus`) rather
+ * than on URLs, fetch options, or WebSocket frames.
+ *
+ * @module client/IAgentRuntimesClient
+ */
+import type { AgentEvent, AgentNotification, AgentUsageSummary, ContextUsage, ConversationCheckpoint, CostUsage, CreateAgentEventRequest, EvalReport, GetAgentEventResponse, ListAgentEventsParams, ListAgentEventsResponse, NotificationFilters, OutputArtifact, RunEvalsRequest, RunningAgent, UpdateAgentEventRequest } from '../types';
+import type { CreateAgentRuntimeRequest, CreateRuntimeApiResponse } from '../types/agents-lifecycle';
+/**
+ * Unified client contract for the Datalayer agent-runtimes control plane.
+ *
+ * Every method corresponds one-to-one with an operation on
+ * `AgentsMixin`. Phase 1 of the interface covers the non-streaming
+ * surface. Streaming chat (`streamChat`), chat config, history, and related
+ * transport-specific operations will be added in a follow-up once
+ * `AgentsMixin` grows typed wrappers for them.
+ */
+export interface IAgentRuntimesClient {
+    /**
+     * Lists every running agent across all runtimes the caller can see.
+     *
+     * @returns Array of running agent summaries.
+     */
+    listRunningAgents(): Promise<RunningAgent[]>;
+    /**
+     * Retrieves the detailed status of a specific running agent.
+     *
+     * @param podName - Pod name hosting the agent.
+     * @param agentId - Optional agent ID within the pod (for multi-agent pods).
+     *
+     * @returns The agent's current status record.
+     */
+    getAgentStatus(podName: string, agentId?: string): Promise<RunningAgent>;
+    /**
+     * Pauses a running agent (light checkpoint by default).
+     *
+     * @param podName - Pod name hosting the agent.
+     */
+    pauseAgent(podName: string): Promise<void>;
+    /**
+     * Resumes a previously paused / checkpointed agent.
+     *
+     * @param podName - Pod name hosting the agent.
+     */
+    resumeAgent(podName: string): Promise<void>;
+    /**
+     * Lists conversation checkpoints for an agent.
+     *
+     * @param podName - Pod name hosting the agent.
+     * @param agentId - Optional agent ID within the pod.
+     *
+     * @returns Array of conversation checkpoints.
+     */
+    getAgentCheckpoints(podName: string, agentId?: string): Promise<ConversationCheckpoint[]>;
+    /**
+     * Retrieves the token and cost usage summary for an agent.
+     *
+     * @param podName - Pod name hosting the agent.
+     * @param agentId - Optional agent ID within the pod.
+     *
+     * @returns Aggregated usage totals.
+     */
+    getAgentUsage(podName: string, agentId?: string): Promise<AgentUsageSummary>;
+    /**
+     * Lists agent notifications, optionally filtered by level or read status.
+     *
+     * @param filters - Optional filter predicates.
+     *
+     * @returns Array of notifications matching the filters.
+     */
+    listNotifications(filters?: NotificationFilters): Promise<AgentNotification[]>;
+    /**
+     * Marks a single notification as read.
+     *
+     * @param notificationId - ID of the notification.
+     */
+    markNotificationRead(notificationId: string): Promise<void>;
+    /**
+     * Marks every notification for the caller as read.
+     */
+    markAllNotificationsRead(): Promise<void>;
+    /**
+     * Creates a new event for an agent.
+     *
+     * @param data - Event payload.
+     *
+     * @returns The created event wrapped in a success envelope.
+     */
+    createEvent(data: CreateAgentEventRequest): Promise<{
+        success: boolean;
+        event: AgentEvent;
+    }>;
+    /**
+     * Lists events for an agent with optional filters.
+     *
+     * @param agentId - Agent identifier whose events are being listed.
+     * @param params - Optional list filters (pagination, type, status).
+     *
+     * @returns Paginated events response.
+     */
+    listEvents(agentId: string, params?: Omit<ListAgentEventsParams, 'agent_id'>): Promise<ListAgentEventsResponse>;
+    /**
+     * Retrieves a single event by identifier.
+     *
+     * @param agentId - Agent that owns the event.
+     * @param eventId - Event identifier.
+     *
+     * @returns The requested event.
+     */
+    getEvent(agentId: string, eventId: string): Promise<GetAgentEventResponse>;
+    /**
+     * Patches an existing event.
+     *
+     * @param agentId - Agent that owns the event.
+     * @param eventId - Event identifier.
+     * @param data - Partial event fields to update.
+     *
+     * @returns The updated event.
+     */
+    updateEvent(agentId: string, eventId: string, data: UpdateAgentEventRequest): Promise<GetAgentEventResponse>;
+    /**
+     * Lists every output artifact an agent has generated.
+     *
+     * @param agentId - Agent identifier.
+     *
+     * @returns Array of output artifacts.
+     */
+    getAgentOutputs(agentId: string): Promise<OutputArtifact[]>;
+    /**
+     * Retrieves a single output artifact by identifier.
+     *
+     * @param agentId - Agent identifier.
+     * @param outputId - Output artifact identifier.
+     *
+     * @returns The requested output artifact.
+     */
+    getAgentOutput(agentId: string, outputId: string): Promise<OutputArtifact>;
+    /**
+     * Generates a new output artifact for an agent.
+     *
+     * @param agentId - Agent identifier.
+     * @param format - Requested output format (e.g. `"pdf"`).
+     * @param options - Optional format-specific generation options.
+     *
+     * @returns The newly generated output artifact.
+     */
+    generateAgentOutput(agentId: string, format: string, options?: Record<string, unknown>): Promise<OutputArtifact>;
+    /**
+     * Runs an evaluation batch against an agent.
+     *
+     * @param agentId - Agent identifier.
+     * @param request - Eval configuration payload.
+     *
+     * @returns Eval report capturing results and metrics.
+     */
+    runEvals(agentId: string, request: RunEvalsRequest): Promise<EvalReport>;
+    /**
+     * Lists past eval reports for an agent.
+     *
+     * @param agentId - Agent identifier.
+     *
+     * @returns Array of eval reports in reverse-chronological order.
+     */
+    listEvals(agentId: string): Promise<EvalReport[]>;
+    /**
+     * Retrieves a single eval report by identifier.
+     *
+     * @param agentId - Agent identifier.
+     * @param evalId - Eval report identifier.
+     *
+     * @returns The requested eval report.
+     */
+    getEval(agentId: string, evalId: string): Promise<EvalReport>;
+    /**
+     * Retrieves the current context window usage for an agent.
+     *
+     * @param agentId - Agent identifier.
+     *
+     * @returns Context usage details.
+     */
+    getContextUsage(agentId: string): Promise<ContextUsage>;
+    /**
+     * Retrieves the per-model cost usage for an agent.
+     *
+     * @param agentId - Agent identifier.
+     *
+     * @returns Cost usage aggregates.
+     */
+    getCostUsage(agentId: string): Promise<CostUsage>;
+    /**
+     * Creates a new agent runtime.
+     *
+     * @param data - Runtime creation parameters.
+     *
+     * @returns The creation response with the provisioned runtime descriptor.
+     */
+    createAgentRuntime(data: CreateAgentRuntimeRequest): Promise<CreateRuntimeApiResponse>;
+}

package/lib/client/IAgentRuntimesClient.js

@@ -0,0 +1,5 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+export {};

package/lib/client/SdkAgentRuntimesClient.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Default implementation of {@link IAgentRuntimesClient} that delegates to a
+ * `DatalayerClient` composed with `AgentsMixin`.
+ *
+ * This is the implementation used by browser, Node, JupyterLab, and standalone
+ * examples of the chat component. The VSCode extension provides its own
+ * implementation (`BridgeAgentRuntimesClient`) that tunnels calls through a
+ * message-passing bridge to an extension-host instance of this same class.
+ *
+ * @module client/SdkAgentRuntimesClient
+ */
+import type { AgentEvent, AgentNotification, AgentUsageSummary, ContextUsage, ConversationCheckpoint, CostUsage, CreateAgentEventRequest, EvalReport, GetAgentEventResponse, ListAgentEventsParams, ListAgentEventsResponse, NotificationFilters, OutputArtifact, RunEvalsRequest, RunningAgent, UpdateAgentEventRequest } from '../types';
+import type { CreateAgentRuntimeRequest, CreateRuntimeApiResponse } from '../types/agents-lifecycle';
+import type { IAgentRuntimesClient } from './IAgentRuntimesClient';
+/**
+ * Structural type describing the subset of methods {@link SdkAgentRuntimesClient}
+ * needs on the underlying SDK instance. Any `DatalayerClient` composed with
+ * `AgentsMixin` satisfies this shape; accepting it structurally avoids a
+ * hard type dependency on `@datalayer/core` inside this file, which keeps the
+ * default implementation drop-in replaceable in alternative deployments.
+ */
+export interface AgentsSdkLike {
+    /** Lists every running agent across runtimes the caller can see. */
+    getRunningAgents(): Promise<RunningAgent[]>;
+    /** Retrieves the detailed status of a specific running agent. */
+    getAgentStatus(podName: string, agentId?: string): Promise<RunningAgent>;
+    /** Pauses a running agent. */
+    pauseAgent(podName: string): Promise<void>;
+    /** Resumes a previously paused agent. */
+    resumeAgent(podName: string): Promise<void>;
+    /** Lists conversation checkpoints for an agent. */
+    getAgentCheckpoints(podName: string, agentId?: string): Promise<ConversationCheckpoint[]>;
+    /** Retrieves the token and cost usage summary for an agent. */
+    getAgentUsage(podName: string, agentId?: string): Promise<AgentUsageSummary>;
+    /** Lists agent notifications with optional filters. */
+    getNotifications(filters?: NotificationFilters): Promise<AgentNotification[]>;
+    /** Marks a single notification as read. */
+    markNotificationRead(notificationId: string): Promise<void>;
+    /** Marks every notification for the caller as read. */
+    markAllNotificationsRead(): Promise<void>;
+    /** Creates a new event for an agent. */
+    createEvent(data: CreateAgentEventRequest): Promise<{
+        success: boolean;
+        event: AgentEvent;
+    }>;
+    /** Lists events for an agent. */
+    listEvents(agentId: string, params?: Omit<ListAgentEventsParams, 'agent_id'>): Promise<ListAgentEventsResponse>;
+    /** Retrieves a single event. */
+    getEvent(agentId: string, eventId: string): Promise<GetAgentEventResponse>;
+    /** Updates an event. */
+    updateEvent(agentId: string, eventId: string, data: UpdateAgentEventRequest): Promise<GetAgentEventResponse>;
+    /** Lists output artifacts for an agent. */
+    getAgentOutputs(agentId: string): Promise<OutputArtifact[]>;
+    /** Retrieves a single output artifact. */
+    getAgentOutput(agentId: string, outputId: string): Promise<OutputArtifact>;
+    /** Generates a new output artifact. */
+    generateAgentOutput(agentId: string, format: string, options?: Record<string, unknown>): Promise<OutputArtifact>;
+    /** Runs an evaluation batch. */
+    runEvals(agentId: string, request: RunEvalsRequest): Promise<EvalReport>;
+    /** Lists eval reports for an agent. */
+    listEvals(agentId: string): Promise<EvalReport[]>;
+    /** Retrieves a single eval report. */
+    getEval(agentId: string, evalId: string): Promise<EvalReport>;
+    /** Retrieves context window usage. */
+    getContextUsage(agentId: string): Promise<ContextUsage>;
+    /** Retrieves cost usage. */
+    getCostUsage(agentId: string): Promise<CostUsage>;
+    /** Creates a new agent runtime. */
+    createAgentRuntime(data: CreateAgentRuntimeRequest): Promise<CreateRuntimeApiResponse>;
+}
+/**
+ * {@link IAgentRuntimesClient} implementation that forwards every call to a
+ * pre-composed `DatalayerClient + AgentsMixin` instance.
+ *
+ * Construct with:
+ *
+ * ```ts
+ * import { DatalayerClient } from '@datalayer/core/lib/client';
+ * import { AgentsMixin, SdkAgentRuntimesClient } from '@datalayer/agent-runtimes';
+ *
+ * const ClientWithAgents = AgentsMixin(DatalayerClient);
+ * const sdk = new ClientWithAgents({ iamRunUrl, runtimesRunUrl, spacerRunUrl });
+ * const client = new SdkAgentRuntimesClient(sdk);
+ * ```
+ */
+export declare class SdkAgentRuntimesClient implements IAgentRuntimesClient {
+    private readonly sdk;
+    /**
+     * Constructs the default client.
+     *
+     * @param sdk - A composed `DatalayerClient + AgentsMixin` instance whose
+     *   `getToken()` / service URL resolvers already return valid values.
+     *   When `null`, every method throws — pass a real SDK to use the client.
+     */
+    constructor(sdk: AgentsSdkLike | null);
+    /**
+     * Asserts the SDK is available for control-plane operations.
+     *
+     * @throws When the client was constructed without an SDK.
+     *
+     * @returns The SDK instance.
+     */
+    private requireSdk;
+    /** @inheritdoc */
+    listRunningAgents(): Promise<RunningAgent[]>;
+    /** @inheritdoc */
+    getAgentStatus(podName: string, agentId?: string): Promise<RunningAgent>;
+    /** @inheritdoc */
+    pauseAgent(podName: string): Promise<void>;
+    /** @inheritdoc */
+    resumeAgent(podName: string): Promise<void>;
+    /** @inheritdoc */
+    getAgentCheckpoints(podName: string, agentId?: string): Promise<ConversationCheckpoint[]>;
+    /** @inheritdoc */
+    getAgentUsage(podName: string, agentId?: string): Promise<AgentUsageSummary>;
+    /** @inheritdoc */
+    listNotifications(filters?: NotificationFilters): Promise<AgentNotification[]>;
+    /** @inheritdoc */
+    markNotificationRead(notificationId: string): Promise<void>;
+    /** @inheritdoc */
+    markAllNotificationsRead(): Promise<void>;
+    /** @inheritdoc */
+    createEvent(data: CreateAgentEventRequest): Promise<{
+        success: boolean;
+        event: AgentEvent;
+    }>;
+    /** @inheritdoc */
+    listEvents(agentId: string, params?: Omit<ListAgentEventsParams, 'agent_id'>): Promise<ListAgentEventsResponse>;
+    /** @inheritdoc */
+    getEvent(agentId: string, eventId: string): Promise<GetAgentEventResponse>;
+    /** @inheritdoc */
+    updateEvent(agentId: string, eventId: string, data: UpdateAgentEventRequest): Promise<GetAgentEventResponse>;
+    /** @inheritdoc */
+    getAgentOutputs(agentId: string): Promise<OutputArtifact[]>;
+    /** @inheritdoc */
+    getAgentOutput(agentId: string, outputId: string): Promise<OutputArtifact>;
+    /** @inheritdoc */
+    generateAgentOutput(agentId: string, format: string, options?: Record<string, unknown>): Promise<OutputArtifact>;
+    /** @inheritdoc */
+    runEvals(agentId: string, request: RunEvalsRequest): Promise<EvalReport>;
+    /** @inheritdoc */
+    listEvals(agentId: string): Promise<EvalReport[]>;
+    /** @inheritdoc */
+    getEval(agentId: string, evalId: string): Promise<EvalReport>;
+    /** @inheritdoc */
+    getContextUsage(agentId: string): Promise<ContextUsage>;
+    /** @inheritdoc */
+    getCostUsage(agentId: string): Promise<CostUsage>;
+    /** @inheritdoc */
+    createAgentRuntime(data: CreateAgentRuntimeRequest): Promise<CreateRuntimeApiResponse>;
+}

package/lib/client/SdkAgentRuntimesClient.js

@@ -0,0 +1,134 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * {@link IAgentRuntimesClient} implementation that forwards every call to a
+ * pre-composed `DatalayerClient + AgentsMixin` instance.
+ *
+ * Construct with:
+ *
+ * ```ts
+ * import { DatalayerClient } from '@datalayer/core/lib/client';
+ * import { AgentsMixin, SdkAgentRuntimesClient } from '@datalayer/agent-runtimes';
+ *
+ * const ClientWithAgents = AgentsMixin(DatalayerClient);
+ * const sdk = new ClientWithAgents({ iamRunUrl, runtimesRunUrl, spacerRunUrl });
+ * const client = new SdkAgentRuntimesClient(sdk);
+ * ```
+ */
+export class SdkAgentRuntimesClient {
+    sdk;
+    /**
+     * Constructs the default client.
+     *
+     * @param sdk - A composed `DatalayerClient + AgentsMixin` instance whose
+     *   `getToken()` / service URL resolvers already return valid values.
+     *   When `null`, every method throws — pass a real SDK to use the client.
+     */
+    constructor(sdk) {
+        this.sdk = sdk;
+    }
+    /**
+     * Asserts the SDK is available for control-plane operations.
+     *
+     * @throws When the client was constructed without an SDK.
+     *
+     * @returns The SDK instance.
+     */
+    requireSdk() {
+        if (!this.sdk) {
+            throw new Error('Control-plane operations require an SDK instance. ' +
+                'Construct SdkAgentRuntimesClient with a DatalayerClient+AgentsMixin.');
+        }
+        return this.sdk;
+    }
+    /** @inheritdoc */
+    async listRunningAgents() {
+        return this.requireSdk().getRunningAgents();
+    }
+    /** @inheritdoc */
+    async getAgentStatus(podName, agentId) {
+        return this.requireSdk().getAgentStatus(podName, agentId);
+    }
+    /** @inheritdoc */
+    async pauseAgent(podName) {
+        return this.requireSdk().pauseAgent(podName);
+    }
+    /** @inheritdoc */
+    async resumeAgent(podName) {
+        return this.requireSdk().resumeAgent(podName);
+    }
+    /** @inheritdoc */
+    async getAgentCheckpoints(podName, agentId) {
+        return this.requireSdk().getAgentCheckpoints(podName, agentId);
+    }
+    /** @inheritdoc */
+    async getAgentUsage(podName, agentId) {
+        return this.requireSdk().getAgentUsage(podName, agentId);
+    }
+    /** @inheritdoc */
+    async listNotifications(filters) {
+        return this.requireSdk().getNotifications(filters);
+    }
+    /** @inheritdoc */
+    async markNotificationRead(notificationId) {
+        return this.requireSdk().markNotificationRead(notificationId);
+    }
+    /** @inheritdoc */
+    async markAllNotificationsRead() {
+        return this.requireSdk().markAllNotificationsRead();
+    }
+    /** @inheritdoc */
+    async createEvent(data) {
+        return this.requireSdk().createEvent(data);
+    }
+    /** @inheritdoc */
+    async listEvents(agentId, params) {
+        return this.requireSdk().listEvents(agentId, params);
+    }
+    /** @inheritdoc */
+    async getEvent(agentId, eventId) {
+        return this.requireSdk().getEvent(agentId, eventId);
+    }
+    /** @inheritdoc */
+    async updateEvent(agentId, eventId, data) {
+        return this.requireSdk().updateEvent(agentId, eventId, data);
+    }
+    /** @inheritdoc */
+    async getAgentOutputs(agentId) {
+        return this.requireSdk().getAgentOutputs(agentId);
+    }
+    /** @inheritdoc */
+    async getAgentOutput(agentId, outputId) {
+        return this.requireSdk().getAgentOutput(agentId, outputId);
+    }
+    /** @inheritdoc */
+    async generateAgentOutput(agentId, format, options) {
+        return this.requireSdk().generateAgentOutput(agentId, format, options);
+    }
+    /** @inheritdoc */
+    async runEvals(agentId, request) {
+        return this.requireSdk().runEvals(agentId, request);
+    }
+    /** @inheritdoc */
+    async listEvals(agentId) {
+        return this.requireSdk().listEvals(agentId);
+    }
+    /** @inheritdoc */
+    async getEval(agentId, evalId) {
+        return this.requireSdk().getEval(agentId, evalId);
+    }
+    /** @inheritdoc */
+    async getContextUsage(agentId) {
+        return this.requireSdk().getContextUsage(agentId);
+    }
+    /** @inheritdoc */
+    async getCostUsage(agentId) {
+        return this.requireSdk().getCostUsage(agentId);
+    }
+    /** @inheritdoc */
+    async createAgentRuntime(data) {
+        return this.requireSdk().createAgentRuntime(data);
+    }
+}

package/lib/client/index.d.ts

@@ -1,6 +1,9 @@
 /**
- * Client mixins for agent-runtimes.
+ * Client mixins and domain-level client abstractions for agent-runtimes.
  *
  * @module client
  */
 export { AgentsMixin } from './AgentsMixin';
+export type { IAgentRuntimesClient } from './IAgentRuntimesClient';
+export { SdkAgentRuntimesClient, type AgentsSdkLike, } from './SdkAgentRuntimesClient';
+export { AgentRuntimesClientProvider, useAgentRuntimesClient, useOptionalAgentRuntimesClient, type AgentRuntimesClientProviderProps, } from './AgentRuntimesClientContext';

package/lib/client/index.js

@@ -3,8 +3,10 @@
  * Distributed under the terms of the Modified BSD License.
  */
 /**
- * Client mixins for agent-runtimes.
+ * Client mixins and domain-level client abstractions for agent-runtimes.
  *
  * @module client
  */
 export { AgentsMixin } from './AgentsMixin';
+export { SdkAgentRuntimesClient, } from './SdkAgentRuntimesClient';
+export { AgentRuntimesClientProvider, useAgentRuntimesClient, useOptionalAgentRuntimesClient, } from './AgentRuntimesClientContext';

package/lib/components/NotificationEventCard.js

@@ -164,7 +164,11 @@ export function NotificationEventCard({ event, onToggleRead, onDelete, onOpenAge
                         }, children: _jsxs("details", { open: isDetailsExpanded, children: [_jsx("summary", { onClick: e => {
                                         e.preventDefault();
                                         setIsDetailsExpanded(prev => !prev);
-                                    }, style: { cursor: 'pointer', display: 'flex', alignItems: 'center' }, children: _jsxs(Box, { sx: { display: 'flex', alignItems: 'center', gap: 1 }, children: [_jsx(Box, { sx: {
+                                    }, style: {
+                                        cursor: 'pointer',
+                                        display: 'flex',
+                                        alignItems: 'center',
+                                    }, children: _jsxs(Box, { sx: { display: 'flex', alignItems: 'center', gap: 1 }, children: [_jsx(Box, { sx: {
                                                     display: 'flex',
                                                     alignItems: 'center',
                                                     color: 'fg.muted',

package/lib/config/AgentConfiguration.d.ts

@@ -53,10 +53,20 @@ export declare const isSpecSelection: (id: string) => boolean;
  * Helper: extract the spec id from a spec selection value.
  */
 export declare const getSpecId: (id: string) => string;
+/**
+ * Helper: is the selected agent id a cloud library spec?
+ */
+export declare const isCloudSpecSelection: (id: string) => boolean;
+/**
+ * Helper: extract the cloud spec id from a cloud selection value.
+ */
+export declare const getCloudSpecId: (id: string) => string;
 export interface SkillOption {
     id: string;
     name: string;
     description?: string;
+    requiredEnvVars?: string[];
+    isAvailable?: boolean;
 }
 declare const AGENT_LIBRARIES: {
     value: AgentLibrary;
@@ -110,6 +120,18 @@ export interface AgentConfigurationProps {
     selectedSkills?: string[];
     /** Selected MCP servers */
     selectedMcpServers?: McpServerSelection[];
+    /** Cloud-discovered specs fetched from a remote runtime catalog. */
+    cloudLibrarySpecs?: LibraryAgentSpec[];
+    /** Loading state for cloud library specs. */
+    cloudLibraryLoading?: boolean;
+    /** Optional cloud library fetch error message. */
+    cloudLibraryError?: string | null;
+    /** Current runtime target mode label. */
+    launchTarget?: 'local' | 'cloud';
+    /** Current launch/runtime status label. */
+    launchStatus?: string;
+    /** Effective service URL that will be used when launching. */
+    launchBaseUrl?: string;
     identityProviders?: {
         [K in OAuthProvider]?: {
             clientId: string;