@retinue/agentkit 0.1.0 → 0.2.0

package/dist/toolkit/sandbox.js

@@ -0,0 +1,239 @@
+/**
+ * Running a command somewhere it cannot hurt you — REQ-047 (#206), task #215.
+ *
+ * `shell_exec` is the only tool in this package whose blast radius is not described by its schema. Every other
+ * tool can do one thing to one kind of object; this one can do anything the process can do. And its trigger is
+ * natural language — including language the model merely *read*, in a document, in an issue body, in a Slack
+ * message. Without isolation, a shell tool is a remote code execution endpoint reachable by anyone who can get
+ * text in front of the agent.
+ *
+ * So the sandbox is not a hardening step applied afterwards. It is the thing that makes the tool defensible, and
+ * the tool does not exist without one wired.
+ *
+ * ## What the contract guarantees
+ *
+ * | Guarantee | Why it is not optional |
+ * |---|---|
+ * | No network | A command that can reach the network can exfiltrate anything it can read, and the egress policy does not apply inside a container |
+ * | Read-only root, one writable scratch mount | A command that can write to the image can install a persistent foothold |
+ * | Memory cap | An unbounded allocation takes the host down with it, and that is a denial of service anybody can trigger by asking |
+ * | Wall-clock timeout | `sleep 999` must end as a *timeout*, not as an empty success |
+ * | No TTY | An interactive prompt would hang forever waiting for a person who is not there |
+ * | Output cap, with the truncation reported | Silent truncation makes a model believe it saw the whole answer |
+ * | The exit code in the envelope | Inferring success from output text is guessing; a non-zero exit is a fact |
+ *
+ * ## Gating is by effect, never by reading the command
+ *
+ * `shell_exec` is classified `destructive` and routed through the approval gate. It is tempting to inspect the
+ * command instead — refuse `rm -rf`, allow `ls` — and that is a losing game: `find . -delete`, `>file`, `dd`,
+ * `python -c`, a base64 pipeline. Any list of dangerous shapes is a list somebody gets around, and worse, it
+ * *feels* like protection. A classification cannot be evaded by rephrasing.
+ */
+import { spawn } from "node:child_process";
+import { AgentPlatformError } from "../core/errors.js";
+/** Bytes of stdout and of stderr returned. Beyond this the output is truncated and says so. */
+export const MAX_OUTPUT_BYTES = 64_000;
+/** Wall clock. A model waiting on a hung command is a run holding a worker slot. */
+export const DEFAULT_TIMEOUT_MS = 20_000;
+export const DEFAULT_MEMORY_MB = 256;
+const cap = (text, limit) => Buffer.byteLength(text, "utf8") <= limit
+    ? { text, truncated: false }
+    : { text: Buffer.from(text, "utf8").subarray(0, limit).toString("utf8"), truncated: true };
+/**
+ * Spawn a process and bound it, shared by both adapters.
+ *
+ * The output cap is applied **while reading**, not afterwards: a command that prints a gigabyte would otherwise
+ * be buffered in full before any limit could run, which is the same mistake `readBounded` exists to avoid in the
+ * HTTP client.
+ *
+ * ## Two decisions the first version got wrong, and CI found
+ *
+ * **The whole process group is killed, not the child.** `sh -c "sleep 999"` may exec or may fork, and when it
+ * forks the grandchild survives a `SIGKILL` aimed at its parent — so a timed-out command left a process running
+ * on the host. `detached: true` makes the child a group leader; `process.kill(-pid)` takes the group with it.
+ *
+ * **Resolution is on `exit`, not `close`.** `close` waits for every stdio stream to end, and an orphaned
+ * grandchild *holds the pipe open* — so `sh -c "sleep 5 | cat"` never resolved at all. The timeout fired, the
+ * process was killed, and the promise hung until the test runner gave up thirty seconds later. Reproduced
+ * locally in one line once CI had pointed at it.
+ */
+const boundedSpawn = async (file, args, input) => {
+    const startedAt = Date.now();
+    return new Promise((resolve) => {
+        // A group leader, so a fork inside the shell can be killed with its parent.
+        const child = spawn(file, [...args], { stdio: ["ignore", "pipe", "pipe"], detached: true });
+        let out = "";
+        let err = "";
+        let truncated = false;
+        let reason;
+        const collect = (stream, append) => {
+            stream.on("data", (chunk) => {
+                const capped = cap(chunk.toString("utf8"), MAX_OUTPUT_BYTES);
+                if (capped.truncated)
+                    truncated = true;
+                append(capped.text);
+            });
+        };
+        collect(child.stdout, (chunk) => {
+            const capped = cap(out + chunk, MAX_OUTPUT_BYTES);
+            out = capped.text;
+            if (capped.truncated)
+                truncated = true;
+        });
+        collect(child.stderr, (chunk) => {
+            const capped = cap(err + chunk, MAX_OUTPUT_BYTES);
+            err = capped.text;
+            if (capped.truncated)
+                truncated = true;
+        });
+        /**
+         * The group, not the process.
+         *
+         * `-pid` addresses the group `detached` created. It throws if the group is already gone — a command that
+         * finished between the timer firing and this line — so the fallback is the plain kill, and neither is
+         * allowed to reject the promise.
+         */
+        const killGroup = () => {
+            try {
+                if (child.pid !== undefined)
+                    process.kill(-child.pid, "SIGKILL");
+            }
+            catch {
+                child.kill("SIGKILL");
+            }
+        };
+        const timer = setTimeout(() => {
+            reason = "timeout";
+            input.onKill?.();
+            killGroup();
+        }, input.timeoutMs);
+        // `exit` and `close` can both fire, and after a group kill only one of them may. Whichever arrives first
+        // answers, and the guard is what makes listening to both safe rather than a double resolution.
+        let settled = false;
+        const settle = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve(result);
+        };
+        child.on("error", (error) => {
+            settle({
+                ok: false,
+                exitCode: null,
+                stdout: out,
+                stderr: `${err}${error.message}`,
+                truncated,
+                reason: "spawn-failed",
+                durationMs: Date.now() - startedAt,
+            });
+        });
+        const finish = (code) => settle({
+            // A timeout is not a completed command, whatever it printed before it died.
+            ok: reason === undefined,
+            exitCode: code,
+            stdout: out,
+            stderr: err,
+            truncated,
+            ...(reason === undefined ? {} : { reason }),
+            durationMs: Date.now() - startedAt,
+        });
+        /**
+         * `exit` fires when the process dies; `close` waits for its stdio to end.
+         *
+         * Preferring `exit` is the fix: a grandchild holding the pipe open means `close` may never come, and the
+         * output collected so far is still the output. `close` stays wired for the ordinary case, where it arrives
+         * a moment later with the last of the buffer flushed.
+         */
+        child.on("exit", (code) => finish(code));
+        child.on("close", (code) => finish(code));
+    });
+};
+/**
+ * The argv, built separately so it can be asserted on.
+ *
+ * Every security property of this adapter *is* this array. A test that ran a command and checked its output would
+ * pass just as well with `--network=none` missing, so the argv is what the tests read — and the flags come before
+ * `extraArgs`, so a deployment adding options cannot quietly drop one.
+ */
+export const dockerArgs = (config, request) => [
+    "run",
+    "--rm",
+    // No network at all. Not a restricted network: a command that can resolve a name can exfiltrate through it.
+    "--network=none",
+    // The image is immutable; only the scratch mount is writable, and it is a tmpfs that dies with the container.
+    "--read-only",
+    "--tmpfs=/scratch:rw,size=16m,mode=1777",
+    `--memory=${config.memoryMb ?? DEFAULT_MEMORY_MB}m`,
+    // Without this a memory-capped container can still be pushed into swap and take the host's disk with it.
+    `--memory-swap=${config.memoryMb ?? DEFAULT_MEMORY_MB}m`,
+    "--pids-limit=128",
+    "--cap-drop=ALL",
+    "--security-opt=no-new-privileges",
+    // Not root inside the container either. `--read-only` makes most of that moot; this makes the rest of it moot.
+    "--user=65534:65534",
+    "--workdir=/scratch",
+    // No TTY, and stdin closed: an interactive prompt has nobody to answer it and would hold the slot until the
+    // timeout, reported as a timeout, which is a confusing way to learn that a command asked a question.
+    ...(config.extraArgs ?? []),
+    config.image,
+    config.shell ?? "sh",
+    "-c",
+    request.command,
+];
+/**
+ * The real adapter: one container per command, destroyed after.
+ *
+ * Not a pool. A reused container is a container a previous command could have left something in, and the whole
+ * proposition here is that a command cannot affect anything outside itself.
+ */
+export const createDockerSandbox = (config) => ({
+    id: `docker:${config.image}`,
+    async run(request) {
+        const timeoutMs = request.timeoutMs ?? config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        const args = dockerArgs({ ...config, ...(request.memoryMb === undefined ? {} : { memoryMb: request.memoryMb }) }, request);
+        const result = await boundedSpawn(config.docker ?? "docker", args, { timeoutMs });
+        /**
+         * 137 is SIGKILL, and inside a memory-capped container that is almost always the OOM killer.
+         *
+         * Reported as `memory` rather than left as a bare exit code, because "exit 137" is a number a reader has to
+         * look up and "the command ran out of memory" is the finding. Not claimed when we did the killing ourselves:
+         * a timeout is also a SIGKILL, and it is already named.
+         */
+        return result.exitCode === 137 && result.reason === undefined
+            ? { ...result, ok: false, reason: "memory" }
+            : result;
+    },
+});
+/**
+ * The development adapter, which **refuses to exist** unless a deployment says so in words.
+ *
+ * The refusal is at construction rather than at the call, so a misconfiguration is a boot failure rather than a
+ * surprise the first time somebody asks the agent to run something. And the message says what to do instead,
+ * because "not allowed" without a next step is how a flag gets set to make an error go away.
+ *
+ * It provides the timeout and the output cap. It provides **none** of the isolation: no network isolation, no
+ * memory cap, no read-only filesystem, no dropped capabilities. The contract's table describes what a sandbox
+ * guarantees; this adapter meets one row of it, and saying so is the point.
+ */
+export const createLocalSandbox = (config) => {
+    if (config.allowUnsafeLocalExecution !== true) {
+        throw new AgentPlatformError({
+            code: "invalid_input",
+            message: "The local sandbox runs commands on this host with no isolation: no network isolation, no memory cap, " +
+                "no read-only filesystem. It is for development only, and it requires " +
+                "`allowUnsafeLocalExecution: true` in so many words. For anything else, use createDockerSandbox — or " +
+                "leave shell_exec unwired, which is the default and is a legitimate answer.",
+            retryable: false,
+        });
+    }
+    return {
+        id: "local:unsafe",
+        async run(request) {
+            return boundedSpawn(config.shell ?? "sh", ["-c", request.command], {
+                timeoutMs: request.timeoutMs ?? config.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+            });
+        },
+    };
+};
+//# sourceMappingURL=sandbox.js.map

package/dist/toolkit/web.d.ts

@@ -87,6 +87,19 @@ export type SearchProvider = {
     /** Build the request URL for a query. The key belongs in `headers`, not here, wherever the provider allows it. */
     readonly endpoint: (query: string, limit: number) => string;
     readonly headers?: Readonly<Record<string, string>>;
+    /**
+     * `POST`, for the providers that require it.
+     *
+     * Added when the first real adapters were written (#214): this contract was GET-only, and three of the four
+     * most-used providers — Tavily, Serper, Exa — are POST with a JSON body. A GET-only seam would have limited the
+     * catalogue to Brave and self-hosted SearXNG, which is not a "one contract, several providers" rule so much as
+     * a rule with two providers.
+     *
+     * Optional, so every existing GET provider is unchanged.
+     */
+    readonly method?: "GET" | "POST";
+    /** The request body for a `POST` provider. Ignored for `GET`. */
+    readonly body?: (query: string, limit: number) => unknown;
     /** Read the provider's JSON into hits. Returning `[]` means "searched, found nothing". */
     readonly parse: (payload: unknown) => readonly SearchHit[];
 };

package/dist/toolkit/web.js

@@ -97,10 +97,16 @@ export const createWebSearch = (config = {}) => {
                     "directly.",
             };
         }
+        const method = provider.method ?? "GET";
         const outcome = await client.request({
             url: provider.endpoint(query, limit),
-            headers: provider.headers,
+            ...(provider.headers === undefined ? {} : { headers: provider.headers }),
+            ...(method === "POST"
+                ? { method, body: JSON.stringify(provider.body?.(query, limit) ?? { query }) }
+                : {}),
             accept: "application/json",
+            // Parsed by the provider's own `parse` and never shown to the model verbatim, so the untrusted-content
+            // envelope would only corrupt the JSON. The *hits* are fenced downstream, where they are read as prose.
             fence: false,
         });
         if (!outcome.ok) {

package/dist/tools/budget.d.ts

@@ -0,0 +1,28 @@
+/**
+ * What a tool costs a catalogue — REQ-045 (#204), task #210, AC-3.
+ *
+ * The budget itself is in `core/budget.ts`, shared with the skill catalogue. What is here is the part that knows
+ * about tools: how many tokens one entry is, which is the only thing the generic algorithm cannot know.
+ */
+import type { ToolCatalogEntry, ToolDescriptor } from "./index.js";
+/**
+ * Deliberately **not** re-exported here.
+ *
+ * `applyTokenBudget`, `TokenBudget` and `BudgetOutcome` live in `core/` and reach consumers through
+ * `@retinue/agentkit/runtime`. Re-exporting them from `./tools` as well gave one name two homes, which
+ * `public-surface.test.ts` fails on — and it is right to: a consumer reading two import paths for one function
+ * has to guess which is canonical, and the two will not stay in step.
+ */
+/**
+ * What a compact catalogue entry costs.
+ *
+ * The fields a model actually reads, plus a small per-entry allowance for the JSON or Markdown scaffolding the
+ * assembler wraps them in — measured at ~35 tokens per entry in #221's harness, which is what this reproduces.
+ * An estimate rather than a tokenizer call: the point is a stable ceiling, and a budget that shifted with the
+ * model's tokenizer would make one deployment's 4,000 tokens another's 4,600.
+ */
+export declare const ENTRY_OVERHEAD_TOKENS = 6;
+export declare const entryTokens: (entry: ToolCatalogEntry) => number;
+/** A preloaded tool carries its schemas, which is usually most of its cost. */
+export declare const descriptorTokens: (descriptor: ToolDescriptor) => number;
+//# sourceMappingURL=budget.d.ts.map

package/dist/tools/budget.js

@@ -0,0 +1,35 @@
+/**
+ * What a tool costs a catalogue — REQ-045 (#204), task #210, AC-3.
+ *
+ * The budget itself is in `core/budget.ts`, shared with the skill catalogue. What is here is the part that knows
+ * about tools: how many tokens one entry is, which is the only thing the generic algorithm cannot know.
+ */
+import { estimateTokens } from "../core/tokens.js";
+/**
+ * Deliberately **not** re-exported here.
+ *
+ * `applyTokenBudget`, `TokenBudget` and `BudgetOutcome` live in `core/` and reach consumers through
+ * `@retinue/agentkit/runtime`. Re-exporting them from `./tools` as well gave one name two homes, which
+ * `public-surface.test.ts` fails on — and it is right to: a consumer reading two import paths for one function
+ * has to guess which is canonical, and the two will not stay in step.
+ */
+/**
+ * What a compact catalogue entry costs.
+ *
+ * The fields a model actually reads, plus a small per-entry allowance for the JSON or Markdown scaffolding the
+ * assembler wraps them in — measured at ~35 tokens per entry in #221's harness, which is what this reproduces.
+ * An estimate rather than a tokenizer call: the point is a stable ceiling, and a budget that shifted with the
+ * model's tokenizer would make one deployment's 4,000 tokens another's 4,600.
+ */
+export const ENTRY_OVERHEAD_TOKENS = 6;
+export const entryTokens = (entry) => estimateTokens(`${entry.name} ${entry.label} ${entry.category} ${entry.effect} ${entry.description}`) +
+    ENTRY_OVERHEAD_TOKENS;
+/** A preloaded tool carries its schemas, which is usually most of its cost. */
+export const descriptorTokens = (descriptor) => entryTokens({
+    name: descriptor.name,
+    label: descriptor.label,
+    description: descriptor.description,
+    category: descriptor.category,
+    effect: descriptor.effect,
+}) + estimateTokens(JSON.stringify(descriptor.inputSchema ?? {}));
+//# sourceMappingURL=budget.js.map

package/dist/tools/credentials.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Credentials, referenced rather than held — REQ-047 (#206), task #214, AC-5.
+ *
+ * A toolkit needs a token. 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.
+ */
+import type { ExecutionContext } from "../core/context.js";
+import type { PlatformError } from "../core/errors.js";
+/** An opaque handle. Its meaning belongs to the resolver, and no tool interprets it. */
+export type CredentialRef = string;
+export interface CredentialResolver {
+    /**
+     * The secret behind a reference, for this caller.
+     *
+     * Takes the context because a reference is resolved *per tenant*: two tenants using the same toolkit name the
+     * same credential and mean different secrets, and a resolver that ignored the caller would hand one tenant
+     * another's token.
+     */
+    resolve(input: {
+        readonly ref: CredentialRef;
+        readonly context: ExecutionContext;
+    }): Promise<string>;
+}
+export declare const credentialMissing: (ref: CredentialRef, detail?: string) => PlatformError;
+/**
+ * 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.
+ */
+export declare const createStaticCredentialResolver: (secrets: Readonly<Record<string, string>>) => CredentialResolver;
+//# sourceMappingURL=credentials.d.ts.map

package/dist/tools/credentials.js

@@ -0,0 +1,54 @@
+/**
+ * Credentials, referenced rather than held — REQ-047 (#206), task #214, AC-5.
+ *
+ * A toolkit needs a token. 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.
+ */
+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,
+});
+/**
+ * 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.
+ */
+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 secret;
+    },
+});
+//# sourceMappingURL=credentials.js.map

package/dist/tools/define.d.ts

@@ -22,4 +22,35 @@ export type ToolSpec<I = unknown, O = unknown> = {
 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

@@ -42,4 +42,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