@datalayer/agent-runtimes 0.0.9 → 0.0.11

package/lib/components/chat/protocols/AGUIAdapter.js

@@ -22,7 +22,13 @@ export class AGUIAdapter extends BaseProtocolAdapter {
     lastTools = [];
     constructor(config) {
         super(config);
-        this.aguiConfig = config;
+        // Ensure baseUrl ends with trailing slash (required for mounted Starlette apps)
+        this.aguiConfig = {
+            ...config,
+            baseUrl: config.baseUrl.endsWith('/')
+                ? config.baseUrl
+                : `${config.baseUrl}/`,
+        };
     }
     /**
      * Connect to AG-UI endpoint (SSE doesn't require persistent connection)
@@ -56,7 +62,7 @@ export class AGUIAdapter extends BaseProtocolAdapter {
     async terminateAgent(threadId) {
         try {
             // Derive the terminate endpoint from the base URL
-            // e.g., http://localhost:8765/api/v1/examples/agentic_chat/ -> http://localhost:8765/api/v1/ag-ui/terminate
+            // e.g., http://localhost:8765/api/v1/examples/agentic_chat -> http://localhost:8765/api/v1/ag-ui/terminate
             const baseUrl = new URL(this.aguiConfig.baseUrl);
             const terminateUrl = `${baseUrl.origin}/api/v1/ag-ui/terminate`;
             const response = await fetch(terminateUrl, {
@@ -521,9 +527,23 @@ export class AGUIAdapter extends BaseProtocolAdapter {
                 });
                 break;
             }
-            case 'RUN_FINISHED':
-                // Run completed successfully
+            case 'RUN_FINISHED': {
+                // Run completed successfully — extract usage data if available
+                const usage = event.usage;
+                if (usage) {
+                    this.emit({
+                        type: 'message',
+                        usage: {
+                            promptTokens: usage.promptTokens ?? 0,
+                            completionTokens: usage.completionTokens ?? 0,
+                            totalTokens: usage.totalTokens ??
+                                (usage.promptTokens ?? 0) + (usage.completionTokens ?? 0),
+                        },
+                        timestamp: new Date(),
+                    });
+                }
                 break;
+            }
             case 'RUN_ERROR': {
                 const errorMessage = event.message;
                 this.emit({

package/lib/components/chat/protocols/VercelAIAdapter.js

@@ -185,6 +185,16 @@ export class VercelAIAdapter extends BaseProtocolAdapter {
             while (true) {
                 const { done, value } = await reader.read();
                 if (done) {
+                    // Stream ended - emit final message if we have accumulated text
+                    if (accumulatedText) {
+                        const message = createAssistantMessage(accumulatedText);
+                        message.id = currentMessageId;
+                        this.emit({
+                            type: 'message',
+                            message,
+                            timestamp: new Date(),
+                        });
+                    }
                     break;
                 }
                 buffer += decoder.decode(value, { stream: true });
@@ -194,6 +204,8 @@ export class VercelAIAdapter extends BaseProtocolAdapter {
                     if (!line.trim() || line.startsWith(':')) {
                         continue;
                     }
+                    // Log raw line for debugging
+                    console.debug('[VercelAIAdapter] SSE line:', line);
                     if (line.startsWith('data: ')) {
                         const data = line.slice(6);
                         if (data === '[DONE]') {
@@ -211,6 +223,7 @@ export class VercelAIAdapter extends BaseProtocolAdapter {
                         }
                         try {
                             const event = JSON.parse(data);
+                            console.debug('[VercelAIAdapter] Parsed event:', event);
                             // Handle Vercel AI event types
                             // Server sends: {"type":"text-delta","delta":"Hello","id":"..."}
                             if (event.type === 'text-delta' && event.delta) {
@@ -239,11 +252,32 @@ export class VercelAIAdapter extends BaseProtocolAdapter {
                                         timestamp: new Date(),
                                     });
                                 }
+                                // Extract and emit usage data from finish events
+                                if (event.usage) {
+                                    const usage = event.usage;
+                                    this.emit({
+                                        type: 'message',
+                                        usage: {
+                                            promptTokens: usage.promptTokens ?? 0,
+                                            completionTokens: usage.completionTokens ?? 0,
+                                            totalTokens: usage.totalTokens ??
+                                                (usage.promptTokens ?? 0) +
+                                                    (usage.completionTokens ?? 0),
+                                        },
+                                        timestamp: new Date(),
+                                    });
+                                }
                             }
                             else if (event.type === 'error') {
+                                const errorMessage = event.error ||
+                                    event.errorText ||
+                                    event.message ||
+                                    event.detail ||
+                                    'Unknown server error';
+                                console.error('[VercelAIAdapter] Server error event:', event);
                                 this.emit({
                                     type: 'error',
-                                    error: new Error(event.error || 'Unknown error'),
+                                    error: new Error(errorMessage),
                                     timestamp: new Date(),
                                 });
                             }

package/lib/components/chat/store/chatStore.d.ts

@@ -51,7 +51,7 @@ export interface ToolCallState {
 /**
  * Chat store state
  */
-interface ChatState {
+export interface ChatState {
     config: ChatConfig;
     ready: boolean;
     inferenceProvider: InferenceProvider | null;
@@ -76,7 +76,7 @@ interface ChatState {
 /**
  * Chat store actions
  */
-interface ChatActions {
+export interface ChatActions {
     setConfig: (config: Partial<ChatConfig>) => void;
     setReady: (ready: boolean) => void;
     setInferenceProvider: (provider: InferenceProvider | null) => void;
@@ -155,4 +155,3 @@ export declare const useChatConfig: () => ChatConfig;
 export declare const useChatReady: () => boolean;
 export declare const useChatInferenceProvider: () => InferenceProvider | null;
 export declare const useChatExtensionRegistry: () => ExtensionRegistry | null;
-export {};

package/lib/components/chat/store/conversationStore.d.ts

@@ -0,0 +1,83 @@
+import type { ChatMessage } from '../types/message';
+/**
+ * Conversation data for a single runtime
+ */
+export interface ConversationData {
+    /** Runtime/agent space ID */
+    runtimeId: string;
+    /** Messages in this conversation */
+    messages: ChatMessage[];
+    /** When the conversation was last updated */
+    updatedAt: number;
+    /** Whether messages have been fetched from the server */
+    fetchedFromServer: boolean;
+    /** Whether a fetch is currently in progress */
+    isFetching: boolean;
+}
+/**
+ * Conversation store state
+ */
+interface ConversationState {
+    /** Map of runtime ID to conversation data */
+    conversations: Record<string, ConversationData>;
+}
+/**
+ * Conversation store actions
+ */
+interface ConversationActions {
+    /** Get messages for a specific runtime */
+    getMessages: (runtimeId: string) => ChatMessage[];
+    /** Set messages for a specific runtime */
+    setMessages: (runtimeId: string, messages: ChatMessage[]) => void;
+    /** Add a message to a specific runtime's conversation */
+    addMessage: (runtimeId: string, message: ChatMessage) => void;
+    /** Update a message in a specific runtime's conversation */
+    updateMessage: (runtimeId: string, messageId: string, updates: Partial<ChatMessage>) => void;
+    /** Clear messages for a specific runtime */
+    clearMessages: (runtimeId: string) => void;
+    /** Clear all conversations */
+    clearAll: () => void;
+    /** Mark a runtime as fetched from server */
+    markFetched: (runtimeId: string) => void;
+    /** Mark a runtime as currently fetching */
+    setFetching: (runtimeId: string, isFetching: boolean) => void;
+    /** Check if a runtime needs to fetch from server */
+    needsFetch: (runtimeId: string) => boolean;
+    /** Check if a runtime is currently fetching */
+    isFetching: (runtimeId: string) => boolean;
+    /** Delete a conversation for a specific runtime */
+    deleteConversation: (runtimeId: string) => void;
+}
+/**
+ * Combined store type
+ */
+export type ConversationStore = ConversationState & ConversationActions;
+/**
+ * Create the conversation store (in-memory only, no browser persistence)
+ */
+export declare const useConversationStore: import("zustand").UseBoundStore<Omit<Omit<import("zustand").StoreApi<ConversationStore>, "setState"> & {
+    setState<A extends string | {
+        type: string;
+    }>(partial: ConversationStore | Partial<ConversationStore> | ((state: ConversationStore) => ConversationStore | Partial<ConversationStore>), replace?: boolean | undefined, action?: A | undefined): void;
+}, "subscribe"> & {
+    subscribe: {
+        (listener: (selectedState: ConversationStore, previousSelectedState: ConversationStore) => void): () => void;
+        <U>(selector: (state: ConversationStore) => U, listener: (selectedState: U, previousSelectedState: U) => void, options?: {
+            equalityFn?: ((a: U, b: U) => boolean) | undefined;
+            fireImmediately?: boolean;
+        } | undefined): () => void;
+    };
+}>;
+/**
+ * Hook to get messages for a specific runtime
+ */
+export declare const useConversationMessages: (runtimeId: string | undefined) => ChatMessage[];
+/**
+ * Hook to check if a runtime needs to fetch messages from server
+ */
+export declare const useNeedsFetch: (runtimeId: string | undefined) => boolean;
+/**
+ * Hook to check if a runtime is currently fetching
+ */
+export declare const useIsFetching: (runtimeId: string | undefined) => boolean;
+export {};

package/lib/components/chat/store/conversationStore.js

@@ -0,0 +1,174 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Zustand store for conversation history per runtime/agent space.
+ * Stores messages per runtime ID in memory during the session.
+ *
+ * Key features:
+ * - Messages are stored per runtime ID (agent space) in memory
+ * - On page reload, messages are fetched from the server API
+ * - No browser storage persistence - server is the source of truth
+ *
+ * @module components/chat/store/conversationStore
+ */
+import { create } from 'zustand';
+import { devtools, subscribeWithSelector } from 'zustand/middleware';
+/**
+ * Initial state
+ */
+const initialState = {
+    conversations: {},
+};
+/**
+ * Create the conversation store (in-memory only, no browser persistence)
+ */
+export const useConversationStore = create()(devtools(subscribeWithSelector((set, get) => ({
+    ...initialState,
+    getMessages: (runtimeId) => {
+        const conversation = get().conversations[runtimeId];
+        return conversation?.messages || [];
+    },
+    setMessages: (runtimeId, messages) => {
+        set(state => ({
+            conversations: {
+                ...state.conversations,
+                [runtimeId]: {
+                    runtimeId,
+                    messages,
+                    updatedAt: Date.now(),
+                    fetchedFromServer: state.conversations[runtimeId]?.fetchedFromServer || false,
+                    isFetching: state.conversations[runtimeId]?.isFetching || false,
+                },
+            },
+        }), false, 'setMessages');
+    },
+    addMessage: (runtimeId, message) => {
+        set(state => {
+            const existing = state.conversations[runtimeId];
+            const currentMessages = existing?.messages || [];
+            return {
+                conversations: {
+                    ...state.conversations,
+                    [runtimeId]: {
+                        runtimeId,
+                        messages: [...currentMessages, message],
+                        updatedAt: Date.now(),
+                        fetchedFromServer: existing?.fetchedFromServer || false,
+                        isFetching: existing?.isFetching || false,
+                    },
+                },
+            };
+        }, false, 'addMessage');
+    },
+    updateMessage: (runtimeId, messageId, updates) => {
+        set(state => {
+            const existing = state.conversations[runtimeId];
+            if (!existing)
+                return state;
+            return {
+                conversations: {
+                    ...state.conversations,
+                    [runtimeId]: {
+                        ...existing,
+                        messages: existing.messages.map(msg => msg.id === messageId ? { ...msg, ...updates } : msg),
+                        updatedAt: Date.now(),
+                    },
+                },
+            };
+        }, false, 'updateMessage');
+    },
+    clearMessages: (runtimeId) => {
+        set(state => {
+            const existing = state.conversations[runtimeId];
+            if (!existing)
+                return state;
+            return {
+                conversations: {
+                    ...state.conversations,
+                    [runtimeId]: {
+                        ...existing,
+                        messages: [],
+                        updatedAt: Date.now(),
+                        // Reset fetch state so next mount will fetch fresh
+                        fetchedFromServer: false,
+                    },
+                },
+            };
+        }, false, 'clearMessages');
+    },
+    clearAll: () => {
+        set({ conversations: {} }, false, 'clearAll');
+    },
+    markFetched: (runtimeId) => {
+        set(state => {
+            const existing = state.conversations[runtimeId];
+            return {
+                conversations: {
+                    ...state.conversations,
+                    [runtimeId]: existing
+                        ? { ...existing, fetchedFromServer: true, isFetching: false }
+                        : {
+                            runtimeId,
+                            messages: [],
+                            updatedAt: Date.now(),
+                            fetchedFromServer: true,
+                            isFetching: false,
+                        },
+                },
+            };
+        }, false, 'markFetched');
+    },
+    setFetching: (runtimeId, isFetching) => {
+        set(state => {
+            const existing = state.conversations[runtimeId];
+            return {
+                conversations: {
+                    ...state.conversations,
+                    [runtimeId]: existing
+                        ? { ...existing, isFetching }
+                        : {
+                            runtimeId,
+                            messages: [],
+                            updatedAt: Date.now(),
+                            fetchedFromServer: false,
+                            isFetching,
+                        },
+                },
+            };
+        }, false, 'setFetching');
+    },
+    needsFetch: (runtimeId) => {
+        const conversation = get().conversations[runtimeId];
+        // Needs fetch if not yet fetched and not currently fetching
+        return !conversation?.fetchedFromServer && !conversation?.isFetching;
+    },
+    isFetching: (runtimeId) => {
+        return get().conversations[runtimeId]?.isFetching || false;
+    },
+    deleteConversation: (runtimeId) => {
+        set(state => {
+            const { [runtimeId]: _, ...remainingConversations } = state.conversations;
+            return { conversations: remainingConversations };
+        }, false, 'deleteConversation');
+    },
+})), { name: 'ConversationStore' }));
+/**
+ * Hook to get messages for a specific runtime
+ */
+export const useConversationMessages = (runtimeId) => {
+    return useConversationStore(state => runtimeId ? state.conversations[runtimeId]?.messages || [] : []);
+};
+/**
+ * Hook to check if a runtime needs to fetch messages from server
+ */
+export const useNeedsFetch = (runtimeId) => {
+    return useConversationStore(state => runtimeId ? state.needsFetch(runtimeId) : false);
+};
+/**
+ * Hook to check if a runtime is currently fetching
+ */
+export const useIsFetching = (runtimeId) => {
+    return useConversationStore(state => runtimeId ? state.isFetching(runtimeId) : false);
+};

package/lib/components/chat/store/index.d.ts

@@ -3,4 +3,5 @@
  *
  * @module components/chat/store
  */
-export { useChatStore, useChatMessages, useChatLoading, useChatStreaming, useChatError, useChatTools, useChatOpen, useChatConfig, useChatReady, useChatInferenceProvider, useChatExtensionRegistry, defaultChatConfig, type ChatStore, type ChatConfig, type ToolCallState, } from './chatStore';
+export { useChatStore, useChatMessages, useChatLoading, useChatStreaming, useChatError, useChatTools, useChatOpen, useChatConfig, useChatReady, useChatInferenceProvider, useChatExtensionRegistry, defaultChatConfig, type ChatStore, type ChatState, type ChatActions, type ChatConfig, type ToolCallState, } from './chatStore';
+export { useConversationStore, useConversationMessages, useNeedsFetch, useIsFetching, type ConversationStore, type ConversationData, } from './conversationStore';

package/lib/components/chat/store/index.js

@@ -8,3 +8,4 @@
  * @module components/chat/store
  */
 export { useChatStore, useChatMessages, useChatLoading, useChatStreaming, useChatError, useChatTools, useChatOpen, useChatConfig, useChatReady, useChatInferenceProvider, useChatExtensionRegistry, defaultChatConfig, } from './chatStore';
+export { useConversationStore, useConversationMessages, useNeedsFetch, useIsFetching, } from './conversationStore';

package/lib/components/chat/types/inference.d.ts

@@ -6,6 +6,23 @@
  */
 import type { ChatMessage, ChatMessageDelta } from './message';
 import type { ToolDefinition, ToolCallRequest, ToolExecutionResult } from './tool';
+/**
+ * Type alias for MCP server identifier
+ */
+export type McpId = string;
+/**
+ * Type alias for MCP server origin
+ */
+export type McpOrigin = 'config' | 'catalog';
+/**
+ * MCP Server selection - identifies a specific MCP server by ID and origin
+ */
+export interface McpServerSelection {
+    /** Unique identifier of the MCP server */
+    id: McpId;
+    /** Origin of the server (config from mcp.json, catalog from built-in) */
+    origin: McpOrigin;
+}
 /**
  * Inference provider configuration
  */

package/lib/components/chat/types/protocol.d.ts

@@ -49,6 +49,14 @@ export interface ProtocolAdapterConfig {
  * Protocol event types
  */
 export type ProtocolEventType = 'connected' | 'disconnected' | 'message' | 'tool-call' | 'tool-result' | 'activity' | 'state-update' | 'error';
+/**
+ * Token usage statistics from a protocol event
+ */
+export interface ProtocolUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens?: number;
+}
 /**
  * Protocol event
  */
@@ -62,6 +70,8 @@ export interface ProtocolEvent {
         type: string;
         data: unknown;
     };
+    /** Token usage for this event (emitted on finish/run-complete events) */
+    usage?: ProtocolUsage;
     error?: Error;
     timestamp: Date;
 }

package/lib/components/index.d.ts

@@ -1 +1,24 @@
 export * from './chat';
+export type { ToolCallStatus } from './chat/types/message';
+export type { ToolCallStatus as DisplayToolCallStatus } from './chat/components/base/ChatBase';
+export { MockFileBrowser } from './MockFileBrowser';
+export type { MockFileBrowserProps } from './MockFileBrowser';
+export { MainContent } from './MainContent';
+export type { MainContentProps } from './MainContent';
+export { SessionTabs } from './SessionTabs';
+export type { SessionTabsProps, Session } from './SessionTabs';
+export { Header } from './Header';
+export type { HeaderProps } from './Header';
+export { HeaderControls } from './HeaderControls';
+export type { HeaderControlsProps } from './HeaderControls';
+export { FooterMetrics } from './FooterMetrics';
+export type { FooterMetricsProps } from './FooterMetrics';
+export { TimeTravel } from './TimeTravel';
+export type { TimeTravelProps } from './TimeTravel';
+export { LexicalEditor } from './LexicalEditor';
+export type { LexicalEditorProps } from './LexicalEditor';
+export { AgentConfiguration, AGENT_LIBRARIES, TRANSPORTS, EXTENSIONS, isSpecSelection, getSpecId, } from './AgentConfiguration';
+export type { AgentLibrary, Transport, Extension, AgentConfigurationProps, SkillOption, MCPServerConfig, MCPServerTool, LibraryAgentSpec, } from './AgentConfiguration';
+export { McpServerManager } from './McpServerManager';
+export type { McpServerSelection, McpServerManagerProps, } from './McpServerManager';
+export type { Agent as ExampleAgent, AgentStatus as ExampleAgentStatus, AgentsState, Transport as ExampleTransport, } from '../examples/stores/examplesStore';

package/lib/components/index.js

@@ -4,3 +4,14 @@
  */
 // Primary exports from chat (next-gen chat component)
 export * from './chat';
+// Example/layout components
+export { MockFileBrowser } from './MockFileBrowser';
+export { MainContent } from './MainContent';
+export { SessionTabs } from './SessionTabs';
+export { Header } from './Header';
+export { HeaderControls } from './HeaderControls';
+export { FooterMetrics } from './FooterMetrics';
+export { TimeTravel } from './TimeTravel';
+export { LexicalEditor } from './LexicalEditor';
+export { AgentConfiguration, AGENT_LIBRARIES, TRANSPORTS, EXTENSIONS, isSpecSelection, getSpecId, } from './AgentConfiguration';
+export { McpServerManager } from './McpServerManager';

package/lib/config/agents/code-ai/agents.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Agent Library.
+ *
+ * Predefined agent specifications that can be instantiated as AgentSpaces.
+ * THIS FILE IS AUTO-GENERATED. DO NOT EDIT MANUALLY.
+ * Generated from YAML specifications in specs/agents/
+ */
+import type { AgentSpec } from '../../../types';
+export declare const SIMPLE_AGENT_SPEC: AgentSpec;
+export declare const AGENT_SPECS: Record<string, AgentSpec>;
+/**
+ * Get an agent specification by ID.
+ */
+export declare function getAgentSpecs(agentId: string): AgentSpec | undefined;
+/**
+ * List all available agent specifications.
+ */
+export declare function listAgentSpecs(): AgentSpec[];
+/**
+ * Collect all required environment variables for an agent spec.
+ *
+ * Iterates over the spec's MCP servers and skills and returns the
+ * deduplicated union of their `requiredEnvVars` arrays.
+ */
+export declare function getAgentSpecRequiredEnvVars(spec: AgentSpec): string[];

package/lib/config/agents/code-ai/agents.js

@@ -0,0 +1,70 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+// ============================================================================
+// Agent Specs
+// ============================================================================
+// Code Ai Agents
+// ============================================================================
+export const SIMPLE_AGENT_SPEC = {
+    id: 'code-ai/simple',
+    name: 'A Simple Agent',
+    description: `A simple conversational agent. No tools, no MCP servers, no skills — just a helpful AI assistant you can chat with.`,
+    tags: ['simple', 'chat', 'assistant'],
+    enabled: true,
+    mcpServers: [],
+    skills: [],
+    environmentName: 'ai-agents-env',
+    icon: 'share-2',
+    emoji: '🤖',
+    color: '#6366F1',
+    suggestions: [
+        'Tell me a joke',
+        'Explain quantum computing in simple terms',
+        'Help me brainstorm ideas for a weekend project',
+        'Summarize the key points of a topic I describe',
+    ],
+    systemPrompt: `You are a helpful, friendly AI assistant. You do not have access to any external tools, MCP servers, or skills. Answer questions using your training knowledge, be concise, and let the user know if a question is outside your knowledge.
+`,
+    systemPromptCodemodeAddons: undefined,
+};
+// ============================================================================
+// Agent Specs Registry
+// ============================================================================
+export const AGENT_SPECS = {
+    // Code Ai
+    'code-ai/simple': SIMPLE_AGENT_SPEC,
+};
+/**
+ * Get an agent specification by ID.
+ */
+export function getAgentSpecs(agentId) {
+    return AGENT_SPECS[agentId];
+}
+/**
+ * List all available agent specifications.
+ */
+export function listAgentSpecs() {
+    return Object.values(AGENT_SPECS);
+}
+/**
+ * Collect all required environment variables for an agent spec.
+ *
+ * Iterates over the spec's MCP servers and skills and returns the
+ * deduplicated union of their `requiredEnvVars` arrays.
+ */
+export function getAgentSpecRequiredEnvVars(spec) {
+    const vars = new Set();
+    for (const server of spec.mcpServers) {
+        for (const v of server.requiredEnvVars ?? []) {
+            vars.add(v);
+        }
+    }
+    for (const skill of spec.skills) {
+        for (const v of skill.requiredEnvVars ?? []) {
+            vars.add(v);
+        }
+    }
+    return Array.from(vars);
+}

package/lib/config/agents/code-ai/index.d.ts

@@ -0,0 +1 @@
+export * from './agents';

package/lib/config/agents/code-ai/index.js

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

package/lib/config/agents/codemode-paper/agents.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Agent Library.
+ *
+ * Predefined agent specifications that can be instantiated as AgentSpaces.
+ * THIS FILE IS AUTO-GENERATED. DO NOT EDIT MANUALLY.
+ * Generated from YAML specifications in specs/agents/
+ */
+import type { AgentSpec } from '../../../types';
+export declare const CRAWLER_AGENT_SPEC: AgentSpec;
+export declare const DATA_ACQUISITION_AGENT_SPEC: AgentSpec;
+export declare const FINANCIAL_VIZ_AGENT_SPEC: AgentSpec;
+export declare const GITHUB_AGENT_SPEC: AgentSpec;
+export declare const INFORMATION_ROUTING_AGENT_SPEC: AgentSpec;
+export declare const AGENT_SPECS: Record<string, AgentSpec>;
+/**
+ * Get an agent specification by ID.
+ */
+export declare function getAgentSpecs(agentId: string): AgentSpec | undefined;
+/**
+ * List all available agent specifications.
+ */
+export declare function listAgentSpecs(): AgentSpec[];
+/**
+ * Collect all required environment variables for an agent spec.
+ *
+ * Iterates over the spec's MCP servers and skills and returns the
+ * deduplicated union of their `requiredEnvVars` arrays.
+ */
+export declare function getAgentSpecRequiredEnvVars(spec: AgentSpec): string[];