@stackfactor/agent-utils 1.7.0 → 1.8.0

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

@@ -1 +1 @@
-{"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"}
+{"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;AAmHD;;;;;;;;;;;;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;mBAzOpD,GAAG,KAAG,WAAW;IA2O1C,0EAA0E;;IAE1E,gFAAgF;oBA9BzE,OAAO,YACL,GAAG,YACH,GAAG,KACX,QAAQ;IA6BT,wDAAwD;uBA1PhC,GAAG,KAAG,IAAI,IAAI,MAAM;IA4P5C,kCAAkC;;;AA7BpC,wBA+BE"}

package/dist/cjs/errorHandling.js

@@ -87,11 +87,16 @@ const parseError = (error) => {
             // 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,
-                };
+                // Only an object is an encoded error; "404" or "true" also parse as
+                // JSON but are just the message text.
+                if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                    return {
+                        code: isHttpCode(parsed.code) ? parsed.code : undefined,
+                        message: parsed.message,
+                        integration: parsed.integration,
+                    };
+                }
+                return { message: error };
             }
             catch {
                 return { message: error };

package/dist/cjs/index.d.ts

@@ -6,6 +6,7 @@ import { serve, runOnce, isRunOnceExecution, EXECUTION_ENV } from "./serve.js";
 import { callAgent, checkAgent } from "./client.js";
 import * as runtimeContext from "./runtimeContext.js";
 import { recordUsage, USAGE_UNITS } from "./usage.js";
+import stackfactorKnowledge from "./stackfactorKnowledge.js";
 export { constants };
 export { errorHandling, AppError };
 export type { ParsedError } from "./errorHandling.js";
@@ -20,4 +21,6 @@ export type { AgentExecuteRequest, CallAgentOptions, CheckAgentOptions, AgentHea
 export { runtimeContext };
 export { recordUsage, USAGE_UNITS };
 export type { UsageEntry, UsageUnit } from "./usage.js";
+export { stackfactorKnowledge };
+export type { GroundingPassage, KnowledgeChunk, KnowledgeSearch, KnowledgeSource, SkippedSource, StackFactorReference, } from "./stackfactorKnowledge.js";
 //# sourceMappingURL=index.d.ts.map

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,EAAE,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,SAAS,MAAM,gBAAgB,CAAC;AACvC,OAAO,MAAM,MAAM,aAAa,CAAC;AACjC,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC/E,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,cAAc,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,YAAY,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,YAAY,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAEhE,OAAO,EAAE,MAAM,EAAE,CAAC;AAElB,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,CAAC;AAE7D,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;AAE1B,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,CAAC;AAEpC,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,YAAY,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,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC/E,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,cAAc,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACtD,OAAO,oBAAoB,MAAM,2BAA2B,CAAC;AAE7D,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,YAAY,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAEhE,OAAO,EAAE,MAAM,EAAE,CAAC;AAElB,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,CAAC;AAE7D,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;AAE1B,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,CAAC;AAEpC,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAExD,OAAO,EAAE,oBAAoB,EAAE,CAAC;AAEhC,YAAY,EACV,gBAAgB,EAChB,cAAc,EACd,eAAe,EACf,eAAe,EACf,aAAa,EACb,oBAAoB,GACrB,MAAM,2BAA2B,CAAC"}

package/dist/cjs/index.js

@@ -36,7 +36,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.USAGE_UNITS = exports.recordUsage = exports.runtimeContext = exports.checkAgent = exports.callAgent = exports.EXECUTION_ENV = exports.isRunOnceExecution = exports.runOnce = exports.serve = exports.logger = exports.langChain = exports.AppError = exports.errorHandling = exports.constants = void 0;
+exports.stackfactorKnowledge = exports.USAGE_UNITS = exports.recordUsage = exports.runtimeContext = exports.checkAgent = exports.callAgent = exports.EXECUTION_ENV = exports.isRunOnceExecution = exports.runOnce = 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 = __importStar(require("./errorHandling.js"));
@@ -59,3 +59,5 @@ exports.runtimeContext = runtimeContext;
 const usage_js_1 = require("./usage.js");
 Object.defineProperty(exports, "recordUsage", { enumerable: true, get: function () { return usage_js_1.recordUsage; } });
 Object.defineProperty(exports, "USAGE_UNITS", { enumerable: true, get: function () { return usage_js_1.USAGE_UNITS; } });
+const stackfactorKnowledge_js_1 = __importDefault(require("./stackfactorKnowledge.js"));
+exports.stackfactorKnowledge = stackfactorKnowledge_js_1.default;

package/dist/cjs/langChain.d.ts

@@ -62,7 +62,7 @@ declare const _default: {
     supportsNativeSchema: (modelName: string) => boolean;
     checkIfAIProviderConfigured: (config: any) => void;
     createAgent: (name: string, modelName: string, systemPrompt: string, tools: any[], responseFormat: any, config: any, usageTracker?: UsageTracker | null) => any;
-    runAgent: (agent: any, prompt: string, config: any, onProgress?: Function | null, usageTracker?: UsageTracker | null) => Promise<any>;
+    runAgent: (agent: any, prompt: string, config: any, onProgress?: Function | null, usageTracker?: UsageTracker | null, progress?: number) => Promise<any>;
     runPromptWithModel: (modelName: string, config: any, prompt: any, onProgressReport: any, minPercent?: number, maxPercent?: number, expectsJsonResponse?: boolean, schema?: any, agentName?: string, tools?: any[], usageTracker?: UsageTracker | null) => Promise<any>;
     runPromptWithModelForImageGeneration: (modelName: string, config: any, prompt: string, options?: any, usageTracker?: UsageTracker | null) => Promise<any>;
     runPromptWithModelForVideoGeneration: (modelName: string, config: any, prompt: string, options?: any, usageTracker?: UsageTracker | null) => Promise<any>;

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

@@ -1 +1 @@
-{"version":3,"file":"langChain.d.ts","sourceRoot":"","sources":["../../src/langChain.ts"],"names":[],"mappings":"AAoGA,KAAK,UAAU,GAAG;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IAKtB,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE;QAAE,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IACvC;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACtD,CAAC;AAmiBF;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,eAAO,MAAM,WAAW,GACtB,WAAW,MAAM,EACjB,QAAQ,GAAG,EACX,SAAQ,GAAU,KACjB,GAwHF,CAAC;;8CA4Z+C,OAAO,UAAU,GAAG,KAAG,OAAO;oCAWxC,GAAG,KAAG,OAAO;0CAgBtC,MAAM,cACN,GAAG,SACR,GAAG,KACT,MAAM;2CA0CqC,GAAG,UAAU,GAAG,KAAG,MAAM;sCAvvC9B,MAAM,KAAG,OAAO;0CA+FZ,GAAG,KAAG,IAAI;wBAusB/C,MAAM,aACD,MAAM,gBACH,MAAM,SACb,GAAG,EAAE,kBACI,GAAG,UACX,GAAG,iBACG,YAAY,GAAG,IAAI,KAChC,GAAG;sBAoCG,GAAG,UACF,MAAM,UACN,GAAG,eACC,QAAQ,GAAG,IAAI,iBACb,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC;oCA6fF,MAAM,UACT,GAAG,UACH,GAAG,oBACO,GAAG,eACT,MAAM,eACN,MAAM,wBACG,OAAO,WACpB,GAAG,cACA,MAAM,UACV,GAAG,EAAE,iBACE,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC;sDA0sBF,MAAM,UACT,GAAG,UACH,MAAM,YACL,GAAG,iBACE,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC;sDAmTF,MAAM,UACT,GAAG,UACH,MAAM,YACL,GAAG,iBACE,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC;0CAv6C8B,GAAG,KAAG,MAAM;uCA3wB9C,YAAY,GAAG,IAAI,GAAG,SAAS,aAC7B,MAAM,YACP,GAAG,WACJ,GAAG,YACF,QAAQ,GAAG,QAAQ,KAC5B,IAAI;kCA5CI,YAAY,GAAG,IAAI,GAAG,SAAS,aAC7B,MAAM,SACV,UAAU,GAAG,IAAI,YACd,GAAG,KACZ,IAAI;+CA0FI,YAAY,GAAG,IAAI,GAAG,SAAS,aAC7B,MAAM,kBACD,MAAM,YACZ,GAAG,KACZ,IAAI;uCAoBI,YAAY,GAAG,IAAI,GAAG,SAAS,aAC7B,MAAM,WACR,MAAM,YACL,GAAG,KACZ,IAAI;mCA4sBU,MAAM,mBACJ,MAAM,EAAE,KACxB,MAAM;;AA08CT,wBAkBE"}
+{"version":3,"file":"langChain.d.ts","sourceRoot":"","sources":["../../src/langChain.ts"],"names":[],"mappings":"AAoGA,KAAK,UAAU,GAAG;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IAKtB,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE;QAAE,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IACvC;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACtD,CAAC;AA0iBF;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,eAAO,MAAM,WAAW,GACtB,WAAW,MAAM,EACjB,QAAQ,GAAG,EACX,SAAQ,GAAU,KACjB,GAwHF,CAAC;;8CAkb+C,OAAO,UAAU,GAAG,KAAG,OAAO;oCAWxC,GAAG,KAAG,OAAO;0CAgBtC,MAAM,cACN,GAAG,SACR,GAAG,KACT,MAAM;2CA0CqC,GAAG,UAAU,GAAG,KAAG,MAAM;sCApxC9B,MAAM,KAAG,OAAO;0CA+FZ,GAAG,KAAG,IAAI;wBA8sB/C,MAAM,aACD,MAAM,gBACH,MAAM,SACb,GAAG,EAAE,kBACI,GAAG,UACX,GAAG,iBACG,YAAY,GAAG,IAAI,KAChC,GAAG;sBAsCG,GAAG,UACF,MAAM,UACN,GAAG,eACC,QAAQ,GAAG,IAAI,iBACb,YAAY,GAAG,IAAI,aACvB,MAAM,KACf,OAAO,CAAC,GAAG,CAAC;oCAghBF,MAAM,UACT,GAAG,UACH,GAAG,oBACO,GAAG,eACT,MAAM,eACN,MAAM,wBACG,OAAO,WACpB,GAAG,cACA,MAAM,UACV,GAAG,EAAE,iBACE,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC;sDA2sBF,MAAM,UACT,GAAG,UACH,MAAM,YACL,GAAG,iBACE,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC;sDAmTF,MAAM,UACT,GAAG,UACH,MAAM,YACL,GAAG,iBACE,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC;0CAx6C8B,GAAG,KAAG,MAAM;uCAxyB9C,YAAY,GAAG,IAAI,GAAG,SAAS,aAC7B,MAAM,YACP,GAAG,WACJ,GAAG,YACF,QAAQ,GAAG,QAAQ,KAC5B,IAAI;kCA5CI,YAAY,GAAG,IAAI,GAAG,SAAS,aAC7B,MAAM,SACV,UAAU,GAAG,IAAI,YACd,GAAG,KACZ,IAAI;+CA0FI,YAAY,GAAG,IAAI,GAAG,SAAS,aAC7B,MAAM,kBACD,MAAM,YACZ,GAAG,KACZ,IAAI;uCAoBI,YAAY,GAAG,IAAI,GAAG,SAAS,aAC7B,MAAM,WACR,MAAM,YACL,GAAG,KACZ,IAAI;mCAyuBU,MAAM,mBACJ,MAAM,EAAE,KACxB,MAAM;;AA28CT,wBAkBE"}

package/dist/cjs/langChain.js

@@ -333,8 +333,14 @@ const formatZodErrors = (zodError) => {
                 const path = err.path.length > 0 ? err.path.join(".") : "root";
                 // Provide more context based on error type
                 switch (err.code) {
-                    case "invalid_type":
-                        return `Field "${path}": Expected ${err.expected}, but received ${err.received}`;
+                    case "invalid_type": {
+                        // zod v3 sets `received`; zod v4 names it only in the message
+                        // ("Invalid input: expected string, received number").
+                        const received = err.received ??
+                            /received (\w+)/.exec(String(err.message ?? ""))?.[1] ??
+                            "a different type";
+                        return `Field "${path}": Expected ${err.expected}, but received ${received}`;
+                    }
                     case "invalid_literal":
                         return `Field "${path}": Expected literal value ${JSON.stringify(err.expected)}, but received ${JSON.stringify(err.received)}`;
                     case "unrecognized_keys":
@@ -771,19 +777,30 @@ const createAgent = (name, modelName, systemPrompt, tools = [], responseFormat,
  * @param onProgress - Optional callback invoked with progress event objects throughout
  *   agent execution
  * @param usageTracker - Optional usage accumulator updated on successful completion
+ * @param progress - The percentage every progress event reports (the stage's
+ *   current one; the agent loop has no percentage of its own). Defaults to 0.
  * @returns The raw response object returned by the agent's `invoke` method
  */
-const runAgent = async (agent, prompt, config, onProgress = null, usageTracker = null) => {
+const runAgent = async (agent, prompt, config, onProgress = null, usageTracker = null, progress = 0) => {
     const startTime = Date.now();
+    // Every event carries `progress`: callers forward these to the platform's
+    // `{ progress, message }` progress bar, where a missing value would read as
+    // 0% and make the bar jump back during a tool call. The agent loop reports
+    // no percentage of its own, so the stage's current one is repeated.
     const callbacks = onProgress
         ? [
             {
-                handleToolStart: (toolInfo) => {
-                    if (toolInfo.name)
+                // LangChain calls handleToolStart(serializedTool, input, runId,
+                // parentRunId, tags, metadata, runName): the serialized tool
+                // ({ lc, type, id }) has no name; the tool's name is runName.
+                handleToolStart: (toolInfo, _input, _runId, _parentRunId, _tags, _metadata, runName) => {
+                    const name = runName || toolInfo?.name || toolInfo?.kwargs?.name;
+                    if (name)
                         onProgress({
                             type: "tool_start",
-                            message: `Using "${toolInfo.name}" tool`,
-                            tool: toolInfo.name,
+                            message: `Using "${name}" tool`,
+                            tool: name,
+                            progress,
                         });
                 },
                 handleAgentAction: (action) => {
@@ -792,12 +809,14 @@ const runAgent = async (agent, prompt, config, onProgress = null, usageTracker =
                         message: action.log || `Calling "${action.tool}" action`,
                         tool: action.tool,
                         input: action.toolInput,
+                        progress,
                     });
                 },
                 handleChainError: (err) => {
                     onProgress({
                         type: "error",
                         message: `Error: ${err?.message || String(err)}`,
+                        progress,
                     });
                 },
             },
@@ -1261,7 +1280,7 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
         let attempt = 0;
         for (;;) {
             // Run the agent with progress callback
-            const response = await runAgent(agent, activeUserPrompt, config, onProgressReport || null, usageTracker);
+            const response = await runAgent(agent, activeUserPrompt, config, onProgressReport || null, usageTracker, minPercent);
             // Extract content from agent response
             const messages = response?.messages || [];
             if (messages.length === 0) {

package/dist/cjs/stackfactorKnowledge.d.ts

@@ -0,0 +1,182 @@
+/** What a STACKFACTOR reference to a knowledge base document carries (backend-core REFERENCE). */
+export declare const STACKFACTOR_REFERENCE: Readonly<{
+    KIND: "STACKFACTOR";
+    TARGET_ELEMENT_TYPE: "KNOWLEDGE_BASE_DOCUMENT";
+    ORIGIN: "KB_EXTRACTION";
+    VISIBILITY: "EDIT";
+}>;
+/** How many documents one search may be kept to (the backend's bound); more are split. */
+export declare const SEARCH_DOCUMENT_IDS_MAX = 500;
+/** How long a query may be (the backend's bound); longer ones are cut. */
+export declare const QUERY_MAX_LENGTH = 4000;
+/** How many passages one search asks for when the caller does not say. */
+export declare const DEFAULT_TOP_K = 8;
+/** A chunk as the platform's search answers it (client-api `RetrievedChunk`). */
+export interface KnowledgeChunk {
+    _id: string;
+    knowledgeBaseId?: string;
+    documentId: string;
+    documentName?: string | null;
+    sectionTitle?: string | null;
+    pageNumber?: number | null;
+    text?: string;
+    skills?: {
+        name: string | null;
+        microSkills?: string[];
+    }[];
+    score?: number | null;
+    [field: string]: unknown;
+}
+/** The platform's search, as client-api's `knowledgeBaseAgent.search` is called. */
+export type KnowledgeSearch = (knowledgeBaseId: string, query: string, options: {
+    topK?: number;
+    documentIds?: string[];
+}, token: string) => Promise<{
+    chunks: KnowledgeChunk[];
+}>;
+/** Where to search: a whole knowledge base, or only some of its documents. */
+export interface KnowledgeSource {
+    knowledgeBaseId: string;
+    /** Only these documents; omitted, the whole knowledge base. */
+    documentIds?: string[];
+}
+/** A passage handed to the model, tagged so it can cite it. */
+export interface GroundingPassage {
+    /** "k1", "k2"… in the order they rank. */
+    tag: string;
+    chunkId: string;
+    knowledgeBaseId: string;
+    documentId: string;
+    documentName: string | null;
+    sectionTitle: string | null;
+    pageNumber: number | null;
+    text: string;
+    /** The skills its passage teaches, as labelling named them. */
+    skills: {
+        name: string | null;
+        microSkills: string[];
+    }[];
+    score: number | null;
+}
+/** A knowledge base that could not be searched, and why. */
+export interface SkippedSource {
+    knowledgeBaseId: string;
+    /** The HTTP status, when the platform answered one. */
+    status: number | null;
+    /** True when the person may not read it (or it is gone): expected, not a fault. */
+    noAccess: boolean;
+    message: string;
+}
+/** A STACKFACTOR reference to the knowledge base document a passage came from. */
+export interface StackFactorReference {
+    kind: "STACKFACTOR";
+    title: string;
+    description: string | null;
+    target: {
+        elementType: "KNOWLEDGE_BASE_DOCUMENT";
+        elementId: string;
+        parentId: string;
+    };
+    knowledgeBase: {
+        knowledgeBaseId: string;
+        documentId: string;
+        chunkId: string;
+        sectionTitle: string | null;
+    };
+    origin: "KB_EXTRACTION";
+    visibility: "EDIT";
+}
+/**
+ * The knowledge bases, and the documents in them, that a list of references
+ * cites: its STACKFACTOR references to knowledge base documents, by their
+ * `knowledgeBase` ids, or by their `target` when only that is there. Any other
+ * reference is passed over. Each knowledge base once, its documents once each,
+ * in the order they first appear.
+ * @param references A skill's (or a microskill's) references
+ * @returns The sources to search
+ */
+export declare const sourcesFromReferences: (references: unknown) => KnowledgeSource[];
+/**
+ * The knowledge bases skill coverage found (client-api
+ * `knowledgeBase.getSkillCoverage`): every one the person can open that holds
+ * the skill, each searched whole.
+ * @param coverage The coverage answer, `{ knowledgeBases: [{ _id }] }`
+ * @returns The sources to search
+ */
+export declare const sourcesFromCoverage: (coverage: unknown) => KnowledgeSource[];
+/**
+ * Searches every source for every query, under the person's access, and hands
+ * back the passages found, best first, each once, tagged "k1", "k2"… for the
+ * model to cite. A source with documents is searched within them (in batches of
+ * SEARCH_DOCUMENT_IDS_MAX); one without, whole. A source the person may not
+ * read (401, 403, 404) is skipped: none of its passages are used and no more of
+ * its searches are made. A search that fails otherwise is reported and the
+ * passages its other searches found stand. Either way it is in `skipped`, once
+ * per knowledge base, and the passages of the others stand.
+ * @param options `sources`, `queries`, `search` (client-api
+ *   `knowledgeBaseAgent.search`), `token` (the run's AGENT token), `topK`
+ *   per search (default DEFAULT_TOP_K)
+ * @returns `{ passages, skipped }`
+ */
+export declare const retrievePassages: (options: {
+    sources: KnowledgeSource[];
+    queries: string[];
+    search: KnowledgeSearch;
+    token: string;
+    topK?: number;
+}) => Promise<{
+    passages: GroundingPassage[];
+    skipped: SkippedSource[];
+}>;
+/**
+ * The passages as a prompt shows them: tag, where each came from, and its text.
+ * @param passages From `retrievePassages`
+ * @returns `[{ tag, document, section, text }]`, for the model's input
+ */
+export declare const passagesForPrompt: (passages: GroundingPassage[]) => {
+    tag: string;
+    document: string | null;
+    section: string | null;
+    text: string;
+}[];
+/**
+ * STACKFACTOR references for passages: one per passage, in their order, with no
+ * cap. With `tags`, only the passages the model cited by tag (any tag it made
+ * up is passed over); without, every passage.
+ * @param passages From `retrievePassages`
+ * @param tags The tags the model cited ("k3", "K3" and " k3 " alike)
+ * @returns The references, ready for a skill's, a microskill's or a question's `references`
+ */
+export declare const referencesFor: (passages: GroundingPassage[], tags?: unknown[]) => StackFactorReference[];
+declare const _default: {
+    DEFAULT_TOP_K: number;
+    QUERY_MAX_LENGTH: number;
+    SEARCH_DOCUMENT_IDS_MAX: number;
+    STACKFACTOR_REFERENCE: Readonly<{
+        KIND: "STACKFACTOR";
+        TARGET_ELEMENT_TYPE: "KNOWLEDGE_BASE_DOCUMENT";
+        ORIGIN: "KB_EXTRACTION";
+        VISIBILITY: "EDIT";
+    }>;
+    passagesForPrompt: (passages: GroundingPassage[]) => {
+        tag: string;
+        document: string | null;
+        section: string | null;
+        text: string;
+    }[];
+    referencesFor: (passages: GroundingPassage[], tags?: unknown[]) => StackFactorReference[];
+    retrievePassages: (options: {
+        sources: KnowledgeSource[];
+        queries: string[];
+        search: KnowledgeSearch;
+        token: string;
+        topK?: number;
+    }) => Promise<{
+        passages: GroundingPassage[];
+        skipped: SkippedSource[];
+    }>;
+    sourcesFromCoverage: (coverage: unknown) => KnowledgeSource[];
+    sourcesFromReferences: (references: unknown) => KnowledgeSource[];
+};
+export default _default;
+//# sourceMappingURL=stackfactorKnowledge.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"stackfactorKnowledge.d.ts","sourceRoot":"","sources":["../../src/stackfactorKnowledge.ts"],"names":[],"mappings":"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"}

package/dist/cjs/stackfactorKnowledge.js

@@ -0,0 +1,274 @@
+"use strict";
+//
+// StackFactor knowledge — grounding generated content in the knowledge bases
+//
+// A generation agent grounded in StackFactor (the Additional Information data
+// source "StackFactor", `dataSource: "RAG"`) writes from knowledge-base
+// passages instead of a web search, and cites every passage it used as a
+// STACKFACTOR reference. A later agent generating for the same skill (its
+// assessments, its learning content) reads those references and searches the
+// documents they cite. Designed with Candin, 2026-10-08:
+//
+//   - which knowledge bases: every one the person can open that holds the
+//     skill (skill coverage), never a fixed number of them;
+//   - which references: one per passage used, with no cap per document or per
+//     microskill;
+//   - access: the platform's search judges the person the run acts for, so a
+//     run reads only what that person may open. A knowledge base the person
+//     cannot read is skipped and reported, never an error: the agent
+//     generates without it.
+//
+// A reference points at the content and never copies it: the passage is
+// searched again, under the reader's own access, whenever it is used. It is
+// EDIT-only (`visibility: "EDIT"`): the platform strips it from what is
+// published, so a knowledge base's titles never reach a learner; agents read
+// it from the draft.
+//
+// The search itself is the caller's (`search`: client-api
+// `knowledgeBaseAgent.search`, 1.11 or later for `documentIds`), so this
+// module needs no particular client-api.
+//
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.referencesFor = exports.passagesForPrompt = exports.retrievePassages = exports.sourcesFromCoverage = exports.sourcesFromReferences = exports.DEFAULT_TOP_K = exports.QUERY_MAX_LENGTH = exports.SEARCH_DOCUMENT_IDS_MAX = exports.STACKFACTOR_REFERENCE = void 0;
+/** What a STACKFACTOR reference to a knowledge base document carries (backend-core REFERENCE). */
+exports.STACKFACTOR_REFERENCE = Object.freeze({
+    KIND: "STACKFACTOR",
+    TARGET_ELEMENT_TYPE: "KNOWLEDGE_BASE_DOCUMENT",
+    ORIGIN: "KB_EXTRACTION",
+    VISIBILITY: "EDIT",
+});
+/** How many documents one search may be kept to (the backend's bound); more are split. */
+exports.SEARCH_DOCUMENT_IDS_MAX = 500;
+/** How long a query may be (the backend's bound); longer ones are cut. */
+exports.QUERY_MAX_LENGTH = 4000;
+/** How many passages one search asks for when the caller does not say. */
+exports.DEFAULT_TOP_K = 8;
+/** How many searches run at once. */
+const CONCURRENCY = 4;
+/** Statuses that mean the person may not read the knowledge base, or it is gone. */
+const NO_ACCESS = new Set([401, 403, 404]);
+const text = (value) => (typeof value === "string" ? value.trim() : "");
+const id = (value) => typeof value === "string" ? value.trim() : value != null && typeof value === "object" ? String(value) : "";
+/**
+ * The knowledge bases, and the documents in them, that a list of references
+ * cites: its STACKFACTOR references to knowledge base documents, by their
+ * `knowledgeBase` ids, or by their `target` when only that is there. Any other
+ * reference is passed over. Each knowledge base once, its documents once each,
+ * in the order they first appear.
+ * @param references A skill's (or a microskill's) references
+ * @returns The sources to search
+ */
+const sourcesFromReferences = (references) => {
+    const byBase = new Map();
+    for (const reference of Array.isArray(references) ? references : []) {
+        if (reference?.kind !== exports.STACKFACTOR_REFERENCE.KIND)
+            continue;
+        const target = reference.target ?? {};
+        const isDocumentTarget = target.elementType === exports.STACKFACTOR_REFERENCE.TARGET_ELEMENT_TYPE;
+        const knowledgeBaseId = id(reference.knowledgeBase?.knowledgeBaseId) || (isDocumentTarget ? id(target.parentId) : "");
+        const documentId = id(reference.knowledgeBase?.documentId) || (isDocumentTarget ? id(target.elementId) : "");
+        if (!knowledgeBaseId || !documentId)
+            continue;
+        const documents = byBase.get(knowledgeBaseId) ?? new Set();
+        documents.add(documentId);
+        byBase.set(knowledgeBaseId, documents);
+    }
+    return [...byBase.entries()].map(([knowledgeBaseId, documents]) => ({
+        knowledgeBaseId,
+        documentIds: [...documents],
+    }));
+};
+exports.sourcesFromReferences = sourcesFromReferences;
+/**
+ * The knowledge bases skill coverage found (client-api
+ * `knowledgeBase.getSkillCoverage`): every one the person can open that holds
+ * the skill, each searched whole.
+ * @param coverage The coverage answer, `{ knowledgeBases: [{ _id }] }`
+ * @returns The sources to search
+ */
+const sourcesFromCoverage = (coverage) => {
+    const bases = coverage?.knowledgeBases;
+    const seen = new Set();
+    const sources = [];
+    for (const base of Array.isArray(bases) ? bases : []) {
+        const knowledgeBaseId = id(base?._id);
+        if (!knowledgeBaseId || seen.has(knowledgeBaseId))
+            continue;
+        seen.add(knowledgeBaseId);
+        sources.push({ knowledgeBaseId });
+    }
+    return sources;
+};
+exports.sourcesFromCoverage = sourcesFromCoverage;
+/** The documents of a source in batches the backend accepts; one batch of none for a whole knowledge base. */
+const batchesOf = (source) => {
+    if (!Array.isArray(source.documentIds))
+        return [undefined];
+    const batches = [];
+    for (let at = 0; at < source.documentIds.length; at += exports.SEARCH_DOCUMENT_IDS_MAX) {
+        batches.push(source.documentIds.slice(at, at + exports.SEARCH_DOCUMENT_IDS_MAX));
+    }
+    return batches;
+};
+/** Runs `worker` over `items`, at most `limit` at a time. */
+const inPool = async (items, limit, worker) => {
+    let next = 0;
+    const run = async () => {
+        while (next < items.length) {
+            const index = next++;
+            await worker(items[index]);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, run));
+};
+/** The status of a failed platform call, from an axios error or one shaped like it. */
+const statusOf = (error) => {
+    const status = error?.response?.status ?? error?.status;
+    return typeof status === "number" ? status : null;
+};
+/**
+ * Searches every source for every query, under the person's access, and hands
+ * back the passages found, best first, each once, tagged "k1", "k2"… for the
+ * model to cite. A source with documents is searched within them (in batches of
+ * SEARCH_DOCUMENT_IDS_MAX); one without, whole. A source the person may not
+ * read (401, 403, 404) is skipped: none of its passages are used and no more of
+ * its searches are made. A search that fails otherwise is reported and the
+ * passages its other searches found stand. Either way it is in `skipped`, once
+ * per knowledge base, and the passages of the others stand.
+ * @param options `sources`, `queries`, `search` (client-api
+ *   `knowledgeBaseAgent.search`), `token` (the run's AGENT token), `topK`
+ *   per search (default DEFAULT_TOP_K)
+ * @returns `{ passages, skipped }`
+ */
+const retrievePassages = async (options) => {
+    const queries = [
+        ...new Set((Array.isArray(options.queries) ? options.queries : [])
+            .map((query) => text(query).slice(0, exports.QUERY_MAX_LENGTH))
+            .filter(Boolean)),
+    ];
+    const sources = Array.isArray(options.sources) ? options.sources : [];
+    const topK = options.topK ?? exports.DEFAULT_TOP_K;
+    const searches = [];
+    for (const source of sources) {
+        for (const documentIds of batchesOf(source)) {
+            if (documentIds && documentIds.length === 0)
+                continue;
+            for (const query of queries) {
+                searches.push({ source, query, documentIds, order: searches.length });
+            }
+        }
+    }
+    const found = new Map();
+    const skipped = new Map();
+    await inPool(searches, CONCURRENCY, async ({ source, query, documentIds, order }) => {
+        if (skipped.get(source.knowledgeBaseId)?.noAccess)
+            return;
+        try {
+            const answer = await options.search(source.knowledgeBaseId, query, documentIds ? { topK, documentIds } : { topK }, options.token);
+            (Array.isArray(answer?.chunks) ? answer.chunks : []).forEach((chunk, rank) => {
+                const chunkId = id(chunk?._id);
+                if (!chunkId || !id(chunk?.documentId))
+                    return;
+                const known = found.get(chunkId);
+                const better = !known || (chunk.score ?? 0) > (known.chunk.score ?? 0);
+                // Ties keep the first search's rank, so the order is the searches' own.
+                found.set(chunkId, {
+                    chunk: better ? chunk : known.chunk,
+                    knowledgeBaseId: source.knowledgeBaseId,
+                    order: known ? Math.min(known.order, order * 1000 + rank) : order * 1000 + rank,
+                });
+            });
+        }
+        catch (error) {
+            const status = statusOf(error);
+            const noAccess = status !== null && NO_ACCESS.has(status);
+            // A refusal outranks a failure reported before it.
+            if (skipped.has(source.knowledgeBaseId) && !noAccess)
+                return;
+            skipped.set(source.knowledgeBaseId, {
+                knowledgeBaseId: source.knowledgeBaseId,
+                message: typeof error?.message === "string" ? error.message : String(error),
+                noAccess,
+                status,
+            });
+        }
+    });
+    const passages = [...found.entries()]
+        .filter(([, entry]) => !skipped.get(entry.knowledgeBaseId)?.noAccess)
+        .sort(([, a], [, b]) => (b.chunk.score ?? 0) - (a.chunk.score ?? 0) || a.order - b.order)
+        .map(([chunkId, { chunk, knowledgeBaseId }], index) => ({
+        chunkId,
+        documentId: id(chunk.documentId),
+        documentName: text(chunk.documentName) || null,
+        knowledgeBaseId: id(chunk.knowledgeBaseId) || knowledgeBaseId,
+        pageNumber: typeof chunk.pageNumber === "number" ? chunk.pageNumber : null,
+        score: typeof chunk.score === "number" ? chunk.score : null,
+        sectionTitle: text(chunk.sectionTitle) || null,
+        skills: (Array.isArray(chunk.skills) ? chunk.skills : []).map((skill) => ({
+            microSkills: (Array.isArray(skill?.microSkills) ? skill.microSkills : []).filter((name) => typeof name === "string"),
+            name: typeof skill?.name === "string" ? skill.name : null,
+        })),
+        tag: `k${index + 1}`,
+        text: typeof chunk.text === "string" ? chunk.text : "",
+    }));
+    return { passages, skipped: [...skipped.values()] };
+};
+exports.retrievePassages = retrievePassages;
+/**
+ * The passages as a prompt shows them: tag, where each came from, and its text.
+ * @param passages From `retrievePassages`
+ * @returns `[{ tag, document, section, text }]`, for the model's input
+ */
+const passagesForPrompt = (passages) => (Array.isArray(passages) ? passages : []).map((passage) => ({
+    document: passage.documentName,
+    section: passage.sectionTitle,
+    tag: passage.tag,
+    text: passage.text,
+}));
+exports.passagesForPrompt = passagesForPrompt;
+/**
+ * STACKFACTOR references for passages: one per passage, in their order, with no
+ * cap. With `tags`, only the passages the model cited by tag (any tag it made
+ * up is passed over); without, every passage.
+ * @param passages From `retrievePassages`
+ * @param tags The tags the model cited ("k3", "K3" and " k3 " alike)
+ * @returns The references, ready for a skill's, a microskill's or a question's `references`
+ */
+const referencesFor = (passages, tags) => {
+    const list = Array.isArray(passages) ? passages : [];
+    const cited = Array.isArray(tags)
+        ? new Set(tags.map((tag) => text(tag).toLowerCase()).filter(Boolean))
+        : null;
+    return list
+        .filter((passage) => !cited || cited.has(passage.tag.toLowerCase()))
+        .map((passage) => ({
+        description: passage.sectionTitle,
+        kind: exports.STACKFACTOR_REFERENCE.KIND,
+        knowledgeBase: {
+            chunkId: passage.chunkId,
+            documentId: passage.documentId,
+            knowledgeBaseId: passage.knowledgeBaseId,
+            sectionTitle: passage.sectionTitle,
+        },
+        origin: exports.STACKFACTOR_REFERENCE.ORIGIN,
+        target: {
+            elementId: passage.documentId,
+            elementType: exports.STACKFACTOR_REFERENCE.TARGET_ELEMENT_TYPE,
+            parentId: passage.knowledgeBaseId,
+        },
+        title: passage.documentName || passage.sectionTitle || "Knowledge base document",
+        visibility: exports.STACKFACTOR_REFERENCE.VISIBILITY,
+    }));
+};
+exports.referencesFor = referencesFor;
+exports.default = {
+    DEFAULT_TOP_K: exports.DEFAULT_TOP_K,
+    QUERY_MAX_LENGTH: exports.QUERY_MAX_LENGTH,
+    SEARCH_DOCUMENT_IDS_MAX: exports.SEARCH_DOCUMENT_IDS_MAX,
+    STACKFACTOR_REFERENCE: exports.STACKFACTOR_REFERENCE,
+    passagesForPrompt: exports.passagesForPrompt,
+    referencesFor: exports.referencesFor,
+    retrievePassages: exports.retrievePassages,
+    sourcesFromCoverage: exports.sourcesFromCoverage,
+    sourcesFromReferences: exports.sourcesFromReferences,
+};

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

@@ -1 +1 @@
-{"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"}
+{"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;AAmHD;;;;;;;;;;;;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;mBAzOpD,GAAG,KAAG,WAAW;IA2O1C,0EAA0E;;IAE1E,gFAAgF;oBA9BzE,OAAO,YACL,GAAG,YACH,GAAG,KACX,QAAQ;IA6BT,wDAAwD;uBA1PhC,GAAG,KAAG,IAAI,IAAI,MAAM;IA4P5C,kCAAkC;;;AA7BpC,wBA+BE"}