@distri/core 0.3.1 → 0.3.3

package/dist/index.d.mts

@@ -143,6 +143,14 @@ interface BrowserScreenshotEvent {
         timestamp_ms?: number;
     };
 }
+interface BrowserSessionStartedEvent {
+    type: 'browser_session_started';
+    data: {
+        session_id: string;
+        viewer_url?: string;
+        stream_url?: string;
+    };
+}
 interface InlineHookRequestedEvent {
     type: 'inline_hook_requested';
     data: {
@@ -161,7 +169,7 @@ interface InlineHookRequestedEvent {
         result?: any;
     };
 }
-type DistriEvent = RunStartedEvent | RunFinishedEvent | RunErrorEvent | PlanStartedEvent | PlanFinishedEvent | PlanPrunedEvent | TextMessageStartEvent | TextMessageContentEvent | TextMessageEndEvent | ToolExecutionStartEvent | ToolExecutionEndEvent | ToolRejectedEvent | StepStartedEvent | StepCompletedEvent | AgentHandoverEvent | FeedbackReceivedEvent | ToolCallsEvent | ToolResultsEvent | BrowserScreenshotEvent | InlineHookRequestedEvent;
+type DistriEvent = RunStartedEvent | RunFinishedEvent | RunErrorEvent | PlanStartedEvent | PlanFinishedEvent | PlanPrunedEvent | TextMessageStartEvent | TextMessageContentEvent | TextMessageEndEvent | ToolExecutionStartEvent | ToolExecutionEndEvent | ToolRejectedEvent | StepStartedEvent | StepCompletedEvent | AgentHandoverEvent | FeedbackReceivedEvent | ToolCallsEvent | ToolResultsEvent | BrowserScreenshotEvent | BrowserSessionStartedEvent | InlineHookRequestedEvent;
 
 type ChatCompletionRole = 'system' | 'user' | 'assistant' | 'tool';
 interface ChatCompletionMessage {
@@ -223,6 +231,23 @@ declare class DistriClient {
     private refreshPromise?;
     private agentClients;
     constructor(config: DistriClientConfig);
+    /**
+     * Get the configured client ID.
+     */
+    get clientId(): string | undefined;
+    /**
+     * Set the client ID for embed token issuance.
+     */
+    set clientId(value: string | undefined);
+    /**
+     * Get the configured workspace ID.
+     */
+    get workspaceId(): string | undefined;
+    /**
+     * Set the workspace ID for multi-tenant support.
+     * Updates the X-Workspace-Id header for all subsequent requests.
+     */
+    set workspaceId(value: string | undefined);
     /**
      * Create a client with default cloud configuration.
      *
@@ -257,25 +282,6 @@ declare class DistriClient {
      * Session store: clear all keys in a session
      */
     clearSession(sessionId: string): Promise<void>;
-    private static readonly ADDITIONAL_PARTS_KEY;
-    /**
-     * Set additional user message parts for the next agent iteration.
-     * These parts will be appended to the user message in the prompt.
-     * @param sessionId - The thread/session ID
-     * @param parts - Array of DistriPart objects to append to user message
-     */
-    setAdditionalUserParts(sessionId: string, parts: DistriPart[]): Promise<void>;
-    /**
-     * Get the current additional user message parts.
-     * @param sessionId - The thread/session ID
-     * @returns Array of DistriPart objects or null if not set
-     */
-    getAdditionalUserParts(sessionId: string): Promise<DistriPart[] | null>;
-    /**
-     * Clear/delete the additional user message parts.
-     * @param sessionId - The thread/session ID
-     */
-    clearAdditionalUserParts(sessionId: string): Promise<void>;
     /**
      * Response from the token endpoint
      */
@@ -315,6 +321,10 @@ declare class DistriClient {
         accessToken?: string;
         refreshToken?: string;
     }): void;
+    /**
+     * Reset all authentication tokens.
+     */
+    resetTokens(): void;
     /**
      * Start streaming speech-to-text transcription via WebSocket
      */
@@ -341,7 +351,13 @@ declare class DistriClient {
     /**
      * Get specific agent by ID
      */
-    getAgent(agentId: string): Promise<AgentDefinition>;
+    getAgent(agentId: string): Promise<AgentConfigWithTools>;
+    /**
+     * Update an agent's definition (markdown only)
+     */
+    updateAgent(agentId: string, update: {
+        markdown: string;
+    }): Promise<AgentConfigWithTools>;
     /**
      * Get or create A2AClient for an agent
      */
@@ -354,6 +370,10 @@ declare class DistriClient {
      * Send a streaming message to an agent
      */
     sendMessageStream(agentId: string, params: MessageSendParams): AsyncGenerator<A2AStreamEventData>;
+    /**
+     * Extract a user-friendly error message from potentially nested errors
+     */
+    private extractErrorMessage;
     /**
      * Get task details
      */
@@ -363,9 +383,18 @@ declare class DistriClient {
      */
     cancelTask(agentId: string, taskId: string): Promise<void>;
     /**
-     * Get threads from Distri server
+     * Get threads from Distri server with filtering and pagination
+     */
+    getThreads(params?: ThreadListParams): Promise<ThreadListResponse>;
+    /**
+     * Get agents sorted by thread count (most active first)
+     */
+    getAgentsByUsage(): Promise<AgentUsageInfo[]>;
+    /**
+     * Create a new browser session
+     * Returns session info including viewer_url and stream_url from browsr
      */
-    getThreads(): Promise<DistriThread[]>;
+    createBrowserSession(): Promise<BrowserSession>;
     getThread(threadId: string): Promise<DistriThread>;
     /**
      * Get thread messages
@@ -392,6 +421,9 @@ declare class DistriClient {
      */
     get baseUrl(): string;
     private applyTokens;
+    /**
+     * Ensure access token is valid, refreshing if necessary
+     */
     private ensureAccessToken;
     private refreshTokens;
     private performTokenRefresh;
@@ -405,9 +437,10 @@ declare class DistriClient {
      */
     private fetchAbsolute;
     /**
-     * Enhanced fetch with retry logic
+     * Enhanced fetch with retry logic and auth headers.
+     * Exposed publicly for extensions like DistriHomeClient.
      */
-    private fetch;
+    fetch(input: RequestInfo | URL, initialInit?: RequestInit): Promise<Response>;
     /**
      * Delay utility
      */
@@ -457,6 +490,20 @@ interface InvokeResult {
     /** Whether the response was streamed */
     streamed: boolean;
 }
+interface ExternalToolValidationResult {
+    isValid: boolean;
+    requiredTools: string[];
+    providedTools: string[];
+    missingTools: string[];
+    message?: string;
+}
+declare class ExternalToolValidationError extends DistriError {
+    missingTools: string[];
+    requiredTools: string[];
+    providedTools: string[];
+    agentName: string;
+    constructor(agentName: string, result: ExternalToolValidationResult);
+}
 /**
  * Enhanced Agent class with simple tool system following AG-UI pattern
  */
@@ -465,7 +512,7 @@ declare class Agent {
     private agentDefinition;
     private hookHandlers;
     private defaultHookHandler;
-    constructor(agentDefinition: AgentDefinition, client: DistriClient);
+    constructor(agentDefinition: AgentConfigWithTools, client: DistriClient);
     /**
      * Get agent information
      */
@@ -477,7 +524,7 @@ declare class Agent {
     /**
      * Get the full agent definition (including backend tools)
      */
-    getDefinition(): AgentDefinition;
+    getDefinition(): AgentConfigWithTools;
     /**
      * Fetch messages for a thread (public method for useChat)
      */
@@ -490,10 +537,19 @@ declare class Agent {
      * Streaming invoke
      */
     invokeStream(params: MessageSendParams, tools?: DistriBaseTool[], hooks?: Record<string, HookHandler>): Promise<AsyncGenerator<DistriChatMessage>>;
+    /**
+     * Validate that required external tools are registered before invoking.
+     */
+    validateExternalTools(tools?: DistriBaseTool[]): ExternalToolValidationResult;
     /**
      * Enhance message params with tool definitions
      */
     private enhanceParamsWithTools;
+    private assertExternalTools;
+    private getRequiredExternalTools;
+    private resolveToolConfig;
+    private extractToolConfig;
+    private formatExternalToolValidationMessage;
     /**
      * Register multiple hooks at once.
      */
@@ -501,7 +557,7 @@ declare class Agent {
     /**
      * Create an agent instance from an agent ID
      */
-    static create(agentIdOrDef: string | AgentDefinition, client: DistriClient): Promise<Agent>;
+    static create(agentIdOrDef: string | AgentConfigWithTools, client: DistriClient): Promise<Agent>;
     /**
      * Complete an external tool call by sending the result back to the server
      */
@@ -515,7 +571,7 @@ declare class Agent {
 /**
  * Message roles supported by Distri
  */
-type MessageRole = 'system' | 'assistant' | 'user' | 'tool';
+type MessageRole = 'system' | 'assistant' | 'user' | 'tool' | 'developer';
 /**
  * Distri-specific message structure with parts
  */
@@ -690,14 +746,18 @@ interface FileUrl {
     name?: string;
 }
 type FileType = FileBytes | FileUrl;
+interface ToolDefinition {
+    name: string;
+    description: string;
+    parameters: object;
+    examples?: string;
+    output_schema?: object;
+}
 /**
  * Tool definition interface following AG-UI pattern
  */
-interface DistriBaseTool {
-    name: string;
+interface DistriBaseTool extends ToolDefinition {
     type: 'function' | 'ui';
-    description: string;
-    parameters: object;
     is_final?: boolean;
     autoExecute?: boolean;
     isExternal?: boolean;
@@ -753,6 +813,10 @@ declare function createFailedToolResult(toolCallId: string, toolName: string, er
  * Handles both frontend DistriPart format and backend BackendPart format
  */
 declare function extractToolResultData(toolResult: ToolResult): ToolResultData | null;
+interface AgentConfigWithTools extends AgentDefinition {
+    markdown?: string;
+    resolved_tools?: ToolDefinition[];
+}
 /**
  * Distri-specific Agent type that wraps A2A AgentCard
  */
@@ -772,6 +836,8 @@ interface AgentDefinition {
     mcp_servers?: McpDefinition[];
     /** Settings related to the model used by the agent. */
     model_settings?: ModelSettings;
+    /** Secondary Model Settings used for analysis */
+    analysis_model_settings?: ModelSettings;
     /** The size of the history to maintain for the agent. */
     history_size?: number;
     /** The planning configuration for the agent, if any. */
@@ -782,10 +848,20 @@ interface AgentDefinition {
     skills?: AgentSkill[];
     /** List of sub-agents that this agent can transfer control to */
     sub_agents?: string[];
-    agentType?: string;
     agent_type?: string;
+    context_size?: number;
     tools?: DistriBaseTool[];
     browser_config?: BrowserAgentConfig;
+    /** Agent usage statistics */
+    stats?: AgentStats;
+}
+/**
+ * Agent usage statistics
+ */
+interface AgentStats {
+    thread_count: number;
+    sub_agent_usage_count: number;
+    last_used_at?: string | null;
 }
 interface BrowserAgentConfig {
     enabled?: boolean;
@@ -846,6 +922,9 @@ interface DistriThread {
     updated_at: string;
     message_count: number;
     last_message?: string;
+    user_id?: string;
+    external_id?: string;
+    tags?: string[];
 }
 interface Thread {
     id: string;
@@ -855,6 +934,48 @@ interface Thread {
     updated_at: string;
     message_count: number;
     last_message?: string;
+    user_id?: string;
+    external_id?: string;
+    tags?: string[];
+}
+/**
+ * Parameters for listing threads with filtering and pagination
+ */
+interface ThreadListParams {
+    agent_id?: string;
+    external_id?: string;
+    search?: string;
+    from_date?: string;
+    to_date?: string;
+    tags?: string[];
+    limit?: number;
+    offset?: number;
+}
+/**
+ * Paginated response for thread listing
+ */
+interface ThreadListResponse {
+    threads: DistriThread[];
+    total: number;
+    page: number;
+    page_size: number;
+}
+/**
+ * Agent usage information for sorting agents by thread count
+ */
+interface AgentUsageInfo {
+    agent_id: string;
+    agent_name: string;
+    thread_count: number;
+}
+/**
+ * Browser session info returned when creating a session
+ */
+interface BrowserSession {
+    session_id: string;
+    viewer_url?: string;
+    stream_url?: string;
+    frame_token?: string;
 }
 interface ChatProps {
     thread: Thread;
@@ -917,6 +1038,11 @@ interface DistriClientConfig {
      * Request interceptor for modifying requests before sending
      */
     interceptor?: (init?: RequestInit) => Promise<RequestInit | undefined>;
+    /**
+     * Hook to refresh the access token when it expires.
+     * Useful for public clients where only an access token is available.
+     */
+    onTokenRefresh?: () => Promise<string | null>;
     /**
      * Access token for bearer auth (optional)
      */
@@ -930,12 +1056,14 @@ interface DistriClientConfig {
      */
     tokenRefreshSkewMs?: number;
     /**
-     * Callback invoked when tokens are refreshed
+     * Client ID from Distri Cloud.
+     */
+    clientId?: string;
+    /**
+     * Workspace ID for multi-tenant support (Distri Cloud).
+     * When provided, all requests will include X-Workspace-Id header.
      */
-    onTokenRefresh?: (tokens: {
-        accessToken: string;
-        refreshToken: string;
-    }) => void;
+    workspaceId?: string;
 }
 interface LLMResponse {
     finish_reason: string;
@@ -1046,4 +1174,4 @@ declare function extractToolCallsFromDistriMessage(message: DistriMessage): any[
  */
 declare function extractToolResultsFromDistriMessage(message: DistriMessage): any[];
 
-export { A2AProtocolError, type A2AStreamEventData, type ActionPlanStep, Agent, type AgentDefinition, type AgentHandoverEvent, ApiError, type AssistantWithToolCalls, type BasePlanStep, type BatchToolCallsStep, type BrowserAgentConfig, type BrowserScreenshotEvent, type ChatCompletionChoice, type ChatCompletionMessage, type ChatCompletionRequest, type ChatCompletionResponse, type ChatCompletionResponseFormat, type ChatCompletionRole, type ChatProps, type CodePlanStep, type ConfigurationMeta, type ConfigurationResponse, ConnectionError, type ConnectionStatus, DEFAULT_BASE_URL, type DataPart, type DistriBaseTool, type DistriBrowserRuntimeConfig, type DistriChatMessage, DistriClient, type DistriClientConfig, type DistriConfiguration, DistriError, type DistriEvent, type DistriFnTool, type DistriMessage, type DistriPart, type DistriPlan, type DistriStreamEvent, type DistriThread, type ExternalMcpServer, type FeedbackReceivedEvent, type FileBytes, type FileType, type FileUrl, type FinalResultPlanStep, type HookContext, type HookHandler, type HookMutation, type ImagePart, type InlineHookEventData, type InlineHookRequest, type InlineHookRequestedEvent, type InvokeConfig, type InvokeContext, type InvokeResult, type LLMResponse, type LlmExecuteOptions, type LlmPlanStep, type McpDefinition, type McpServerType, type MessageRole, type ModelProviderConfig, type ModelProviderName, type ModelSettings, type PlanAction, type PlanFinishedEvent, type PlanPrunedEvent, type PlanStartedEvent, type PlanStep, type ReactStep, type Role, type RunErrorEvent, type RunFinishedEvent, type RunStartedEvent, type ServerConfig, type SpeechToTextConfig, type StepCompletedEvent, type StepStartedEvent, type StreamingTranscriptionOptions, type TextMessageContentEvent, type TextMessageEndEvent, type TextMessageStartEvent, type TextPart, type ThoughtPlanStep, type ThoughtStep, type Thread, type ToolCall, type ToolCallPart, type ToolCallsEvent, type ToolExecutionEndEvent, type ToolExecutionOptions, type ToolExecutionStartEvent, type ToolHandler, type ToolRejectedEvent, type ToolResult, type ToolResultData, type ToolResultRefPart, type ToolResults, type ToolResultsEvent, type UseToolsOptions, convertA2AMessageToDistri, convertA2APartToDistri, convertA2AStatusUpdateToDistri, convertDistriMessageToA2A, convertDistriPartToA2A, createFailedToolResult, createSuccessfulToolResult, decodeA2AStreamEvent, extractTextFromDistriMessage, extractToolCallsFromDistriMessage, extractToolResultData, extractToolResultsFromDistriMessage, isArrayParts, isDistriEvent, isDistriMessage, processA2AMessagesData, processA2AStreamData, uuidv4 };
+export { A2AProtocolError, type A2AStreamEventData, type ActionPlanStep, Agent, type AgentConfigWithTools, type AgentDefinition, type AgentHandoverEvent, type AgentStats, type AgentUsageInfo, ApiError, type AssistantWithToolCalls, type BasePlanStep, type BatchToolCallsStep, type BrowserAgentConfig, type BrowserScreenshotEvent, type BrowserSession, type BrowserSessionStartedEvent, type ChatCompletionChoice, type ChatCompletionMessage, type ChatCompletionRequest, type ChatCompletionResponse, type ChatCompletionResponseFormat, type ChatCompletionRole, type ChatProps, type CodePlanStep, type ConfigurationMeta, type ConfigurationResponse, ConnectionError, type ConnectionStatus, DEFAULT_BASE_URL, type DataPart, type DistriBaseTool, type DistriBrowserRuntimeConfig, type DistriChatMessage, DistriClient, type DistriClientConfig, type DistriConfiguration, DistriError, type DistriEvent, type DistriFnTool, type DistriMessage, type DistriPart, type DistriPlan, type DistriStreamEvent, type DistriThread, type ExternalMcpServer, ExternalToolValidationError, type ExternalToolValidationResult, type FeedbackReceivedEvent, type FileBytes, type FileType, type FileUrl, type FinalResultPlanStep, type HookContext, type HookHandler, type HookMutation, type ImagePart, type InlineHookEventData, type InlineHookRequest, type InlineHookRequestedEvent, type InvokeConfig, type InvokeContext, type InvokeResult, type LLMResponse, type LlmExecuteOptions, type LlmPlanStep, type McpDefinition, type McpServerType, type MessageRole, type ModelProviderConfig, type ModelProviderName, type ModelSettings, type PlanAction, type PlanFinishedEvent, type PlanPrunedEvent, type PlanStartedEvent, type PlanStep, type ReactStep, type Role, type RunErrorEvent, type RunFinishedEvent, type RunStartedEvent, type ServerConfig, type SpeechToTextConfig, type StepCompletedEvent, type StepStartedEvent, type StreamingTranscriptionOptions, type TextMessageContentEvent, type TextMessageEndEvent, type TextMessageStartEvent, type TextPart, type ThoughtPlanStep, type ThoughtStep, type Thread, type ThreadListParams, type ThreadListResponse, type ToolCall, type ToolCallPart, type ToolCallsEvent, type ToolDefinition, type ToolExecutionEndEvent, type ToolExecutionOptions, type ToolExecutionStartEvent, type ToolHandler, type ToolRejectedEvent, type ToolResult, type ToolResultData, type ToolResultRefPart, type ToolResults, type ToolResultsEvent, type UseToolsOptions, convertA2AMessageToDistri, convertA2APartToDistri, convertA2AStatusUpdateToDistri, convertDistriMessageToA2A, convertDistriPartToA2A, createFailedToolResult, createSuccessfulToolResult, decodeA2AStreamEvent, extractTextFromDistriMessage, extractToolCallsFromDistriMessage, extractToolResultData, extractToolResultsFromDistriMessage, isArrayParts, isDistriEvent, isDistriMessage, processA2AMessagesData, processA2AStreamData, uuidv4 };