@dexto/core 1.1.4

package/dist/index.browser.d.ts

@@ -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 };

package/dist/index.browser.js

@@ -0,0 +1,217 @@
+// src/utils/redactor.ts
+var SENSITIVE_FIELDS = [
+  "apikey",
+  "api_key",
+  "token",
+  "access_token",
+  "refresh_token",
+  "password",
+  "secret"
+];
+var FILE_DATA_FIELDS = [
+  "base64",
+  "filedata",
+  "file_data",
+  "imagedata",
+  "image_data",
+  "audiodata",
+  "audio_data",
+  "data"
+];
+var SENSITIVE_PATTERNS = [
+  /\bsk-[A-Za-z0-9]{20,}\b/g,
+  // OpenAI API keys (at least 20 chars after sk-)
+  /\bBearer\s+[A-Za-z0-9\-_.=]+\b/gi,
+  // Bearer tokens
+  /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g,
+  // Emails
+  /\beyJ[A-Za-z0-9_-]*\.[A-Za-z0-9_-]*\.[A-Za-z0-9_-]*/g
+  // JWT tokens
+];
+var REDACTED = "[REDACTED]";
+var REDACTED_CIRCULAR = "[REDACTED_CIRCULAR]";
+var FILE_DATA_TRUNCATED = "[FILE_DATA_TRUNCATED]";
+function isLargeBase64Data(value) {
+  return value.length > 1e3 && /^[A-Za-z0-9+/=]{1000,}$/.test(value.substring(0, 1e3));
+}
+function truncateFileData(value, key, parent) {
+  if (typeof value !== "string") return value;
+  const lowerKey = key.toLowerCase();
+  const hasFileContext = !!parent && ("mimeType" in parent || "filename" in parent || "fileName" in parent);
+  const looksLikeFileField = FILE_DATA_FIELDS.includes(lowerKey) || lowerKey === "data" && hasFileContext;
+  if (looksLikeFileField && isLargeBase64Data(value)) {
+    return `${FILE_DATA_TRUNCATED} (${value.length} chars)`;
+  }
+  return value;
+}
+function redactSensitiveData(input, seen = /* @__PURE__ */ new WeakSet()) {
+  if (typeof input === "string") {
+    let result = input;
+    for (const pattern of SENSITIVE_PATTERNS) {
+      result = result.replace(pattern, REDACTED);
+    }
+    return result;
+  }
+  if (Array.isArray(input)) {
+    if (seen.has(input)) return REDACTED_CIRCULAR;
+    seen.add(input);
+    return input.map((item) => redactSensitiveData(item, seen));
+  }
+  if (input && typeof input === "object") {
+    if (seen.has(input)) return REDACTED_CIRCULAR;
+    seen.add(input);
+    const result = {};
+    for (const [key, value] of Object.entries(input)) {
+      if (SENSITIVE_FIELDS.includes(key.toLowerCase())) {
+        result[key] = REDACTED;
+      } else {
+        const truncatedValue = truncateFileData(
+          value,
+          key,
+          input
+        );
+        result[key] = redactSensitiveData(truncatedValue, seen);
+      }
+    }
+    return result;
+  }
+  return input;
+}
+
+// src/utils/safe-stringify.ts
+function safeStringify(value, maxLen = 1e3) {
+  try {
+    if (typeof value === "bigint") {
+      return value.toString();
+    }
+    const redacted = redactSensitiveData(value);
+    const str = JSON.stringify(redacted, (_, v) => {
+      if (v instanceof Error) {
+        return { name: v.name, message: v.message, stack: v.stack };
+      }
+      if (typeof v === "bigint") return v.toString();
+      return v;
+    });
+    const indicator = "\u2026(truncated)";
+    const limit = Number.isFinite(maxLen) && maxLen > 0 ? Math.floor(maxLen) : 1e3;
+    if (typeof str === "string") {
+      if (str.length <= limit) return str;
+      const sliceLen = Math.max(0, limit - indicator.length);
+      return `${str.slice(0, sliceLen)}${indicator}`;
+    }
+    return String(value);
+  } catch {
+    try {
+      return String(value);
+    } catch {
+      return "[Unserializable value]";
+    }
+  }
+}
+
+// src/utils/error-conversion.ts
+function toError(error) {
+  if (error instanceof Error) {
+    return error;
+  }
+  if (error && typeof error === "object") {
+    if ("message" in error && typeof error.message === "string") {
+      return new Error(error.message, { cause: error });
+    }
+    if ("error" in error && typeof error.error === "string") {
+      return new Error(error.error, { cause: error });
+    }
+    if ("details" in error && typeof error.details === "string") {
+      return new Error(error.details, { cause: error });
+    }
+    if ("description" in error && typeof error.description === "string") {
+      return new Error(error.description, { cause: error });
+    }
+    const serialized = safeStringify(error);
+    return new Error(serialized);
+  }
+  if (typeof error === "string") {
+    return new Error(error, { cause: error });
+  }
+  return new Error(String(error), { cause: error });
+}
+
+// src/utils/result.ts
+import { z } from "zod";
+
+// src/errors/types.ts
+var ErrorScope = /* @__PURE__ */ ((ErrorScope2) => {
+  ErrorScope2["LLM"] = "llm";
+  ErrorScope2["AGENT"] = "agent";
+  ErrorScope2["CONFIG"] = "config";
+  ErrorScope2["CONTEXT"] = "context";
+  ErrorScope2["SESSION"] = "session";
+  ErrorScope2["MCP"] = "mcp";
+  ErrorScope2["TOOLS"] = "tools";
+  ErrorScope2["STORAGE"] = "storage";
+  ErrorScope2["SYSTEM_PROMPT"] = "system_prompt";
+  ErrorScope2["PREFERENCE"] = "preference";
+  ErrorScope2["AGENT_REGISTRY"] = "agent_registry";
+  return ErrorScope2;
+})(ErrorScope || {});
+var ErrorType = /* @__PURE__ */ ((ErrorType2) => {
+  ErrorType2["USER"] = "user";
+  ErrorType2["NOT_FOUND"] = "not_found";
+  ErrorType2["FORBIDDEN"] = "forbidden";
+  ErrorType2["TIMEOUT"] = "timeout";
+  ErrorType2["RATE_LIMIT"] = "rate_limit";
+  ErrorType2["SYSTEM"] = "system";
+  ErrorType2["THIRD_PARTY"] = "third_party";
+  ErrorType2["UNKNOWN"] = "unknown";
+  return ErrorType2;
+})(ErrorType || {});
+
+// src/utils/result.ts
+var NonEmptyTrimmed = z.string().transform((s) => s.trim()).refine((s) => s.length > 0, { message: "Required" });
+function isValidUrl(s) {
+  try {
+    const u = new URL(s);
+    return u.protocol === "http:" || u.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+var OptionalURL = z.string().transform((s) => s.trim()).refine((s) => s === "" || isValidUrl(s), { message: "Invalid URL" }).transform((s) => s === "" ? void 0 : s).optional();
+function zodToIssues(err, severity = "error") {
+  return err.errors.map((e) => {
+    const params = e.params || {};
+    return {
+      code: params.code ?? "schema_validation",
+      message: e.message,
+      scope: params.scope ?? "agent" /* AGENT */,
+      // Fallback for non-custom Zod errors
+      // Treat plain Zod schema failures as USER errors by default
+      type: params.type ?? "user" /* USER */,
+      path: e.path,
+      severity,
+      context: params
+    };
+  });
+}
+
+// src/llm/types.ts
+var LLM_PROVIDERS = [
+  "openai",
+  "openai-compatible",
+  "anthropic",
+  "google",
+  "groq",
+  "xai",
+  "cohere"
+];
+var LLM_ROUTERS = ["vercel", "in-built"];
+var SUPPORTED_FILE_TYPES = ["pdf", "image", "audio"];
+export {
+  ErrorScope,
+  ErrorType,
+  LLM_PROVIDERS,
+  LLM_ROUTERS,
+  SUPPORTED_FILE_TYPES,
+  toError,
+  zodToIssues
+};