@retinue/agentkit 0.1.0 → 0.3.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,9 @@
 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";
+import type { GraphLocalSearch } from "./graph-retrieval.js";
+import type { GraphGlobalSearch } from "./graph-global.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 +55,25 @@ 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.
+ */
+/**
+ * `graph-local` joins the union in REQ-064 (#270), task #273.
+ *
+ * A closed union read in several places, so a new member is threaded rather than cast past — the same
+ * discipline #219 applied when it added `not-configured`. Like `navigate`, it is *delegated whole*: it shares
+ * no step with the fusion path, because it answers a different kind of question.
+ */
+export type RetrievalMode = "semantic" | "keyword" | "hybrid" | "navigate" | "graph-local" | "graph-global";
 /** 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 +98,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 +116,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 +150,30 @@ 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;
+    /**
+     * Serves `mode: "graph-local"` — REQ-064 (#270), task #273.
+     *
+     * Optional for the same reason `navigator` is, and its absence is the same named refusal. GraphRAG is opt-in
+     * and expensive to index, so a deployment that never enabled it supplies nothing here and asking for the
+     * mode says so rather than quietly returning embeddings.
+     */
+    readonly graphLocal?: GraphLocalSearch;
+    /**
+     * Serves `mode: "graph-global"` — REQ-064 (#270), task #274.
+     *
+     * Separate from `graphLocal` rather than one graph dependency, because they are independently useful: a
+     * deployment can run entity-centric retrieval without paying for community summaries at all, and #273 landed
+     * before #272 for exactly that reason.
+     */
+    readonly graphGlobal?: GraphGlobalSearch;
 };
 export type RetrieveInput = {
     readonly query: string;
@@ -126,6 +189,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,52 @@ 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.
+     *
+     * 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.
+     *
+     * **Live, not a placeholder** — audited for #256 AC-8. Three code paths return it (`navigate` with no
+     * navigator, `graph-local` and `graph-global` with no GraphRAG), and three test files assert it. The optional
+     * modes are exactly why it has to exist: GraphRAG ships **off by default** on the measured evidence in
+     * `docs/29`, so "you asked for a mode this deployment did not switch on" is an ordinary answer rather than an
+     * edge case. The comment previously cited task #219 as if it were pending; it closed.
+     */
+    "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 +115,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 +125,91 @@ export const createRetriever = (deps) => {
         rerankerId: deps.reranker?.id ?? null,
         async retrieve(context, input) {
             const mode = input.mode ?? "hybrid";
+            /**
+             * The graph mode, delegated whole — task #273.
+             *
+             * Before the `authSubjects` check below only because it does its own: an empty subject list means the
+             * same thing here, and the graph search returns an empty result for it rather than traversing first and
+             * filtering after. Placed with `navigate` because both are delegated modes rather than fusion inputs.
+             */
+            if (mode === "graph-local") {
+                if (deps.graphLocal === undefined)
+                    return { found: false, reason: "not-configured", message: NO_RESULT_MESSAGES["not-configured"], mode };
+                if (input.authSubjects.length === 0)
+                    return { found: false, reason: "no-access", message: NO_RESULT_MESSAGES["no-access"], mode };
+                const result = await deps.graphLocal.search(context, {
+                    query: input.query,
+                    authSubjects: input.authSubjects,
+                    limit: input.limit,
+                    ...(input.sourceTypes === undefined ? {} : { sourceTypes: input.sourceTypes }),
+                });
+                if (result.hits.length === 0)
+                    /**
+                     * An honest empty result, and the reason distinguishes the two ways it happens.
+                     *
+                     * Nothing in the question named an entity the graph knows is `no-match` — rephrasing might work.
+                     * Entities matched but reached no readable chunk is also `no-match` rather than `no-access`, because
+                     * the principal may genuinely have access to a corpus that simply says nothing more.
+                     */
+                    return { found: false, reason: "no-match", message: NO_RESULT_MESSAGES["no-match"], mode };
+                return {
+                    found: true,
+                    mode,
+                    hits: result.hits.map((hit) => ({
+                        chunk: hit.chunk,
+                        score: hit.score,
+                        signals: ["graph-local"],
+                        reference: referenceFor(hit.chunk),
+                    })),
+                };
+            }
+            /**
+             * The corpus-level mode — task #274.
+             *
+             * Its cost ceiling **throws** rather than returning an outcome, and that is deliberate: exceeding it is
+             * not "found nothing", it is "this question is too expensive to answer this way", and the two want
+             * different responses. `RetrievalOutcome`'s `found: false` reasons are all about the corpus; this is
+             * about the request.
+             */
+            if (mode === "graph-global") {
+                if (deps.graphGlobal === undefined)
+                    return { found: false, reason: "not-configured", message: NO_RESULT_MESSAGES["not-configured"], mode };
+                if (input.authSubjects.length === 0)
+                    return { found: false, reason: "no-access", message: NO_RESULT_MESSAGES["no-access"], mode };
+                const result = await deps.graphGlobal.search(context, {
+                    query: input.query,
+                    authSubjects: input.authSubjects,
+                    limit: input.limit,
+                    ...(input.sourceTypes === undefined ? {} : { sourceTypes: input.sourceTypes }),
+                });
+                if (result.hits.length === 0)
+                    return { found: false, reason: "no-match", message: NO_RESULT_MESSAGES["no-match"], mode };
+                return {
+                    found: true,
+                    mode,
+                    hits: result.hits.map((hit) => ({
+                        chunk: hit.chunk,
+                        score: hit.score,
+                        signals: ["graph-global"],
+                        reference: referenceFor(hit.chunk),
+                    })),
+                };
+            }
+            // 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 +234,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/mcp-server/index.d.ts

@@ -0,0 +1,168 @@
+/**
+ * An inbound MCP server — REQ-059 (#249), task #250.
+ *
+ * `backend/src/mcp/` is the **outbound** direction: a tenant registers their MCP server and this platform
+ * consumes it. Its own header says so, and points at an inbound server that lives in the *old Chorus
+ * repository* — not in this package. So `@retinue/agentkit` could consume an MCP server and could not be one,
+ * and a deployment's tools were unreachable from Claude Code, Claude Desktop, Cursor and every other MCP client.
+ *
+ * Nothing here re-implements a capability. The registry already does authorization, the tenant's toolset, the
+ * approval gate, validation, idempotency and audit attribution; this is a protocol surface in front of it, and
+ * every call goes through `registry.execute` exactly as an agent's would.
+ *
+ * ## The trust direction inverts, and that is the thing to get right
+ *
+ * Outbound, `mcp/index.ts` establishes the rule: a remote server's `readOnlyHint`/`destructiveHint` are
+ * *advisory and untrusted*, and "a remote server cannot talk its way down to" a weaker effect. Inbound, **this
+ * package is the remote server**. Two consequences, and both are enforced rather than intended:
+ *
+ * 1. What it advertises must be what it enforces. The annotations are derived from `ToolEffect` by one
+ *    function, so they cannot drift from the effect the registry acts on.
+ * 2. Nothing the client sends is trusted — not an effect, not a hint, not a claim about a prior approval. The
+ *    client supplies a tool name and arguments; everything else comes from the context the *host* built.
+ *
+ * ## Authentication is structural
+ *
+ * `createMcpToolServer` takes a resolved `ExecutionContext`. There is no `authenticate` callback to forget and
+ * no default: a host that has not authenticated has nothing to pass, so it cannot construct a server. That is
+ * the same decision `server/main.ts` makes — "a permissive default would serve an open API to anyone who forgot
+ * to set it" — expressed in the type instead of in a runtime check, because this surface gets exposed to the
+ * internet and a runtime check can be skipped.
+ *
+ * One server per authenticated session: a stdio server is launched per client and carries that client's
+ * identity for its lifetime; an HTTP mount builds one per authenticated request.
+ */
+import type { ExecutionContext } from "../core/context.js";
+import type { ToolDescriptor, ToolEffect, ToolRegistry } from "../tools/index.js";
+/**
+ * The MCP SDK, imported for its types only where possible.
+ *
+ * An **optional peer dependency**, following `vitest` on `./testing`: a consumer who never mounts an MCP server
+ * never installs it, and the only path to this module is its own subpath.
+ */
+export type McpServerLike = {
+    /**
+     * `any`, and it is the correct choice rather than a shortcut.
+     *
+     * The SDK's real signature is generic —
+     * `<T extends AnyObjectSchema>(schema: T, handler: (request: SchemaOutput<T>, extra: RequestHandlerExtra) => …)`
+     * — and this package cannot restate those generics without importing the SDK, which would stop it being an
+     * optional peer. A structural type with `unknown`/`never` parameters looks stricter and is **not assignable
+     * from** the SDK's `Server`, so the first version of this failed to typecheck at the only call site anybody
+     * will write. `check:consumer` caught it by compiling the documented sample against the packed tarball:
+     *
+     *     Argument of type 'Server<…>' is not assignable to parameter of type 'McpServerLike'
+     *       Type 'any' is not assignable to type 'never'
+     *
+     * A type nothing real satisfies is worse than a permissive one.
+     */
+    setRequestHandler(schema: any, 
+    /**
+     * The result is an object, not `unknown` — the second half of the same lesson.
+     *
+     * The SDK's handler must return a `ServerResult`, and `Promise<unknown>` is *wider* than that, so a `Server`
+     * was still not assignable even after the parameters were relaxed. A permissive object shape satisfies it
+     * in both directions.
+     */
+    handler: (request: any, extra?: any) => Promise<Record<string, unknown>>): void;
+    connect(transport: any): Promise<void>;
+};
+export type McpToolAnnotations = {
+    readonly readOnlyHint: boolean;
+    readonly destructiveHint: boolean;
+    readonly idempotentHint: boolean;
+    /** True when the tool reaches something outside this deployment. */
+    readonly openWorldHint: boolean;
+};
+/**
+ * `ToolEffect` → MCP annotations, in **one** place — AC-7.
+ *
+ * One function, so the advertised hint and the enforced effect cannot drift: a test asserts this mapping over
+ * every effect, and the exposed set is checked against it. Two tables would be two chances to disagree, and the
+ * disagreement would be a client told a tool is read-only calling something that writes.
+ *
+ * `destructive` is the only `destructiveHint`, and `read` the only `readOnlyHint` — deliberately narrow.
+ * Over-claiming read-only is the dangerous direction: a client may skip a confirmation on it.
+ */
+export declare const annotationsFor: (effect: ToolEffect) => McpToolAnnotations;
+/**
+ * A tool's input schema, in the shape MCP requires — found by a real client.
+ *
+ * MCP's `tools/list` demands `inputSchema.type === "object"`, and the SDK's *client* validates it: a tool whose
+ * descriptor holds a Zod schema made the whole listing fail with `expected "object"` at one index. So the
+ * failure was not "one tool looks odd", it was **no tools at all**, from one non-conforming entry.
+ *
+ * Three cases, in order of fidelity:
+ *
+ * 1. Already a JSON-Schema object — pass it through unchanged. It is what execution validates against, so
+ *    advertising anything else would advertise a contract nothing enforces.
+ * 2. A Zod schema — convert it. `defineTool` documents `inputSchema` as "Zod schema or JSON-schema object", so
+ *    both are legitimate and a client deserves the real one either way.
+ * 3. Anything else — `{ type: "object" }`, permissive. Deliberately the *weaker* advertisement rather than a
+ *    refusal to list: the registry still validates the real schema on execution, so the failure direction is a
+ *    rejected call rather than an accepted bad one.
+ */
+export declare const toMcpInputSchema: (schema: unknown) => Record<string, unknown>;
+/** What a client is shown for one tool. */
+export declare const describeForMcp: (descriptor: ToolDescriptor) => {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    annotations: McpToolAnnotations;
+};
+export type McpToolServerDeps = {
+    readonly registry: ToolRegistry;
+    /**
+     * The authenticated caller. **Required, and there is no default.**
+     *
+     * A host that has not authenticated cannot construct a server, which is the guarantee expressed in the type
+     * rather than in a check somebody can skip.
+     */
+    readonly context: ExecutionContext;
+    readonly serverInfo?: {
+        readonly name: string;
+        readonly version: string;
+    };
+};
+/**
+ * The result of a `tools/call`, in MCP's shape.
+ *
+ * A refusal is `isError: true` with the reason as text — **not** a protocol error. That distinction matters: a
+ * protocol error tells the client the server is broken, and a tool refusal is a normal outcome the model should
+ * see and respond to. It is the same decision `streamModelTurn` makes for `tool-error`.
+ */
+export declare const toMcpResult: (outcome: {
+    readonly ok: true;
+    readonly data: unknown;
+} | {
+    readonly ok: false;
+    readonly error: {
+        readonly code: string;
+        readonly message: string;
+    };
+}) => {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError?: undefined;
+} | {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: true;
+};
+/**
+ * Registers the two handlers on an SDK `Server`.
+ *
+ * Takes the server rather than constructing it, so the SDK stays an optional peer of this package: the host
+ * imports `@modelcontextprotocol/sdk`, builds a `Server`, and hands it here. That also leaves the host in
+ * charge of the transport, which is where the authentication story differs between stdio and HTTP.
+ */
+export declare const registerRetinueTools: (server: McpServerLike, schemas: {
+    readonly listTools: unknown;
+    readonly callTool: unknown;
+}, deps: McpToolServerDeps) => void;
+//# sourceMappingURL=index.d.ts.map