@a5c-ai/babysitter-sdk 0.0.169 → 0.0.170-staging.00aac85c

package/dist/runtime/exceptions.d.ts

@@ -1,15 +1,158 @@
 import { EffectAction, SerializedEffectError } from "./types";
 import { type ParallelBatch } from "../tasks/batching";
+/**
+ * Error category enum for classifying errors by their source and type.
+ * This helps users understand the nature of errors and how to address them.
+ */
+export declare enum ErrorCategory {
+    /** Configuration errors - issues with settings, environment, or setup */
+    Configuration = "CONFIGURATION",
+    /** Validation errors - input data or parameter validation failures */
+    Validation = "VALIDATION",
+    /** Runtime errors - errors during execution of processes or tasks */
+    Runtime = "RUNTIME",
+    /** External errors - failures from external services, APIs, or dependencies */
+    External = "EXTERNAL",
+    /** Internal errors - unexpected internal failures, bugs, or invariant violations */
+    Internal = "INTERNAL"
+}
+/**
+ * Human-readable descriptions for each error category
+ */
+export declare const ERROR_CATEGORY_DESCRIPTIONS: Record<ErrorCategory, string>;
+/**
+ * Context variables that can be interpolated into error templates
+ */
+export interface ErrorTemplateContext {
+    [key: string]: string | number | boolean | undefined | null;
+}
+/**
+ * Error template definition with message pattern and default context
+ */
+export interface ErrorTemplate {
+    /** Template string with {{variable}} placeholders */
+    pattern: string;
+    /** Error category for this template */
+    category: ErrorCategory;
+    /** Default next steps for this error type */
+    defaultNextSteps?: string[];
+    /** Default suggestions for this error type */
+    defaultSuggestions?: string[];
+}
+/**
+ * Built-in error templates for common error scenarios
+ */
+export declare const ERROR_TEMPLATES: {
+    readonly MISSING_REQUIRED_FLAG: {
+        readonly pattern: "Missing required flag: {{flag}}";
+        readonly category: ErrorCategory.Validation;
+        readonly defaultNextSteps: ["Add the missing flag to your command", "Run with --help to see all available options"];
+    };
+    readonly INVALID_FLAG_VALUE: {
+        readonly pattern: "Invalid value for {{flag}}: {{value}}. Expected {{expected}}";
+        readonly category: ErrorCategory.Validation;
+        readonly defaultNextSteps: ["Check the expected format for this flag", "Run with --help for usage information"];
+    };
+    readonly FILE_NOT_FOUND: {
+        readonly pattern: "File not found: {{path}}";
+        readonly category: ErrorCategory.Configuration;
+        readonly defaultNextSteps: ["Verify the file path is correct", "Check that the file exists and is readable"];
+    };
+    readonly PROCESS_NOT_FOUND: {
+        readonly pattern: "Process entry file not found: {{path}}";
+        readonly category: ErrorCategory.Configuration;
+        readonly defaultNextSteps: ["Ensure the path is correct and points to a valid JS/TS module", "Check that the file has been compiled if using TypeScript"];
+    };
+    readonly EXPORT_NOT_FOUND: {
+        readonly pattern: "Process module {{path}} does not export '{{exportName}}'";
+        readonly category: ErrorCategory.Configuration;
+        readonly defaultNextSteps: ["Check available exports in your module", "Use --entry {{path}}#default for default export"];
+        readonly defaultSuggestions: ["Did you mean to use a different export name?"];
+    };
+    readonly EFFECT_NOT_FOUND: {
+        readonly pattern: "Effect {{effectId}} not found at {{runDir}}";
+        readonly category: ErrorCategory.Validation;
+        readonly defaultNextSteps: ["Verify the effect ID is correct", "Run task:list to see available effects"];
+    };
+    readonly EFFECT_WRONG_STATUS: {
+        readonly pattern: "Effect {{effectId}} is not {{expectedStatus}} (current status={{actualStatus}})";
+        readonly category: ErrorCategory.Validation;
+        readonly defaultNextSteps: ["Check the current effect status with task:show", "Ensure you're operating on the correct effect"];
+    };
+    readonly RUN_NOT_FOUND: {
+        readonly pattern: "Run directory not found: {{runDir}}";
+        readonly category: ErrorCategory.Configuration;
+        readonly defaultNextSteps: ["Verify the run directory path", "Ensure the run has been created with run:create"];
+    };
+    readonly JSON_PARSE_ERROR: {
+        readonly pattern: "Failed to parse {{file}} as JSON: {{error}}";
+        readonly category: ErrorCategory.Validation;
+        readonly defaultNextSteps: ["Check that the file contains valid JSON", "Validate JSON syntax with a linter"];
+    };
+    readonly MISSING_PROCESS_CONTEXT: {
+        readonly pattern: "No active process context found on the current async call stack";
+        readonly category: ErrorCategory.Runtime;
+        readonly defaultNextSteps: ["Ensure you are calling this from within a babysitter process function", "Check that async context is properly maintained"];
+    };
+    readonly INVOCATION_COLLISION: {
+        readonly pattern: "Invocation key {{invocationKey}} is already in use within this run";
+        readonly category: ErrorCategory.Runtime;
+        readonly defaultNextSteps: ["Ensure unique invocation keys for each task invocation", "Check for duplicate task calls in your process"];
+    };
+};
+export type ErrorTemplateKey = keyof typeof ERROR_TEMPLATES;
+/**
+ * Interpolates context variables into a template pattern
+ */
+export declare function interpolateTemplate(pattern: string, context: ErrorTemplateContext): string;
+/**
+ * Creates an error message from a template and context
+ */
+export declare function createErrorMessage(templateKey: ErrorTemplateKey, context: ErrorTemplateContext): string;
+/**
+ * Suggests corrections for a potentially misspelled command
+ */
+export declare function suggestCommand(input: string): string | undefined;
+/**
+ * Suggests corrections for a potentially misspelled flag
+ */
+export declare function suggestFlag(input: string): string | undefined;
+/**
+ * Generic suggestion helper that finds the closest match from a list
+ */
+export declare function suggestFix(input: string, validOptions: string[], maxDistance?: number): string | undefined;
 export interface BabysitterErrorDetails {
     [key: string]: unknown;
 }
+/**
+ * Extended error options including category and suggestions
+ */
+export interface BabysitterErrorOptions {
+    /** Error category for classification */
+    category?: ErrorCategory;
+    /** Suggested fixes or "did you mean" hints */
+    suggestions?: string[];
+    /** Actionable next steps for the user */
+    nextSteps?: string[];
+    /** Additional context details */
+    details?: BabysitterErrorDetails;
+    /** The original error if this wraps another error */
+    cause?: Error;
+}
 export declare class BabysitterRuntimeError extends Error {
     readonly details?: BabysitterErrorDetails;
-    constructor(name: string, message: string, details?: BabysitterErrorDetails);
+    readonly category: ErrorCategory;
+    readonly suggestions: string[];
+    readonly nextSteps: string[];
+    constructor(name: string, message: string, options?: BabysitterErrorOptions | BabysitterErrorDetails);
+    /**
+     * Creates an error from a template
+     */
+    static fromTemplate(name: string, templateKey: ErrorTemplateKey, context: ErrorTemplateContext, additionalOptions?: Partial<BabysitterErrorOptions>): BabysitterRuntimeError;
 }
 export declare class BabysitterIntrinsicError extends BabysitterRuntimeError {
     readonly isIntrinsic = true;
-    constructor(name: string, message: string, details?: BabysitterErrorDetails);
+    constructor(name: string, message: string, options?: BabysitterErrorOptions | BabysitterErrorDetails);
 }
 export declare class EffectRequestedError extends BabysitterIntrinsicError {
     readonly action: EffectAction;
@@ -29,7 +172,7 @@ export declare class InvocationCollisionError extends BabysitterRuntimeError {
     constructor(invocationKey: string);
 }
 export declare class RunFailedError extends BabysitterRuntimeError {
-    constructor(message: string, details?: BabysitterErrorDetails);
+    constructor(message: string, options?: BabysitterErrorOptions | BabysitterErrorDetails);
 }
 export declare class MissingProcessContextError extends BabysitterRuntimeError {
     constructor();
@@ -40,6 +183,46 @@ export declare class InvalidTaskDefinitionError extends BabysitterRuntimeError {
 export declare class InvalidSleepTargetError extends BabysitterRuntimeError {
     constructor(value: string | number);
 }
+/**
+ * Options for formatting errors
+ */
+export interface FormatErrorOptions {
+    /** Whether to include ANSI color codes */
+    colors?: boolean;
+    /** Whether to include the stack trace */
+    includeStack?: boolean;
+    /** Prefix for the error output */
+    prefix?: string;
+}
+/**
+ * Formats an error with full context including category, suggestions, and next steps
+ */
+export declare function formatErrorWithContext(error: Error, options?: FormatErrorOptions): string;
+/**
+ * Formats next steps as a bulleted list
+ */
+export declare function formatNextSteps(nextSteps: string[], options?: {
+    prefix?: string;
+    colors?: boolean;
+}): string;
+/**
+ * Structured error output for JSON formatting
+ */
+export interface StructuredError {
+    name: string;
+    message: string;
+    category: ErrorCategory;
+    categoryDescription: string;
+    suggestions: string[];
+    nextSteps: string[];
+    details?: BabysitterErrorDetails;
+    stack?: string;
+}
+/**
+ * Converts an error to a structured JSON-serializable format
+ */
+export declare function toStructuredError(error: Error, includeStack?: boolean): StructuredError;
 export declare function isIntrinsicError(error: unknown): error is BabysitterIntrinsicError;
+export declare function isBabysitterError(error: unknown): error is BabysitterRuntimeError;
 export declare function rehydrateSerializedError(data?: SerializedEffectError): Error;
 //# sourceMappingURL=exceptions.d.ts.map

package/dist/runtime/exceptions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"exceptions.d.ts","sourceRoot":"","sources":["../../src/runtime/exceptions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAC9D,OAAO,EAA4B,KAAK,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEjF,MAAM,WAAW,sBAAsB;IACrC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,QAAQ,CAAC,OAAO,CAAC,EAAE,sBAAsB,CAAC;gBAE9B,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,sBAAsB;CAK5E;AAED,qBAAa,wBAAyB,SAAQ,sBAAsB;IAClE,QAAQ,CAAC,WAAW,QAAQ;gBAEhB,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,sBAAsB;CAG5E;AAED,qBAAa,oBAAqB,SAAQ,wBAAwB;aACpC,MAAM,EAAE,YAAY;gBAApB,MAAM,EAAE,YAAY;CAGjD;AAED,qBAAa,kBAAmB,SAAQ,wBAAwB;aAClC,MAAM,EAAE,YAAY;gBAApB,MAAM,EAAE,YAAY;CAGjD;AAED,qBAAa,oBAAqB,SAAQ,wBAAwB;aAEpC,KAAK,EAAE,aAAa;IADhD,QAAQ,CAAC,OAAO,EAAE,YAAY,EAAE,CAAC;gBACL,KAAK,EAAE,aAAa;CAOjD;AAED,qBAAa,wBAAyB,SAAQ,sBAAsB;aACtC,aAAa,EAAE,MAAM;gBAArB,aAAa,EAAE,MAAM;CAOlD;AAED,qBAAa,cAAe,SAAQ,sBAAsB;gBAC5C,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,sBAAsB;CAG9D;AAED,qBAAa,0BAA2B,SAAQ,sBAAsB;;CAIrE;AAED,qBAAa,0BAA2B,SAAQ,sBAAsB;gBACxD,MAAM,EAAE,MAAM;CAG3B;AAED,qBAAa,uBAAwB,SAAQ,sBAAsB;gBACrD,KAAK,EAAE,MAAM,GAAG,MAAM;CAGnC;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,wBAAwB,CAElF;AAID,wBAAgB,wBAAwB,CAAC,IAAI,CAAC,EAAE,qBAAqB,GAAG,KAAK,CAY5E"}
+{"version":3,"file":"exceptions.d.ts","sourceRoot":"","sources":["../../src/runtime/exceptions.ts"],"names":[],"mappings":"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"}