ai-agent-runtime/dist/index.d.ts

Runtime adapter that bridges agent frameworks (OpenAI SDK, LangChain) with production infrastructure

import { z } from 'zod';
import { Agent } from '@openai/agents';

interface ToolDefinition {
    name: string;
    description: string;
    parameters: z.ZodObject<any>;
    execute: (input: any, config?: any) => Promise<any>;
}
interface MCPServer {
    name: string;
    url: string;
    env?: Record<string, string>;
    tools?: ToolDefinition[];
    oauth?: {
        service: string;
        userId?: string;
        envPrefix?: string;
    };
    auth?: {
        type: 'oauth' | 'bearer' | 'api-key';
        apiKey?: string;
        envVar?: string;
    };
    apiKey?: string;
}
interface ReasoningConfig {
    effort?: 'minimal' | 'low' | 'medium' | 'high';
}
interface ModelSettings {
    temperature?: number;
    topP?: number;
    frequencyPenalty?: number;
    presencePenalty?: number;
    maxTokens?: number;
    reasoning?: ReasoningConfig;
    verbosity?: 'low' | 'medium' | 'high';
    toolChoice?: 'auto' | 'required' | 'none' | string;
    parallelToolCalls?: boolean;
    truncation?: 'auto' | 'disabled';
    store?: boolean;
}
interface ToolSettings {
    behavior?: 'run_llm_again' | 'stop_on_first_tool';
    resetChoice?: boolean;
}
interface OutputSettings {
    type?: 'text' | 'structured';
    schema?: any;
}
interface GuardrailsConfig {
    input?: any[];
    output?: any[];
}
interface HandoffConfig {
    agent?: string;
    toolNameOverride?: string;
    toolDescriptionOverride?: string;
    onHandoff?: string;
    inputType?: any;
    inputFilter?: string;
}
interface AgentConfig {
    name: string;
    model?: string;
    instructions?: string;
    temperature?: number;
    maxTokens?: number;
    maxTurns?: number;
    reasoning?: ReasoningConfig;
    verbosity?: 'low' | 'medium' | 'high';
    tools?: ToolDefinition[];
    mcpServers?: MCPServer[];
    enabledTools?: string[];
    toolConfigurations?: Record<string, any>;
    modelSettings?: ModelSettings;
    toolSettings?: ToolSettings;
    outputSettings?: OutputSettings;
    guardrails?: GuardrailsConfig;
    handoffs?: HandoffConfig[];
    prompt?: string;
}
interface ChatSession {
    id: string;
    agent: Agent;
    history: Message[];
    context: Map<string, any>;
}
interface Message {
    role: 'user' | 'assistant' | 'system' | 'tool';
    content: string;
    toolCalls?: ToolCall[];
    timestamp: Date;
}
interface ToolCall {
    id: string;
    name: string;
    arguments: any;
    result?: any;
}
interface RuntimeOptions {
    model?: string;
    temperature?: number;
    maxTokens?: number;
    verbose?: boolean;
    port?: number;
    apiKey?: string;
}
interface AgentManifest {
    name: string;
    version: string;
    description?: string;
    author?: string;
    license?: string;
    model: string;
    instructions: string;
    temperature?: number;
    maxTurns?: number;
    reasoning?: ReasoningConfig;
    verbosity?: 'low' | 'medium' | 'high';
    mcpServers?: Array<{
        name: string;
        url: string;
        env?: Record<string, string>;
        required?: boolean;
        oauth?: {
            service: string;
            scopes?: string[];
            userId?: string;
            envPrefix?: string;
        };
    }>;
    requiredEnvVars?: string[];
    tags?: string[];
    category?: string;
    a2aCapabilities?: Array<{
        name: string;
        description: string;
        inputSchema?: any;
        outputSchema?: any;
    }>;
    enabledTools?: string[];
    toolConfigurations?: Record<string, any>;
    modelSettings?: ModelSettings;
    toolSettings?: ToolSettings;
    outputSettings?: OutputSettings;
    guardrails?: GuardrailsConfig;
    handoffs?: HandoffConfig[];
    prompt?: string;
}
interface ErrorContext {
    operation?: string;
    toolName?: string;
    parameters?: any;
    userInput?: string;
    timestamp: Date;
    sessionId?: string;
}
interface EnhancedError {
    message: string;
    code?: string;
    context: ErrorContext;
    recovery?: {
        suggestedActions: string[];
        canRetry: boolean;
        alternativeCommands?: string[];
    };
}
interface ToolExecutionState {
    id: string;
    toolName: string;
    parameters: any;
    status: 'pending' | 'running' | 'completed' | 'failed';
    startTime: Date;
    endTime?: Date;
    result?: any;
    error?: EnhancedError;
}
interface ValidationIssue {
    type: 'truncated' | 'mixed_content' | 'empty' | 'corrupted' | 'incomplete_tool';
    severity: 'error' | 'warning';
    description: string;
    location?: string;
}
interface ValidationResult {
    isValid: boolean;
    issues: ValidationIssue[];
    canRecover: boolean;
    suggestedFixes?: string[];
    cleanedContent?: string;
}

declare class AgentRuntime {
    private agentFactory;
    private agent;
    private conversationManager;
    private config;
    private options;
    constructor(options?: RuntimeOptions);
    /**
     * Initialize the runtime with an agent manifest
     */
    initialize(manifest: AgentManifest, customTools?: ToolDefinition[]): Promise<void>;
    /**
     * Process a single message and return the response
     */
    chat(message: string): Promise<string>;
    /**
     * Process a message with streaming response
     */
    chatStream(message: string, onChunk?: (text: string) => void): Promise<string>;
    /**
     * Get conversation history
     */
    getHistory(): Message[];
    /**
     * Clear conversation history
     */
    clearHistory(): void;
    /**
     * Get agent configuration
     */
    getConfig(): AgentConfig | null;
    /**
     * Add custom tools after initialization
     */
    addTools(tools: ToolDefinition[]): void;
    /**
     * Reinitialize the runtime (useful when OAuth tokens become available)
     */
    reinitialize(manifest: AgentManifest, customTools?: ToolDefinition[]): Promise<void>;
    /**
     * Clean up resources
     */
    cleanup(): Promise<void>;
    private buildConfigFromManifest;
}
/**
 * Convenience function to create and initialize an agent runtime
 */
declare function createAgentRuntime(manifest: AgentManifest, customTools?: ToolDefinition[], options?: RuntimeOptions): Promise<AgentRuntime>;

interface TaskRequest {
    instruction: string;
    content?: Array<{
        type: 'text' | 'image' | 'file';
        text?: string;
        url?: string;
        data?: string;
    }>;
    metadata?: Record<string, any>;
}
interface Task {
    id: string;
    status: 'submitted' | 'working' | 'input-required' | 'completed' | 'failed';
    instruction: string;
    content?: Array<any>;
    metadata?: Record<string, any>;
    result?: any;
    error?: string;
    created: string;
    updated: string;
}
interface AgentCapabilities {
    name: string;
    version: string;
    description: string;
    capabilities: {
        streaming: boolean;
        multimodal: string[];
        authentication?: string[];
    };
    skills: Array<{
        name: string;
        description: string;
        input_types: string[];
        output_types: string[];
    }>;
    endpoints: {
        rpc: string;
        health: string;
        wellknown: string;
    };
}
interface JsonRpcRequest {
    jsonrpc: '2.0';
    id?: string | number;
    method: string;
    params: any;
}
interface JsonRpcResponse {
    jsonrpc: '2.0';
    id?: string | number;
    result?: any;
    error?: {
        code: number;
        message: string;
        data?: any;
    };
}
declare class AgentHttpServer {
    private app;
    private runtime;
    private manifest;
    private tasks;
    private taskSubscriptions;
    private capabilities;
    private port;
    private server?;
    constructor(manifest: AgentManifest, customTools?: ToolDefinition[], port?: number);
    private setupMiddleware;
    private setupRoutes;
    private buildCapabilities;
    private handleAgentDiscovery;
    private handleJsonRpc;
    private handleTaskSend;
    private handleTaskSendSubscribe;
    private processTask;
    private handleTaskGet;
    private handleTaskCancel;
    private notifyTaskSubscribers;
    private sendTaskEvent;
    private handleHealth;
    private handleMetrics;
    private handleGetTask;
    private handleError;
    start(customTools?: ToolDefinition[]): Promise<void>;
    stop(): Promise<void>;
}
/**
 * Convenience function to create and start an agent HTTP server
 */
declare function createAgentHttpServer(manifest: AgentManifest, customTools?: ToolDefinition[], port?: number): Promise<AgentHttpServer>;

declare class ToolRegistry {
    private tools;
    register(tool: ToolDefinition): void;
    registerMany(tools: ToolDefinition[]): void;
    unregister(name: string): boolean;
    get(name: string): ToolDefinition | undefined;
    getAllTools(): ToolDefinition[];
    getToolNames(): string[];
    has(name: string): boolean;
    clear(): void;
    size(): number;
}

declare class MCPManager {
    private servers;
    private clients;
    registerServer(server: MCPServer): Promise<void>;
    loadServerTools(server: MCPServer): Promise<ToolDefinition[]>;
    private connectToServer;
    private connectToStdioServer;
    private connectToHttpServer;
    private buildHttpHeaders;
    private getOrCreateClient;
    private injectOAuthTokens;
    private isOAuthRelatedError;
    private createOAuthErrorMessage;
    private isApiKeyAuthError;
    private createApiKeyErrorMessage;
    private getPossibleApiKeyEnvVars;
    disconnectAll(): Promise<void>;
    getServer(name: string): MCPServer | undefined;
    getAllServers(): MCPServer[];
}

declare class AgentFactory {
    private toolRegistry;
    private mcpManager;
    private openai;
    private currentModel;
    constructor();
    createAgent(config: AgentConfig): Promise<Agent>;
    private buildModelSettings;
    private loadTools;
    private convertToAgentTool;
    /**
     * Wrap tool execution with intelligent chunking for large responses
     */
    private wrapExecuteWithChunking;
    /**
     * Process large tool responses by chunking and iterative analysis
     */
    private processLargeToolResponse;
    /**
     * Analyze a single chunk using the OpenAI model
     */
    private analyzeChunkWithModel;
    /**
     * Create analysis prompt for a single chunk
     */
    private createChunkAnalysisPrompt;
    /**
     * Aggregate chunk analyses into a coherent final response
     */
    private aggregateChunkAnalyses;
    /**
     * Create synthesis prompt for combining chunk analyses
     */
    private createSynthesisPrompt;
    private buildToolAwareInstructions;
    registerTool(tool: ToolDefinition): void;
    registerTools(tools: ToolDefinition[]): void;
    registerMCPServer(server: MCPServer): Promise<void>;
    getToolRegistry(): ToolRegistry;
    getMCPManager(): MCPManager;
    cleanup(): Promise<void>;
}

declare class ConversationManager {
    private session;
    private maxTurns;
    private executionTracker;
    private responseValidator;
    constructor(session: ChatSession);
    processUserMessage(userInput: string, abortSignal?: AbortSignal): Promise<Message>;
    processUserMessageStream(userInput: string, onChunk?: (text: string) => void): Promise<Message>;
    setMaxTurns(max: number): void;
    clearHistory(): void;
    getHistory(): Message[];
    getSession(): ChatSession;
    getExecutionStats(): {
        active: number;
        completed: number;
        failed: number;
        averageDuration: number;
    };
    getExecutionHistory(toolName?: string): ToolExecutionState[];
    private buildContextualInput;
}

declare class ExecutionTracker {
    private activeExecutions;
    private completedExecutions;
    private maxCompletedHistory;
    getActiveExecution(toolName: string): ToolExecutionState | undefined;
    getAllActiveExecutions(): ToolExecutionState[];
    startExecution(toolName: string, parameters: any): string;
    completeExecution(id: string, result: any): void;
    failExecution(id: string, error: EnhancedError): void;
    getExecutionHistory(toolName?: string): ToolExecutionState[];
    clearHistory(): void;
    getExecutionStats(): {
        active: number;
        completed: number;
        failed: number;
        averageDuration: number;
    };
    hasActiveExecutions(): boolean;
    cancelAllExecutions(): void;
}

declare class ResponseValidator {
    validateResponse(response: Message): ValidationResult;
    private isLikelyTruncated;
    private containsMixedContent;
    private hasIncompleteToolOutput;
    private hasCorruptedFormatting;
    private canRecoverFromIssues;
    private getSuggestedFixes;
    private cleanContent;
}

declare const shellTool: ToolDefinition;
declare const readFileTool: ToolDefinition;
declare const writeFileTool: ToolDefinition;
declare const listDirectoryTool: ToolDefinition;
declare const webSearchTool: ToolDefinition;
declare const calculatorTool: ToolDefinition;
declare const analyzePdfTool: ToolDefinition;
declare const generatePdfTool: ToolDefinition;
declare const discoverAgentsTool: ToolDefinition;
declare const sendAgentTaskTool: ToolDefinition;
declare const getTaskStatusTool: ToolDefinition;
declare const getAgentCapabilitesTool: ToolDefinition;
declare const firstPrinciplesAnalysisTool: ToolDefinition;
declare const getCoreBuiltInTools: () => ToolDefinition[];
declare const getInterAgentTools: () => ToolDefinition[];
declare const getBuiltInTools: () => ToolDefinition[];
declare const getAllAvailableTools: () => ToolDefinition[];

/**
 * Load and parse an agent manifest from a file
 */
declare function loadManifestFromFile(filePath: string): Promise<AgentManifest>;
/**
 * Validate an agent manifest object
 */
declare function validateManifest(data: any): AgentManifest;

export { type AgentCapabilities, type AgentConfig, AgentFactory, AgentHttpServer, type AgentManifest, AgentRuntime, type ChatSession, ConversationManager, ExecutionTracker, type JsonRpcRequest, type JsonRpcResponse, MCPManager, type MCPServer, type Message, ResponseValidator, type RuntimeOptions, type Task, type TaskRequest, type ToolCall, type ToolDefinition, ToolRegistry, analyzePdfTool, calculatorTool, createAgentHttpServer, createAgentRuntime, discoverAgentsTool, firstPrinciplesAnalysisTool, generatePdfTool, getAgentCapabilitesTool, getAllAvailableTools, getBuiltInTools, getCoreBuiltInTools, getInterAgentTools, getTaskStatusTool, listDirectoryTool, loadManifestFromFile, readFileTool, sendAgentTaskTool, shellTool, validateManifest, webSearchTool, writeFileTool };