@distri/core 0.1.8 → 0.2.1

package/README.md

@@ -0,0 +1,140 @@
+# @distri/core
+
+Core API client for Distri Framework with support for DistriMessage and DistriPart types.
+
+## Features
+
+- **DistriMessage**: Enhanced message structure with typed parts
+- **DistriPart**: Typed message parts supporting text, code observations, tool calls, and more
+- **A2A Protocol Integration**: Seamless conversion between A2A and Distri message formats
+- **Enhanced Message Rendering**: Rich display of different message part types
+
+## DistriMessage Structure
+
+```typescript
+interface DistriMessage {
+  id: string;
+  role: 'user' | 'assistant';
+  parts: DistriPart[];
+  created_at?: string;
+  metadata?: any;
+}
+```
+
+## DistriPart Types
+
+```typescript
+type DistriPart =
+  | { type: 'text'; text: string }
+  | { type: 'code_observation'; code_observation: CodeObservation }
+  | { type: 'image'; image: FileType }
+  | { type: 'data'; data: any }
+  | { type: 'tool_call'; tool_call: ToolCall }
+  | { type: 'tool_result'; tool_result: ToolResponse }
+  | { type: 'plan'; plan: string };
+```
+
+## Usage
+
+### Creating DistriMessages
+
+```typescript
+import { DistriClient, DistriMessage } from '@distri/core';
+
+// Create a simple text message
+const textMessage = DistriClient.initDistriMessage('Hello, world!', 'user');
+
+// Create a message with multiple parts
+const complexMessage = DistriClient.initDistriMessage([
+  { type: 'text', text: 'Here is my analysis:' },
+  { 
+    type: 'code_observation', 
+    code_observation: {
+      thought: 'I need to analyze this data',
+      code: 'const result = data.map(x => x * 2);'
+    }
+  },
+  {
+    type: 'tool_call',
+    tool_call: {
+      tool_call_id: 'call_123',
+      tool_name: 'calculate',
+      input: { numbers: [1, 2, 3] }
+    }
+  }
+], 'assistant');
+```
+
+### Converting Between Formats
+
+```typescript
+import { 
+  convertA2AMessageToDistri, 
+  convertDistriMessageToA2A 
+} from '@distri/core';
+
+// Convert A2A Message to DistriMessage
+const a2aMessage = /* A2A message from protocol */;
+const distriMessage = convertA2AMessageToDistri(a2aMessage);
+
+// Convert DistriMessage to A2A Message
+const a2aMessage = convertDistriMessageToA2A(distriMessage);
+```
+
+### Extracting Content
+
+```typescript
+import { 
+  extractTextFromDistriMessage,
+  extractToolCallsFromDistriMessage,
+  extractToolResultsFromDistriMessage 
+} from '@distri/core';
+
+// Extract text content
+const text = extractTextFromDistriMessage(message);
+
+// Extract tool calls
+const toolCalls = extractToolCallsFromDistriMessage(message);
+
+// Extract tool results
+const toolResults = extractToolResultsFromDistriMessage(message);
+```
+
+## Message Rendering
+
+The React package includes enhanced message rendering components that can display all DistriPart types:
+
+- **Text**: Standard text rendering with markdown support
+- **Code Observations**: Thought process and code with syntax highlighting
+- **Tool Calls**: Tool execution details with input/output display
+- **Tool Results**: Success/failure status with result data
+- **Plans**: Structured plan display
+- **Images**: Base64 image rendering
+- **Data**: JSON data display
+
+## Migration from A2A Messages
+
+The framework provides backward compatibility while encouraging the use of DistriMessage:
+
+```typescript
+// Old way (still supported)
+const oldMessage = DistriClient.initMessage('Hello', 'user');
+
+// New way (recommended)
+const newMessage = DistriClient.initDistriMessage('Hello', 'user');
+```
+
+## Type Safety
+
+All DistriPart types are fully typed, providing compile-time safety and better IDE support:
+
+```typescript
+// TypeScript will ensure correct structure
+const part: DistriPart = {
+  type: 'code_observation',
+  code_observation: {
+    thought: 'My analysis',
+    code: 'console.log("Hello");'
+  }
+};
+``` 

package/dist/index.d.mts

@@ -1,7 +1,191 @@
-import { AgentSkill, Message, TaskStatusUpdateEvent, TaskArtifactUpdateEvent, Task, MessageSendParams } from '@a2a-js/sdk/client';
-export * from '@a2a-js/sdk/client';
-export { AgentCard, Message, MessageSendParams, Task, TaskArtifactUpdateEvent, TaskStatus, TaskStatusUpdateEvent } from '@a2a-js/sdk/client';
+import { AgentSkill, Message, TaskStatusUpdateEvent, TaskArtifactUpdateEvent, Task, MessageSendParams, Part } from '@a2a-js/sdk/client';
 
+type Role = 'user' | 'system' | 'assistant';
+interface RunStartedEvent {
+    type: 'run_started';
+    data: {};
+}
+interface RunFinishedEvent {
+    type: 'run_finished';
+    data: {};
+}
+interface RunErrorEvent {
+    type: 'run_error';
+    data: {
+        message: string;
+        code?: string;
+    };
+}
+interface TextMessageStartEvent {
+    type: 'text_message_start';
+    data: {
+        message_id: string;
+        role: Role;
+    };
+}
+interface TextMessageContentEvent {
+    type: 'text_message_content';
+    data: {
+        message_id: string;
+        delta: string;
+    };
+}
+interface TextMessageEndEvent {
+    type: 'text_message_end';
+    data: {
+        message_id: string;
+    };
+}
+interface ToolCallStartEvent {
+    type: 'tool_call_start';
+    data: {
+        tool_call_id: string;
+        tool_call_name: string;
+        parent_message_id?: string;
+        is_external?: boolean;
+    };
+}
+interface ToolCallArgsEvent {
+    type: 'tool_call_args';
+    data: {
+        tool_call_id: string;
+        delta: string;
+    };
+}
+interface ToolCallEndEvent {
+    type: 'tool_call_end';
+    data: {
+        tool_call_id: string;
+    };
+}
+interface ToolCallResultEvent {
+    type: 'tool_call_result';
+    data: {
+        tool_call_id: string;
+        result: string;
+    };
+}
+interface AgentHandoverEvent {
+    type: 'agent_handover';
+    data: {
+        from_agent: string;
+        to_agent: string;
+        reason?: string;
+    };
+}
+type DistriEvent = RunStartedEvent | RunFinishedEvent | RunErrorEvent | TextMessageStartEvent | TextMessageContentEvent | TextMessageEndEvent | ToolCallStartEvent | ToolCallArgsEvent | ToolCallEndEvent | ToolCallResultEvent | AgentHandoverEvent;
+
+/**
+ * Message roles supported by Distri
+ */
+type MessageRole = 'system' | 'assistant' | 'user' | 'tool';
+/**
+ * Distri-specific message structure with parts
+ */
+interface DistriMessage {
+    id: string;
+    role: MessageRole;
+    parts: DistriPart[];
+    created_at?: string;
+}
+type DistriStreamEvent = DistriMessage | DistriEvent;
+/**
+ * Context required for constructing A2A messages from DistriMessage
+ */
+interface InvokeContext {
+    thread_id: string;
+    run_id?: string;
+    metadata?: any;
+}
+/**
+ * Distri message parts - equivalent to Rust enum Part
+ */
+type TextPart = {
+    type: 'text';
+    text: string;
+};
+type CodeObservationPart = {
+    type: 'code_observation';
+    thought: string;
+    code: string;
+};
+type ImageUrlPart = {
+    type: 'image_url';
+    image: FileUrl;
+};
+type ImageBytesPart = {
+    type: 'image_bytes';
+    image: FileBytes;
+};
+type ImagePart = ImageUrlPart | ImageBytesPart;
+type DataPart = {
+    type: 'data';
+    data: any;
+};
+type ToolCallPart = {
+    type: 'tool_call';
+    tool_call: ToolCall;
+};
+type ToolResultPart = {
+    type: 'tool_result';
+    tool_result: ToolResult;
+};
+type PlanPart = {
+    type: 'plan';
+    plan: string;
+};
+type DistriPart = TextPart | CodeObservationPart | ImagePart | DataPart | ToolCallPart | ToolResultPart | PlanPart;
+/**
+ * File type for images
+ */
+interface FileBytes {
+    mime_type: string;
+    data: string;
+    name?: string;
+}
+interface FileUrl {
+    mime_type: string;
+    url: string;
+    name?: string;
+}
+type FileType = FileBytes | FileUrl;
+/**
+ * Tool definition interface following AG-UI pattern
+ */
+interface DistriBaseTool {
+    name: string;
+    type: 'function' | 'ui';
+    description: string;
+    input_schema: object;
+}
+interface DistriFnTool extends DistriBaseTool {
+    type: 'function';
+    handler: ToolHandler;
+    onToolComplete?: (toolCallId: string, toolResult: ToolResult) => void;
+}
+/**
+ * Tool handler function
+ */
+interface ToolHandler {
+    (input: any): Promise<string | number | boolean | null | object>;
+}
+/**
+ * Tool call from agent
+ */
+interface ToolCall {
+    tool_call_id: string;
+    tool_name: string;
+    input: any;
+}
+/**
+ * Tool result for responding to tool calls
+ */
+interface ToolResult {
+    tool_call_id: string;
+    result: string | number | boolean | null;
+    success: boolean;
+    error?: string;
+}
 /**
  * Distri-specific Agent type that wraps A2A AgentCard
  */
@@ -66,12 +250,6 @@ interface DistriThread {
     message_count: number;
     last_message?: string;
 }
-interface Agent {
-    id: string;
-    name: string;
-    description: string;
-    status: 'online' | 'offline';
-}
 interface Thread {
     id: string;
     title: string;
@@ -83,7 +261,7 @@ interface Thread {
 }
 interface ChatProps {
     thread: Thread;
-    agent: Agent;
+    agent: DistriAgent;
     onThreadUpdate?: () => void;
 }
 /**
@@ -103,26 +281,9 @@ interface DistriClientConfig {
     headers?: Record<string, string>;
     interceptor?: (init?: RequestInit) => Promise<RequestInit | undefined>;
 }
-/**
- * Error Types
- */
-declare class DistriError extends Error {
-    code: string;
-    details?: any | undefined;
-    constructor(message: string, code: string, details?: any | undefined);
-}
-declare class A2AProtocolError extends DistriError {
-    constructor(message: string, details?: any);
-}
-declare class ApiError extends DistriError {
-    statusCode: number;
-    constructor(message: string, statusCode: number, details?: any);
-}
-declare class ConnectionError extends DistriError {
-    constructor(message: string, details?: any);
-}
-
 type A2AStreamEventData = Message | TaskStatusUpdateEvent | TaskArtifactUpdateEvent | Task;
+declare function isDistriMessage(event: DistriStreamEvent): event is DistriMessage;
+declare function isDistriEvent(event: DistriStreamEvent): event is DistriEvent;
 
 /**
  * Enhanced Distri Client that wraps A2AClient and adds Distri-specific features
@@ -168,6 +329,14 @@ declare class DistriClient {
      * Get thread messages
      */
     getThreadMessages(threadId: string): Promise<Message[]>;
+    /**
+     * Get messages from a thread as DistriMessage format
+     */
+    getThreadMessagesAsDistri(threadId: string): Promise<DistriMessage[]>;
+    /**
+     * Send a DistriMessage to a thread
+     */
+    sendDistriMessage(threadId: string, message: DistriMessage, context: InvokeContext): Promise<void>;
     /**
      * Get the base URL for making direct requests
      */
@@ -191,84 +360,132 @@ declare class DistriClient {
     /**
      * Helper method to create A2A messages
      */
-    static initMessage(input: string, role?: 'agent' | 'user', contextId?: string, messageId?: string, taskId?: string): Message;
+    static initMessage(parts: Part[] | string, role: "agent" | "user" | undefined, message: Omit<Partial<Message>, 'parts' | 'role' | 'kind'>): Message;
+    /**
+     * Create a DistriMessage instance
+     */
+    static initDistriMessage(role: DistriMessage['role'], parts: DistriPart[], id?: string, created_at?: string): DistriMessage;
     /**
      * Helper method to create message send parameters
      */
-    static initMessageParams(message: Message, configuration?: MessageSendParams['configuration']): MessageSendParams;
+    static initMessageParams(message: Message, configuration?: MessageSendParams['configuration'], metadata?: any): MessageSendParams;
+    /**
+     * Create MessageSendParams from a DistriMessage using InvokeContext
+     */
+    static initDistriMessageParams(message: DistriMessage, context: InvokeContext): MessageSendParams;
 }
 declare function uuidv4(): string;
 
-type Role = 'user' | 'system' | 'assistant';
-interface RunStartedEvent {
-    type: 'run_started';
-}
-interface RunFinishedEvent {
-    type: 'run_finished';
-}
-interface RunErrorEvent {
-    type: 'run_error';
-    data: {
-        message: string;
-        code?: string;
-    };
-}
-interface TextMessageStartEvent {
-    type: 'text_message_start';
-    data: {
-        message_id: string;
-        role: Role;
-    };
-}
-interface TextMessageContentEvent {
-    type: 'text_message_content';
-    data: {
-        message_id: string;
-        delta: string;
-    };
-}
-interface TextMessageEndEvent {
-    type: 'text_message_end';
-    data: {
-        message_id: string;
-    };
-}
-interface ToolCallStartEvent {
-    type: 'tool_call_start';
-    data: {
-        tool_call_id: string;
-        tool_call_name: string;
-        parent_message_id?: string;
-    };
-}
-interface ToolCallArgsEvent {
-    type: 'tool_call_args';
-    data: {
-        tool_call_id: string;
-        delta: string;
-    };
-}
-interface ToolCallEndEvent {
-    type: 'tool_call_end';
-    data: {
-        tool_call_id: string;
-    };
+/**
+ * Configuration for Agent invoke method
+ */
+interface InvokeConfig {
+    /** Configuration for the message */
+    configuration?: MessageSendParams['configuration'];
+    /** Context/thread ID */
+    contextId?: string;
+    /** Metadata for the requests */
+    metadata?: any;
 }
-interface ToolCallResultEvent {
-    type: 'tool_call_result';
-    data: {
-        tool_call_id: string;
-        result: string;
-    };
+/**
+ * Result from agent invoke
+ */
+interface InvokeResult {
+    /** Final response message */
+    message?: Message;
+    /** Task if created */
+    task?: any;
+    /** Whether the response was streamed */
+    streamed: boolean;
 }
-interface AgentHandoverEvent {
-    type: 'agent_handover';
-    data: {
-        from_agent: string;
-        to_agent: string;
-        reason?: string;
-    };
+/**
+ * Enhanced Agent class with simple tool system following AG-UI pattern
+ */
+declare class Agent {
+    private client;
+    private agentDefinition;
+    private tools;
+    constructor(agentDefinition: DistriAgent, client: DistriClient);
+    /**
+     * Add a tool to the agent (AG-UI style)
+     */
+    registerTool(tool: DistriBaseTool): void;
+    /**
+     * Add multiple tools at once
+     */
+    registerTools(tools: DistriBaseTool[]): void;
+    /**
+     * Remove a tool
+     */
+    unregisterTool(toolName: string): void;
+    /**
+     * Get all registered tools
+     */
+    getTools(): DistriBaseTool[];
+    /**
+     * Check if a tool is registered
+     */
+    hasTool(toolName: string): boolean;
+    /**
+     * Get agent information
+     */
+    get id(): string;
+    get name(): string;
+    get description(): string | undefined;
+    get iconUrl(): string | undefined;
+    /**
+     * Fetch messages for a thread (public method for useChat)
+     */
+    getThreadMessages(threadId: string): Promise<Message[]>;
+    /**
+     * Direct (non-streaming) invoke
+     */
+    invoke(params: MessageSendParams): Promise<Message>;
+    /**
+     * Streaming invoke
+     */
+    invokeStream(params: MessageSendParams): Promise<AsyncGenerator<DistriEvent | DistriMessage>>;
+    /**
+     * Enhance message params with tool definitions
+     */
+    private enhanceParamsWithTools;
+    /**
+     * Create an agent instance from an agent ID
+     */
+    static create(agentId: string, client: DistriClient): Promise<Agent>;
+    /**
+     * List all available agents
+     */
+    static list(client: DistriClient): Promise<Agent[]>;
 }
-type DistriEvent = RunStartedEvent | RunFinishedEvent | RunErrorEvent | TextMessageStartEvent | TextMessageContentEvent | TextMessageEndEvent | ToolCallStartEvent | ToolCallArgsEvent | ToolCallEndEvent | ToolCallResultEvent | AgentHandoverEvent;
 
-export { A2AProtocolError, type A2AStreamEventData, type Agent, type AgentHandoverEvent, ApiError, type ChatProps, ConnectionError, type ConnectionStatus, type DistriAgent, DistriClient, type DistriClientConfig, DistriError, type DistriEvent, type DistriThread, type McpDefinition, type McpServerType, type ModelProvider, type ModelSettings, type Role, type RunErrorEvent, type RunFinishedEvent, type RunStartedEvent, type TextMessageContentEvent, type TextMessageEndEvent, type TextMessageStartEvent, type Thread, type ToolCallArgsEvent, type ToolCallEndEvent, type ToolCallResultEvent, type ToolCallStartEvent, uuidv4 };
+/**
+ * Converts an A2A Message to a DistriMessage
+ */
+declare function convertA2AMessageToDistri(a2aMessage: Message): DistriMessage;
+/**
+ * Converts an A2A Part to a DistriPart
+ */
+declare function convertA2APartToDistri(a2aPart: Part): DistriPart;
+/**
+ * Converts a DistriMessage to an A2A Message using the provided context
+ */
+declare function convertDistriMessageToA2A(distriMessage: DistriMessage, context: InvokeContext): Message;
+/**
+ * Converts a DistriPart to an A2A Part
+ */
+declare function convertDistriPartToA2A(distriPart: DistriPart): Part;
+/**
+ * Extract text content from DistriMessage
+ */
+declare function extractTextFromDistriMessage(message: DistriMessage): string;
+/**
+ * Extract tool calls from DistriMessage
+ */
+declare function extractToolCallsFromDistriMessage(message: DistriMessage): any[];
+/**
+ * Extract tool results from DistriMessage
+ */
+declare function extractToolResultsFromDistriMessage(message: DistriMessage): any[];
+
+export { Agent, type AgentHandoverEvent, type ChatProps, type CodeObservationPart, type ConnectionStatus, type DataPart, type DistriAgent, type DistriBaseTool, DistriClient, type DistriClientConfig, type DistriEvent, type DistriFnTool, type DistriMessage, type DistriPart, type DistriStreamEvent, type DistriThread, type FileType, type ImagePart, type InvokeConfig, type InvokeContext, type InvokeResult, type McpDefinition, type McpServerType, type MessageRole, type ModelProvider, type ModelSettings, type PlanPart, type RunErrorEvent, type RunFinishedEvent, type RunStartedEvent, type TextMessageContentEvent, type TextMessageEndEvent, type TextMessageStartEvent, type TextPart, type Thread, type ToolCall, type ToolCallArgsEvent, type ToolCallEndEvent, type ToolCallPart, type ToolCallResultEvent, type ToolCallStartEvent, type ToolResult, type ToolResultPart, convertA2AMessageToDistri, convertA2APartToDistri, convertDistriMessageToA2A, convertDistriPartToA2A, extractTextFromDistriMessage, extractToolCallsFromDistriMessage, extractToolResultsFromDistriMessage, isDistriEvent, isDistriMessage, uuidv4 };