@retinue/agentkit 0.1.0 → 0.2.0

package/dist/agents/agent.js

@@ -56,7 +56,13 @@ export const createAgent = (config) => {
     });
     const providerFactory = createProviderFactory({ credentials: config.providerCredentials ?? {} });
     const authorization = config.authorization ?? allowAllAuthorization();
-    const toolRegistry = createToolRegistry({ providers: config.tools ?? [], authorization });
+    const toolRegistry = createToolRegistry({
+        providers: config.tools ?? [],
+        authorization,
+        ...(config.toolSearch === undefined ? {} : { search: config.toolSearch }),
+        ...(config.toolsets === undefined ? {} : { toolsets: config.toolsets }),
+        ...(config.catalogBudget === undefined ? {} : { catalogBudget: config.catalogBudget }),
+    });
     const resolveModel = config.resolveModel ??
         ((m) => {
             const def = registry.resolve(m.modelPolicy);
@@ -69,6 +75,8 @@ export const createAgent = (config) => {
         });
     const contextProviders = config.contextProviders ?? [];
     const engine = config.engine ?? createDefaultEngine({
+        ...(config.guardrails === undefined ? {} : { guardrails: config.guardrails }),
+        ...(config.catalogBudget === undefined ? {} : { catalogBudget: config.catalogBudget }),
         async loadManifest() {
             return manifest; // single-manifest embedded agent
         },
@@ -120,19 +128,97 @@ export const createAgent = (config) => {
         },
         ...(config.tools && config.tools.length > 0
             ? {
+                /**
+                 * The tools this turn, through the registry rather than around it — task #210.
+                 *
+                 * This used to gather the providers itself and filter them with `authorization.filterTools`, which was
+                 * a second copy of what the registry does: no duplicate-name check, and — once tenant toolsets existed
+                 * — no toolset either, so a switched-off category was hidden everywhere except in the list actually
+                 * handed to the model.
+                 */
                 buildTools: async (context) => {
-                    const resolvedTools = [];
-                    const gathered = (await Promise.all((config.tools ?? []).map((p) => p.listTools(context)))).flat();
-                    const permitted = new Set((await authorization.filterTools(context, gathered.map((t) => t.descriptor))).map((d) => d.name));
-                    for (const t of gathered) {
-                        if (!permitted.has(t.descriptor.name))
-                            continue;
+                    const descriptors = await toolRegistry.listAuthorized(context);
+                    const resolvedTools = descriptors.map((descriptor) => ({
+                        name: descriptor.name,
+                        description: descriptor.description,
+                        inputSchema: descriptor.inputSchema,
+                        execute: async (input) => {
+                            const result = await toolRegistry.execute(context, { name: descriptor.name, input });
+                            if (!result.ok)
+                                throw new AgentPlatformError(result.error);
+                            return result.data;
+                        },
+                    }));
+                    /**
+                     * `find_tools`, when a search is wired — task #210, AC-1.
+                     *
+                     * Its schema is written here because a meta-tool descriptor carries none, and a model handed a
+                     * permissive schema streams `{}` for every call. The registry validates the arguments itself.
+                     */
+                    /**
+                     * `execute_tool`, alongside search — task #210.
+                     *
+                     * Without it `find_tools` is a dead end: the tool it names is not in this turn's list (that is why
+                     * it had to be searched for), so the model learns a name it cannot call. Added whenever search or a
+                     * budget is configured, which are exactly the cases where the list is partial.
+                     */
+                    if (config.toolSearch !== undefined || config.catalogBudget !== undefined) {
+                        resolvedTools.push({
+                            name: "execute_tool",
+                            description: "Run a tool by name — including one that is not listed here, for example one you found with " +
+                                "find_tools. Authorization and approval apply exactly as they would to a direct call.",
+                            inputSchema: {
+                                type: "object",
+                                properties: {
+                                    name: { type: "string", description: "The tool's name." },
+                                    input: { type: "object", description: "The tool's arguments, matching its schema." },
+                                },
+                                required: ["name", "input"],
+                            },
+                            execute: async (input, options) => {
+                                const result = await toolRegistry.execute(context, { name: "execute_tool", input });
+                                // What actually ran, so the run event log names the action rather than the mechanism.
+                                if (result.ranToolName !== undefined)
+                                    options?.report?.({ ranToolName: result.ranToolName });
+                                if (!result.ok)
+                                    throw new AgentPlatformError(result.error);
+                                return result.data;
+                            },
+                        });
+                    }
+                    if (config.toolSearch !== undefined || config.catalogBudget !== undefined) {
                         resolvedTools.push({
-                            name: t.descriptor.name,
-                            description: t.descriptor.description,
-                            inputSchema: t.descriptor.inputSchema,
+                            name: "learn_tools",
+                            description: "Fetch the full input schemas for tools by name — including ones not listed here. Call this " +
+                                "before running a tool you found with find_tools, so you know what arguments it takes.",
+                            inputSchema: {
+                                type: "object",
+                                properties: { names: { type: "array", items: { type: "string" } } },
+                                required: ["names"],
+                            },
+                            execute: async (input) => {
+                                const result = await toolRegistry.execute(context, { name: "learn_tools", input });
+                                if (!result.ok)
+                                    throw new AgentPlatformError(result.error);
+                                return result.data;
+                            },
+                        });
+                    }
+                    if (config.toolSearch !== undefined) {
+                        resolvedTools.push({
+                            name: "find_tools",
+                            description: "Search for a tool by describing what you need to do. Not all available tools are listed, so " +
+                                "search before concluding that something cannot be done. Run what you find with execute_tool.",
+                            inputSchema: {
+                                type: "object",
+                                properties: {
+                                    query: { type: "string", description: "What you are trying to do, in your own words." },
+                                    limit: { type: "number", description: "How many tools to return. Default 10." },
+                                },
+                                required: ["query"],
+                            },
                             execute: async (input) => {
-                                const result = await toolRegistry.execute(context, { name: t.descriptor.name, input });
+                                const result = await toolRegistry.execute(context, { name: "find_tools", input });
                                 if (!result.ok)
                                     throw new AgentPlatformError(result.error);
                                 return result.data;

package/dist/agents/engine.d.ts

@@ -20,10 +20,20 @@
 import type { ExecutionContext } from "../core/context.js";
 import type { RunId, TenantId } from "../core/ids.js";
 import type { ModelDefinition, ModelTurnRequest, ModelTurnTool, NeutralStreamChunk, NeutralUsage, ResolvedModel, TurnMessage } from "../models/index.js";
+import { type Guardrail } from "../guardrails/index.js";
 import { type AgentEngine, type RetryPolicy, type Run } from "../runtime/index.js";
+import { type TokenBudget } from "../core/budget.js";
 import type { PendingQuestion, RunApprovals } from "../hitl/index.js";
 import type { CitationEmitter } from "../citations/index.js";
 import type { AgentManifest } from "./index.js";
+/**
+ * What one tool costs the model's context.
+ *
+ * A `ModelTurnTool` is not a catalogue entry — it carries the full input schema, because that is what a provider
+ * puts in the request — so this deliberately does *not* reuse `entryTokens`. Using the compact estimate here
+ * would understate a schema-heavy tool by an order of magnitude and produce a budget that never binds.
+ */
+export declare const turnToolTokens: (tool: ModelTurnTool) => number;
 /** A model resolved for a turn: the opaque handle plus what the engine needs to attribute usage. */
 export type ResolvedModelInfo = {
     readonly model: ResolvedModel;
@@ -63,6 +73,24 @@ export type DefaultEngineDeps = {
      * pause on.
      */
     readonly approvals?: RunApprovals;
+    /**
+     * Checks a deployment adds — REQ-046 (#205).
+     *
+     * Absent means no inspection, which is the current behaviour and stays the default: a runtime that imposed a
+     * model call on every turn to moderate it would be making a cost decision that belongs to the host.
+     */
+    readonly guardrails?: readonly Guardrail[];
+    /**
+     * A ceiling in tokens on the tool list handed to the model — REQ-045 (#204), task #210, AC-3.
+     *
+     * Here rather than only in the registry because *this* is where the tokens are actually spent: the registry's
+     * catalogue is what a client renders, and `buildTools` is what reaches the provider. A budget enforced in one
+     * and not the other would be a budget a deployment believes it has.
+     *
+     * Absent means no ceiling, which stays the default — a runtime that silently withheld tools from a model
+     * nobody had asked it to withhold would be making a correctness decision on the host's behalf.
+     */
+    readonly catalogBudget?: TokenBudget;
     /**
      * The question side of resumption — #163.
      *

package/dist/agents/engine.js

@@ -19,9 +19,23 @@
  */
 import { AgentPlatformError, isAgentPlatformError } from "../core/errors.js";
 import { asId } from "../core/ids.js";
-import { streamModelTurn } from "../models/index.js";
+import { applyInputGuardrails, applyOutputGuardrails } from "../guardrails/index.js";
+import { streamModelTurn, turnText } from "../models/index.js";
 import { decideRetry, deriveRunMessageId, toPlatformError, DEFAULT_RETRY_POLICY, } from "../runtime/index.js";
+import { META_TOOLS } from "../tools/index.js";
+// The specific modules rather than `core/index.js`: the barrel pulls in `zod` through `core/validation.ts`,
+// and a subpath's dependency graph is a guarantee this package tests for.
+import { applyTokenBudget } from "../core/budget.js";
+import { estimateTokens } from "../core/tokens.js";
 import { isQuestionPending } from "../hitl/service.js";
+/**
+ * What one tool costs the model's context.
+ *
+ * A `ModelTurnTool` is not a catalogue entry — it carries the full input schema, because that is what a provider
+ * puts in the request — so this deliberately does *not* reuse `entryTokens`. Using the compact estimate here
+ * would understate a schema-heavy tool by an order of magnitude and produce a budget that never binds.
+ */
+export const turnToolTokens = (tool) => estimateTokens(`${tool.name} ${tool.description ?? ""}`) + estimateTokens(JSON.stringify(tool.inputSchema ?? {}));
 const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
 /**
  * Take citation candidates off a tool's result — #165.
@@ -83,6 +97,21 @@ const questionMarker = (thrown, toolName) => {
         },
     };
 };
+/**
+ * A record becomes an event, with no value ever attached.
+ *
+ * One place, so a future field on `GuardrailRecord` cannot reach the event log by being spread in somewhere: the
+ * mapping is explicit, field by field, and adding one here is a decision rather than a consequence.
+ */
+const verdictEvent = (record) => ({
+    type: "guardrail.verdict",
+    guardrail: record.guardrail,
+    subject: record.subject,
+    outcome: record.outcome,
+    ...(record.what === undefined ? {} : { what: record.what }),
+    ...(record.code === undefined ? {} : { code: record.code }),
+    ...(record.threw === undefined ? {} : { threw: record.threw }),
+});
 export const createDefaultEngine = (deps) => {
     const policy = deps.retry ?? DEFAULT_RETRY_POLICY;
     const sleep = deps.sleep ?? defaultSleep;
@@ -94,7 +123,39 @@ export const createDefaultEngine = (deps) => {
             const resolved = deps.resolveModel(manifest, context);
             const system = (await (deps.systemPrompt?.(manifest, context) ?? manifest.instructions)) || undefined;
             const history = await deps.loadHistory(context, run);
-            const declared = deps.buildTools ? await deps.buildTools(context, manifest) : [];
+            const built = deps.buildTools ? await deps.buildTools(context, manifest) : [];
+            /**
+             * The budget, applied to the list the model will actually see — AC-3.
+             *
+             * Meta-tools are protected: dropping `find_tools` to save its own ~35 tokens would leave the model with a
+             * shortened list and no way to discover that it was shortened, which is the failure this whole mechanism
+             * exists to prevent.
+             *
+             * `findable` is *derived* rather than configured. Whether truncation is a deferral or an amputation
+             * depends on one fact — is `find_tools` in the model's hands this turn — and asking the host to declare
+             * that separately would let the declaration be wrong.
+             */
+            const budgetOutcome = deps.catalogBudget === undefined
+                ? undefined
+                : applyTokenBudget({
+                    items: built,
+                    budget: deps.catalogBudget,
+                    tokensOf: turnToolTokens,
+                    nameOf: (tool) => tool.name,
+                    protect: (tool) => META_TOOLS.includes(tool.name),
+                });
+            const declared = budgetOutcome?.resident ?? built;
+            if (budgetOutcome !== undefined && (budgetOutcome.dropped.length > 0 || budgetOutcome.overBudget)) {
+                yield {
+                    type: "catalog.truncated",
+                    catalog: "tools",
+                    budgetTokens: budgetOutcome.budgetTokens,
+                    residentTokens: budgetOutcome.residentTokens,
+                    dropped: budgetOutcome.dropped,
+                    findable: declared.some((tool) => tool.name === "find_tools"),
+                    ...(budgetOutcome.overBudget ? { overBudget: true } : {}),
+                };
+            }
             const maxSteps = manifest.limits?.maxSteps ?? 8;
             const messageId = deriveRunMessageId(run.id);
             // A decision taken while the run was parked. Executed before the model gets another turn, so the
@@ -113,6 +174,46 @@ export const createDefaultEngine = (deps) => {
                 for (const event of questionEvents(answered, messages))
                     yield event;
             }
+            /**
+             * Inspection, before the model sees anything — REQ-046 (#205), AC-1.
+             *
+             * Placed after resumption so an approved side effect that already happened is not re-inspected, and
+             * *before* the tools are built so a refusal costs nothing: no provider call, no tool discovery, no spend.
+             *
+             * The subject is the newest user turn rather than the whole history. Re-inspecting history every turn
+             * would re-refuse a conversation over something already allowed, and a guardrail that changes its mind
+             * about the past makes a conversation impossible to continue.
+             */
+            const guardrails = deps.guardrails ?? [];
+            if (guardrails.length > 0) {
+                const latest = [...messages].reverse().find((m) => m.role === "user");
+                const decision = await applyInputGuardrails(guardrails, { text: latest ? turnText(latest) : "" }, context);
+                for (const record of decision.records)
+                    yield verdictEvent(record);
+                if (decision.outcome === "refused") {
+                    /**
+                     * The turn ends here, and it ends *visibly*.
+                     *
+                     * A text part rather than a thrown error: a refusal is a policy outcome, not a crash, and a run that
+                     * failed with a stack trace tells the person nothing and the operator the wrong thing. The model is
+                     * never called, which is what AC-3 asks for — "the turn does not proceed".
+                     */
+                    const partId = `${messageId}:guardrail:refused`;
+                    yield {
+                        type: "part.added",
+                        messageId,
+                        part: {
+                            id: partId,
+                            type: "text",
+                            schemaVersion: 1,
+                            createdAt: new Date(0).toISOString(),
+                            text: decision.message,
+                        },
+                    };
+                    yield { type: "run.completed" };
+                    return;
+                }
+            }
             /**
              * The tools the model may call, with execution routed through the approval loop.
              *
@@ -139,6 +240,15 @@ export const createDefaultEngine = (deps) => {
              * the passage supports. Emitting at the tool call would produce citations supporting nothing.
              */
             const pendingCitations = [];
+            /**
+             * Guardrail verdicts on tool arguments, buffered — REQ-046 (#205), AC-2 and AC-4.
+             *
+             * Buffered for the same reason as the citations above: the inspection happens inside a tool's `execute`,
+             * which is a callback the model's stream invokes and not a generator, so it cannot yield. Dropping the
+             * records instead would satisfy the enforcement half of AC-2 and quietly fail AC-4 — the check would work
+             * and leave no trace, which is the combination that makes an incident unreconstructable.
+             */
+            const pendingVerdicts = [];
             const approvals = deps.approvals;
             /**
              * Every tool is wrapped, whether or not an approval gate is configured.
@@ -147,12 +257,74 @@ export const createDefaultEngine = (deps) => {
              * interception point at all — and a question raised by one of its tools could not be noticed. The gate
              * decides *approvals*; parking a run on a question is not its business.
              */
+            /**
+             * What each call actually ran, keyed by the provider's call id — task #210.
+             *
+             * `execute_tool` names its target, so the tool the model called and the action performed are two different
+             * things. The wrapper is the only place that knows both, and the events are emitted somewhere else, so the
+             * fact has to be carried across. Without it a `destructive` tool invoked through `execute_tool` appears in
+             * the audit trail as "execute_tool", which is not an answer to the question the trail exists to answer.
+             */
+            const ranByCall = new Map();
             const tools = declared.map((t) => ({
                 ...t,
-                execute: async (input) => {
+                execute: async (input, options) => {
+                    /**
+                     * What this call is allowed to tell us — task #210.
+                     *
+                     * The host's closure is what reaches the registry, so it is the only thing that can know a call
+                     * resolved to a different tool. `report` is how it says so, and the map is read where the events are
+                     * emitted.
+                     */
+                    const report = (fact) => {
+                        if (options?.toolCallId !== undefined)
+                            ranByCall.set(options.toolCallId, fact.ranToolName);
+                    };
+                    /**
+                     * A tool call is an output — AC-2.
+                     *
+                     * Before either branch below, so it applies whether or not an approval gate is configured, and
+                     * *before* the gate so a refused call never becomes an approval request: asking a person to approve
+                     * something that will not happen is how approving comes to feel meaningless.
+                     *
+                     * The refusal is returned as a tool *result* rather than thrown. The model then sees why its call did
+                     * not happen and can say so, which is the difference between a run that explains itself and one that
+                     * dies with a stack trace the person cannot act on.
+                     */
+                    if (guardrails.length > 0) {
+                        const decision = await applyOutputGuardrails(guardrails, { kind: "tool-call", toolName: t.name, input }, context);
+                        pendingVerdicts.push(...decision.records);
+                        if (decision.outcome === "refused") {
+                            return { refused: true, guardrail: decision.by, code: decision.code, message: decision.message };
+                        }
+                        // A redacted call runs with the redaction, not with what the model typed.
+                        if (decision.value.kind === "tool-call")
+                            input = decision.value.input;
+                    }
+                    /**
+                     * What a tool hands back is inspected too — AC-3.
+                     *
+                     * A tool result is content entering the model's context from outside the tenant, and it is the
+                     * likeliest source of personal data in a run: a document read by a tool contains whatever the document
+                     * contains. Checking arguments and not results would guard the direction data leaves and ignore the
+                     * direction it arrives.
+                     *
+                     * A refusal replaces the result rather than throwing, for the same reason as above: the model is told
+                     * why and can say so, instead of the run dying where the person cannot see the cause.
+                     */
+                    const inspectResult = async (output) => {
+                        if (guardrails.length === 0)
+                            return output;
+                        const decision = await applyOutputGuardrails(guardrails, { kind: "tool-result", toolName: t.name, output }, context);
+                        pendingVerdicts.push(...decision.records);
+                        if (decision.outcome === "refused") {
+                            return { refused: true, guardrail: decision.by, code: decision.code, message: decision.message };
+                        }
+                        return decision.value.kind === "tool-result" ? decision.value.output : output;
+                    };
                     if (approvals === undefined) {
                         try {
-                            return collectCitations(await t.execute(input), pendingCitations);
+                            return collectCitations(await inspectResult(await t.execute(input, { ...(options ?? {}), report })), pendingCitations);
                         }
                         catch (thrown) {
                             const parked = questionMarker(thrown, t.name);
@@ -175,6 +347,9 @@ export const createDefaultEngine = (deps) => {
                             message: `${t.name} needs human approval before it can run. The run is paused; do not retry.`,
                         };
                     }
+                    // The approval path reaches the registry itself, so the fact needs no host cooperation here.
+                    if (outcome.result.ranToolName !== undefined)
+                        report({ ranToolName: outcome.result.ranToolName });
                     if (!outcome.result.ok) {
                         // The registry flattens a delegate's throw into a result, so the question arrives here as a code.
                         const parked = questionMarker(outcome.result.error, t.name);
@@ -184,7 +359,7 @@ export const createDefaultEngine = (deps) => {
                         }
                         throw new AgentPlatformError(outcome.result.error);
                     }
-                    return collectCitations(outcome.result.data, pendingCitations);
+                    return collectCitations(await inspectResult(outcome.result.data), pendingCitations);
                 },
             }));
             let attempt = 1;
@@ -238,7 +413,7 @@ export const createDefaultEngine = (deps) => {
                             controller.abort();
                             return;
                         }
-                        for (const event of mapChunk(chunk, messageId, resolved, textParts)) {
+                        for (const event of mapChunk(chunk, messageId, resolved, textParts, ranByCall)) {
                             emitted += 1;
                             yield event;
                         }
@@ -270,6 +445,8 @@ export const createDefaultEngine = (deps) => {
                      * After the stream, so a citation cannot appear above text the reader is already looking at — the
                      * append-only property `citationViewModel` depends on.
                      */
+                    for (const record of pendingVerdicts.splice(0))
+                        yield verdictEvent(record);
                     if (deps.citations !== undefined && pendingCitations.length > 0) {
                         const claims = [...textParts.values()].map((t) => t.partId);
                         if (claims.length > 0) {
@@ -392,7 +569,9 @@ function* approvalEvents(resumed, messageId, messages) {
     });
 }
 /** Map one neutral chunk to zero or more engine events. Mutates `textParts` to accumulate deltas. */
-function* mapChunk(chunk, messageId, resolved, textParts) {
+function* mapChunk(chunk, messageId, resolved, textParts, 
+/** What each call resolved to, when it was not what the model named — task #210. */
+ranByCall = new Map()) {
     switch (chunk.type) {
         case "text-delta": {
             const existing = textParts.get(chunk.id);
@@ -425,6 +604,7 @@ function* mapChunk(chunk, messageId, resolved, textParts) {
             return;
         }
         case "tool-result": {
+            const ran = ranByCall.get(chunk.toolCallId);
             const part = {
                 id: `${chunk.toolCallId}:result`,
                 type: "tool-result",
@@ -432,10 +612,16 @@ function* mapChunk(chunk, messageId, resolved, textParts) {
                 createdAt: new Date(0).toISOString(),
                 toolCallId: asId(chunk.toolCallId),
                 toolName: chunk.toolName,
+                ...(ran === undefined ? {} : { ranToolName: ran }),
                 output: chunk.output,
                 truncated: false,
             };
-            yield { type: "tool.completed", toolCallId: asId(chunk.toolCallId), toolName: chunk.toolName };
+            yield {
+                type: "tool.completed",
+                toolCallId: asId(chunk.toolCallId),
+                toolName: chunk.toolName,
+                ...(ran === undefined ? {} : { ranToolName: ran }),
+            };
             yield { type: "part.added", messageId, part };
             return;
         }

package/dist/capabilities/index.d.ts

@@ -34,7 +34,7 @@
  * which auto-approves a stated set of effects, and is auditable afterwards where a flag leaves no record. The
  * difference is between "nobody had to approve this" and "we cannot tell whether anyone should have".
  */
-export declare const CAPABILITIES: readonly ["history", "memory", "compaction", "citations", "questions", "skills", "mcp", "usage"];
+export declare const CAPABILITIES: readonly ["history", "memory", "compaction", "citations", "questions", "skills", "mcp", "usage", "guardrails", "shell"];
 export type Capability = (typeof CAPABILITIES)[number];
 export type CapabilityState = "on" | "off";
 export type CapabilityMap = Readonly<Record<Capability, CapabilityState>>;
@@ -62,6 +62,8 @@ export declare const PROFILES: {
         readonly skills: "on";
         readonly mcp: "off";
         readonly usage: "on";
+        readonly guardrails: "off";
+        readonly shell: "off";
     };
     /**
      * A headless automation: no conversation, no person, no recall.
@@ -78,6 +80,8 @@ export declare const PROFILES: {
         readonly skills: "off";
         readonly mcp: "off";
         readonly usage: "on";
+        readonly guardrails: "off";
+        readonly shell: "off";
     };
 };
 export type ProfileName = keyof typeof PROFILES;

package/dist/capabilities/index.js

@@ -44,6 +44,8 @@ export const CAPABILITIES = [
     "skills",
     "mcp",
     "usage",
+    "guardrails",
+    "shell",
 ];
 /**
  * What each capability cannot work without, by the name a host wires it under.
@@ -62,6 +64,18 @@ export const CAPABILITY_REQUIRES = {
     skills: ["skills"],
     mcp: ["mcpConnections", "mcpClient"],
     usage: ["usage"],
+    // A guardrail set, supplied by the host. Declaring the capability without wiring one is refused at
+    // construction — which is the point: "guardrails: on" must mean a check exists, not that somebody intended one.
+    guardrails: ["guardrails"],
+    /**
+     * A sandbox for `shell_exec` — REQ-047 (#206), task #215.
+     *
+     * The only capability whose *absence* is a security property rather than a missing feature. `shell_exec` is
+     * arbitrary code execution with a natural-language trigger, so it takes two switches: a sandbox wired, and this
+     * declared. Declaring it with no sandbox is refused at construction, and wiring a sandbox without declaring it
+     * leaves the tool present and refusing — which is the safe direction of the two.
+     */
+    shell: ["sandbox"],
 };
 const OFF = Object.freeze(Object.fromEntries(CAPABILITIES.map((c) => [c, "off"])));
 /**
@@ -81,6 +95,13 @@ export const PROFILES = {
         skills: "on",
         mcp: "off",
         usage: "on",
+        // Off in both profiles, deliberately. A guardrail set is the host's — and a profile that turned this on
+        // would be a profile that refuses to construct until somebody supplies one, which is a poor default for a
+        // named starting point.
+        guardrails: "off",
+        // Off in both profiles, and this one should never be otherwise: no named starting point gets to decide that
+        // an application can run shell commands.
+        shell: "off",
     },
     /**
      * A headless automation: no conversation, no person, no recall.
@@ -97,6 +118,8 @@ export const PROFILES = {
         skills: "off",
         mcp: "off",
         usage: "on",
+        guardrails: "off",
+        shell: "off",
     },
 };
 /** A profile as a plain map, so a caller can read a default before adopting it. */

package/dist/capabilities/runtime.d.ts

@@ -18,6 +18,7 @@
  * capability. Not a function a caller must remember to call first: the ones who forget are exactly the six
  * defects this module exists for. Every consumer of a store goes through the same property.
  */
+import type { Guardrail } from "../guardrails/index.js";
 import type { RunEventLog } from "../core/events.js";
 import type { InteractionStore, MessageStore, RunStore, SkillStore, ThreadSummaryStore, UsageStore } from "../persistence/index.js";
 import type { PrincipalMemoryStore } from "../principal-memory/index.js";
@@ -56,6 +57,13 @@ export type RuntimeStores = {
 export type RuntimeServices = {
     readonly summarizer?: ThreadSummarizer;
     readonly mcpClient?: McpClient;
+    /**
+     * Ordered, and the order is the host's — REQ-046 (#205), AC-7.
+     *
+     * An array rather than a record, because composition order decides the outcome when two guardrails both
+     * redact, and a record's key order is an implementation detail that changes when somebody reformats a config.
+     */
+    readonly guardrails?: readonly Guardrail[];
 };
 export type CreateRuntimeInput = {
     readonly profile?: ProfileName;

package/dist/core/budget.d.ts

@@ -0,0 +1,55 @@
+/**
+ * A token ceiling on a catalogue, and the rule that truncation is never quiet — REQ-045 (#204), task #210.
+ *
+ * The tool catalogue and the skill catalogue have the same problem: a compact entry per item, resident on every
+ * turn, linear in how many exist. #221 measured ~35 tokens per tool entry, so 200 tools is ~7,000 tokens before
+ * a word of the conversation. Two-tier loading bounded the *schemas* and left the entries.
+ *
+ * ## Truncation must be loud, and this is the whole guarantee
+ *
+ * A silently shortened catalogue is **indistinguishable from correct behaviour**. The model is not told an item
+ * was withheld; it simply never uses it, and the transcript reads as a run where the model chose not to. Nobody
+ * reviewing that run has anything to notice. So dropping is never quiet: the outcome names every dropped item,
+ * the engine turns that into a run event, and #210's AC-7 is a test that removing the event fails the build.
+ *
+ * In `core/` because both callers need it and neither owns it — and because a second copy for skills would drift
+ * from the first, which is the shape this repository keeps finding defects in.
+ */
+export type TokenBudget = {
+    /** The ceiling. A catalogue at or under it is untouched and no event is emitted. */
+    readonly maxTokens: number;
+};
+export type BudgetOutcome<T> = {
+    readonly resident: readonly T[];
+    /** Names, in the order they were dropped. Named rather than counted: a count is not actionable. */
+    readonly dropped: readonly string[];
+    readonly residentTokens: number;
+    readonly budgetTokens: number;
+    /**
+     * True when the budget could not be met even after dropping everything droppable.
+     *
+     * Distinct from "it bound", because the two need different responses: a bound budget is the mechanism working,
+     * while an unmeetable one is a misconfiguration — the protected set alone does not fit, and a deployment that
+     * believes it capped its context has not.
+     */
+    readonly overBudget: boolean;
+};
+/**
+ * Keep what fits, in the order given, and name what did not.
+ *
+ * **Order is the caller's priority**, not a ranking invented here. For tools that is the order the host's
+ * providers were registered in, which is a deployment's own statement about what matters; inventing a relevance
+ * order would mean guessing at the model's next need, and `find_tools` is the honest answer to that.
+ *
+ * `protect` names what may never be dropped. Meta-tools are the reason it exists: dropping `find_tools` or
+ * `learn_tools` to save 35 tokens would remove the model's only route back to everything else, turning a budget
+ * into a permanent amputation.
+ */
+export declare const applyTokenBudget: <T>(input: {
+    readonly items: readonly T[];
+    readonly budget: TokenBudget;
+    readonly tokensOf: (item: T) => number;
+    readonly nameOf: (item: T) => string;
+    readonly protect?: (item: T) => boolean;
+}) => BudgetOutcome<T>;
+//# sourceMappingURL=budget.d.ts.map