@stackfactor/agent-utils 1.7.0 → 1.9.0

package/README.md

@@ -419,6 +419,21 @@ A model that cannot tell it received half a regulation will reason over the half
 - Per-URL failures are surfaced in the tool result instead of being dropped, so a fetch failure is not mistaken for an absence of content.
 - Tool calls honour the caller's abort signal, so a cancelled run stops paying for in-flight crawls.
 
+### Checking that cited links resolve
+
+`checkUrlsReachable(urls, config, usageTracker?)` returns the URLs, exactly as passed, that Tavily could fetch. Use it in place of requesting a link yourself. Cited links come from web pages anyone can publish, so a link, its redirects or its DNS can point inside StackFactor's network; a request this process sends would go there through StackFactor's own egress addresses. Tavily fetches from its own infrastructure.
+
+```js
+const { checkUrlsReachable } = require("@stackfactor/agent-utils");
+
+const live = await checkUrlsReachable(references.map((r) => r.url), config, usageTracker);
+const kept = references.filter((r) => !r.url || live.has(r.url));
+```
+
+- Only `http:` and `https:` URLs are sent, 20 per call (Tavily's limit), at basic depth: 1 credit per 5 URLs fetched, failed ones free. Credits are billed like any Tavily call; the URLs are not added to `webSearchSources`.
+- A URL Tavily lists under `failed_results` is unreachable. A batch whose call fails, or a config without `tavilyAPIKey`, confirms none of its URLs. It never throws.
+- No `config.tavily` or `agentic` is needed: it calls Tavily directly, not through the model.
+
 ---
 
 ## Supported Models

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,11 +6,14 @@ 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";
+import { checkUrlsReachable } from "./tavily.js";
 export { constants };
 export { errorHandling, AppError };
 export type { ParsedError } from "./errorHandling.js";
 export { langChain };
 export type { UsageTracker } from "./langChain.js";
+export { checkUrlsReachable };
 export type { TavilyConfig, TavilyToolName } from "./tavily.js";
 export { logger };
 export { serve, runOnce, isRunOnceExecution, EXECUTION_ENV };
@@ -20,4 +23,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;AAC7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEjD,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,OAAO,EAAE,kBAAkB,EAAE,CAAC;AAE9B,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.checkUrlsReachable = 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,7 @@ 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;
+const tavily_js_1 = require("./tavily.js");
+Object.defineProperty(exports, "checkUrlsReachable", { enumerable: true, get: function () { return tavily_js_1.checkUrlsReachable; } });

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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"}