@kjerneverk/agentic 1.0.5-dev.0

package/dist/index.d.ts

@@ -0,0 +1,770 @@
+/**
+ * Agentic Package
+ *
+ * Components for building agentic AI workflows:
+ * - Tool registry and execution
+ * - Context management
+ * - Conversation state tracking
+ *
+ * @packageDocumentation
+ */
+
+import { ZodSchema } from 'zod';
+
+/**
+ * Anthropic-compatible tool format
+ */
+export declare interface AnthropicTool {
+    name: string;
+    description: string;
+    input_schema: {
+        type: 'object';
+        properties: Record<string, any>;
+        required?: string[];
+    };
+}
+
+/**
+ * Compression statistics
+ */
+export declare interface CompressionStats {
+    messagesBefore: number;
+    messagesAfter: number;
+    tokensBefore: number;
+    tokensAfter: number;
+    tokensSaved: number;
+    strategy: CompressionStrategy;
+}
+
+/**
+ * Compression strategy
+ */
+export declare type CompressionStrategy = 'priority-based' | 'fifo' | 'summarize' | 'adaptive';
+
+/**
+ * ContextManager tracks and manages dynamically injected context.
+ */
+export declare class ContextManager {
+    private items;
+    private hashes;
+    private logger;
+    constructor(logger?: Logger);
+    /**
+     * Track a context item
+     */
+    track(item: DynamicContentItem, position: number): void;
+    /**
+     * Check if context with given ID exists
+     */
+    hasContext(id: string): boolean;
+    /**
+     * Check if content with given hash exists
+     */
+    hasContentHash(content: string): boolean;
+    /**
+     * Check if similar content exists (fuzzy match)
+     */
+    hasSimilarContent(content: string, similarityThreshold?: number): boolean;
+    /**
+     * Get context item by ID
+     */
+    get(id: string): TrackedContextItem | undefined;
+    /**
+     * Get all tracked context items
+     */
+    getAll(): TrackedContextItem[];
+    /**
+     * Get context items by category
+     */
+    getByCategory(category: string): TrackedContextItem[];
+    /**
+     * Get context items by priority
+     */
+    getByPriority(priority: 'high' | 'medium' | 'low'): TrackedContextItem[];
+    /**
+     * Get context items by source
+     */
+    getBySource(source: string): TrackedContextItem[];
+    /**
+     * Get all categories
+     */
+    getCategories(): string[];
+    /**
+     * Get context statistics
+     */
+    getStats(): ContextStats;
+    /**
+     * Remove context item by ID
+     */
+    remove(id: string): boolean;
+    /**
+     * Clear all tracked context
+     */
+    clear(): void;
+    private generateId;
+    private hashContent;
+    private normalizeContent;
+}
+
+/**
+ * Context statistics
+ */
+export declare interface ContextStats {
+    totalItems: number;
+    byCategory: Map<string, number>;
+    byPriority: Map<string, number>;
+    bySource: Map<string, number>;
+    oldestTimestamp?: Date;
+    newestTimestamp?: Date;
+}
+
+export declare interface ConversationMessage {
+    role: 'system' | 'user' | 'assistant' | 'tool' | 'developer';
+    content: string | null;
+    name?: string;
+    tool_calls?: ToolCall[];
+    tool_call_id?: string;
+}
+
+/**
+ * Create a security-wrapped version of a tool
+ */
+export declare function createSecureTool(tool: Tool, sandbox: ToolSandbox, guard: ToolGuard): Tool;
+
+/**
+ * Default logger - silent by default to prevent information disclosure
+ *
+ * Enable logging by setting one of:
+ * - AGENTIC_LOGGING=true
+ * - DEBUG=*agentic*
+ * - NODE_ENV=development
+ */
+export declare const DEFAULT_LOGGER: Logger;
+
+/**
+ * Dynamic content item with enhanced tracking and lifecycle
+ */
+export declare interface DynamicContentItem {
+    content: string;
+    title?: string;
+    weight?: number;
+    id?: string;
+    category?: string;
+    source?: string;
+    priority?: 'high' | 'medium' | 'low';
+    timestamp?: Date;
+}
+
+/**
+ * Options for injecting context
+ */
+export declare interface InjectOptions {
+    position?: 'end' | 'before-last' | 'after-system' | number;
+    format?: 'structured' | 'inline' | 'reference';
+    deduplicate?: boolean;
+    deduplicateBy?: 'id' | 'content' | 'hash';
+    priority?: 'high' | 'medium' | 'low';
+    weight?: number;
+    category?: string;
+    source?: string;
+}
+
+/**
+ * Insight discovered during execution
+ */
+export declare interface Insight {
+    source: string;
+    content: string;
+    confidence: number;
+    relatedTo?: string[];
+}
+
+/**
+ * Action to take after iteration
+ */
+export declare type IterationAction = 'continue' | 'stop' | 'next-phase';
+
+/**
+ * Agentic Package - Logger
+ *
+ * Shared logging infrastructure backed by @fjell/logging for
+ * comprehensive sensitive data masking and structured logging.
+ */
+export declare const LIBRARY_NAME = "agentic";
+
+/**
+ * LLM client interface (generic, provider-agnostic)
+ */
+export declare interface LLMClient {
+    complete(messages: ConversationMessage[], tools?: any[]): Promise<{
+        content: string | null;
+        tool_calls?: ToolCall[];
+    }>;
+}
+
+/**
+ * Log configuration
+ */
+export declare interface LogConfig {
+    enabled: boolean;
+    outputPath?: string;
+    format?: LogFormat;
+    filenameTemplate?: string;
+    includeMetadata?: boolean;
+    includePrompt?: boolean;
+    redactSensitive?: boolean;
+    redactPatterns?: RegExp[];
+    onSaved?: (path: string) => void;
+    onError?: (error: Error) => void;
+}
+
+/**
+ * Log format
+ */
+export declare type LogFormat = 'json' | 'markdown' | 'jsonl';
+
+export declare interface Logger {
+    name: string;
+    debug: (message: string, ...args: any[]) => void;
+    info: (message: string, ...args: any[]) => void;
+    warn: (message: string, ...args: any[]) => void;
+    error: (message: string, ...args: any[]) => void;
+    verbose: (message: string, ...args: any[]) => void;
+    silly: (message: string, ...args: any[]) => void;
+    /** Get a child logger for a component */
+    get?: (...components: string[]) => Logger;
+}
+
+/**
+ * Agentic Package - Types
+ *
+ * Core type definitions for agentic workflows.
+ */
+export declare type Model = string;
+
+/**
+ * OpenAI-compatible tool format
+ */
+export declare interface OpenAITool {
+    type: 'function';
+    function: {
+        name: string;
+        description: string;
+        parameters: {
+            type: 'object';
+            properties: Record<string, any>;
+            required?: string[];
+        };
+    };
+}
+
+/**
+ * Result of a phase
+ */
+export declare interface PhaseResult {
+    name: string;
+    iterations: number;
+    toolCalls: number;
+    success: boolean;
+    insights?: Insight[];
+}
+
+/**
+ * Extended context with sandbox restrictions
+ */
+export declare interface SandboxedContext extends ToolContext {
+    readonly sandbox: {
+        allowedOperations: Set<string>;
+        maxOutputSize: number;
+        executionId: string;
+    };
+}
+
+/**
+ * Options for sandbox execution
+ */
+export declare interface SandboxOptions {
+    maxExecutionTime: number;
+    maxOutputSize: number;
+    allowedOperations?: string[];
+    onBeforeExecution?: (tool: Tool, params: unknown) => void | Promise<void>;
+    onAfterExecution?: (tool: Tool, result: unknown, error?: Error) => void | Promise<void>;
+}
+
+/**
+ * Current state of strategy execution
+ */
+export declare interface StrategyState {
+    phase: string | number;
+    iteration: number;
+    toolCallsExecuted: number;
+    startTime: number;
+    insights: Insight[];
+    findings: any[];
+    errors: Error[];
+    toolFailures: Map<string, number>;
+    [key: string]: any;
+}
+
+/**
+ * Token budget configuration
+ */
+export declare interface TokenBudgetConfig {
+    max: number;
+    reserveForResponse: number;
+    warningThreshold?: number;
+    strategy: CompressionStrategy;
+    onBudgetExceeded: 'compress' | 'error' | 'warn' | 'truncate';
+    preserveRecent?: number;
+    preserveSystem?: boolean;
+    preserveHighPriority?: boolean;
+    onWarning?: (usage: TokenUsage) => void;
+    onCompression?: (stats: CompressionStats) => void;
+}
+
+/**
+ * Token usage information
+ */
+export declare interface TokenUsage {
+    used: number;
+    max: number;
+    remaining: number;
+    percentage: number;
+}
+
+/**
+ * Tool definition
+ */
+export declare interface Tool {
+    name: string;
+    description: string;
+    parameters: {
+        type: 'object';
+        properties: Record<string, ToolParameter>;
+        required?: string[];
+    };
+    execute: (params: any, context?: ToolContext) => Promise<any>;
+    category?: string;
+    cost?: ToolCost;
+    examples?: ToolExample[];
+    /** Optional Zod schema for parameter validation */
+    schema?: ZodSchema<any>;
+}
+
+export declare interface ToolCall {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+
+/**
+ * Action to take for tool call
+ */
+export declare type ToolCallAction = 'execute' | 'skip' | 'defer';
+
+/**
+ * Context provided to tool execution
+ */
+export declare interface ToolContext {
+    workingDirectory?: string;
+    storage?: any;
+    logger?: Logger;
+    conversationState?: any;
+    [key: string]: any;
+}
+
+/**
+ * Cost hint for tool execution
+ */
+export declare type ToolCost = 'cheap' | 'moderate' | 'expensive';
+
+/**
+ * Tool definition for export
+ */
+export declare interface ToolDefinition {
+    name: string;
+    description: string;
+    parameters: Tool['parameters'];
+    category?: string;
+    cost?: ToolCost;
+    examples?: ToolExample[];
+    schema?: ZodSchema<any>;
+}
+
+/**
+ * Example usage of a tool
+ */
+export declare interface ToolExample {
+    scenario: string;
+    params: any;
+    expectedResult: string;
+}
+
+/**
+ * Tool execution result
+ */
+export declare interface ToolExecutionResult {
+    success: boolean;
+    result?: any;
+    error?: string;
+    duration?: number;
+}
+
+/**
+ * ToolGuard provides security validation for tool execution.
+ *
+ * Features:
+ * - Schema-based parameter validation with Zod
+ * - Prototype pollution detection
+ * - Tool allow/deny lists
+ * - Event callbacks for security monitoring
+ *
+ * @example
+ * ```typescript
+ * const guard = new ToolGuard({ deniedTools: ['dangerous_tool'] });
+ *
+ * // Validate parameters
+ * const schema = z.object({ path: z.string() });
+ * const result = guard.validateParams('read_file', { path: '/test' }, schema);
+ *
+ * // Check if tool is allowed
+ * if (guard.isToolAllowed('my_tool')) {
+ *   // execute tool
+ * }
+ * ```
+ */
+export declare class ToolGuard {
+    private config;
+    private logger;
+    private events;
+    constructor(config?: Partial<ToolSecurityConfig>, logger?: Logger, events?: ToolGuardEvents);
+    /**
+     * Validate tool parameters against a Zod schema
+     */
+    validateParams<T>(toolName: string, params: unknown, schema: ZodSchema<T>): ToolValidationResult<T>;
+    /**
+     * Safely parse JSON tool arguments
+     */
+    parseToolArguments(toolName: string, jsonString: string): ToolValidationResult<Record<string, unknown>>;
+    /**
+     * Check if a tool is allowed to execute
+     */
+    isToolAllowed(toolName: string): boolean;
+    /**
+     * Get current configuration
+     */
+    getConfig(): Readonly<ToolSecurityConfig>;
+    /**
+     * Update configuration
+     */
+    updateConfig(config: Partial<ToolSecurityConfig>): void;
+    /**
+     * Add a tool to the deny list
+     */
+    denyTool(toolName: string): void;
+    /**
+     * Remove a tool from the deny list
+     */
+    allowTool(toolName: string): void;
+    /**
+     * Check if security is enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Enable or disable security
+     */
+    setEnabled(enabled: boolean): void;
+    /**
+     * Detect prototype pollution attempts
+     */
+    private hasPrototypePollution;
+}
+
+/**
+ * Event handlers for security events
+ */
+export declare interface ToolGuardEvents {
+    onValidationFailed?: (toolName: string, message: string) => void;
+    onExecutionBlocked?: (toolName: string, reason: string) => void;
+    onPrototypePollution?: (toolName: string) => void;
+}
+
+/**
+ * Parameter definition for a tool
+ */
+export declare interface ToolParameter {
+    type: 'string' | 'number' | 'boolean' | 'array' | 'object';
+    description: string;
+    items?: ToolParameter;
+    properties?: Record<string, ToolParameter>;
+    required?: string[];
+    enum?: string[];
+    default?: any;
+}
+
+/**
+ * ToolRegistry manages tool definitions and execution.
+ */
+export declare class ToolRegistry {
+    private tools;
+    private context;
+    private logger;
+    private usageStats;
+    private toolGuard?;
+    private toolSandbox?;
+    private constructor();
+    /**
+     * Create a new ToolRegistry instance
+     */
+    static create(context?: ToolContext, logger?: Logger): ToolRegistry;
+    /**
+     * Configure security guard for tool execution
+     */
+    withSecurity(guard: ToolGuard): this;
+    /**
+     * Get the configured security guard
+     */
+    getSecurityGuard(): ToolGuard | undefined;
+    /**
+     * Configure sandbox for tool execution
+     */
+    withSandbox(sandbox: ToolSandbox): this;
+    /**
+     * Get the configured sandbox
+     */
+    getSandbox(): ToolSandbox | undefined;
+    /**
+     * Register a single tool
+     */
+    register(tool: Tool): void;
+    /**
+     * Register multiple tools at once
+     */
+    registerAll(tools: Tool[]): void;
+    /**
+     * Get a tool by name
+     */
+    get(name: string): Tool | undefined;
+    /**
+     * Get all registered tools
+     */
+    getAll(): Tool[];
+    /**
+     * Get tools by category
+     */
+    getByCategory(category: string): Tool[];
+    /**
+     * Check if a tool is registered
+     */
+    has(name: string): boolean;
+    /**
+     * Get number of registered tools
+     */
+    count(): number;
+    /**
+     * Execute a tool by name
+     */
+    execute(name: string, params: any): Promise<any>;
+    /**
+     * Safely parse and execute a tool from JSON arguments
+     */
+    executeFromJSON(name: string, jsonArgs: string): Promise<any>;
+    /**
+     * Execute multiple tools in sequence
+     */
+    executeBatch(calls: Array<{
+        name: string;
+        params: any;
+    }>): Promise<any[]>;
+    /**
+     * Export tools in OpenAI format
+     */
+    toOpenAIFormat(): OpenAITool[];
+    /**
+     * Export tools in Anthropic format
+     */
+    toAnthropicFormat(): AnthropicTool[];
+    /**
+     * Get tool definitions (without execute function)
+     */
+    getDefinitions(): ToolDefinition[];
+    /**
+     * Get usage statistics for all tools
+     */
+    getUsageStats(): Map<string, ToolUsageStats>;
+    /**
+     * Get most frequently used tools
+     */
+    getMostUsed(limit?: number): Tool[];
+    /**
+     * Get list of all categories
+     */
+    getCategories(): string[];
+    /**
+     * Update execution context
+     */
+    updateContext(context: Partial<ToolContext>): void;
+    /**
+     * Get current context
+     */
+    getContext(): ToolContext;
+    /**
+     * Clear all tools
+     */
+    clear(): void;
+    /**
+     * Unregister a specific tool
+     */
+    unregister(name: string): boolean;
+    /**
+     * Reset usage statistics
+     */
+    resetStats(): void;
+}
+
+/**
+ * Result of tool execution
+ */
+export declare interface ToolResult {
+    callId: string;
+    toolName: string;
+    result: any;
+    error?: Error;
+    duration: number;
+}
+
+/**
+ * ToolSandbox provides capability-based sandboxing for tool execution.
+ *
+ * Features:
+ * - Execution timeout enforcement
+ * - Concurrent execution limits
+ * - Output size limits
+ * - Pre/post execution hooks
+ * - Cancellation support
+ *
+ * Note: This provides capability-based restrictions, not true process isolation.
+ * For maximum security, consider running untrusted tools in separate processes.
+ *
+ * @example
+ * ```typescript
+ * const sandbox = new ToolSandbox({
+ *   maxExecutionTime: 5000,
+ *   maxConcurrentCalls: 5,
+ * });
+ *
+ * const result = await sandbox.execute(tool, params, context);
+ * ```
+ */
+export declare class ToolSandbox {
+    private config;
+    private logger;
+    private events;
+    private activeExecutions;
+    private executionCount;
+    constructor(config?: Partial<ToolSecurityConfig>, logger?: Logger, events?: ToolSandboxEvents);
+    /**
+     * Execute a tool with sandbox restrictions
+     */
+    execute<T>(tool: Tool, params: unknown, baseContext: ToolContext, options?: Partial<SandboxOptions>): Promise<T>;
+    /**
+     * Cancel all active executions
+     */
+    cancelAll(): void;
+    /**
+     * Cancel a specific execution by ID
+     */
+    cancel(executionId: string): boolean;
+    /**
+     * Get active execution count
+     */
+    getActiveCount(): number;
+    /**
+     * Get list of active execution IDs
+     */
+    getActiveExecutionIds(): string[];
+    /**
+     * Check if sandbox is enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Get current configuration
+     */
+    getConfig(): Readonly<ToolSecurityConfig>;
+    /**
+     * Update configuration
+     */
+    updateConfig(config: Partial<ToolSecurityConfig>): void;
+    private executeWithTimeout;
+    private estimateSize;
+}
+
+/**
+ * Event handlers for sandbox events
+ */
+export declare interface ToolSandboxEvents {
+    onConcurrencyExceeded?: (toolName: string, activeCount: number) => void;
+    onTimeout?: (toolName: string, timeoutMs: number) => void;
+    onOutputSizeExceeded?: (toolName: string, size: number, maxSize: number) => void;
+    onCancelled?: (executionId: string) => void;
+}
+
+/**
+ * Configuration for tool security
+ */
+export declare interface ToolSecurityConfig {
+    enabled: boolean;
+    validateParams: boolean;
+    sandboxExecution: boolean;
+    maxExecutionTime: number;
+    maxConcurrentCalls: number;
+    deniedTools: string[];
+    allowedTools?: string[];
+}
+
+/**
+ * Tool usage policy for a phase
+ */
+export declare type ToolUsagePolicy = 'required' | 'encouraged' | 'optional' | 'forbidden';
+
+/**
+ * Usage statistics for a tool
+ */
+export declare interface ToolUsageStats {
+    calls: number;
+    failures: number;
+    successRate: number;
+    averageDuration?: number;
+}
+
+/**
+ * Result of tool parameter validation
+ */
+export declare interface ToolValidationResult<T> {
+    success: boolean;
+    data?: T;
+    error?: string;
+    violations?: string[];
+}
+
+/**
+ * Tracked context item with metadata
+ */
+export declare interface TrackedContextItem extends DynamicContentItem {
+    id: string;
+    hash: string;
+    position: number;
+    injectedAt: Date;
+}
+
+/**
+ * Package version
+ */
+export declare const VERSION = "0.0.1";
+
+export declare function wrapLogger(toWrap: Logger, name?: string): Logger;
+
+export { }