@retinue/agentkit 0.1.0 → 0.2.0

package/dist/knowledge/navigate.js

@@ -0,0 +1,107 @@
+/**
+ * Retrieval without vectors — REQ-050 (#209), task #219, AC-4.
+ *
+ * A **spike**, and the deliverable is a decision with numbers rather than a subsystem. See
+ * `docs/26-retrieval-quality.md` for what it scored.
+ *
+ * ## The idea being tested
+ *
+ * Embedding-based retrieval matches a query against fragments of text and hopes the fragments it surfaces are the
+ * ones that answer it. A person looking something up in a manual does something else entirely: they read the
+ * table of contents, decide which chapter is relevant, and then read it. That needs no index, no embedding cost
+ * and no re-indexing when a document changes — and its citations name a *document* somebody chose rather than a
+ * fragment a cosine distance surfaced.
+ *
+ * The cost is a model call per query, and latency measured in seconds rather than milliseconds.
+ *
+ * ## Two things this prototype found immediately
+ *
+ * **`KnowledgeStore` cannot enumerate its sources.** There is `listBySource`, `get`, `deleteSource` and
+ * `staleSources`, and no way to ask "what documents are in here". That is correct for a vector-based design —
+ * nothing needed it — and it is exactly what a navigating retriever needs first. So the outline arrives through
+ * a port the *host* supplies (`OutlineCatalogue`), which is honest but means this mode is not a drop-in for a
+ * deployment that already has hybrid retrieval working.
+ *
+ * **It does fit behind `RetrievalMode`**, which the issue asked to test. `createRetriever` gains one optional
+ * dependency and a fourth mode; every caller — `search_knowledge` included — is unchanged, and a deployment that
+ * has not wired a navigator gets a named refusal rather than a silent fall back to semantic search. If it had
+ * *not* fit, that would have been the finding; it fits.
+ */
+export const DEFAULT_MAX_SOURCES = 3;
+export const DEFAULT_MAX_CHUNKS_PER_SOURCE = 40;
+const reference = (chunk) => ({
+    sourceType: chunk.sourceType,
+    sourceId: chunk.sourceId,
+    chunkIndex: chunk.chunkIndex,
+    chunkId: chunk.id,
+    ...(chunk.locator === undefined ? {} : { locator: chunk.locator }),
+});
+/**
+ * Query terms, for ordering chunks *within* the documents the chooser picked.
+ *
+ * Six lines of tokenisation rather than a second ranker: there is no fusion here and no relevance floor, because
+ * the relevance decision was already made — by a model, over titles and headings. What remains is "which part of
+ * this chapter", and term overlap answers that well enough to measure. If the eval had shown this mode worth
+ * shipping, this is the first thing to replace.
+ */
+const terms = (text) => [
+    ...new Set(text.toLowerCase().split(/[^a-z0-9]+/).filter((word) => word.length > 2)),
+];
+export const createNavigator = (deps) => {
+    const maxSources = deps.maxSources ?? DEFAULT_MAX_SOURCES;
+    const maxChunks = deps.maxChunksPerSource ?? DEFAULT_MAX_CHUNKS_PER_SOURCE;
+    return {
+        id: `navigate:${deps.chooser.id}`,
+        async navigate(context, input) {
+            if (input.authSubjects.length === 0)
+                return { found: false, reason: "no-access", message: "There is no material you have access to.", mode: "navigate" };
+            const catalogue = await deps.catalogue.list({ tenantId: context.tenantId, authSubjects: input.authSubjects });
+            if (catalogue.length === 0)
+                return { found: false, reason: "nothing-indexed", message: "There is no indexed material to search yet.", mode: "navigate" };
+            const chosen = await deps.chooser.choose({ query: input.query, catalogue, limit: maxSources });
+            /**
+             * An empty choice is a real answer, and a distinct one.
+             *
+             * A model that has read the table of contents and concluded nothing there is relevant has told you
+             * something a cosine distance cannot: `no-match` rather than the least-bad chapter. This is the mode's most
+             * attractive property and the reason it is worth measuring at all.
+             */
+            if (chosen.length === 0)
+                return { found: false, reason: "no-match", message: "Nothing in the available material covers that.", mode: "navigate" };
+            const known = new Map(catalogue.map((outline) => [outline.sourceId, outline]));
+            const wanted = input.query.toLowerCase();
+            const queryTerms = terms(input.query);
+            const hits = [];
+            for (const sourceId of chosen.slice(0, maxSources)) {
+                const outline = known.get(sourceId);
+                // A chooser naming a document that is not in the catalogue it was given is a chooser that hallucinated
+                // one. Skipped rather than fetched: fetching would be a model choosing which document to read.
+                if (outline === undefined)
+                    continue;
+                const page = await deps.store.listBySource({
+                    tenantId: context.tenantId,
+                    sourceType: outline.sourceType,
+                    sourceId,
+                    limit: maxChunks,
+                });
+                for (const chunk of page.items) {
+                    const content = chunk.content.toLowerCase();
+                    const overlap = queryTerms.filter((term) => content.includes(term)).length;
+                    hits.push({
+                        chunk,
+                        // Not comparable with a fused score, and deliberately so: this number orders chunks inside a chosen
+                        // document and means nothing outside one.
+                        score: queryTerms.length === 0 ? 0 : overlap / queryTerms.length + (content.includes(wanted) ? 1 : 0),
+                        signals: ["navigate"],
+                        reference: reference(chunk),
+                    });
+                }
+            }
+            if (hits.length === 0)
+                return { found: false, reason: "no-match", message: "The chosen documents had no readable content.", mode: "navigate" };
+            const ordered = [...hits].sort((a, b) => b.score !== a.score ? b.score - a.score : a.reference.chunkId.localeCompare(b.reference.chunkId));
+            return { found: true, hits: ordered.slice(0, input.limit), mode: "navigate" };
+        },
+    };
+};
+//# sourceMappingURL=navigate.js.map

package/dist/knowledge/retrieval.d.ts

@@ -14,9 +14,19 @@
  *
  *     score(d) = Σ over signals of 1 / (K + rank(d))
  *
- * A document ranked first by one signal and absent from the other still beats one ranked fifth by both, which
- * is the behaviour that makes hybrid better than either — the exact-term hit surfaces even though the semantic
- * signal never saw it.
+ * A document ranked first by one signal and absent from the other still beats one ranked fifth by both, which is
+ * the behaviour hybrid exists for — the exact-term hit surfaces even though the semantic signal never saw it.
+ *
+ * **And on one real corpus it is worse than semantic alone.** This comment used to say hybrid "measurably beats"
+ * both parts; #219 measured it over 56 documents of technical prose and hybrid lost 11.1 points of success@5 to
+ * semantic-only — two cases out of eighteen. The mechanism is the same paragraph read the other way: RRF weights both signals equally by
+ * construction, so fusing a weak list with a strong one demotes the strong list's top hits wherever the weak one
+ * disagrees. The lexical signal is weak on natural-language questions over prose.
+ *
+ * Hybrid remains the default, deliberately — that dataset has 18 queries, one author, and **no identifier
+ * queries**, which is precisely the case hybrid exists for. But the claim in this comment was untested for months
+ * and turned out to be false where it was finally tested, so it is stated with its evidence now. See
+ * `docs/26-retrieval-quality.md`.
  *
  * **`K = 60`** is the value from Cormack, Clarke and Buettcher's original TREC work and the one every
  * implementation since has used. It is large relative to the ranks that matter, which flattens the difference
@@ -30,6 +40,7 @@
 import type { TenantId } from "../core/ids.js";
 import type { KeywordIndex, KnowledgeChunk, KnowledgeSourceType, VectorIndex } from "../persistence/index.js";
 import type { EmbeddingProvider } from "./index.js";
+import type { Navigator } from "./navigate.js";
 /** The rank-fusion constant. See the note above on why 60 and why rank rather than score. */
 export declare const RRF_K = 60;
 /** How many candidates each signal contributes before fusion. */
@@ -42,7 +53,18 @@ export declare const DEFAULT_CANDIDATES = 20;
  * second-best answer and tight enough to reject a corpus that simply has nothing to say.
  */
 export declare const DEFAULT_RELEVANCE_FLOOR = 0.4;
-export type RetrievalMode = "semantic" | "keyword" | "hybrid";
+/**
+ * `navigate` is a **spike** — REQ-050 (#209), task #219, AC-4.
+ *
+ * The issue asked whether retrieval without vectors can be expressed as a fourth mode behind this interface, and
+ * "if it cannot, that is itself the finding". It can: `createRetriever` gains one optional dependency, and every
+ * caller — `search_knowledge` included — is unchanged. A deployment that has not wired a navigator gets a named
+ * refusal rather than a silent fall back to semantic search, which is the failure that would have made the mode
+ * dangerous rather than merely unused.
+ *
+ * See `navigate.ts` for what it is and `docs/26-retrieval-quality.md` for what it scored.
+ */
+export type RetrievalMode = "semantic" | "keyword" | "hybrid" | "navigate";
 /** What a citation needs, derived from a hit so there is one shape rather than each caller's own (AC-6). */
 export type SourceReference = {
     readonly sourceType: KnowledgeSourceType;
@@ -67,7 +89,7 @@ export type RetrievalHit = {
  * different answer from "you have no indexed documents", and telling a user the first when the second is true
  * sends them looking for content they never uploaded.
  */
-export declare const NO_RESULT_REASONS: readonly ["nothing-indexed", "no-match", "below-threshold", "no-access"];
+export declare const NO_RESULT_REASONS: readonly ["nothing-indexed", "no-match", "below-threshold", "no-access", "not-configured"];
 export type NoResultReason = (typeof NO_RESULT_REASONS)[number];
 export type RetrievalOutcome = {
     readonly found: true;
@@ -85,6 +107,14 @@ export type RetrievalOutcome = {
  * A port, and **switchable**, because a reranker's value is a claim that has to be provable. A cross-encoder is
  * materially more expensive than the retrieval it reorders, so "we rerank" without a measured contribution is
  * a cost nobody justified. Absent means fusion order stands, which is the honest default.
+ *
+ * **`createExactTermReranker`'s measured contribution is negative** — #219, over 56 documents of technical prose:
+ * −5.6 points of success@5, −5.6 of recall, −0.028 MRR, and no latency saving. It promotes chunks containing query
+ * terms verbatim, which on prose queries promotes chunks that happen to repeat a common word. Leave it off.
+ *
+ * That is a result about *that* reranker, not about reranking: a cross-encoder is a different mechanism and might
+ * well earn its cost. This port is how it would be measured, and `docs/26-retrieval-quality.md` is the baseline to
+ * measure it against.
  */
 export interface Reranker {
     readonly id: string;
@@ -111,6 +141,14 @@ export type RetrieverDeps = {
      * "no match"), the best of them normalises to 1.0, and every query finds something.
      */
     readonly semanticFloor?: number;
+    /**
+     * Serves `mode: "navigate"` — task #219, AC-4.
+     *
+     * Optional, and its absence is a *named refusal* for that mode rather than a fall back to semantic search: a
+     * caller that asked for navigation and silently got embeddings would attribute the results to the wrong
+     * mechanism, which is the only way this spike could have done harm.
+     */
+    readonly navigator?: Navigator;
 };
 export type RetrieveInput = {
     readonly query: string;
@@ -126,6 +164,36 @@ export type RetrieveInput = {
     /** Defaults to `hybrid`. The other two exist so the hybrid claim can be measured against them. */
     readonly mode?: RetrievalMode;
 };
+/**
+ * Reciprocal rank fusion, extracted so there is exactly one of it — REQ-045 (#204), task #210, AC-2.
+ *
+ * `find_tools` fuses two signals over tool descriptors and this fuses two signals over knowledge chunks. Those
+ * are the same algorithm with a different corpus, and writing it twice is the shape this repository keeps
+ * finding defects in: the second copy drifts, usually in the tie-break or the normalisation, and the drift
+ * shows up as one ranker being subtly worse with nothing pointing at why.
+ *
+ * Generic over the item and its key. The **key** is what merges an item found by both signals; without it a
+ * chunk in both lists would fuse with itself and score twice.
+ *
+ * Scores come back normalised against the best fused score, because a raw RRF sum means nothing on its own —
+ * `2/61` is not "poor", it is "found first by both signals". Normalising is what lets one relevance floor apply
+ * to any corpus, tools included.
+ */
+export type FusedEntry<T, S extends string> = {
+    readonly item: T;
+    /** 0–1, relative to the best entry in this fusion. Comparable within one query, never across two. */
+    readonly score: number;
+    readonly signals: readonly S[];
+};
+export declare const fuseByRank: <T, S extends string>(input: {
+    readonly lists: readonly {
+        readonly signal: S;
+        readonly items: readonly T[];
+    }[];
+    readonly keyOf: (item: T) => string;
+    /** The rank-fusion constant. Defaults to `RRF_K`; a caller changing it should say why. */
+    readonly k?: number;
+}) => readonly FusedEntry<T, S>[];
 export declare const createRetriever: (deps: RetrieverDeps) => {
     rerankerId: string | null;
     retrieve(context: {

package/dist/knowledge/retrieval.js

@@ -14,9 +14,19 @@
  *
  *     score(d) = Σ over signals of 1 / (K + rank(d))
  *
- * A document ranked first by one signal and absent from the other still beats one ranked fifth by both, which
- * is the behaviour that makes hybrid better than either — the exact-term hit surfaces even though the semantic
- * signal never saw it.
+ * A document ranked first by one signal and absent from the other still beats one ranked fifth by both, which is
+ * the behaviour hybrid exists for — the exact-term hit surfaces even though the semantic signal never saw it.
+ *
+ * **And on one real corpus it is worse than semantic alone.** This comment used to say hybrid "measurably beats"
+ * both parts; #219 measured it over 56 documents of technical prose and hybrid lost 11.1 points of success@5 to
+ * semantic-only — two cases out of eighteen. The mechanism is the same paragraph read the other way: RRF weights both signals equally by
+ * construction, so fusing a weak list with a strong one demotes the strong list's top hits wherever the weak one
+ * disagrees. The lexical signal is weak on natural-language questions over prose.
+ *
+ * Hybrid remains the default, deliberately — that dataset has 18 queries, one author, and **no identifier
+ * queries**, which is precisely the case hybrid exists for. But the claim in this comment was untested for months
+ * and turned out to be false where it was finally tested, so it is stated with its evidence now. See
+ * `docs/26-retrieval-quality.md`.
  *
  * **`K = 60`** is the value from Cormack, Clarke and Buettcher's original TREC work and the one every
  * implementation since has used. It is large relative to the ranks that matter, which flattens the difference
@@ -47,7 +57,46 @@ export const DEFAULT_RELEVANCE_FLOOR = 0.4;
  * different answer from "you have no indexed documents", and telling a user the first when the second is true
  * sends them looking for content they never uploaded.
  */
-export const NO_RESULT_REASONS = ["nothing-indexed", "no-match", "below-threshold", "no-access"];
+export const NO_RESULT_REASONS = [
+    "nothing-indexed",
+    "no-match",
+    "below-threshold",
+    "no-access",
+    /**
+     * The mode asked for is not wired — task #219.
+     *
+     * Its own reason rather than `no-match`, because the two want opposite responses: one says rephrase, this says
+     * a deployment has not configured what you asked for. Falling back to another mode silently would be worse
+     * than either, since the caller would attribute the results to the mode it named.
+     */
+    "not-configured",
+];
+export const fuseByRank = (input) => {
+    const k = input.k ?? RRF_K;
+    const fused = new Map();
+    for (const list of input.lists) {
+        list.items.forEach((item, rank) => {
+            const key = input.keyOf(item);
+            const increment = 1 / (k + rank + 1);
+            const existing = fused.get(key);
+            if (existing === undefined)
+                fused.set(key, { item, key, score: increment, signals: new Set([list.signal]) });
+            else {
+                existing.score += increment;
+                existing.signals.add(list.signal);
+            }
+        });
+    }
+    // Key order breaks ties, so two runs over the same corpus produce the same ranking. A `Map` iteration order
+    // tie-break would depend on which signal happened to return first.
+    const ordered = [...fused.values()].sort((a, b) => (b.score !== a.score ? b.score - a.score : a.key.localeCompare(b.key)));
+    const best = ordered[0]?.score ?? 0;
+    return ordered.map((entry) => ({
+        item: entry.item,
+        score: best === 0 ? 0 : entry.score / best,
+        signals: [...entry.signals],
+    }));
+};
 const referenceFor = (chunk) => ({
     sourceType: chunk.sourceType,
     sourceId: chunk.sourceId,
@@ -60,6 +109,7 @@ const NO_RESULT_MESSAGES = {
     "no-match": "Nothing in the available material matches that.",
     "below-threshold": "Nothing in the available material is a close enough match to rely on.",
     "no-access": "There is no material you have access to that matches that.",
+    "not-configured": "That retrieval mode is not configured for this deployment.",
 };
 export const createRetriever = (deps) => {
     const candidateCount = deps.candidates ?? DEFAULT_CANDIDATES;
@@ -69,6 +119,21 @@ export const createRetriever = (deps) => {
         rerankerId: deps.reranker?.id ?? null,
         async retrieve(context, input) {
             const mode = input.mode ?? "hybrid";
+            // The spike's mode, delegated whole: it shares no step with the fusion path below.
+            if (mode === "navigate") {
+                if (deps.navigator === undefined)
+                    return {
+                        found: false,
+                        reason: "not-configured",
+                        message: NO_RESULT_MESSAGES["not-configured"],
+                        mode,
+                    };
+                return deps.navigator.navigate(context, {
+                    query: input.query,
+                    authSubjects: input.authSubjects,
+                    limit: input.limit,
+                });
+            }
             // Checked before either index is asked. An empty subject list is not a query with no results — it is a
             // caller with no access, and the two want different sentences.
             if (input.authSubjects.length === 0)
@@ -93,30 +158,19 @@ export const createRetriever = (deps) => {
             const lexical = mode === "semantic" ? [] : await deps.keyword.search({ ...scope, query: input.query });
             if (semantic.length === 0 && lexical.length === 0)
                 return { found: false, reason: "no-match", message: NO_RESULT_MESSAGES["no-match"], mode };
-            // RRF. Rank, not score: see the note at the top on why adding two incomparable scales fails silently.
-            const fused = new Map();
-            const contribute = (hits, signal) => {
-                hits.forEach((hit, rank) => {
-                    const existing = fused.get(hit.chunk.id);
-                    const increment = 1 / (RRF_K + rank + 1);
-                    if (existing === undefined)
-                        fused.set(hit.chunk.id, { chunk: hit.chunk, score: increment, signals: new Set([signal]) });
-                    else {
-                        existing.score += increment;
-                        existing.signals.add(signal);
-                    }
-                });
-            };
-            contribute(semantic, "semantic");
-            contribute(lexical, "keyword");
-            const ordered = [...fused.values()].sort((a, b) => b.score !== a.score ? b.score - a.score : a.chunk.id.localeCompare(b.chunk.id));
-            const best = ordered[0]?.score ?? 0;
-            const candidates = ordered.map((entry) => ({
-                chunk: entry.chunk,
-                // Normalised against the best fused score, so the floor means the same thing whatever the corpus.
-                score: best === 0 ? 0 : entry.score / best,
-                signals: [...entry.signals],
-                reference: referenceFor(entry.chunk),
+            // RRF, through the shared implementation. Rank, not score: see the note at the top on why adding two
+            // incomparable scales fails silently, and `fuseByRank` on why there is only one of these.
+            const candidates = fuseByRank({
+                lists: [
+                    { signal: "semantic", items: semantic },
+                    { signal: "keyword", items: lexical },
+                ],
+                keyOf: (hit) => hit.chunk.id,
+            }).map((entry) => ({
+                chunk: entry.item.chunk,
+                score: entry.score,
+                signals: entry.signals,
+                reference: referenceFor(entry.item.chunk),
             }));
             const relevant = candidates.filter((hit) => hit.score >= floor);
             if (relevant.length === 0)

package/dist/models/streaming.d.ts

@@ -61,13 +61,34 @@ export declare const nonTextCounts: (messages: readonly TurnMessage[]) => {
     readonly imageCount?: number;
 };
 export declare const modalitiesOf: (messages: readonly TurnMessage[]) => readonly InputModality[];
+/**
+ * What the provider tells us about a call it is making.
+ *
+ * Only the id, and only because a wrapper needs a key: an execution that resolved to a *different* tool than the
+ * one the model named — `execute_tool` — has to be able to say which call it was, or the run event log records
+ * the indirection and loses the action.
+ */
+export type ModelToolCallOptions = {
+    readonly toolCallId?: string;
+    /**
+     * Report what actually ran, when it is not the tool the model named.
+     *
+     * Best effort by construction: the platform's execution path knows the fact and the *host's* `execute` closure
+     * is the only thing standing between the two, so a host that does not call this leaves the field absent. Absent
+     * therefore means "nobody reported an indirection", not "there was none" — which is why the run event log keeps
+     * the model's own tool name as the primary record and treats this as an addition to it.
+     */
+    readonly report?: (fact: {
+        readonly ranToolName: string;
+    }) => void;
+};
 /** A tool the model may call this turn. `execute` is the platform's guarded execution path. */
 export type ModelTurnTool = {
     readonly name: string;
     readonly description?: string;
     /** Zod schema or JSON-schema object; a permissive object schema is used when absent. */
     readonly inputSchema?: unknown;
-    execute(input: unknown): Promise<unknown>;
+    execute(input: unknown, options?: ModelToolCallOptions): Promise<unknown>;
 };
 export type ModelTurnRequest = {
     readonly model: ResolvedModel;

package/dist/models/streaming.js

@@ -87,7 +87,11 @@ const toToolSet = (tools) => {
                 : isJsonSchema(t.inputSchema)
                     ? jsonSchema(t.inputSchema)
                     : jsonSchema({ type: "object", additionalProperties: true }),
-            execute: (input) => t.execute(input),
+            // The options are *forwarded*, not dropped. Without the call id a wrapper cannot attribute what it ran,
+            // which is how a tool executed through `execute_tool` became an unattributable entry in the audit trail.
+            // The options are *forwarded*, not dropped. Without the call id a wrapper cannot attribute what it ran,
+            // which is how a tool executed through `execute_tool` became an unattributable entry in the audit trail.
+            execute: (input, options) => t.execute(input, { toolCallId: options?.toolCallId }),
         });
     }
     return set;

package/dist/security/checklist.js

@@ -198,6 +198,15 @@ export const CREDENTIAL_FIELD_EXEMPTIONS = [
             "credential must exist in memory to authenticate; what AC-1 forbids is storing, passing, returning or " +
             "logging one, and none of those happen here.",
     },
+    {
+        file: "adapters/embeddings/openai.ts",
+        reason: "`OpenAiEmbeddingsConfig.apiKey` is the same shape as the model provider's, for the same reason and with " +
+            "the same limits: a key the host supplies at wiring time and this adapter puts in one Authorization " +
+            "header. Process-local — never written to a table, never in a message part or a result envelope, and no " +
+            "allowlisted log field could carry it. It is also never reachable from a model: an embedding is computed " +
+            "for a chunk the platform is indexing, not for text a model asked about, so there is no input path that " +
+            "could name or read it.",
+    },
 ];
 /** Checks with no automated backing. The set a person must actually walk at each release. */
 export const manualChecks = () => SECURITY_CHECKS.filter((check) => check.verifiedBy === "manual");

package/dist/security/findings.js

@@ -134,19 +134,28 @@ export const FINDINGS = [
         id: "SEC-006",
         area: "egress",
         severity: "informational",
-        title: "There is no research or web-fetch path to audit",
+        title: "The web-fetch path exists now, and the audit had been passing it for the wrong reason",
         impact: "AC-2 asks for the allow-list to be enforced at a single point covered by *both* the research and MCP paths. " +
-            "The research path does not exist in this package: the only outbound HTTP is the MCP transport and the " +
-            "Supabase storage adapter, whose destination is operator configuration rather than a model's choice. So the " +
-            "single-point property holds trivially today and is not evidence that it will hold once research lands.",
-        foundBy: "grepping for every `fetch(` call in the tree and finding two, neither model-directed",
+            "When this was written the research path did not exist and the property held trivially. It exists now — " +
+            "REQ-039 (#188) shipped `fetch_url`, `fetch_json`, `http_request` and `http_write`, all through " +
+            "`toolkit/http.ts`, and #219 added an embedding adapter — so the property is real rather than trivial: the " +
+            "model-directed path goes through `validateHttpEgress`, which refuses private ranges, cloud metadata, " +
+            "non-https schemes, credentials in the URL and followed redirects.\n\n" +
+            "The finding that replaces the original: the audit asserting 'no other outbound call' matched `fetch(` and " +
+            "not `?? fetch`, and every injectable client in this codebase captures the global that way. So " +
+            "`toolkit/http.ts` had never appeared in that check at all. Not a vulnerability — its destination was " +
+            "policed throughout — but the check was passing it by accident, and would have passed the next such file " +
+            "the same way.",
+        foundBy: "adding a third outbound path in #219 and asking why the audit's allow-list had only ever had three " +
+            "entries when the tree had four outbound sites",
         resolution: {
             kind: "accepted",
             owner: "azeem@snipe-solutions.de",
-            reason: "Nothing to fix; recording it so the AC is not read as stronger than the evidence. A test asserts the " +
-                "*absence* of any other outbound call, so adding one fails the audit and forces the author to route it " +
-                "through `validateEndpoint` — which is the durable version of this guarantee.",
-            revisitBy: "when a research or web-fetch tool is implemented",
+            reason: "The audit now matches a captured `fetch` as well as a called one, and its allow-list names five paths " +
+                "with the reason each destination is auditable. Adding a sixth fails the test and forces its author to " +
+                "say which policy governs the destination — which is the durable version of this guarantee, and is what " +
+                "the original entry was reaching for before there was anything to govern.",
+            revisitBy: "2027-06-30",
         },
     },
 ];

package/dist/skills/catalogue.d.ts

@@ -0,0 +1,49 @@
+/**
+ * A token ceiling on the skill catalogue — REQ-045 (#204), task #210, AC-5.
+ *
+ * Skills have exactly the tool catalogue's problem: a compact entry per skill sits in context on every turn, and
+ * the bodies already load on demand, so what is left is linear in how many skills a tenant has. 25 skills at
+ * `descriptionMaxLength` is a page of prompt before the conversation starts.
+ *
+ * The budget is `core/budget.ts` — the same one the tool catalogue uses, not a second copy.
+ *
+ * ## The notice is part of the catalogue, not part of the log
+ *
+ * The tool path can be loud in a run event because the engine assembles the tool list and the engine owns the
+ * event stream. The skill catalogue is assembled by a *context provider*, which has no event stream, so the same
+ * report reaches the same place by a different route: `truncationNotice` puts it in the text the model reads.
+ *
+ * That is arguably the stronger channel of the two. A run event tells whoever reviews the run afterwards; this
+ * tells the model *during* the turn, so it can say "there are more skills than I was shown" instead of
+ * confidently reporting that no skill exists for the job. Callers still get the report, and a host with an event
+ * stream to hand should log it too.
+ */
+/**
+ * The specific core modules, **not** `core/index.js`.
+ *
+ * The barrel re-exports `core/validation.ts`, which imports `zod`. Importing it from here put zod into the
+ * dependency graph of `@retinue/agentkit/persistence` — a subpath whose whole claim is that it reaches nothing
+ * outside the standard library, so a test or a prototype needs no install beyond the package. Caught by
+ * `root-import-weight.test.ts`, which walks the graph transitively; a barrel import is how that guarantee gets
+ * lost, and it is invisible in review.
+ */
+import { type BudgetOutcome, type TokenBudget } from "../core/budget.js";
+import type { SkillCatalogEntry } from "./index.js";
+/**
+ * Per-entry scaffolding: the bullet, the name emphasis, the version.
+ *
+ * Slightly larger than the tool catalogue's because a skill entry is rendered as prose in Markdown rather than
+ * as a JSON tool definition.
+ */
+export declare const SKILL_ENTRY_OVERHEAD_TOKENS = 8;
+export declare const skillEntryTokens: (entry: SkillCatalogEntry) => number;
+export declare const budgetSkillCatalogue: (entries: readonly SkillCatalogEntry[], budget: TokenBudget) => BudgetOutcome<SkillCatalogEntry>;
+/**
+ * What the model is told when the catalogue was shortened.
+ *
+ * Names the skills rather than counting them, for the same reason the run event does: "3 more skills exist" is
+ * something a model can only ignore, while a name is something it can ask for. Empty string when nothing was
+ * dropped, so a caller can concatenate unconditionally.
+ */
+export declare const truncationNotice: (outcome: BudgetOutcome<SkillCatalogEntry>) => string;
+//# sourceMappingURL=catalogue.d.ts.map

package/dist/skills/catalogue.js

@@ -0,0 +1,61 @@
+/**
+ * A token ceiling on the skill catalogue — REQ-045 (#204), task #210, AC-5.
+ *
+ * Skills have exactly the tool catalogue's problem: a compact entry per skill sits in context on every turn, and
+ * the bodies already load on demand, so what is left is linear in how many skills a tenant has. 25 skills at
+ * `descriptionMaxLength` is a page of prompt before the conversation starts.
+ *
+ * The budget is `core/budget.ts` — the same one the tool catalogue uses, not a second copy.
+ *
+ * ## The notice is part of the catalogue, not part of the log
+ *
+ * The tool path can be loud in a run event because the engine assembles the tool list and the engine owns the
+ * event stream. The skill catalogue is assembled by a *context provider*, which has no event stream, so the same
+ * report reaches the same place by a different route: `truncationNotice` puts it in the text the model reads.
+ *
+ * That is arguably the stronger channel of the two. A run event tells whoever reviews the run afterwards; this
+ * tells the model *during* the turn, so it can say "there are more skills than I was shown" instead of
+ * confidently reporting that no skill exists for the job. Callers still get the report, and a host with an event
+ * stream to hand should log it too.
+ */
+/**
+ * The specific core modules, **not** `core/index.js`.
+ *
+ * The barrel re-exports `core/validation.ts`, which imports `zod`. Importing it from here put zod into the
+ * dependency graph of `@retinue/agentkit/persistence` — a subpath whose whole claim is that it reaches nothing
+ * outside the standard library, so a test or a prototype needs no install beyond the package. Caught by
+ * `root-import-weight.test.ts`, which walks the graph transitively; a barrel import is how that guarantee gets
+ * lost, and it is invisible in review.
+ */
+import { applyTokenBudget } from "../core/budget.js";
+import { estimateTokens } from "../core/tokens.js";
+/**
+ * Per-entry scaffolding: the bullet, the name emphasis, the version.
+ *
+ * Slightly larger than the tool catalogue's because a skill entry is rendered as prose in Markdown rather than
+ * as a JSON tool definition.
+ */
+export const SKILL_ENTRY_OVERHEAD_TOKENS = 8;
+export const skillEntryTokens = (entry) => estimateTokens(`${entry.name} v${entry.version} ${entry.description}`) + SKILL_ENTRY_OVERHEAD_TOKENS;
+export const budgetSkillCatalogue = (entries, budget) => applyTokenBudget({
+    items: entries,
+    budget,
+    tokensOf: skillEntryTokens,
+    nameOf: (entry) => entry.name,
+});
+/**
+ * What the model is told when the catalogue was shortened.
+ *
+ * Names the skills rather than counting them, for the same reason the run event does: "3 more skills exist" is
+ * something a model can only ignore, while a name is something it can ask for. Empty string when nothing was
+ * dropped, so a caller can concatenate unconditionally.
+ */
+export const truncationNotice = (outcome) => outcome.dropped.length === 0
+    ? ""
+    : [
+        "",
+        `Not every skill is listed above: ${outcome.dropped.length} more exist but did not fit this turn's`,
+        `catalogue budget (${outcome.dropped.join(", ")}). If one of them is what the task needs, say so rather`,
+        "than concluding there is no skill for it.",
+    ].join("\n");
+//# sourceMappingURL=catalogue.js.map

package/dist/skills/index.d.ts

@@ -63,5 +63,6 @@ export interface SkillResolver {
         version: number;
     }): Promise<SkillVersion>;
 }
+export * from "./catalogue.js";
 export * from "./resolver.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/skills/index.js

@@ -27,5 +27,6 @@ export const SKILL_LIMITS = {
     /** Per run, to bound what `load_skill` can pull into context. */
     maxLoadedPerRun: 5,
 };
+export * from "./catalogue.js";
 export * from "./resolver.js";
 //# sourceMappingURL=index.js.map

package/dist/telemetry/spans.js

@@ -38,6 +38,18 @@ export const SPAN_FOR_RUN_EVENT = {
     "approval.decided": "hitl.approval",
     "usage.updated": "run.step",
     "context.compacted": "context.compact",
+    // Its own span, not `run.step`: a guardrail verdict is the boundary of a decision somebody will need to find
+    // later — "what stopped this turn" is the question a trace gets opened to answer.
+    "guardrail.verdict": "guardrail.inspect",
+    /**
+     * Its own span, and the reason is a rule this repository enforces: a span shares its first word with its
+     * event unless it is deliberately folded into `run.step`.
+     *
+     * `context.compact` was the first choice — dropping tools to fit a budget is the same *kind* of act as
+     * dropping history to fit one — and `telemetry.test.ts` rejected it. Correctly: an operator searching traces
+     * for why a turn was short of tools would not find it filed under context compaction.
+     */
+    "catalog.truncated": "catalog.truncate",
 };
 /**
  * The spans that are *not* run events.