@stackfactor/agent-utils 1.10.0 → 1.11.0

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 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 };
 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,MAAM,uBAAuB,CAAC;AACrD,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,CAAC;AAElD,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.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,7 @@ 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 = __importDefault(require("./referenceContext.js"));
+exports.referenceContext = referenceContext_js_1.default;
 const tavily_js_1 = require("./tavily.js");
 Object.defineProperty(exports, "checkUrlsReachable", { enumerable: true, get: function () { return tavily_js_1.checkUrlsReachable; } });

package/dist/cjs/referenceContext.d.ts

@@ -0,0 +1,191 @@
+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 every STACKFACTOR reference that cites this passage's 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[];
+    skipped: SkippedSource[];
+    /** True when the references cite at least one knowledge base document, whether or not it could be read. */
+    citesKnowledge: boolean;
+}
+/**
+ * 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.
+ * @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 }`
+ */
+export declare const gatherReferenceContext: (options: {
+    references: unknown;
+    queries: string[];
+    search: KnowledgeSearch;
+    token: string | null | undefined;
+    topK?: 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, and only when
+ * there are pages to open.
+ * @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.
+ */
+export declare const toolsFor: (context: ReferenceContext) => {
+    tavily?: {
+        tools: string[];
+    };
+};
+/**
+ * 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.
+ * @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: {
+    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;
+    }) => 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[];
+        };
+    };
+};
+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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"}

package/dist/cjs/referenceContext.js

@@ -0,0 +1,299 @@
+"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.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 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;
+/** 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() : "");
+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 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. */
+const citersByDocument = (references) => {
+    const citers = new Map();
+    references.forEach((reference, index) => {
+        if (reference?.kind !== stackfactorKnowledge_js_1.STACKFACTOR_REFERENCE.KIND)
+            return;
+        const documentId = documentOf(reference);
+        if (documentId)
+            citers.set(documentId, [...(citers.get(documentId) ?? []), shortId(index)]);
+    });
+    return citers;
+};
+/**
+ * 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.
+ * @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 }`
+ */
+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);
+    if (!options.token || !citesKnowledge) {
+        logContext(pages.length, 0, [], citesKnowledge && !options.token);
+        return { citesKnowledge, pages, passages: [], skipped: [] };
+    }
+    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,
+    });
+    const citers = citersByDocument(references);
+    const passages = found.passages
+        .filter((passage) => citers.has(passage.documentId))
+        .map((passage) => ({
+        chunkId: passage.chunkId,
+        document: passage.documentName,
+        documentId: passage.documentId,
+        knowledgeBaseId: passage.knowledgeBaseId,
+        references: citers.get(passage.documentId),
+        section: passage.sectionTitle,
+        text: passage.text,
+    }));
+    logContext(pages.length, passages.length, found.skipped, false);
+    return { citesKnowledge, pages, passages, skipped: found.skipped };
+};
+exports.gatherReferenceContext = gatherReferenceContext;
+/** The one summary line of a gathering, for the logs. */
+const logContext = (pages, passages, skipped, noToken) => {
+    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_js_1.default.log(null, 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, and only when
+ * there are pages to open.
+ * @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.
+ */
+const toolsFor = (context) => context.pages.length > 0 ? { tavily: { tools: ["extract"] } } : {};
+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, 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 = {
+    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/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 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 };
 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,MAAM,uBAAuB,CAAC;AACrD,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,CAAC;AAElD,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 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 };

package/dist/esm/referenceContext.d.ts

@@ -0,0 +1,191 @@
+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 every STACKFACTOR reference that cites this passage's 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[];
+    skipped: SkippedSource[];
+    /** True when the references cite at least one knowledge base document, whether or not it could be read. */
+    citesKnowledge: boolean;
+}
+/**
+ * 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.
+ * @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 }`
+ */
+export declare const gatherReferenceContext: (options: {
+    references: unknown;
+    queries: string[];
+    search: KnowledgeSearch;
+    token: string | null | undefined;
+    topK?: 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, and only when
+ * there are pages to open.
+ * @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.
+ */
+export declare const toolsFor: (context: ReferenceContext) => {
+    tavily?: {
+        tools: string[];
+    };
+};
+/**
+ * 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.
+ * @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: {
+    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;
+    }) => 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[];
+        };
+    };
+};
+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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"}

package/dist/esm/referenceContext.js

@@ -0,0 +1,284 @@
+//
+// 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 reference is cited by its short id `r<N>`, N being its index in the
+// supplied list, whatever its kind.
+//
+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;
+/** 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() : "");
+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 === STACKFACTOR_REFERENCE.TARGET_ELEMENT_TYPE ? id(target.elementId) : ""));
+};
+/** 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. */
+const citersByDocument = (references) => {
+    const citers = 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)]);
+    });
+    return citers;
+};
+/**
+ * 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.
+ * @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 }`
+ */
+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);
+        return { citesKnowledge, pages, passages: [], skipped: [] };
+    }
+    const found = await retrievePassages({
+        queries: options.queries,
+        search: options.search,
+        sources,
+        token: options.token,
+        topK: options.topK ?? DEFAULT_REFERENCE_TOP_K,
+    });
+    const citers = citersByDocument(references);
+    const passages = found.passages
+        .filter((passage) => citers.has(passage.documentId))
+        .map((passage) => ({
+        chunkId: passage.chunkId,
+        document: passage.documentName,
+        documentId: passage.documentId,
+        knowledgeBaseId: passage.knowledgeBaseId,
+        references: citers.get(passage.documentId),
+        section: passage.sectionTitle,
+        text: passage.text,
+    }));
+    logContext(pages.length, passages.length, found.skipped, false);
+    return { citesKnowledge, pages, passages, skipped: found.skipped };
+};
+/** The one summary line of a gathering, for the logs. */
+const logContext = (pages, passages, skipped, noToken) => {
+    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("; ")}`);
+};
+/**
+ * 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 const referencePassagesForPrompt = (context) => context.passages.map((passage) => ({
+    document: passage.document,
+    references: passage.references,
+    section: passage.section,
+    text: passage.text,
+}));
+/**
+ * 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.
+ * @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.
+ */
+export const toolsFor = (context) => context.pages.length > 0 ? { tavily: { tools: ["extract"] } } : {};
+/**
+ * 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.
+ * @param stagePrompt The stage's own prompt
+ * @param context From `gatherReferenceContext`
+ * @param guidance From `sourceGuidanceFrom`
+ * @returns The sections joined with a blank line
+ */
+export 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");
+};
+/**
+ * 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 const referenceForModel = (reference) => {
+    if (reference?.kind !== STACKFACTOR_REFERENCE.KIND)
+        return reference;
+    const { _id: _i, origin: _o, visibility: _v, target: _target, knowledgeBase: _knowledgeBase, url: _url, ...rest } = reference;
+    return rest;
+};
+/**
+ * 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 const referencesForModel = (references) => {
+    const shown = [];
+    (Array.isArray(references) ? references : []).forEach((reference, index) => {
+        if (!reference || typeof reference !== "object")
+            return;
+        const { _id: _ignored, ...rest } = referenceForModel(reference);
+        shown.push({ ...rest, _id: shortId(index) });
+    });
+    return shown;
+};
+/** What a STACKFACTOR reference points at, as the platform stores it. */
+const stackfactorPointers = (reference) => {
+    if (reference.kind !== STACKFACTOR_REFERENCE.KIND)
+        return {};
+    const pointer = reference.knowledgeBase;
+    if (pointer?.knowledgeBaseId && pointer?.documentId) {
+        return {
+            knowledgeBase: { ...pointer },
+            target: {
+                elementType: 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"`
+ */
+export 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,
+    };
+};
+/**
+ * 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 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(toStoredReference(list[index], origin));
+    }
+    return cited;
+};
+/**
+ * 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 const sourceGuidanceFrom = (config) => ({
+    pages: text(config?.referencedPagesGuidance),
+    passages: text(config?.knowledgeBasePassagesGuidance),
+    none: text(config?.noReferencesGuidance),
+});
+export default {
+    REFERENCE_PASSAGES_KEY,
+    citedReferences,
+    composeSourceInstructions,
+    gatherReferenceContext,
+    referenceForModel,
+    referencePassagesForPrompt,
+    referencesForModel,
+    sourceGuidanceFrom,
+    toStoredReference,
+    toolsFor,
+};

package/package.json

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