@dexto/core 1.1.4 → 1.1.6

package/dist/utils/result.d.cts

@@ -0,0 +1,180 @@
+import { ZodError, z } from 'zod';
+import { Issue } from '../errors/types.cjs';
+import '../agent/error-codes.cjs';
+import '../config/error-codes.cjs';
+import '../context/error-codes.cjs';
+import '../llm/error-codes.cjs';
+import '../mcp/error-codes.cjs';
+import '../session/error-codes.cjs';
+import '../storage/error-codes.cjs';
+import '../systemPrompt/error-codes.cjs';
+import '../tools/error-codes.cjs';
+import '../preferences/error-codes.cjs';
+import '../agent/registry/error-codes.cjs';
+
+/** Trim and require non-empty after trim */
+declare const NonEmptyTrimmed: z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>;
+declare const OptionalURL: z.ZodOptional<z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>, string | undefined, string>>;
+declare const EnvExpandedString: (env?: Record<string, string | undefined>) => z.ZodEffects<z.ZodString, string, string>;
+declare const NonEmptyEnvExpandedString: (env?: Record<string, string | undefined>) => z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>;
+declare const RequiredEnvURL: (env?: Record<string, string | undefined>) => z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>;
+/**
+ * A discriminated union result type that can be either successful or failed
+ * Provides type safety by ensuring data is only available on success
+ * @param T - The type of the data on success
+ * @param C - The type of the context for issues
+ */
+type Result<T, C = unknown> = {
+    ok: true;
+    data: T;
+    issues: Issue<C>[];
+} | {
+    ok: false;
+    issues: Issue<C>[];
+};
+/**
+ * Create a successful result with validated data and optional warnings.
+ *
+ * **Usage Guidelines:**
+ * - Use for operations that completed successfully, even with warnings
+ * - Include warnings for non-blocking issues (API key too short, fallback model used, etc.)
+ * - DextoAgent methods should prefer this over throwing exceptions
+ * - API layer maps this to 2xx status codes
+ *
+ * @param data - The successfully validated/processed data
+ * @param issues - Optional warnings or informational issues (defaults to empty array)
+ * @returns A successful Result with ok: true
+ *
+ * @example
+ * ```typescript
+ * // Success with no warnings
+ * return ok(validatedConfig);
+ *
+ * // Success with warnings
+ * return ok(validatedConfig, [
+ *   { code: 'llm_short_api_key', message: 'API key seems short', severity: 'warning', context: {} }
+ * ]);
+ * ```
+ */
+declare const ok: <T, C = unknown>(data: T, issues?: Issue<C>[]) => Result<T, C>;
+/**
+ * Create a failed result with blocking errors that prevent operation completion.
+ *
+ * **Usage Guidelines:**
+ * - Use for validation failures, business rule violations, or any error that should stop execution
+ * - Do NOT mix with exceptions - choose Result pattern OR throwing, not both
+ * - API layer maps this to 4xx status codes (user/validation errors)
+ * - Issues should have severity: 'error' for blocking problems
+ *
+ * @param issues - Array of error issues that caused the failure (must not be empty)
+ * @returns A failed Result with ok: false and no data
+ *
+ * @example
+ * ```typescript
+ * // Validation failure
+ * return fail([
+ *   {
+ *     code: LLMErrorCode.SWITCH_INPUT_MISSING,
+ *     message: 'At least model or provider must be specified',
+ *     severity: 'error',
+ *     context: {}
+ *   }
+ * ]);
+ *
+ * // Multiple validation errors
+ * return fail([
+ *   { code: 'missing_api_key', message: 'API key required', severity: 'error', context: {} },
+ *   { code: 'invalid_model', message: 'Model not supported', severity: 'error', context: {} }
+ * ]);
+ * ```
+ */
+declare const fail: <T = never, C = unknown>(issues: Issue<C>[]) => Result<T, C>;
+/**
+ * Check if a list of issues contains any blocking errors (non-warning severity).
+ *
+ * **Usage Guidelines:**
+ * - Use to determine if a Result should be ok: false
+ * - Warnings don't count as errors - operations can succeed with warnings
+ * - Useful in validation functions to decide success vs failure
+ *
+ * @param issues - Array of issues to check
+ * @returns true if any issue has severity other than 'warning', false otherwise
+ *
+ * @example
+ * ```typescript
+ * const issues = [
+ *   { severity: 'warning', message: 'API key seems short' },
+ *   { severity: 'error', message: 'Model not found' }
+ * ];
+ *
+ * if (hasErrors(issues)) {
+ *   return fail(issues); // Contains errors, operation fails
+ * } else {
+ *   return ok(data, issues); // Only warnings, operation succeeds
+ * }
+ * ```
+ */
+declare function hasErrors<C>(issues: Issue<C>[]): boolean;
+/**
+ * Separate issues into errors (blocking) and warnings (non-blocking) for different handling.
+ *
+ * **Usage Guidelines:**
+ * - Use when you need to handle errors and warnings differently
+ * - Errors should block operation, warnings should be logged/reported but allow success
+ * - Useful in API responses to show both what failed and what succeeded with caveats
+ *
+ * @param issues - Array of mixed issues to categorize
+ * @returns Object with separate arrays for errors and warnings
+ *
+ * @example
+ * ```typescript
+ * const { errors, warnings } = splitIssues(allIssues);
+ *
+ * if (errors.length > 0) {
+ *   logger.error('Validation failed:', errors);
+ *   return fail(errors);
+ * }
+ *
+ * if (warnings.length > 0) {
+ *   logger.warn('Validation succeeded with warnings:', warnings);
+ * }
+ *
+ * return ok(data, warnings);
+ * ```
+ */
+declare function splitIssues<C>(issues: Issue<C>[]): {
+    errors: Issue<C>[];
+    warnings: Issue<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>[];
+
+export { EnvExpandedString, NonEmptyEnvExpandedString, NonEmptyTrimmed, OptionalURL, RequiredEnvURL, type Result, fail, hasErrors, ok, splitIssues, zodToIssues };

package/dist/utils/result.d.ts

@@ -0,0 +1,180 @@
+import { ZodError, z } from 'zod';
+import { Issue } from '../errors/types.js';
+import '../agent/error-codes.js';
+import '../config/error-codes.js';
+import '../context/error-codes.js';
+import '../llm/error-codes.js';
+import '../mcp/error-codes.js';
+import '../session/error-codes.js';
+import '../storage/error-codes.js';
+import '../systemPrompt/error-codes.js';
+import '../tools/error-codes.js';
+import '../preferences/error-codes.js';
+import '../agent/registry/error-codes.js';
+
+/** Trim and require non-empty after trim */
+declare const NonEmptyTrimmed: z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>;
+declare const OptionalURL: z.ZodOptional<z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>, string | undefined, string>>;
+declare const EnvExpandedString: (env?: Record<string, string | undefined>) => z.ZodEffects<z.ZodString, string, string>;
+declare const NonEmptyEnvExpandedString: (env?: Record<string, string | undefined>) => z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>;
+declare const RequiredEnvURL: (env?: Record<string, string | undefined>) => z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>;
+/**
+ * A discriminated union result type that can be either successful or failed
+ * Provides type safety by ensuring data is only available on success
+ * @param T - The type of the data on success
+ * @param C - The type of the context for issues
+ */
+type Result<T, C = unknown> = {
+    ok: true;
+    data: T;
+    issues: Issue<C>[];
+} | {
+    ok: false;
+    issues: Issue<C>[];
+};
+/**
+ * Create a successful result with validated data and optional warnings.
+ *
+ * **Usage Guidelines:**
+ * - Use for operations that completed successfully, even with warnings
+ * - Include warnings for non-blocking issues (API key too short, fallback model used, etc.)
+ * - DextoAgent methods should prefer this over throwing exceptions
+ * - API layer maps this to 2xx status codes
+ *
+ * @param data - The successfully validated/processed data
+ * @param issues - Optional warnings or informational issues (defaults to empty array)
+ * @returns A successful Result with ok: true
+ *
+ * @example
+ * ```typescript
+ * // Success with no warnings
+ * return ok(validatedConfig);
+ *
+ * // Success with warnings
+ * return ok(validatedConfig, [
+ *   { code: 'llm_short_api_key', message: 'API key seems short', severity: 'warning', context: {} }
+ * ]);
+ * ```
+ */
+declare const ok: <T, C = unknown>(data: T, issues?: Issue<C>[]) => Result<T, C>;
+/**
+ * Create a failed result with blocking errors that prevent operation completion.
+ *
+ * **Usage Guidelines:**
+ * - Use for validation failures, business rule violations, or any error that should stop execution
+ * - Do NOT mix with exceptions - choose Result pattern OR throwing, not both
+ * - API layer maps this to 4xx status codes (user/validation errors)
+ * - Issues should have severity: 'error' for blocking problems
+ *
+ * @param issues - Array of error issues that caused the failure (must not be empty)
+ * @returns A failed Result with ok: false and no data
+ *
+ * @example
+ * ```typescript
+ * // Validation failure
+ * return fail([
+ *   {
+ *     code: LLMErrorCode.SWITCH_INPUT_MISSING,
+ *     message: 'At least model or provider must be specified',
+ *     severity: 'error',
+ *     context: {}
+ *   }
+ * ]);
+ *
+ * // Multiple validation errors
+ * return fail([
+ *   { code: 'missing_api_key', message: 'API key required', severity: 'error', context: {} },
+ *   { code: 'invalid_model', message: 'Model not supported', severity: 'error', context: {} }
+ * ]);
+ * ```
+ */
+declare const fail: <T = never, C = unknown>(issues: Issue<C>[]) => Result<T, C>;
+/**
+ * Check if a list of issues contains any blocking errors (non-warning severity).
+ *
+ * **Usage Guidelines:**
+ * - Use to determine if a Result should be ok: false
+ * - Warnings don't count as errors - operations can succeed with warnings
+ * - Useful in validation functions to decide success vs failure
+ *
+ * @param issues - Array of issues to check
+ * @returns true if any issue has severity other than 'warning', false otherwise
+ *
+ * @example
+ * ```typescript
+ * const issues = [
+ *   { severity: 'warning', message: 'API key seems short' },
+ *   { severity: 'error', message: 'Model not found' }
+ * ];
+ *
+ * if (hasErrors(issues)) {
+ *   return fail(issues); // Contains errors, operation fails
+ * } else {
+ *   return ok(data, issues); // Only warnings, operation succeeds
+ * }
+ * ```
+ */
+declare function hasErrors<C>(issues: Issue<C>[]): boolean;
+/**
+ * Separate issues into errors (blocking) and warnings (non-blocking) for different handling.
+ *
+ * **Usage Guidelines:**
+ * - Use when you need to handle errors and warnings differently
+ * - Errors should block operation, warnings should be logged/reported but allow success
+ * - Useful in API responses to show both what failed and what succeeded with caveats
+ *
+ * @param issues - Array of mixed issues to categorize
+ * @returns Object with separate arrays for errors and warnings
+ *
+ * @example
+ * ```typescript
+ * const { errors, warnings } = splitIssues(allIssues);
+ *
+ * if (errors.length > 0) {
+ *   logger.error('Validation failed:', errors);
+ *   return fail(errors);
+ * }
+ *
+ * if (warnings.length > 0) {
+ *   logger.warn('Validation succeeded with warnings:', warnings);
+ * }
+ *
+ * return ok(data, warnings);
+ * ```
+ */
+declare function splitIssues<C>(issues: Issue<C>[]): {
+    errors: Issue<C>[];
+    warnings: Issue<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>[];
+
+export { EnvExpandedString, NonEmptyEnvExpandedString, NonEmptyTrimmed, OptionalURL, RequiredEnvURL, type Result, fail, hasErrors, ok, splitIssues, zodToIssues };

package/dist/utils/result.js

@@ -0,0 +1,82 @@
+import { z } from "zod";
+import { ErrorScope, ErrorType } from "../errors/types.js";
+const 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;
+  }
+}
+const OptionalURL = z.string().transform((s) => s.trim()).refine((s) => s === "" || isValidUrl(s), { message: "Invalid URL" }).transform((s) => s === "" ? void 0 : s).optional();
+const EnvExpandedString = (env) => z.string().transform((input) => {
+  if (typeof input !== "string") return "";
+  const envToUse = env ?? process.env;
+  const out = input.replace(
+    /\$([A-Z_][A-Z0-9_]*)|\${([A-Z_][A-Z0-9_]*)}/gi,
+    (_, a, b) => envToUse[a || b] ?? ""
+  );
+  return out.trim();
+});
+const NonEmptyEnvExpandedString = (env) => EnvExpandedString(env).refine((s) => s.length > 0, {
+  message: "Value is required"
+});
+const RequiredEnvURL = (env) => EnvExpandedString(env).refine(
+  (s) => {
+    try {
+      const u = new URL(s);
+      return u.protocol === "http:" || u.protocol === "https:";
+    } catch {
+      return false;
+    }
+  },
+  { message: "Invalid URL" }
+);
+const ok = (data, issues = []) => ({
+  ok: true,
+  data,
+  issues
+  // warnings live alongside errors here
+});
+const fail = (issues) => ({
+  ok: false,
+  issues
+});
+function hasErrors(issues) {
+  return issues.some((i) => i.severity !== "warning");
+}
+function splitIssues(issues) {
+  return {
+    errors: issues.filter((i) => i.severity !== "warning"),
+    warnings: issues.filter((i) => i.severity === "warning")
+  };
+}
+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 ?? ErrorScope.AGENT,
+      // Fallback for non-custom Zod errors
+      // Treat plain Zod schema failures as USER errors by default
+      type: params.type ?? ErrorType.USER,
+      path: e.path,
+      severity,
+      context: params
+    };
+  });
+}
+export {
+  EnvExpandedString,
+  NonEmptyEnvExpandedString,
+  NonEmptyTrimmed,
+  OptionalURL,
+  RequiredEnvURL,
+  fail,
+  hasErrors,
+  ok,
+  splitIssues,
+  zodToIssues
+};

package/dist/utils/safe-stringify.cjs

@@ -0,0 +1,57 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var safe_stringify_exports = {};
+__export(safe_stringify_exports, {
+  safeStringify: () => safeStringify
+});
+module.exports = __toCommonJS(safe_stringify_exports);
+var import_redactor = require("./redactor.js");
+function safeStringify(value, maxLen = 1e3) {
+  try {
+    if (typeof value === "bigint") {
+      return value.toString();
+    }
+    const redacted = (0, import_redactor.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]";
+    }
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  safeStringify
+});

package/dist/utils/safe-stringify.d.cts

@@ -0,0 +1,7 @@
+/**
+ * Safe stringify that handles circular references, BigInt, and limits output size
+ * Also redacts sensitive data to prevent PII leaks in error messages
+ */
+declare function safeStringify(value: unknown, maxLen?: number): string;
+
+export { safeStringify };

package/dist/utils/safe-stringify.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Safe stringify that handles circular references, BigInt, and limits output size
+ * Also redacts sensitive data to prevent PII leaks in error messages
+ */
+declare function safeStringify(value: unknown, maxLen?: number): string;
+
+export { safeStringify };

package/dist/utils/safe-stringify.js

@@ -0,0 +1,33 @@
+import { redactSensitiveData } from "./redactor.js";
+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]";
+    }
+  }
+}
+export {
+  safeStringify
+};

package/dist/utils/schema.cjs

@@ -0,0 +1,42 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var schema_exports = {};
+__export(schema_exports, {
+  convertZodSchemaToJsonSchema: () => convertZodSchemaToJsonSchema
+});
+module.exports = __toCommonJS(schema_exports);
+var import_zod_to_json_schema = require("zod-to-json-schema");
+var import_logger = require("../logger/index.js");
+function convertZodSchemaToJsonSchema(zodSchema) {
+  try {
+    return (0, import_zod_to_json_schema.zodToJsonSchema)(zodSchema);
+  } catch (error) {
+    import_logger.logger.warn(
+      `Failed to convert Zod schema to JSON Schema: ${error instanceof Error ? error.message : String(error)}`
+    );
+    return {
+      type: "object",
+      properties: {}
+    };
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  convertZodSchemaToJsonSchema
+});

package/dist/utils/schema.d.cts

@@ -0,0 +1,6 @@
+/**
+ * Convert Zod schema to JSON Schema format for tool parameters
+ */
+declare function convertZodSchemaToJsonSchema(zodSchema: any): any;
+
+export { convertZodSchemaToJsonSchema };

package/dist/utils/schema.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Convert Zod schema to JSON Schema format for tool parameters
+ */
+declare function convertZodSchemaToJsonSchema(zodSchema: any): any;
+
+export { convertZodSchemaToJsonSchema };

package/dist/utils/schema.js

@@ -0,0 +1,18 @@
+import { zodToJsonSchema } from "zod-to-json-schema";
+import { logger } from "../logger/index.js";
+function convertZodSchemaToJsonSchema(zodSchema) {
+  try {
+    return zodToJsonSchema(zodSchema);
+  } catch (error) {
+    logger.warn(
+      `Failed to convert Zod schema to JSON Schema: ${error instanceof Error ? error.message : String(error)}`
+    );
+    return {
+      type: "object",
+      properties: {}
+    };
+  }
+}
+export {
+  convertZodSchemaToJsonSchema
+};