@retinue/agentkit 0.1.0 → 0.3.0

package/dist/tools/credentials.js

@@ -0,0 +1,369 @@
+/**
+ * Credentials, referenced rather than held — REQ-047 (#206), task #214, AC-5; widened by REQ-063 (#259), #260.
+ *
+ * A toolkit needs a secret. The question is who holds it and when it is read, and getting that wrong is the
+ * decision that makes a multi-tenant deployment a rewrite of every package rather than a configuration change.
+ *
+ * ## Why a tool must not read the environment
+ *
+ * `process.env.GITHUB_TOKEN` inside a tool works perfectly for exactly one tenant. It is also the shape that
+ * twenty more toolkits will copy, because the first one did — and each of them then has to be rewritten when a
+ * second customer arrives, with their own token, for the same tool.
+ *
+ * So a tool takes a **reference** and the host resolves it. What the reference means — a row in a credential
+ * table, a secret manager path, an env var name in a single-tenant deployment — is the host's business and
+ * changes nothing about the tool.
+ *
+ * ## Why resolution happens at the point of use
+ *
+ * Not at construction. A credential read once at startup is a credential that survives its own rotation: the
+ * secret changes, every request keeps sending the old one, and the failure looks like the vendor rejecting a
+ * token that "has not changed". Resolving per call costs a lookup — cacheable by the host, which knows its own
+ * rotation window — and means a rotated secret takes effect without a restart.
+ *
+ * The corollary: **a resolved secret is never stored on the tool.** It lives in the local scope of one call.
+ *
+ * ## Why a miss throws
+ *
+ * Returning an empty string would send an unauthenticated request and surface as a vendor 401 several layers
+ * away, where the actual problem — nobody wired the credential — is invisible. A typed failure names the ref.
+ *
+ * ## Why a string was not enough — #260
+ *
+ * `resolve()` returned `Promise<string>`, which covers a bearer token and nothing else. Jira and Confluence
+ * want an account email *and* an API token as Basic auth; Atlassian's OAuth needs an access token *and* a cloud
+ * id discovered after consent; WhatsApp needs a token *and* a phone number id; a vendor using `X-Api-Key` needs
+ * a header name. Four of the fourteen integrations specified in `docs/23` cannot be expressed as a string, and
+ * every one of them would have grown its own side-channel.
+ *
+ * Two axes, deliberately kept apart, because they are answered by different people:
+ *
+ * - **`CredentialScheme`** — how the secret is presented on the wire. The toolkit knows this.
+ * - **`AuthMode`** — how the tenant *obtained* it: pasted a token, or completed an OAuth flow. The deployment
+ *   knows this, and it is what decides whether an unconnected tool can pause a run for consent (#264) or must
+ *   simply fail, since a token has no login URL to redirect to.
+ */
+import { AgentPlatformError } from "../core/errors.js";
+/** How a secret is presented on the wire. */
+export const CREDENTIAL_SCHEMES = ["bearer", "basic", "custom-header"];
+/**
+ * How a tenant supplied the credential.
+ *
+ * Not the same question as the scheme: an OAuth access token is presented as a bearer, so the two would collapse
+ * if they shared a type — and the collapse would lose exactly the fact #264 needs, which is whether there is a
+ * login URL to send someone to.
+ */
+export const AUTH_MODES = ["token", "oauth2"];
+/** The secret-bearing property of each scheme — the ones that must never be enumerable. */
+const SECRET_KEYS = {
+    bearer: ["token"],
+    basic: ["password"],
+    "custom-header": ["value"],
+};
+const REDACTED = "[credential redacted]";
+/**
+ * Builds a credential whose secret is **not enumerable** — AC-7.
+ *
+ * A typed object is far more likely to reach a log line than a bare string was: it gets spread into an error's
+ * `details`, passed to a structured logger, or serialised into an audit row, and every one of those uses
+ * `JSON.stringify` or an object spread. So the secret is defined non-enumerably and `toJSON`/`toString`/
+ * `util.inspect` are overridden. `credential.token` still reads normally; `{ ...credential }`,
+ * `JSON.stringify(credential)` and `console.log(credential)` do not.
+ *
+ * This is defence in depth, not a licence: a caller that reads `.token` and logs *that* is still logging a
+ * secret, and no type can stop it.
+ */
+export const createCredential = (input) => {
+    const secrets = SECRET_KEYS[input.scheme];
+    const credential = { ...input };
+    for (const key of secrets) {
+        const value = credential[key];
+        delete credential[key];
+        Object.defineProperty(credential, key, { value, enumerable: false, writable: false, configurable: false });
+    }
+    Object.defineProperty(credential, "toJSON", {
+        value: () => ({ scheme: input.scheme, ...(input.mode === undefined ? {} : { mode: input.mode }), secret: REDACTED }),
+        enumerable: false,
+    });
+    Object.defineProperty(credential, "toString", { value: () => REDACTED, enumerable: false });
+    // Node's `console.log` and `util.inspect` ignore `toString`; this is the hook they do read.
+    Object.defineProperty(credential, Symbol.for("nodejs.util.inspect.custom"), {
+        value: () => `Credential(${input.scheme}) ${REDACTED}`,
+        enumerable: false,
+    });
+    return Object.freeze(credential);
+};
+/** A bearer credential, which is what most vendors want and what a plain string used to mean. */
+export const bearer = (token, metadata, mode) => createCredential({ scheme: "bearer", token, ...(metadata === undefined ? {} : { metadata }), ...(mode === undefined ? {} : { mode }) });
+export const credentialMissing = (ref, detail) => ({
+    code: "capability_unavailable",
+    message: `No credential is wired for reference "${ref}"` +
+        (detail === undefined ? "" : `: ${detail}`) +
+        ". A tool cannot read one from the environment — supply a CredentialResolver to the host.",
+    // Retrying an unwired credential cannot help; something has to be configured.
+    retryable: false,
+});
+/**
+ * The credential resolved is not the shape this toolkit can present — #260 AC-2.
+ *
+ * Raised at **construction** where possible, and at resolution otherwise. A misconfiguration discovered as a
+ * vendor 401 an hour later is the failure this exists to prevent: the vendor's message says the token is
+ * invalid, which sends an operator to rotate a token that was never the problem.
+ */
+export const credentialSchemeMismatch = (ref, expected, got) => ({
+    code: "capability_unavailable",
+    message: `Credential "${ref}" is a ${got} credential and this toolkit presents ${expected.join(" or ")}. ` +
+        "The vendor would answer 401 and the message would say the token is invalid, which is not the problem.",
+    retryable: false,
+});
+/**
+ * A resolver over a plain map, for a single-tenant deployment and for tests.
+ *
+ * Shipped because the alternative is every host writing the same six lines, and the sixth one writing it with a
+ * fallback to `process.env` — which is the thing this module exists to prevent. Explicitly *not* environment
+ * backed: a host that wants that passes `{ github: process.env.GITHUB_TOKEN ?? "" }` and can see it doing so.
+ *
+ * **A bare string still works**, and stays the common case: it means a bearer token, which is what it meant
+ * before #260. The single-tenant path must not get harder because multi-tenant got possible.
+ */
+export const createStaticCredentialResolver = (secrets) => ({
+    async resolve({ ref }) {
+        const secret = secrets[ref];
+        if (secret === undefined || secret === "")
+            throw credentialMissing(ref, "not present in the static map");
+        return typeof secret === "string" ? bearer(secret) : secret;
+    },
+});
+/**
+ * Wraps a resolver so every resolution is audited, and so a scheme mismatch is caught here rather than by the
+ * vendor — #260 AC-2 and AC-8.
+ *
+ * A wrapper rather than a change to every resolver: a host's own resolver stays a four-line object, and the
+ * cross-cutting obligations are added once, where they cannot be forgotten per toolkit.
+ */
+export const withCredentialAudit = (resolver, audit, expected) => ({
+    async resolve(input) {
+        let credential;
+        try {
+            credential = await resolver.resolve(input);
+        }
+        catch (thrown) {
+            const reason = thrown instanceof Error ? thrown.message : String(thrown);
+            await audit.onRefused({ ref: input.ref, context: input.context, reason });
+            throw thrown;
+        }
+        if (expected !== undefined && !expected.includes(credential.scheme)) {
+            const error = credentialSchemeMismatch(input.ref, expected, credential.scheme);
+            await audit.onRefused({ ref: input.ref, context: input.context, reason: error.message });
+            throw error;
+        }
+        await audit.onResolved({ ref: input.ref, context: input.context, scheme: credential.scheme });
+        return credential;
+    },
+});
+/**
+ * The `Authorization`-style header a credential presents as.
+ *
+ * One function, so twenty toolkits do not each write their own base64 and get the padding wrong. Returns the
+ * header **name and value**, because `custom-header` does not use `Authorization`.
+ */
+export const credentialHeader = (credential) => {
+    switch (credential.scheme) {
+        case "bearer":
+            return ["Authorization", `Bearer ${credential.token}`];
+        case "basic":
+            return ["Authorization", `Basic ${Buffer.from(`${credential.username}:${credential.password}`).toString("base64")}`];
+        case "custom-header":
+            return [credential.header, credential.value];
+    }
+};
+/**
+ * Refuses a toolkit configuration whose credential cannot be presented — at construction.
+ *
+ * Takes the *declared* scheme rather than resolving, because resolution needs a context and construction has
+ * none. A host that wires a static map can therefore be told immediately; a host whose resolver is dynamic is
+ * caught by `withCredentialAudit` at the first call instead. Both are before the vendor sees anything.
+ */
+export const assertToolkitAuth = (ref, auth, declared) => {
+    if (auth.schemes.length === 0)
+        throw new Error(`toolkit auth for "${ref}" declares no schemes, so no credential could ever satisfy it`);
+    if (declared !== undefined && !auth.schemes.includes(declared)) {
+        const error = credentialSchemeMismatch(ref, auth.schemes, declared);
+        throw Object.assign(new Error(error.message), error);
+    }
+};
+/**
+ * Adds an expiry to a credential **without losing its secret protection** — AC-6.
+ *
+ * This exists because the obvious way to build one is wrong, and wrong invisibly. A host writing a
+ * `CredentialRefresher` reaches for:
+ *
+ * ```ts
+ * return { ...bearer(accessToken), expiresAt };   // ← the secret is now enumerable
+ * ```
+ *
+ * `createCredential` defines the secret **non-enumerably**, which is precisely what makes it survive a
+ * `JSON.stringify` into a log line — and precisely what a spread drops. The result looks identical, works
+ * identically, and serialises the token into the first structured log that touches it.
+ *
+ * Found by the AC-6 test failing against this repository's own test helper, which had made exactly that
+ * mistake. If the helper made it, a host will.
+ */
+export const refreshable = (credential, expiresAt) => {
+    const secrets = SECRET_KEYS[credential.scheme];
+    /**
+     * Rebuilt **through** `createCredential`, with the expiry passed in rather than added after.
+     *
+     * Two reasons it has to be this way round. The protection must be *applied* rather than copied — a copy of a
+     * non-enumerable property is an enumerable one — and `createCredential` freezes what it returns, so there is
+     * no "after" to add a field in. The secrets are read back explicitly because the spread above cannot see
+     * them, which is the whole point of them.
+     */
+    return createCredential({
+        ...credential,
+        ...Object.fromEntries(secrets.map((key) => [key, credential[key]])),
+        expiresAt,
+    });
+};
+export const isRefreshable = (credential) => typeof credential.expiresAt === "string";
+/**
+ * How early a token is replaced.
+ *
+ * Sixty seconds, and the number is a *commitment* rather than a guess: a tool call can take tens of seconds —
+ * a slow vendor, a large upload, a retry — and a token that was valid when the call started must still be
+ * valid when it arrives. Refreshing exactly at expiry makes "expired mid-flight" the common case rather than
+ * the rare one, and that failure looks like an intermittent authentication bug.
+ *
+ * AC-5. Configurable because a deployment whose calls are slower than this needs more.
+ */
+export const DEFAULT_REFRESH_SKEW_MS = 60_000;
+/** Whether a credential is expired, or close enough that it should be replaced before use. */
+export const isExpiring = (credential, skewMs, now) => {
+    if (!isRefreshable(credential))
+        return false;
+    const expiresAt = Date.parse(credential.expiresAt);
+    // An unparseable expiry is treated as expiring. The alternative is using a credential whose lifetime is
+    // unknown, and the cost of an unnecessary refresh is one call.
+    return Number.isNaN(expiresAt) || expiresAt - now <= skewMs;
+};
+/**
+ * A refresh that failed because the grant is gone, rather than because the network was.
+ *
+ * The distinction is the whole of AC-3, and it is not cosmetic: `invalid_grant` means a person must consent
+ * again and no amount of retrying will help, while a timeout means try again in a second. A runtime that
+ * conflates them either retries a dead grant forever or asks a user to re-authorise because of a blip.
+ */
+export const REFRESH_GRANT_ERRORS = ["invalid_grant", "invalid_client", "unauthorized_client", "access_denied"];
+export const isGrantError = (error) => {
+    const text = (error instanceof Error ? error.message : String(error)).toLowerCase();
+    return REFRESH_GRANT_ERRORS.some((code) => text.includes(code));
+};
+/**
+ * Wraps a resolver so an expiring credential is renewed before it is handed out.
+ *
+ * A wrapper, like `withCredentialAudit`, and for the same reason: the eight shipped toolkits already resolve
+ * **per call**, so they pick this up without a line changing. A toolkit that cached a credential at
+ * construction would defeat it, which is why `createGitHubToolkit` and every sibling resolve inside `call()`.
+ *
+ * ## Time-driven, never 401-driven — AC-7
+ *
+ * The obvious design is to refresh when the vendor returns 401. It is wrong, and worth stating plainly because
+ * it is what most integrations do:
+ *
+ * A 401 is what a vendor returns for an expired token, a **revoked** grant, a token for the wrong tenant, and a
+ * scope the grant never had. Refreshing on 401 therefore turns a revoked grant into an infinite refresh loop
+ * against the vendor's token endpoint, and turns a missing scope into a refresh that succeeds and a call that
+ * fails again identically. Neither is diagnosable from the outside.
+ *
+ * Time is the only signal that means what it says: a token with an expiry in the past is expired, and nothing
+ * else is inferred from it. A 401 on a freshly-refreshed token is a real error and is surfaced as one.
+ *
+ * ## One refresh, not N — AC-2
+ *
+ * Twenty concurrent tool calls hitting an expired token must produce **one** refresh. Refresh endpoints rate
+ * limit, and — worse — several vendors invalidate the previous refresh token when one is used, so N concurrent
+ * refreshes race to invalidate each other and log the deployment out permanently.
+ *
+ * The in-flight promise is stored *before* the first await, so a second caller entering the function
+ * synchronously after the first still finds it.
+ */
+export const withRefreshingCredentials = (resolver, refresher, options = {}) => {
+    const skewMs = Math.max(0, options.skewMs ?? DEFAULT_REFRESH_SKEW_MS);
+    const now = options.now ?? (() => Date.now());
+    /**
+     * Keyed by tenant **and** ref — AC-4.
+     *
+     * Two tenants naming the same credential `"google"` mean different grants, and a cache keyed by ref alone
+     * would hand one tenant the other's token after a refresh. A space separates them: a tenant id cannot
+     * contain one, so `a` + `b c` and `a b` + `c` cannot collide.
+     */
+    const cached = new Map();
+    const inFlight = new Map();
+    const keyOf = (tenantId, ref) => `${tenantId} ${ref}`;
+    const refreshOnce = (key, input) => {
+        const existing = inFlight.get(key);
+        if (existing !== undefined)
+            return existing;
+        // Built and stored before the first await, so a synchronous second caller joins this one rather than
+        // starting a second refresh.
+        const attempt = (async () => {
+            try {
+                const fresh = await refresher.refresh({ ref: input.ref, context: input.context });
+                cached.set(key, fresh);
+                options.onRefreshed?.({
+                    ref: input.ref,
+                    tenantId: String(input.context.tenantId),
+                    expiresAt: fresh.expiresAt,
+                });
+                return fresh;
+            }
+            catch (thrown) {
+                /**
+                 * Belt-and-braces, and **not** load-bearing — worth saying rather than implying otherwise.
+                 *
+                 * A cached credential that is expiring already fails the freshness guard in `resolve`, so the next
+                 * caller would attempt a refresh whether or not this line ran. Removing it breaks no test, which is
+                 * exactly what one should expect. It stays because the invariant it states — a credential known to be
+                 * dead is never held — is one a future edit could otherwise quietly rely on being false.
+                 */
+                cached.delete(key);
+                throw new AgentPlatformError(isGrantError(thrown)
+                    ? {
+                        code: "unauthorized",
+                        message: `The stored authorisation for "${input.ref}" is no longer valid and could not be renewed. ` +
+                            "Someone needs to connect the account again — retrying will not help.",
+                        retryable: false,
+                    }
+                    : {
+                        code: "provider_unavailable",
+                        message: `Could not renew the authorisation for "${input.ref}" right now.`,
+                        retryable: true,
+                    }, { cause: thrown });
+            }
+            finally {
+                inFlight.delete(key);
+            }
+        })();
+        inFlight.set(key, attempt);
+        return attempt;
+    };
+    return {
+        async resolve(input) {
+            const key = keyOf(String(input.context.tenantId), input.ref);
+            const held = cached.get(key);
+            if (held !== undefined && !isExpiring(held, skewMs, now()))
+                return held;
+            // Ask the underlying resolver first: it is the source of truth, and on the common path the credential it
+            // returns is a plain one with no expiry, which is passed straight through.
+            const resolved = await resolver.resolve(input);
+            if (!isRefreshable(resolved))
+                return resolved;
+            if (!isExpiring(resolved, skewMs, now())) {
+                cached.set(key, resolved);
+                return resolved;
+            }
+            return refreshOnce(key, input);
+        },
+    };
+};
+//# sourceMappingURL=credentials.js.map

package/dist/tools/define.d.ts

@@ -16,10 +16,55 @@ export type ToolSpec<I = unknown, O = unknown> = {
     readonly inputSchema?: unknown;
     readonly outputSchema?: unknown;
     readonly requiresIdempotencyKey?: boolean;
+    /**
+     * The provider scopes this tool needs — #260's field, made settable by #234.
+     *
+     * It was declared on `ToolDescriptor` and had **no way to be set**: `ToolSpec` did not carry it, so nothing
+     * in the repository could populate it and nothing read it. A field that cannot be written is a field that
+     * documents an intention rather than expressing one, which is the defect class `check:reachability` exists
+     * for — it was missed because the check asks whether declared fields are *read*, and an unwritable field is
+     * never read either.
+     *
+     * Google is the first vendor where it matters: `gmail.send` and `gmail.readonly` are different consents, and
+     * asking for the wrong one is the difference between a security team approving an integration and refusing
+     * it.
+     */
+    readonly requiredScopes?: readonly string[];
     execute(input: I, context: ExecutionContext): Promise<O> | O;
 };
 /** Build a `Tool` from a plain spec: `execute` returns data (or throws); the envelope is handled here. */
 export declare const defineTool: <I = unknown, O = unknown>(spec: ToolSpec<I, O>) => Tool<O>;
 /** A `ToolProvider` serving a fixed set of tools. For dynamic per-tenant tools, implement the port. */
 export declare const toolProvider: (id: string, tools: readonly Tool[]) => ToolProvider;
+/**
+ * The spec a confirmation wrapper accepts — the three classification fields removed.
+ *
+ * Removed rather than defaulted, so passing one is a **compile error** instead of a silent override. "Visible in
+ * review" was the weaker version of this requirement: a reviewer reading `confirms({ …, approvalPolicy: "never" })`
+ * has to notice a contradiction, and the type system can refuse it instead.
+ */
+export type GatedToolSpec<I, O> = Omit<ToolSpec<I, O>, "effect" | "approvalPolicy" | "requiresIdempotencyKey">;
+/**
+ * A tool that writes somewhere outside this system, and therefore waits for a person.
+ *
+ * `effect`, `approvalPolicy` and `requiresIdempotencyKey` are one decision, and this is the word for it. Setting
+ * them individually is three chances to get it wrong, and the failure is silent: `effect: "read"` on a tool that
+ * posts a message skips the approval gate, carries no idempotency key, and nothing in the build objects, because
+ * `read` is a valid value and the compiler cannot know what the function does.
+ *
+ * Across one package that is a code-review problem. Across the twenty-one toolkit packages `docs/23` plans, some
+ * contributed, it is a systemic one — so the safe thing is now shorter to write than the unsafe thing.
+ *
+ * Use `defineTool` directly for a read, or for the rare combination this does not express.
+ */
+export declare const confirms: <I = unknown, O = unknown>(spec: GatedToolSpec<I, O>) => Tool<O>;
+/**
+ * A tool whose effect cannot be undone — a delete, a merge, a send that cannot be recalled.
+ *
+ * Distinct from `confirms` because the *classification* differs and downstream policy reads it: a shadow run
+ * suppresses `destructive` and `external-write` alike, but an operator reviewing what an agent may do wants to
+ * know which of the two a tool is. Collapsing them would lose that, and the answer to "what can this agent
+ * irreversibly do" would stop being answerable from the catalogue.
+ */
+export declare const destroys: <I = unknown, O = unknown>(spec: GatedToolSpec<I, O>) => Tool<O>;
 //# sourceMappingURL=define.d.ts.map

package/dist/tools/define.js

@@ -22,6 +22,9 @@ export const defineTool = (spec) => {
         effect,
         approvalPolicy: spec.approvalPolicy ?? (effect === "external-write" || effect === "destructive" ? "always" : "never"),
         requiresIdempotencyKey: spec.requiresIdempotencyKey ?? (effect === "external-write" || effect === "destructive"),
+        // Omitted rather than defaulted to `[]`: absent means "this vendor has no scopes", which is true of
+        // every wave-1 tool, and an empty array would read as "needs none" — a different claim.
+        ...(spec.requiredScopes === undefined ? {} : { requiredScopes: spec.requiredScopes }),
     };
     return {
         descriptor,
@@ -42,4 +45,27 @@ export const toolProvider = (id, tools) => ({
         return tools;
     },
 });
+/**
+ * A tool that writes somewhere outside this system, and therefore waits for a person.
+ *
+ * `effect`, `approvalPolicy` and `requiresIdempotencyKey` are one decision, and this is the word for it. Setting
+ * them individually is three chances to get it wrong, and the failure is silent: `effect: "read"` on a tool that
+ * posts a message skips the approval gate, carries no idempotency key, and nothing in the build objects, because
+ * `read` is a valid value and the compiler cannot know what the function does.
+ *
+ * Across one package that is a code-review problem. Across the twenty-one toolkit packages `docs/23` plans, some
+ * contributed, it is a systemic one — so the safe thing is now shorter to write than the unsafe thing.
+ *
+ * Use `defineTool` directly for a read, or for the rare combination this does not express.
+ */
+export const confirms = (spec) => defineTool({ ...spec, effect: "external-write", approvalPolicy: "always", requiresIdempotencyKey: true });
+/**
+ * A tool whose effect cannot be undone — a delete, a merge, a send that cannot be recalled.
+ *
+ * Distinct from `confirms` because the *classification* differs and downstream policy reads it: a shadow run
+ * suppresses `destructive` and `external-write` alike, but an operator reviewing what an agent may do wants to
+ * know which of the two a tool is. Collapsing them would lose that, and the answer to "what can this agent
+ * irreversibly do" would stop being answerable from the catalogue.
+ */
+export const destroys = (spec) => defineTool({ ...spec, effect: "destructive", approvalPolicy: "always", requiresIdempotencyKey: true });
 //# sourceMappingURL=define.js.map

package/dist/tools/find.d.ts

@@ -0,0 +1,109 @@
+/**
+ * `find_tools` — REQ-045 (#204), task #210, AC-1 and AC-2.
+ *
+ * Search over tool descriptors, so a catalogue can be *findable* rather than resident. The two-tier loading
+ * already keeps schemas out of context; this keeps the compact entries out too, which is what makes a budget
+ * (AC-3) something other than a way to hide tools from the model permanently.
+ *
+ * ## What is reused, and the one thing that is not
+ *
+ * **Fusion is `fuseByRank`** — the same reciprocal rank fusion, the same `K = 60`, the same normalisation and
+ * the same relevance floor as knowledge retrieval. There is one implementation and both callers use it.
+ *
+ * **Embeddings are the same port.** `EmbeddingProvider`, injected. No second embedding path, no second client,
+ * no second cache format.
+ *
+ * **The keyword signal is not `KeywordIndex`, and that is a finding rather than a shortcut.** `KeywordIndex` is
+ * a Postgres full-text index over `knowledge_chunks`; tools are not rows in that table and putting them there
+ * would mean a write path, a migration, and an index to keep in sync with a registry that is assembled per
+ * request from providers. A corpus of a few hundred short documents that already lives in memory does not need
+ * an index — it needs a scan, and the scan is deterministic and free. AC-2's "no second implementation" is about
+ * not having two rankers; this is one ranker over a corpus the other one cannot hold.
+ *
+ * ## Why the semantic signal is optional
+ *
+ * Without an `EmbeddingProvider` this is keyword-only, and it says so in the result rather than pretending. Most
+ * deployments will not wire embeddings *for tools*: #221 measured selection accuracy as flat from 20 to 200
+ * tools, so the case for `find_tools` is context cost, not accuracy — and a deployment that pays for embeddings
+ * to solve a problem it does not have is exactly the cost this repository keeps refusing to impose by default.
+ */
+import type { EmbeddingProvider } from "../knowledge/index.js";
+import type { ToolCatalogEntry, ToolDescriptor } from "./index.js";
+/** Which signals found a tool. Reported, because "keyword only" is a different confidence from "both agreed". */
+export type ToolSearchSignal = "semantic" | "keyword";
+export type ToolSearchHit = {
+    readonly entry: ToolCatalogEntry;
+    /** 0–1 relative to the best hit for this query. Never comparable across queries. */
+    readonly score: number;
+    readonly signals: readonly ToolSearchSignal[];
+};
+export type ToolSearchOutcome = {
+    readonly hits: readonly ToolSearchHit[];
+    /** The signals actually used. Keyword-only when no embedding provider is wired. */
+    readonly modes: readonly ToolSearchSignal[];
+};
+/**
+ * The absolute floor, and why a relative one is not enough.
+ *
+ * Fused scores are normalised against the best hit, so a query that matched exactly one tool badly gives that
+ * tool a score of 1.0 — the relative floor cannot reject a uniformly poor result set, because something is
+ * always the best of it. Knowledge retrieval solves this with an absolute `semanticFloor` handed to the vector
+ * index; this is the same idea for the keyword signal.
+ *
+ * **2 is one name or category hit, or two words of prose.** A single common word appearing somewhere in a
+ * description is not evidence: "translate this into Welsh" found `parse_csv`, whose description happens to say
+ * "into", and returned it with a perfect score. That was a real result from the first run of this file's tests,
+ * and it is the least-bad-match failure the floor exists to prevent — a model handed the least-bad tool calls it.
+ */
+export declare const MIN_KEYWORD_SCORE = 2;
+export type ToolSearchDeps = {
+    /** Absent means keyword-only — see the note above on why that is the honest default. */
+    readonly embeddings?: EmbeddingProvider;
+    readonly candidates?: number;
+    readonly relevanceFloor?: number;
+    /** The absolute keyword floor. See `MIN_KEYWORD_SCORE`. */
+    readonly minKeywordScore?: number;
+    /** The absolute semantic floor, for the same reason. Defaults to the platform's `SEMANTIC_RELEVANCE_FLOOR`. */
+    readonly minSimilarity?: number;
+};
+/** The compact entry a catalogue shows, derived once so search and catalogue cannot disagree about a tool. */
+export declare const compactEntry: (d: ToolDescriptor) => ToolCatalogEntry;
+export declare const termsOf: (text: string) => readonly string[];
+/** What a tool is embedded and matched as. One string, so both signals read the same document. */
+export declare const documentFor: (entry: ToolCatalogEntry) => string;
+/**
+ * The keyword signal: how many of the query's terms this tool mentions, and where.
+ *
+ * Weighted by field, because a term in the *name* is a different claim from a term buried in prose — a query for
+ * "issue" should rank `github_create_issue` above a tool whose description mentions issues in passing. Weights
+ * are small integers rather than tuned constants: RRF uses only the rank, so their exact values decide ordering
+ * and nothing else, and a fused score cannot be dominated by a badly chosen one.
+ */
+export declare const keywordScore: (entry: ToolCatalogEntry, queryTerms: readonly string[]) => number;
+/**
+ * The same score, divided by document length — and this is what fixed a real ranking defect.
+ *
+ * The 200-tool measurement found `find_tools` returning `archive_post_metrics` above `get_post_metrics`. Both
+ * match the query's terms identically, so the raw scores tied and the tie-break — alphabetical by name — decided
+ * it. Alphabetical order is arbitrary with respect to relevance, and in a catalogue whose near-duplicates are
+ * `<verb>_<object>` it is *systematically* wrong: it prefers whichever verb sorts earliest.
+ *
+ * Length normalisation is the standard answer and it is the correct one here rather than a fitted one: the
+ * distractors are the base tool's description **plus** a qualifier, so they say the same thing less densely. A
+ * short, focused description that matches your query is a better match than a long one that matches it
+ * incidentally. `sqrt` rather than a linear divisor, as in BM25, so a genuinely detailed description is not
+ * punished out of contention.
+ *
+ * The raw score still decides the *floor* (see `MIN_KEYWORD_SCORE`); this decides the *order*. Two values,
+ * because "is this a match at all" and "which match is better" are different questions.
+ */
+export declare const weightedKeywordScore: (entry: ToolCatalogEntry, queryTerms: readonly string[]) => number;
+export type ToolSearch = {
+    search(input: {
+        readonly query: string;
+        readonly tools: readonly ToolDescriptor[];
+        readonly limit: number;
+    }): Promise<ToolSearchOutcome>;
+};
+export declare const createToolSearch: (deps?: ToolSearchDeps) => ToolSearch;
+//# sourceMappingURL=find.d.ts.map