@kjerneverk/agentic 1.0.6 → 1.0.7-dev.20260212012257.575e470

package/dist/index.d.ts

@@ -11,6 +11,243 @@
 
 import { ZodSchema } from 'zod';
 
+/**
+ * A chunk yielded during agent execution
+ */
+export declare interface AgentChunk {
+    type: AgentChunkType;
+    /** Text content (for type='text') */
+    text?: string;
+    /** Tool information (for tool_start/tool_result) */
+    tool?: {
+        id: string;
+        name: string;
+        arguments?: Record<string, any>;
+        result?: string;
+        error?: string;
+        duration?: number;
+    };
+    /** Error information (for type='error') */
+    error?: {
+        message: string;
+        code?: string;
+    };
+    /** Metadata */
+    meta?: {
+        iteration?: number;
+        tokenUsage?: {
+            input: number;
+            output: number;
+        };
+    };
+}
+
+/**
+ * Streaming chunk types from the agent loop
+ */
+export declare type AgentChunkType = 'text' | 'tool_start' | 'tool_result' | 'turn_complete' | 'done' | 'error';
+
+/**
+ * Execution options
+ */
+export declare interface AgentExecutionOptions {
+    apiKey?: string;
+    model?: string;
+    temperature?: number;
+    maxTokens?: number;
+}
+
+/**
+ * AgentLoop orchestrates multi-turn LLM conversations with tool use.
+ *
+ * The loop:
+ * 1. Sends messages + tool definitions to LLM
+ * 2. Parses response for tool calls
+ * 3. Executes tool calls via ToolRegistry
+ * 4. Formats tool results as messages
+ * 5. Feeds back to LLM
+ * 6. Repeats until LLM responds with text (no tool calls)
+ */
+export declare class AgentLoop {
+    private provider;
+    private toolRegistry;
+    private conversation;
+    private model;
+    private maxIterations;
+    private events;
+    private logger;
+    private executionOptions;
+    private cancelled;
+    private constructor();
+    /**
+     * Create a new AgentLoop instance
+     */
+    static create(options: AgentLoopOptions): AgentLoop;
+    /**
+     * Set the system prompt
+     */
+    setSystemPrompt(prompt: string): void;
+    /**
+     * Get the conversation manager
+     */
+    getConversation(): ConversationManager;
+    /**
+     * Cancel the current execution
+     */
+    cancel(): void;
+    /**
+     * Reset cancellation state
+     */
+    resetCancellation(): void;
+    /**
+     * Run the agent loop with a user message (non-streaming)
+     */
+    run(userMessage: string): Promise<AgentLoopResult>;
+    /**
+     * Run the agent loop with streaming output
+     */
+    runStream(userMessage: string): AsyncIterable<AgentChunk>;
+    /**
+     * Execute tool calls and yield streaming results
+     */
+    private executeToolCallsStreaming;
+    /**
+     * Build a request object for the provider
+     */
+    private buildRequest;
+    /**
+     * Get tool definitions in provider-agnostic format
+     */
+    private getToolDefinitions;
+    /**
+     * Build ToolCall array from accumulated streaming data
+     */
+    private buildToolCalls;
+}
+
+/**
+ * Events emitted by the agent loop
+ */
+export declare interface AgentLoopEvents {
+    onToolCallStart?: (toolName: string, args: Record<string, any>) => void;
+    onToolCallComplete?: (toolName: string, result: any, duration: number) => void;
+    onToolCallError?: (toolName: string, error: Error) => void;
+    onLLMRequest?: (messages: ConversationMessage[]) => void;
+    onLLMResponse?: (content: string | null, toolCalls?: ToolCall[]) => void;
+    onIterationStart?: (iteration: number) => void;
+    onIterationComplete?: (iteration: number) => void;
+}
+
+/**
+ * Options for creating an AgentLoop
+ */
+export declare interface AgentLoopOptions {
+    /** The LLM provider to use */
+    provider: AgentProvider;
+    /** Tool registry with available tools */
+    toolRegistry: ToolRegistry;
+    /** Conversation manager (optional, will create one if not provided) */
+    conversation?: ConversationManager;
+    /** Model to use */
+    model?: string;
+    /** Maximum iterations before stopping (default: 10) */
+    maxIterations?: number;
+    /** Event handlers */
+    events?: AgentLoopEvents;
+    /** Logger */
+    logger?: Logger;
+    /** Execution options passed to provider */
+    executionOptions?: AgentExecutionOptions;
+}
+
+/**
+ * Result of running the agent loop
+ */
+export declare interface AgentLoopResult {
+    /** Final text response from the agent */
+    response: string;
+    /** Number of iterations executed */
+    iterations: number;
+    /** Tool calls made during execution */
+    toolCalls: Array<{
+        name: string;
+        arguments: Record<string, any>;
+        result: any;
+        duration: number;
+    }>;
+    /** Total token usage */
+    tokenUsage?: {
+        input: number;
+        output: number;
+    };
+    /** Whether the loop was cancelled */
+    cancelled: boolean;
+}
+
+/**
+ * Provider interface for the agent loop
+ * Compatible with execution package providers
+ */
+export declare interface AgentProvider {
+    readonly name: string;
+    execute(request: AgentRequest, options?: AgentExecutionOptions): Promise<AgentProviderResponse>;
+    executeStream?(request: AgentRequest, options?: AgentExecutionOptions): AsyncIterable<AgentStreamChunk>;
+}
+
+/**
+ * Response from the provider
+ */
+export declare interface AgentProviderResponse {
+    content: string;
+    model: string;
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+    toolCalls?: ToolCall[];
+}
+
+/**
+ * Request to the provider
+ */
+export declare interface AgentRequest {
+    messages: ConversationMessage[];
+    model: string;
+    tools?: AgentToolDefinition[];
+    addMessage(message: ConversationMessage): void;
+}
+
+/**
+ * Streaming chunk from provider
+ */
+export declare interface AgentStreamChunk {
+    type: 'text' | 'tool_call_start' | 'tool_call_delta' | 'tool_call_end' | 'usage' | 'done';
+    text?: string;
+    toolCall?: {
+        id?: string;
+        index?: number;
+        name?: string;
+        argumentsDelta?: string;
+    };
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+}
+
+/**
+ * Tool definition for the agent
+ */
+export declare interface AgentToolDefinition {
+    name: string;
+    description: string;
+    parameters: {
+        type: 'object';
+        properties: Record<string, any>;
+        required?: string[];
+    };
+}
+
 /**
  * Anthropic-compatible tool format
  */
@@ -118,6 +355,144 @@ export declare interface ContextStats {
     newestTimestamp?: Date;
 }
 
+/**
+ * ConversationManager manages message history for agent conversations.
+ *
+ * Features:
+ * - Add/retrieve messages
+ * - Handle provider-specific format differences
+ * - Serialize/deserialize for persistence
+ * - Token budget awareness and compression
+ */
+export declare class ConversationManager {
+    private messages;
+    private logger;
+    private tokenBudget?;
+    private tokenCounter?;
+    private createdAt;
+    private updatedAt;
+    private constructor();
+    /**
+     * Create a new ConversationManager instance
+     */
+    static create(options?: ConversationManagerOptions): ConversationManager;
+    /**
+     * Create from serialized state
+     */
+    static fromSerialized(data: SerializedConversation, options?: ConversationManagerOptions): ConversationManager;
+    /**
+     * Add a system message (will be placed at the beginning)
+     */
+    addSystemMessage(content: string): void;
+    /**
+     * Add a user message
+     */
+    addUserMessage(content: string): void;
+    /**
+     * Add an assistant message (text response)
+     */
+    addAssistantMessage(content: string): void;
+    /**
+     * Add an assistant message with tool calls
+     */
+    addAssistantToolCalls(toolCalls: ToolCall[], content?: string): void;
+    /**
+     * Add a tool result message
+     */
+    addToolResult(toolCallId: string, result: string): void;
+    /**
+     * Add a raw message (any role)
+     */
+    addMessage(message: ConversationMessage): void;
+    /**
+     * Get all messages
+     */
+    getMessages(): ConversationMessage[];
+    /**
+     * Get messages in a format suitable for the provider
+     * This handles any provider-specific transformations
+     */
+    getMessagesForProvider(_provider: 'anthropic' | 'openai'): ConversationMessage[];
+    /**
+     * Get the system prompt (if any)
+     */
+    getSystemPrompt(): string | undefined;
+    /**
+     * Get the last message
+     */
+    getLastMessage(): ConversationMessage | undefined;
+    /**
+     * Get the last assistant message
+     */
+    getLastAssistantMessage(): ConversationMessage | undefined;
+    /**
+     * Get message count
+     */
+    count(): number;
+    /**
+     * Check if conversation is empty
+     */
+    isEmpty(): boolean;
+    /**
+     * Clear all messages except system prompt
+     */
+    clearHistory(): void;
+    /**
+     * Clear everything including system prompt
+     */
+    clear(): void;
+    /**
+     * Serialize conversation for persistence
+     */
+    serialize(): SerializedConversation;
+    /**
+     * Get token usage information
+     */
+    getTokenUsage(): TokenUsage | undefined;
+    /**
+     * Check token budget and compress if needed
+     */
+    private checkTokenBudget;
+    /**
+     * Handle budget exceeded based on configuration
+     */
+    private handleBudgetExceeded;
+    /**
+     * Compress conversation to fit within budget
+     */
+    private compressConversation;
+    /**
+     * Truncate conversation to fit within budget
+     */
+    private truncateConversation;
+    /**
+     * Check if currently over budget
+     */
+    private isOverBudget;
+    /**
+     * Get a summary of the conversation for debugging
+     */
+    getSummary(): {
+        messageCount: number;
+        roles: Record<string, number>;
+        hasSystemPrompt: boolean;
+        lastRole?: string;
+        tokenUsage?: TokenUsage;
+    };
+}
+
+/**
+ * Options for creating a ConversationManager
+ */
+export declare interface ConversationManagerOptions {
+    /** Optional logger */
+    logger?: Logger;
+    /** Token budget configuration for context window management */
+    tokenBudget?: TokenBudgetConfig;
+    /** Function to count tokens in a message */
+    tokenCounter?: (message: ConversationMessage) => number;
+}
+
 export declare interface ConversationMessage {
     role: 'system' | 'user' | 'assistant' | 'tool' | 'developer';
     content: string | null;
@@ -291,6 +666,19 @@ export declare interface SandboxOptions {
     onAfterExecution?: (tool: Tool, result: unknown, error?: Error) => void | Promise<void>;
 }
 
+/**
+ * Serialized conversation state for persistence
+ */
+export declare interface SerializedConversation {
+    messages: ConversationMessage[];
+    metadata: {
+        createdAt: string;
+        updatedAt: string;
+        messageCount: number;
+        systemPrompt?: string;
+    };
+}
+
 /**
  * Current state of strategy execution
  */