@crewhaus/tool-capability 0.0.0-stage → 0.8.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,9 @@
+CrewHaus Factory
+Copyright 2026 Max Meier
+
+This product includes software developed by Max Meier
+(operating as StudioMax — https://studiomax.io) and contributors.
+
+The CrewHaus name and logo are trademarks of Max Meier. See
+https://github.com/crewhaus/factory/blob/main/TRADEMARK.md for the
+use-of-marks policy.

package/README.md

@@ -1,3 +1,11 @@
-# Temporary Holding Version
+# @crewhaus/tool-capability
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+ToolRegistry: what builtin tools exist, and which of them this harness is actually running
+
+Part of [CrewHaus](https://github.com/crewhaus/factory). Most people install the CLI (`npm install -g crewhaus`) rather than this package.
+
+Which tools a spec can turn on, and how: [tools reference](https://github.com/crewhaus/docs/blob/main/TOOLS-REFERENCE.md).
+
+Requires [Bun](https://bun.sh) `>=1.3.14`; plain Node is not supported.
+
+[Source](https://github.com/crewhaus/factory/tree/main/packages/tool-capability)

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import type { RegisteredTool } from "@crewhaus/tool-catalog";
+export { DEFAULT_LIMIT, MAX_LIMIT, MCP_NOTE, type RegistryAnswer, type RegistryQuery, type RegistryRow, buildRegistryAnswer, firstSentence, howToRequest, knownCategories, liveToolNames, matchesQuery, normalizeCategory, } from "./lib";
+export declare const toolRegistry: RegisteredTool;

package/dist/index.js

@@ -0,0 +1,92 @@
+/**
+ * @crewhaus/tool-capability — `ToolRegistry`, the answer to "what exists that
+ * I am not running".
+ *
+ * TWO QUESTIONS, ONE OF WHICH WAS ALREADY ANSWERED.
+ *
+ *   "What can I call right now?" is `ListTools` (`@crewhaus/runtime-core`).
+ *   It reads the bound catalog, covers MCP peers that connected after boot,
+ *   and is authoritative. Nothing here duplicates it.
+ *
+ *   "What exists in this framework that I was not given?" had no answer at
+ *   all. A compiled bundle contains only the tools its spec granted, so the
+ *   tools it lacks are, from inside, invisible — an agent could not name one,
+ *   let alone say what it does. `ToolRegistry` reads the generated manifest in
+ *   `@crewhaus/tool-registry-manifest` and reports both halves.
+ *
+ * THIS IS ERGONOMICS, NOT A CONTROL. Leaving a tool out of `tools:` is what
+ * shapes a harness; this tool only makes the omission legible, so an operator
+ * can see what the agent is missing and decide. In any harness that grants
+ * bash, file write or code execution the agent can edit `crewhaus.yaml`
+ * itself, so nothing here stands between an agent and a tool — and nothing in
+ * its description, its output or its docs says otherwise.
+ *
+ * WHY ITS OWN PACKAGE. The manifest is roughly 450 KB of description text.
+ * `ListTools` lives in `runtime-core`, which is in every bundle of every
+ * shape, so growing it would put that text into harnesses that never asked
+ * for it. `toolInventory` is the wrong axis — it reads a SPEC file, cannot
+ * see MCP tools bound at connect time, and its package depends on
+ * `@crewhaus/compiler`, which drags all fourteen target emitters. A separate
+ * spec-granted tool makes the cost declared, which is what
+ * `collectCrewhausDeps` measures anyway.
+ *
+ * WHAT IT READS. `granted` is computed against the LIVE catalog off
+ * `ToolExecuteContext.bridge`, not against the spec — so an MCP tool
+ * registered an hour after boot counts as bound, the same way `ListTools`
+ * counts it. The bridge is read structurally (see `lib.ts`) so this package
+ * does not depend on the sub-agent fabric.
+ */
+import { buildTool } from "@crewhaus/tool-builder";
+import { REGISTRY_VERSION, TOOL_REGISTRY } from "@crewhaus/tool-registry-manifest";
+import { z } from "zod";
+import { DEFAULT_LIMIT, MAX_LIMIT, buildRegistryAnswer, liveToolNames } from "./lib";
+export { DEFAULT_LIMIT, MAX_LIMIT, MCP_NOTE, buildRegistryAnswer, firstSentence, howToRequest, knownCategories, liveToolNames, matchesQuery, normalizeCategory, } from "./lib";
+const json = (value) => JSON.stringify(value);
+export const toolRegistry = buildTool({
+    name: "ToolRegistry",
+    description: "List the builtin tools CrewHaus ships and mark which ones this harness is actually running, so you can name a tool you do not have and say what it would do. `ListTools` answers what you can call right now; this one also covers what you cannot. Search with `query`, narrow with `category` (`all-fs` or `fs`), or pass one `key` for that tool's full description. Rows you are not running come with a line on how to ask for them. It reports; it enables nothing, and a tool appears here whether or not this harness will ever have it. Builtins only: a spec declares an MCP server rather than the tools it offers, so which MCP tools exist elsewhere cannot be answered offline.",
+    inputSchema: z
+        .object({
+        query: z
+            .string()
+            .optional()
+            .describe("lexical search over key, name, description, category and keywords"),
+        category: z
+            .string()
+            .optional()
+            .describe('one category, written either way: "all-fs" or "fs"'),
+        key: z
+            .string()
+            .optional()
+            .describe("one tool's camelCase spec key; returns that tool with its whole description"),
+        only: z
+            .enum(["granted", "unlisted", "all"])
+            .optional()
+            .describe('"granted" = bound here, "unlisted" = exists but not bound; default "all"'),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(MAX_LIMIT)
+            .optional()
+            .describe(`rows to return, up to ${MAX_LIMIT} (default ${DEFAULT_LIMIT})`),
+    })
+        .strict(),
+    readOnly: true,
+    destructive: false,
+    concurrencySafe: true,
+    requiresSandbox: false,
+    requireJustification: false,
+    scope: "internal",
+    execute: async (input, ctx) => {
+        const answer = buildRegistryAnswer({
+            registry: TOOL_REGISTRY,
+            version: REGISTRY_VERSION,
+            live: liveToolNames(ctx?.bridge),
+            input,
+        });
+        if ("error" in answer)
+            return `[ToolRegistry] ${answer.error}`;
+        return json(answer);
+    },
+});

package/dist/lib.d.ts

@@ -0,0 +1,114 @@
+/**
+ * The pure half of `ToolRegistry` — everything that can be decided from a
+ * manifest, a set of live tool names and an input object, with no runtime
+ * attached. Kept separate so the answer can be tested against a hand-built
+ * catalog instead of a booted harness.
+ */
+import type { RegistryEntry } from "@crewhaus/tool-registry-manifest";
+/** One tool as `ToolRegistry` reports it in a list. */
+export type RegistryRow = {
+    readonly key: string;
+    readonly name: string;
+    /** First sentence in a list; the whole description for a single-`key` ask. */
+    readonly description: string;
+    readonly readOnly: boolean;
+    readonly destructive: boolean;
+    readonly scope: string;
+    readonly ioCapability?: string;
+    readonly requiresSandbox: boolean;
+    readonly requireJustification: boolean;
+    readonly categories: ReadonlyArray<string>;
+    readonly package: string;
+    readonly keywords?: ReadonlyArray<string>;
+    /** Present only when the live catalog was readable. */
+    readonly granted?: boolean;
+    /** Present only on a row this harness is not running. */
+    readonly howToRequest?: string;
+};
+export type RegistryQuery = {
+    readonly query?: string;
+    readonly category?: string;
+    readonly key?: string;
+    readonly only?: "granted" | "unlisted" | "all";
+    readonly limit?: number;
+};
+export declare const DEFAULT_LIMIT = 25;
+export declare const MAX_LIMIT = 100;
+/**
+ * The asymmetry, stated in every answer.
+ *
+ * `registerMcpServer` registers whatever a server offers when it connects,
+ * and `watchMcpServer` re-diffs that list mid-run; a spec names the SERVER,
+ * never its tools. So "which MCP tools exist that I am not running" has no
+ * offline answer, and an answer that quietly covered builtins only would read
+ * as complete. Saying it costs one line and is the difference between a short
+ * list and a wrong one.
+ */
+export declare const MCP_NOTE = "Builtin tools only, on BOTH sides. A spec declares an MCP server, not the tools it offers, and a server's tools are only known once it connects. So MCP tools you DO have are missing from `granted` \u2014 call ListTools for the whole live toolset \u2014 and which MCP tools exist beyond this harness has no offline answer at all.";
+/** What an agent can do about a tool it is not running. */
+export declare function howToRequest(key: string): string;
+/** The category names the manifest actually uses — leaves and roll-ups alike. */
+export declare function knownCategories(registry: Readonly<Record<string, RegistryEntry>>): ReadonlyArray<string>;
+/** `all-fs` and `fs` mean the same category. */
+export declare function normalizeCategory(raw: string): string;
+export declare function unknownCategoryMessage(raw: string, registry: Readonly<Record<string, RegistryEntry>>): string;
+/** The first sentence, which is what a list needs. `ListTools` does the same. */
+export declare function firstSentence(description: string): string;
+/** Lexical match over the fields a person would search by. */
+export declare function matchesQuery(entry: RegistryEntry, query: string): boolean;
+/**
+ * Read the live tool catalog structurally off the execution context.
+ *
+ * Deliberately structural rather than typed: `RuntimeBridge` lives in
+ * `@crewhaus/agent-context-isolation`, and depending on it here would pull a
+ * sub-agent fabric into every bundle that wants to list tools. The tree
+ * already re-declares shapes this way twice (`tool-approvals` re-declares
+ * `PendingApproval`, `tools-cli` re-declares `ToolLike`), and `tool-task`
+ * reads the same bridge field.
+ *
+ * Returns `undefined` — not an empty set — when the catalog is not reachable.
+ * The two are completely different answers: an empty set would say "you are
+ * running nothing", and the caller must be able to say "I could not tell"
+ * instead of reporting every builtin as missing.
+ */
+export declare function liveToolNames(bridge: unknown): ReadonlySet<string> | undefined;
+export type RegistryAnswer = {
+    readonly version: string;
+    readonly liveCatalog: "read" | "unavailable";
+    readonly counts: {
+        readonly total: number;
+        readonly matched: number;
+        readonly shown: number;
+        readonly granted?: number;
+        readonly unlisted?: number;
+        /**
+         * Bound tools this manifest cannot describe — MCP tools and any tool a
+         * host registered programmatically. Reported as a number rather than
+         * silently dropped, so `granted` is never mistaken for the whole toolset.
+         */
+        readonly otherBound?: number;
+    };
+    readonly granted?: ReadonlyArray<RegistryRow>;
+    readonly unlisted?: ReadonlyArray<RegistryRow>;
+    /** Used instead of the split when the live catalog could not be read. */
+    readonly tools?: ReadonlyArray<RegistryRow>;
+    readonly truncated: boolean;
+    readonly note: string;
+};
+/**
+ * Build the answer.
+ *
+ * `live` is the set of tool names bound to this runtime right now, or
+ * `undefined` when that could not be read. Which builtins a harness HAS is
+ * read from that live catalog rather than from the spec, so a tool an MCP
+ * peer registered an hour after boot counts as bound — the same reason
+ * `ListTools` reads the catalog and not the spec.
+ */
+export declare function buildRegistryAnswer(args: {
+    readonly registry: Readonly<Record<string, RegistryEntry>>;
+    readonly version: string;
+    readonly live: ReadonlySet<string> | undefined;
+    readonly input: RegistryQuery;
+}): RegistryAnswer | {
+    readonly error: string;
+};

package/dist/lib.js

@@ -0,0 +1,251 @@
+export const DEFAULT_LIMIT = 25;
+export const MAX_LIMIT = 100;
+/**
+ * The asymmetry, stated in every answer.
+ *
+ * `registerMcpServer` registers whatever a server offers when it connects,
+ * and `watchMcpServer` re-diffs that list mid-run; a spec names the SERVER,
+ * never its tools. So "which MCP tools exist that I am not running" has no
+ * offline answer, and an answer that quietly covered builtins only would read
+ * as complete. Saying it costs one line and is the difference between a short
+ * list and a wrong one.
+ */
+export const MCP_NOTE = "Builtin tools only, on BOTH sides. A spec declares an MCP server, not the tools it offers, and a server's tools are only known once it connects. So MCP tools you DO have are missing from `granted` — call ListTools for the whole live toolset — and which MCP tools exist beyond this harness has no offline answer at all.";
+/** What an agent can do about a tool it is not running. */
+export function howToRequest(key) {
+    return `Not bound here. Ask the person running this harness to add "${key}" to tools: in crewhaus.yaml.`;
+}
+/** The category names the manifest actually uses — leaves and roll-ups alike. */
+export function knownCategories(registry) {
+    const out = new Set();
+    for (const entry of Object.values(registry))
+        for (const c of entry.categories)
+            out.add(c);
+    return [...out].sort();
+}
+/** `all-fs` and `fs` mean the same category. */
+export function normalizeCategory(raw) {
+    return raw.startsWith("all-") ? raw.slice("all-".length) : raw;
+}
+export function unknownCategoryMessage(raw, registry) {
+    const name = normalizeCategory(raw);
+    const known = knownCategories(registry);
+    const near = known.filter((k) => k.includes(name) || name.includes(k)).slice(0, 3);
+    const hint = near.length > 0 ? ` Did you mean ${near.map((k) => `all-${k}`).join(", ")}?` : "";
+    // The note rides on this too. A reader who asked for a category that does
+    // not exist is one step from concluding the category has no tools, and the
+    // categories here cover builtins only.
+    return `unknown tool category "${raw}".${hint} There are ${known.length} categories; ask with no category to see them on the rows. ${MCP_NOTE}`;
+}
+/** The first sentence, which is what a list needs. `ListTools` does the same. */
+export function firstSentence(description) {
+    return description.split(/(?<=[.!?])\s/)[0] ?? description;
+}
+/** Lexical match over the fields a person would search by. */
+export function matchesQuery(entry, query) {
+    const needle = query.toLowerCase();
+    if (needle.length === 0)
+        return true;
+    if (entry.key.toLowerCase().includes(needle))
+        return true;
+    if (entry.name.toLowerCase().includes(needle))
+        return true;
+    if (entry.description.toLowerCase().includes(needle))
+        return true;
+    if (entry.categories.some((c) => c.toLowerCase().includes(needle)))
+        return true;
+    return entry.keywords.some((k) => k.toLowerCase().includes(needle));
+}
+/**
+ * Read the live tool catalog structurally off the execution context.
+ *
+ * Deliberately structural rather than typed: `RuntimeBridge` lives in
+ * `@crewhaus/agent-context-isolation`, and depending on it here would pull a
+ * sub-agent fabric into every bundle that wants to list tools. The tree
+ * already re-declares shapes this way twice (`tool-approvals` re-declares
+ * `PendingApproval`, `tools-cli` re-declares `ToolLike`), and `tool-task`
+ * reads the same bridge field.
+ *
+ * Returns `undefined` — not an empty set — when the catalog is not reachable.
+ * The two are completely different answers: an empty set would say "you are
+ * running nothing", and the caller must be able to say "I could not tell"
+ * instead of reporting every builtin as missing.
+ */
+export function liveToolNames(bridge) {
+    if (typeof bridge !== "object" || bridge === null)
+        return undefined;
+    const tools = bridge.tools;
+    if (!Array.isArray(tools))
+        return undefined;
+    const names = new Set();
+    for (const t of tools) {
+        if (typeof t === "object" && t !== null) {
+            const name = t.name;
+            if (typeof name === "string")
+                names.add(name);
+        }
+    }
+    return names;
+}
+function toRow(entry, opts) {
+    return {
+        key: entry.key,
+        name: entry.name,
+        description: opts.full ? entry.description : firstSentence(entry.description),
+        readOnly: entry.readOnly,
+        destructive: entry.destructive,
+        scope: entry.scope,
+        ...(entry.ioCapability !== undefined ? { ioCapability: entry.ioCapability } : {}),
+        requiresSandbox: entry.requiresSandbox,
+        requireJustification: entry.requireJustification,
+        categories: entry.categories,
+        package: entry.package,
+        ...(opts.full ? { keywords: entry.keywords } : {}),
+        ...(opts.granted !== undefined ? { granted: opts.granted } : {}),
+        ...(opts.granted === false ? { howToRequest: howToRequest(entry.key) } : {}),
+    };
+}
+/**
+ * Build the answer.
+ *
+ * `live` is the set of tool names bound to this runtime right now, or
+ * `undefined` when that could not be read. Which builtins a harness HAS is
+ * read from that live catalog rather than from the spec, so a tool an MCP
+ * peer registered an hour after boot counts as bound — the same reason
+ * `ListTools` reads the catalog and not the spec.
+ */
+export function buildRegistryAnswer(args) {
+    const { registry, version, live, input } = args;
+    const only = input.only ?? "all";
+    const limit = Math.min(input.limit ?? DEFAULT_LIMIT, MAX_LIMIT);
+    if (live === undefined && only !== "all") {
+        return {
+            error: `ToolRegistry could not read this runtime's live tool catalog, so it cannot answer only: "${only}". Ask again without \`only\` to get the tools that exist, or call ListTools for what is bound right now. ${MCP_NOTE}`,
+        };
+    }
+    const all = Object.values(registry);
+    // Bound names this manifest has no row for: MCP tools, and anything a host
+    // registered programmatically. Counting them is what keeps `granted` from
+    // reading as "everything I have".
+    const manifestNames = new Set(all.map((e) => e.name));
+    const otherBound = live === undefined ? undefined : [...live].filter((n) => !manifestNames.has(n)).length;
+    // A single key is a detail lookup, not a search: it answers with the whole
+    // description rather than the first sentence, and ignores the other filters.
+    if (input.key !== undefined) {
+        // `Object.hasOwn`, not a bare index: `TOOL_REGISTRY` is an object literal,
+        // so a bare lookup reaches Object.prototype and `key: "constructor"` comes
+        // back as a function rather than as `undefined`. The row built from it
+        // would name a tool called "Object" and tell the reader to ask an operator
+        // to add "constructor" to `tools:` — a confabulated tool from the one tool
+        // whose whole job is saying truthfully what exists.
+        const entry = Object.hasOwn(registry, input.key) ? registry[input.key] : undefined;
+        if (entry === undefined) {
+            const near = Object.keys(registry)
+                .filter((k) => k.toLowerCase().includes(input.key?.toLowerCase() ?? ""))
+                .slice(0, 5);
+            const hint = near.length > 0 ? ` Close matches: ${near.join(", ")}.` : "";
+            return {
+                error: `no builtin tool has the key "${input.key}".${hint} ${MCP_NOTE}`,
+            };
+        }
+        const isGranted = live === undefined ? undefined : live.has(entry.name);
+        const row = toRow(entry, {
+            full: true,
+            ...(isGranted !== undefined ? { granted: isGranted } : {}),
+        });
+        const counts = { total: all.length, matched: 1, shown: 1 };
+        if (live === undefined) {
+            return {
+                version,
+                liveCatalog: "unavailable",
+                counts,
+                tools: [row],
+                truncated: false,
+                note: `${unavailableNote()} ${MCP_NOTE}`,
+            };
+        }
+        return {
+            version,
+            liveCatalog: "read",
+            counts: {
+                ...counts,
+                granted: isGranted === true ? 1 : 0,
+                unlisted: isGranted === true ? 0 : 1,
+                ...(otherBound !== undefined ? { otherBound } : {}),
+            },
+            granted: isGranted === true ? [row] : [],
+            unlisted: isGranted === true ? [] : [row],
+            truncated: false,
+            note: MCP_NOTE,
+        };
+    }
+    let matched = all;
+    if (input.category !== undefined) {
+        const name = normalizeCategory(input.category);
+        if (!knownCategories(registry).includes(name)) {
+            return { error: unknownCategoryMessage(input.category, registry) };
+        }
+        matched = matched.filter((e) => e.categories.includes(name));
+    }
+    if (input.query !== undefined) {
+        matched = matched.filter((e) => matchesQuery(e, input.query ?? ""));
+    }
+    matched = [...matched].sort((a, b) => a.key.localeCompare(b.key));
+    if (live === undefined) {
+        const shown = matched.slice(0, limit);
+        return {
+            version,
+            liveCatalog: "unavailable",
+            counts: { total: all.length, matched: matched.length, shown: shown.length },
+            tools: shown.map((e) => toRow(e, { full: false })),
+            truncated: shown.length < matched.length,
+            note: `${unavailableNote()} ${MCP_NOTE}`,
+        };
+    }
+    const grantedEntries = matched.filter((e) => live.has(e.name));
+    const unlistedEntries = matched.filter((e) => !live.has(e.name));
+    const wantGranted = only === "all" || only === "granted";
+    const wantUnlisted = only === "all" || only === "unlisted";
+    // How the page is spent.
+    //
+    // `only` gets the whole budget, because asking for one half and being given
+    // half of it is a page nobody wanted. `all` splits it, and the reason is the
+    // whole point of this tool: filling the page with what a harness already has
+    // would push out what it does not, which is the half that cannot be got from
+    // `ListTools`. Each side still takes whatever the other does not use, so a
+    // small answer is never padded with blank space.
+    let grantedCap = 0;
+    let unlistedCap = 0;
+    if (only === "granted")
+        grantedCap = limit;
+    else if (only === "unlisted")
+        unlistedCap = limit;
+    else {
+        grantedCap = Math.min(grantedEntries.length, Math.ceil(limit / 2));
+        unlistedCap = Math.min(unlistedEntries.length, limit - grantedCap);
+        grantedCap = Math.min(grantedEntries.length, limit - unlistedCap);
+    }
+    const grantedShown = wantGranted ? grantedEntries.slice(0, grantedCap) : [];
+    const unlistedShown = wantUnlisted ? unlistedEntries.slice(0, unlistedCap) : [];
+    const shown = grantedShown.length + unlistedShown.length;
+    const askedFor = (wantGranted ? grantedEntries.length : 0) + (wantUnlisted ? unlistedEntries.length : 0);
+    return {
+        version,
+        liveCatalog: "read",
+        counts: {
+            total: all.length,
+            matched: matched.length,
+            shown,
+            granted: grantedEntries.length,
+            unlisted: unlistedEntries.length,
+            ...(otherBound !== undefined ? { otherBound } : {}),
+        },
+        granted: grantedShown.map((e) => toRow(e, { full: false, granted: true })),
+        unlisted: unlistedShown.map((e) => toRow(e, { full: false, granted: false })),
+        truncated: shown < askedFor,
+        note: MCP_NOTE,
+    };
+}
+function unavailableNote() {
+    return "This runtime's live tool catalog was not reachable from this call, so no row says whether you are running it — these are the tools that exist. Call ListTools for what is bound right now.";
+}

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@crewhaus/tool-capability",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.8.1",
+  "type": "module",
+  "description": "ToolRegistry: what builtin tools exist, and which of them this harness is actually running",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "test": "bun test src"
+  },
+  "dependencies": {
+    "@crewhaus/tool-builder": "0.8.1",
+    "@crewhaus/tool-catalog": "0.8.1",
+    "@crewhaus/tool-registry-manifest": "0.8.1",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@crewhaus/tool-executor": "workspace:*"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Max Meier",
+    "email": "max@crewhaus.ai",
+    "url": "https://crewhaus.ai"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crewhaus/factory.git",
+    "directory": "packages/tool-capability"
+  },
+  "homepage": "https://github.com/crewhaus/factory/tree/main/packages/tool-capability#readme",
+  "bugs": {
+    "url": "https://github.com/crewhaus/factory/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": ["dist", "README.md", "LICENSE", "NOTICE"],
+  "engines": {
+    "bun": ">=1.3.14"
+  }
+}