@llmrtc/llmrtc-core 1.0.0

package/dist/protocol.js

@@ -0,0 +1,149 @@
+/**
+ * @llmrtc/llmrtc Wire Protocol v1
+ *
+ * This file defines all JSON message types exchanged between
+ * the web-client and backend over WebSocket and WebRTC data channel.
+ *
+ * See PROTOCOL.md in the repository root for full documentation.
+ */
+// =============================================================================
+// Protocol Version
+// =============================================================================
+/**
+ * Current protocol version.
+ * Exchanged during handshake in the 'ready' message.
+ */
+export const PROTOCOL_VERSION = 1;
+// =============================================================================
+// Type Guards
+// =============================================================================
+/** Client message type literals */
+const CLIENT_MESSAGE_TYPES = new Set([
+    'ping',
+    'offer',
+    'reconnect',
+    'audio',
+    'attachments'
+]);
+/** Server message type literals */
+const SERVER_MESSAGE_TYPES = new Set([
+    'ready',
+    'pong',
+    'signal',
+    'reconnect-ack',
+    'transcript',
+    'llm-chunk',
+    'llm',
+    'tts-start',
+    'tts-chunk',
+    'tts',
+    'tts-complete',
+    'tts-cancelled',
+    'speech-start',
+    'speech-end',
+    'tool-call-start',
+    'tool-call-end',
+    'stage-change',
+    'error'
+]);
+/**
+ * Check if a message is a client-to-server message
+ */
+export function isClientMessage(msg) {
+    return CLIENT_MESSAGE_TYPES.has(msg.type);
+}
+/**
+ * Check if a message is a server-to-client message
+ */
+export function isServerMessage(msg) {
+    return SERVER_MESSAGE_TYPES.has(msg.type);
+}
+/**
+ * Check if a message is an error message
+ */
+export function isErrorMessage(msg) {
+    return msg.type === 'error';
+}
+/**
+ * Parse and validate a JSON message
+ * Returns null if parsing fails or message type is unknown
+ */
+export function parseMessage(json) {
+    try {
+        const msg = JSON.parse(json);
+        if (typeof msg !== 'object' || msg === null || typeof msg.type !== 'string') {
+            return null;
+        }
+        if (!CLIENT_MESSAGE_TYPES.has(msg.type) && !SERVER_MESSAGE_TYPES.has(msg.type)) {
+            return null;
+        }
+        return msg;
+    }
+    catch {
+        return null;
+    }
+}
+// =============================================================================
+// Message Constructors (for type-safe message creation)
+// =============================================================================
+/**
+ * Create a ready message
+ */
+export function createReadyMessage(id, iceServers) {
+    return { type: 'ready', id, protocolVersion: PROTOCOL_VERSION, iceServers };
+}
+/**
+ * Create an error message
+ */
+export function createErrorMessage(code, message) {
+    return { type: 'error', code, message };
+}
+/**
+ * Create a transcript message
+ */
+export function createTranscriptMessage(text, isFinal) {
+    return { type: 'transcript', text, isFinal };
+}
+/**
+ * Create an LLM chunk message
+ */
+export function createLLMChunkMessage(content, done) {
+    return { type: 'llm-chunk', content, done };
+}
+/**
+ * Create an LLM message
+ */
+export function createLLMMessage(text) {
+    return { type: 'llm', text };
+}
+/**
+ * Create a TTS chunk message
+ */
+export function createTTSChunkMessage(data, format, sampleRate) {
+    return { type: 'tts-chunk', data, format, sampleRate };
+}
+/**
+ * Create a TTS message
+ */
+export function createTTSMessage(data, format) {
+    return { type: 'tts', data, format };
+}
+/**
+ * Create a tool call start message
+ */
+export function createToolCallStartMessage(name, callId, args) {
+    return { type: 'tool-call-start', name, callId, arguments: args };
+}
+/**
+ * Create a tool call end message
+ */
+export function createToolCallEndMessage(callId, durationMs, result, error) {
+    return { type: 'tool-call-end', callId, result, error, durationMs };
+}
+/**
+ * Create a stage change message
+ */
+export function createStageChangeMessage(from, to, reason) {
+    return { type: 'stage-change', from, to, reason };
+}
+//# sourceMappingURL=protocol.js.map

package/dist/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"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"}

package/dist/tool-executor.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Tool Executor
+ *
+ * Handles execution of tool calls from LLM responses.
+ * Supports sequential and parallel execution policies.
+ */
+import { Tool, ToolCallRequest, ToolCallResult, ToolExecutionContext, ToolRegistry } from './tools.js';
+/**
+ * Options for tool execution
+ */
+export interface ToolExecutorOptions {
+    /** Default execution policy when not specified on tool (default: 'parallel') */
+    defaultPolicy?: 'sequential' | 'parallel';
+    /** Maximum concurrent tool executions (default: 10) */
+    maxConcurrency?: number;
+    /** Timeout per tool execution in ms (default: 30000) */
+    timeout?: number;
+    /** Validate tool arguments against schema before execution (default: true) */
+    validateArguments?: boolean;
+    /** Handler called when a tool execution starts */
+    onToolStart?: (toolName: string, callId: string, args: Record<string, unknown>) => void;
+    /** Handler called when a tool execution completes */
+    onToolEnd?: (result: ToolCallResult) => void;
+    /** Handler called when a tool execution fails */
+    onToolError?: (toolName: string, callId: string, error: Error) => void;
+}
+/**
+ * Executes tool calls from LLM responses
+ * Handles both sequential and parallel execution based on tool policies
+ */
+export declare class ToolExecutor {
+    private registry;
+    private options;
+    constructor(registry: ToolRegistry, options?: ToolExecutorOptions);
+    /**
+     * Execute a batch of tool calls
+     * Respects individual tool execution policies
+     */
+    execute(calls: ToolCallRequest[], context: Omit<ToolExecutionContext, 'callId'>): Promise<ToolCallResult[]>;
+    /**
+     * Execute a single tool call
+     */
+    executeSingle(call: ToolCallRequest, context: Omit<ToolExecutionContext, 'callId'>): Promise<ToolCallResult>;
+    /**
+     * Execute multiple tools in parallel with concurrency limit
+     */
+    private executeParallel;
+    /**
+     * Execute a tool handler with timeout
+     */
+    private executeWithTimeout;
+    /**
+     * Combine multiple abort signals into one
+     */
+    private combineAbortSignals;
+    /**
+     * Group tool calls by their execution policy
+     */
+    private groupByPolicy;
+}
+/**
+ * Create a tool executor with a new registry
+ */
+export declare function createToolExecutor(tools: Tool<unknown, unknown>[], options?: ToolExecutorOptions): ToolExecutor;

package/dist/tool-executor.js

@@ -0,0 +1,240 @@
+/**
+ * Tool Executor
+ *
+ * Handles execution of tool calls from LLM responses.
+ * Supports sequential and parallel execution policies.
+ */
+import { ToolRegistry, validateToolArguments, } from './tools.js';
+// =============================================================================
+// Tool Executor
+// =============================================================================
+/**
+ * Executes tool calls from LLM responses
+ * Handles both sequential and parallel execution based on tool policies
+ */
+export class ToolExecutor {
+    constructor(registry, options = {}) {
+        Object.defineProperty(this, "registry", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "options", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.registry = registry;
+        this.options = {
+            defaultPolicy: options.defaultPolicy ?? 'parallel',
+            maxConcurrency: options.maxConcurrency ?? 10,
+            timeout: options.timeout ?? 30000,
+            validateArguments: options.validateArguments ?? true,
+            onToolStart: options.onToolStart,
+            onToolEnd: options.onToolEnd,
+            onToolError: options.onToolError,
+        };
+    }
+    /**
+     * Execute a batch of tool calls
+     * Respects individual tool execution policies
+     */
+    async execute(calls, context) {
+        if (calls.length === 0) {
+            return [];
+        }
+        // Group calls by execution policy
+        const { sequential, parallel } = this.groupByPolicy(calls);
+        const results = [];
+        // Execute sequential tools first (in order)
+        for (const call of sequential) {
+            const result = await this.executeSingle(call, context);
+            results.push(result);
+            // Stop if aborted
+            if (context.abortSignal?.aborted) {
+                break;
+            }
+        }
+        // Execute parallel tools concurrently (with concurrency limit)
+        if (parallel.length > 0 && !context.abortSignal?.aborted) {
+            const parallelResults = await this.executeParallel(parallel, context);
+            results.push(...parallelResults);
+        }
+        return results;
+    }
+    /**
+     * Execute a single tool call
+     */
+    async executeSingle(call, context) {
+        const startTime = Date.now();
+        const fullContext = { ...context, callId: call.callId };
+        // Find the tool
+        const tool = this.registry.get(call.name);
+        if (!tool) {
+            const result = {
+                toolName: call.name,
+                callId: call.callId,
+                result: null,
+                durationMs: Date.now() - startTime,
+                success: false,
+                error: `Tool '${call.name}' not found`,
+            };
+            this.options.onToolError?.(call.name, call.callId, new Error(result.error));
+            this.options.onToolEnd?.(result);
+            return result;
+        }
+        // Validate arguments if enabled
+        if (this.options.validateArguments) {
+            const validation = validateToolArguments(tool.definition, call.arguments);
+            if (!validation.valid) {
+                const errorMsg = `Invalid arguments: ${validation.errors.join(', ')}`;
+                const result = {
+                    toolName: call.name,
+                    callId: call.callId,
+                    result: null,
+                    durationMs: Date.now() - startTime,
+                    success: false,
+                    error: errorMsg,
+                };
+                this.options.onToolError?.(call.name, call.callId, new Error(errorMsg));
+                this.options.onToolEnd?.(result);
+                return result;
+            }
+        }
+        // Notify start
+        this.options.onToolStart?.(call.name, call.callId, call.arguments);
+        try {
+            // Execute with timeout
+            const result = await this.executeWithTimeout(tool, call.arguments, fullContext);
+            const toolResult = {
+                toolName: call.name,
+                callId: call.callId,
+                result,
+                durationMs: Date.now() - startTime,
+                success: true,
+            };
+            this.options.onToolEnd?.(toolResult);
+            return toolResult;
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            const toolResult = {
+                toolName: call.name,
+                callId: call.callId,
+                result: null,
+                durationMs: Date.now() - startTime,
+                success: false,
+                error: errorMessage,
+            };
+            this.options.onToolError?.(call.name, call.callId, error instanceof Error ? error : new Error(errorMessage));
+            this.options.onToolEnd?.(toolResult);
+            return toolResult;
+        }
+    }
+    /**
+     * Execute multiple tools in parallel with concurrency limit
+     */
+    async executeParallel(calls, context) {
+        const results = [];
+        const executing = [];
+        const queue = [...calls];
+        while (queue.length > 0 || executing.length > 0) {
+            // Check for abort
+            if (context.abortSignal?.aborted) {
+                break;
+            }
+            // Start new executions up to concurrency limit
+            while (executing.length < this.options.maxConcurrency && queue.length > 0) {
+                const call = queue.shift();
+                const promise = this.executeSingle(call, context).then(result => {
+                    results.push(result);
+                    const index = executing.indexOf(promise);
+                    if (index > -1) {
+                        executing.splice(index, 1);
+                    }
+                });
+                executing.push(promise);
+            }
+            // Wait for at least one to complete
+            if (executing.length > 0) {
+                await Promise.race(executing);
+            }
+        }
+        return results;
+    }
+    /**
+     * Execute a tool handler with timeout
+     */
+    async executeWithTimeout(tool, args, context) {
+        const timeoutMs = this.options.timeout;
+        // Create abort controller for timeout
+        const timeoutController = new AbortController();
+        const timeoutId = setTimeout(() => timeoutController.abort(), timeoutMs);
+        // Combine with external abort signal
+        const combinedSignal = context.abortSignal
+            ? this.combineAbortSignals(context.abortSignal, timeoutController.signal)
+            : timeoutController.signal;
+        try {
+            const result = await Promise.race([
+                tool.handler(args, { ...context, abortSignal: combinedSignal }),
+                new Promise((_, reject) => {
+                    combinedSignal.addEventListener('abort', () => {
+                        if (timeoutController.signal.aborted) {
+                            reject(new Error(`Tool execution timed out after ${timeoutMs}ms`));
+                        }
+                        else {
+                            reject(new Error('Tool execution aborted'));
+                        }
+                    });
+                }),
+            ]);
+            return result;
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    /**
+     * Combine multiple abort signals into one
+     */
+    combineAbortSignals(...signals) {
+        const controller = new AbortController();
+        for (const signal of signals) {
+            if (signal.aborted) {
+                controller.abort();
+                break;
+            }
+            signal.addEventListener('abort', () => controller.abort(), { once: true });
+        }
+        return controller.signal;
+    }
+    /**
+     * Group tool calls by their execution policy
+     */
+    groupByPolicy(calls) {
+        const sequential = [];
+        const parallel = [];
+        for (const call of calls) {
+            const tool = this.registry.get(call.name);
+            const policy = tool?.definition.executionPolicy ?? this.options.defaultPolicy;
+            if (policy === 'sequential') {
+                sequential.push(call);
+            }
+            else {
+                parallel.push(call);
+            }
+        }
+        return { sequential, parallel };
+    }
+}
+/**
+ * Create a tool executor with a new registry
+ */
+export function createToolExecutor(tools, options) {
+    const registry = new ToolRegistry();
+    registry.registerAll(tools);
+    return new ToolExecutor(registry, options);
+}
+//# sourceMappingURL=tool-executor.js.map

package/dist/tool-executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-executor.js","sourceRoot":"","sources":["../src/tool-executor.ts"],"names":[],"mappings":"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"}

package/dist/tools.d.ts

@@ -0,0 +1,183 @@
+/**
+ * Tool Types and Registry for LLM Tool Calling
+ *
+ * Provides provider-agnostic tool definitions that can be adapted
+ * to any LLM provider's tool calling format.
+ */
+/**
+ * JSON Schema property definition for tool parameters
+ */
+export interface JSONSchemaProperty {
+    type: 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'object' | 'null';
+    description?: string;
+    enum?: (string | number | boolean | null)[];
+    default?: unknown;
+    items?: JSONSchemaProperty;
+    properties?: Record<string, JSONSchemaProperty>;
+    required?: string[];
+    minimum?: number;
+    maximum?: number;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    format?: string;
+}
+/**
+ * JSON Schema definition for tool parameters
+ * Follows JSON Schema draft-07 subset supported by most LLM providers
+ */
+export interface ToolParameterSchema {
+    type: 'object';
+    properties: Record<string, JSONSchemaProperty>;
+    required?: string[];
+    additionalProperties?: boolean;
+}
+/**
+ * Provider-agnostic tool definition
+ * Can be converted to any LLM provider's format
+ */
+export interface ToolDefinition {
+    /** Unique name for the tool (used in function calls) */
+    name: string;
+    /** Human-readable description for the LLM */
+    description: string;
+    /** JSON Schema describing the parameters */
+    parameters: ToolParameterSchema;
+    /** Execution policy when multiple calls to this tool occur (default: 'parallel') */
+    executionPolicy?: 'sequential' | 'parallel';
+}
+/**
+ * Context provided to tool handlers during execution
+ */
+export interface ToolExecutionContext {
+    /** Unique identifier for this tool call */
+    callId: string;
+    /** Current session ID */
+    sessionId?: string;
+    /** Current turn ID */
+    turnId?: string;
+    /** Signal to check if execution should be aborted */
+    abortSignal?: AbortSignal;
+    /** Additional metadata from the orchestrator */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Function signature for tool handlers
+ * @template TParams - Type of the parsed parameters
+ * @template TResult - Type of the result
+ */
+export type ToolHandler<TParams = Record<string, unknown>, TResult = unknown> = (params: TParams, context: ToolExecutionContext) => Promise<TResult>;
+/**
+ * Complete tool with definition and handler
+ * @template TParams - Type of the parsed parameters
+ * @template TResult - Type of the result
+ */
+export interface Tool<TParams = Record<string, unknown>, TResult = unknown> {
+    definition: ToolDefinition;
+    handler: ToolHandler<TParams, TResult>;
+}
+/**
+ * A tool call request from the LLM
+ * Normalized from provider-specific formats
+ */
+export interface ToolCallRequest {
+    /** Provider-specific call ID for correlating results */
+    callId: string;
+    /** Name of the tool to invoke */
+    name: string;
+    /** Parsed arguments from the LLM */
+    arguments: Record<string, unknown>;
+}
+/**
+ * Result of a tool execution
+ */
+export interface ToolCallResult {
+    /** Name of the tool that was called */
+    toolName: string;
+    /** Call ID for correlation with request */
+    callId: string;
+    /** Result data (will be serialized to JSON for LLM) */
+    result: unknown;
+    /** Execution duration in milliseconds */
+    durationMs: number;
+    /** Whether execution succeeded */
+    success: boolean;
+    /** Error message if execution failed */
+    error?: string;
+}
+/**
+ * Tool choice options for LLM requests
+ * - 'auto': LLM decides whether to use tools
+ * - 'none': Disable tool use
+ * - 'required': LLM must use at least one tool
+ * - { name: string }: Force use of a specific tool
+ */
+export type ToolChoice = 'auto' | 'none' | 'required' | {
+    name: string;
+};
+/**
+ * Registry for managing tool definitions and handlers
+ * Provides lookup by name and bulk operations
+ */
+export declare class ToolRegistry {
+    private tools;
+    /**
+     * Register a tool with its handler
+     * @throws Error if a tool with the same name is already registered
+     */
+    register<TParams = Record<string, unknown>, TResult = unknown>(tool: Tool<TParams, TResult>): this;
+    /**
+     * Register multiple tools at once
+     * @throws Error if any tool name conflicts
+     */
+    registerAll(tools: Tool<unknown, unknown>[]): this;
+    /**
+     * Unregister a tool by name
+     * @returns true if the tool was found and removed
+     */
+    unregister(name: string): boolean;
+    /**
+     * Get a tool by name
+     * @returns The tool or undefined if not found
+     */
+    get<TParams = Record<string, unknown>, TResult = unknown>(name: string): Tool<TParams, TResult> | undefined;
+    /**
+     * Check if a tool is registered
+     */
+    has(name: string): boolean;
+    /**
+     * Get all registered tool names
+     */
+    names(): string[];
+    /**
+     * Get tool definitions for a subset of tools
+     * Useful for providing stage-specific tool lists
+     * @param names - Optional filter; if omitted, returns all definitions
+     */
+    getDefinitions(names?: string[]): ToolDefinition[];
+    /**
+     * Get all registered tools
+     */
+    getAll(): Tool<unknown, unknown>[];
+    /**
+     * Clear all registered tools
+     */
+    clear(): void;
+    /**
+     * Number of registered tools
+     */
+    get size(): number;
+}
+/**
+ * Create a tool definition with a handler
+ * Type-safe helper for defining tools
+ */
+export declare function defineTool<TParams = Record<string, unknown>, TResult = unknown>(definition: ToolDefinition, handler: ToolHandler<TParams, TResult>): Tool<TParams, TResult>;
+/**
+ * Validate that arguments match a tool's parameter schema
+ * Basic validation - providers typically do this, but useful for testing
+ */
+export declare function validateToolArguments(definition: ToolDefinition, args: Record<string, unknown>): {
+    valid: boolean;
+    errors: string[];
+};