@retinue/agentkit 0.1.0 → 0.2.0

package/dist/tools/meta-tools.js

@@ -26,6 +26,14 @@ const meta = (name, label, description) => ({
 });
 export const META_TOOL_DESCRIPTORS = {
     learn_tools: meta("learn_tools", "Learn tools", "Fetch the full input/output schemas for named tools before using them."),
+    /**
+     * REQ-045 (#204), task #210.
+     *
+     * The description says "not all of them are listed", and that sentence is doing real work: a model that
+     * believes the catalogue it can see is complete will not search, and a budget that dropped fourteen tools
+     * would then behave exactly like fourteen tools that do not exist.
+     */
+    find_tools: meta("find_tools", "Find tools", "Search for a tool by describing what you need to do. Not all available tools are listed in the catalogue, so search before concluding that something cannot be done. Returns names and descriptions; use learn_tools for a schema."),
     execute_tool: meta("execute_tool", "Execute tool", "Run a tool by name with validated input; authorization is rechecked at execution."),
     load_skill: meta("load_skill", "Load skill", "Load a named skill's instructions into context on demand."),
     ask_questions: meta("ask_questions", "Ask questions", "Ask the user consequential questions that cannot be resolved from context or tools."),

package/dist/tools/registry.d.ts

@@ -16,10 +16,13 @@
  *   result instead of firing the side effect twice.
  */
 import type { ExecutionContext } from "../core/context.js";
+import type { PlatformError } from "../core/errors.js";
 import type { BlobRef } from "../core/ids.js";
 import { type AuthorizationPolicy } from "../authorization/index.js";
 import { type IdempotencyStore } from "../idempotency/index.js";
 import type { BlobStore } from "../persistence/index.js";
+import { type TokenBudget } from "../core/budget.js";
+import type { ToolSearch, ToolSearchOutcome } from "./find.js";
 import type { OneTimeApprovalRef, ShadowRecorder, ToolCatalogEntry, ToolDescriptor, ToolProvider, ToolResult } from "./index.js";
 /** Validates a tool input against its (opaque) `inputSchema`. Default duck-types a zod schema. */
 export interface SchemaValidator {
@@ -33,6 +36,55 @@ export interface SchemaValidator {
 }
 /** Default validator: run a zod-like schema's `safeParse`; pass through anything else (tool self-validates). */
 export declare const zodishValidator: SchemaValidator;
+/**
+ * `execute_tool({ name, input })` → the call it names. Anything else passes through untouched.
+ *
+ * Refuses to target another meta-tool: `execute_tool` calling itself is an unbounded recursion a model can start
+ * with one call, and the others have their own entry points. One level of indirection is the feature; a stack of
+ * it is a way to hide what a call actually was from every log that records the outer name.
+ */
+export type ExecuteToolRequest = {
+    name: string;
+    input: unknown;
+    idempotencyKey?: string;
+    toolCallId?: string;
+    approval?: OneTimeApprovalRef;
+};
+export declare const unwrapExecuteTool: (request: ExecuteToolRequest) => ExecuteToolRequest | {
+    readonly error: PlatformError;
+};
+/**
+ * What a tenant has switched on — REQ-045 (#204), task #210, AC-4.
+ *
+ * Authorization answers *may this principal use this tool*. Nothing answered *does this tenant want it at all*,
+ * and without the second question a catalogue is only ever as small as its largest customer: every tenant pays
+ * the context cost of every integration anybody wired.
+ *
+ * Categories rather than names, deliberately. A tenant switching off `communication` should not have to name
+ * five Slack tools and then miss the sixth when it ships.
+ */
+export type TenantToolset = {
+    /** An allow-list. Present means *only* these categories, which is the safer shape for a tenant opting in. */
+    readonly enabledCategories?: readonly string[];
+    /** A deny-list, applied after any allow-list. */
+    readonly disabledCategories?: readonly string[];
+};
+/**
+ * Resolves a tenant's toolset. A port, because where this lives is a deployment's decision — a column, a
+ * settings service, a static map.
+ */
+export interface ToolsetResolver {
+    resolve(context: ExecutionContext): Promise<TenantToolset>;
+}
+/**
+ * Categories a tenant may not switch off.
+ *
+ * `meta` is the model's route back to everything else. A tenant that disabled it would have an agent that cannot
+ * learn a schema or search the catalogue — which is not a smaller toolset, it is a broken one.
+ */
+export declare const UNDISABLEABLE_CATEGORIES: readonly string[];
+/** Whether a category survives a tenant's toolset. Exported because the filtering is worth testing directly. */
+export declare const categoryEnabled: (toolset: TenantToolset, category: string) => boolean;
 export type ToolPolicyView = {
     readonly preloaded: readonly string[];
     readonly categories: readonly string[];
@@ -45,6 +97,28 @@ export type ToolCatalog = {
     readonly discoverable: readonly ToolCatalogEntry[];
     /** Always-present meta-tools. */
     readonly meta: readonly ToolCatalogEntry[];
+    /**
+     * Present only when a budget bound — REQ-045 (#204), task #210, AC-3.
+     *
+     * On the catalogue as well as in the run event log, because the two have different readers: the event is for
+     * whoever reviews the run afterwards, and this is for the client rendering the catalogue *now*. A UI showing
+     * a shortened list with no indication it was shortened is the same invisible failure in a different place.
+     */
+    readonly truncation?: {
+        readonly budgetTokens: number;
+        readonly residentTokens: number;
+        readonly dropped: readonly string[];
+        readonly findable: boolean;
+        readonly overBudget: boolean;
+    };
+    /**
+     * The tenant's toolset as it was applied — AC-4's "visible in the capability declaration".
+     *
+     * This catalogue *is* the declaration a client reads: it is the only place the platform states what an agent
+     * can do. A tenant setting that silently narrowed it, with nothing in the answer saying so, would be
+     * indistinguishable from tools that were never built.
+     */
+    readonly toolset?: TenantToolset;
 };
 /** Structural approval check (satisfied by the HITL `ApprovalGate`) — kept structural to avoid a
  * tools→hitl dependency. Returns false when the tool needs approval and the call carries neither a
@@ -127,9 +201,48 @@ export type ToolRegistryConfig = {
      * than performed, the same fail-closed rule as the envelope's.
      */
     readonly shadow?: ShadowRecorder;
+    /**
+     * Search over the catalogue, which is what makes `find_tools` exist — AC-1.
+     *
+     * Absent means no `find_tools` in the catalogue at all, rather than one that always answers "not configured".
+     * Wiring is the toggle, the same rule the tool library already follows for `web_search`.
+     */
+    readonly search?: ToolSearch;
+    /** A tenant's category switches, applied *before* authorization filtering — AC-4. */
+    readonly toolsets?: ToolsetResolver;
+    /**
+     * A ceiling in tokens on the discoverable catalogue — AC-3.
+     *
+     * Applies to the compact entries only. Preloaded tools are an explicit instruction from the host and are not
+     * silently withdrawn; a host that preloads more than its own budget is told so through `overBudget` rather
+     * than having its instruction quietly reversed.
+     */
+    readonly catalogBudget?: TokenBudget;
 };
 export interface ToolRegistry {
     catalog(context: ExecutionContext, policy: ToolPolicyView): Promise<ToolCatalog>;
+    /**
+     * Search the catalogue — AC-1.
+     *
+     * Filtered by the same authorization policy as discovery, which is not a nicety: an unfiltered search is an
+     * enumeration oracle. A principal who cannot see `github_merge_pull_request` in the catalogue but can confirm
+     * it exists by searching for "merge" has learned what the deployment does, and hiding a tool from discovery
+     * while making it findable is worse than not hiding it, because it looks like it was hidden.
+     */
+    find(context: ExecutionContext, input: {
+        readonly query: string;
+        readonly limit?: number;
+    }): Promise<ToolSearchOutcome>;
+    /**
+     * Every tool this caller may use, with schemas — the list `buildTools` should hand a model.
+     *
+     * Exists because the embedded facade was doing this itself: gathering providers, flattening, and filtering by
+     * authorization, in its own copy of the four lines this registry already owns. The copy had no duplicate-name
+     * check and no tenant toolset, so a category a tenant had switched off was invisible in the catalogue, absent
+     * from `find_tools`, refused at execution — and *still handed to the model*, which would then call it and be
+     * refused. One implementation, and this is it.
+     */
+    listAuthorized(context: ExecutionContext): Promise<readonly ToolDescriptor[]>;
     learn(context: ExecutionContext, names: readonly string[]): Promise<readonly ToolDescriptor[]>;
     execute(context: ExecutionContext, input: {
         name: string;

package/dist/tools/registry.js

@@ -18,6 +18,8 @@
 import { assertToolAuthorized } from "../authorization/index.js";
 import { deriveIdempotencyKey } from "../idempotency/index.js";
 import { META_TOOL_DESCRIPTOR_LIST } from "./meta-tools.js";
+import { applyTokenBudget } from "../core/budget.js";
+import { entryTokens } from "./budget.js";
 /** Default validator: run a zod-like schema's `safeParse`; pass through anything else (tool self-validates). */
 export const zodishValidator = {
     validate(schema, value) {
@@ -39,6 +41,26 @@ const compact = (d) => ({
     effect: d.effect,
 });
 const invalidInput = (message) => ({ code: "invalid_input", message, retryable: false });
+/** The registry's own meta-tools, which a model may not target through `execute_tool`. */
+const META_ONLY = new Set(["execute_tool", "find_tools", "learn_tools", "read_tool_output"]);
+export const unwrapExecuteTool = (request) => {
+    if (request.name !== "execute_tool")
+        return request;
+    const asked = (request.input ?? {});
+    if (typeof asked.name !== "string" || asked.name.trim() === "")
+        return { error: invalidInput("execute_tool needs the name of the tool to run.") };
+    if (META_ONLY.has(asked.name))
+        return { error: invalidInput(`execute_tool cannot call ${asked.name}; call it directly.`) };
+    return {
+        name: asked.name,
+        input: asked.input,
+        ...(typeof asked.idempotencyKey === "string" ? { idempotencyKey: asked.idempotencyKey } : {}),
+        // The *outer* call's identity is kept: the tool call the model made is the one the run event log records,
+        // and rewriting it here would make a transcript disagree with the model's own history.
+        ...(request.toolCallId === undefined ? {} : { toolCallId: request.toolCallId }),
+        ...(request.approval === undefined ? {} : { approval: request.approval }),
+    };
+};
 /** A wiring problem, not a caller problem: retrying the identical call cannot help. */
 const capabilityUnavailable = (message) => ({
     code: "capability_unavailable",
@@ -46,6 +68,21 @@ const capabilityUnavailable = (message) => ({
     retryable: false,
 });
 const requiresKey = (effect, requires) => requires || effect === "external-write" || effect === "destructive";
+/**
+ * Categories a tenant may not switch off.
+ *
+ * `meta` is the model's route back to everything else. A tenant that disabled it would have an agent that cannot
+ * learn a schema or search the catalogue — which is not a smaller toolset, it is a broken one.
+ */
+export const UNDISABLEABLE_CATEGORIES = ["meta"];
+/** Whether a category survives a tenant's toolset. Exported because the filtering is worth testing directly. */
+export const categoryEnabled = (toolset, category) => {
+    if (UNDISABLEABLE_CATEGORIES.includes(category))
+        return true;
+    if (toolset.enabledCategories !== undefined && !toolset.enabledCategories.includes(category))
+        return false;
+    return !(toolset.disabledCategories ?? []).includes(category);
+};
 export const createToolRegistry = (config) => {
     const maxInline = config.maxInlineOutputBytes ?? 8 * 1024;
     const validator = config.validator ?? zodishValidator;
@@ -110,13 +147,38 @@ export const createToolRegistry = (config) => {
                 });
             }
         }
-        const usable = all.filter((t) => !duplicated.has(t.descriptor.name));
+        /**
+         * The tenant's toolset, applied **before** authorization — AC-4.
+         *
+         * Order matters and this is the order the AC asks for. A tool a tenant switched off is not a tool the
+         * principal is unauthorized for: it does not exist for that tenant, so it must not reach the authorization
+         * policy, must not appear in a policy's audit of what it filtered, and must not be findable.
+         */
+        const toolset = config.toolsets === undefined ? undefined : await config.toolsets.resolve(context);
+        const wanted = toolset === undefined
+            ? all.filter((t) => !duplicated.has(t.descriptor.name))
+            : all.filter((t) => !duplicated.has(t.descriptor.name) && categoryEnabled(toolset, t.descriptor.category));
+        const usable = wanted;
         const descriptors = usable.map((t) => t.descriptor);
         const permitted = new Set((await config.authorization.filterTools(context, descriptors)).map((d) => d.name));
         return usable.filter((t) => permitted.has(t.descriptor.name));
     };
     const findAuthorized = async (context, name) => (await authorizedTools(context)).find((t) => t.descriptor.name === name) ?? null;
-    return {
+    /**
+     * One implementation, reached two ways: `registry.find` for a host, and `execute("find_tools")` for a model.
+     *
+     * `find_tools` is not authorized as a tool in its own right, and that is deliberate: like every other
+     * meta-tool it is part of the interface rather than a capability a role grants. What *is* authorized is
+     * everything it can return — the corpus is the caller's own authorized tool list — so the worst a principal
+     * with no tools can learn from it is that they have none.
+     */
+    const runFind = async (context, input) => {
+        if (config.search === undefined)
+            return { hits: [], modes: [] };
+        const tools = (await authorizedTools(context)).map((t) => t.descriptor);
+        return config.search.search({ query: input.query, tools, limit: input.limit ?? 10 });
+    };
+    const api = {
         async catalog(context, policy) {
             const excluded = new Set(policy.excluded);
             const preloadNames = new Set(policy.preloaded);
@@ -131,14 +193,127 @@ export const createToolRegistry = (config) => {
                 else
                     discoverable.push(compact(d));
             }
-            return { preloaded, discoverable, meta: META_TOOL_DESCRIPTOR_LIST.map(compact) };
+            /**
+             * `find_tools` is advertised only when a search is wired.
+             *
+             * The alternative — a permanent descriptor that fails at execution — costs the model a call to discover
+             * and reads in a transcript exactly like a broken platform.
+             */
+            const meta = META_TOOL_DESCRIPTOR_LIST.filter((d) => d.name !== "find_tools" || config.search !== undefined).map(compact);
+            const toolset = config.toolsets === undefined ? undefined : await config.toolsets.resolve(context);
+            if (config.catalogBudget === undefined)
+                return {
+                    preloaded,
+                    discoverable,
+                    meta,
+                    ...(toolset === undefined ? {} : { toolset }),
+                };
+            // Preloaded entries and the meta-tools are charged against the budget but never dropped: they are the
+            // host's own instruction and the model's route back to what was withheld.
+            const fixed = preloaded.reduce((total, d) => total + entryTokens(compact(d)), 0) +
+                meta.reduce((total, entry) => total + entryTokens(entry), 0);
+            const outcome = applyTokenBudget({
+                items: discoverable,
+                budget: { maxTokens: Math.max(0, config.catalogBudget.maxTokens - fixed) },
+                tokensOf: entryTokens,
+                nameOf: (entry) => entry.name,
+            });
+            return {
+                preloaded,
+                discoverable: outcome.resident,
+                meta,
+                ...(toolset === undefined ? {} : { toolset }),
+                ...(outcome.dropped.length === 0 && !outcome.overBudget
+                    ? {}
+                    : {
+                        truncation: {
+                            budgetTokens: config.catalogBudget.maxTokens,
+                            residentTokens: outcome.residentTokens + fixed,
+                            dropped: outcome.dropped,
+                            findable: config.search !== undefined,
+                            overBudget: outcome.residentTokens + fixed > config.catalogBudget.maxTokens,
+                        },
+                    }),
+            };
+        },
+        find: runFind,
+        async listAuthorized(context) {
+            return (await authorizedTools(context)).map((t) => t.descriptor);
         },
         async learn(context, names) {
             // Only authorized tools are returned — an unauthorized name is silently unlearnable.
             const wanted = new Set(names);
             return (await authorizedTools(context)).map((t) => t.descriptor).filter((d) => wanted.has(d.name));
         },
-        async execute(context, input) {
+        async execute(context, outer) {
+            /**
+             * `execute_tool`, unwrapped before anything else — task #210.
+             *
+             * Without this, `find_tools` finds a tool the model **cannot call**: a truncated tool list means the name
+             * it just learned is not in its own tool set, so search would return an answer and leave the model stuck.
+             * That is the difference between a deferral and an amputation, and it was missing — `execute_tool` has been
+             * in `META_TOOLS` since the registry was written and nothing implemented it.
+             *
+             * Unwrapping rather than dispatching: the inner call then goes through *every* check below — authorization,
+             * the toolset, the approval gate, validation, idempotency, the shadow recorder — because it is the same
+             * code path. A separate branch that called the tool directly would be a way around all of them, reachable
+             * by name from a model.
+             */
+            if (outer.name === "execute_tool") {
+                const unwrapped = unwrapExecuteTool(outer);
+                if ("error" in unwrapped)
+                    return { ok: false, error: unwrapped.error };
+                /**
+                 * Re-entered through the public surface, and tagged once on the way out.
+                 *
+                 * Re-entering rather than falling through with a rewritten argument: the inner call then passes every
+                 * check below exactly as a direct call would — authorization, the tenant's toolset, the approval gate,
+                 * validation, idempotency, the shadow recorder — because it *is* a direct call. A fall-through would work
+                 * today and become a bypass the first time somebody adds a check above this line.
+                 *
+                 * `ranToolName` is attached here, in the one place the indirection is known. The audit trail's question
+                 * is "what was done", and `execute_tool` is not an answer to it.
+                 */
+                const inner = await api.execute(context, unwrapped);
+                return { ...inner, ranToolName: unwrapped.name };
+            }
+            const input = outer;
+            /**
+             * `learn_tools`, handled here — task #210, and the leg that was missing.
+             *
+             * `find_tools` returns names and descriptions. A model that then calls the tool through `execute_tool` has
+             * to guess its arguments, and in the 200-tool measurement it did exactly that: searched, found the right
+             * tool, and called it wrongly or not at all. Search without schemas is a dead end, and the descriptor for
+             * `learn_tools` had been in `META_TOOLS` since the registry was written with nothing implementing it.
+             */
+            if (input.name === "learn_tools") {
+                const asked = (input.input ?? {});
+                const names = Array.isArray(asked.names) ? asked.names.filter((n) => typeof n === "string") : [];
+                if (names.length === 0)
+                    return { ok: false, error: invalidInput("learn_tools needs `names`: the tools whose schemas you want.") };
+                // Authorized only, like discovery and like search — an unauthorized name is silently unlearnable.
+                return { ok: true, data: { tools: await api.learn(context, names) } };
+            }
+            /**
+             * `find_tools`, handled here rather than by a provider — AC-1.
+             *
+             * It has to be the registry: the corpus *is* the registry's authorized tool list, and a provider-supplied
+             * search tool would either need the registry passed into it (a construction cycle) or its own idea of what
+             * exists, which is the second implementation AC-2 forbids.
+             */
+            if (input.name === "find_tools") {
+                if (config.search === undefined)
+                    return {
+                        ok: false,
+                        error: capabilityUnavailable("find_tools is not available: no tool search is configured (see ToolRegistryConfig.search)."),
+                    };
+                const asked = (input.input ?? {});
+                if (typeof asked.query !== "string" || asked.query.trim() === "")
+                    return { ok: false, error: invalidInput("find_tools needs a query describing what you are trying to do.") };
+                const limit = typeof asked.limit === "number" && asked.limit > 0 ? Math.min(Math.floor(asked.limit), 25) : 10;
+                const outcome = await runFind(context, { query: asked.query, limit });
+                return { ok: true, data: outcome };
+            }
             const tool = await findAuthorized(context, input.name);
             // Not found OR not authorized → both reject; execution is never a way around discovery filtering.
             if (!tool) {
@@ -272,6 +447,7 @@ export const createToolRegistry = (config) => {
             return { ok: true, data: value };
         },
     };
+    return api;
     /** Spill an oversize success payload to blob storage and reference it. */
     async function maybeSpill(context, result) {
         if (!result.ok || result.spilledOutputRef !== undefined)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@retinue/agentkit",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "A provider-neutral, durable AI agent runtime for TypeScript: agents, tools, approvals, context, knowledge and persistence behind ports.",
   "license": "MIT",
   "type": "module",
@@ -39,6 +39,10 @@
       "types": "./dist/entries/hitl.d.ts",
       "default": "./dist/entries/hitl.js"
     },
+    "./guardrails": {
+      "types": "./dist/entries/guardrails.d.ts",
+      "default": "./dist/entries/guardrails.js"
+    },
     "./usage": {
       "types": "./dist/entries/usage.d.ts",
       "default": "./dist/entries/usage.js"