@dexto/core 1.1.4

package/dist/index.browser.d.cts

@@ -0,0 +1,379 @@
+import { ZodError } from 'zod';
+
+/**
+ * Utility functions for converting various error types to proper Error instances
+ * with meaningful messages instead of "[object Object]"
+ */
+/**
+ * Converts any error value to an Error instance with a meaningful message
+ *
+ * @param error - The error value to convert (can be Error, object, string, etc.)
+ * @returns Error instance with extracted or serialized message
+ */
+declare function toError(error: unknown): Error;
+
+/**
+ * Agent-specific error codes
+ * Includes agent configuration and lifecycle errors only
+ * Domain-specific errors (LLM, Session, MCP, etc.) belong in their respective modules
+ */
+declare enum AgentErrorCode {
+    NOT_STARTED = "agent_not_started",
+    ALREADY_STARTED = "agent_already_started",
+    STOPPED = "agent_stopped",
+    INITIALIZATION_FAILED = "agent_initialization_failed",
+    API_VALIDATION_ERROR = "agent_api_validation_error"
+}
+
+/**
+ * Config-specific error codes
+ * Includes file operations, parsing, and validation errors for configuration management
+ */
+declare enum ConfigErrorCode {
+    FILE_NOT_FOUND = "config_file_not_found",
+    FILE_READ_ERROR = "config_file_read_error",
+    FILE_WRITE_ERROR = "config_file_write_error",
+    PARSE_ERROR = "config_parse_error",
+    NO_PROJECT_DEFAULT = "config_no_project_default",
+    NO_GLOBAL_PREFERENCES = "config_no_global_preferences",
+    SETUP_INCOMPLETE = "config_setup_incomplete",
+    BUNDLED_NOT_FOUND = "config_bundled_not_found",
+    UNKNOWN_CONTEXT = "config_unknown_context"
+}
+
+/**
+ * Context-specific error codes
+ * Includes initialization, message validation, token processing, and formatting errors
+ */
+declare enum ContextErrorCode {
+    MESSAGE_ROLE_MISSING = "context_message_role_missing",
+    MESSAGE_CONTENT_EMPTY = "context_message_content_empty",
+    USER_MESSAGE_CONTENT_INVALID = "context_user_message_content_invalid",
+    ASSISTANT_MESSAGE_CONTENT_OR_TOOLS_REQUIRED = "context_assistant_message_content_or_tools_required",
+    ASSISTANT_MESSAGE_TOOL_CALLS_INVALID = "context_assistant_message_tool_calls_invalid",
+    TOOL_MESSAGE_FIELDS_MISSING = "context_tool_message_fields_missing",
+    TOOL_CALL_ID_NAME_REQUIRED = "context_tool_call_id_name_required",
+    SYSTEM_MESSAGE_CONTENT_INVALID = "context_system_message_content_invalid",
+    TOKEN_COUNT_FAILED = "context_token_count_failed",
+    PRESERVE_VALUES_NEGATIVE = "context_preserve_values_negative",
+    MIN_MESSAGES_NEGATIVE = "context_min_messages_negative"
+}
+
+/**
+ * LLM-specific error codes
+ * Includes configuration, validation, and runtime errors for LLM operations
+ */
+declare enum LLMErrorCode {
+    API_KEY_MISSING = "llm_api_key_missing",
+    API_KEY_INVALID = "llm_api_key_invalid",// Too short, wrong format
+    API_KEY_CANDIDATE_MISSING = "llm_api_key_candidate_missing",
+    BASE_URL_MISSING = "llm_base_url_missing",
+    BASE_URL_INVALID = "llm_base_url_invalid",
+    MODEL_INCOMPATIBLE = "llm_model_incompatible",
+    MODEL_UNKNOWN = "llm_model_unknown",
+    PROVIDER_UNSUPPORTED = "llm_provider_unsupported",
+    ROUTER_UNSUPPORTED = "llm_router_unsupported",
+    INPUT_FILE_UNSUPPORTED = "llm_input_file_unsupported",
+    INPUT_IMAGE_UNSUPPORTED = "llm_input_image_unsupported",
+    INPUT_TEXT_INVALID = "llm_input_text_invalid",
+    TOKENS_EXCEEDED = "llm_tokens_exceeded",
+    RATE_LIMIT_EXCEEDED = "llm_rate_limit_exceeded",
+    SWITCH_FAILED = "llm_switch_failed",
+    GENERATION_FAILED = "llm_generation_failed",
+    SWITCH_INPUT_MISSING = "llm_switch_input_missing",// At least model or provider must be specified
+    REQUEST_INVALID_SCHEMA = "llm_request_invalid_schema"
+}
+
+/**
+ * MCP-specific error codes
+ * Includes server configuration, connection, and protocol errors
+ */
+declare enum MCPErrorCode {
+    SCHEMA_VALIDATION = "mcp_schema_validation",
+    COMMAND_MISSING = "mcp_command_missing",
+    DUPLICATE_NAME = "mcp_duplicate_name",
+    CONNECTION_FAILED = "mcp_connection_failed",
+    PROTOCOL_ERROR = "mcp_protocol_error",
+    TOOL_NOT_FOUND = "mcp_tool_not_found",
+    PROMPT_NOT_FOUND = "mcp_prompt_not_found",
+    RESOURCE_NOT_FOUND = "mcp_resource_not_found"
+}
+
+/**
+ * Session-specific error codes
+ * Includes session lifecycle, management, and state errors
+ */
+declare enum SessionErrorCode {
+    SESSION_NOT_FOUND = "session_not_found",
+    SESSION_INITIALIZATION_FAILED = "session_initialization_failed",
+    SESSION_MAX_SESSIONS_EXCEEDED = "session_max_sessions_exceeded",
+    SESSION_STORAGE_FAILED = "session_storage_failed",
+    SESSION_RESET_FAILED = "session_reset_failed"
+}
+
+/**
+ * Storage-specific error codes
+ * Includes database, file system, and persistence errors
+ */
+declare enum StorageErrorCode {
+    CONNECTION_FAILED = "storage_connection_failed",
+    CONNECTION_CONFIG_MISSING = "storage_connection_config_missing",
+    READ_FAILED = "storage_read_failed",
+    WRITE_FAILED = "storage_write_failed",
+    DELETE_FAILED = "storage_delete_failed",
+    MIGRATION_FAILED = "storage_migration_failed"
+}
+
+/**
+ * SystemPrompt-specific error codes
+ * Includes file processing and configuration errors
+ */
+declare enum SystemPromptErrorCode {
+    FILE_INVALID_TYPE = "systemprompt_file_invalid_type",
+    FILE_TOO_LARGE = "systemprompt_file_too_large",
+    FILE_READ_FAILED = "systemprompt_file_read_failed",
+    CONTRIBUTOR_SOURCE_UNKNOWN = "systemprompt_contributor_source_unknown",
+    CONTRIBUTOR_CONFIG_INVALID = "systemprompt_contributor_config_invalid"
+}
+
+/**
+ * Tools-specific error codes
+ * Includes tool execution, confirmation, and authorization errors
+ */
+declare enum ToolErrorCode {
+    EXECUTION_DENIED = "tools_execution_denied",
+    EXECUTION_TIMEOUT = "tools_execution_timeout",
+    EXECUTION_FAILED = "tools_execution_failed",
+    CONFIRMATION_HANDLER_MISSING = "tools_confirmation_handler_missing",
+    CONFIRMATION_TIMEOUT = "tools_confirmation_timeout",
+    CONFIRMATION_CANCELLED = "tools_confirmation_cancelled",
+    TOOL_NOT_FOUND = "tools_tool_not_found",
+    TOOL_INVALID_ARGS = "tools_invalid_args",
+    TOOL_UNAUTHORIZED = "tools_unauthorized",
+    CONFIG_INVALID = "tools_config_invalid"
+}
+
+declare enum PreferenceErrorCode {
+    FILE_NOT_FOUND = "preference_file_not_found",
+    FILE_READ_ERROR = "preference_file_read_error",
+    FILE_WRITE_ERROR = "preference_file_write_error",
+    VALIDATION_ERROR = "preference_validation_error",
+    MODEL_INCOMPATIBLE = "preference_model_incompatible"
+}
+
+/**
+ * Registry-specific error codes
+ * Includes agent resolution, installation, and registry management errors
+ */
+declare enum RegistryErrorCode {
+    AGENT_NOT_FOUND = "registry_agent_not_found",
+    AGENT_INVALID_ENTRY = "registry_agent_invalid_entry",
+    INSTALLATION_FAILED = "registry_installation_failed",
+    INSTALLATION_VALIDATION_FAILED = "registry_installation_validation_failed",
+    REGISTRY_NOT_FOUND = "registry_file_not_found",
+    REGISTRY_PARSE_ERROR = "registry_parse_error",
+    CONFIG_NOT_FOUND = "registry_config_not_found",
+    MAIN_CONFIG_MISSING = "registry_main_config_missing",
+    AGENT_NOT_INSTALLED = "registry_agent_not_installed",
+    AGENT_PROTECTED = "registry_agent_protected",
+    UNINSTALLATION_FAILED = "registry_uninstallation_failed",
+    AGENT_NOT_INSTALLED_AUTO_INSTALL_DISABLED = "registry_agent_not_installed_auto_install_disabled"
+}
+
+/**
+ * Error scopes representing functional domains in the system
+ * Each scope owns its validation and error logic
+ */
+declare enum ErrorScope {
+    LLM = "llm",// LLM operations, model compatibility, input validation for LLMs
+    AGENT = "agent",// Agent lifecycle, configuration
+    CONFIG = "config",// Configuration file operations, parsing, validation
+    CONTEXT = "context",// Context management, message validation, token processing
+    SESSION = "session",// Session lifecycle, management, and state
+    MCP = "mcp",// MCP server connections and protocol
+    TOOLS = "tools",// Tool execution and authorization
+    STORAGE = "storage",// Storage backend operations
+    SYSTEM_PROMPT = "system_prompt",// System prompt contributors and file processing
+    PREFERENCE = "preference",// Global preferences file operations and validation
+    AGENT_REGISTRY = "agent_registry"
+}
+/**
+ * Error types that map directly to HTTP status codes
+ * Each type represents the nature of the error
+ */
+declare enum ErrorType {
+    USER = "user",// 400 - bad input, config errors, validation failures
+    NOT_FOUND = "not_found",// 404 - resource doesn't exist (session, file, etc.)
+    FORBIDDEN = "forbidden",// 403 - permission denied, unauthorized
+    TIMEOUT = "timeout",// 408 - operation timed out
+    RATE_LIMIT = "rate_limit",// 429 - too many requests
+    SYSTEM = "system",// 500 - bugs, internal failures, unexpected states
+    THIRD_PARTY = "third_party",// 502 - upstream provider failures, API errors
+    UNKNOWN = "unknown"
+}
+/**
+ * Union type for all error codes across domains
+ * Provides type safety for error handling
+ */
+type DextoErrorCode = LLMErrorCode | AgentErrorCode | ConfigErrorCode | ContextErrorCode | SessionErrorCode | MCPErrorCode | ToolErrorCode | StorageErrorCode | SystemPromptErrorCode | PreferenceErrorCode | RegistryErrorCode;
+/** Severity of an issue */
+type Severity = 'error' | 'warning';
+/** Generic issue type for validation results */
+interface Issue<C = unknown> {
+    code: DextoErrorCode;
+    message: string;
+    scope: ErrorScope;
+    type: ErrorType;
+    severity: Severity;
+    path?: Array<string | number>;
+    context?: C;
+}
+
+/**
+ * Convert Zod validation errors to standardized Issue format for Result pattern.
+ *
+ * **Usage Guidelines:**
+ * - Use in schema validation functions to convert Zod errors to our Issue format
+ * - Allows custom error codes via Zod's params.code field in custom refinements
+ * - Falls back to SCHEMA_VALIDATION code for standard Zod validation errors
+ * - Typically used with severity: 'error' for blocking validation failures
+ *
+ * @param err - ZodError from failed schema validation
+ * @param severity - Issue severity level (defaults to 'error')
+ * @returns Array of Issues in our standardized format
+ *
+ * @example
+ * ```typescript
+ * // In a validation function
+ * const result = MySchema.safeParse(data);
+ * if (!result.success) {
+ *   const issues = zodToIssues(result.error);
+ *   return fail(issues);
+ * }
+ *
+ * // Custom error codes in Zod schema
+ * const schema = z.string().refine(val => val.length > 0, {
+ *   message: 'Field is required',
+ *   params: { code: LLMErrorCode.API_KEY_MISSING }
+ * });
+ * ```
+ */
+declare function zodToIssues<C = unknown>(err: ZodError, severity?: 'error' | 'warning'): Issue<C>[];
+
+declare const LLM_PROVIDERS: readonly ["openai", "openai-compatible", "anthropic", "google", "groq", "xai", "cohere"];
+type LLMProvider = (typeof LLM_PROVIDERS)[number];
+declare const LLM_ROUTERS: readonly ["vercel", "in-built"];
+type LLMRouter = (typeof LLM_ROUTERS)[number];
+declare const SUPPORTED_FILE_TYPES: readonly ["pdf", "image", "audio"];
+
+/**
+ * Internal representation of a message in a conversation.
+ * Standardizes message format across different LLM providers.
+ */
+interface ImageData {
+    image: string | Uint8Array | Buffer | ArrayBuffer | URL;
+    mimeType?: string;
+}
+interface FileData {
+    data: string | Uint8Array | Buffer | ArrayBuffer | URL;
+    mimeType: string;
+    filename?: string;
+}
+interface TextPart {
+    type: 'text';
+    text: string;
+}
+interface ImagePart extends ImageData {
+    type: 'image';
+}
+interface FilePart extends FileData {
+    type: 'file';
+}
+interface InternalMessage {
+    /**
+     * The role of the entity sending the message.
+     * - 'system': System instructions or context
+     * - 'user': End-user input
+     * - 'assistant': LLM response
+     * - 'tool': Result from a tool execution
+     */
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    /**
+     * Timestamp when the message was created (Unix timestamp in milliseconds).
+     * TODO: Populate this field when messages are created. Currently not implemented.
+     * @see https://github.com/truffle-ai/dexto/issues/XXX
+     */
+    timestamp?: number;
+    /**
+     * The content of the message.
+     * - String for system, assistant (text only), and tool messages.
+     * - Array of parts for user messages (can include text, images, and files).
+     * - null if an assistant message only contains tool calls.
+     */
+    content: string | null | Array<TextPart | ImagePart | FilePart>;
+    /**
+     * Optional model reasoning text associated with an assistant response.
+     * Present when the provider supports reasoning and returns a final reasoning trace.
+     */
+    reasoning?: string;
+    /**
+     * Optional token usage accounting for this assistant response.
+     */
+    tokenUsage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+        reasoningTokens?: number;
+        totalTokens?: number;
+    };
+    /**
+     * Optional model identifier for assistant messages.
+     * Indicates which LLM model generated this response.
+     */
+    model?: string;
+    /** Optional provider identifier for assistant messages. */
+    provider?: LLMProvider;
+    /**
+     * Optional router metadata for assistant messages.
+     * Indicates which router was used to route the request.
+     */
+    router?: LLMRouter;
+    /**
+     * Tool calls made by the assistant.
+     * Only present in assistant messages when the LLM requests tool execution.
+     */
+    toolCalls?: Array<{
+        /**
+         * Unique identifier for this tool call
+         */
+        id: string;
+        /**
+         * The type of tool call (currently only 'function' is supported)
+         */
+        type: 'function';
+        /**
+         * Function call details
+         */
+        function: {
+            /**
+             * Name of the function to call
+             */
+            name: string;
+            /**
+             * Arguments for the function in JSON string format
+             */
+            arguments: string;
+        };
+    }>;
+    /**
+     * ID of the tool call this message is responding to.
+     * Only present in tool messages.
+     */
+    toolCallId?: string;
+    /**
+     * Name of the tool that produced this result.
+     * Only present in tool messages.
+     */
+    name?: string;
+}
+
+export { type DextoErrorCode, ErrorScope, ErrorType, type FilePart, type ImagePart, type InternalMessage, type Issue, type LLMProvider, type LLMRouter, LLM_PROVIDERS, LLM_ROUTERS, SUPPORTED_FILE_TYPES, type Severity, type TextPart, toError, zodToIssues };