@stackfactor/agent-utils 1.11.0 → 1.13.0

package/dist/esm/referenceContext.js

@@ -11,6 +11,12 @@
 //     references cite, searched under the run's own token, so a run reads only
 //     what the person it acts for may open.
 //
+// A cited knowledge base that cannot be read stops the run (Candin,
+// 2026-10-13): with no token, a refusal or a failed search, the gathering
+// throws a KnowledgeAccessError naming the documents, and the agent answers
+// with it rather than writing as if the content cited nothing. A search that
+// works and finds nothing is not an error.
+//
 // A reference is cited by its short id `r<N>`, N being its index in the
 // supplied list, whatever its kind.
 //
@@ -18,9 +24,43 @@ import logger from "./logger.js";
 import { STACKFACTOR_REFERENCE, retrievePassages, sourcesFromReferences, } from "./stackfactorKnowledge.js";
 /** How many passages one search asks for when the caller does not say. */
 const DEFAULT_REFERENCE_TOP_K = 5;
+/** How many passages a gathering keeps when the caller does not say: the best-ranked. */
+const DEFAULT_MAX_PASSAGES = 40;
 /** The prompt key the passages are handed to the model under. */
 export const REFERENCE_PASSAGES_KEY = "Knowledge Base Passages";
 const text = (value) => (typeof value === "string" ? value.trim() : "");
+/**
+ * The knowledge base documents a run's references cite could not be read: the
+ * run has no token, the person may not open a cited knowledge base (401, 403,
+ * 404), or its search failed. The agent answers with it — `code` and `message`
+ * are what the person sees — and generates nothing.
+ */
+export class KnowledgeAccessError extends Error {
+    /** 403 when every skipped knowledge base refused the person (or there was no token), else 502. */
+    code;
+    /** The knowledge bases that could not be searched, and why; empty when there was no token. */
+    skipped;
+    /** The titles of the STACKFACTOR references citing those knowledge bases, each once. */
+    documents;
+    /**
+     * @param details `skipped` (from the search) and `documents` (titles); the
+     *   code and the message follow from them
+     */
+    constructor(details = {}) {
+        const skipped = Array.isArray(details.skipped) ? details.skipped : [];
+        const documents = [...new Set((Array.isArray(details.documents) ? details.documents : []).map(text).filter(Boolean))];
+        const code = skipped.every((source) => source?.noAccess) ? 403 : 502;
+        const titles = documents.map((title) => `"${title}"`).join(", ");
+        super(code === 403
+            ? `The knowledge base documents this content cites could not be read with your access${titles ? `: ${titles}` : ""}.`
+            : `The knowledge base documents this content cites could not be read: the knowledge base search failed${titles ? ` for ${titles}` : ""}.`);
+        this.name = "KnowledgeAccessError";
+        this.code = code;
+        this.skipped = skipped;
+        this.documents = documents;
+        Object.setPrototypeOf(this, KnowledgeAccessError.prototype);
+    }
+}
 const id = (value) => typeof value === "string" ? value.trim() : value != null && typeof value === "object" ? String(value) : "";
 const shortId = (index) => `r${index}`;
 /** The document a STACKFACTOR reference cites, or "" when it cites none. */
@@ -29,6 +69,14 @@ const documentOf = (reference) => {
     return (id(reference.knowledgeBase?.documentId) ||
         (target.elementType === STACKFACTOR_REFERENCE.TARGET_ELEMENT_TYPE ? id(target.elementId) : ""));
 };
+/** The knowledge base a STACKFACTOR reference's document is in, or "" when it cites no document. */
+const knowledgeBaseOf = (reference) => {
+    const target = reference.target ?? {};
+    return (id(reference.knowledgeBase?.knowledgeBaseId) ||
+        (target.elementType === STACKFACTOR_REFERENCE.TARGET_ELEMENT_TYPE ? id(target.parentId) : ""));
+};
+/** A cap the caller passed (a whole number, 0 or more), else `fallback`. */
+const capOf = (value, fallback) => typeof value === "number" && Number.isInteger(value) && value >= 0 ? value : fallback;
 /** The kinds the platform retired; it reads them as PUBLICATION. */
 const RETIRED_KINDS = new Set(["DOCUMENT", "KNOWLEDGE_BASE", "NOTE"]);
 /** A reference's kind as the platform reads it: missing or retired is PUBLICATION. */
@@ -54,39 +102,71 @@ const pagesOf = (references) => {
     });
     return pages;
 };
-/** The short ids of the STACKFACTOR references citing each document. */
-const citersByDocument = (references) => {
-    const citers = new Map();
+/**
+ * The short ids of the STACKFACTOR references citing each document, and of
+ * those citing each chunk (`knowledgeBase.chunkId`) of a document.
+ */
+const citersOf = (references) => {
+    const byDocument = new Map();
+    const byChunk = new Map();
     references.forEach((reference, index) => {
         if (reference?.kind !== STACKFACTOR_REFERENCE.KIND)
             return;
         const documentId = documentOf(reference);
-        if (documentId)
-            citers.set(documentId, [...(citers.get(documentId) ?? []), shortId(index)]);
+        if (!documentId)
+            return;
+        byDocument.set(documentId, [...(byDocument.get(documentId) ?? []), shortId(index)]);
+        const chunkId = id(reference.knowledgeBase?.chunkId);
+        if (chunkId)
+            byChunk.set(chunkId, [...(byChunk.get(chunkId) ?? []), shortId(index)]);
     });
-    return citers;
+    return { byChunk, byDocument };
 };
+/**
+ * The error for cited knowledge bases that could not be read: it names the
+ * documents of the STACKFACTOR references citing them.
+ */
+const accessError = (references, unread, skipped) => new KnowledgeAccessError({
+    documents: references
+        .filter((reference) => reference?.kind === STACKFACTOR_REFERENCE.KIND && documentOf(reference) && unread.has(knowledgeBaseOf(reference)))
+        .map((reference) => reference.title),
+    skipped,
+});
 /**
  * What a list of references points at: its pages, and the passages of the
  * documents its STACKFACTOR references cite. One search per knowledge base per
- * query (per batch of 500 documents), however many references there are. With
- * no token no search is made and the pages are still listed. A knowledge base
- * the person cannot open is in `skipped`; the other passages stand.
+ * query (per batch of 500 documents), however many references there are.
+ *
+ * References that cite a knowledge base the run cannot read stop it: with no
+ * token, or when any cited knowledge base is skipped (refused or failed), it
+ * throws a KnowledgeAccessError naming the documents. A search that works and
+ * finds nothing is not an error. With no knowledge cited, no token is needed.
+ *
+ * A passage is attributed to the references citing its chunk, else to every
+ * reference citing its document. The best-ranked `maxPassages` are kept, and
+ * the first `maxPages` pages in reference order.
  * @param options `references` (a skill's, a microskill's…), `queries` to
  *   search the cited documents with, `search` (client-api
  *   `knowledgeBaseAgent.search`), `token` (the run's AGENT token), `topK` per
- *   search (default 5)
- * @returns `{ pages, passages, skipped, citesKnowledge }`
+ *   search (default 5), `maxPassages` (default 40), `maxPages` (default: all)
+ * @returns `{ pages, passages, skipped, citesKnowledge }`; `skipped` is always
+ *   empty, since a skip throws
+ * @throws KnowledgeAccessError When cited knowledge bases cannot be read
  */
 export const gatherReferenceContext = async (options) => {
     const references = Array.isArray(options.references) ? options.references : [];
     const sources = sourcesFromReferences(references);
     const citesKnowledge = sources.length > 0;
-    const pages = pagesOf(references);
-    if (!options.token || !citesKnowledge) {
-        logContext(pages.length, 0, [], citesKnowledge && !options.token);
+    const pages = pagesOf(references).slice(0, capOf(options.maxPages, Infinity));
+    if (!citesKnowledge) {
+        logContext(pages.length, 0, []);
         return { citesKnowledge, pages, passages: [], skipped: [] };
     }
+    if (!options.token) {
+        const error = accessError(references, new Set(sources.map((source) => source.knowledgeBaseId)), []);
+        logContext(pages.length, 0, [], { error, noToken: true });
+        throw error;
+    }
     const found = await retrievePassages({
         queries: options.queries,
         search: options.search,
@@ -94,30 +174,44 @@ export const gatherReferenceContext = async (options) => {
         token: options.token,
         topK: options.topK ?? DEFAULT_REFERENCE_TOP_K,
     });
-    const citers = citersByDocument(references);
+    if (found.skipped.length > 0) {
+        const unread = new Set(found.skipped.map((source) => source.knowledgeBaseId));
+        const error = accessError(references, unread, found.skipped);
+        logContext(pages.length, 0, found.skipped, { error });
+        throw error;
+    }
+    const citers = citersOf(references);
     const passages = found.passages
-        .filter((passage) => citers.has(passage.documentId))
+        .filter((passage) => citers.byDocument.has(passage.documentId))
+        .slice(0, capOf(options.maxPassages, DEFAULT_MAX_PASSAGES))
         .map((passage) => ({
         chunkId: passage.chunkId,
         document: passage.documentName,
         documentId: passage.documentId,
         knowledgeBaseId: passage.knowledgeBaseId,
-        references: citers.get(passage.documentId),
+        references: citers.byChunk.get(passage.chunkId) ?? citers.byDocument.get(passage.documentId),
         section: passage.sectionTitle,
         text: passage.text,
     }));
-    logContext(pages.length, passages.length, found.skipped, false);
-    return { citesKnowledge, pages, passages, skipped: found.skipped };
+    logContext(pages.length, passages.length, []);
+    return { citesKnowledge, pages, passages, skipped: [] };
 };
-/** The one summary line of a gathering, for the logs. */
-const logContext = (pages, passages, skipped, noToken) => {
+/**
+ * The one summary line of a gathering, for the logs: a warning when it was
+ * refused. Document titles stay out of the logs.
+ */
+const logContext = (pages, passages, skipped, refusal) => {
     const parts = [`${pages} page${pages === 1 ? "" : "s"}`, `${passages} passage${passages === 1 ? "" : "s"}`];
     if (skipped.length > 0) {
         parts.push(`skipped knowledge bases: ${skipped.map((s) => `${s.knowledgeBaseId} (noAccess: ${s.noAccess})`).join(", ")}`);
     }
-    if (noToken)
-        parts.push("no token, so no passages");
-    logger.log(null, logger.levels.info, `Reference context: ${parts.join("; ")}`);
+    if (refusal?.noToken)
+        parts.push("no token");
+    if (refusal) {
+        const count = refusal.error.documents.length;
+        parts.push(`refused (${refusal.error.code}): ${count} document${count === 1 ? "" : "s"} unreadable`);
+    }
+    logger.log(null, refusal ? logger.levels.warn : logger.levels.info, `Reference context: ${parts.join("; ")}`);
 };
 /**
  * The passages as a prompt shows them: who cites each, where it came from, and
@@ -133,19 +227,23 @@ export const referencePassagesForPrompt = (context) => context.passages.map((pas
 }));
 /**
  * The tools a run is given. Never `search`, `map` or `crawl`: a run reads what
- * its references point at and discovers nothing. `extract` only, and only when
- * there are pages to open.
+ * its references point at and discovers nothing. `extract` only, only when
+ * there are pages to open, and kept to those pages: any other url the model
+ * asks for is refused (`allowedUrls`).
  * @param context From `gatherReferenceContext`
- * @returns `{ tavily: { tools: ["extract"] } }` with pages, else `{}`. With no
- *   pages it returns `{}`, so a caller spreading it over a config that already
- *   has a `tavily` key keeps that key (and `tavily: true` means search plus
- *   extract): callers must not carry a base `tavily` key.
+ * @returns `{ tavily: { tools: ["extract"], allowedUrls } }` with pages, else
+ *   `{}`. With no pages it returns `{}`, so a caller spreading it over a config
+ *   that already has a `tavily` key keeps that key (and `tavily: true` means
+ *   search plus extract): callers must not carry a base `tavily` key.
  */
-export const toolsFor = (context) => context.pages.length > 0 ? { tavily: { tools: ["extract"] } } : {};
+export const toolsFor = (context) => context.pages.length > 0
+    ? { tavily: { tools: ["extract"], allowedUrls: context.pages.map((page) => page.url) } }
+    : {};
 /**
  * The stage prompt followed by the guidance for each kind of source the run
- * has: pages, then passages; when it has neither, the `none` guidance. An empty
- * guidance adds nothing.
+ * has: pages, then passages; when it has neither (knowledge cited and readable
+ * but no passage found included), the `none` guidance. An empty guidance adds
+ * nothing.
  * @param stagePrompt The stage's own prompt
  * @param context From `gatherReferenceContext`
  * @param guidance From `sourceGuidanceFrom`
@@ -271,6 +369,7 @@ export const sourceGuidanceFrom = (config) => ({
     none: text(config?.noReferencesGuidance),
 });
 export default {
+    KnowledgeAccessError,
     REFERENCE_PASSAGES_KEY,
     citedReferences,
     composeSourceInstructions,

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

@@ -1 +1 @@
-{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../../src/serve.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,eAAe,CAAC;AAWtC,OAAO,EAIL,KAAK,WAAW,EACjB,MAAM,YAAY,CAAC;AAwPpB;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;AAE/D;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,CAC1B,OAAO,EAAE,GAAG,KACT,OAAO,CAAC;IAAE,IAAI,EAAE,GAAG,CAAC;IAAC,MAAM,EAAE,GAAG,CAAA;CAAE,CAAC,CAAC;AAEzC,MAAM,WAAW,YAAY;IAC3B,4EAA4E;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wFAAwF;IACxF,YAAY,CAAC,EAAE,aAAa,CAAC;IAC7B,uEAAuE;IACvE,aAAa,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;IACpE,sEAAsE;IACtE,SAAS,CAAC,EAAE,YAAY,CAAC;IACzB,iEAAiE;IACjE,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9B,mFAAmF;IACnF,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,mFAAmF;IACnF,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IACxD,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,MAAM,EAAE,CACN,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,MAAM,KACV,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CACpC;AAKD;;;;;;GAMG;AACH,eAAO,MAAM,aAAa;;;;;CAKhB,CAAC;AAEX,mFAAmF;AACnF,eAAO,MAAM,kBAAkB,GAAI,MAAK,MAAM,CAAC,UAAwB,KAAG,OACJ,CAAC;AAKvE;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,qBAAqB,GAAI,OAAO,GAAG,EAAE,SAAS,GAAG,KAAG,OAEhB,CAAC;AAKlD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,cAAc,GAAI,OAAO,GAAG,EAAE,SAAS,GAAG,KAAG,OAGN,CAAC;AA4JrD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,OAAO,GAClB,MAAM,SAAS,EACf,UAAS,YAAiB,KACzB,OAAO,CAAC,IAAI,CA8Id,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,KAAK,GAChB,MAAM,SAAS,EACf,UAAS,YAAiB,KACzB,IAAI,CAAC,MAyOP,CAAC"}
+{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../../src/serve.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,eAAe,CAAC;AAWtC,OAAO,EAIL,KAAK,WAAW,EACjB,MAAM,YAAY,CAAC;AAwPpB;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;AAE/D;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,CAC1B,OAAO,EAAE,GAAG,KACT,OAAO,CAAC;IAAE,IAAI,EAAE,GAAG,CAAC;IAAC,MAAM,EAAE,GAAG,CAAA;CAAE,CAAC,CAAC;AAEzC,MAAM,WAAW,YAAY;IAC3B,4EAA4E;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wFAAwF;IACxF,YAAY,CAAC,EAAE,aAAa,CAAC;IAC7B,uEAAuE;IACvE,aAAa,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;IACpE,sEAAsE;IACtE,SAAS,CAAC,EAAE,YAAY,CAAC;IACzB,iEAAiE;IACjE,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9B,mFAAmF;IACnF,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,mFAAmF;IACnF,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IACxD,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,MAAM,EAAE,CACN,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,MAAM,KACV,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CACpC;AAKD;;;;;;GAMG;AACH,eAAO,MAAM,aAAa;;;;;CAKhB,CAAC;AAEX,mFAAmF;AACnF,eAAO,MAAM,kBAAkB,GAAI,MAAK,MAAM,CAAC,UAAwB,KAAG,OACJ,CAAC;AAKvE;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,qBAAqB,GAAI,OAAO,GAAG,EAAE,SAAS,GAAG,KAAG,OAEhB,CAAC;AAKlD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,cAAc,GAAI,OAAO,GAAG,EAAE,SAAS,GAAG,KAAG,OAGN,CAAC;AAmKrD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,OAAO,GAClB,MAAM,SAAS,EACf,UAAS,YAAiB,KACzB,OAAO,CAAC,IAAI,CA8Id,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,KAAK,GAChB,MAAM,SAAS,EACf,UAAS,YAAiB,KACzB,IAAI,CAAC,MAyOP,CAAC"}

package/dist/esm/serve.js

@@ -339,8 +339,15 @@ const safeParse = (value, fallback) => {
 /**
  * Agents that fail throw `new Error(JSON.stringify({ code, message }))`. Unwrap
  * that back into a structured gRPC error frame; fall back to a 500 otherwise.
+ * A KnowledgeAccessError an agent did not catch (referenceContext) answers
+ * with its own code (403, 502) and message, which names the documents that
+ * could not be read. It is known by its name, so one thrown by another copy of
+ * this package in the agent's dependencies is known too.
  */
 const toErrorFrame = (error) => {
+    if (error?.name === "KnowledgeAccessError" && typeof error.code === "number") {
+        return { code: error.code, message: String(error.message ?? "") };
+    }
     try {
         const parsed = JSON.parse(error?.message);
         if (parsed && typeof parsed.code === "number") {

package/dist/esm/stackfactorKnowledge.d.ts

@@ -17,6 +17,8 @@ export interface KnowledgeChunk {
     knowledgeBaseId?: string;
     documentId: string;
     documentName?: string | null;
+    /** The title taken from the document itself (its front matter or first heading); null when it has none. */
+    documentTitle?: string | null;
     /** The document's page at its source (sent by the platform's search since backend-core #630). */
     documentUrl?: string | null;
     sectionTitle?: string | null;
@@ -50,6 +52,8 @@ export interface GroundingPassage {
     knowledgeBaseId: string;
     documentId: string;
     documentName: string | null;
+    /** The title taken from the document itself; null when it has none. */
+    documentTitle?: string | null;
     /** The document's page at its source, an http(s) address; null when the platform has none. */
     documentUrl?: string | null;
     sectionTitle: string | null;
@@ -67,7 +71,10 @@ 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. */
+    /**
+     * True when the platform refused the person (401, 403) or does not have the
+     * knowledge base (404); false when the search failed otherwise.
+     */
     noAccess: boolean;
     message: string;
 }
@@ -86,6 +93,8 @@ export interface StackFactorReference {
     knowledgeBase: {
         knowledgeBaseId: string;
         documentId: string;
+        /** The document's name at its source (GitHub: `<repo>/<path>`); absent when the passage has none. */
+        documentName?: string;
         chunkId: string;
         sectionTitle: string | null;
     };
@@ -116,9 +125,11 @@ export declare const sourcesFromCoverage: (coverage: unknown) => KnowledgeSource
  * 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.
+ * its searches are made. A search that fails otherwise is tried once more; when
+ * that fails too it is reported and the passages its other searches found
+ * stand. A refusal is never tried again. Either way it is in `skipped`, once
+ * per knowledge base, and the passages of the others stand; whether a skip is
+ * an error is the caller's to say.
  * @param options `sources`, `queries`, `search` (client-api
  *   `knowledgeBaseAgent.search`), `token` (the run's AGENT token), `topK`
  *   per search (default DEFAULT_TOP_K)
@@ -149,7 +160,9 @@ export declare const passagesForPrompt: (passages: GroundingPassage[]) => {
  * 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. Each links to its document's
- * page at the source (`url`) when the passage has one.
+ * page at the source (`url`) when the passage has one. Each is titled by its
+ * document's title, else its name, else its section; its pointer keeps the
+ * document's name (`knowledgeBase.documentName`) when the passage has one.
  * @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`

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

@@ -1 +1 @@
-{"version":3,"file":"stackfactorKnowledge.d.ts","sourceRoot":"","sources":["../../src/stackfactorKnowledge.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"stackfactorKnowledge.d.ts","sourceRoot":"","sources":["../../src/stackfactorKnowledge.ts"],"names":[],"mappings":"AAsCA,kGAAkG;AAClG,eAAO,MAAM,qBAAqB;;;;;EAKhC,CAAC;AAEH,0FAA0F;AAC1F,eAAO,MAAM,uBAAuB,MAAM,CAAC;AAE3C,0EAA0E;AAC1E,eAAO,MAAM,gBAAgB,OAAO,CAAC;AAErC,0EAA0E;AAC1E,eAAO,MAAM,aAAa,IAAI,CAAC;AAW/B,iFAAiF;AACjF,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,2GAA2G;IAC3G,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,iGAAiG;IACjG,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,EAAE,CAAC;IAC3D,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1B;AAED,oFAAoF;AACpF,MAAM,MAAM,eAAe,GAAG,CAC5B,eAAe,EAAE,MAAM,EACvB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,EAClD,KAAK,EAAE,MAAM,KACV,OAAO,CAAC;IAAE,MAAM,EAAE,cAAc,EAAE,CAAA;CAAE,CAAC,CAAC;AAE3C,8EAA8E;AAC9E,MAAM,WAAW,eAAe;IAC9B,eAAe,EAAE,MAAM,CAAC;IACxB,+DAA+D;IAC/D,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,+DAA+D;AAC/D,MAAM,WAAW,gBAAgB;IAC/B,0CAA0C;IAC1C,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,uEAAuE;IACvE,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,8FAA8F;IAC9F,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,WAAW,EAAE,MAAM,EAAE,CAAA;KAAE,EAAE,CAAC;IACzD,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,4DAA4D;AAC5D,MAAM,WAAW,aAAa;IAC5B,eAAe,EAAE,MAAM,CAAC;IACxB,uDAAuD;IACvD,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB;;;OAGG;IACH,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,kFAAkF;AAClF,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,aAAa,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,4EAA4E;IAC5E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,EAAE;QAAE,WAAW,EAAE,yBAAyB,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IACxF,aAAa,EAAE;QACb,eAAe,EAAE,MAAM,CAAC;QACxB,UAAU,EAAE,MAAM,CAAC;QACnB,qGAAqG;QACrG,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,OAAO,EAAE,MAAM,CAAC;QAChB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;KAC7B,CAAC;IACF,MAAM,EAAE,eAAe,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;CACpB;AAQD;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB,GAAI,YAAY,OAAO,KAAG,eAAe,EAmB1E,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,GAAI,UAAU,OAAO,KAAG,eAAe,EAWtE,CAAC;AAgCF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,gBAAgB,GAAU,SAAS;IAC9C,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,EAAE,eAAe,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,KAAG,OAAO,CAAC;IAAE,QAAQ,EAAE,gBAAgB,EAAE,CAAC;IAAC,OAAO,EAAE,aAAa,EAAE,CAAA;CAAE,CA2FrE,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,GAC5B,UAAU,gBAAgB,EAAE,KAC3B;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EAM5E,CAAC;AAEN;;;;;;;;;;GAUG;AACH,eAAO,MAAM,aAAa,GACxB,UAAU,gBAAgB,EAAE,EAC5B,OAAO,OAAO,EAAE,KACf,oBAAoB,EA+BtB,CAAC;;;;;;;;;;;kCAtDU,gBAAgB,EAAE,KAC3B;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE;8BAoBvE,gBAAgB,EAAE,SACrB,OAAO,EAAE,KACf,oBAAoB,EAAE;gCAhIuB;QAC9C,OAAO,EAAE,eAAe,EAAE,CAAC;QAC3B,OAAO,EAAE,MAAM,EAAE,CAAC;QAClB,MAAM,EAAE,eAAe,CAAC;QACxB,KAAK,EAAE,MAAM,CAAC;QACd,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,KAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,gBAAgB,EAAE,CAAC;QAAC,OAAO,EAAE,aAAa,EAAE,CAAA;KAAE,CAAC;oCAjEzB,OAAO,KAAG,eAAe,EAAE;wCA5BvB,OAAO,KAAG,eAAe,EAAE;;AAwP7E,wBAUE"}

package/dist/esm/stackfactorKnowledge.js

@@ -14,13 +14,19 @@
 //     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.
+//     cannot read is skipped and reported (`retrievePassages`): grounding from
+//     skill coverage generates without it. A knowledge base that references
+//     cite is another matter (Candin, 2026-10-13): the references reader
+//     (referenceContext `gatherReferenceContext`) stops the run with a
+//     KnowledgeAccessError instead.
 //
 // 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. Its
 // `url` is the document's page at its source (GitHub, Confluence…), when the
-// platform knows it, so a person can open what was cited. It is
+// platform knows it, so a person can open what was cited. Its title is the
+// title taken from the document itself, when ingestion found one, and its
+// pointer keeps the document's name at the source (`documentName`), so a
+// person can still see where the titled document lives. 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.
@@ -46,6 +52,8 @@ export const DEFAULT_TOP_K = 8;
 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]);
+/** How long a search that failed for another reason waits before it is tried once more. */
+const RETRY_DELAY_MS = 200;
 const text = (value) => (typeof value === "string" ? value.trim() : "");
 /** An http(s) address, or null: a reference's url lands in an `href`. */
 const webUrl = (value) => (/^https?:\/\//i.test(text(value)) ? text(value) : null);
@@ -125,15 +133,18 @@ const statusOf = (error) => {
     const status = error?.response?.status ?? error?.status;
     return typeof status === "number" ? status : null;
 };
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 /**
  * 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.
+ * its searches are made. A search that fails otherwise is tried once more; when
+ * that fails too it is reported and the passages its other searches found
+ * stand. A refusal is never tried again. Either way it is in `skipped`, once
+ * per knowledge base, and the passages of the others stand; whether a skip is
+ * an error is the caller's to say.
  * @param options `sources`, `queries`, `search` (client-api
  *   `knowledgeBaseAgent.search`), `token` (the run's AGENT token), `topK`
  *   per search (default DEFAULT_TOP_K)
@@ -162,8 +173,24 @@ export const retrievePassages = async (options) => {
     await inPool(searches, CONCURRENCY, async ({ source, query, documentIds, order }) => {
         if (skipped.get(source.knowledgeBaseId)?.noAccess)
             return;
+        const searchOnce = () => options.search(source.knowledgeBaseId, query, documentIds ? { topK, documentIds } : { topK }, options.token);
         try {
-            const answer = await options.search(source.knowledgeBaseId, query, documentIds ? { topK, documentIds } : { topK }, options.token);
+            let answer;
+            try {
+                answer = await searchOnce();
+            }
+            catch (error) {
+                // A refusal is the platform's answer and is not asked again. Any other
+                // failure may pass (a dropped connection, a 5xx), and one failed search
+                // would skip its whole knowledge base, so it is tried once more —
+                // unless the base refused the person meanwhile.
+                if (NO_ACCESS.has(statusOf(error)))
+                    throw error;
+                await delay(RETRY_DELAY_MS);
+                if (skipped.get(source.knowledgeBaseId)?.noAccess)
+                    return;
+                answer = await searchOnce();
+            }
             (Array.isArray(answer?.chunks) ? answer.chunks : []).forEach((chunk, rank) => {
                 const chunkId = id(chunk?._id);
                 if (!chunkId || !id(chunk?.documentId))
@@ -199,6 +226,7 @@ export const retrievePassages = async (options) => {
         chunkId,
         documentId: id(chunk.documentId),
         documentName: text(chunk.documentName) || null,
+        documentTitle: text(chunk.documentTitle) || null,
         documentUrl: webUrl(chunk.documentUrl),
         knowledgeBaseId: id(chunk.knowledgeBaseId) || knowledgeBaseId,
         pageNumber: typeof chunk.pageNumber === "number" ? chunk.pageNumber : null,
@@ -228,7 +256,9 @@ export const passagesForPrompt = (passages) => (Array.isArray(passages) ? passag
  * 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. Each links to its document's
- * page at the source (`url`) when the passage has one.
+ * page at the source (`url`) when the passage has one. Each is titled by its
+ * document's title, else its name, else its section; its pointer keeps the
+ * document's name (`knowledgeBase.documentName`) when the passage has one.
  * @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`
@@ -242,12 +272,14 @@ export const referencesFor = (passages, tags) => {
         .filter((passage) => !cited || cited.has(passage.tag.toLowerCase()))
         .map((passage) => {
         const url = webUrl(passage.documentUrl);
+        const documentName = text(passage.documentName);
         return {
             description: passage.sectionTitle,
             kind: STACKFACTOR_REFERENCE.KIND,
             knowledgeBase: {
                 chunkId: passage.chunkId,
                 documentId: passage.documentId,
+                ...(documentName ? { documentName } : {}),
                 knowledgeBaseId: passage.knowledgeBaseId,
                 sectionTitle: passage.sectionTitle,
             },
@@ -257,7 +289,7 @@ export const referencesFor = (passages, tags) => {
                 elementType: STACKFACTOR_REFERENCE.TARGET_ELEMENT_TYPE,
                 parentId: passage.knowledgeBaseId,
             },
-            title: passage.documentName || passage.sectionTitle || "Knowledge base document",
+            title: text(passage.documentTitle) || documentName || passage.sectionTitle || "Knowledge base document",
             ...(url ? { url } : {}),
             visibility: STACKFACTOR_REFERENCE.VISIBILITY,
         };

package/dist/esm/tavily.d.ts

@@ -46,6 +46,14 @@ export type TavilyConfig = {
      * for the tabular documents this is usually pointed at.
      */
     format?: "markdown" | "text";
+    /**
+     * The only URLs `web_extract` may read (matched trimmed, without case or a
+     * trailing slash, and sent as listed). Any other URL is never sent to
+     * Tavily: the tool answers the model with an error line for it and never
+     * throws. Unset, any URL may be read. Only `web_extract` reads it, so a run
+     * kept to its pages enables `extract` alone (referenceContext `toolsFor`).
+     */
+    allowedUrls?: string[];
 };
 /**
  * Normalizes `config.tavily` into an options object, returning `null` when the

package/dist/esm/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;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"}
+{"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;IAC7B;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB,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,IA+BvE,CAAC;AA0OF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,gBAAgB,GAC3B,QAAQ,GAAG,EACX,SAAS,YAAY,EACrB,eAAc,YAAY,GAAG,IAAW,KACvC,GAAG,EAmRL,CAAC;AAiBF;;;;;;;;;;;;;;;;;;;;;;;;;;;;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;;iCAhqByC,GAAG,WAAW,YAAY,KAAG,IAAI;+BA2RlE,GAAG,WACF,YAAY,iBACP,YAAY,GAAG,IAAI,KAChC,GAAG,EAAE;+BAkUA,SAAS,MAAM,EAAE,UACf,GAAG,iBACG,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;+BAlnBkB,GAAG,KAAG,YAAY,GAAG,IAAI;iCA+IvD,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;;AA8hBP,wBAME"}

package/dist/esm/tavily.js

@@ -53,6 +53,10 @@ export const assertTavilyUsable = (config, options) => {
     if (!config?.tavilyAPIKey) {
         throw errorHandlingHelper.create(constants.HTTP_CODES.INTERNAL_SERVER_ERROR, "Tavily tools are enabled but config.tavilyAPIKey is missing.");
     }
+    if (options.allowedUrls !== undefined &&
+        !(Array.isArray(options.allowedUrls) && options.allowedUrls.every((url) => typeof url === "string"))) {
+        throw errorHandlingHelper.create(constants.HTTP_CODES.BAD_REQUEST, "config.tavily.allowedUrls must be a list of URLs.");
+    }
     const unknown = (options.tools || []).filter((name) => !["search", "extract", "crawl", "map"].includes(name));
     if (unknown.length > 0) {
         throw errorHandlingHelper.create(constants.HTTP_CODES.BAD_REQUEST, `Unknown Tavily tool(s): ${unknown.join(", ")}. Valid values are search, extract, crawl, map.`);
@@ -160,6 +164,52 @@ const recordTavilyUsage = (tracker, _config, credits, sources) => {
         }
     }
 };
+/**
+ * Adds the URLs `web_extract` is about to ask Tavily for to
+ * `tracker.attemptedUrls`, each once across the run. Recorded before the call,
+ * so a URL the call then fails on is still there.
+ * @param tracker - The caller's usage accumulator, when it passed one
+ * @param urls - The URLs sent
+ */
+const recordAttemptedUrls = (tracker, urls) => {
+    if (!tracker || urls.length === 0)
+        return;
+    const attempted = tracker.attemptedUrls || (tracker.attemptedUrls = []);
+    for (const url of urls) {
+        if (!attempted.includes(url))
+            attempted.push(url);
+    }
+};
+/**
+ * How a URL is matched, against Tavily's answer or `allowedUrls`: trimmed,
+ * lowercased, no trailing slash.
+ */
+const urlMatchKey = (url) => url.trim().replace(/\/+$/, "").toLowerCase();
+/** What `web_extract` answers for each URL `allowedUrls` refused. */
+const REFUSED_HEADING = "Refused, not read (only the referenced pages may be read):";
+/**
+ * Splits the URLs the model asked `web_extract` for into those it may read —
+ * as `allowedUrls` lists them — and those it may not, each once. With no
+ * `allowedUrls`, every URL may be read, as asked.
+ * @param urls - The URLs the model asked for
+ * @param allowed - `allowedUrls` by match key, or `null` when unset
+ */
+const screenUrls = (urls, allowed) => {
+    if (!allowed)
+        return { read: urls, refused: [] };
+    const read = [];
+    const refused = [];
+    for (const url of urls) {
+        const listed = allowed.get(urlMatchKey(url));
+        if (listed === undefined) {
+            if (!refused.includes(url))
+                refused.push(url);
+        }
+        else if (!read.includes(listed))
+            read.push(listed);
+    }
+    return { read, refused };
+};
 /**
  * Trims one document to whatever the per-URL and per-call budgets allow,
  * appending a note when anything was cut.
@@ -230,6 +280,9 @@ export const buildTavilyTools = (config, options, usageTracker = null) => {
     const maxCharsPerUrl = options.maxCharsPerUrl ?? DEFAULT_MAX_CHARS_PER_URL;
     const maxCharsTotal = options.maxCharsTotal ?? DEFAULT_MAX_CHARS_TOTAL;
     const crawlLimit = options.crawlLimit ?? DEFAULT_CRAWL_LIMIT;
+    const allowed = Array.isArray(options.allowedUrls)
+        ? new Map(options.allowedUrls.map((url) => [urlMatchKey(url), url.trim()]))
+        : null;
     const newBudget = () => ({
         remaining: maxCharsTotal,
         perUrl: maxCharsPerUrl,
@@ -277,8 +330,22 @@ export const buildTavilyTools = (config, options, usageTracker = null) => {
     }
     if (enabled.includes("extract")) {
         tools.push(tool(async ({ urls, query }) => {
+            // Outside `allowedUrls` nothing is sent: the model is told per URL,
+            // and the run goes on with what it may read.
+            const { read, refused } = screenUrls(urls, allowed);
+            const refusal = refused.length
+                ? `${REFUSED_HEADING}\n${refused
+                    .map((url) => `- ${url}: not one of the referenced pages`)
+                    .join("\n")}`
+                : "";
+            if (refused.length > 0) {
+                logger.log(null, logger.levels.warn, `Tavily extract refused ${refused.length} URL(s) not among the allowed pages: ${refused.join(", ")}`);
+            }
+            if (read.length === 0)
+                return refusal;
+            recordAttemptedUrls(usageTracker, read);
             const data = await callTavily("extract", {
-                urls,
+                urls: read,
                 extract_depth: options.extractDepth,
                 format,
                 // `query` switches the API from whole-document extraction to
@@ -309,10 +376,14 @@ export const buildTavilyTools = (config, options, usageTracker = null) => {
                     .join("\n");
                 rendered += `\n\n---\n\nFailed to extract:\n${lines}`;
             }
+            if (refusal)
+                rendered += `\n\n---\n\n${refusal}`;
             return rendered;
         }, {
             name: "web_extract",
-            description: "Read the content of specific URLs. Pass a query to get back only the passages relevant to it — much cheaper and usually sufficient. Omit the query to retrieve the whole document, which is appropriate when you need its full structure. Long documents are truncated, and the result says so when that happens.",
+            description: `Read the content of specific URLs. Pass a query to get back only the passages relevant to it — much cheaper and usually sufficient. Omit the query to retrieve the whole document, which is appropriate when you need its full structure. Long documents are truncated, and the result says so when that happens.${allowed
+                ? " Only the referenced pages can be read; any other URL is refused."
+                : ""}`,
             schema: z.object({
                 urls: z
                     .array(z.string())
@@ -390,8 +461,6 @@ export const buildTavilyTools = (config, options, usageTracker = null) => {
 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 {

package/package.json

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