@stackfactor/agent-utils 1.10.0 → 1.12.0

package/dist/cjs/tavily.js

@@ -60,6 +60,10 @@ const assertTavilyUsable = (config, options) => {
     if (!config?.tavilyAPIKey) {
         throw errorHandling_js_1.default.create(const_js_1.default.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 errorHandling_js_1.default.create(const_js_1.default.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 errorHandling_js_1.default.create(const_js_1.default.HTTP_CODES.BAD_REQUEST, `Unknown Tavily tool(s): ${unknown.join(", ")}. Valid values are search, extract, crawl, map.`);
@@ -168,6 +172,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.
@@ -238,6 +288,9 @@ 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,
@@ -285,8 +338,22 @@ const buildTavilyTools = (config, options, usageTracker = null) => {
     }
     if (enabled.includes("extract")) {
         tools.push((0, langchain_1.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_js_1.default.log(null, logger_js_1.default.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
@@ -317,10 +384,14 @@ 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: zod_1.z.object({
                 urls: zod_1.z
                     .array(zod_1.z.string())
@@ -399,8 +470,6 @@ exports.buildTavilyTools = buildTavilyTools;
 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/dist/esm/index.d.ts

@@ -7,6 +7,7 @@ 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 referenceContext, { KnowledgeAccessError } from "./referenceContext.js";
 import { checkUrlsReachable } from "./tavily.js";
 export { constants };
 export { errorHandling, AppError };
@@ -23,6 +24,7 @@ export type { AgentExecuteRequest, CallAgentOptions, CheckAgentOptions, AgentHea
 export { runtimeContext };
 export { recordUsage, USAGE_UNITS };
 export type { UsageEntry, UsageUnit } from "./usage.js";
-export { stackfactorKnowledge };
+export { stackfactorKnowledge, referenceContext, KnowledgeAccessError };
 export type { GroundingPassage, KnowledgeChunk, KnowledgeSearch, KnowledgeSource, SkippedSource, StackFactorReference, } from "./stackfactorKnowledge.js";
+export type { ReferenceContext, ReferencePage, ReferencePassage, SourceGuidance, StoredReference, } from "./referenceContext.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;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"}
+{"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,gBAAgB,EAAE,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAC/E,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,gBAAgB,EAAE,oBAAoB,EAAE,CAAC;AAExE,YAAY,EACV,gBAAgB,EAChB,cAAc,EACd,eAAe,EACf,eAAe,EACf,aAAa,EACb,oBAAoB,GACrB,MAAM,2BAA2B,CAAC;AAEnC,YAAY,EACV,gBAAgB,EAChB,aAAa,EACb,gBAAgB,EAChB,cAAc,EACd,eAAe,GAChB,MAAM,uBAAuB,CAAC"}

package/dist/esm/index.js

@@ -7,6 +7,7 @@ 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 referenceContext, { KnowledgeAccessError } from "./referenceContext.js";
 import { checkUrlsReachable } from "./tavily.js";
 export { constants };
 export { errorHandling, AppError };
@@ -18,4 +19,4 @@ export { callAgent };
 export { checkAgent };
 export { runtimeContext };
 export { recordUsage, USAGE_UNITS };
-export { stackfactorKnowledge };
+export { stackfactorKnowledge, referenceContext, KnowledgeAccessError };

package/dist/esm/langChain.d.ts

@@ -31,6 +31,14 @@ export type UsageTracker = {
         url: string;
         title?: string;
     }[];
+    /**
+     * Every URL `web_extract` asked Tavily for, each once, in the order first
+     * asked, whether Tavily could read it or not (a failed URL, a failed call).
+     * A URL refused by `allowedUrls` was never asked for and is not here. What
+     * Tavily answered is `webSearchSources`, under the address it answered with
+     * (after a redirect); this is what the run actually tried to read.
+     */
+    attemptedUrls?: string[];
 };
 /**
  * Instantiates and returns the appropriate LangChain chat model based on the model

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;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"}
+{"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;IACrD;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B,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;sCA5xC9B,MAAM,KAAG,OAAO;0CAuGZ,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;oCAihBF,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;0CAz6C8B,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;;AA48CT,wBAkBE"}

package/dist/esm/langChain.js

@@ -1203,8 +1203,9 @@ const parseAgenticJsonResponse = (rawContent, schema) => {
  *
  * Setting `config.tavily` adds the Tavily web tools (`web_search`, `web_extract`, and
  * optionally `web_map` / `web_crawl`). They execute in this process, so they require
- * `config.agentic` to be `true`; the credits spent and the URLs returned are recorded
- * on `usageTracker`.
+ * `config.agentic` to be `true`; the credits spent, the URLs returned and the URLs
+ * `web_extract` asked for are recorded on `usageTracker`. `tavily.allowedUrls` keeps
+ * `web_extract` to those URLs.
  * @param modelName - The model identifier, e.g. `"gpt-4o"`, `"claude-3-5-sonnet"`,
  *   `"gemini-1.5-pro"`
  * @param config - Configuration object with API keys, `temperature`, optional `agentic`

package/dist/esm/referenceContext.d.ts

@@ -0,0 +1,238 @@
+import { KnowledgeSearch, SkippedSource } from "./stackfactorKnowledge.js";
+/** The prompt key the passages are handed to the model under. */
+export declare const REFERENCE_PASSAGES_KEY = "Knowledge Base Passages";
+/** A web or publication page a reference points at. */
+export interface ReferencePage {
+    /** The reference's short id, "r0"… */
+    id: string;
+    title: string;
+    url: string;
+}
+/** A passage of a document that references cite. */
+export interface ReferencePassage {
+    /**
+     * The short ids of the STACKFACTOR references that cite this passage's chunk
+     * (`knowledgeBase.chunkId`); when none does, of every one citing its document.
+     */
+    references: string[];
+    document: string | null;
+    section: string | null;
+    text: string;
+    chunkId: string;
+    documentId: string;
+    knowledgeBaseId: string;
+}
+/** What a list of references points at. */
+export interface ReferenceContext {
+    pages: ReferencePage[];
+    passages: ReferencePassage[];
+    /**
+     * Always empty from `gatherReferenceContext`: a cited knowledge base that
+     * cannot be read throws KnowledgeAccessError, which carries the skips.
+     */
+    skipped: SkippedSource[];
+    /** True when the references cite at least one knowledge base document (all of them readable, or it would have thrown). */
+    citesKnowledge: boolean;
+}
+/**
+ * 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 declare class KnowledgeAccessError extends Error {
+    /** 403 when every skipped knowledge base refused the person (or there was no token), else 502. */
+    readonly code: 403 | 502;
+    /** The knowledge bases that could not be searched, and why; empty when there was no token. */
+    readonly skipped: SkippedSource[];
+    /** The titles of the STACKFACTOR references citing those knowledge bases, each once. */
+    readonly documents: string[];
+    /**
+     * @param details `skipped` (from the search) and `documents` (titles); the
+     *   code and the message follow from them
+     */
+    constructor(details?: {
+        skipped?: SkippedSource[];
+        documents?: unknown[];
+    });
+}
+/**
+ * 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
+ */
+export declare const gatherReferenceContext: (options: {
+    references: unknown;
+    queries: string[];
+    search: KnowledgeSearch;
+    token: string | null | undefined;
+    topK?: number;
+    maxPassages?: number;
+    maxPages?: number;
+}) => Promise<ReferenceContext>;
+/**
+ * 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
+ */
+export declare const referencePassagesForPrompt: (context: ReferenceContext) => {
+    references: string[];
+    document: string | null;
+    section: string | null;
+    text: string;
+}[];
+/** The guidance an agent's config gives for each kind of source it may be handed. */
+export interface SourceGuidance {
+    pages: string;
+    passages: string;
+    none: string;
+}
+/** A reference as the platform stores it. `visibility` is left to the caller. */
+export interface StoredReference {
+    kind: string;
+    title: string;
+    description?: string;
+    url?: string;
+    publication?: {
+        author?: string;
+        publisher?: string;
+        identifier?: string;
+        locator?: string;
+    };
+    origin: string;
+    visibility?: string;
+    target?: {
+        elementType: string;
+        elementId: string;
+        parentId?: string;
+    };
+    knowledgeBase?: {
+        knowledgeBaseId: string;
+        documentId: string;
+        chunkId?: string;
+        sectionTitle?: string | null;
+    };
+}
+/**
+ * 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.
+ */
+export declare const toolsFor: (context: ReferenceContext) => {
+    tavily?: {
+        tools: string[];
+        allowedUrls: string[];
+    };
+};
+/**
+ * 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
+ */
+export declare const composeSourceInstructions: (stagePrompt: string, context: ReferenceContext, guidance: SourceGuidance) => string;
+/**
+ * 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`
+ */
+export declare const referenceForModel: <T extends {
+    kind?: string;
+}>(reference: T) => T;
+/**
+ * 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
+ */
+export declare const referencesForModel: (references: unknown) => Array<Record<string, unknown>>;
+/**
+ * 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"`
+ */
+export declare const toStoredReference: (reference: any, origin?: string) => StoredReference;
+/**
+ * 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"`
+ */
+export declare const citedReferences: (ids: unknown, supplied: unknown, origin?: string) => StoredReference[];
+/**
+ * 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
+ */
+export declare const sourceGuidanceFrom: (config: Record<string, unknown>) => SourceGuidance;
+declare const _default: {
+    KnowledgeAccessError: typeof KnowledgeAccessError;
+    REFERENCE_PASSAGES_KEY: string;
+    citedReferences: (ids: unknown, supplied: unknown, origin?: string) => StoredReference[];
+    composeSourceInstructions: (stagePrompt: string, context: ReferenceContext, guidance: SourceGuidance) => string;
+    gatherReferenceContext: (options: {
+        references: unknown;
+        queries: string[];
+        search: KnowledgeSearch;
+        token: string | null | undefined;
+        topK?: number;
+        maxPassages?: number;
+        maxPages?: number;
+    }) => Promise<ReferenceContext>;
+    referenceForModel: <T extends {
+        kind?: string;
+    }>(reference: T) => T;
+    referencePassagesForPrompt: (context: ReferenceContext) => {
+        references: string[];
+        document: string | null;
+        section: string | null;
+        text: string;
+    }[];
+    referencesForModel: (references: unknown) => Array<Record<string, unknown>>;
+    sourceGuidanceFrom: (config: Record<string, unknown>) => SourceGuidance;
+    toStoredReference: (reference: any, origin?: string) => StoredReference;
+    toolsFor: (context: ReferenceContext) => {
+        tavily?: {
+            tools: string[];
+            allowedUrls: string[];
+        };
+    };
+};
+export default _default;
+//# sourceMappingURL=referenceContext.d.ts.map

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

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