@stackfactor/agent-utils 1.10.0 → 1.12.0

package/README.md

@@ -392,6 +392,7 @@ const result = await langChain.runPromptWithModel(
 | `excludeDomains`  | —                        | Exclude these domains from `web_search`                                                       |
 | `crawlLimit`      | `10`                     | Maximum pages one `web_crawl` or `web_map` call may return                                    |
 | `format`          | `"markdown"`             | `"markdown"` preserves table and heading structure at fewer tokens than the prose equivalent  |
+| `allowedUrls`     | —                        | The only URLs `web_extract` may read; any other gets an error line in the tool result and is never sent to Tavily |
 
 ### Context management
 
@@ -416,6 +417,7 @@ A model that cannot tell it received half a regulation will reason over the half
 - Works with every supported provider.
 - Credits come from each response's own `usage` block rather than an estimate. They are reported to the platform as `credits` of the model `tavily` (see [Usage](#usage)) and counted on `usageTracker.tokens.tavilyCredits`.
 - URLs are collected on `usageTracker.webSearchSources`, deduplicated across the whole run — Tavily's terms require citing the original sources when its content is shown to end users.
+- Every URL `web_extract` asked Tavily for is on `usageTracker.attemptedUrls`, each once, whether Tavily could read it or not; a URL `allowedUrls` refused was never asked for and is not there. `webSearchSources` holds what Tavily answered, under the address it answered with; `attemptedUrls` is what the run tried to read, so a caller can check a model's claim that it read a page.
 - Per-URL failures are surfaced in the tool result instead of being dropped, so a fetch failure is not mistaken for an absence of content.
 - Tool calls honour the caller's abort signal, so a cancelled run stops paying for in-flight crawls.
 
@@ -436,6 +438,28 @@ const kept = references.filter((r) => !r.url || live.has(r.url));
 
 ---
 
+## Reading references (`referenceContext`)
+
+An agent reading a skill's (or a microskill's, a question's) references gathers what they point at once, with `referenceContext.gatherReferenceContext({ references, queries, search, token, topK?, maxPassages?, maxPages? })`:
+
+- **pages**: WEB and PUBLICATION references with an http(s) url, each `{ id: "r<N>", title, url }`, opened by the model through Tavily `extract`. All of them by default; `maxPages` keeps the first N in reference order.
+- **passages**: the passages of the knowledge base documents STACKFACTOR references cite, searched under the run's token (client-api `knowledgeBaseAgent.search`). A passage names the references citing its chunk (`knowledgeBase.chunkId`); when none does, every reference citing its document. The best-ranked 40 are kept (`maxPassages`).
+
+**A cited knowledge base that cannot be read stops the run.** With no token, or when the person may not open a cited knowledge base (401, 403, 404) or its search fails, it throws `KnowledgeAccessError` (exported from the package and from `referenceContext`). A search that fails for any reason other than access is tried once more, 200 ms later, before it counts as failed; a refusal is not asked again.
+
+| Field       | Value                                                                                        |
+| ----------- | -------------------------------------------------------------------------------------------- |
+| `code`      | `403` when every skipped knowledge base refused the person (or there was no token), else `502` |
+| `documents` | The titles of the STACKFACTOR references citing those knowledge bases, each once              |
+| `skipped`   | The knowledge bases that could not be searched, and why                                       |
+| `message`   | `The knowledge base documents this content cites could not be read with your access: "A", "B".` (502: `…could not be read: the knowledge base search failed for "A".`) |
+
+The agent answers with `code` and `message`, so the person sees which documents could not be read. An agent that does not catch it answers the same: `serve` and `runOnce` turn an uncaught `KnowledgeAccessError` (known by its `name`, so a second copy of this package counts too) into an error with its own `code` and `message`, not a 500. A search that works and finds nothing is not an error: the run gets no passages and the `none` guidance. Grounding from skill coverage (`stackfactorKnowledge.retrievePassages`) still skips a knowledge base it cannot read.
+
+`referenceContext.toolsFor(context)` gives the run its tools: `{ tavily: { tools: ["extract"], allowedUrls } }` when there are pages (their urls), else `{}`. Spread it after `tavily: undefined`, so `web_extract` reads only the referenced pages.
+
+---
+
 ## Supported Models
 
 ### Text / Chat

package/dist/cjs/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/cjs/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,SAAS,MAAM,YAAY,CAAC;AACnC,OAAO,aAAa,EAAE,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,SAAS,MAAM,gBAAgB,CAAC;AACvC,OAAO,MAAM,MAAM,aAAa,CAAC;AACjC,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC/E,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,cAAc,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;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/cjs/index.js

@@ -36,7 +36,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.stackfactorKnowledge = exports.USAGE_UNITS = exports.recordUsage = exports.runtimeContext = exports.checkAgent = exports.callAgent = exports.EXECUTION_ENV = exports.isRunOnceExecution = exports.runOnce = exports.serve = exports.logger = exports.checkUrlsReachable = exports.langChain = exports.AppError = exports.errorHandling = exports.constants = void 0;
+exports.KnowledgeAccessError = exports.referenceContext = exports.stackfactorKnowledge = exports.USAGE_UNITS = exports.recordUsage = exports.runtimeContext = exports.checkAgent = exports.callAgent = exports.EXECUTION_ENV = exports.isRunOnceExecution = exports.runOnce = exports.serve = exports.logger = exports.checkUrlsReachable = exports.langChain = exports.AppError = exports.errorHandling = exports.constants = void 0;
 const const_js_1 = __importDefault(require("./const.js"));
 exports.constants = const_js_1.default;
 const errorHandling_js_1 = __importStar(require("./errorHandling.js"));
@@ -61,5 +61,8 @@ Object.defineProperty(exports, "recordUsage", { enumerable: true, get: function
 Object.defineProperty(exports, "USAGE_UNITS", { enumerable: true, get: function () { return usage_js_1.USAGE_UNITS; } });
 const stackfactorKnowledge_js_1 = __importDefault(require("./stackfactorKnowledge.js"));
 exports.stackfactorKnowledge = stackfactorKnowledge_js_1.default;
+const referenceContext_js_1 = __importStar(require("./referenceContext.js"));
+exports.referenceContext = referenceContext_js_1.default;
+Object.defineProperty(exports, "KnowledgeAccessError", { enumerable: true, get: function () { return referenceContext_js_1.KnowledgeAccessError; } });
 const tavily_js_1 = require("./tavily.js");
 Object.defineProperty(exports, "checkUrlsReachable", { enumerable: true, get: function () { return tavily_js_1.checkUrlsReachable; } });

package/dist/cjs/langChain.d.ts

@@ -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/cjs/langChain.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"langChain.d.ts","sourceRoot":"","sources":["../../src/langChain.ts"],"names":[],"mappings":"AAoGA,KAAK,UAAU,GAAG;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IAKtB,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE;QAAE,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IACvC;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACtD,CAAC;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/cjs/langChain.js

@@ -1210,8 +1210,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/cjs/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/cjs/referenceContext.d.ts.map

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