@retinue/agentkit 0.1.0 → 0.3.0

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/core/validation.js

@@ -133,6 +133,25 @@ const messagePartSchema = z.discriminatedUnion("type", [
     z.object({ ...base, type: z.literal("artifact"), artifactId: idString, versionId: idString, title: z.string() }),
     z.object({ ...base, type: z.literal("status"), status: z.string(), detail: z.string().optional() }),
     z.object({ ...base, type: z.literal("error"), error: platformErrorSchema }),
+    /**
+     * A structured agent's validated answer — #243.
+     *
+     * `value` is `unknown` on purpose. The schema that constrains it belongs to the *agent*, is chosen by whoever
+     * wrote the manifest, and has already been enforced before the part was emitted — so re-describing it here is
+     * impossible (there is no one shape) and re-validating it would be validating against the wrong schema.
+     *
+     * What this layer does check is that `value` is **present**. `z.unknown()` accepts `undefined`, which would let
+     * a part claiming to be a structured answer round-trip carrying nothing — the empty version of the exact defect
+     * #243 fixed. `z.unknown().refine(v => v !== undefined)` is the narrowest thing that closes it, and `null`
+     * stays legal because `null` is a valid JSON value a schema may well permit.
+     */
+    z.object({
+        ...base,
+        type: z.literal("structured"),
+        value: z.unknown().refine((v) => v !== undefined, {
+            message: "a structured part must carry a value; an absent one is an answer that was never validated",
+        }),
+    }),
 ]);
 const executionContextSchema = z.object({
     tenantId: idString,

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/connections.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `@retinue/agentkit/connections` — a tenant's links to third-party providers, and the cipher that protects
+ * them (#261).
+ *
+ * Its own subpath rather than part of `./tools`, because the two have different readers: a toolkit author needs
+ * `credentialRef` and `Credential`, and a *deployment* needs the store, the cipher and the resolver that
+ * connects them. Nothing here is needed to write a tool.
+ */
+export * from "../connections/index.js";
+//# sourceMappingURL=connections.d.ts.map

package/dist/entries/connections.js

@@ -0,0 +1,10 @@
+/**
+ * `@retinue/agentkit/connections` — a tenant's links to third-party providers, and the cipher that protects
+ * them (#261).
+ *
+ * Its own subpath rather than part of `./tools`, because the two have different readers: a toolkit author needs
+ * `credentialRef` and `Credential`, and a *deployment* needs the store, the cipher and the resolver that
+ * connects them. Nothing here is needed to write a tool.
+ */
+export * from "../connections/index.js";
+//# sourceMappingURL=connections.js.map

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,21 @@ 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";
+/**
+ * The extraction prompt, exported so a harness can use the same one the runtime does — task #275.
+ *
+ * `extractGraph` itself is not exported here: it takes a `LanguageModel` from the AI SDK, and a consumer that
+ * wanted it would be pulling a provider package through the knowledge entrypoint. The prompt is the part worth
+ * sharing — a measurement run against a *different* prompt is measuring a different system.
+ */
+export { DEFAULT_EXTRACTION_PROMPT } from "../models/extraction.js";
 //# sourceMappingURL=knowledge.d.ts.map

package/dist/entries/knowledge.js

@@ -16,4 +16,20 @@ 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";
+/**
+ * The extraction prompt, exported so a harness can use the same one the runtime does — task #275.
+ *
+ * `extractGraph` itself is not exported here: it takes a `LanguageModel` from the AI SDK, and a consumer that
+ * wanted it would be pulling a provider package through the knowledge entrypoint. The prompt is the part worth
+ * sharing — a measurement run against a *different* prompt is measuring a different system.
+ */
+export { DEFAULT_EXTRACTION_PROMPT } from "../models/extraction.js";
 //# sourceMappingURL=knowledge.js.map

package/dist/entries/mcp-server.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `@retinue/agentkit/mcp-server` — expose this deployment's tools to MCP clients (#250).
+ *
+ * Its own subpath, and separate from `./mcp`, because the two are opposite directions: `./mcp` consumes a
+ * tenant's MCP servers, and this **is** one. Sharing an entry would put the SDK's server half in the way of
+ * every consumer who only wanted the client half.
+ */
+export * from "../mcp-server/index.js";
+//# sourceMappingURL=mcp-server.d.ts.map

package/dist/entries/mcp-server.js

@@ -0,0 +1,9 @@
+/**
+ * `@retinue/agentkit/mcp-server` — expose this deployment's tools to MCP clients (#250).
+ *
+ * Its own subpath, and separate from `./mcp`, because the two are opposite directions: `./mcp` consumes a
+ * tenant's MCP servers, and this **is** one. Sharing an entry would put the SDK's server half in the way of
+ * every consumer who only wanted the client half.
+ */
+export * from "../mcp-server/index.js";
+//# sourceMappingURL=mcp-server.js.map

package/dist/entries/runtime.d.ts

@@ -10,4 +10,14 @@ export * from "../models/index.js";
 export * from "../capabilities/index.js";
 export * from "../capabilities/runtime.js";
 export * from "../core/index.js";
+/**
+ * The audio ports and their OpenAI adapters — REQ-062 (#257).
+ *
+ * Here rather than in `tools`, because a `TranscriptionProvider` is a runtime capability a host wires once —
+ * the same place a `SearchProvider` is chosen. The two tools that use them live in the tool library.
+ */
+export { assertWithinBounds, AUDIO_MEDIA_TYPES, AudioRejected, boundTranscript, describeAudioFailure, isAudioMediaType, MAX_AUDIO_BYTES, MAX_AUDIO_SECONDS, MAX_SPEECH_CHARS, MAX_TRANSCRIPT_CHARS, } from "../audio/index.js";
+export type { AudioBounds, AudioMediaType, SpeechProvider, SpeechRequest, SpeechResult, TranscriptionProvider, TranscriptionRequest, TranscriptionResult, } from "../audio/index.js";
+export { openAiSpeech, openAiTranscription } from "../adapters/audio/openai.js";
+export type { OpenAiAudioConfig } from "../adapters/audio/openai.js";
 //# sourceMappingURL=runtime.d.ts.map

package/dist/entries/runtime.js

@@ -10,4 +10,12 @@ export * from "../models/index.js";
 export * from "../capabilities/index.js";
 export * from "../capabilities/runtime.js";
 export * from "../core/index.js";
+/**
+ * The audio ports and their OpenAI adapters — REQ-062 (#257).
+ *
+ * Here rather than in `tools`, because a `TranscriptionProvider` is a runtime capability a host wires once —
+ * the same place a `SearchProvider` is chosen. The two tools that use them live in the tool library.
+ */
+export { assertWithinBounds, AUDIO_MEDIA_TYPES, AudioRejected, boundTranscript, describeAudioFailure, isAudioMediaType, MAX_AUDIO_BYTES, MAX_AUDIO_SECONDS, MAX_SPEECH_CHARS, MAX_TRANSCRIPT_CHARS, } from "../audio/index.js";
+export { openAiSpeech, openAiTranscription } from "../adapters/audio/openai.js";
 //# sourceMappingURL=runtime.js.map

package/dist/entries/testing.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `@retinue/agentkit/testing` — the conformance suite and the fakes — task #253.
+ *
+ * The README's headline claim is *"Replaceable everything — 31 ports, three adapter families, one conformance
+ * suite held over all of them."* A consumer who took that invitation and wrote a fourth adapter family could not
+ * run the suite: it lived in `src/testing/`, which the build excluded and no export reached. The most valuable
+ * thing in the repository for anyone doing that was the one thing they could not have.
+ *
+ * ## Two audiences, one entry
+ *
+ * - **Implementing a port.** `<port>Conformance` runs the same contract tests the built-in families are held to.
+ *   That is what makes "replaceable" checkable rather than an invitation.
+ * - **Implementing an agent or a tool.** `createStubModel` and `createMemoryStores` are for a test that must not
+ *   call a provider or stand up a database.
+ *
+ * ## Why the test runner is an optional peer
+ *
+ * The harnesses call `describe`/`it`/`expect` at module scope, so importing this pulls `vitest`. It is an
+ * **optional peer dependency**, not a dependency: a consumer who never imports this subpath never installs it,
+ * and nothing in a production bundle can reach it — the only paths to these modules are through this entry.
+ * `@electric-sql/pglite` is optional for the same reason, and only `pgliteExecutor` needs it.
+ */
+export * from "../testing/conformance/index.js";
+export * from "../testing/stub-model.js";
+export * from "../testing/memory-backend.js";
+export * from "../testing/pglite.js";
+export * from "../testing/conformance/audio.js";
+//# sourceMappingURL=testing.d.ts.map

package/dist/entries/testing.js

@@ -0,0 +1,28 @@
+/**
+ * `@retinue/agentkit/testing` — the conformance suite and the fakes — task #253.
+ *
+ * The README's headline claim is *"Replaceable everything — 31 ports, three adapter families, one conformance
+ * suite held over all of them."* A consumer who took that invitation and wrote a fourth adapter family could not
+ * run the suite: it lived in `src/testing/`, which the build excluded and no export reached. The most valuable
+ * thing in the repository for anyone doing that was the one thing they could not have.
+ *
+ * ## Two audiences, one entry
+ *
+ * - **Implementing a port.** `<port>Conformance` runs the same contract tests the built-in families are held to.
+ *   That is what makes "replaceable" checkable rather than an invitation.
+ * - **Implementing an agent or a tool.** `createStubModel` and `createMemoryStores` are for a test that must not
+ *   call a provider or stand up a database.
+ *
+ * ## Why the test runner is an optional peer
+ *
+ * The harnesses call `describe`/`it`/`expect` at module scope, so importing this pulls `vitest`. It is an
+ * **optional peer dependency**, not a dependency: a consumer who never imports this subpath never installs it,
+ * and nothing in a production bundle can reach it — the only paths to these modules are through this entry.
+ * `@electric-sql/pglite` is optional for the same reason, and only `pgliteExecutor` needs it.
+ */
+export * from "../testing/conformance/index.js";
+export * from "../testing/stub-model.js";
+export * from "../testing/memory-backend.js";
+export * from "../testing/pglite.js";
+export * from "../testing/conformance/audio.js";
+//# sourceMappingURL=testing.js.map

package/dist/graphql/resolvers.d.ts

@@ -5,7 +5,7 @@
  * shape and delegates to a service. No business logic lives in this layer.
  */
 import type { ExecutionContext } from "../core/context.js";
-import type { QuotaGuard } from "../usage/index.js";
+import type { QuotaGuard, RateLimitGuard } from "../usage/index.js";
 import type { UsageRollupStore } from "../persistence/index.js";
 import type { ConversationId, RunId } from "../core/ids.js";
 import type { ConversationStore, UsageStore } from "../persistence/index.js";
@@ -38,6 +38,8 @@ export type ResolverDeps = {
      * that blocks nothing is a bill the rollups make visible.
      */
     readonly quota?: QuotaGuard;
+    /** Capacity, as distinct from spend — task #248. Absent means unchecked. */
+    readonly rateLimit?: RateLimitGuard;
     /**
      * Rollups for the spend panel (#140).
      *
@@ -76,6 +78,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) } : {}) });
             },
@@ -195,6 +201,20 @@ export const createResolvers = (deps) => {
                 //
                 // Optional, because a deployment with no limits configured is valid; when it is absent nothing is
                 // checked, which is the same as an unbounded limit.
+                /**
+                 * Rate before cost — task #248.
+                 *
+                 * This order is deliberate. A rate check is one atomic counter increment; a quota check reads a rollup.
+                 * A tenant hammering the platform should be turned away by the cheaper check, not made to do the more
+                 * expensive one first — otherwise the defence against a runaway client is itself proportional to how
+                 * hard the client is running.
+                 *
+                 * Optional like the quota, and absent means unchecked. See `createRateLimitGuard`: an absent policy or a
+                 * `max` of zero is unlimited, so adding this feature cannot refuse a deployment that has configured
+                 * nothing.
+                 */
+                if (deps.rateLimit !== undefined)
+                    await deps.rateLimit.assertAdmitted(ctx.execution);
                 if (deps.quota !== undefined)
                     await deps.quota.assertAdmitted(ctx.execution);
                 const started = await startOrEnqueueRun(deps.coordinator, { tenantId: tid(ctx), conversationId, 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).