@distri/core 0.3.2 → 0.3.4

package/dist/index.d.mts

@@ -169,7 +169,23 @@ 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 | BrowserSessionStartedEvent | InlineHookRequestedEvent;
+type TodoStatus = 'open' | 'in_progress' | 'done';
+interface TodoItem {
+    id: string;
+    content: string;
+    status: TodoStatus;
+}
+interface TodosUpdatedEvent {
+    type: 'todos_updated';
+    data: {
+        formatted_todos: string;
+        action: string;
+        todo_count: number;
+        /** Parsed todo items for rendering */
+        todos?: TodoItem[];
+    };
+}
+type DistriEvent = RunStartedEvent | RunFinishedEvent | RunErrorEvent | PlanStartedEvent | PlanFinishedEvent | PlanPrunedEvent | TextMessageStartEvent | TextMessageContentEvent | TextMessageEndEvent | ToolExecutionStartEvent | ToolExecutionEndEvent | ToolRejectedEvent | StepStartedEvent | StepCompletedEvent | AgentHandoverEvent | FeedbackReceivedEvent | ToolCallsEvent | ToolResultsEvent | BrowserScreenshotEvent | BrowserSessionStartedEvent | InlineHookRequestedEvent | TodosUpdatedEvent;
 
 type ChatCompletionRole = 'system' | 'user' | 'assistant' | 'tool';
 interface ChatCompletionMessage {
@@ -239,6 +255,15 @@ declare class DistriClient {
      * 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.
      *
@@ -334,7 +359,7 @@ declare class DistriClient {
     /**
      * Minimal LLM helper that proxies to the Distri server using Distri messages.
      */
-    llm(messages: DistriMessage[], tools?: unknown[], options?: LlmExecuteOptions): Promise<LLMResponse>;
+    llm(messages: DistriMessage[], tools?: ToolDefinition[], options?: LlmExecuteOptions): Promise<LLMResponse>;
     /**
      * Get all available agents from the Distri server
      */
@@ -361,6 +386,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
      */
@@ -374,9 +403,13 @@ declare class DistriClient {
      */
     getThreads(params?: ThreadListParams): Promise<ThreadListResponse>;
     /**
-     * Get agents sorted by thread count (most active first)
+     * Get agents sorted by thread count (most active first).
+     * Includes all registered agents, even those with 0 threads.
+     * Optionally filter by name with search parameter.
      */
-    getAgentsByUsage(): Promise<AgentUsageInfo[]>;
+    getAgentsByUsage(options?: {
+        search?: string;
+    }): Promise<AgentUsageInfo[]>;
     /**
      * Create a new browser session
      * Returns session info including viewer_url and stream_url from browsr
@@ -391,6 +424,35 @@ declare class DistriClient {
      * Get messages from a thread as DistriMessage format
      */
     getThreadMessagesAsDistri(threadId: string): Promise<DistriMessage[]>;
+    /**
+     * Mark a message as read
+     */
+    markMessageRead(threadId: string, messageId: string): Promise<MessageReadStatus>;
+    /**
+     * Get read status for a specific message
+     */
+    getMessageReadStatus(threadId: string, messageId: string): Promise<MessageReadStatus | null>;
+    /**
+     * Get read status for all messages in a thread
+     */
+    getThreadReadStatus(threadId: string): Promise<MessageReadStatus[]>;
+    /**
+     * Vote on a message (upvote or downvote)
+     * Downvotes require a comment explaining the issue
+     */
+    voteMessage(threadId: string, messageId: string, request: VoteMessageRequest): Promise<MessageVote>;
+    /**
+     * Remove vote from a message
+     */
+    removeVote(threadId: string, messageId: string): Promise<void>;
+    /**
+     * Get vote summary for a message (counts + current user's vote)
+     */
+    getMessageVoteSummary(threadId: string, messageId: string): Promise<MessageVoteSummary>;
+    /**
+     * Get all votes for a message (admin/analytics use)
+     */
+    getMessageVotes(threadId: string, messageId: string): Promise<MessageVote[]>;
     /**
      * Send a DistriMessage to a thread
      */
@@ -445,13 +507,19 @@ declare class DistriClient {
      */
     static initDistriMessage(role: DistriMessage['role'], parts: DistriPart[], id?: string, created_at?: number): DistriMessage;
     /**
-     * Helper method to create message send parameters
+     * Helper method to create message send parameters.
+     *
+     * Pass `dynamicMetadata` to inject `dynamic_sections` and/or `dynamic_values`
+     * into the metadata so the server can apply them to prompt templates.
      */
-    static initMessageParams(message: Message, configuration?: MessageSendParams['configuration'], metadata?: any): MessageSendParams;
+    static initMessageParams(message: Message, configuration?: MessageSendParams['configuration'], metadata?: any, dynamicMetadata?: DynamicMetadata): MessageSendParams;
     /**
-     * Create MessageSendParams from a DistriMessage using InvokeContext
+     * Create MessageSendParams from a DistriMessage using InvokeContext.
+     *
+     * Pass `dynamicMetadata` to inject `dynamic_sections` and/or `dynamic_values`
+     * into the metadata so the server can apply them to prompt templates.
      */
-    static initDistriMessageParams(message: DistriMessage, context: InvokeContext): MessageSendParams;
+    static initDistriMessageParams(message: DistriMessage, context: InvokeContext, dynamicMetadata?: DynamicMetadata): MessageSendParams;
 }
 declare function uuidv4(): string;
 
@@ -465,6 +533,14 @@ interface InvokeConfig {
     contextId?: string;
     /** Metadata for the requests */
     metadata?: any;
+    /** Dynamic prompt sections injected into the template per-call */
+    dynamic_sections?: DynamicMetadata['dynamic_sections'];
+    /** Dynamic key-value pairs available in templates per-call */
+    dynamic_values?: DynamicMetadata['dynamic_values'];
+    /** Per-part metadata indexed by part position (0-based).
+     *  Use to control which parts are saved to the database.
+     *  Parts with `save: false` will be filtered out before saving. */
+    parts?: DynamicMetadata['parts'];
 }
 /**
  * Result from agent invoke
@@ -529,7 +605,10 @@ declare class Agent {
      */
     validateExternalTools(tools?: DistriBaseTool[]): ExternalToolValidationResult;
     /**
-     * Enhance message params with tool definitions
+     * Enhance message params with tool definitions and dynamic metadata.
+     *
+     * When `dynamic_sections` or `dynamic_values` are present in `params.metadata`,
+     * they are forwarded so the server injects them into the prompt template.
      */
     private enhanceParamsWithTools;
     private assertExternalTools;
@@ -558,7 +637,27 @@ declare class Agent {
 /**
  * Message roles supported by Distri
  */
-type MessageRole = 'system' | 'assistant' | 'user' | 'tool';
+type MessageRole = 'system' | 'assistant' | 'user' | 'tool' | 'developer';
+/**
+ * Message metadata structure that matches the backend.
+ * The 'parts' field maps part indices to PartMetadata for save filtering.
+ */
+interface DistriMessageMetadata {
+    /** Per-part metadata indexed by part position (0-based). Parts with save: false are filtered before DB save. */
+    parts?: Record<number, {
+        save?: boolean;
+    }>;
+    /** Session ID for browser sessions */
+    session_id?: string;
+    /** Browser session ID */
+    browser_session_id?: string;
+    /** Model/definition overrides */
+    definition_overrides?: {
+        model?: string;
+    };
+    /** Additional arbitrary metadata */
+    [key: string]: unknown;
+}
 /**
  * Distri-specific message structure with parts
  */
@@ -569,6 +668,12 @@ interface DistriMessage {
     created_at: number;
     step_id?: string;
     is_final?: boolean;
+    /** The ID of the agent that generated this message (for assistant messages) */
+    agent_id?: string;
+    /** The name of the agent that generated this message (for assistant messages) */
+    agent_name?: string;
+    /** Message metadata including parts metadata for save filtering */
+    metadata?: DistriMessageMetadata;
 }
 interface LlmExecuteOptions {
     thread_id?: string;
@@ -576,6 +681,11 @@ interface LlmExecuteOptions {
     run_id?: string;
     model_settings?: any;
     is_sub_task?: boolean;
+    headers?: Record<string, string>;
+    agent_id?: string;
+    external_id?: string;
+    load_history?: boolean;
+    title?: string;
 }
 interface AssistantWithToolCalls {
     id: string;
@@ -684,6 +794,36 @@ interface ReactStep extends BasePlanStep {
     action: string;
 }
 type DistriStreamEvent = DistriMessage | DistriEvent;
+/**
+ * A named prompt section that can be dynamically injected into templates per-call.
+ */
+interface PromptSection {
+    key: string;
+    content: string;
+}
+/**
+ * Metadata for individual message parts.
+ * Used to control part behavior such as persistence.
+ */
+interface PartMetadata {
+    /** If false, this part will be filtered out before saving to the database.
+     *  Useful for ephemeral/dynamic content that should only be sent in the current turn.
+     *  Defaults to true. */
+    save?: boolean;
+}
+/**
+ * Dynamic metadata that can be provided per invoke call to customise
+ * prompt template rendering on the server.
+ */
+interface DynamicMetadata {
+    /** Dynamic prompt sections injected into the template per-call */
+    dynamic_sections?: PromptSection[];
+    /** Dynamic key-value pairs available in templates per-call */
+    dynamic_values?: Record<string, unknown>;
+    /** Per-part metadata indexed by part position (0-based).
+     *  Parts not listed will use default metadata (save: true). */
+    parts?: Record<number, PartMetadata>;
+}
 /**
  * Context required for constructing A2A messages from DistriMessage
  */
@@ -718,12 +858,12 @@ type DataPart = {
 };
 type DistriPart = TextPart | ToolCallPart | ToolResultRefPart | ImagePart | DataPart;
 /**
- * File type for images
+ * File type for images - matches Rust FileType::Bytes
  */
 interface FileBytes {
     type: 'bytes';
     mime_type: string;
-    data: string;
+    bytes: string;
     name?: string;
 }
 interface FileUrl {
@@ -775,6 +915,8 @@ interface ToolResult {
     readonly tool_call_id: string;
     readonly tool_name: string;
     readonly parts: readonly DistriPart[];
+    /** Per-part metadata indexed by part position (0-based). Parts with save: false will be filtered out when storing. */
+    readonly parts_metadata?: Record<number, PartMetadata>;
 }
 /**
  * Tool result data that goes inside the parts array
@@ -785,11 +927,20 @@ interface ToolResultData {
     error?: string;
 }
 declare function isArrayParts(result: any): boolean;
+/**
+ * Part with optional inline metadata - used by tool handlers to mark parts as non-saveable
+ */
+type DistriPartWithMetadata = DistriPart & {
+    __metadata?: PartMetadata;
+};
 /**
  * Type-safe helper to create a successful ToolResult
  * Uses proper DistriPart structure - conversion to backend format happens in encoder
+ *
+ * Parts can include __metadata property to specify part-level metadata (e.g., save: false).
+ * Image parts are automatically marked as save: false.
  */
-declare function createSuccessfulToolResult(toolCallId: string, toolName: string, result: string | number | boolean | null | object | DistriPart[]): ToolResult;
+declare function createSuccessfulToolResult(toolCallId: string, toolName: string, result: string | number | boolean | null | object | DistriPartWithMetadata[], explicitPartsMetadata?: Record<number, PartMetadata>): ToolResult;
 /**
  * Type-safe helper to create a failed ToolResult
  * Uses proper DistriPart structure - conversion to backend format happens in encoder
@@ -1046,6 +1197,11 @@ interface DistriClientConfig {
      * 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.
+     */
+    workspaceId?: string;
 }
 interface LLMResponse {
     finish_reason: string;
@@ -1110,6 +1266,51 @@ type A2AStreamEventData = Message | TaskStatusUpdateEvent | TaskArtifactUpdateEv
 declare function isDistriMessage(event: DistriStreamEvent): event is DistriMessage;
 declare function isDistriEvent(event: DistriStreamEvent): event is DistriEvent;
 type DistriChatMessage = DistriEvent | DistriMessage;
+/**
+ * Vote type for message feedback
+ */
+type VoteType = 'upvote' | 'downvote';
+/**
+ * Record of a message being read
+ */
+interface MessageReadStatus {
+    thread_id: string;
+    message_id: string;
+    user_id: string;
+    read_at: string;
+}
+/**
+ * Request to vote on a message
+ */
+interface VoteMessageRequest {
+    vote_type: VoteType;
+    /** Required for downvotes */
+    comment?: string;
+}
+/**
+ * A vote on a message with optional feedback comment
+ */
+interface MessageVote {
+    id: string;
+    thread_id: string;
+    message_id: string;
+    user_id: string;
+    vote_type: VoteType;
+    /** Comment is required for downvotes, optional for upvotes */
+    comment?: string;
+    created_at: string;
+    updated_at: string;
+}
+/**
+ * Summary of votes for a message
+ */
+interface MessageVoteSummary {
+    message_id: string;
+    upvotes: number;
+    downvotes: number;
+    /** Current user's vote on this message, if any */
+    user_vote?: VoteType;
+}
 
 /**
  * Converts an A2A Message to a DistriMessage
@@ -1156,4 +1357,4 @@ declare function extractToolCallsFromDistriMessage(message: DistriMessage): any[
  */
 declare function extractToolResultsFromDistriMessage(message: DistriMessage): any[];
 
-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 };
+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 DistriMessageMetadata, type DistriPart, type DistriPartWithMetadata, type DistriPlan, type DistriStreamEvent, type DistriThread, type DynamicMetadata, 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 MessageReadStatus, type MessageRole, type MessageVote, type MessageVoteSummary, type ModelProviderConfig, type ModelProviderName, type ModelSettings, type PartMetadata, type PlanAction, type PlanFinishedEvent, type PlanPrunedEvent, type PlanStartedEvent, type PlanStep, type PromptSection, 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 TodoItem, type TodoStatus, type TodosUpdatedEvent, 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, type VoteMessageRequest, type VoteType, convertA2AMessageToDistri, convertA2APartToDistri, convertA2AStatusUpdateToDistri, convertDistriMessageToA2A, convertDistriPartToA2A, createFailedToolResult, createSuccessfulToolResult, decodeA2AStreamEvent, extractTextFromDistriMessage, extractToolCallsFromDistriMessage, extractToolResultData, extractToolResultsFromDistriMessage, isArrayParts, isDistriEvent, isDistriMessage, processA2AMessagesData, processA2AStreamData, uuidv4 };