@agenticc/core 1.0.0

package/dist/types/streaming.js

@@ -0,0 +1,483 @@
+/**
+ * Streaming Response Type Definitions
+ *
+ * Defines the interfaces for Server-Sent Events (SSE) streaming responses.
+ * Used for real-time feedback during long-running AI assistant operations.
+ *
+ * Requirements: 1.1, 1.2, 1.3, 1.4, 1.5, 2.3, 2.4, 3.1, 3.2, 3.3, 3.4, 3.5, 8.1, 8.2, 8.4, 10.4
+ */
+// ============================================================================
+// SSE Event Types
+// ============================================================================
+/**
+ * All possible SSE event types
+ */
+export const SSE_EVENT_TYPES = [
+    'processing_started',
+    'iteration_started',
+    'iteration_completed',
+    'content_chunk',
+    'tool_call_started',
+    'tool_call_completed',
+    'tool_error',
+    'knowledge_retrieved',
+    'confirmation_check',
+    'decision',
+    'completed',
+    'error',
+    'cancelled',
+    'heartbeat',
+    'max_iterations',
+];
+/**
+ * Default streaming configuration
+ */
+export const DEFAULT_STREAMING_CONFIG = {
+    enabled: true,
+    maxDuration: 5 * 60 * 1000, // 5 minutes
+    heartbeatInterval: 15 * 1000, // 15 seconds
+    maxConcurrent: 100,
+    enableBatching: false,
+    batchInterval: 50, // 50ms
+};
+// ============================================================================
+// Error Handling Types
+// ============================================================================
+/**
+ * Error codes for streaming errors
+ */
+export const STREAMING_ERROR_CODES = [
+    'LLM_API_ERROR',
+    'TOOL_EXECUTION_FAILED',
+    'KNOWLEDGE_RETRIEVAL_FAILED',
+    'RATE_LIMIT_EXCEEDED',
+    'CONTEXT_LENGTH_EXCEEDED',
+    'AGENT_CRASH',
+    'DATABASE_ERROR',
+    'NETWORK_ERROR',
+    'TIMEOUT',
+    'INVALID_REQUEST',
+    'STREAM_CLOSED',
+    'MAX_CONCURRENT_EXCEEDED',
+    'UNKNOWN_ERROR',
+];
+/**
+ * Cancellation reasons
+ */
+export const CANCELLATION_REASONS = [
+    'user_cancelled',
+    'client_disconnected',
+    'timeout',
+    'server_shutdown',
+];
+/**
+ * Default error handling strategies
+ */
+export const DEFAULT_ERROR_HANDLING = {
+    LLM_API_ERROR: {
+        code: 'LLM_API_ERROR',
+        recoverable: false,
+        strategy: 'abort',
+    },
+    TOOL_EXECUTION_FAILED: {
+        code: 'TOOL_EXECUTION_FAILED',
+        recoverable: true,
+        strategy: 'continue',
+    },
+    KNOWLEDGE_RETRIEVAL_FAILED: {
+        code: 'KNOWLEDGE_RETRIEVAL_FAILED',
+        recoverable: true,
+        strategy: 'continue',
+    },
+    RATE_LIMIT_EXCEEDED: {
+        code: 'RATE_LIMIT_EXCEEDED',
+        recoverable: true,
+        strategy: 'retry',
+        maxRetries: 3,
+        retryDelay: 1000,
+    },
+    CONTEXT_LENGTH_EXCEEDED: {
+        code: 'CONTEXT_LENGTH_EXCEEDED',
+        recoverable: false,
+        strategy: 'abort',
+    },
+    AGENT_CRASH: {
+        code: 'AGENT_CRASH',
+        recoverable: false,
+        strategy: 'abort',
+    },
+    DATABASE_ERROR: {
+        code: 'DATABASE_ERROR',
+        recoverable: false,
+        strategy: 'abort',
+    },
+    NETWORK_ERROR: {
+        code: 'NETWORK_ERROR',
+        recoverable: true,
+        strategy: 'retry',
+        maxRetries: 3,
+        retryDelay: 500,
+    },
+    TIMEOUT: {
+        code: 'TIMEOUT',
+        recoverable: true,
+        strategy: 'retry',
+        maxRetries: 2,
+        retryDelay: 1000,
+    },
+    INVALID_REQUEST: {
+        code: 'INVALID_REQUEST',
+        recoverable: false,
+        strategy: 'abort',
+    },
+    STREAM_CLOSED: {
+        code: 'STREAM_CLOSED',
+        recoverable: false,
+        strategy: 'abort',
+    },
+    MAX_CONCURRENT_EXCEEDED: {
+        code: 'MAX_CONCURRENT_EXCEEDED',
+        recoverable: false,
+        strategy: 'abort',
+    },
+    UNKNOWN_ERROR: {
+        code: 'UNKNOWN_ERROR',
+        recoverable: false,
+        strategy: 'abort',
+    },
+};
+// ============================================================================
+// Type Guards
+// ============================================================================
+/**
+ * Type guard to check if a value is a valid SSE event type
+ */
+export function isValidSSEEventType(type) {
+    return typeof type === 'string' && SSE_EVENT_TYPES.includes(type);
+}
+/**
+ * Type guard to check if a value is a valid streaming error code
+ */
+export function isValidStreamingErrorCode(code) {
+    return typeof code === 'string' && STREAMING_ERROR_CODES.includes(code);
+}
+/**
+ * Type guard to check if a value is a valid cancellation reason
+ */
+export function isValidCancellationReason(reason) {
+    return typeof reason === 'string' && CANCELLATION_REASONS.includes(reason);
+}
+/**
+ * Type guard for ProcessingStartedEvent
+ */
+export function isProcessingStartedEvent(event) {
+    return event.type === 'processing_started';
+}
+/**
+ * Type guard for IterationStartedEvent
+ */
+export function isIterationStartedEvent(event) {
+    return event.type === 'iteration_started';
+}
+/**
+ * Type guard for IterationCompletedEvent
+ */
+export function isIterationCompletedEvent(event) {
+    return event.type === 'iteration_completed';
+}
+/**
+ * Type guard for ContentChunkEvent
+ */
+export function isContentChunkEvent(event) {
+    return event.type === 'content_chunk';
+}
+/**
+ * Type guard for ToolCallStartedEvent
+ */
+export function isToolCallStartedEvent(event) {
+    return event.type === 'tool_call_started';
+}
+/**
+ * Type guard for ToolCallCompletedEvent
+ */
+export function isToolCallCompletedEvent(event) {
+    return event.type === 'tool_call_completed';
+}
+/**
+ * Type guard for ToolErrorEvent
+ */
+export function isToolErrorEvent(event) {
+    return event.type === 'tool_error';
+}
+/**
+ * Type guard for ErrorEvent
+ */
+export function isErrorEvent(event) {
+    return event.type === 'error';
+}
+/**
+ * Type guard for CancelledEvent
+ */
+export function isCancelledEvent(event) {
+    return event.type === 'cancelled';
+}
+/**
+ * Type guard for CompletedEvent
+ */
+export function isCompletedEvent(event) {
+    return event.type === 'completed';
+}
+/**
+ * Type guard for HeartbeatEvent
+ */
+export function isHeartbeatEvent(event) {
+    return event.type === 'heartbeat';
+}
+// ============================================================================
+// Factory Functions
+// ============================================================================
+let eventIdCounter = 0;
+/**
+ * Generates a unique event ID
+ */
+export function generateEventId() {
+    return `evt_${Date.now()}_${++eventIdCounter}`;
+}
+/**
+ * Creates a base event with common fields
+ */
+function createBaseEvent(type, sessionId) {
+    return {
+        id: generateEventId(),
+        type,
+        timestamp: Date.now(),
+        sessionId,
+    };
+}
+/**
+ * Creates a ProcessingStartedEvent
+ */
+export function createProcessingStartedEvent(sessionId, messageId) {
+    return {
+        ...createBaseEvent('processing_started', sessionId),
+        data: { messageId },
+    };
+}
+/**
+ * Creates an IterationStartedEvent
+ */
+export function createIterationStartedEvent(sessionId, iteration, maxIterations) {
+    return {
+        ...createBaseEvent('iteration_started', sessionId),
+        data: { iteration, maxIterations },
+    };
+}
+/**
+ * Creates an IterationCompletedEvent
+ */
+export function createIterationCompletedEvent(sessionId, iteration, duration, toolCallCount) {
+    return {
+        ...createBaseEvent('iteration_completed', sessionId),
+        data: { iteration, duration, toolCallCount },
+    };
+}
+/**
+ * Creates a ContentChunkEvent
+ */
+export function createContentChunkEvent(sessionId, content, isComplete) {
+    return {
+        ...createBaseEvent('content_chunk', sessionId),
+        data: { content, isComplete },
+    };
+}
+/**
+ * Creates a ToolCallStartedEvent
+ */
+export function createToolCallStartedEvent(sessionId, toolCallId, toolName, args) {
+    return {
+        ...createBaseEvent('tool_call_started', sessionId),
+        data: { toolCallId, toolName, arguments: args },
+    };
+}
+/**
+ * Creates a ToolCallCompletedEvent
+ */
+export function createToolCallCompletedEvent(sessionId, toolCallId, toolName, success, duration, result) {
+    return {
+        ...createBaseEvent('tool_call_completed', sessionId),
+        data: { toolCallId, toolName, success, duration, result },
+    };
+}
+/**
+ * Creates a ToolErrorEvent
+ */
+export function createToolErrorEvent(sessionId, toolCallId, toolName, error, recoverable) {
+    return {
+        ...createBaseEvent('tool_error', sessionId),
+        data: { toolCallId, toolName, error, recoverable },
+    };
+}
+/**
+ * Creates a KnowledgeRetrievedEvent
+ */
+export function createKnowledgeRetrievedEvent(sessionId, documentCount, categories) {
+    return {
+        ...createBaseEvent('knowledge_retrieved', sessionId),
+        data: { documentCount, categories },
+    };
+}
+/**
+ * Creates a ConfirmationCheckEvent
+ */
+export function createConfirmationCheckEvent(sessionId, description) {
+    return {
+        ...createBaseEvent('confirmation_check', sessionId),
+        data: { description },
+    };
+}
+/**
+ * Creates a DecisionEvent
+ */
+export function createDecisionEvent(sessionId, reason, completed) {
+    return {
+        ...createBaseEvent('decision', sessionId),
+        data: { reason, completed },
+    };
+}
+/**
+ * Creates a CompletedEvent
+ */
+export function createCompletedEvent(sessionId, messageId, totalDuration, iterations, toolCalls) {
+    return {
+        ...createBaseEvent('completed', sessionId),
+        data: { messageId, totalDuration, iterations, toolCalls },
+    };
+}
+/**
+ * Creates a MaxIterationsEvent
+ */
+export function createMaxIterationsEvent(sessionId, iterations, partialContent) {
+    return {
+        ...createBaseEvent('max_iterations', sessionId),
+        data: { iterations, partialContent },
+    };
+}
+/**
+ * Creates an ErrorEvent
+ */
+export function createErrorEvent(sessionId, code, message, recoverable, details) {
+    return {
+        ...createBaseEvent('error', sessionId),
+        data: { code, message, recoverable, details },
+    };
+}
+/**
+ * Creates a CancelledEvent
+ */
+export function createCancelledEvent(sessionId, reason, partialContent) {
+    return {
+        ...createBaseEvent('cancelled', sessionId),
+        data: { reason, partialContent },
+    };
+}
+/**
+ * Creates a HeartbeatEvent
+ */
+export function createHeartbeatEvent(sessionId) {
+    return {
+        ...createBaseEvent('heartbeat', sessionId),
+        data: { serverTime: Date.now() },
+    };
+}
+// ============================================================================
+// Utility Functions
+// ============================================================================
+/**
+ * Formats an SSE event for transmission
+ */
+export function formatSSEEvent(event) {
+    const lines = [];
+    lines.push(`id: ${event.id}`);
+    lines.push(`event: ${event.type}`);
+    lines.push(`data: ${JSON.stringify(event)}`);
+    lines.push(''); // Empty line to end the event
+    return lines.join('\n') + '\n';
+}
+/**
+ * Parses an SSE event from a string
+ */
+export function parseSSEEvent(eventString) {
+    const lines = eventString.split('\n');
+    let data = null;
+    for (const line of lines) {
+        if (line.startsWith('data: ')) {
+            data = line.slice(6);
+        }
+    }
+    if (!data) {
+        return null;
+    }
+    try {
+        return JSON.parse(data);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Gets the error handling configuration for an error code
+ */
+export function getErrorHandling(code) {
+    return DEFAULT_ERROR_HANDLING[code] ?? DEFAULT_ERROR_HANDLING.UNKNOWN_ERROR;
+}
+/**
+ * Checks if an error is recoverable
+ */
+export function isRecoverableError(code) {
+    return getErrorHandling(code).recoverable;
+}
+/**
+ * Creates a new StreamContext
+ */
+export function createStreamContext(id, sessionId, userId) {
+    return {
+        id,
+        sessionId,
+        userId,
+        status: 'active',
+        startTime: Date.now(),
+        lastEventId: 0,
+        abortController: new AbortController(),
+        accumulatedContent: '',
+        eventCount: 0,
+    };
+}
+/**
+ * Validates streaming configuration
+ */
+export function validateStreamingConfig(config) {
+    const errors = [];
+    if (config.maxDuration !== undefined && config.maxDuration < 1000) {
+        errors.push('maxDuration must be at least 1000ms (1 second)');
+    }
+    if (config.heartbeatInterval !== undefined && config.heartbeatInterval < 1000) {
+        errors.push('heartbeatInterval must be at least 1000ms (1 second)');
+    }
+    if (config.maxConcurrent !== undefined && config.maxConcurrent < 1) {
+        errors.push('maxConcurrent must be at least 1');
+    }
+    if (config.batchInterval !== undefined && config.batchInterval < 10) {
+        errors.push('batchInterval must be at least 10ms');
+    }
+    return errors;
+}
+/**
+ * Merges partial config with defaults
+ */
+export function mergeStreamingConfig(partial) {
+    return {
+        ...DEFAULT_STREAMING_CONFIG,
+        ...partial,
+    };
+}
+//# sourceMappingURL=streaming.js.map

package/dist/types/streaming.js.map

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

package/dist/types/tool.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Tool System Type Definitions
+ *
+ * Defines the interfaces for the Agent's tool registration and execution system.
+ * Tools are the primary way the Agent interacts with external systems.
+ */
+import type { KnowledgeBase } from './knowledge.js';
+/**
+ * Parameter type for tool definitions
+ */
+export type ToolParameterType = 'string' | 'number' | 'boolean' | 'object' | 'array';
+/**
+ * Defines a single parameter for a tool
+ */
+export interface ToolParameter {
+    /** Parameter name */
+    name: string;
+    /** Parameter data type */
+    type: ToolParameterType;
+    /** Human-readable description of the parameter */
+    description: string;
+    /** Whether this parameter is required */
+    required: boolean;
+    /** Optional list of allowed values */
+    enum?: string[];
+    /** Default value if not provided */
+    default?: unknown;
+}
+/**
+ * Context provided to tool execution
+ */
+export interface ToolContext {
+    /** Access to the knowledge base for RAG operations */
+    knowledgeBase: KnowledgeBase;
+    /** Current conversation session ID */
+    sessionId: string;
+    /** Logger for tool operations */
+    logger: ToolLogger;
+}
+/**
+ * Logger interface for tool operations
+ */
+export interface ToolLogger {
+    info(message: string, data?: Record<string, unknown>): void;
+    warn(message: string, data?: Record<string, unknown>): void;
+    error(message: string, data?: Record<string, unknown>): void;
+    debug(message: string, data?: Record<string, unknown>): void;
+}
+/**
+ * Result of a tool execution
+ */
+export interface ToolResult {
+    /** Whether the execution was successful */
+    success: boolean;
+    /** Human-readable result message */
+    content: string;
+    /** Optional structured data from the execution */
+    data?: unknown;
+    /** Error details if execution failed */
+    error?: {
+        code: string;
+        message: string;
+        details?: unknown;
+    };
+}
+/**
+ * Tool execution function signature
+ */
+export type ToolExecutor = (args: Record<string, unknown>, context: ToolContext) => Promise<ToolResult>;
+/**
+ * Complete tool definition
+ */
+export interface Tool {
+    /** Unique tool name (used for Function Calling) */
+    name: string;
+    /** Human-readable description of what the tool does */
+    description: string;
+    /** List of parameters the tool accepts */
+    parameters: ToolParameter[];
+    /** The function that executes the tool */
+    execute: ToolExecutor;
+    /** Optional category for grouping tools */
+    category?: string;
+    /** Whether this tool requires confirmation before execution */
+    requiresConfirmation?: boolean;
+    /** Risk level of this tool's operations */
+    riskLevel?: 'low' | 'medium' | 'high';
+}
+/**
+ * Tool definition format for LLM Function Calling
+ * This is the format expected by OpenAI/Claude APIs
+ */
+export interface ToolDefinition {
+    type: 'function';
+    function: {
+        name: string;
+        description: string;
+        parameters: {
+            type: 'object';
+            properties: Record<string, ToolPropertySchema>;
+            required: string[];
+        };
+    };
+}
+/**
+ * JSON Schema property definition for tool parameters
+ */
+export interface ToolPropertySchema {
+    type: string;
+    description: string;
+    enum?: string[];
+    default?: unknown;
+}
+/**
+ * Converts a Tool to a ToolDefinition for LLM Function Calling
+ */
+export declare function toolToDefinition(tool: Tool): ToolDefinition;
+//# sourceMappingURL=tool.d.ts.map

package/dist/types/tool.d.ts.map

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

package/dist/types/tool.js

@@ -0,0 +1,42 @@
+/**
+ * Tool System Type Definitions
+ *
+ * Defines the interfaces for the Agent's tool registration and execution system.
+ * Tools are the primary way the Agent interacts with external systems.
+ */
+/**
+ * Converts a Tool to a ToolDefinition for LLM Function Calling
+ */
+export function toolToDefinition(tool) {
+    const properties = {};
+    const required = [];
+    for (const param of tool.parameters) {
+        const propSchema = {
+            type: param.type,
+            description: param.description,
+        };
+        if (param.enum) {
+            propSchema.enum = param.enum;
+        }
+        if (param.default !== undefined) {
+            propSchema.default = param.default;
+        }
+        properties[param.name] = propSchema;
+        if (param.required) {
+            required.push(param.name);
+        }
+    }
+    return {
+        type: 'function',
+        function: {
+            name: tool.name,
+            description: tool.description,
+            parameters: {
+                type: 'object',
+                properties,
+                required,
+            },
+        },
+    };
+}
+//# sourceMappingURL=tool.js.map

package/dist/types/tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.js","sourceRoot":"","sources":["../../src/types/tool.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA0HH;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAU;IACzC,MAAM,UAAU,GAAuC,EAAE,CAAC;IAC1D,MAAM,QAAQ,GAAa,EAAE,CAAC;IAE9B,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;QACpC,MAAM,UAAU,GAAuB;YACrC,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,WAAW,EAAE,KAAK,CAAC,WAAW;SAC/B,CAAC;QACF,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;YACf,UAAU,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;QAC/B,CAAC;QACD,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;YAChC,UAAU,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;QACrC,CAAC;QACD,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,UAAU,CAAC;QAEpC,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;YACnB,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC5B,CAAC;IACH,CAAC;IAED,OAAO;QACL,IAAI,EAAE,UAAU;QAChB,QAAQ,EAAE;YACR,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,UAAU,EAAE;gBACV,IAAI,EAAE,QAAQ;gBACd,UAAU;gBACV,QAAQ;aACT;SACF;KACF,CAAC;AACJ,CAAC"}

package/dist/utils/error.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Error Handling Utilities
+ *
+ * Provides safe error message extraction to prevent '[object Object]' in error messages.
+ */
+/**
+ * Safely extract error message from unknown error type
+ *
+ * @param error - Unknown error value
+ * @returns Human-readable error message
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   throw new Error('Something went wrong');
+ * } catch (error) {
+ *   console.log(getErrorMessage(error)); // "Something went wrong"
+ * }
+ * ```
+ */
+export declare function getErrorMessage(error: unknown): string;
+//# sourceMappingURL=error.d.ts.map

package/dist/utils/error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../../src/utils/error.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAatD"}