@stackfactor/agent-utils 1.1.5 → 1.1.7

package/dist/cjs/const.d.ts

@@ -8,6 +8,7 @@ declare const _default: {
     };
     ERROR: {
         UNABLE_TO_GENERATE_CONTENT: string;
+        MISSING_INFORMATION: string;
         UNEXPECTED_ERROR: string;
         UNSUPPORTED_MODEL: string;
         QUOTA_EXHAUSTED: string;

package/dist/cjs/const.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"const.d.ts","sourceRoot":"","sources":["../../src/const.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;AAAA,wBAgBE"}
+{"version":3,"file":"const.d.ts","sourceRoot":"","sources":["../../src/const.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,wBAiBE"}

package/dist/cjs/const.js

@@ -10,6 +10,7 @@ exports.default = {
     },
     ERROR: {
         UNABLE_TO_GENERATE_CONTENT: "Unable to generate content",
+        MISSING_INFORMATION: "Required information is missing or invalid",
         UNEXPECTED_ERROR: "An unexpected error occured. If the issue persists please contact the StackFactor support team at support@stackfactor.ai",
         UNSUPPORTED_MODEL: "The specified model is not supported",
         QUOTA_EXHAUSTED: "Agent session quota exhausted: no remaining budget for additional LLM calls.",

package/dist/cjs/errorHandling.d.ts

@@ -1,3 +1,74 @@
+/** Winston log levels accepted by the shared {@link logger}. */
+type LogLevel = "error" | "warn" | "info" | "http" | "verbose" | "debug" | "silly";
+/**
+ * The normalised shape every error is reduced to: a numeric code, a human-readable
+ * message, optional structured `details`, and the failing `integration` name when
+ * the error originated from an external service call.
+ */
+export interface ParsedError {
+    code?: number;
+    message?: string;
+    details?: any;
+    integration?: string;
+}
+/**
+ * A structured, throwable error that normalises any caught value, logs itself
+ * through the shared {@link logger}, and serialises to the `ErrorInfo` wire frame
+ * (`{ code, message }`) that {@link serve} sends and unwraps across the gRPC
+ * boundary.
+ *
+ * @example
+ *   try {
+ *     await doWork();
+ *   } catch (err) {
+ *     throw AppError.from(err).log(request).toWireError();
+ *   }
+ */
+export declare class AppError extends Error {
+    /** Numeric HTTP/application status code; defaults to 500 when unknown. */
+    readonly code: number;
+    /** Optional structured supplementary information (e.g. validation details). */
+    readonly details?: any;
+    /** Name of the external integration that failed, when applicable. */
+    readonly integration?: string;
+    constructor(parsed?: ParsedError);
+    /**
+     * Normalise any thrown value into an {@link AppError}. Idempotent — an existing
+     * `AppError` is returned unchanged.
+     */
+    static from(error: unknown): AppError;
+    /**
+     * Inspect any value and return its {@link ParsedError} shape without
+     * constructing an error instance.
+     */
+    static parse(error: unknown): ParsedError;
+    /**
+     * The serialisable payload: code + message, plus details/integration when
+     * present. The extra fields are dropped by proto-loader on the `ErrorInfo`
+     * frame and preserved everywhere else (logs, JSON responses).
+     */
+    toFrame(): ParsedError & {
+        code: number;
+        message: string;
+    };
+    toJSON(): ParsedError;
+    /**
+     * Encode this error for rethrow across the agent boundary. {@link serve}'s
+     * handler unwraps `error.message` as JSON, so the structured payload lives
+     * there.
+     */
+    toWireError(): Error;
+    /**
+     * Log this error through the shared {@link logger} and return `this` for
+     * chaining (`AppError.from(err).log(request).toWireError()`).
+     *
+     * @param request - HTTP/agent request used by the logger to prefix the user's
+     *   email; may be `null`.
+     * @param level - Log level; defaults to `"error"`.
+     * @param options - Extra structured fields merged into the log record.
+     */
+    log(request?: any, level?: LogLevel, options?: any): this;
+}
 declare const _default: {
     /**
      * Creates a structured error object with a code, message, and optional details.
@@ -15,6 +86,16 @@ declare const _default: {
         details: any;
         stack: string;
     };
+    /** {@link AppError.parse} — normalise any value to a {@link ParsedError}. */
+    parse: (error: any) => ParsedError;
+    /** {@link AppError.from} — normalise any value to an {@link AppError}. */
+    from: typeof AppError.from;
+    /** Normalise + log a caught value in one call; returns the {@link AppError}. */
+    handle: (error: unknown, request?: any, options?: any) => AppError;
+    /** Test whether a value is a valid HTTP status code. */
+    isHttpCode: (code: any) => code is number;
+    /** The {@link AppError} class. */
+    AppError: typeof AppError;
 };
 export default _default;
 //# sourceMappingURL=errorHandling.d.ts.map

package/dist/cjs/errorHandling.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errorHandling.d.ts","sourceRoot":"","sources":["../../src/errorHandling.ts"],"names":[],"mappings":";IACE;;;;;;;;;OASG;wBACiB,MAAM,gBAAgB,MAAM,YAAW,GAAG;;;;;;;AAXhE,wBAoBE"}
+{"version":3,"file":"errorHandling.d.ts","sourceRoot":"","sources":["../../src/errorHandling.ts"],"names":[],"mappings":"AAGA,gEAAgE;AAChE,KAAK,QAAQ,GACT,OAAO,GACP,MAAM,GACN,MAAM,GACN,MAAM,GACN,SAAS,GACT,OAAO,GACP,OAAO,CAAC;AAEZ;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,GAAG,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AA8GD;;;;;;;;;;;;GAYG;AACH,qBAAa,QAAS,SAAQ,KAAK;IACjC,0EAA0E;IAC1E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,+EAA+E;IAC/E,QAAQ,CAAC,OAAO,CAAC,EAAE,GAAG,CAAC;IACvB,qEAAqE;IACrE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;gBAElB,MAAM,GAAE,WAAgB;IAUpC;;;OAGG;IACH,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ;IAKrC;;;OAGG;IACH,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW;IAIzC;;;;OAIG;IACH,OAAO,IAAI,WAAW,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE;IAS1D,MAAM,IAAI,WAAW;IAIrB;;;;OAIG;IACH,WAAW,IAAI,KAAK;IAIpB;;;;;;;;OAQG;IACH,GAAG,CAAC,OAAO,GAAE,GAAU,EAAE,KAAK,GAAE,QAAkB,EAAE,OAAO,GAAE,GAAQ,GAAG,IAAI;CAU7E;;IAkBC;;;;;;;;;OASG;wBACiB,MAAM,gBAAgB,MAAM,YAAW,GAAG;;;;;;IAU9D,6EAA6E;mBApOpD,GAAG,KAAG,WAAW;IAsO1C,0EAA0E;;IAE1E,gFAAgF;oBA9BzE,OAAO,YACL,GAAG,YACH,GAAG,KACX,QAAQ;IA6BT,wDAAwD;uBArPhC,GAAG,KAAG,IAAI,IAAI,MAAM;IAuP5C,kCAAkC;;;AA7BpC,wBA+BE"}

package/dist/cjs/errorHandling.js

@@ -1,5 +1,211 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.AppError = void 0;
+const const_js_1 = __importDefault(require("./const.js"));
+const logger_js_1 = __importDefault(require("./logger.js"));
+/** True when `code` is a syntactically valid HTTP status (100–599). */
+const isHttpCode = (code) => typeof code === "number" && Number.isInteger(code) && code >= 100 && code <= 599;
+/**
+ * Reduce any thrown value — Error, axios failure, validation error, structured
+ * payload from {@link create}, JSON-encoded rethrow, or bare string — into a
+ * consistent {@link ParsedError}. Never throws; falls back to a generic 500.
+ *
+ * @param error - Anything that was caught or thrown.
+ * @returns The normalised error shape.
+ */
+const parseError = (error) => {
+    try {
+        if (typeof error === "object" && error !== null) {
+            // Integration calls tag the failing integration's name.
+            const integration = error.integrationName;
+            // express-validator style validation error (e.g. runSocketValidators).
+            if (error.message === "VALIDATION_ERROR" && Array.isArray(error.details)) {
+                return {
+                    code: const_js_1.default.HTTP_CODES.BAD_REQUEST,
+                    message: const_js_1.default.ERROR.MISSING_INFORMATION,
+                    details: error.details,
+                    integration,
+                };
+            }
+            // Structured error produced by create().
+            if (error.code && error.message && isHttpCode(error.code)) {
+                return {
+                    code: error.code,
+                    message: error.message,
+                    details: error.details,
+                    integration,
+                };
+            }
+            // axios error format.
+            if (error.isAxiosError && error.response) {
+                return {
+                    code: error.response.status,
+                    message: error.response.data?.message || error.response.statusText,
+                    integration,
+                };
+            }
+            // Any other error carrying an HTTP-style response.
+            if (error.response) {
+                return {
+                    code: error.response.status,
+                    message: error.response.data?.message || error.response.statusText,
+                    integration,
+                };
+            }
+            // Standard Error objects or objects with a message.
+            if (typeof error.message === "string") {
+                // The message may itself be a JSON-encoded error — agents rethrow across
+                // the gRPC boundary as `new Error(JSON.stringify({ code, message }))`.
+                try {
+                    const parsed = JSON.parse(error.message);
+                    if (parsed && (parsed.code || parsed.message)) {
+                        return {
+                            code: isHttpCode(parsed.code) ? parsed.code : undefined,
+                            message: parsed.message,
+                            details: parsed.details,
+                            integration: parsed.integration ?? integration,
+                        };
+                    }
+                }
+                catch {
+                    // Not JSON — use the message as-is.
+                }
+                return {
+                    code: error.message.includes("validation failed")
+                        ? const_js_1.default.HTTP_CODES.BAD_REQUEST
+                        : undefined,
+                    message: error.message,
+                    integration,
+                };
+            }
+            return { message: const_js_1.default.ERROR.UNEXPECTED_ERROR, integration };
+        }
+        if (typeof error === "string") {
+            // A JSON-encoded error string, or just a plain message.
+            try {
+                const parsed = JSON.parse(error);
+                return {
+                    code: isHttpCode(parsed.code) ? parsed.code : undefined,
+                    message: parsed.message,
+                    integration: parsed.integration,
+                };
+            }
+            catch {
+                return { message: error };
+            }
+        }
+    }
+    catch {
+        // Fall through to the generic fallback below.
+    }
+    return {
+        code: const_js_1.default.HTTP_CODES.INTERNAL_SERVER_ERROR,
+        message: const_js_1.default.ERROR.UNEXPECTED_ERROR,
+    };
+};
+/**
+ * A structured, throwable error that normalises any caught value, logs itself
+ * through the shared {@link logger}, and serialises to the `ErrorInfo` wire frame
+ * (`{ code, message }`) that {@link serve} sends and unwraps across the gRPC
+ * boundary.
+ *
+ * @example
+ *   try {
+ *     await doWork();
+ *   } catch (err) {
+ *     throw AppError.from(err).log(request).toWireError();
+ *   }
+ */
+class AppError extends Error {
+    /** Numeric HTTP/application status code; defaults to 500 when unknown. */
+    code;
+    /** Optional structured supplementary information (e.g. validation details). */
+    details;
+    /** Name of the external integration that failed, when applicable. */
+    integration;
+    constructor(parsed = {}) {
+        super(parsed.message ?? const_js_1.default.ERROR.UNEXPECTED_ERROR);
+        this.name = "AppError";
+        this.code = parsed.code ?? const_js_1.default.HTTP_CODES.INTERNAL_SERVER_ERROR;
+        this.details = parsed.details;
+        this.integration = parsed.integration;
+        // Restore the prototype chain (TS targeting ES2022 extending built-ins).
+        Object.setPrototypeOf(this, AppError.prototype);
+    }
+    /**
+     * Normalise any thrown value into an {@link AppError}. Idempotent — an existing
+     * `AppError` is returned unchanged.
+     */
+    static from(error) {
+        if (error instanceof AppError)
+            return error;
+        return new AppError(parseError(error));
+    }
+    /**
+     * Inspect any value and return its {@link ParsedError} shape without
+     * constructing an error instance.
+     */
+    static parse(error) {
+        return parseError(error);
+    }
+    /**
+     * The serialisable payload: code + message, plus details/integration when
+     * present. The extra fields are dropped by proto-loader on the `ErrorInfo`
+     * frame and preserved everywhere else (logs, JSON responses).
+     */
+    toFrame() {
+        return {
+            code: this.code,
+            message: this.message,
+            ...(this.details !== undefined ? { details: this.details } : {}),
+            ...(this.integration ? { integration: this.integration } : {}),
+        };
+    }
+    toJSON() {
+        return this.toFrame();
+    }
+    /**
+     * Encode this error for rethrow across the agent boundary. {@link serve}'s
+     * handler unwraps `error.message` as JSON, so the structured payload lives
+     * there.
+     */
+    toWireError() {
+        return new Error(JSON.stringify(this.toFrame()));
+    }
+    /**
+     * Log this error through the shared {@link logger} and return `this` for
+     * chaining (`AppError.from(err).log(request).toWireError()`).
+     *
+     * @param request - HTTP/agent request used by the logger to prefix the user's
+     *   email; may be `null`.
+     * @param level - Log level; defaults to `"error"`.
+     * @param options - Extra structured fields merged into the log record.
+     */
+    log(request = null, level = "error", options = {}) {
+        logger_js_1.default.log(request, level, this.message, {
+            code: this.code,
+            ...(this.details !== undefined ? { details: this.details } : {}),
+            ...(this.integration ? { integration: this.integration } : {}),
+            stack: this.stack,
+            ...options,
+        });
+        return this;
+    }
+}
+exports.AppError = AppError;
+/**
+ * One-shot handler for a caught value: normalise it to an {@link AppError}, log
+ * it, and return it so the caller can serialise (`.toFrame()` / `.toWireError()`)
+ * or rethrow.
+ *
+ * @param error - The caught value.
+ * @param request - Request passed to the logger for the email prefix; may be `null`.
+ * @param options - Extra structured fields merged into the log record.
+ */
+const handle = (error, request = null, options = {}) => AppError.from(error).log(request, "error", options);
 exports.default = {
     /**
      * Creates a structured error object with a code, message, and optional details.
@@ -20,4 +226,14 @@ exports.default = {
             stack: error.stack,
         };
     },
+    /** {@link AppError.parse} — normalise any value to a {@link ParsedError}. */
+    parse: parseError,
+    /** {@link AppError.from} — normalise any value to an {@link AppError}. */
+    from: AppError.from,
+    /** Normalise + log a caught value in one call; returns the {@link AppError}. */
+    handle,
+    /** Test whether a value is a valid HTTP status code. */
+    isHttpCode,
+    /** The {@link AppError} class. */
+    AppError,
 };

package/dist/cjs/index.d.ts

@@ -1,12 +1,13 @@
 import constants from "./const.js";
-import errorHandling from "./errorHandling.js";
+import errorHandling, { AppError } from "./errorHandling.js";
 import langChain from "./langChain.js";
 import logger from "./logger.js";
 import { serve } from "./serve.js";
 import { callAgent, checkAgent } from "./client.js";
 import * as runtimeContext from "./runtimeContext.js";
 export { constants };
-export { errorHandling };
+export { errorHandling, AppError };
+export type { ParsedError } from "./errorHandling.js";
 export { langChain };
 export { logger };
 export { serve };

package/dist/cjs/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,SAAS,MAAM,YAAY,CAAC;AACnC,OAAO,aAAa,MAAM,oBAAoB,CAAC;AAC/C,OAAO,SAAS,MAAM,gBAAgB,CAAC;AACvC,OAAO,MAAM,MAAM,aAAa,CAAC;AACjC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,cAAc,MAAM,qBAAqB,CAAC;AAEtD,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,OAAO,EAAE,aAAa,EAAE,CAAC;AAEzB,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,OAAO,EAAE,MAAM,EAAE,CAAC;AAElB,OAAO,EAAE,KAAK,EAAE,CAAC;AAEjB,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,OAAO,EAAE,UAAU,EAAE,CAAC;AAEtB,YAAY,EACV,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,EACjB,WAAW,GACZ,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,cAAc,EAAE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,SAAS,MAAM,YAAY,CAAC;AACnC,OAAO,aAAa,EAAE,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,SAAS,MAAM,gBAAgB,CAAC;AACvC,OAAO,MAAM,MAAM,aAAa,CAAC;AACjC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,cAAc,MAAM,qBAAqB,CAAC;AAEtD,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,CAAC;AAEnC,YAAY,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,OAAO,EAAE,MAAM,EAAE,CAAC;AAElB,OAAO,EAAE,KAAK,EAAE,CAAC;AAEjB,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,OAAO,EAAE,UAAU,EAAE,CAAC;AAEtB,YAAY,EACV,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,EACjB,WAAW,GACZ,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,cAAc,EAAE,CAAC"}

package/dist/cjs/index.js

@@ -36,11 +36,12 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.runtimeContext = exports.checkAgent = exports.callAgent = exports.serve = exports.logger = exports.langChain = exports.errorHandling = exports.constants = void 0;
+exports.runtimeContext = exports.checkAgent = exports.callAgent = exports.serve = exports.logger = exports.langChain = exports.AppError = exports.errorHandling = exports.constants = void 0;
 const const_js_1 = __importDefault(require("./const.js"));
 exports.constants = const_js_1.default;
-const errorHandling_js_1 = __importDefault(require("./errorHandling.js"));
+const errorHandling_js_1 = __importStar(require("./errorHandling.js"));
 exports.errorHandling = errorHandling_js_1.default;
+Object.defineProperty(exports, "AppError", { enumerable: true, get: function () { return errorHandling_js_1.AppError; } });
 const langChain_js_1 = __importDefault(require("./langChain.js"));
 exports.langChain = langChain_js_1.default;
 const logger_js_1 = __importDefault(require("./logger.js"));

package/dist/esm/const.d.ts

@@ -8,6 +8,7 @@ declare const _default: {
     };
     ERROR: {
         UNABLE_TO_GENERATE_CONTENT: string;
+        MISSING_INFORMATION: string;
         UNEXPECTED_ERROR: string;
         UNSUPPORTED_MODEL: string;
         QUOTA_EXHAUSTED: string;

package/dist/esm/const.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"const.d.ts","sourceRoot":"","sources":["../../src/const.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;AAAA,wBAgBE"}
+{"version":3,"file":"const.d.ts","sourceRoot":"","sources":["../../src/const.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,wBAiBE"}

package/dist/esm/const.js

@@ -8,6 +8,7 @@ export default {
     },
     ERROR: {
         UNABLE_TO_GENERATE_CONTENT: "Unable to generate content",
+        MISSING_INFORMATION: "Required information is missing or invalid",
         UNEXPECTED_ERROR: "An unexpected error occured. If the issue persists please contact the StackFactor support team at support@stackfactor.ai",
         UNSUPPORTED_MODEL: "The specified model is not supported",
         QUOTA_EXHAUSTED: "Agent session quota exhausted: no remaining budget for additional LLM calls.",

package/dist/esm/errorHandling.d.ts

@@ -1,3 +1,74 @@
+/** Winston log levels accepted by the shared {@link logger}. */
+type LogLevel = "error" | "warn" | "info" | "http" | "verbose" | "debug" | "silly";
+/**
+ * The normalised shape every error is reduced to: a numeric code, a human-readable
+ * message, optional structured `details`, and the failing `integration` name when
+ * the error originated from an external service call.
+ */
+export interface ParsedError {
+    code?: number;
+    message?: string;
+    details?: any;
+    integration?: string;
+}
+/**
+ * A structured, throwable error that normalises any caught value, logs itself
+ * through the shared {@link logger}, and serialises to the `ErrorInfo` wire frame
+ * (`{ code, message }`) that {@link serve} sends and unwraps across the gRPC
+ * boundary.
+ *
+ * @example
+ *   try {
+ *     await doWork();
+ *   } catch (err) {
+ *     throw AppError.from(err).log(request).toWireError();
+ *   }
+ */
+export declare class AppError extends Error {
+    /** Numeric HTTP/application status code; defaults to 500 when unknown. */
+    readonly code: number;
+    /** Optional structured supplementary information (e.g. validation details). */
+    readonly details?: any;
+    /** Name of the external integration that failed, when applicable. */
+    readonly integration?: string;
+    constructor(parsed?: ParsedError);
+    /**
+     * Normalise any thrown value into an {@link AppError}. Idempotent — an existing
+     * `AppError` is returned unchanged.
+     */
+    static from(error: unknown): AppError;
+    /**
+     * Inspect any value and return its {@link ParsedError} shape without
+     * constructing an error instance.
+     */
+    static parse(error: unknown): ParsedError;
+    /**
+     * The serialisable payload: code + message, plus details/integration when
+     * present. The extra fields are dropped by proto-loader on the `ErrorInfo`
+     * frame and preserved everywhere else (logs, JSON responses).
+     */
+    toFrame(): ParsedError & {
+        code: number;
+        message: string;
+    };
+    toJSON(): ParsedError;
+    /**
+     * Encode this error for rethrow across the agent boundary. {@link serve}'s
+     * handler unwraps `error.message` as JSON, so the structured payload lives
+     * there.
+     */
+    toWireError(): Error;
+    /**
+     * Log this error through the shared {@link logger} and return `this` for
+     * chaining (`AppError.from(err).log(request).toWireError()`).
+     *
+     * @param request - HTTP/agent request used by the logger to prefix the user's
+     *   email; may be `null`.
+     * @param level - Log level; defaults to `"error"`.
+     * @param options - Extra structured fields merged into the log record.
+     */
+    log(request?: any, level?: LogLevel, options?: any): this;
+}
 declare const _default: {
     /**
      * Creates a structured error object with a code, message, and optional details.
@@ -15,6 +86,16 @@ declare const _default: {
         details: any;
         stack: string;
     };
+    /** {@link AppError.parse} — normalise any value to a {@link ParsedError}. */
+    parse: (error: any) => ParsedError;
+    /** {@link AppError.from} — normalise any value to an {@link AppError}. */
+    from: typeof AppError.from;
+    /** Normalise + log a caught value in one call; returns the {@link AppError}. */
+    handle: (error: unknown, request?: any, options?: any) => AppError;
+    /** Test whether a value is a valid HTTP status code. */
+    isHttpCode: (code: any) => code is number;
+    /** The {@link AppError} class. */
+    AppError: typeof AppError;
 };
 export default _default;
 //# sourceMappingURL=errorHandling.d.ts.map

package/dist/esm/errorHandling.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errorHandling.d.ts","sourceRoot":"","sources":["../../src/errorHandling.ts"],"names":[],"mappings":";IACE;;;;;;;;;OASG;wBACiB,MAAM,gBAAgB,MAAM,YAAW,GAAG;;;;;;;AAXhE,wBAoBE"}
+{"version":3,"file":"errorHandling.d.ts","sourceRoot":"","sources":["../../src/errorHandling.ts"],"names":[],"mappings":"AAGA,gEAAgE;AAChE,KAAK,QAAQ,GACT,OAAO,GACP,MAAM,GACN,MAAM,GACN,MAAM,GACN,SAAS,GACT,OAAO,GACP,OAAO,CAAC;AAEZ;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,GAAG,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AA8GD;;;;;;;;;;;;GAYG;AACH,qBAAa,QAAS,SAAQ,KAAK;IACjC,0EAA0E;IAC1E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,+EAA+E;IAC/E,QAAQ,CAAC,OAAO,CAAC,EAAE,GAAG,CAAC;IACvB,qEAAqE;IACrE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;gBAElB,MAAM,GAAE,WAAgB;IAUpC;;;OAGG;IACH,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ;IAKrC;;;OAGG;IACH,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW;IAIzC;;;;OAIG;IACH,OAAO,IAAI,WAAW,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE;IAS1D,MAAM,IAAI,WAAW;IAIrB;;;;OAIG;IACH,WAAW,IAAI,KAAK;IAIpB;;;;;;;;OAQG;IACH,GAAG,CAAC,OAAO,GAAE,GAAU,EAAE,KAAK,GAAE,QAAkB,EAAE,OAAO,GAAE,GAAQ,GAAG,IAAI;CAU7E;;IAkBC;;;;;;;;;OASG;wBACiB,MAAM,gBAAgB,MAAM,YAAW,GAAG;;;;;;IAU9D,6EAA6E;mBApOpD,GAAG,KAAG,WAAW;IAsO1C,0EAA0E;;IAE1E,gFAAgF;oBA9BzE,OAAO,YACL,GAAG,YACH,GAAG,KACX,QAAQ;IA6BT,wDAAwD;uBArPhC,GAAG,KAAG,IAAI,IAAI,MAAM;IAuP5C,kCAAkC;;;AA7BpC,wBA+BE"}

package/dist/esm/errorHandling.js

@@ -1,3 +1,204 @@
+import constants from "./const.js";
+import logger from "./logger.js";
+/** True when `code` is a syntactically valid HTTP status (100–599). */
+const isHttpCode = (code) => typeof code === "number" && Number.isInteger(code) && code >= 100 && code <= 599;
+/**
+ * Reduce any thrown value — Error, axios failure, validation error, structured
+ * payload from {@link create}, JSON-encoded rethrow, or bare string — into a
+ * consistent {@link ParsedError}. Never throws; falls back to a generic 500.
+ *
+ * @param error - Anything that was caught or thrown.
+ * @returns The normalised error shape.
+ */
+const parseError = (error) => {
+    try {
+        if (typeof error === "object" && error !== null) {
+            // Integration calls tag the failing integration's name.
+            const integration = error.integrationName;
+            // express-validator style validation error (e.g. runSocketValidators).
+            if (error.message === "VALIDATION_ERROR" && Array.isArray(error.details)) {
+                return {
+                    code: constants.HTTP_CODES.BAD_REQUEST,
+                    message: constants.ERROR.MISSING_INFORMATION,
+                    details: error.details,
+                    integration,
+                };
+            }
+            // Structured error produced by create().
+            if (error.code && error.message && isHttpCode(error.code)) {
+                return {
+                    code: error.code,
+                    message: error.message,
+                    details: error.details,
+                    integration,
+                };
+            }
+            // axios error format.
+            if (error.isAxiosError && error.response) {
+                return {
+                    code: error.response.status,
+                    message: error.response.data?.message || error.response.statusText,
+                    integration,
+                };
+            }
+            // Any other error carrying an HTTP-style response.
+            if (error.response) {
+                return {
+                    code: error.response.status,
+                    message: error.response.data?.message || error.response.statusText,
+                    integration,
+                };
+            }
+            // Standard Error objects or objects with a message.
+            if (typeof error.message === "string") {
+                // The message may itself be a JSON-encoded error — agents rethrow across
+                // the gRPC boundary as `new Error(JSON.stringify({ code, message }))`.
+                try {
+                    const parsed = JSON.parse(error.message);
+                    if (parsed && (parsed.code || parsed.message)) {
+                        return {
+                            code: isHttpCode(parsed.code) ? parsed.code : undefined,
+                            message: parsed.message,
+                            details: parsed.details,
+                            integration: parsed.integration ?? integration,
+                        };
+                    }
+                }
+                catch {
+                    // Not JSON — use the message as-is.
+                }
+                return {
+                    code: error.message.includes("validation failed")
+                        ? constants.HTTP_CODES.BAD_REQUEST
+                        : undefined,
+                    message: error.message,
+                    integration,
+                };
+            }
+            return { message: constants.ERROR.UNEXPECTED_ERROR, integration };
+        }
+        if (typeof error === "string") {
+            // A JSON-encoded error string, or just a plain message.
+            try {
+                const parsed = JSON.parse(error);
+                return {
+                    code: isHttpCode(parsed.code) ? parsed.code : undefined,
+                    message: parsed.message,
+                    integration: parsed.integration,
+                };
+            }
+            catch {
+                return { message: error };
+            }
+        }
+    }
+    catch {
+        // Fall through to the generic fallback below.
+    }
+    return {
+        code: constants.HTTP_CODES.INTERNAL_SERVER_ERROR,
+        message: constants.ERROR.UNEXPECTED_ERROR,
+    };
+};
+/**
+ * A structured, throwable error that normalises any caught value, logs itself
+ * through the shared {@link logger}, and serialises to the `ErrorInfo` wire frame
+ * (`{ code, message }`) that {@link serve} sends and unwraps across the gRPC
+ * boundary.
+ *
+ * @example
+ *   try {
+ *     await doWork();
+ *   } catch (err) {
+ *     throw AppError.from(err).log(request).toWireError();
+ *   }
+ */
+export class AppError extends Error {
+    /** Numeric HTTP/application status code; defaults to 500 when unknown. */
+    code;
+    /** Optional structured supplementary information (e.g. validation details). */
+    details;
+    /** Name of the external integration that failed, when applicable. */
+    integration;
+    constructor(parsed = {}) {
+        super(parsed.message ?? constants.ERROR.UNEXPECTED_ERROR);
+        this.name = "AppError";
+        this.code = parsed.code ?? constants.HTTP_CODES.INTERNAL_SERVER_ERROR;
+        this.details = parsed.details;
+        this.integration = parsed.integration;
+        // Restore the prototype chain (TS targeting ES2022 extending built-ins).
+        Object.setPrototypeOf(this, AppError.prototype);
+    }
+    /**
+     * Normalise any thrown value into an {@link AppError}. Idempotent — an existing
+     * `AppError` is returned unchanged.
+     */
+    static from(error) {
+        if (error instanceof AppError)
+            return error;
+        return new AppError(parseError(error));
+    }
+    /**
+     * Inspect any value and return its {@link ParsedError} shape without
+     * constructing an error instance.
+     */
+    static parse(error) {
+        return parseError(error);
+    }
+    /**
+     * The serialisable payload: code + message, plus details/integration when
+     * present. The extra fields are dropped by proto-loader on the `ErrorInfo`
+     * frame and preserved everywhere else (logs, JSON responses).
+     */
+    toFrame() {
+        return {
+            code: this.code,
+            message: this.message,
+            ...(this.details !== undefined ? { details: this.details } : {}),
+            ...(this.integration ? { integration: this.integration } : {}),
+        };
+    }
+    toJSON() {
+        return this.toFrame();
+    }
+    /**
+     * Encode this error for rethrow across the agent boundary. {@link serve}'s
+     * handler unwraps `error.message` as JSON, so the structured payload lives
+     * there.
+     */
+    toWireError() {
+        return new Error(JSON.stringify(this.toFrame()));
+    }
+    /**
+     * Log this error through the shared {@link logger} and return `this` for
+     * chaining (`AppError.from(err).log(request).toWireError()`).
+     *
+     * @param request - HTTP/agent request used by the logger to prefix the user's
+     *   email; may be `null`.
+     * @param level - Log level; defaults to `"error"`.
+     * @param options - Extra structured fields merged into the log record.
+     */
+    log(request = null, level = "error", options = {}) {
+        logger.log(request, level, this.message, {
+            code: this.code,
+            ...(this.details !== undefined ? { details: this.details } : {}),
+            ...(this.integration ? { integration: this.integration } : {}),
+            stack: this.stack,
+            ...options,
+        });
+        return this;
+    }
+}
+/**
+ * One-shot handler for a caught value: normalise it to an {@link AppError}, log
+ * it, and return it so the caller can serialise (`.toFrame()` / `.toWireError()`)
+ * or rethrow.
+ *
+ * @param error - The caught value.
+ * @param request - Request passed to the logger for the email prefix; may be `null`.
+ * @param options - Extra structured fields merged into the log record.
+ */
+const handle = (error, request = null, options = {}) => AppError.from(error).log(request, "error", options);
 export default {
     /**
      * Creates a structured error object with a code, message, and optional details.
@@ -18,4 +219,14 @@ export default {
             stack: error.stack,
         };
     },
+    /** {@link AppError.parse} — normalise any value to a {@link ParsedError}. */
+    parse: parseError,
+    /** {@link AppError.from} — normalise any value to an {@link AppError}. */
+    from: AppError.from,
+    /** Normalise + log a caught value in one call; returns the {@link AppError}. */
+    handle,
+    /** Test whether a value is a valid HTTP status code. */
+    isHttpCode,
+    /** The {@link AppError} class. */
+    AppError,
 };

package/dist/esm/index.d.ts

@@ -1,12 +1,13 @@
 import constants from "./const.js";
-import errorHandling from "./errorHandling.js";
+import errorHandling, { AppError } from "./errorHandling.js";
 import langChain from "./langChain.js";
 import logger from "./logger.js";
 import { serve } from "./serve.js";
 import { callAgent, checkAgent } from "./client.js";
 import * as runtimeContext from "./runtimeContext.js";
 export { constants };
-export { errorHandling };
+export { errorHandling, AppError };
+export type { ParsedError } from "./errorHandling.js";
 export { langChain };
 export { logger };
 export { serve };

package/dist/esm/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,SAAS,MAAM,YAAY,CAAC;AACnC,OAAO,aAAa,MAAM,oBAAoB,CAAC;AAC/C,OAAO,SAAS,MAAM,gBAAgB,CAAC;AACvC,OAAO,MAAM,MAAM,aAAa,CAAC;AACjC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,cAAc,MAAM,qBAAqB,CAAC;AAEtD,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,OAAO,EAAE,aAAa,EAAE,CAAC;AAEzB,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,OAAO,EAAE,MAAM,EAAE,CAAC;AAElB,OAAO,EAAE,KAAK,EAAE,CAAC;AAEjB,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,OAAO,EAAE,UAAU,EAAE,CAAC;AAEtB,YAAY,EACV,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,EACjB,WAAW,GACZ,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,cAAc,EAAE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,SAAS,MAAM,YAAY,CAAC;AACnC,OAAO,aAAa,EAAE,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,SAAS,MAAM,gBAAgB,CAAC;AACvC,OAAO,MAAM,MAAM,aAAa,CAAC;AACjC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,cAAc,MAAM,qBAAqB,CAAC;AAEtD,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,CAAC;AAEnC,YAAY,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,OAAO,EAAE,MAAM,EAAE,CAAC;AAElB,OAAO,EAAE,KAAK,EAAE,CAAC;AAEjB,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,OAAO,EAAE,UAAU,EAAE,CAAC;AAEtB,YAAY,EACV,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,EACjB,WAAW,GACZ,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,cAAc,EAAE,CAAC"}

package/dist/esm/index.js

@@ -1,12 +1,12 @@
 import constants from "./const.js";
-import errorHandling from "./errorHandling.js";
+import errorHandling, { AppError } from "./errorHandling.js";
 import langChain from "./langChain.js";
 import logger from "./logger.js";
 import { serve } from "./serve.js";
 import { callAgent, checkAgent } from "./client.js";
 import * as runtimeContext from "./runtimeContext.js";
 export { constants };
-export { errorHandling };
+export { errorHandling, AppError };
 export { langChain };
 export { logger };
 export { serve };

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "1.1.5",
+  "version": "1.1.7",
   "description": "",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",