@retinue/agentkit 0.1.0 → 0.2.0

package/dist/core/budget.js

@@ -0,0 +1,56 @@
+/**
+ * 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.
+ */
+/**
+ * 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 const applyTokenBudget = (input) => {
+    const protectedItems = [];
+    const droppable = [];
+    for (const item of input.items)
+        (input.protect?.(item) === true ? protectedItems : droppable).push(item);
+    // Protected first, and counted even when they overrun: a report that omitted them would understate the
+    // resident cost and hide precisely the misconfiguration `overBudget` exists to name.
+    let spent = protectedItems.reduce((total, item) => total + input.tokensOf(item), 0);
+    const resident = [...protectedItems];
+    const dropped = [];
+    for (const item of droppable) {
+        const cost = input.tokensOf(item);
+        if (spent + cost <= input.budget.maxTokens) {
+            resident.push(item);
+            spent += cost;
+        }
+        else
+            dropped.push(input.nameOf(item));
+    }
+    return {
+        resident,
+        dropped,
+        residentTokens: spent,
+        budgetTokens: input.budget.maxTokens,
+        overBudget: spent > input.budget.maxTokens,
+    };
+};
+//# sourceMappingURL=budget.js.map

package/dist/core/content-parts.d.ts

@@ -34,6 +34,14 @@ export type ToolCallPart = PartBase<"tool-call"> & {
 export type ToolResultPart = PartBase<"tool-result"> & {
     readonly toolCallId: ToolCallId;
     readonly toolName: string;
+    /**
+     * What actually ran, when it differs from `toolName` — task #210.
+     *
+     * `execute_tool` names its target, so the call the model made and the action performed are two different
+     * things. Both are recorded: the first is what the model's own history says it did, and the second is what a
+     * reader needs.
+     */
+    readonly ranToolName?: string;
     /** Populated for inline results. Large results are spilled and referenced instead. */
     readonly output?: unknown;
     /** Authorized reference to an offloaded result, read back via `read_tool_output`. */

package/dist/core/events.d.ts

@@ -8,7 +8,7 @@
 import type { MessagePart } from "./content-parts.js";
 import type { PlatformError } from "./errors.js";
 import type { InteractionId, MessageId, RunId, TenantId, ToolCallId } from "./ids.js";
-export declare const RUN_EVENT_TYPES: readonly ["run.queued", "run.started", "run.checkpointed", "run.completed", "run.failed", "run.cancelled", "run.retry-pending", "part.added", "part.updated", "tool.started", "tool.completed", "tool.failed", "question.requested", "question.answered", "approval.requested", "approval.decided", "usage.updated", "context.compacted"];
+export declare const RUN_EVENT_TYPES: readonly ["run.queued", "run.started", "run.checkpointed", "run.completed", "run.failed", "run.cancelled", "run.retry-pending", "part.added", "part.updated", "tool.started", "tool.completed", "tool.failed", "question.requested", "question.answered", "approval.requested", "approval.decided", "usage.updated", "context.compacted", "guardrail.verdict", "catalog.truncated"];
 export type RunEventType = (typeof RUN_EVENT_TYPES)[number];
 type EventBase<T extends RunEventType> = {
     readonly type: T;
@@ -41,6 +41,14 @@ export type PartEvent = EventBase<"part.added" | "part.updated"> & {
 export type ToolEvent = EventBase<"tool.started" | "tool.completed" | "tool.failed"> & {
     readonly toolCallId: ToolCallId;
     readonly toolName: string;
+    /**
+     * The tool that actually ran, when the model called `execute_tool` — task #210.
+     *
+     * Absent on `tool.started`, because at that point nothing has resolved the target yet. Present on completion
+     * and failure, where it is the difference between an audit trail that names an action and one that names a
+     * mechanism.
+     */
+    readonly ranToolName?: string;
 };
 export type InteractionEvent = EventBase<"question.requested" | "question.answered" | "approval.requested" | "approval.decided"> & {
     readonly interactionId: InteractionId;
@@ -70,7 +78,65 @@ export type ContextCompactedEvent = EventBase<"context.compacted"> & {
     readonly droppedParts: number;
     readonly tokensReclaimed: number;
 };
-export type RunEvent = RunLifecycleEvent | RunFailedEvent | RunRetryPendingEvent | PartEvent | ToolEvent | InteractionEvent | UsageUpdatedEvent | ContextCompactedEvent;
+/**
+ * What a guardrail concluded — REQ-046 (#205).
+ *
+ * Emitted for every verdict, including a pass, because "no guardrail ran" and "a guardrail ran and allowed it"
+ * are different facts and an incident review needs to tell them apart.
+ *
+ * **Carries no inspected value, ever.** `what` names fields or entity types; the content that was redacted is
+ * precisely what must not travel into an event log, a trace, or a support ticket — otherwise the audit trail
+ * becomes the leak it exists to record.
+ */
+export type GuardrailVerdictEvent = EventBase<"guardrail.verdict"> & {
+    readonly guardrail: string;
+    readonly subject: "input" | "message" | "tool-call" | "tool-result";
+    readonly outcome: "pass" | "redacted" | "refused";
+    /** For a redaction: the fields or entity types touched. Never their contents. */
+    readonly what?: readonly string[];
+    /** For a refusal. */
+    readonly code?: string;
+    /** True when the guardrail threw and was therefore treated as a refusal. */
+    readonly threw?: boolean;
+};
+/**
+ * A catalogue did not fit its budget, and what was left out — REQ-045 (#204), task #210, AC-3 and AC-5.
+ *
+ * This event *is* the guarantee. A truncated tool list is invisible from inside a run: the model is not told a
+ * tool was withheld, so it never calls it, and the transcript reads exactly like a run where the model chose
+ * not to. Every other failure at least looks like a failure; this one looks like a decision. So the names go in
+ * the log, in full, and #210's AC-7 is a test that deleting this event fails the build.
+ *
+ * Names, not a count. "14 tools were dropped" tells a reader that something happened and nothing about whether
+ * it mattered; `github_merge_pull_request` tells them immediately.
+ */
+export type CatalogTruncatedEvent = EventBase<"catalog.truncated"> & {
+    /**
+     * Which catalogue. One event rather than two, because the fact is the same fact and a reader asking "what was
+     * withheld from this turn" should not have to know there are two mechanisms.
+     */
+    readonly catalog: "tools" | "skills";
+    readonly budgetTokens: number;
+    readonly residentTokens: number;
+    /** Every dropped tool, by name. */
+    readonly dropped: readonly string[];
+    /**
+     * Whether the model can still get to what was dropped.
+     *
+     * `find_tools` makes a truncated tool catalogue a *deferral*; without it the same event describes a permanent
+     * removal, and a reader cannot tell which from the names alone. There is no `find_skills`, so a truncated
+     * skill catalogue is always `false` today — which is a fact worth having in the log rather than a field to
+     * leave off.
+     */
+    readonly findable: boolean;
+    /**
+     * Set when the protected set alone exceeds the budget — a misconfiguration, not the mechanism working.
+     *
+     * A deployment in this state believes it capped its context and has not.
+     */
+    readonly overBudget?: boolean;
+};
+export type RunEvent = RunLifecycleEvent | RunFailedEvent | RunRetryPendingEvent | PartEvent | ToolEvent | InteractionEvent | UsageUpdatedEvent | ContextCompactedEvent | GuardrailVerdictEvent | CatalogTruncatedEvent;
 /** Fan-out port. Adapters: Supabase Realtime, Redis pub/sub, in-memory for tests. */
 export interface RealtimePublisher {
     publish(channel: string, event: RunEvent): Promise<void>;

package/dist/core/events.js

@@ -24,6 +24,8 @@ export const RUN_EVENT_TYPES = [
     "approval.decided",
     "usage.updated",
     "context.compacted",
+    "guardrail.verdict",
+    "catalog.truncated",
 ];
 export const EMPTY_RUN_STREAM_STATE = {
     parts: [],

package/dist/core/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./ids.js";
+export * from "./budget.js";
 export * from "./tokens.js";
 export * from "./context.js";
 export * from "./content-parts.js";

package/dist/core/index.js

@@ -1,4 +1,5 @@
 export * from "./ids.js";
+export * from "./budget.js";
 export * from "./tokens.js";
 export * from "./context.js";
 export * from "./content-parts.js";

package/dist/documents/index.d.ts

@@ -73,6 +73,20 @@ export type ExtractedDocument = {
      * answer, and a log line does not reach them.
      */
     readonly warnings: readonly string[];
+    /**
+     * YAML front matter, when the source had a leading `---` block — REQ-050 (#209), task #220.
+     *
+     * **Scalar keys only, and deliberately not a YAML parser.** A nested mapping, a list of mappings or a flow
+     * collection is reported in `warnings` and otherwise dropped, because a half-correct parse of provenance
+     * metadata is worse than none: `generated: { by: x, at: y }` silently read as the string `{ by: x, at: y }`
+     * would be recorded as if it had been understood.
+     *
+     * It exists because the alternative was worse. Front matter used to reach the block stream as *content*: a
+     * document's `sidebar_position` and `type` became a paragraph, got chunked, embedded, and could be returned as
+     * a retrieval hit and cited. #220 found it while reading the Open Knowledge Format — whose concept files carry
+     * far more metadata than ours — and it was already happening to this repository's own documentation site.
+     */
+    readonly frontMatter?: Readonly<Record<string, string>>;
     /**
      * How confident the extraction is, 0–1 (#132).
      *

package/dist/documents/parsers/text.d.ts

@@ -30,6 +30,22 @@ export type BlockBuilder = ReturnType<typeof createBlockBuilder>;
  * Plain text has no headings or tables, so running it through the same parser costs nothing and means one
  * code path instead of two that differ in how they split paragraphs.
  */
+/**
+ * A leading `---` block, split off before anything else reads the document — task #220.
+ *
+ * Returns the remaining lines and the scalar keys, and **names what it could not read** rather than guessing.
+ * Front matter is metadata about a document, not part of it: left in the stream it becomes a paragraph, gets
+ * chunked and embedded, and can be returned as a retrieval hit — so a question about revenue policy can be
+ * answered with a block of YAML.
+ *
+ * Scalar keys only. `generated: { by: x, at: y }` read as the *string* `{ by: x, at: y }` would be provenance
+ * recorded as if it had been understood, which is worse than a warning saying it was skipped.
+ */
+export declare const splitFrontMatter: (lines: readonly string[]) => {
+    readonly body: readonly string[];
+    readonly fields: Record<string, string>;
+    readonly warnings: readonly string[];
+};
 export declare const parseMarkdown: (bytes: Uint8Array, limits: ExtractionLimits) => ExtractedDocument;
 /**
  * A CSV row splitter that understands quotes.

package/dist/documents/parsers/text.js

@@ -96,9 +96,56 @@ const isPipeDivider = (line) => /^\s*\|?\s*:?-{2,}:?\s*(\|\s*:?-{2,}:?\s*)*\|?\s
  * Plain text has no headings or tables, so running it through the same parser costs nothing and means one
  * code path instead of two that differ in how they split paragraphs.
  */
+/**
+ * A leading `---` block, split off before anything else reads the document — task #220.
+ *
+ * Returns the remaining lines and the scalar keys, and **names what it could not read** rather than guessing.
+ * Front matter is metadata about a document, not part of it: left in the stream it becomes a paragraph, gets
+ * chunked and embedded, and can be returned as a retrieval hit — so a question about revenue policy can be
+ * answered with a block of YAML.
+ *
+ * Scalar keys only. `generated: { by: x, at: y }` read as the *string* `{ by: x, at: y }` would be provenance
+ * recorded as if it had been understood, which is worse than a warning saying it was skipped.
+ */
+export const splitFrontMatter = (lines) => {
+    if ((lines[0] ?? "").trim() !== "---")
+        return { body: lines, fields: {}, warnings: [] };
+    const end = lines.findIndex((line, at) => at > 0 && line.trim() === "---");
+    // No closing fence: a document that happens to start with a horizontal rule, not front matter.
+    if (end === -1)
+        return { body: lines, fields: {}, warnings: [] };
+    const fields = {};
+    const skipped = [];
+    for (const line of lines.slice(1, end)) {
+        if (line.trim() === "" || line.trimStart().startsWith("#"))
+            continue;
+        // An indented line or a list item belongs to a structure this does not read.
+        if (/^\s/.test(line) || line.trimStart().startsWith("- "))
+            continue;
+        const match = /^([A-Za-z_][\w.-]*)\s*:\s*(.*)$/.exec(line);
+        if (match === null)
+            continue;
+        const [, key, raw] = match;
+        const value = (raw ?? "").trim();
+        // A flow collection or the start of a block one: named as skipped, never half-read.
+        if (value === "" || value.startsWith("{") || value.startsWith("[")) {
+            skipped.push(key);
+            continue;
+        }
+        fields[key] = value.replace(/^["']|["']$/g, "");
+    }
+    return {
+        body: lines.slice(end + 1),
+        fields,
+        warnings: skipped.length === 0
+            ? []
+            : [`front matter key(s) not read because they are not scalars: ${skipped.join(", ")}`],
+    };
+};
 export const parseMarkdown = (bytes, limits) => {
     const builder = createBlockBuilder(limits);
-    const lines = decode(bytes).split(/\r?\n/);
+    const matter = splitFrontMatter(decode(bytes).split(/\r?\n/));
+    const lines = matter.body;
     let paragraph = [];
     const flushParagraph = () => {
         if (paragraph.length === 0)
@@ -176,7 +223,12 @@ export const parseMarkdown = (bytes, limits) => {
     }
     flushParagraph();
     flushList();
-    return builder.done();
+    const parsed = builder.done();
+    return {
+        ...parsed,
+        ...(Object.keys(matter.fields).length === 0 ? {} : { frontMatter: matter.fields }),
+        warnings: [...parsed.warnings, ...matter.warnings],
+    };
 };
 /**
  * A CSV row splitter that understands quotes.

package/dist/entries/guardrails.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `@retinue/agentkit/guardrails` — checks a deployment adds, and the contract they satisfy.
+ *
+ * Its own subpath rather than part of `./hitl`, though both stop a run. The distinction is who decides: a
+ * guardrail is an automated inspection whose verdict is final, and HITL is a person being asked. Putting them
+ * together would invite a host to treat a refusal as something a human could override, which is precisely what a
+ * guardrail must not be.
+ *
+ * Nothing here imports a provider or a store, so declaring the capability costs a consumer no dependency.
+ */
+export * from "../guardrails/index.js";
+export * from "../guardrails/pii.js";
+export * from "../guardrails/moderation.js";
+//# sourceMappingURL=guardrails.d.ts.map

package/dist/entries/guardrails.js

@@ -0,0 +1,14 @@
+/**
+ * `@retinue/agentkit/guardrails` — checks a deployment adds, and the contract they satisfy.
+ *
+ * Its own subpath rather than part of `./hitl`, though both stop a run. The distinction is who decides: a
+ * guardrail is an automated inspection whose verdict is final, and HITL is a person being asked. Putting them
+ * together would invite a host to treat a refusal as something a human could override, which is precisely what a
+ * guardrail must not be.
+ *
+ * Nothing here imports a provider or a store, so declaring the capability costs a consumer no dependency.
+ */
+export * from "../guardrails/index.js";
+export * from "../guardrails/pii.js";
+export * from "../guardrails/moderation.js";
+//# sourceMappingURL=guardrails.js.map

package/dist/entries/knowledge.d.ts

@@ -15,4 +15,13 @@ export * from "../artifacts/index.js";
 export * from "../export/index.js";
 export * from "../export/pdf.js";
 export * from "../export/markdown.js";
+/**
+ * The one embedding adapter — REQ-050 (#209), task #219.
+ *
+ * Here rather than behind an `adapters/*` subpath because it carries no driver: it is a `fetch` to an
+ * OpenAI-shaped endpoint, so it adds nothing to a consumer's install. The Postgres and Redis adapters have their
+ * own subpaths because they each pull a client library in.
+ */
+export { DEFAULT_EMBEDDING_BATCH, DEFAULT_EMBEDDING_MODEL, createOpenAiEmbeddings } from "../adapters/embeddings/openai.js";
+export type { OpenAiEmbeddingsConfig } from "../adapters/embeddings/openai.js";
 //# sourceMappingURL=knowledge.d.ts.map

package/dist/entries/knowledge.js

@@ -16,4 +16,12 @@ export * from "../artifacts/index.js";
 export * from "../export/index.js";
 export * from "../export/pdf.js";
 export * from "../export/markdown.js";
+/**
+ * The one embedding adapter — REQ-050 (#209), task #219.
+ *
+ * Here rather than behind an `adapters/*` subpath because it carries no driver: it is a `fetch` to an
+ * OpenAI-shaped endpoint, so it adds nothing to a consumer's install. The Postgres and Redis adapters have their
+ * own subpaths because they each pull a client library in.
+ */
+export { DEFAULT_EMBEDDING_BATCH, DEFAULT_EMBEDDING_MODEL, createOpenAiEmbeddings } from "../adapters/embeddings/openai.js";
 //# sourceMappingURL=knowledge.js.map

package/dist/graphql/resolvers.d.ts

@@ -76,6 +76,10 @@ export declare const createResolvers: (deps: ResolverDeps) => {
             categories: string[];
             excluded: string[];
         }, ctx: GraphQLContext): Promise<import("../tools/registry.js").ToolCatalog>;
+        findTools(_: unknown, args: {
+            query: string;
+            limit?: number;
+        }, ctx: GraphQLContext): Promise<import("../tools/find.js").ToolSearchOutcome>;
         usage(_: unknown, args: {
             runId?: string;
         }, ctx: GraphQLContext): Promise<import("../persistence/index.js").UsageTotals>;

package/dist/graphql/resolvers.js

@@ -75,6 +75,12 @@ export const createResolvers = (deps) => {
             async toolCatalog(_, args, ctx) {
                 return deps.toolRegistry.catalog(ctx.execution, args);
             },
+            async findTools(_, args, ctx) {
+                return deps.toolRegistry.find(ctx.execution, {
+                    query: args.query,
+                    ...(args.limit === undefined ? {} : { limit: args.limit }),
+                });
+            },
             async usage(_, args, ctx) {
                 return deps.usage.totals({ tenantId: tid(ctx), ...(args.runId ? { runId: asId(args.runId) } : {}) });
             },

package/dist/graphql/schema.d.ts

@@ -7,5 +7,5 @@
  * platform service. Subscriptions carry the stable `RunEvent` set and support resuming after a
  * cursor via `openRunEventStream`.
  */
-export declare const typeDefs = "\n  scalar JSON\n  scalar DateTime\n\n  type Conversation {\n    id: ID!\n    title: String!\n    version: Int!\n    archivedAt: DateTime\n    createdAt: DateTime!\n    updatedAt: DateTime!\n  }\n\n  type ConversationPage {\n    items: [Conversation!]!\n    nextCursor: String\n  }\n\n  enum RunStatus {\n    queued\n    running\n    waiting_for_question\n    waiting_for_approval\n    retry_pending\n    completed\n    failed\n    cancelled\n  }\n\n  type Run {\n    id: ID!\n    \"Null for a run that belongs to no conversation \u2014 a triggered automation rather than a chat turn (#198).\"\n    conversationId: ID\n    status: RunStatus!\n    createdAt: DateTime!\n    finishedAt: DateTime\n  }\n\n  type ToolCatalogEntry {\n    name: String!\n    label: String!\n    description: String!\n    category: String!\n    effect: String!\n  }\n\n  type ToolCatalog {\n    preloaded: [JSON!]!\n    discoverable: [ToolCatalogEntry!]!\n    meta: [ToolCatalogEntry!]!\n  }\n\n  type UsageTotals {\n    inputTokens: Int!\n    outputTokens: Int!\n    cachedInputTokens: Int!\n    costMinorUnits: Int!\n    eventCount: Int!\n  }\n\n  \"One period's consumption. #139's rollups, so a chart never scans raw records.\"\n  type UsageBucket {\n    bucketStart: String!\n    totals: UsageTotals!\n    currency: String!\n  }\n\n  \"Consumption grouped by model or conversation over the requested range.\"\n  type UsageBreakdownEntry {\n    key: String!\n    totals: UsageTotals!\n  }\n\n  \"\"\"\n  Where the tenant stands against its limit.\n\n  Absent when no limit is configured \u2014 which means unbounded, not zero. A UI must show \"no limit set\"\n  rather than a full bar.\n  \"\"\"\n  type UsageQuota {\n    \"\"\"\n    The window in words \u2014 \"the day\", \"any 5 hours\" (#181).\n\n    period stayed for the calendar case and is **null** for a rolling window, because no RollupPeriod describes\n    one and returning \"hour\" for a five-hour window would be a wrong answer rather than a missing one. A client\n    rendering the window reads this field; one keying a chart by bucket reads period and correctly finds nothing\n    to key by.\n    \"\"\"\n    window: String!\n    period: String\n    \"The model this limit covers, or null for any model (#182).\"\n    modelId: String\n    costLimitMinorUnits: Int\n    inputTokenLimit: Int\n    outputTokenLimit: Int\n    \"The fraction of the limit at which a warning shows. Sent so the UI cannot disagree with the server.\"\n    warnAt: Float!\n    \"True once any dimension is past warnAt and still admitted.\"\n    warning: Boolean!\n    \"True once any dimension has reached its limit, so work is being refused.\"\n    exceeded: Boolean!\n  }\n\n  \"\"\"\n  The usage report a spend panel renders.\n\n  One query rather than several, so a panel cannot show a total from one moment and a breakdown from another.\n  \"\"\"\n  type UsageReport {\n    period: String!\n    from: String!\n    to: String!\n    totals: UsageTotals!\n    buckets: [UsageBucket!]!\n    byModel: [UsageBreakdownEntry!]!\n    byConversation: [UsageBreakdownEntry!]!\n    quota: UsageQuota\n    currency: String!\n  }\n\n  \"A single transport event; payload carries the typed part / lifecycle detail.\"\n  type RunEvent {\n    type: String!\n    runId: ID!\n    sequence: Int!\n    occurredAt: DateTime!\n    payload: JSON!\n  }\n\n  \"\"\"\n  One question put to a person, as it must be *rendered* \u2014 #163.\n\n  The event that suspends a run carries only an interactionId, deliberately: events are thin, and a payload\n  that duplicated the question would be a second copy to keep in step with the stored one. But nothing exposed\n  the stored one either, so a client could answer a question it had no way to display. The example's picker\n  rendered an empty text box next to \"The assistant has a question\", which is the whole gap in one screenshot.\n  \"\"\"\n  type PendingQuestionSpec {\n    \"Stable key the answer is filed under.\"\n    key: String!\n    prompt: String!\n    \"A short closed list, when there is one. Empty means free text.\"\n    options: [String!]!\n    \"Several choices are allowed, not one.\"\n    multiple: Boolean!\n    \"Free text is accepted alongside the options.\"\n    allowOther: Boolean!\n  }\n\n  type PendingQuestion {\n    interactionId: ID!\n    runId: ID!\n    questions: [PendingQuestionSpec!]!\n    createdAt: DateTime!\n  }\n\n  \"\"\"\n  The approval a run is parked on \u2014 the read side of decideApproval (#163).\n\n  The same gap as pendingQuestion and milder rather than absent: approval.requested also carries only an\n  interaction id, so a client had no summary to show and fell back to a generic \"Run a tool?\". Asking someone\n  to authorise an action the card cannot name is how approval becomes a reflex.\n  \"\"\"\n  type PendingApprovalDetail {\n    interactionId: ID!\n    runId: ID!\n    toolName: String!\n    \"One line a person can decide on, written by the host's summarizer.\"\n    summary: String!\n    riskCategory: String!\n    expiresAt: DateTime!\n    \"The arguments the approval is for, so what runs is what was shown.\"\n    normalizedInput: JSON!\n  }\n\n  input QuestionAnswerInput {\n    interactionId: ID!\n    runId: ID!\n    answers: JSON!\n  }\n\n  input ApprovalDecisionInput {\n    interactionId: ID!\n    runId: ID!\n    decision: String!\n  }\n\n  \"A section that shaped a turn's prompt \u2014 for the context inspector (#39).\"\n  type InspectedSection {\n    title: String!\n    providerId: String!\n    kind: String!\n    provenance: String!\n    estimatedTokens: Int!\n    sensitivity: String!\n    included: Boolean!\n    prunedReason: String\n  }\n\n  type ContextInspection {\n    sections: [InspectedSection!]!\n    totalTokens: Int!\n    budget: JSON!\n  }\n\n  type Query {\n    conversations(limit: Int!, cursor: String): ConversationPage!\n    conversation(id: ID!): Conversation\n    run(id: ID!): Run\n    toolCatalog(preloaded: [String!]!, categories: [String!]!, excluded: [String!]!): ToolCatalog!\n    usage(runId: ID): UsageTotals!\n    \"\"\"\n    Consumption and cost by period, with breakdowns and quota state (#140).\n\n    An extension of the usage query rather than a second endpoint: a panel showing a total from one query and a\n    breakdown from another can show two moments at once, and the discrepancy looks like a bug in the numbers.\n    \"\"\"\n    usageReport(period: String!, from: String!, to: String!, breakdownLimit: Int): UsageReport!\n    \"What context shaped a turn \u2014 attributes memory/tools/history that influenced the prompt.\"\n    conversationContext(conversationId: ID!, runId: ID): ContextInspection\n    \"\"\"\n    The question a run is parked on, or null \u2014 the read side of answerQuestion (#163).\n\n    Null covers both \"this run was never asked anything\" and \"it has been answered already\", because a client\n    has the same thing to do in either case: show no picker. A run that is waiting is the only state with a\n    question to render.\n    \"\"\"\n    pendingQuestion(runId: ID!): PendingQuestion\n    \"The approval a run is parked on, or null (#163).\"\n    pendingApproval(runId: ID!): PendingApprovalDetail\n  }\n\n  type Mutation {\n    createConversation(id: ID!, title: String!): Conversation!\n    renameConversation(id: ID!, expectedVersion: Int!, title: String!): Conversation!\n    archiveConversation(id: ID!, expectedVersion: Int!): Conversation!\n    deleteConversation(id: ID!): Boolean!\n    sendMessage(conversationId: ID!, runId: ID!): Run!\n    cancelRun(runId: ID!): Boolean!\n    answerQuestion(input: QuestionAnswerInput!): Boolean!\n    decideApproval(input: ApprovalDecisionInput!): Boolean!\n  }\n\n  type Subscription {\n    \"Conversation/run events, resumable after a cursor (sequence).\"\n    runEvents(runId: ID!, conversationId: ID!, after: Int): RunEvent!\n  }\n";
+export declare const typeDefs = "\n  scalar JSON\n  scalar DateTime\n\n  type Conversation {\n    id: ID!\n    title: String!\n    version: Int!\n    archivedAt: DateTime\n    createdAt: DateTime!\n    updatedAt: DateTime!\n  }\n\n  type ConversationPage {\n    items: [Conversation!]!\n    nextCursor: String\n  }\n\n  enum RunStatus {\n    queued\n    running\n    waiting_for_question\n    waiting_for_approval\n    retry_pending\n    completed\n    failed\n    cancelled\n  }\n\n  type Run {\n    id: ID!\n    \"Null for a run that belongs to no conversation \u2014 a triggered automation rather than a chat turn (#198).\"\n    conversationId: ID\n    status: RunStatus!\n    createdAt: DateTime!\n    finishedAt: DateTime\n  }\n\n  type ToolCatalogEntry {\n    name: String!\n    label: String!\n    description: String!\n    category: String!\n    effect: String!\n  }\n\n  \"\"\"\n  What was withheld from a catalogue, and why \u2014 REQ-045 (#204), task #210.\n\n  Present only when a budget bound. A client rendering a shortened list with nothing saying it was shortened\n  is the same invisible failure the run event exists to prevent, one layer out.\n  \"\"\"\n  type ToolCatalogTruncation {\n    budgetTokens: Int!\n    residentTokens: Int!\n    dropped: [String!]!\n    \"Whether find_tools is wired, which is the difference between a deferral and a removal.\"\n    findable: Boolean!\n    \"True when the protected set alone exceeds the budget: a misconfiguration, not the mechanism working.\"\n    overBudget: Boolean!\n  }\n\n  \"The tenant's category switches as they were applied \u2014 task #210, AC-4.\"\n  type TenantToolset {\n    enabledCategories: [String!]\n    disabledCategories: [String!]\n  }\n\n  type ToolCatalog {\n    preloaded: [JSON!]!\n    discoverable: [ToolCatalogEntry!]!\n    meta: [ToolCatalogEntry!]!\n    truncation: ToolCatalogTruncation\n    toolset: TenantToolset\n  }\n\n  \"A tool found by describing a need \u2014 task #210, AC-1. Filtered by the same authorization as discovery.\"\n  type ToolSearchHit {\n    entry: ToolCatalogEntry!\n    score: Float!\n    signals: [String!]!\n  }\n\n  type ToolSearchResult {\n    hits: [ToolSearchHit!]!\n    \"The signals actually used. Keyword-only when no embedding provider is wired.\"\n    modes: [String!]!\n  }\n\n  type UsageTotals {\n    inputTokens: Int!\n    outputTokens: Int!\n    cachedInputTokens: Int!\n    costMinorUnits: Int!\n    eventCount: Int!\n  }\n\n  \"One period's consumption. #139's rollups, so a chart never scans raw records.\"\n  type UsageBucket {\n    bucketStart: String!\n    totals: UsageTotals!\n    currency: String!\n  }\n\n  \"Consumption grouped by model or conversation over the requested range.\"\n  type UsageBreakdownEntry {\n    key: String!\n    totals: UsageTotals!\n  }\n\n  \"\"\"\n  Where the tenant stands against its limit.\n\n  Absent when no limit is configured \u2014 which means unbounded, not zero. A UI must show \"no limit set\"\n  rather than a full bar.\n  \"\"\"\n  type UsageQuota {\n    \"\"\"\n    The window in words \u2014 \"the day\", \"any 5 hours\" (#181).\n\n    period stayed for the calendar case and is **null** for a rolling window, because no RollupPeriod describes\n    one and returning \"hour\" for a five-hour window would be a wrong answer rather than a missing one. A client\n    rendering the window reads this field; one keying a chart by bucket reads period and correctly finds nothing\n    to key by.\n    \"\"\"\n    window: String!\n    period: String\n    \"The model this limit covers, or null for any model (#182).\"\n    modelId: String\n    costLimitMinorUnits: Int\n    inputTokenLimit: Int\n    outputTokenLimit: Int\n    \"The fraction of the limit at which a warning shows. Sent so the UI cannot disagree with the server.\"\n    warnAt: Float!\n    \"True once any dimension is past warnAt and still admitted.\"\n    warning: Boolean!\n    \"True once any dimension has reached its limit, so work is being refused.\"\n    exceeded: Boolean!\n  }\n\n  \"\"\"\n  The usage report a spend panel renders.\n\n  One query rather than several, so a panel cannot show a total from one moment and a breakdown from another.\n  \"\"\"\n  type UsageReport {\n    period: String!\n    from: String!\n    to: String!\n    totals: UsageTotals!\n    buckets: [UsageBucket!]!\n    byModel: [UsageBreakdownEntry!]!\n    byConversation: [UsageBreakdownEntry!]!\n    quota: UsageQuota\n    currency: String!\n  }\n\n  \"A single transport event; payload carries the typed part / lifecycle detail.\"\n  type RunEvent {\n    type: String!\n    runId: ID!\n    sequence: Int!\n    occurredAt: DateTime!\n    payload: JSON!\n  }\n\n  \"\"\"\n  One question put to a person, as it must be *rendered* \u2014 #163.\n\n  The event that suspends a run carries only an interactionId, deliberately: events are thin, and a payload\n  that duplicated the question would be a second copy to keep in step with the stored one. But nothing exposed\n  the stored one either, so a client could answer a question it had no way to display. The example's picker\n  rendered an empty text box next to \"The assistant has a question\", which is the whole gap in one screenshot.\n  \"\"\"\n  type PendingQuestionSpec {\n    \"Stable key the answer is filed under.\"\n    key: String!\n    prompt: String!\n    \"A short closed list, when there is one. Empty means free text.\"\n    options: [String!]!\n    \"Several choices are allowed, not one.\"\n    multiple: Boolean!\n    \"Free text is accepted alongside the options.\"\n    allowOther: Boolean!\n  }\n\n  type PendingQuestion {\n    interactionId: ID!\n    runId: ID!\n    questions: [PendingQuestionSpec!]!\n    createdAt: DateTime!\n  }\n\n  \"\"\"\n  The approval a run is parked on \u2014 the read side of decideApproval (#163).\n\n  The same gap as pendingQuestion and milder rather than absent: approval.requested also carries only an\n  interaction id, so a client had no summary to show and fell back to a generic \"Run a tool?\". Asking someone\n  to authorise an action the card cannot name is how approval becomes a reflex.\n  \"\"\"\n  type PendingApprovalDetail {\n    interactionId: ID!\n    runId: ID!\n    toolName: String!\n    \"One line a person can decide on, written by the host's summarizer.\"\n    summary: String!\n    riskCategory: String!\n    expiresAt: DateTime!\n    \"The arguments the approval is for, so what runs is what was shown.\"\n    normalizedInput: JSON!\n  }\n\n  input QuestionAnswerInput {\n    interactionId: ID!\n    runId: ID!\n    answers: JSON!\n  }\n\n  input ApprovalDecisionInput {\n    interactionId: ID!\n    runId: ID!\n    decision: String!\n  }\n\n  \"A section that shaped a turn's prompt \u2014 for the context inspector (#39).\"\n  type InspectedSection {\n    title: String!\n    providerId: String!\n    kind: String!\n    provenance: String!\n    estimatedTokens: Int!\n    sensitivity: String!\n    included: Boolean!\n    prunedReason: String\n  }\n\n  type ContextInspection {\n    sections: [InspectedSection!]!\n    totalTokens: Int!\n    budget: JSON!\n  }\n\n  type Query {\n    conversations(limit: Int!, cursor: String): ConversationPage!\n    conversation(id: ID!): Conversation\n    run(id: ID!): Run\n    toolCatalog(preloaded: [String!]!, categories: [String!]!, excluded: [String!]!): ToolCatalog!\n    \"\"\"\n    Search the catalogue by describing what you need \u2014 task #210, AC-1.\n\n    Returns nothing at all when no search is configured, rather than failing: a client asking for a capability\n    the deployment did not wire should render an empty result, not an error dialog.\n    \"\"\"\n    findTools(query: String!, limit: Int): ToolSearchResult!\n    usage(runId: ID): UsageTotals!\n    \"\"\"\n    Consumption and cost by period, with breakdowns and quota state (#140).\n\n    An extension of the usage query rather than a second endpoint: a panel showing a total from one query and a\n    breakdown from another can show two moments at once, and the discrepancy looks like a bug in the numbers.\n    \"\"\"\n    usageReport(period: String!, from: String!, to: String!, breakdownLimit: Int): UsageReport!\n    \"What context shaped a turn \u2014 attributes memory/tools/history that influenced the prompt.\"\n    conversationContext(conversationId: ID!, runId: ID): ContextInspection\n    \"\"\"\n    The question a run is parked on, or null \u2014 the read side of answerQuestion (#163).\n\n    Null covers both \"this run was never asked anything\" and \"it has been answered already\", because a client\n    has the same thing to do in either case: show no picker. A run that is waiting is the only state with a\n    question to render.\n    \"\"\"\n    pendingQuestion(runId: ID!): PendingQuestion\n    \"The approval a run is parked on, or null (#163).\"\n    pendingApproval(runId: ID!): PendingApprovalDetail\n  }\n\n  type Mutation {\n    createConversation(id: ID!, title: String!): Conversation!\n    renameConversation(id: ID!, expectedVersion: Int!, title: String!): Conversation!\n    archiveConversation(id: ID!, expectedVersion: Int!): Conversation!\n    deleteConversation(id: ID!): Boolean!\n    sendMessage(conversationId: ID!, runId: ID!): Run!\n    cancelRun(runId: ID!): Boolean!\n    answerQuestion(input: QuestionAnswerInput!): Boolean!\n    decideApproval(input: ApprovalDecisionInput!): Boolean!\n  }\n\n  type Subscription {\n    \"Conversation/run events, resumable after a cursor (sequence).\"\n    runEvents(runId: ID!, conversationId: ID!, after: Int): RunEvent!\n  }\n";
 //# sourceMappingURL=schema.d.ts.map

package/dist/graphql/schema.js

@@ -53,10 +53,47 @@ export const typeDefs = /* GraphQL */ `
     effect: String!
   }
 
+  """
+  What was withheld from a catalogue, and why — REQ-045 (#204), task #210.
+
+  Present only when a budget bound. A client rendering a shortened list with nothing saying it was shortened
+  is the same invisible failure the run event exists to prevent, one layer out.
+  """
+  type ToolCatalogTruncation {
+    budgetTokens: Int!
+    residentTokens: Int!
+    dropped: [String!]!
+    "Whether find_tools is wired, which is the difference between a deferral and a removal."
+    findable: Boolean!
+    "True when the protected set alone exceeds the budget: a misconfiguration, not the mechanism working."
+    overBudget: Boolean!
+  }
+
+  "The tenant's category switches as they were applied — task #210, AC-4."
+  type TenantToolset {
+    enabledCategories: [String!]
+    disabledCategories: [String!]
+  }
+
   type ToolCatalog {
     preloaded: [JSON!]!
     discoverable: [ToolCatalogEntry!]!
     meta: [ToolCatalogEntry!]!
+    truncation: ToolCatalogTruncation
+    toolset: TenantToolset
+  }
+
+  "A tool found by describing a need — task #210, AC-1. Filtered by the same authorization as discovery."
+  type ToolSearchHit {
+    entry: ToolCatalogEntry!
+    score: Float!
+    signals: [String!]!
+  }
+
+  type ToolSearchResult {
+    hits: [ToolSearchHit!]!
+    "The signals actually used. Keyword-only when no embedding provider is wired."
+    modes: [String!]!
   }
 
   type UsageTotals {
@@ -217,6 +254,13 @@ export const typeDefs = /* GraphQL */ `
     conversation(id: ID!): Conversation
     run(id: ID!): Run
     toolCatalog(preloaded: [String!]!, categories: [String!]!, excluded: [String!]!): ToolCatalog!
+    """
+    Search the catalogue by describing what you need — task #210, AC-1.
+
+    Returns nothing at all when no search is configured, rather than failing: a client asking for a capability
+    the deployment did not wire should render an empty result, not an error dialog.
+    """
+    findTools(query: String!, limit: Int): ToolSearchResult!
     usage(runId: ID): UsageTotals!
     """
     Consumption and cost by period, with breakdowns and quota state (#140).

package/dist/guardrails/index.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Guardrails — REQ-046 (#205), task #211.
+ *
+ * A seam for checks a deployment needs and this runtime does not ship: PII redaction, moderation, a topic
+ * restriction, an output schema. Without it, a deployment that needs any of those has to edit the engine.
+ *
+ * The injection half of "guardrails" is already built and lives elsewhere (`security/prompt-safety.ts`), and it
+ * is deliberately *not* a guardrail in this sense: containment is structural — untrusted content is wrapped in a
+ * nonce-delimited envelope whether or not anything recognises an attack — whereas everything here is
+ * *inspection*, which can only act on what it detects. Conflating the two would invite someone to switch off
+ * containment because a detector is present.
+ *
+ * ## Three decisions that make this worth having
+ *
+ * **Tool calls are outputs.** A guardrail that inspects only the final message can be walked straight past by
+ * putting the data in a tool argument. Checking prose and not arguments is checking the boring half, so
+ * `GuardrailOutput` is a discriminated union of a message *and* a tool call, and the tool-call case is enforced
+ * at the one choke point every call goes through.
+ *
+ * **Fail closed.** A guardrail that throws refuses the turn, attributed to the guardrail that threw. The
+ * opposite default is how a guardrail silently stops guarding the day its dependency times out — and the run
+ * looks entirely normal afterwards, which is the property that makes it dangerous.
+ *
+ * **Every verdict is recorded, and never the value.** A redaction that leaves no trace is indistinguishable from
+ * the model never having been told, which makes an incident unreconstructable. So a record names *what* was
+ * redacted — the field, the entity type — and never what it contained, or the audit trail becomes the leak.
+ */
+import type { ExecutionContext } from "../core/context.js";
+/** What a guardrail may conclude. */
+export declare const GUARDRAIL_OUTCOMES: readonly ["pass", "redacted", "refused"];
+export type GuardrailOutcome = (typeof GUARDRAIL_OUTCOMES)[number];
+/** The turn's input, before the model sees it. */
+export type GuardrailInput = {
+    readonly text: string;
+    /** Identifiers only. A guardrail that needs contents reads them through the file service, under its own budget. */
+    readonly attachmentIds?: readonly string[];
+};
+/**
+ * Every boundary crossing that is not the turn's own input.
+ *
+ * Three kinds, one hook, deliberately. A separate hook per kind lets an author implement two of three and have a
+ * gap they did not choose — and the gap would be in whichever kind was added last, which is the one nobody
+ * remembers. The union forces the `switch` to be written.
+ *
+ * `tool-result` is here even though a tool produced it rather than the model: it is content *entering* the
+ * model's context from outside the tenant, and it is the likeliest source of personal data in a whole run — a
+ * document read by a tool contains what the document contains. Inspecting the arguments and not the results
+ * would check the direction data leaves and ignore the direction it arrives.
+ */
+export type GuardrailOutput = {
+    readonly kind: "message";
+    readonly text: string;
+} | {
+    readonly kind: "tool-call";
+    readonly toolName: string;
+    readonly input: unknown;
+} | {
+    readonly kind: "tool-result";
+    readonly toolName: string;
+    readonly output: unknown;
+};
+export type GuardrailVerdict<T> = {
+    readonly kind: "pass";
+}
+/** `what` names fields or entity types — never values. */
+ | {
+    readonly kind: "redacted";
+    readonly value: T;
+    readonly what: readonly string[];
+} | {
+    readonly kind: "refused";
+    readonly code: string;
+    readonly message: string;
+};
+export interface Guardrail {
+    /** Stable, and used in records and refusals: "which check stopped this" must be answerable. */
+    readonly name: string;
+    inspectInput?(input: GuardrailInput, context: ExecutionContext): Promise<GuardrailVerdict<GuardrailInput>> | GuardrailVerdict<GuardrailInput>;
+    inspectOutput?(output: GuardrailOutput, context: ExecutionContext): Promise<GuardrailVerdict<GuardrailOutput>> | GuardrailVerdict<GuardrailOutput>;
+}
+/** One line of the audit trail. Carries no inspected value, by construction. */
+export type GuardrailRecord = {
+    readonly guardrail: string;
+    readonly subject: "input" | "message" | "tool-call" | "tool-result";
+    readonly outcome: GuardrailOutcome;
+    /** For a redaction: the fields or entity types touched. Never their contents. */
+    readonly what?: readonly string[];
+    /** For a refusal. */
+    readonly code?: string;
+    /** True when the guardrail threw and was therefore treated as a refusal. */
+    readonly threw?: boolean;
+};
+export type GuardrailDecision<T> = {
+    readonly outcome: "allowed";
+    readonly value: T;
+    readonly records: readonly GuardrailRecord[];
+} | {
+    readonly outcome: "refused";
+    readonly by: string;
+    readonly code: string;
+    readonly message: string;
+    readonly records: readonly GuardrailRecord[];
+};
+/** Before the model sees the turn. */
+export declare const applyInputGuardrails: (guardrails: readonly Guardrail[], input: GuardrailInput, context: ExecutionContext) => Promise<GuardrailDecision<GuardrailInput>>;
+/** Before anything leaves the model — a message *or* a tool call. */
+export declare const applyOutputGuardrails: (guardrails: readonly Guardrail[], output: GuardrailOutput, context: ExecutionContext) => Promise<GuardrailDecision<GuardrailOutput>>;
+/**
+ * Whether a record could carry an inspected value — used by the test that asserts it never does.
+ *
+ * Here rather than in the test file because it states the invariant next to the type it constrains: a record has
+ * a fixed shape, and adding a field that holds content is the change this is meant to make somebody notice.
+ */
+export declare const recordCarriesOnlyMetadata: (record: GuardrailRecord) => boolean;
+//# sourceMappingURL=index.d.ts.map