@stackfactor/agent-utils 1.10.0 → 1.12.0

package/dist/cjs/referenceContext.js

@@ -0,0 +1,399 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sourceGuidanceFrom = exports.citedReferences = exports.toStoredReference = exports.referencesForModel = exports.referenceForModel = exports.composeSourceInstructions = exports.toolsFor = exports.referencePassagesForPrompt = exports.gatherReferenceContext = exports.KnowledgeAccessError = exports.REFERENCE_PASSAGES_KEY = void 0;
+//
+// Reference context — gathering what a list of references points at
+//
+// An agent that reads its references never discovers new sources. It reads
+// what they point at:
+//
+//   - pages: WEB and PUBLICATION references with an http(s) url, which the
+//     agent opens through Tavily `extract`. A STACKFACTOR reference's url is
+//     the document's page at its source and is never opened as a page;
+//   - passages: the passages of the knowledge base documents STACKFACTOR
+//     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.
+//
+const logger_js_1 = __importDefault(require("./logger.js"));
+const stackfactorKnowledge_js_1 = require("./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. */
+exports.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.
+ */
+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);
+    }
+}
+exports.KnowledgeAccessError = KnowledgeAccessError;
+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. */
+const documentOf = (reference) => {
+    const target = reference.target ?? {};
+    return (id(reference.knowledgeBase?.documentId) ||
+        (target.elementType === stackfactorKnowledge_js_1.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 === stackfactorKnowledge_js_1.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. */
+const resolveKind = (reference) => {
+    const kind = reference?.kind;
+    return typeof kind !== "string" || kind === "" || RETIRED_KINDS.has(kind) ? "PUBLICATION" : kind;
+};
+/** The pages among the references, each url once, under the first reference that has it. */
+const pagesOf = (references) => {
+    const pages = [];
+    const seen = new Set();
+    references.forEach((reference, index) => {
+        if (!reference || typeof reference !== "object")
+            return;
+        const kind = resolveKind(reference);
+        if (kind !== "WEB" && kind !== "PUBLICATION")
+            return;
+        const url = text(reference.url);
+        if (!/^https?:\/\//i.test(url) || seen.has(url))
+            return;
+        seen.add(url);
+        pages.push({ id: shortId(index), title: text(reference.title) || url, url });
+    });
+    return pages;
+};
+/**
+ * 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 !== stackfactorKnowledge_js_1.STACKFACTOR_REFERENCE.KIND)
+            return;
+        const documentId = documentOf(reference);
+        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 { 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 === stackfactorKnowledge_js_1.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.
+ *
+ * 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), `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
+ */
+const gatherReferenceContext = async (options) => {
+    const references = Array.isArray(options.references) ? options.references : [];
+    const sources = (0, stackfactorKnowledge_js_1.sourcesFromReferences)(references);
+    const citesKnowledge = sources.length > 0;
+    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 (0, stackfactorKnowledge_js_1.retrievePassages)({
+        queries: options.queries,
+        search: options.search,
+        sources,
+        token: options.token,
+        topK: options.topK ?? DEFAULT_REFERENCE_TOP_K,
+    });
+    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.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.byChunk.get(passage.chunkId) ?? citers.byDocument.get(passage.documentId),
+        section: passage.sectionTitle,
+        text: passage.text,
+    }));
+    logContext(pages.length, passages.length, []);
+    return { citesKnowledge, pages, passages, skipped: [] };
+};
+exports.gatherReferenceContext = gatherReferenceContext;
+/**
+ * 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 (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_js_1.default.log(null, refusal ? logger_js_1.default.levels.warn : logger_js_1.default.levels.info, `Reference context: ${parts.join("; ")}`);
+};
+/**
+ * The passages as a prompt shows them: who cites each, where it came from, and
+ * its text. The ids that locate it in the platform are left out.
+ * @param context From `gatherReferenceContext`
+ * @returns `[{ references, document, section, text }]`, for the model's input
+ */
+const referencePassagesForPrompt = (context) => context.passages.map((passage) => ({
+    document: passage.document,
+    references: passage.references,
+    section: passage.section,
+    text: passage.text,
+}));
+exports.referencePassagesForPrompt = referencePassagesForPrompt;
+/**
+ * The tools a run is given. Never `search`, `map` or `crawl`: a run reads what
+ * 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"], 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.
+ */
+const toolsFor = (context) => context.pages.length > 0
+    ? { tavily: { tools: ["extract"], allowedUrls: context.pages.map((page) => page.url) } }
+    : {};
+exports.toolsFor = toolsFor;
+/**
+ * The stage prompt followed by the guidance for each kind of source the run
+ * 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`
+ * @returns The sections joined with a blank line
+ */
+const composeSourceInstructions = (stagePrompt, context, guidance) => {
+    const sections = [];
+    if (context.pages.length > 0)
+        sections.push(guidance.pages);
+    if (context.passages.length > 0)
+        sections.push(guidance.passages);
+    if (sections.length === 0)
+        sections.push(guidance.none);
+    return [stagePrompt, ...sections].filter(Boolean).join("\n\n");
+};
+exports.composeSourceInstructions = composeSourceInstructions;
+/**
+ * A reference as a model is shown it. A STACKFACTOR reference loses its pointer
+ * and its url (ids mean nothing to a model, and the url is behind the
+ * organization's own sign-in); the model cites it by short id.
+ * @param reference A supplied reference
+ * @returns The reference; a STACKFACTOR one without `_id`, `origin`, `visibility`,
+ *   `target`, `knowledgeBase` and `url`
+ */
+const referenceForModel = (reference) => {
+    if (reference?.kind !== stackfactorKnowledge_js_1.STACKFACTOR_REFERENCE.KIND)
+        return reference;
+    const { _id: _i, origin: _o, visibility: _v, target: _target, knowledgeBase: _knowledgeBase, url: _url, ...rest } = reference;
+    return rest;
+};
+exports.referenceForModel = referenceForModel;
+/**
+ * The supplied references as a model is shown them, each under its short id
+ * `r<N>` (N the index in the supplied list) as `_id`, set last so a stored
+ * reference's own id never wins. Non-object entries are skipped but keep their
+ * index, so the ids stay aligned with `citedReferences`.
+ * @param references The supplied list
+ */
+const referencesForModel = (references) => {
+    const shown = [];
+    (Array.isArray(references) ? references : []).forEach((reference, index) => {
+        if (!reference || typeof reference !== "object")
+            return;
+        const { _id: _ignored, ...rest } = (0, exports.referenceForModel)(reference);
+        shown.push({ ...rest, _id: shortId(index) });
+    });
+    return shown;
+};
+exports.referencesForModel = referencesForModel;
+/** What a STACKFACTOR reference points at, as the platform stores it. */
+const stackfactorPointers = (reference) => {
+    if (reference.kind !== stackfactorKnowledge_js_1.STACKFACTOR_REFERENCE.KIND)
+        return {};
+    const pointer = reference.knowledgeBase;
+    if (pointer?.knowledgeBaseId && pointer?.documentId) {
+        return {
+            knowledgeBase: { ...pointer },
+            target: {
+                elementType: stackfactorKnowledge_js_1.STACKFACTOR_REFERENCE.TARGET_ELEMENT_TYPE,
+                elementId: pointer.documentId,
+                parentId: pointer.knowledgeBaseId,
+            },
+        };
+    }
+    return reference.target?.elementType && reference.target?.elementId ? { target: { ...reference.target } } : {};
+};
+/**
+ * A reference from the flat projection the host sends (or the flat shape a
+ * model emits) in the shape the platform stores: nested `publication`,
+ * `relatedTo` folded into `description`, a STACKFACTOR reference's pointer and
+ * target kept. `visibility` is never set; the caller decides it.
+ * @param reference The flat reference
+ * @param origin Default `"AI_GENERATED"`
+ */
+const toStoredReference = (reference, origin = "AI_GENERATED") => {
+    const publication = {
+        ...(reference.author ? { author: reference.author } : {}),
+        ...(reference.publisher ? { publisher: reference.publisher } : {}),
+        ...(reference.identifier ? { identifier: reference.identifier } : {}),
+        ...(reference.locator ? { locator: reference.locator } : {}),
+        ...(reference.publication || {}),
+    };
+    const description = [reference.description, reference.relatedTo ? `Related to: ${reference.relatedTo}` : null]
+        .filter(Boolean)
+        .join(" \u2014 ");
+    return {
+        kind: reference.kind,
+        title: reference.title,
+        ...(description ? { description } : {}),
+        ...(reference.url ? { url: reference.url } : {}),
+        ...(Object.keys(publication).length > 0 ? { publication } : {}),
+        ...stackfactorPointers(reference),
+        origin,
+    };
+};
+exports.toStoredReference = toStoredReference;
+/**
+ * The supplied references a model cited by short id, stored. Ids are matched
+ * trimmed and case-insensitively; unknown and non-string ids are dropped and
+ * each reference appears once, at its first citation.
+ * @param ids The model's cited ids (`["r0", "r3"]`)
+ * @param supplied The list the ids index into
+ * @param origin Default `"AI_GENERATED"`
+ */
+const citedReferences = (ids, supplied, origin) => {
+    const list = Array.isArray(supplied) ? supplied : [];
+    const taken = new Set();
+    const cited = [];
+    for (const raw of Array.isArray(ids) ? ids : []) {
+        const match = typeof raw === "string" ? /^r(\d+)$/.exec(raw.trim().toLowerCase()) : null;
+        const index = match ? Number(match[1]) : -1;
+        if (!list[index] || typeof list[index] !== "object" || taken.has(index))
+            continue;
+        taken.add(index);
+        cited.push((0, exports.toStoredReference)(list[index], origin));
+    }
+    return cited;
+};
+exports.citedReferences = citedReferences;
+/**
+ * The three guidance texts an agent's config holds. A missing or non-string
+ * value is an empty string.
+ * @param config The agent's config
+ */
+const sourceGuidanceFrom = (config) => ({
+    pages: text(config?.referencedPagesGuidance),
+    passages: text(config?.knowledgeBasePassagesGuidance),
+    none: text(config?.noReferencesGuidance),
+});
+exports.sourceGuidanceFrom = sourceGuidanceFrom;
+exports.default = {
+    KnowledgeAccessError,
+    REFERENCE_PASSAGES_KEY: exports.REFERENCE_PASSAGES_KEY,
+    citedReferences: exports.citedReferences,
+    composeSourceInstructions: exports.composeSourceInstructions,
+    gatherReferenceContext: exports.gatherReferenceContext,
+    referenceForModel: exports.referenceForModel,
+    referencePassagesForPrompt: exports.referencePassagesForPrompt,
+    referencesForModel: exports.referencesForModel,
+    sourceGuidanceFrom: exports.sourceGuidanceFrom,
+    toStoredReference: exports.toStoredReference,
+    toolsFor: exports.toolsFor,
+};

package/dist/cjs/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/cjs/serve.js

@@ -381,8 +381,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/cjs/stackfactorKnowledge.d.ts

@@ -67,7 +67,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;
 }
@@ -116,9 +119,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)

package/dist/cjs/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":"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"}

package/dist/cjs/stackfactorKnowledge.js

@@ -15,8 +15,11 @@
 //     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
@@ -49,6 +52,8 @@ exports.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);
@@ -130,15 +135,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)
@@ -167,8 +175,24 @@ 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))

package/dist/cjs/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/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;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"}