@distri/core 0.2.5 → 0.2.7

package/README.md

@@ -137,4 +137,63 @@ const part: DistriPart = {
     code: 'console.log("Hello");'
   }
 };
-``` 
+```
+
+## Session Store API
+
+The `DistriClient` provides a comprehensive session store API for managing thread-scoped key-value storage.
+
+### Basic Operations
+
+```typescript
+import { DistriClient } from '@distri/core';
+
+const client = DistriClient.create();
+const sessionId = 'thread-123';
+
+// Set a session value
+await client.setSessionValue(sessionId, 'key', { data: 'value' });
+
+// Get a session value
+const value = await client.getSessionValue(sessionId, 'key');
+
+// Get all session values (returns a map)
+const allValues = await client.getSessionValues(sessionId);
+
+// Delete a session value
+await client.deleteSessionValue(sessionId, 'key');
+
+// Clear all session values
+await client.clearSession(sessionId);
+```
+
+### API Endpoints
+
+All session methods use the following endpoints (mounted at `/v1/sessions/`):
+
+- `POST /sessions/{sessionId}/values` - Set a session value
+- `GET /sessions/{sessionId}/values` - Get all session values (returns map)
+- `GET /sessions/{sessionId}/values/{key}` - Get a specific session value
+- `DELETE /sessions/{sessionId}/values/{key}` - Delete a session value
+- `DELETE /sessions/{sessionId}` - Clear all session values
+
+### Integration with Agent Definitions
+
+Session values can be referenced in agent definitions using `UserMessageOverrides`:
+
+```yaml
+# Agent definition
+user_message_overrides:
+  parts:
+    - type: session_key
+      key: "observation"  # References session value with key "observation"
+    - type: template
+      template: "custom_user_template"
+  include_artifacts: true
+```
+
+When the agent processes a message, it will automatically:
+1. Load all session values as a map
+2. Resolve `PartDefinition::SessionKey` references from the map
+3. Merge override parts with the default message parts
+4. Include the merged message in the LLM prompt 

package/dist/index.d.mts

@@ -257,25 +257,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
      */
@@ -341,7 +322,7 @@ declare class DistriClient {
     /**
      * Get specific agent by ID
      */
-    getAgent(agentId: string): Promise<AgentDefinition>;
+    getAgent(agentId: string): Promise<AgentConfigWithTools>;
     /**
      * Get or create A2AClient for an agent
      */
@@ -405,9 +386,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
      */
@@ -479,7 +461,7 @@ declare class Agent {
     private agentDefinition;
     private hookHandlers;
     private defaultHookHandler;
-    constructor(agentDefinition: AgentDefinition, client: DistriClient);
+    constructor(agentDefinition: AgentConfigWithTools, client: DistriClient);
     /**
      * Get agent information
      */
@@ -491,7 +473,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)
      */
@@ -524,7 +506,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
      */
@@ -713,14 +695,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;
@@ -776,6 +762,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
  */
@@ -795,6 +785,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. */
@@ -805,8 +797,8 @@ 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;
 }
@@ -1069,4 +1061,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, 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 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, 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, 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 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 };

package/dist/index.d.ts

@@ -257,25 +257,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
      */
@@ -341,7 +322,7 @@ declare class DistriClient {
     /**
      * Get specific agent by ID
      */
-    getAgent(agentId: string): Promise<AgentDefinition>;
+    getAgent(agentId: string): Promise<AgentConfigWithTools>;
     /**
      * Get or create A2AClient for an agent
      */
@@ -405,9 +386,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
      */
@@ -479,7 +461,7 @@ declare class Agent {
     private agentDefinition;
     private hookHandlers;
     private defaultHookHandler;
-    constructor(agentDefinition: AgentDefinition, client: DistriClient);
+    constructor(agentDefinition: AgentConfigWithTools, client: DistriClient);
     /**
      * Get agent information
      */
@@ -491,7 +473,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)
      */
@@ -524,7 +506,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
      */
@@ -713,14 +695,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;
@@ -776,6 +762,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
  */
@@ -795,6 +785,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. */
@@ -805,8 +797,8 @@ 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;
 }
@@ -1069,4 +1061,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, 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 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, 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, 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 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 };

package/dist/index.js

@@ -1688,7 +1688,8 @@ var _DistriClient = class _DistriClient {
     throw lastError;
   }
   /**
-   * Enhanced fetch with retry logic
+   * Enhanced fetch with retry logic and auth headers.
+   * Exposed publicly for extensions like DistriHomeClient.
    */
   async fetch(input, initialInit) {
     const url = `${this.config.baseUrl}${input}`;
@@ -1832,7 +1833,7 @@ var Agent = class _Agent {
     return this.agentDefinition.description;
   }
   get agentType() {
-    return this.agentDefinition.agent_type ?? this.agentDefinition.agentType;
+    return this.agentDefinition.agent_type;
   }
   get iconUrl() {
     return this.agentDefinition.icon_url;
@@ -1982,12 +1983,13 @@ var Agent = class _Agent {
    */
   static async create(agentIdOrDef, client) {
     const agentDefinition = typeof agentIdOrDef === "string" ? await client.getAgent(agentIdOrDef) : agentIdOrDef;
+    const tools = agentDefinition?.resolved_tools || [];
     console.log("\u{1F916} Agent definition loaded:", {
       id: agentDefinition.id,
       name: agentDefinition.name,
-      tools: agentDefinition.tools?.map((t) => ({
+      tools: tools.map((t) => ({
         name: t.name,
-        type: t.type || "function"
+        type: "function"
       })) || [],
       toolCount: agentDefinition.tools?.length || 0
     });