@retinue/agentkit 0.1.0 → 0.3.0

package/dist/adapters/supabase/rls.js

@@ -72,6 +72,13 @@ export const TENANT_SCOPED_TABLES = [
     { table: "idempotency_keys" },
     { table: "skills" },
     { table: "mcp_connections" },
+    /**
+     * #261. A tenant's third-party credentials, and therefore the table where a missing policy would be worst:
+     * every row is somebody's access to somebody else's system, and the plain `tenant_id` predicate is exactly
+     * the isolation the port already enforces in its `WHERE` clauses. Defence in depth, and #91 is the reminder
+     * that a method accepting a tenant scope and not using it typechecks perfectly.
+     */
+    { table: "connections" },
     { table: "principal_memory", extraPredicate: PRINCIPAL_PREDICATE },
     // `blobs`, not the SPEC's `blob_refs`: BlobStore stores the value, and the metadata-and-pointer
     // design belongs to FileMetadataStore (#129) / ArtifactStore (#133).
@@ -98,6 +105,32 @@ export const TENANT_SCOPED_TABLES = [
      */
     { table: "flow_definitions" },
     { table: "flow_executions" },
+    /**
+     * #271. The knowledge graph, all five tables, and they belong here rather than beside `knowledge_chunks`
+     * in the vector list: none of them needs pgvector, so they exist in every deployment and can be protected
+     * unconditionally.
+     *
+     * Worth stating why the *settings* table needs a policy as much as the content ones. `knowledge_graph_settings`
+     * holds one boolean, so it looks harmless — but it is the switch that decides whether a tenant is paying for
+     * extraction, and a missing policy would let one tenant read, and worse write, another's. Turning a
+     * neighbour's GraphRAG on is a bill they did not agree to.
+     */
+    { table: "knowledge_graph_settings" },
+    { table: "knowledge_graph_sources" },
+    /**
+     * The contributions table is the one to get right. It holds the entities and relationships each source
+     * asserted, as JSON — which is to say, the substance of the documents themselves in condensed form. A leak
+     * here is a leak of what a tenant's corpus says, not merely of which entities exist.
+     */
+    { table: "knowledge_graph_contributions" },
+    { table: "knowledge_graph_entities" },
+    { table: "knowledge_graph_relationships" },
+    /**
+     * #272. Community summaries are **generated prose about a tenant's corpus** — a paraphrase of what their
+     * documents say, which is if anything more sensitive than the entity names next door. A missing policy here
+     * would leak the substance of a corpus rather than its index.
+     */
+    { table: "knowledge_graph_communities" },
 ];
 /**
  * Tables that deliberately have no tenant policy, each with the reason.

package/dist/agents/agent.d.ts

@@ -15,11 +15,52 @@ import { type ProviderCredentials } from "../models/provider-factory.js";
 import type { ModelProvider } from "../models/index.js";
 import type { AuthorizationPolicy } from "../authorization/index.js";
 import { type ContextProvider } from "../context/index.js";
-import { type ToolProvider } from "../tools/index.js";
+import { type ShadowRecorder, type ToolProvider, type ToolSearch, type ToolsetResolver } from "../tools/index.js";
+import type { TokenBudget } from "../core/budget.js";
 import { type AgentEngine, type ProcessOutcome } from "../runtime/index.js";
+import type { Guardrail } from "../guardrails/index.js";
+import { type SkillResolver } from "../skills/index.js";
 import { type ResolvedModelInfo } from "./engine.js";
 import type { AgentManifest } from "./index.js";
 import { type AgentManifestInput } from "./define.js";
+/**
+ * The policy this agent runs under — task #244, the interpreter for `authorizationPolicyId`.
+ *
+ * The field was declared and read by nothing, so an agent naming `"restricted"` ran under whatever the host had
+ * wired — very possibly the permissive default. Three rules, and the third is the one that matters:
+ *
+ * 1. A map is supplied and contains the id → that policy.
+ * 2. No map, and the id is `defineAgent`'s `"default"` → the single wired policy, or the permissive default.
+ *    This is the normal case and stays a one-liner.
+ * 3. **Any other combination is an error.** An id the deployment cannot honour must never fall through to the
+ *    permissive default: an agent asking to run under a narrow policy and silently getting allow-all is the
+ *    worst possible reading of this field, and it is the reading it had. Failing at construction is loud, early
+ *    and cheap.
+ *
+ * Note the platform does not check that a named policy is *narrower* than any other. It cannot: a policy is an
+ * interface the host implements, and composing two of them into an intersection would mean second-guessing a
+ * deployment's own authorization. What the platform guarantees is that the policy an agent named is the policy
+ * it got, or the run does not start.
+ */
+export declare const selectAuthorization: (config: Pick<CreateAgentConfig, "authorization" | "authorizationPolicies">, manifest: Pick<AgentManifest, "authorizationPolicyId" | "id">) => AuthorizationPolicy;
+/**
+ * The providers this agent asked for, in the order it asked — task #244.
+ *
+ * `AgentManifest.contextProviderIds` was declared and read by nothing, so a manifest naming two of four wired
+ * providers got all four, and naming none got all of them too. Two decisions make the field meaningful without
+ * making it a trap:
+ *
+ * - **An empty list means every wired provider**, not none. `defineAgent` defaults it to `[]`, so treating empty
+ *   as "no context" would silently strip the memory, notes and attachments from every agent already written
+ *   against the default. The field is a *selection*, and no selection means no narrowing.
+ * - **A named id that is not wired is an error**, not a silent omission. The failure it prevents is the one worth
+ *   preventing: an agent whose manifest asks for `principal-memory`, a typo or a missing wire, and an assistant
+ *   that quietly remembers nothing. That reads exactly like a model that chose not to use its memory.
+ *
+ * Order follows the manifest, because section order is prompt order and the manifest is where an author can see
+ * and control it.
+ */
+export declare const selectContextProviders: (wired: readonly ContextProvider[], manifest: Pick<AgentManifest, "contextProviderIds" | "id">) => readonly ContextProvider[];
 export type CreateAgentConfig = {
     readonly manifest: AgentManifestInput;
     /** Model catalog; defaults to a small Anthropic catalog (smart/fast). */
@@ -38,7 +79,52 @@ export type CreateAgentConfig = {
      */
     readonly randomHex?: (bytes: number) => string;
     readonly authorization?: AuthorizationPolicy;
+    /**
+     * Named policies a manifest may select with `authorizationPolicyId` — task #244.
+     *
+     * Absent is the normal case: one `authorization` (or the permissive default), and every manifest carrying
+     * `defineAgent`'s `"default"`. Supplying a map is how a deployment runs several agents under different
+     * policies — a customer-facing agent under a narrow one, an internal agent under a wider one — without the
+     * host having to build a separate registry per agent.
+     */
+    readonly authorizationPolicies?: Readonly<Record<string, AuthorizationPolicy>>;
+    /**
+     * Checks to run before the model sees a turn and before anything leaves it — REQ-046 (#205), AC-5.
+     *
+     * Here so a host can add one without composing the runtime by hand: this facade exists to be the short path,
+     * and a guardrail that could only be wired through the long one would be a guardrail most deployments never
+     * add.
+     */
+    readonly guardrails?: readonly Guardrail[];
+    /**
+     * Search over the catalogue, which is what makes `find_tools` exist — REQ-045 (#204), task #210.
+     *
+     * Absent means no `find_tools`. Wire it with `createToolSearch()` for keyword search, or pass an
+     * `EmbeddingProvider` to it for hybrid — and see `tools/find.ts` on why keyword-only is the honest default.
+     */
+    readonly toolSearch?: ToolSearch;
+    /** A ceiling in tokens on the tool list handed to the model — task #210, AC-3. Absent means no ceiling. */
+    readonly catalogBudget?: TokenBudget;
+    /** A tenant's category switches, applied before authorization — task #210, AC-4. */
+    readonly toolsets?: ToolsetResolver;
+    /**
+     * A skill resolver — task #244, and what makes `manifest.skillPolicy` mean something.
+     *
+     * Wiring is the toggle, the rule `toolSearch` already follows. Supplying one adds a skills catalogue section
+     * to the prompt (names and descriptions, filtered by the manifest's `assigned`/`allowTenantSkills`) and makes
+     * `load_skill` real; omitting it means neither is advertised.
+     */
+    readonly skills?: SkillResolver;
     readonly tenantId?: string;
+    /**
+     * Where a shadow run's suppressed writes go — required to run one at all.
+     *
+     * Without it `createAgent` cannot run a shadow turn: the registry refuses a gated tool when
+     * `context.shadow` is true and no recorder is configured, which is the correct fail-closed rule but meant
+     * this runner had no way to satisfy it. Parity measurement needs a run driven to completion in one process,
+     * and this is that seam.
+     */
+    readonly shadow?: ShadowRecorder;
     /** Test/advanced seam: override how a manifest resolves to a model (e.g. a mock model). */
     readonly resolveModel?: (manifest: AgentManifest, context: ExecutionContext) => ResolvedModelInfo;
     /** Test/advanced seam: supply the engine directly instead of building the default one. */
@@ -50,6 +136,18 @@ export type RunInput = {
     readonly message: string;
     readonly principalId?: string;
     readonly roleIds?: readonly string[];
+    /**
+     * Run with every gated effect suppressed and recorded instead of performed.
+     *
+     * Per-run rather than per-agent, because the same agent serves both: a parity harness shadows one turn and
+     * runs the next for real. `shadow` without `config.shadow` is refused by the registry rather than performed
+     * — announcing a shadow run with nowhere to record it is not a licence to publish.
+     *
+     * Note what shadow mode does **not** suppress: an `internal-write` still happens, so a shadow run really
+     * does create drafts. It measures everything up to the external write and nothing after it, because what an
+     * agent does after publishing cannot be observed without publishing.
+     */
+    readonly shadow?: boolean;
 };
 export type RunResult = {
     readonly runId: string;

package/dist/agents/agent.js

@@ -17,14 +17,95 @@ import { createProviderFactory, } from "../models/provider-factory.js";
 import { gatherSections } from "../context/index.js";
 import { randomBytes } from "node:crypto";
 import { makeNonce, renderContextBlock } from "../security/prompt-safety.js";
-import { createToolRegistry } from "../tools/index.js";
+import { createToolRegistry, } from "../tools/index.js";
 import { createDurableWorker } from "../runtime/index.js";
 import { createMemoryCheckpointStore, createMemoryRunEventLog, createMemoryRunStore, } from "../adapters/memory/runtime.js";
 import { createMemoryConversationStore } from "../adapters/memory/index.js";
 import { createMemoryEventBus } from "../runtime/index.js";
 import { createMemoryMessageStore } from "../adapters/memory/message-store.js";
+import { createSkillBodyLoader, createSkillCatalogueProvider, } from "../skills/index.js";
 import { createDefaultEngine } from "./engine.js";
 import { DEFAULT_MODEL_CATALOG, DEFAULT_ROLE_ASSIGNMENTS, defineAgent, } from "./define.js";
+/**
+ * The policy this agent runs under — task #244, the interpreter for `authorizationPolicyId`.
+ *
+ * The field was declared and read by nothing, so an agent naming `"restricted"` ran under whatever the host had
+ * wired — very possibly the permissive default. Three rules, and the third is the one that matters:
+ *
+ * 1. A map is supplied and contains the id → that policy.
+ * 2. No map, and the id is `defineAgent`'s `"default"` → the single wired policy, or the permissive default.
+ *    This is the normal case and stays a one-liner.
+ * 3. **Any other combination is an error.** An id the deployment cannot honour must never fall through to the
+ *    permissive default: an agent asking to run under a narrow policy and silently getting allow-all is the
+ *    worst possible reading of this field, and it is the reading it had. Failing at construction is loud, early
+ *    and cheap.
+ *
+ * Note the platform does not check that a named policy is *narrower* than any other. It cannot: a policy is an
+ * interface the host implements, and composing two of them into an intersection would mean second-guessing a
+ * deployment's own authorization. What the platform guarantees is that the policy an agent named is the policy
+ * it got, or the run does not start.
+ */
+export const selectAuthorization = (config, manifest) => {
+    const id = manifest.authorizationPolicyId ?? "default";
+    const named = config.authorizationPolicies;
+    if (named !== undefined) {
+        const chosen = named[id];
+        if (chosen !== undefined)
+            return chosen;
+        throw new AgentPlatformError({
+            code: "capability_unavailable",
+            message: `agent "${manifest.id}" runs under authorization policy "${id}" and no such policy is registered ` +
+                `(registered: ${Object.keys(named).map((k) => `"${k}"`).join(", ") || "none"}). Refusing rather than ` +
+                "falling back — an agent that asked for a narrow policy and silently got a permissive one is the " +
+                "failure this field exists to prevent.",
+            retryable: false,
+        });
+    }
+    if (id !== "default")
+        throw new AgentPlatformError({
+            code: "capability_unavailable",
+            message: `agent "${manifest.id}" runs under authorization policy "${id}" and none is registered. Pass ` +
+                "`authorizationPolicies: { \"" +
+                id +
+                "\": … }`, or leave the manifest's `authorizationPolicyId` at \"default\".",
+            retryable: false,
+        });
+    return config.authorization ?? allowAllAuthorization();
+};
+/**
+ * The providers this agent asked for, in the order it asked — task #244.
+ *
+ * `AgentManifest.contextProviderIds` was declared and read by nothing, so a manifest naming two of four wired
+ * providers got all four, and naming none got all of them too. Two decisions make the field meaningful without
+ * making it a trap:
+ *
+ * - **An empty list means every wired provider**, not none. `defineAgent` defaults it to `[]`, so treating empty
+ *   as "no context" would silently strip the memory, notes and attachments from every agent already written
+ *   against the default. The field is a *selection*, and no selection means no narrowing.
+ * - **A named id that is not wired is an error**, not a silent omission. The failure it prevents is the one worth
+ *   preventing: an agent whose manifest asks for `principal-memory`, a typo or a missing wire, and an assistant
+ *   that quietly remembers nothing. That reads exactly like a model that chose not to use its memory.
+ *
+ * Order follows the manifest, because section order is prompt order and the manifest is where an author can see
+ * and control it.
+ */
+export const selectContextProviders = (wired, manifest) => {
+    const asked = manifest.contextProviderIds ?? [];
+    if (asked.length === 0)
+        return wired;
+    const byId = new Map(wired.map((p) => [p.id, p]));
+    const missing = asked.filter((id) => !byId.has(id));
+    if (missing.length > 0)
+        throw new AgentPlatformError({
+            code: "capability_unavailable",
+            message: `agent "${manifest.id}" asks for context provider(s) ${missing.map((m) => `"${m}"`).join(", ")} and ` +
+                `nothing wired supplies them (wired: ${wired.map((p) => `"${p.id}"`).join(", ") || "none"}). An agent ` +
+                "that silently runs without the context it declared is indistinguishable from a model choosing not to " +
+                "use it.",
+            retryable: false,
+        });
+    return asked.map((id) => byId.get(id));
+};
 /** Permissive policy used by the embedded facade when a caller wires tools but no authorization. */
 const allowAllAuthorization = () => ({
     async can() {
@@ -55,8 +136,28 @@ export const createAgent = (config) => {
         roles: config.roleAssignments ?? DEFAULT_ROLE_ASSIGNMENTS,
     });
     const providerFactory = createProviderFactory({ credentials: config.providerCredentials ?? {} });
-    const authorization = config.authorization ?? allowAllAuthorization();
-    const toolRegistry = createToolRegistry({ providers: config.tools ?? [], authorization });
+    const authorization = selectAuthorization(config, manifest);
+    /**
+     * Skills, when a resolver is wired — #244.
+     *
+     * Both halves read the *same* policy, and that is the point: `createSkillBodyLoader` re-derives the catalogue
+     * before loading, so `assigned` and `allowTenantSkills` gate loading as well as listing. A policy that
+     * filtered the list but not the load would be no policy at all — a model that guessed a name would get it.
+     */
+    const skillPolicy = {
+        assigned: manifest.skillPolicy?.assigned ?? [],
+        allowTenantSkills: manifest.skillPolicy?.allowTenantSkills ?? false,
+    };
+    const skillLoader = config.skills === undefined ? undefined : createSkillBodyLoader({ resolver: config.skills, policy: skillPolicy });
+    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 }),
+        ...(skillLoader === undefined ? {} : { skills: skillLoader }),
+        ...(config.shadow === undefined ? {} : { shadow: config.shadow }),
+    });
     const resolveModel = config.resolveModel ??
         ((m) => {
             const def = registry.resolve(m.modelPolicy);
@@ -64,11 +165,25 @@ export const createAgent = (config) => {
                 model: providerFactory.languageModel(def),
                 modelId: def.modelId,
                 currency: def.pricing.currency,
-                price: (u) => computeModelCostMinorUnits(def.pricing, { inputTokens: u.inputTokens, outputTokens: u.outputTokens, cachedInputTokens: u.cachedInputTokens }),
+                price: (u) => computeModelCostMinorUnits(def.pricing, {
+                    inputTokens: u.inputTokens,
+                    outputTokens: u.outputTokens,
+                    cachedInputTokens: u.cachedInputTokens,
+                    // Dropped here before #247, so a cache write was billed as fresh input — and on a provider that
+                    // charges a premium for a write, under-billed.
+                    ...(u.cacheWriteTokens === undefined ? {} : { cacheWriteTokens: u.cacheWriteTokens }),
+                }),
             };
         });
-    const contextProviders = config.contextProviders ?? [];
+    const contextProviders = [
+        ...(config.contextProviders ?? []),
+        ...(config.skills === undefined
+            ? []
+            : [createSkillCatalogueProvider({ resolver: config.skills, policy: skillPolicy })]),
+    ];
     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
         },
@@ -88,7 +203,7 @@ export const createAgent = (config) => {
                  * assembly, so content cannot learn the delimiter from a previous turn.
                  */
                 systemPrompt: async (m, context) => {
-                    const sections = await gatherSections(context, contextProviders);
+                    const sections = await gatherSections(context, selectContextProviders(contextProviders, m));
                     if (sections.length === 0)
                         return m.instructions;
                     const ctxText = renderContextBlock(sections, makeNonce(config.randomHex ?? defaultRandomHex));
@@ -120,19 +235,100 @@ 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,
+                        // Carried through so the engine can honour `toolPolicy.categories` without reaching back into
+                        // the registry for a descriptor it already handed over — #244.
+                        category: descriptor.category,
+                        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;
@@ -173,6 +369,9 @@ export const createAgent = (config) => {
                 requestId: asId(`req-${seq}`),
                 conversationId,
                 runId,
+                // Only when asked. Defaulting to shadow would make every existing run a shadow run; the dangerous
+                // direction — claiming shadow with nowhere to record it — is closed in the registry instead.
+                ...(input.shadow === true ? { shadow: true } : {}),
             };
             contextByRun.set(runId, context);
             if (!(await conversations.findById({ tenantId, id: conversationId }))) {

package/dist/agents/define.js

@@ -39,9 +39,22 @@ export const DEFAULT_MODEL_CATALOG = [
         label: "Claude Sonnet 5",
         lifecycle: "generally-available",
         inputModalities: ["text", "image"],
-        capabilities: { tools: true, structuredOutput: true, reasoning: true, nativeSearch: false },
+        capabilities: { tools: true, structuredOutput: true, reasoning: true, nativeSearch: false, promptCaching: "explicit" },
         limits: { contextTokens: 200_000, maxOutputTokens: 8_192 },
-        pricing: { currency: "USD", inputPerMillion: 3_000, outputPerMillion: 15_000 },
+        /**
+         * Cache rates, added by #247.
+         *
+         * Anthropic's published ratios: a cache **read** is 0.1× a fresh input token and a cache **write** is
+         * **1.25×** — a write costs *more*. `cacheWritePerMillion` was in `ModelPricing` and read by nothing, so a
+         * cache write was billed as ordinary input and the first turn of every conversation was under-billed.
+         */
+        pricing: {
+            currency: "USD",
+            inputPerMillion: 3_000,
+            outputPerMillion: 15_000,
+            cacheReadPerMillion: 300,
+            cacheWritePerMillion: 3_750,
+        },
         dataResidency: ["us"],
     },
     {
@@ -50,9 +63,16 @@ export const DEFAULT_MODEL_CATALOG = [
         label: "Claude Haiku 4.5",
         lifecycle: "generally-available",
         inputModalities: ["text", "image"],
-        capabilities: { tools: true, structuredOutput: true, reasoning: false, nativeSearch: false },
+        capabilities: { tools: true, structuredOutput: true, reasoning: false, nativeSearch: false, promptCaching: "explicit" },
         limits: { contextTokens: 200_000, maxOutputTokens: 8_192 },
-        pricing: { currency: "USD", inputPerMillion: 800, outputPerMillion: 4_000 },
+        pricing: {
+            currency: "USD",
+            inputPerMillion: 800,
+            outputPerMillion: 4_000,
+            // Same ratios as Sonnet above: read 0.1×, write 1.25×.
+            cacheReadPerMillion: 80,
+            cacheWritePerMillion: 1_000,
+        },
         dataResidency: ["us"],
     },
 ];

package/dist/agents/engine.d.ts

@@ -18,12 +18,23 @@
  *    on a refusal the model cannot resolve.
  */
 import type { ExecutionContext } from "../core/context.js";
+import { type ConnectionNeed } from "../connections/pause.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 +74,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.
      *
@@ -93,6 +122,25 @@ export type DefaultEngineDeps = {
     readonly now?: () => number;
     /** The streaming primitive. Defaults to the models-layer `streamModelTurn`; overridden in tests. */
     readonly streamTurn?: (req: ModelTurnRequest) => AsyncIterable<NeutralStreamChunk>;
+    /**
+     * Turns "this run needs a connection" into somewhere to send a person — task #264.
+     *
+     * **Optional, and its absence means today's behaviour**: the tool call fails and the run fails with it. That
+     * is the correct default, not a degraded one — a host with no OAuth flow wired has no login URL to offer, and
+     * pausing a run for a consent screen nobody can reach would hang it for ever.
+     *
+     * Returning `null` says the same thing for one provider: this one is token-only, so fail rather than pause.
+     * That decision comes from `ToolkitAuth.modes`, which is why #260 kept `AuthMode` separate from
+     * `CredentialScheme` — an OAuth token is presented as a bearer, so the wire format cannot answer it.
+     */
+    readonly connectionConsent?: (input: {
+        readonly context: ExecutionContext;
+        readonly need: ConnectionNeed;
+    }) => Promise<{
+        readonly loginUrl: string;
+        readonly scopes: readonly string[];
+        readonly expiresAt: string;
+    } | null>;
 };
 export declare const createDefaultEngine: (deps: DefaultEngineDeps) => AgentEngine;
 //# sourceMappingURL=engine.d.ts.map