@stackfactor/agent-utils 1.7.0 → 1.9.0

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/cjs/tavily.d.ts

@@ -82,9 +82,40 @@ export declare const assertTavilyUsable: (config: any, options: TavilyConfig) =>
  * @returns LangChain tool instances to append to the agent's tool list
  */
 export declare const buildTavilyTools: (config: any, options: TavilyConfig, usageTracker?: UsageTracker | null) => any[];
+/**
+ * Which of these URLs resolve, judged by Tavily fetching them rather than by
+ * this process connecting to them.
+ *
+ * An agent that confirms a cited link by requesting it itself sends that
+ * request from inside StackFactor's network, through its fixed egress
+ * addresses, to wherever the link, a redirect or its DNS points — and cited
+ * links come from web pages anyone can publish, so that is a request to an
+ * address an outsider chose (server-side request forgery). Tavily fetches from
+ * its own infrastructure, so nothing here ever connects to such a host.
+ *
+ * Only `http:` and `https:` URLs are sent; any other is unreachable by
+ * definition. They go in batches of 20, Tavily's limit, at basic depth: 1
+ * credit per 5 URLs Tavily fetched, failed ones free. The credits are billed
+ * like every other Tavily call, but the URLs are not added to the tracker's
+ * sources: a link worth checking was found there in the first place.
+ *
+ * Tavily accounts for every URL it is given, listing the ones it could not
+ * fetch under `failed_results`. So a URL listed there is unreachable, and every
+ * other URL of a batch Tavily answered is reachable (the results may name a
+ * URL by its address after a redirect, which is why they are not matched). A
+ * batch whose call fails outright, or a config without `tavilyAPIKey`,
+ * confirms none of its URLs: a link that could not be checked is not trusted.
+ *
+ * @param urls - The URLs to check; a URL given twice is checked once
+ * @param config - The integration config; supplies `tavilyAPIKey`
+ * @param usageTracker - Optional accumulator the credits are counted into
+ * @returns The given URLs, exactly as passed, that resolve
+ */
+export declare const checkUrlsReachable: (urls: readonly string[], config: any, usageTracker?: UsageTracker | null) => Promise<Set<string>>;
 declare const _default: {
     assertTavilyUsable: (config: any, options: TavilyConfig) => void;
     buildTavilyTools: (config: any, options: TavilyConfig, usageTracker?: UsageTracker | null) => any[];
+    checkUrlsReachable: (urls: readonly string[], config: any, usageTracker?: UsageTracker | null) => Promise<Set<string>>;
     getTavilyOptions: (config: any) => TavilyConfig | null;
     recordTavilyUsage: (tracker: UsageTracker | null | undefined, _config: any, credits: number, sources: {
         url: string;

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

@@ -1 +1 @@
-{"version":3,"file":"tavily.d.ts","sourceRoot":"","sources":["../../src/tavily.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AA0BnD,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,GAAG,KAAK,CAAC;AAEpE;;;;;;;;;GASG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,cAAc,EAAE,CAAC;IACzB,iEAAiE;IACjE,WAAW,CAAC,EAAE,OAAO,GAAG,UAAU,GAAG,MAAM,GAAG,YAAY,CAAC;IAC3D,kFAAkF;IAClF,YAAY,CAAC,EAAE,OAAO,GAAG,UAAU,CAAC;IACpC,2CAA2C;IAC3C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oEAAoE;IACpE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qEAAqE;IACrE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,4CAA4C;IAC5C,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,6CAA6C;IAC7C,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,MAAM,CAAC,EAAE,UAAU,GAAG,MAAM,CAAC;CAC9B,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAAI,QAAQ,GAAG,KAAG,YAAY,GAAG,IAI7D,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,GAAI,QAAQ,GAAG,EAAE,SAAS,YAAY,KAAG,IAsBvE,CAAC;AAsLF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,gBAAgB,GAC3B,QAAQ,GAAG,EACX,SAAS,YAAY,EACrB,eAAc,YAAY,GAAG,IAAW,KACvC,GAAG,EA2PL,CAAC;;iCA5dyC,GAAG,WAAW,YAAY,KAAG,IAAI;+BA8NlE,GAAG,WACF,YAAY,iBACP,YAAY,GAAG,IAAI,KAChC,GAAG,EAAE;+BAhPiC,GAAG,KAAG,YAAY,GAAG,IAAI;iCAsIvD,YAAY,GAAG,IAAI,GAAG,SAAS,WAC/B,GAAG,WACH,MAAM,WACN;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,KACzC,IAAI;;AAmWP,wBAKE"}
+{"version":3,"file":"tavily.d.ts","sourceRoot":"","sources":["../../src/tavily.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AA0BnD,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,GAAG,KAAK,CAAC;AAEpE;;;;;;;;;GASG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,cAAc,EAAE,CAAC;IACzB,iEAAiE;IACjE,WAAW,CAAC,EAAE,OAAO,GAAG,UAAU,GAAG,MAAM,GAAG,YAAY,CAAC;IAC3D,kFAAkF;IAClF,YAAY,CAAC,EAAE,OAAO,GAAG,UAAU,CAAC;IACpC,2CAA2C;IAC3C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oEAAoE;IACpE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qEAAqE;IACrE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,4CAA4C;IAC5C,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,6CAA6C;IAC7C,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,MAAM,CAAC,EAAE,UAAU,GAAG,MAAM,CAAC;CAC9B,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAAI,QAAQ,GAAG,KAAG,YAAY,GAAG,IAI7D,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,GAAI,QAAQ,GAAG,EAAE,SAAS,YAAY,KAAG,IAsBvE,CAAC;AAsLF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,gBAAgB,GAC3B,QAAQ,GAAG,EACX,SAAS,YAAY,EACrB,eAAc,YAAY,GAAG,IAAW,KACvC,GAAG,EA2PL,CAAC;AAqBF;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,kBAAkB,GAC7B,MAAM,SAAS,MAAM,EAAE,EACvB,QAAQ,GAAG,EACX,eAAc,YAAY,GAAG,IAAW,KACvC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CA6DrB,CAAC;;iCA/kByC,GAAG,WAAW,YAAY,KAAG,IAAI;+BA8NlE,GAAG,WACF,YAAY,iBACP,YAAY,GAAG,IAAI,KAChC,GAAG,EAAE;+BA8SA,SAAS,MAAM,EAAE,UACf,GAAG,iBACG,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;+BAjiBkB,GAAG,KAAG,YAAY,GAAG,IAAI;iCAsIvD,YAAY,GAAG,IAAI,GAAG,SAAS,WAC/B,GAAG,WACH,MAAM,WACN;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,KACzC,IAAI;;AAsdP,wBAME"}

package/dist/cjs/tavily.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.buildTavilyTools = exports.assertTavilyUsable = exports.getTavilyOptions = void 0;
+exports.checkUrlsReachable = exports.buildTavilyTools = exports.assertTavilyUsable = exports.getTavilyOptions = void 0;
 const langchain_1 = require("langchain");
 const zod_1 = require("zod");
 const const_js_1 = __importDefault(require("./const.js"));
@@ -395,9 +395,96 @@ const buildTavilyTools = (config, options, usageTracker = null) => {
     return tools;
 };
 exports.buildTavilyTools = buildTavilyTools;
+/** Tavily's own limit on URLs per `/extract` request. */
+const EXTRACT_MAX_URLS = 20;
+/** Seconds. A reachability check needs the page fetched, not rendered at length. */
+const REACHABILITY_TIMEOUT_SECONDS = 20;
+/** How a URL is matched against Tavily's answer: trimmed, lowercased, no trailing slash. */
+const urlMatchKey = (url) => url.trim().replace(/\/+$/, "").toLowerCase();
+/** True for an `http:` or `https:` URL; false for anything else, unparsable included. */
+const isWebUrl = (url) => {
+    try {
+        const { protocol } = new URL(url);
+        return protocol === "http:" || protocol === "https:";
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Which of these URLs resolve, judged by Tavily fetching them rather than by
+ * this process connecting to them.
+ *
+ * An agent that confirms a cited link by requesting it itself sends that
+ * request from inside StackFactor's network, through its fixed egress
+ * addresses, to wherever the link, a redirect or its DNS points — and cited
+ * links come from web pages anyone can publish, so that is a request to an
+ * address an outsider chose (server-side request forgery). Tavily fetches from
+ * its own infrastructure, so nothing here ever connects to such a host.
+ *
+ * Only `http:` and `https:` URLs are sent; any other is unreachable by
+ * definition. They go in batches of 20, Tavily's limit, at basic depth: 1
+ * credit per 5 URLs Tavily fetched, failed ones free. The credits are billed
+ * like every other Tavily call, but the URLs are not added to the tracker's
+ * sources: a link worth checking was found there in the first place.
+ *
+ * Tavily accounts for every URL it is given, listing the ones it could not
+ * fetch under `failed_results`. So a URL listed there is unreachable, and every
+ * other URL of a batch Tavily answered is reachable (the results may name a
+ * URL by its address after a redirect, which is why they are not matched). A
+ * batch whose call fails outright, or a config without `tavilyAPIKey`,
+ * confirms none of its URLs: a link that could not be checked is not trusted.
+ *
+ * @param urls - The URLs to check; a URL given twice is checked once
+ * @param config - The integration config; supplies `tavilyAPIKey`
+ * @param usageTracker - Optional accumulator the credits are counted into
+ * @returns The given URLs, exactly as passed, that resolve
+ */
+const checkUrlsReachable = async (urls, config, usageTracker = null) => {
+    const reachable = new Set();
+    const candidates = [
+        ...new Set(urls.filter((url) => typeof url === "string" && isWebUrl(url.trim()))),
+    ];
+    if (candidates.length === 0)
+        return reachable;
+    const apiKey = config?.tavilyAPIKey;
+    if (!apiKey) {
+        logger_js_1.default.log(null, logger_js_1.default.levels.warn, `Tavily reachability: no tavilyAPIKey, so none of ${candidates.length} URL(s) is confirmed`);
+        return reachable;
+    }
+    const batches = [];
+    for (let start = 0; start < candidates.length; start += EXTRACT_MAX_URLS) {
+        batches.push(candidates.slice(start, start + EXTRACT_MAX_URLS));
+    }
+    await Promise.all(batches.map(async (batch) => {
+        let data;
+        try {
+            data = await callTavily("extract", {
+                urls: batch.map((url) => url.trim()),
+                extract_depth: "basic",
+                format: "text",
+            }, apiKey, REACHABILITY_TIMEOUT_SECONDS);
+        }
+        catch (err) {
+            logger_js_1.default.log(null, logger_js_1.default.levels.warn, `Tavily reachability: the check of ${batch.length} URL(s) failed (${err?.message || String(err)}), so none of them is confirmed`);
+            return;
+        }
+        recordTavilyUsage(usageTracker, config, data?.usage?.credits || 0, []);
+        const failed = new Set((data?.failed_results || [])
+            .map((entry) => typeof entry?.url === "string" ? urlMatchKey(entry.url) : "")
+            .filter(Boolean));
+        for (const url of batch) {
+            if (!failed.has(urlMatchKey(url)))
+                reachable.add(url);
+        }
+    }));
+    return reachable;
+};
+exports.checkUrlsReachable = checkUrlsReachable;
 exports.default = {
     assertTavilyUsable: exports.assertTavilyUsable,
     buildTavilyTools: exports.buildTavilyTools,
+    checkUrlsReachable: exports.checkUrlsReachable,
     getTavilyOptions: exports.getTavilyOptions,
     recordTavilyUsage,
 };

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

package/dist/esm/errorHandling.js

@@ -81,11 +81,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/esm/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/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,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/esm/index.js

@@ -6,12 +6,16 @@ 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 { langChain };
+export { checkUrlsReachable };
 export { logger };
 export { serve, runOnce, isRunOnceExecution, EXECUTION_ENV };
 export { callAgent };
 export { checkAgent };
 export { runtimeContext };
 export { recordUsage, USAGE_UNITS };
+export { stackfactorKnowledge };

package/dist/esm/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/esm/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/esm/langChain.js

@@ -327,8 +327,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":
@@ -764,19 +770,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) => {
@@ -785,12 +802,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,
                     });
                 },
             },
@@ -1254,7 +1273,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) {