@retinue/agentkit 0.2.0 → 0.3.1

package/dist/tools/define.d.ts

@@ -16,6 +16,20 @@ export type ToolSpec<I = unknown, O = unknown> = {
     readonly inputSchema?: unknown;
     readonly outputSchema?: unknown;
     readonly requiresIdempotencyKey?: boolean;
+    /**
+     * The provider scopes this tool needs — #260's field, made settable by #234.
+     *
+     * It was declared on `ToolDescriptor` and had **no way to be set**: `ToolSpec` did not carry it, so nothing
+     * in the repository could populate it and nothing read it. A field that cannot be written is a field that
+     * documents an intention rather than expressing one, which is the defect class `check:reachability` exists
+     * for — it was missed because the check asks whether declared fields are *read*, and an unwritable field is
+     * never read either.
+     *
+     * Google is the first vendor where it matters: `gmail.send` and `gmail.readonly` are different consents, and
+     * asking for the wrong one is the difference between a security team approving an integration and refusing
+     * it.
+     */
+    readonly requiredScopes?: readonly string[];
     execute(input: I, context: ExecutionContext): Promise<O> | O;
 };
 /** Build a `Tool` from a plain spec: `execute` returns data (or throws); the envelope is handled here. */

package/dist/tools/define.js

@@ -22,6 +22,9 @@ export const defineTool = (spec) => {
         effect,
         approvalPolicy: spec.approvalPolicy ?? (effect === "external-write" || effect === "destructive" ? "always" : "never"),
         requiresIdempotencyKey: spec.requiresIdempotencyKey ?? (effect === "external-write" || effect === "destructive"),
+        // Omitted rather than defaulted to `[]`: absent means "this vendor has no scopes", which is true of
+        // every wave-1 tool, and an empty array would read as "needs none" — a different claim.
+        ...(spec.requiredScopes === undefined ? {} : { requiredScopes: spec.requiredScopes }),
     };
     return {
         descriptor,

package/dist/tools/index.d.ts

@@ -12,6 +12,13 @@ import type { IdempotencyKey } from "../idempotency/index.js";
 /**
  * Effect classification. This drives the approval policy, so an unknown effect is
  * never treated as `read` — see `../mcp` for how imported tools are classified.
+ *
+ * **Adding a value is more expensive than it looks — #228.** `external-write` and `destructive` appear in a
+ * disjunction three times: twice in `define.ts` (deriving `approvalPolicy` and `requiresIdempotencyKey`) and
+ * once in `registry.ts`'s `requiresKey`. A new value has to be added to all three, and missing one gives the
+ * new effect **`approvalPolicy: "never"`** by default — silently ungating the very tools it was added to
+ * protect. #228 asked for a fifth value for public publishing and declined for this reason; the gate there is
+ * an exact list in `docs/23-tool-catalogue.md`, enforced by `check:effects`.
  */
 export declare const TOOL_EFFECTS: readonly ["read", "internal-write", "external-write", "destructive"];
 export type ToolEffect = (typeof TOOL_EFFECTS)[number];
@@ -28,6 +35,20 @@ export type ToolDescriptor = {
     readonly approvalPolicy: ApprovalPolicy;
     /** External and destructive tools must supply an idempotency key. */
     readonly requiresIdempotencyKey: boolean;
+    /**
+     * The vendor scopes this tool needs — REQ-063 (#259), task #260 AC-3.
+     *
+     * Per **tool**, not per toolkit, because that is the granularity the question is asked at: a deployment
+     * enabling three of Gmail's eight tools should be sent through a consent screen for three tools' worth of
+     * scopes, not eight. Google's restricted scopes are the case that makes this matter — asking for
+     * `gmail.modify` when only `gmail.readonly` is needed is the difference between a consent a security team
+     * approves and one they refuse.
+     *
+     * Absent means "no scope is required or the vendor has no scopes", which is true of every wave 1 tool.
+     * Declared here rather than only in prose so a connection can be checked against what the enabled tools
+     * actually need **before** a tenant is sent through consent, rather than after a 403.
+     */
+    readonly requiredScopes?: readonly string[];
     /**
      * For a delegating tool (#113): the deterministic function this capability wraps.
      *

package/dist/tools/index.js

@@ -8,6 +8,13 @@
 /**
  * Effect classification. This drives the approval policy, so an unknown effect is
  * never treated as `read` — see `../mcp` for how imported tools are classified.
+ *
+ * **Adding a value is more expensive than it looks — #228.** `external-write` and `destructive` appear in a
+ * disjunction three times: twice in `define.ts` (deriving `approvalPolicy` and `requiresIdempotencyKey`) and
+ * once in `registry.ts`'s `requiresKey`. A new value has to be added to all three, and missing one gives the
+ * new effect **`approvalPolicy: "never"`** by default — silently ungating the very tools it was added to
+ * protect. #228 asked for a fifth value for public publishing and declined for this reason; the gate there is
+ * an exact list in `docs/23-tool-catalogue.md`, enforced by `check:effects`.
  */
 export const TOOL_EFFECTS = [
     "read",

package/dist/tools/library/audio.d.ts

@@ -0,0 +1,63 @@
+/**
+ * `transcribe` and `speech_generate` — REQ-062 (#257), task #258, AC-9.
+ *
+ * ## These are library tools, not a `tools-media` package — a deviation from `docs/23`
+ *
+ * The catalogue assigns both to a `tools-media` sibling package. That assignment predates the provider-port
+ * pattern being settled, and following it now would put these in the wrong place for a reason worth recording.
+ *
+ * A sibling package exists for a **vendor**: `tools-github` wraps GitHub's API, and a change to that API is a
+ * patch to one small package rather than a platform release. Neither of these tools wraps a vendor. They take a
+ * `TranscriptionProvider` and a `SpeechProvider` — ports — exactly as `web_search` takes a `SearchProvider`
+ * and lives right here in the library for that reason.
+ *
+ * Putting them in a package would mean the package had no vendor in it: Whisper, Deepgram and a self-hosted
+ * `whisper.cpp` are values of a parameter, and a `tools-media` that shipped no vendor code would be a folder
+ * whose only content is two thin wrappers over runtime ports. `docs/23`'s row is updated rather than obeyed.
+ *
+ * The other two tools that row names — `image_generate` and `video_generate` — are out of REQ-062's scope and
+ * unaffected by this. If they arrive as vendor integrations, a `tools-media` package is the right home for
+ * *them*.
+ *
+ * ## The effects, and why `speech_generate` is not an external write
+ *
+ * `transcribe` is a `read`: it looks at a recording and returns text, changes nothing, and notifies nobody.
+ *
+ * `speech_generate` is an `internal-write` because it **creates a file the tenant owns**. Nothing leaves the
+ * deployment and nobody else sees it, which is what separates `internal-write` from `external-write` — the
+ * distinction #228 settled. It costs money, which is why it is not a `read`, and the cost is bounded by the
+ * character ceiling rather than by an approval.
+ */
+import { type AudioBounds } from "../../audio/index.js";
+import type { SpeechProvider, TranscriptionProvider } from "../../audio/index.js";
+import { type DelegatingToolDeps } from "../delegating.js";
+import type { Tool } from "../index.js";
+/** What the tool needs in order to read an uploaded file and write a generated one. */
+export type AudioToolDeps = {
+    /**
+     * Reads an uploaded file's bytes **through the authorized path**.
+     *
+     * A function rather than a store, because the tool must not be able to reach a file the principal cannot:
+     * the host supplies a reader already scoped to the execution context, which is the same arrangement the
+     * attachment bridge uses.
+     */
+    readonly readFile: (fileId: string) => Promise<{
+        readonly bytes: Uint8Array;
+        readonly mediaType: string;
+        readonly filename?: string;
+        readonly byteSize: number;
+    }>;
+    /** Stores generated audio and returns what a client needs to play it. */
+    readonly writeAudio: (input: {
+        readonly bytes: Uint8Array;
+        readonly mediaType: string;
+        readonly filename: string;
+    }) => Promise<{
+        readonly fileId: string;
+        readonly url?: string;
+    }>;
+    readonly bounds?: AudioBounds;
+};
+export declare const createTranscribeTool: (deps: DelegatingToolDeps, provider: TranscriptionProvider, audio: AudioToolDeps) => Tool;
+export declare const createSpeechGenerateTool: (deps: DelegatingToolDeps, provider: SpeechProvider, audio: AudioToolDeps) => Tool;
+//# sourceMappingURL=audio.d.ts.map

package/dist/tools/library/audio.js

@@ -0,0 +1,148 @@
+/**
+ * `transcribe` and `speech_generate` — REQ-062 (#257), task #258, AC-9.
+ *
+ * ## These are library tools, not a `tools-media` package — a deviation from `docs/23`
+ *
+ * The catalogue assigns both to a `tools-media` sibling package. That assignment predates the provider-port
+ * pattern being settled, and following it now would put these in the wrong place for a reason worth recording.
+ *
+ * A sibling package exists for a **vendor**: `tools-github` wraps GitHub's API, and a change to that API is a
+ * patch to one small package rather than a platform release. Neither of these tools wraps a vendor. They take a
+ * `TranscriptionProvider` and a `SpeechProvider` — ports — exactly as `web_search` takes a `SearchProvider`
+ * and lives right here in the library for that reason.
+ *
+ * Putting them in a package would mean the package had no vendor in it: Whisper, Deepgram and a self-hosted
+ * `whisper.cpp` are values of a parameter, and a `tools-media` that shipped no vendor code would be a folder
+ * whose only content is two thin wrappers over runtime ports. `docs/23`'s row is updated rather than obeyed.
+ *
+ * The other two tools that row names — `image_generate` and `video_generate` — are out of REQ-062's scope and
+ * unaffected by this. If they arrive as vendor integrations, a `tools-media` package is the right home for
+ * *them*.
+ *
+ * ## The effects, and why `speech_generate` is not an external write
+ *
+ * `transcribe` is a `read`: it looks at a recording and returns text, changes nothing, and notifies nobody.
+ *
+ * `speech_generate` is an `internal-write` because it **creates a file the tenant owns**. Nothing leaves the
+ * deployment and nobody else sees it, which is what separates `internal-write` from `external-write` — the
+ * distinction #228 settled. It costs money, which is why it is not a `read`, and the cost is bounded by the
+ * character ceiling rather than by an approval.
+ */
+import { z } from "zod";
+import { AgentPlatformError } from "../../core/errors.js";
+import { assertWithinBounds, MAX_SPEECH_CHARS } from "../../audio/index.js";
+import { defineDelegatingTool } from "../delegating.js";
+const transcribeSchema = z.object({
+    /**
+     * A file id, never bytes and never a URL.
+     *
+     * Bytes in a tool argument would mean a base64 recording inside the model's context — expensive, and it would
+     * arrive having bypassed the upload bounds entirely. A URL would make this a fetch tool with an SSRF surface.
+     * An id goes through the mediated read path, so authorization applies and the bounds were checked at upload.
+     */
+    fileId: z.string().min(1).describe("The id of an uploaded audio file."),
+    languageHint: z
+        .string()
+        .min(2)
+        .max(8)
+        .optional()
+        .describe("A BCP-47 language tag, if you already know it. Leave it out to let the provider detect."),
+});
+const speechSchema = z.object({
+    text: z.string().min(1).max(MAX_SPEECH_CHARS).describe("What to say. Plain text."),
+    voice: z.string().min(1).max(64).optional().describe("The provider's voice name, if the deployment offers a choice."),
+    format: z.enum(["mp3", "wav", "opus", "flac"]).optional(),
+});
+export const createTranscribeTool = (deps, provider, audio) => defineDelegatingTool(deps, {
+    name: "transcribe",
+    label: "Transcribe a recording",
+    description: "Turn an uploaded audio file into text. Give it the file's id. Returns the transcript, the detected " +
+        "language and the duration. If `truncated` is true the recording was longer than the transcript limit " +
+        "and you are reading only the beginning — say so rather than summarising it as the whole thing.",
+    category: "media",
+    effect: "read",
+    inputSchema: transcribeSchema,
+    delegatesTo: "audio.TranscriptionProvider",
+    delegate: async (input) => {
+        const file = await audio.readFile(input.fileId);
+        /**
+         * Bounds checked again here, and that is not redundant.
+         *
+         * The upload path checks what a client *declared*; this checks what was actually stored. A file that grew
+         * past the ceiling, or one uploaded before a deployment tightened its bounds, would otherwise reach the
+         * provider — and the provider's refusal costs the round trip and names the request rather than the size.
+         */
+        try {
+            assertWithinBounds({ byteSize: file.byteSize, mediaType: file.mediaType }, audio.bounds);
+        }
+        catch (error) {
+            throw new AgentPlatformError({
+                code: "invalid_input",
+                message: error instanceof Error ? error.message : String(error),
+                retryable: false,
+            });
+        }
+        const result = await provider.transcribe({
+            audio: file.bytes,
+            mediaType: file.mediaType,
+            ...(file.filename === undefined ? {} : { filename: file.filename }),
+            ...(input.languageHint === undefined ? {} : { languageHint: input.languageHint }),
+        });
+        return {
+            text: result.text,
+            truncated: result.truncated,
+            ...(result.durationSeconds === undefined ? {} : { durationSeconds: result.durationSeconds }),
+            ...(result.language === undefined ? {} : { language: result.language }),
+            // Reported so a summary of what happened can name the provider rather than implying the platform did it.
+            provider: provider.id,
+        };
+    },
+});
+export const createSpeechGenerateTool = (deps, provider, audio) => defineDelegatingTool(deps, {
+    name: "speech_generate",
+    label: "Say something aloud",
+    description: "Turn text into an audio file the user can play. Returns a file id. This costs money per character, so " +
+        "say what needs saying rather than reading a whole document aloud. Requires approval by policy.",
+    category: "media",
+    // Creates a file the tenant owns; nothing leaves the deployment. See the header on why not external-write.
+    effect: "internal-write",
+    /**
+     * `policy`, set explicitly — and the explicitness is the point.
+     *
+     * `internal-write` *derives* `never`, which is right for the writes that motivated that default: a note
+     * saved to the tenant's own store costs nothing and asking about it would be noise. This one costs money
+     * per character, so a deployment should be able to decide whether an agent may spend it unattended.
+     *
+     * `policy` rather than `always` because the amount is small and bounded by the character ceiling — a
+     * mandatory click on every sentence would make the tool unusable, and `docs/23` specifies `policy` for
+     * exactly this reason.
+     */
+    approvalPolicy: "policy",
+    inputSchema: speechSchema,
+    delegatesTo: "audio.SpeechProvider",
+    delegate: async (input) => {
+        const spoken = await provider.speak({
+            text: input.text,
+            ...(input.voice === undefined ? {} : { voice: input.voice }),
+            ...(input.format === undefined ? {} : { format: input.format }),
+        });
+        const extension = { "audio/mpeg": "mp3", "audio/wav": "wav", "audio/ogg": "opus", "audio/flac": "flac" }[spoken.mediaType];
+        const stored = await audio.writeAudio({
+            bytes: spoken.audio,
+            mediaType: spoken.mediaType,
+            // Named from the text so a list of generated files is readable, and bounded so a long prompt does not
+            // become a 4,000-character filename.
+            filename: `speech-${input.text.slice(0, 40).replace(/[^\w -]/g, "").trim().replace(/\s+/g, "-") || "audio"}.${extension ?? "bin"}`,
+        });
+        return {
+            fileId: stored.fileId,
+            ...(stored.url === undefined ? {} : { url: stored.url }),
+            mediaType: spoken.mediaType,
+            byteSize: spoken.audio.byteLength,
+            ...(spoken.durationSeconds === undefined ? {} : { durationSeconds: spoken.durationSeconds }),
+            characters: input.text.length,
+            provider: provider.id,
+        };
+    },
+});
+//# sourceMappingURL=audio.js.map

package/dist/tools/library/index.d.ts

@@ -121,4 +121,12 @@ export { createHttpRequestTool, createHttpWriteTool } from "./http.js";
 export { createSearchKnowledgeTool } from "./knowledge.js";
 export type { KnowledgeRetriever } from "./knowledge.js";
 export { createFetchJsonTool, createFetchUrlTool, createWebSearchTool } from "./web.js";
+/**
+ * Audio — REQ-062 (#257), task #258.
+ *
+ * Library tools rather than a `tools-media` package, and the reason is argued in `audio.ts`: they take ports,
+ * not a vendor, exactly as `createWebSearchTool` does.
+ */
+export { createSpeechGenerateTool, createTranscribeTool } from "./audio.js";
+export type { AudioToolDeps } from "./audio.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/tools/library/index.js

@@ -171,4 +171,11 @@ export { createParseCsvTool, createQueryJsonTool, createSqlQueryTool, createSqlS
 export { createHttpRequestTool, createHttpWriteTool } from "./http.js";
 export { createSearchKnowledgeTool } from "./knowledge.js";
 export { createFetchJsonTool, createFetchUrlTool, createWebSearchTool } from "./web.js";
+/**
+ * Audio — REQ-062 (#257), task #258.
+ *
+ * Library tools rather than a `tools-media` package, and the reason is argued in `audio.ts`: they take ports,
+ * not a vendor, exactly as `createWebSearchTool` does.
+ */
+export { createSpeechGenerateTool, createTranscribeTool } from "./audio.js";
 //# sourceMappingURL=index.js.map

package/dist/tools/registry.d.ts

@@ -120,6 +120,26 @@ export type ToolCatalog = {
      */
     readonly toolset?: TenantToolset;
 };
+/**
+ * Loads a skill body by name — the execution half of `load_skill`.
+ *
+ * Kept structural (no `skills` import) so `tools` does not depend on `skills`. Returns `null` for a name the
+ * tenant does not have, so an unknown skill is a message rather than a throw.
+ */
+export interface SkillBodyLoader {
+    load(context: ExecutionContext, name: string): Promise<{
+        readonly name: string;
+        readonly version: number;
+        readonly instructions: string;
+    } | null>;
+}
+/**
+ * How many distinct skills one run may pull into context.
+ *
+ * Mirrors `SKILL_LIMITS.maxLoadedPerRun`, duplicated rather than imported for the same layering reason as
+ * `SkillBodyLoader`. A test asserts the two agree, so the copy cannot drift silently.
+ */
+export declare const MAX_SKILLS_LOADED_PER_RUN = 5;
 /** Structural approval check (satisfied by the HITL `ApprovalGate`) — kept structural to avoid a
  * tools→hitl dependency. Returns false when the tool needs approval and the call carries neither a
  * standing grant nor a valid one-time approval. */
@@ -208,6 +228,19 @@ export type ToolRegistryConfig = {
      * Wiring is the toggle, the same rule the tool library already follows for `web_search`.
      */
     readonly search?: ToolSearch;
+    /**
+     * Loads a named skill's body, when the deployment has skills — task #244.
+     *
+     * Structural rather than importing `SkillResolver`, for the reason `ApprovalCheck` is structural: `tools` must
+     * not depend on `skills`. `createSkillBodyLoader` in `skills/` adapts a resolver to this shape.
+     *
+     * Wiring is the toggle. `load_skill` has been in `META_TOOLS` since the registry was written with **nothing
+     * implementing it** — the third instance of that exact pattern after `execute_tool` and `learn_tools` (#210).
+     * A model handed the descriptor would call it, get "Unknown tool load_skill", and a transcript reader would
+     * see a broken platform. So the descriptor is now advertised only when this is wired, which is the rule
+     * `find_tools` already follows.
+     */
+    readonly skills?: SkillBodyLoader;
     /** A tenant's category switches, applied *before* authorization filtering — AC-4. */
     readonly toolsets?: ToolsetResolver;
     /**

package/dist/tools/registry.js

@@ -83,6 +83,13 @@ export const categoryEnabled = (toolset, category) => {
         return false;
     return !(toolset.disabledCategories ?? []).includes(category);
 };
+/**
+ * How many distinct skills one run may pull into context.
+ *
+ * Mirrors `SKILL_LIMITS.maxLoadedPerRun`, duplicated rather than imported for the same layering reason as
+ * `SkillBodyLoader`. A test asserts the two agree, so the copy cannot drift silently.
+ */
+export const MAX_SKILLS_LOADED_PER_RUN = 5;
 export const createToolRegistry = (config) => {
     const maxInline = config.maxInlineOutputBytes ?? 8 * 1024;
     const validator = config.validator ?? zodishValidator;
@@ -158,7 +165,19 @@ export const createToolRegistry = (config) => {
         const wanted = toolset === undefined
             ? all.filter((t) => !duplicated.has(t.descriptor.name))
             : all.filter((t) => !duplicated.has(t.descriptor.name) && categoryEnabled(toolset, t.descriptor.category));
-        const usable = wanted;
+        /**
+         * The running agent's exclusions — task #244.
+         *
+         * Here, alongside the tenant toolset and before authorization, for the same reason: an excluded tool does not
+         * exist for this agent, so it must not reach the authorization policy, must not appear in what a policy
+         * audits, and must not be findable by `find_tools`.
+         *
+         * `excluded` only. `preloaded` and `categories` decide which tools carry full schemas up front, which is a
+         * question about the *catalogue* and is answered in `catalog()`; they are not a permission and must not
+         * remove anything here.
+         */
+        const excludedByAgent = new Set(context.agentToolPolicy?.excluded ?? []);
+        const usable = excludedByAgent.size === 0 ? wanted : wanted.filter((t) => !excludedByAgent.has(t.descriptor.name));
         const descriptors = usable.map((t) => t.descriptor);
         const permitted = new Set((await config.authorization.filterTools(context, descriptors)).map((d) => d.name));
         return usable.filter((t) => permitted.has(t.descriptor.name));
@@ -178,6 +197,15 @@ export const createToolRegistry = (config) => {
         const tools = (await authorizedTools(context)).map((t) => t.descriptor);
         return config.search.search({ query: input.query, tools, limit: input.limit ?? 10 });
     };
+    /**
+     * Skills already pulled into context, per run — the ceiling for `load_skill`.
+     *
+     * Per registry instance and keyed by run id. In a multi-process deployment a run is claimed by one worker at a
+     * time (the lease), so a per-process tally is the right scope; it is a *context* ceiling, and context is
+     * per-turn anyway. A run that migrates to another worker after a crash starts its tally again, which is the
+     * correct direction: the new attempt's context is empty.
+     */
+    const skillsLoadedPerRun = new Map();
     const api = {
         async catalog(context, policy) {
             const excluded = new Set(policy.excluded);
@@ -199,7 +227,10 @@ export const createToolRegistry = (config) => {
              * The alternative — a permanent descriptor that fails at execution — costs the model a call to discover
              * and reads in a transcript exactly like a broken platform.
              */
-            const meta = META_TOOL_DESCRIPTOR_LIST.filter((d) => d.name !== "find_tools" || config.search !== undefined).map(compact);
+            const meta = META_TOOL_DESCRIPTOR_LIST.filter((d) => (d.name !== "find_tools" || config.search !== undefined) &&
+                // Same rule, same reason: a descriptor that fails at execution costs the model a call to discover and
+                // reads in a transcript exactly like a broken platform — #244.
+                (d.name !== "load_skill" || config.skills !== undefined)).map(compact);
             const toolset = config.toolsets === undefined ? undefined : await config.toolsets.resolve(context);
             if (config.catalogBudget === undefined)
                 return {
@@ -286,6 +317,45 @@ export const createToolRegistry = (config) => {
              * tool, and called it wrongly or not at all. Search without schemas is a dead end, and the descriptor for
              * `learn_tools` had been in `META_TOOLS` since the registry was written with nothing implementing it.
              */
+            /**
+             * `load_skill` — task #244, and the third meta-tool that was advertised with nothing behind it.
+             *
+             * Handled in the registry for the reason `find_tools` is: the model reaches it as a tool, so it has to go
+             * through the same surface. A per-run ceiling bounds what one run may pull into context — a model that
+             * loads every skill it can see has undone the whole point of a catalogue plus on-demand bodies.
+             *
+             * **Only when a loader is wired**, and unlike `find_tools` this branch does not refuse when it is not — it
+             * falls through to provider dispatch. `find_tools` has to be the registry's (its corpus *is* the registry's
+             * authorized list), but `load_skill` can perfectly well be a provider tool, and the reference host had one
+             * before this existed. Intercepting the name unconditionally broke it: a host with a working `load_skill`
+             * got `capability_unavailable` because *this* registry had no resolver. The built-in is a default, not a
+             * claim on the name.
+             */
+            if (input.name === "load_skill" && config.skills !== undefined) {
+                const asked = (input.input ?? {});
+                if (typeof asked.name !== "string" || asked.name.trim() === "")
+                    return { ok: false, error: invalidInput("load_skill needs `name`: the skill whose instructions you want.") };
+                const runKey = context.runId ?? "no-run";
+                const loaded = skillsLoadedPerRun.get(runKey) ?? new Set();
+                // Counted per distinct name, so re-loading one already in context is free rather than spending the
+                // ceiling twice on the same content.
+                if (!loaded.has(asked.name) && loaded.size >= MAX_SKILLS_LOADED_PER_RUN)
+                    return {
+                        ok: false,
+                        error: capabilityUnavailable(`this run has already loaded ${MAX_SKILLS_LOADED_PER_RUN} skills, which is the ceiling. ` +
+                            `Already loaded: ${[...loaded].join(", ")}.`),
+                    };
+                const skill = await config.skills.load(context, asked.name);
+                if (skill === null)
+                    return {
+                        ok: false,
+                        error: invalidInput(`No skill named "${asked.name}" is available to this tenant. The skills you can load are listed in ` +
+                            "your context."),
+                    };
+                loaded.add(skill.name);
+                skillsLoadedPerRun.set(runKey, loaded);
+                return { ok: true, data: { name: skill.name, version: skill.version, instructions: skill.instructions } };
+            }
             if (input.name === "learn_tools") {
                 const asked = (input.input ?? {});
                 const names = Array.isArray(asked.names) ? asked.names.filter((n) => typeof n === "string") : [];

package/dist/usage/index.d.ts

@@ -32,6 +32,14 @@ export type UsageEvent = {
     readonly inputTokens: number;
     readonly outputTokens: number;
     readonly cachedInputTokens: number;
+    /**
+     * Tokens written into a prompt cache — task #247.
+     *
+     * Optional, and absent means "not reported" rather than "none": rows written before this existed and a turn
+     * whose provider reports no breakdown are different facts, and a zero would merge them. The same rule
+     * `imageCount` follows.
+     */
+    readonly cacheWriteTokens?: number;
     readonly reasoningTokens?: number;
     /**
      * Non-text input this turn carried — #185 AC-4.
@@ -70,6 +78,18 @@ export type CostEstimate = {
     readonly modelId: string;
     readonly inputTokens: number;
     readonly maxOutputTokens: number;
+    /**
+     * How much of `inputTokens` the caller expects to be served from cache — task #247.
+     *
+     * Optional, and its absence means "assume none", which is what this did unconditionally before. That default
+     * is deliberately the *conservative* one for a spend limit: over-reserving refuses a turn slightly early,
+     * under-reserving admits a turn that then exceeds the ceiling, and only the second one costs money.
+     *
+     * A seam rather than a prediction. The platform cannot know a hit rate before the call, and inventing one
+     * would make every reservation wrong in a new way; a caller that has just observed 97% on the previous turn of
+     * the same conversation genuinely does know something, and this is where it says so.
+     */
+    readonly cachedInputTokens?: number;
 };
 export type Reservation = {
     readonly id: string;
@@ -101,5 +121,6 @@ export interface PricingResolver {
 }
 export * from "./recorder.js";
 export * from "./quota.js";
+export * from "./rate-limit.js";
 export * from "./rollups.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/usage/index.js

@@ -16,5 +16,6 @@
 export const usageDedupeKey = (event) => (event.stepId === undefined ? event.id : `${event.runId}:${event.stepId}`);
 export * from "./recorder.js";
 export * from "./quota.js";
+export * from "./rate-limit.js";
 export * from "./rollups.js";
 //# sourceMappingURL=index.js.map

package/dist/usage/rate-limit.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Per-tenant rate limiting at run admission — REQ-058 (#246), task #248.
+ *
+ * Cost quotas already gate admission and work well: reservations, `UsageCeiling`, refusal before a provider call
+ * (`quota.ts`). **Rate is a different axis and nothing bounded it.** A thousand runs a second, each costing a
+ * fraction of a cent, passes every check that existed — `grep -ril "rate limit"` found the phrase only in
+ * `runtime/retry.ts`, handling a *provider's* 429, and in the load-test scenario.
+ *
+ * The two fail differently, which is why this is not a dimension of the quota guard:
+ *
+ * - A cost ceiling stops a tenant **spending too much over a period**. It is answered from a rollup.
+ * - A rate limit stops a tenant **consuming a deployment's capacity right now**. It is answered from a counter
+ *   that has to be correct across every process in the fleet.
+ *
+ * ## Why this lives in `usage/`
+ *
+ * It is not usage, and it sits here anyway: it is an *admission guard*, it is called on the same line as the
+ * quota guard, a deployment configures both in the same place, and putting it in its own module would add a
+ * published subpath for one port. The alternative was worse than the mild misfiling.
+ *
+ * ## Fixed window, and what that costs
+ *
+ * The window is identified by its **start, truncated to the period** — the same decision `bucketStartFor` makes
+ * for rollups, for the same reason: two processes asking "which window does T belong to" must agree, and they do
+ * because truncation is a pure function of T rather than a range someone chooses. It also means the Redis key is
+ * deterministic, so a key can never be created without an expiry and strand a tenant.
+ *
+ * The cost is the boundary burst: a tenant may send `max` at the end of one window and `max` at the start of the
+ * next, so the true worst case over a sliding window is 2×`max`. A sliding-log implementation would fix that and
+ * costs a sorted set per tenant with a member per request. Not worth it: the point is to stop a runaway client
+ * saturating a fleet, and 2× the intended rate for one window boundary does not.
+ *
+ * ## Two axes deliberately not implemented — AC-1
+ *
+ * **Concurrent runs per tenant.** This is a real gap: `startOrEnqueueRun` serialises runs *within* a
+ * conversation, and `serialization.ts` says outright that a conversation-less run's concurrency is "bounded
+ * where it should be: the worker's own limits, and quotas" — which is a per-process setting and a spend limit,
+ * neither of which stops one tenant occupying every slot in the fleet. It is left out because a *correct*
+ * implementation must be crash-safe, and a counter incremented at admission and decremented at completion leaks
+ * a permanent unit every time a worker dies mid-run. The right home is the existing run **lease**, which already
+ * has a TTL and a heartbeat — so this belongs with the lease rather than beside it, and doing it here would mean
+ * shipping the leaky version first.
+ *
+ * **Tool executions per run per interval.** `ExecutionLimits.maxToolCalls` already bounds the *count* and
+ * `wallClockTimeoutMs` bounds a tight loop, so a rate would need a clock threaded through the tool path to
+ * constrain something already constrained twice.
+ */
+import type { ExecutionContext } from "../core/context.js";
+import type { TenantId } from "../core/ids.js";
+/**
+ * How many admissions a tenant gets, and over how long.
+ *
+ * `max: 0` and an absent policy both mean **unlimited** — see `createRateLimitGuard`. A deployment upgrading
+ * into this feature must not find its runs refused because it has not configured a limit yet.
+ */
+export type RateLimitPolicy = {
+    readonly max: number;
+    readonly windowSeconds: number;
+};
+export type RateLimitDecision = 
+/** `remaining` is after this admission, so zero means the next one refuses. */
+{
+    readonly admitted: true;
+    readonly remaining: number;
+    readonly resetsAt: string;
+} | {
+    readonly admitted: false;
+    readonly limit: number;
+    readonly windowSeconds: number;
+    readonly used: number;
+    readonly resetsAt: string;
+    readonly retryAfterMs: number;
+    readonly message: string;
+};
+/**
+ * The counter, as a port.
+ *
+ * `consume` must be **atomic** and must set the expiry in the same operation. An `INCR` followed by a separate
+ * `EXPIRE` is the obvious implementation and it is wrong: a process dying between the two leaves a key with no
+ * TTL, and that tenant is refused for ever. The Redis adapter uses one script.
+ */
+export interface RateLimitStore {
+    consume(input: {
+        readonly tenantId: TenantId;
+        /** The truncated window start, in epoch milliseconds — the key's identity. */
+        readonly windowStartMs: number;
+        readonly windowSeconds: number;
+    }): Promise<number>;
+}
+/** The window a moment belongs to. Pure, so every process agrees without coordinating. */
+export declare const windowStartMs: (atMs: number, windowSeconds: number) => number;
+/**
+ * Told when a tenant is refused.
+ *
+ * A sink of its own rather than a `RunEvent`, and the reason is the one `QuotaObserver` already gives: a
+ * `RunEvent` carries a `runId`, and this fires **before a run exists** — which is the whole point of refusing at
+ * admission. Squeezing it into the run stream would mean inventing a run id for an event about not starting one.
+ */
+export interface RateLimitObserver {
+    onRefusal(context: ExecutionContext, refusal: Extract<RateLimitDecision, {
+        admitted: false;
+    }>): Promise<void> | void;
+}
+export type RateLimitGuardDeps = {
+    readonly store: RateLimitStore;
+    /**
+     * The policy for this tenant, or undefined for unlimited.
+     *
+     * A function rather than a value, for the reason `QuotaGuardDeps` gives: limits are per tenant and change
+     * without a redeploy, and a value captured at construction would be the limits of whoever booted the process.
+     */
+    readonly policyFor: (context: ExecutionContext) => Promise<RateLimitPolicy | undefined> | RateLimitPolicy | undefined;
+    readonly observer?: RateLimitObserver;
+    readonly now?: () => number;
+};
+export declare const createRateLimitGuard: (deps: RateLimitGuardDeps) => {
+    admit(context: ExecutionContext): Promise<RateLimitDecision>;
+    /** Throws the refusal, for a caller that would rather not branch. Same decision, different ergonomics. */
+    assertAdmitted(context: ExecutionContext): Promise<RateLimitDecision>;
+};
+export type RateLimitGuard = ReturnType<typeof createRateLimitGuard>;
+//# sourceMappingURL=rate-limit.d.ts.map