@datalayer/agent-runtimes 0.0.2

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

@@ -0,0 +1,181 @@
+/**
+ * Extension types for chat component.
+ * Extensions add pluggable UI and protocol capabilities.
+ *
+ * @module components/chat/types/extension
+ */
+import type { ReactNode } from 'react';
+import type { ChatMessage } from './message';
+import type { ToolRenderProps } from './tool';
+import type { ProtocolEvent } from './protocol';
+/**
+ * Extension type identifiers
+ */
+export type ExtensionType = 'a2ui' | 'mcp-ui' | 'tool-approval' | 'dev-console' | 'activity' | 'custom';
+/**
+ * Extension lifecycle hooks
+ */
+export interface ExtensionLifecycle {
+    /** Called when extension is registered */
+    onRegister?: () => void;
+    /** Called when extension is unregistered */
+    onUnregister?: () => void;
+    /** Called when chat context changes */
+    onContextChange?: (context: unknown) => void;
+}
+/**
+ * Message renderer extension
+ * Used to render custom message types (A2UI, activity messages, etc.)
+ */
+export interface MessageRendererExtension {
+    type: 'message-renderer';
+    /** Unique extension name */
+    name: string;
+    /** Check if this extension can render the message */
+    canRender: (message: ChatMessage) => boolean;
+    /** Render the message */
+    render: (props: {
+        message: ChatMessage;
+        isStreaming?: boolean;
+    }) => ReactNode;
+    /** Priority (higher = checked first) */
+    priority?: number;
+}
+/**
+ * Activity renderer extension
+ * Used to render protocol-specific activity messages
+ */
+export interface ActivityRendererExtension {
+    type: 'activity-renderer';
+    /** Unique extension name */
+    name: string;
+    /** Activity types this extension handles */
+    activityTypes: string[];
+    /** Render the activity */
+    render: (props: {
+        activityType: string;
+        data: unknown;
+        message: ChatMessage;
+    }) => ReactNode;
+    /** Priority (higher = checked first) */
+    priority?: number;
+}
+/**
+ * Tool UI extension
+ * Used to provide custom UI for tool calls (beyond tool's own render)
+ */
+export interface ToolUIExtension {
+    type: 'tool-ui';
+    /** Unique extension name */
+    name: string;
+    /** Tool names this extension handles (or '*' for all) */
+    toolNames: string[] | '*';
+    /** Render custom UI for tool */
+    render: (props: ToolRenderProps & {
+        toolName: string;
+        defaultRender: () => ReactNode;
+    }) => ReactNode;
+    /** Priority (higher = checked first) */
+    priority?: number;
+}
+/**
+ * Protocol event extension
+ * Used to handle custom protocol events
+ */
+export interface ProtocolEventExtension {
+    type: 'protocol-event';
+    /** Unique extension name */
+    name: string;
+    /** Event types this extension handles */
+    eventTypes: string[];
+    /** Handle the protocol event */
+    handle: (event: ProtocolEvent) => void;
+    /** Optionally render UI for the event */
+    render?: (event: ProtocolEvent) => ReactNode;
+}
+/**
+ * Panel extension
+ * Used to add custom panels (dev console, settings, etc.)
+ */
+export interface PanelExtension {
+    type: 'panel';
+    /** Unique extension name */
+    name: string;
+    /** Panel title */
+    title: string;
+    /** Panel icon (optional) */
+    icon?: ReactNode;
+    /** Panel position */
+    position: 'sidebar' | 'bottom' | 'floating';
+    /** Render the panel content */
+    render: () => ReactNode;
+    /** Whether panel is initially visible */
+    defaultVisible?: boolean;
+}
+/**
+ * Union type for all extensions
+ */
+export type ChatExtension = MessageRendererExtension | ActivityRendererExtension | ToolUIExtension | ProtocolEventExtension | PanelExtension;
+/**
+ * Extension registration options
+ */
+export interface ExtensionRegistrationOptions {
+    /** Replace existing extension with same name */
+    replace?: boolean;
+    /** Enable/disable extension */
+    enabled?: boolean;
+}
+/**
+ * Extension registry entry
+ */
+export interface ExtensionRegistryEntry {
+    extension: ChatExtension;
+    enabled: boolean;
+    registeredAt: Date;
+}
+/**
+ * A2UI specific extension types
+ */
+export declare namespace A2UIExtension {
+    /** A2UI surface state */
+    interface Surface {
+        id: string;
+        root: string;
+        styles?: {
+            font?: string;
+            primaryColor?: string;
+        };
+        components: Map<string, Component>;
+        dataModel: Map<string, unknown>;
+    }
+    /** A2UI component definition */
+    interface Component {
+        id: string;
+        type: string;
+        props: Record<string, unknown>;
+        children?: string[];
+    }
+    /** A2UI message types */
+    type MessageType = 'beginRendering' | 'surfaceUpdate' | 'dataModelUpdate' | 'deleteSurface';
+    /** A2UI renderer theme */
+    interface Theme {
+        components?: Record<string, React.ComponentType<unknown>>;
+        styles?: Record<string, unknown>;
+    }
+}
+/**
+ * Type guard to check extension type
+ */
+export declare function isMessageRendererExtension(ext: ChatExtension): ext is MessageRendererExtension;
+export declare function isActivityRendererExtension(ext: ChatExtension): ext is ActivityRendererExtension;
+export declare function isToolUIExtension(ext: ChatExtension): ext is ToolUIExtension;
+export declare function isProtocolEventExtension(ext: ChatExtension): ext is ProtocolEventExtension;
+export declare function isPanelExtension(ext: ChatExtension): ext is PanelExtension;
+/**
+ * Helper to create a message renderer extension
+ */
+export declare function createMessageRenderer(name: string, canRender: MessageRendererExtension['canRender'], render: MessageRendererExtension['render'], priority?: number): MessageRendererExtension;
+/**
+ * Helper to create an activity renderer extension
+ */
+export declare function createActivityRenderer(name: string, activityTypes: string[], render: ActivityRendererExtension['render'], priority?: number): ActivityRendererExtension;

package/lib/components/chat/types/extension.js

@@ -0,0 +1,46 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Type guard to check extension type
+ */
+export function isMessageRendererExtension(ext) {
+    return ext.type === 'message-renderer';
+}
+export function isActivityRendererExtension(ext) {
+    return ext.type === 'activity-renderer';
+}
+export function isToolUIExtension(ext) {
+    return ext.type === 'tool-ui';
+}
+export function isProtocolEventExtension(ext) {
+    return ext.type === 'protocol-event';
+}
+export function isPanelExtension(ext) {
+    return ext.type === 'panel';
+}
+/**
+ * Helper to create a message renderer extension
+ */
+export function createMessageRenderer(name, canRender, render, priority = 0) {
+    return {
+        type: 'message-renderer',
+        name,
+        canRender,
+        render,
+        priority,
+    };
+}
+/**
+ * Helper to create an activity renderer extension
+ */
+export function createActivityRenderer(name, activityTypes, render, priority = 0) {
+    return {
+        type: 'activity-renderer',
+        name,
+        activityTypes,
+        render,
+        priority,
+    };
+}

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

@@ -0,0 +1,11 @@
+/**
+ * Core types for chat component.
+ *
+ * @module components/chat/types
+ */
+export * from './message';
+export * from './tool';
+export * from './inference';
+export * from './protocol';
+export * from './middleware';
+export * from './extension';

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

@@ -0,0 +1,16 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Core types for chat component.
+ *
+ * @module components/chat/types
+ */
+// Re-export all types
+export * from './message';
+export * from './tool';
+export * from './inference';
+export * from './protocol';
+export * from './middleware';
+export * from './extension';

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

@@ -0,0 +1,117 @@
+/**
+ * Inference provider types for chat component.
+ * Supports multiple backends: Datalayer, OpenAI, Anthropic, self-hosted.
+ *
+ * @module components/chat/types/inference
+ */
+import type { ChatMessage, ChatMessageDelta } from './message';
+import type { ToolDefinition, ToolCallRequest, ToolExecutionResult } from './tool';
+/**
+ * Inference provider configuration
+ */
+export interface InferenceProviderConfig {
+    /** API key for authentication */
+    apiKey?: string;
+    /** Base URL for API requests */
+    baseUrl?: string;
+    /** Model to use for inference */
+    model?: string;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+    /** Additional provider-specific options */
+    options?: Record<string, unknown>;
+}
+/**
+ * Request options for sending messages
+ */
+export interface InferenceRequestOptions {
+    /** System prompt / instructions */
+    instructions?: string;
+    /** Temperature for response generation */
+    temperature?: number;
+    /** Maximum tokens to generate */
+    maxTokens?: number;
+    /** Tools available for the LLM */
+    tools?: ToolDefinition[];
+    /** Abort signal for cancellation */
+    signal?: AbortSignal;
+    /** Thread/conversation ID */
+    threadId?: string;
+    /** Agent name for multi-agent scenarios */
+    agentName?: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Response from inference provider
+ */
+export interface InferenceResponse {
+    /** Generated message */
+    message: ChatMessage;
+    /** Usage statistics */
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+    /** Finish reason */
+    finishReason?: 'stop' | 'length' | 'tool_calls' | 'content_filter' | 'error';
+}
+/**
+ * Streaming event types
+ */
+export type StreamEventType = 'message-start' | 'content-delta' | 'tool-call-start' | 'tool-call-delta' | 'tool-call-end' | 'message-end' | 'error';
+/**
+ * Streaming event
+ */
+export interface StreamEvent {
+    type: StreamEventType;
+    messageId?: string;
+    delta?: ChatMessageDelta;
+    toolCall?: ToolCallRequest;
+    error?: Error;
+    finishReason?: string;
+}
+/**
+ * Callback for handling stream events
+ */
+export type StreamEventHandler = (event: StreamEvent) => void;
+/**
+ * Abstract inference provider interface
+ */
+export interface InferenceProvider {
+    /** Provider name for identification */
+    readonly name: string;
+    /**
+     * Send a message and get a response (non-streaming)
+     */
+    sendMessage(messages: ChatMessage[], options?: InferenceRequestOptions): Promise<InferenceResponse>;
+    /**
+     * Send a message with streaming response
+     */
+    streamMessage(messages: ChatMessage[], options?: InferenceRequestOptions, onEvent?: StreamEventHandler): Promise<InferenceResponse>;
+    /**
+     * Cancel an ongoing request
+     */
+    cancelRequest(requestId?: string): void;
+    /**
+     * Execute a backend tool (for hybrid execution)
+     */
+    executeBackendTool?(toolName: string, args: Record<string, unknown>, options?: InferenceRequestOptions): Promise<ToolExecutionResult>;
+    /**
+     * Check if provider is available/configured
+     */
+    isAvailable(): boolean;
+    /**
+     * Get provider configuration
+     */
+    getConfig(): InferenceProviderConfig;
+}
+/**
+ * Factory function type for creating inference providers
+ */
+export type InferenceProviderFactory = (config: InferenceProviderConfig) => InferenceProvider;
+/**
+ * Provider type identifiers
+ */
+export type InferenceProviderType = 'datalayer' | 'openai' | 'anthropic' | 'self-hosted' | 'copilotkit';

package/lib/components/chat/types/inference.js

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

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

@@ -0,0 +1,117 @@
+/**
+ * Message types for chat component.
+ * Based on AG-UI protocol message format for interoperability.
+ *
+ * @module components/chat/types/message
+ */
+/**
+ * Message role enumeration
+ */
+export type MessageRole = 'user' | 'assistant' | 'system' | 'tool';
+/**
+ * Tool call status for tracking execution state
+ */
+export type ToolCallStatus = 'pending' | 'executing' | 'completed' | 'failed' | 'awaiting-approval';
+/**
+ * Content part types for multi-modal messages
+ */
+export interface TextContentPart {
+    type: 'text';
+    text: string;
+}
+export interface ImageContentPart {
+    type: 'image';
+    url: string;
+    alt?: string;
+}
+export interface ToolCallContentPart {
+    type: 'tool-call';
+    toolCallId: string;
+    toolName: string;
+    args: Record<string, unknown>;
+    status: ToolCallStatus;
+    result?: unknown;
+}
+export interface ToolResultContentPart {
+    type: 'tool-result';
+    toolCallId: string;
+    toolName: string;
+    result: unknown;
+    isError?: boolean;
+}
+export interface ActivityContentPart {
+    type: 'activity';
+    activityType: string;
+    data: unknown;
+}
+export type ContentPart = TextContentPart | ImageContentPart | ToolCallContentPart | ToolResultContentPart | ActivityContentPart;
+/**
+ * Core message interface
+ */
+export interface ChatMessage {
+    /** Unique message identifier */
+    id: string;
+    /** Message role */
+    role: MessageRole;
+    /** Message content - can be string or structured parts */
+    content: string | ContentPart[];
+    /** Timestamp when message was created */
+    createdAt: Date;
+    /** Optional agent name for multi-agent scenarios */
+    agentName?: string;
+    /** Optional metadata */
+    metadata?: Record<string, unknown>;
+    /** Tool calls for assistant messages */
+    toolCalls?: ToolCallContentPart[];
+    /** For activity messages (A2A, A2UI, etc.) */
+    activityType?: string;
+    activityData?: unknown;
+}
+/**
+ * Message input for sending new messages
+ */
+export interface ChatMessageInput {
+    role: MessageRole;
+    content: string | ContentPart[];
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Streaming message delta for incremental updates
+ */
+export interface ChatMessageDelta {
+    messageId: string;
+    delta: {
+        content?: string;
+        toolCalls?: Partial<ToolCallContentPart>[];
+    };
+}
+/**
+ * Conversation thread metadata
+ */
+export interface ChatThread {
+    id: string;
+    title?: string;
+    createdAt: Date;
+    updatedAt: Date;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Generate unique message ID
+ */
+export declare function generateMessageId(): string;
+/**
+ * Create a new user message
+ */
+export declare function createUserMessage(content: string, metadata?: Record<string, unknown>): ChatMessage;
+/**
+ * Create a new assistant message
+ */
+export declare function createAssistantMessage(content: string, options?: {
+    agentName?: string;
+    toolCalls?: ToolCallContentPart[];
+    metadata?: Record<string, unknown>;
+}): ChatMessage;
+/**
+ * Create an activity message (for A2A, A2UI protocols)
+ */
+export declare function createActivityMessage(activityType: string, activityData: unknown, metadata?: Record<string, unknown>): ChatMessage;

package/lib/components/chat/types/message.js

@@ -0,0 +1,50 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Generate unique message ID
+ */
+export function generateMessageId() {
+    return `msg_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
+}
+/**
+ * Create a new user message
+ */
+export function createUserMessage(content, metadata) {
+    return {
+        id: generateMessageId(),
+        role: 'user',
+        content,
+        createdAt: new Date(),
+        metadata,
+    };
+}
+/**
+ * Create a new assistant message
+ */
+export function createAssistantMessage(content, options) {
+    return {
+        id: generateMessageId(),
+        role: 'assistant',
+        content,
+        createdAt: new Date(),
+        agentName: options?.agentName,
+        toolCalls: options?.toolCalls,
+        metadata: options?.metadata,
+    };
+}
+/**
+ * Create an activity message (for A2A, A2UI protocols)
+ */
+export function createActivityMessage(activityType, activityData, metadata) {
+    return {
+        id: generateMessageId(),
+        role: 'assistant',
+        content: [{ type: 'activity', activityType, data: activityData }],
+        createdAt: new Date(),
+        activityType,
+        activityData,
+        metadata,
+    };
+}

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

@@ -0,0 +1,153 @@
+/**
+ * Middleware types for chat component.
+ * Supports request/response interception and tool call middleware.
+ *
+ * @module components/chat/types/middleware
+ */
+import type { ChatMessage } from './message';
+import type { ToolCallRequest, ToolExecutionResult } from './tool';
+import type { InferenceRequestOptions, InferenceResponse } from './inference';
+/**
+ * Context passed to middleware functions
+ */
+export interface MiddlewareContext {
+    /** Thread/conversation ID */
+    threadId?: string;
+    /** Run/request ID */
+    runId?: string;
+    /** Request URL */
+    url?: string;
+    /** Additional properties */
+    properties?: Record<string, unknown>;
+}
+/**
+ * Middleware for intercepting requests before they're sent
+ */
+export interface BeforeRequestMiddleware {
+    name: string;
+    /**
+     * Called before a request is sent to the inference provider
+     * Can modify messages, options, or abort the request
+     */
+    onBeforeRequest: (options: {
+        messages: ChatMessage[];
+        requestOptions: InferenceRequestOptions;
+        context: MiddlewareContext;
+    }) => Promise<{
+        messages: ChatMessage[];
+        requestOptions: InferenceRequestOptions;
+        abort?: boolean;
+        abortReason?: string;
+    }>;
+}
+/**
+ * Middleware for intercepting responses after they're received
+ */
+export interface AfterRequestMiddleware {
+    name: string;
+    /**
+     * Called after a response is received from the inference provider
+     * Can modify the response or perform side effects
+     */
+    onAfterRequest: (options: {
+        inputMessages: ChatMessage[];
+        outputMessages: ChatMessage[];
+        response: InferenceResponse;
+        context: MiddlewareContext;
+    }) => Promise<{
+        outputMessages: ChatMessage[];
+        response: InferenceResponse;
+    }>;
+}
+/**
+ * Middleware for intercepting tool calls
+ */
+export interface ToolCallMiddleware {
+    name: string;
+    /**
+     * Called before a tool is executed
+     * Can modify args, approve/reject, or skip execution
+     */
+    onToolCall: (options: {
+        toolCall: ToolCallRequest;
+        context: MiddlewareContext;
+    }) => Promise<{
+        toolCall: ToolCallRequest;
+        /** If true, proceed with execution */
+        proceed: boolean;
+        /** If false, use this result instead of executing */
+        overrideResult?: ToolExecutionResult;
+        /** Reason for rejection/override */
+        reason?: string;
+    }>;
+    /**
+     * Called after a tool is executed (optional)
+     */
+    onToolResult?: (options: {
+        toolCall: ToolCallRequest;
+        result: ToolExecutionResult;
+        context: MiddlewareContext;
+    }) => Promise<{
+        result: ToolExecutionResult;
+    }>;
+}
+/**
+ * Error handling middleware
+ */
+export interface ErrorMiddleware {
+    name: string;
+    /**
+     * Called when an error occurs during request/response cycle
+     */
+    onError: (options: {
+        error: Error;
+        phase: 'request' | 'response' | 'tool-execution' | 'stream';
+        context: MiddlewareContext;
+    }) => Promise<{
+        /** If true, error is handled and should not propagate */
+        handled: boolean;
+        /** Optional replacement error */
+        error?: Error;
+        /** Optional recovery message to show user */
+        recoveryMessage?: string;
+    }>;
+}
+/**
+ * Combined middleware definition
+ */
+export interface ChatMiddleware {
+    name: string;
+    priority?: number;
+    beforeRequest?: BeforeRequestMiddleware['onBeforeRequest'];
+    afterRequest?: AfterRequestMiddleware['onAfterRequest'];
+    onToolCall?: ToolCallMiddleware['onToolCall'];
+    onToolResult?: ToolCallMiddleware['onToolResult'];
+    onError?: ErrorMiddleware['onError'];
+}
+/**
+ * Middleware pipeline configuration
+ */
+export interface MiddlewarePipelineConfig {
+    /** Middlewares to use */
+    middlewares: ChatMiddleware[];
+    /** Whether to continue on middleware error */
+    continueOnError?: boolean;
+    /** Enable middleware logging */
+    debug?: boolean;
+}
+/**
+ * Built-in middleware names
+ */
+export type BuiltInMiddlewareName = 'auth' | 'logging' | 'rate-limit' | 'retry' | 'cache' | 'tool-approval' | 'analytics';
+/**
+ * Helper to create a simple before-request middleware
+ */
+export declare function createBeforeRequestMiddleware(name: string, handler: BeforeRequestMiddleware['onBeforeRequest']): ChatMiddleware;
+/**
+ * Helper to create a simple after-request middleware
+ */
+export declare function createAfterRequestMiddleware(name: string, handler: AfterRequestMiddleware['onAfterRequest']): ChatMiddleware;
+/**
+ * Helper to create a tool call middleware
+ */
+export declare function createToolCallMiddleware(name: string, onToolCall: ToolCallMiddleware['onToolCall'], onToolResult?: ToolCallMiddleware['onToolResult']): ChatMiddleware;