@retinue/agentkit 0.1.0 → 0.3.0

package/dist/tools/registry.js

@@ -18,6 +18,8 @@
 import { assertToolAuthorized } from "../authorization/index.js";
 import { deriveIdempotencyKey } from "../idempotency/index.js";
 import { META_TOOL_DESCRIPTOR_LIST } from "./meta-tools.js";
+import { applyTokenBudget } from "../core/budget.js";
+import { entryTokens } from "./budget.js";
 /** Default validator: run a zod-like schema's `safeParse`; pass through anything else (tool self-validates). */
 export const zodishValidator = {
     validate(schema, value) {
@@ -39,6 +41,26 @@ const compact = (d) => ({
     effect: d.effect,
 });
 const invalidInput = (message) => ({ code: "invalid_input", message, retryable: false });
+/** The registry's own meta-tools, which a model may not target through `execute_tool`. */
+const META_ONLY = new Set(["execute_tool", "find_tools", "learn_tools", "read_tool_output"]);
+export const unwrapExecuteTool = (request) => {
+    if (request.name !== "execute_tool")
+        return request;
+    const asked = (request.input ?? {});
+    if (typeof asked.name !== "string" || asked.name.trim() === "")
+        return { error: invalidInput("execute_tool needs the name of the tool to run.") };
+    if (META_ONLY.has(asked.name))
+        return { error: invalidInput(`execute_tool cannot call ${asked.name}; call it directly.`) };
+    return {
+        name: asked.name,
+        input: asked.input,
+        ...(typeof asked.idempotencyKey === "string" ? { idempotencyKey: asked.idempotencyKey } : {}),
+        // The *outer* call's identity is kept: the tool call the model made is the one the run event log records,
+        // and rewriting it here would make a transcript disagree with the model's own history.
+        ...(request.toolCallId === undefined ? {} : { toolCallId: request.toolCallId }),
+        ...(request.approval === undefined ? {} : { approval: request.approval }),
+    };
+};
 /** A wiring problem, not a caller problem: retrying the identical call cannot help. */
 const capabilityUnavailable = (message) => ({
     code: "capability_unavailable",
@@ -46,6 +68,28 @@ const capabilityUnavailable = (message) => ({
     retryable: false,
 });
 const requiresKey = (effect, requires) => requires || effect === "external-write" || effect === "destructive";
+/**
+ * Categories a tenant may not switch off.
+ *
+ * `meta` is the model's route back to everything else. A tenant that disabled it would have an agent that cannot
+ * learn a schema or search the catalogue — which is not a smaller toolset, it is a broken one.
+ */
+export const UNDISABLEABLE_CATEGORIES = ["meta"];
+/** Whether a category survives a tenant's toolset. Exported because the filtering is worth testing directly. */
+export const categoryEnabled = (toolset, category) => {
+    if (UNDISABLEABLE_CATEGORIES.includes(category))
+        return true;
+    if (toolset.enabledCategories !== undefined && !toolset.enabledCategories.includes(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;
@@ -110,13 +154,59 @@ export const createToolRegistry = (config) => {
                 });
             }
         }
-        const usable = all.filter((t) => !duplicated.has(t.descriptor.name));
+        /**
+         * The tenant's toolset, applied **before** authorization — AC-4.
+         *
+         * Order matters and this is the order the AC asks for. A tool a tenant switched off is not a tool the
+         * principal is unauthorized for: it does not exist for that tenant, so it must not reach the authorization
+         * policy, must not appear in a policy's audit of what it filtered, and must not be findable.
+         */
+        const toolset = config.toolsets === undefined ? undefined : await config.toolsets.resolve(context);
+        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));
+        /**
+         * 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));
     };
     const findAuthorized = async (context, name) => (await authorizedTools(context)).find((t) => t.descriptor.name === name) ?? null;
-    return {
+    /**
+     * One implementation, reached two ways: `registry.find` for a host, and `execute("find_tools")` for a model.
+     *
+     * `find_tools` is not authorized as a tool in its own right, and that is deliberate: like every other
+     * meta-tool it is part of the interface rather than a capability a role grants. What *is* authorized is
+     * everything it can return — the corpus is the caller's own authorized tool list — so the worst a principal
+     * with no tools can learn from it is that they have none.
+     */
+    const runFind = async (context, input) => {
+        if (config.search === undefined)
+            return { hits: [], modes: [] };
+        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);
             const preloadNames = new Set(policy.preloaded);
@@ -131,14 +221,169 @@ export const createToolRegistry = (config) => {
                 else
                     discoverable.push(compact(d));
             }
-            return { preloaded, discoverable, meta: META_TOOL_DESCRIPTOR_LIST.map(compact) };
+            /**
+             * `find_tools` is advertised only when a search is wired.
+             *
+             * 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) &&
+                // 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 {
+                    preloaded,
+                    discoverable,
+                    meta,
+                    ...(toolset === undefined ? {} : { toolset }),
+                };
+            // Preloaded entries and the meta-tools are charged against the budget but never dropped: they are the
+            // host's own instruction and the model's route back to what was withheld.
+            const fixed = preloaded.reduce((total, d) => total + entryTokens(compact(d)), 0) +
+                meta.reduce((total, entry) => total + entryTokens(entry), 0);
+            const outcome = applyTokenBudget({
+                items: discoverable,
+                budget: { maxTokens: Math.max(0, config.catalogBudget.maxTokens - fixed) },
+                tokensOf: entryTokens,
+                nameOf: (entry) => entry.name,
+            });
+            return {
+                preloaded,
+                discoverable: outcome.resident,
+                meta,
+                ...(toolset === undefined ? {} : { toolset }),
+                ...(outcome.dropped.length === 0 && !outcome.overBudget
+                    ? {}
+                    : {
+                        truncation: {
+                            budgetTokens: config.catalogBudget.maxTokens,
+                            residentTokens: outcome.residentTokens + fixed,
+                            dropped: outcome.dropped,
+                            findable: config.search !== undefined,
+                            overBudget: outcome.residentTokens + fixed > config.catalogBudget.maxTokens,
+                        },
+                    }),
+            };
+        },
+        find: runFind,
+        async listAuthorized(context) {
+            return (await authorizedTools(context)).map((t) => t.descriptor);
         },
         async learn(context, names) {
             // Only authorized tools are returned — an unauthorized name is silently unlearnable.
             const wanted = new Set(names);
             return (await authorizedTools(context)).map((t) => t.descriptor).filter((d) => wanted.has(d.name));
         },
-        async execute(context, input) {
+        async execute(context, outer) {
+            /**
+             * `execute_tool`, unwrapped before anything else — task #210.
+             *
+             * Without this, `find_tools` finds a tool the model **cannot call**: a truncated tool list means the name
+             * it just learned is not in its own tool set, so search would return an answer and leave the model stuck.
+             * That is the difference between a deferral and an amputation, and it was missing — `execute_tool` has been
+             * in `META_TOOLS` since the registry was written and nothing implemented it.
+             *
+             * Unwrapping rather than dispatching: the inner call then goes through *every* check below — authorization,
+             * the toolset, the approval gate, validation, idempotency, the shadow recorder — because it is the same
+             * code path. A separate branch that called the tool directly would be a way around all of them, reachable
+             * by name from a model.
+             */
+            if (outer.name === "execute_tool") {
+                const unwrapped = unwrapExecuteTool(outer);
+                if ("error" in unwrapped)
+                    return { ok: false, error: unwrapped.error };
+                /**
+                 * Re-entered through the public surface, and tagged once on the way out.
+                 *
+                 * Re-entering rather than falling through with a rewritten argument: the inner call then passes every
+                 * check below exactly as a direct call would — authorization, the tenant's toolset, the approval gate,
+                 * validation, idempotency, the shadow recorder — because it *is* a direct call. A fall-through would work
+                 * today and become a bypass the first time somebody adds a check above this line.
+                 *
+                 * `ranToolName` is attached here, in the one place the indirection is known. The audit trail's question
+                 * is "what was done", and `execute_tool` is not an answer to it.
+                 */
+                const inner = await api.execute(context, unwrapped);
+                return { ...inner, ranToolName: unwrapped.name };
+            }
+            const input = outer;
+            /**
+             * `learn_tools`, handled here — task #210, and the leg that was missing.
+             *
+             * `find_tools` returns names and descriptions. A model that then calls the tool through `execute_tool` has
+             * to guess its arguments, and in the 200-tool measurement it did exactly that: searched, found the right
+             * 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") : [];
+                if (names.length === 0)
+                    return { ok: false, error: invalidInput("learn_tools needs `names`: the tools whose schemas you want.") };
+                // Authorized only, like discovery and like search — an unauthorized name is silently unlearnable.
+                return { ok: true, data: { tools: await api.learn(context, names) } };
+            }
+            /**
+             * `find_tools`, handled here rather than by a provider — AC-1.
+             *
+             * It has to be the registry: the corpus *is* the registry's authorized tool list, and a provider-supplied
+             * search tool would either need the registry passed into it (a construction cycle) or its own idea of what
+             * exists, which is the second implementation AC-2 forbids.
+             */
+            if (input.name === "find_tools") {
+                if (config.search === undefined)
+                    return {
+                        ok: false,
+                        error: capabilityUnavailable("find_tools is not available: no tool search is configured (see ToolRegistryConfig.search)."),
+                    };
+                const asked = (input.input ?? {});
+                if (typeof asked.query !== "string" || asked.query.trim() === "")
+                    return { ok: false, error: invalidInput("find_tools needs a query describing what you are trying to do.") };
+                const limit = typeof asked.limit === "number" && asked.limit > 0 ? Math.min(Math.floor(asked.limit), 25) : 10;
+                const outcome = await runFind(context, { query: asked.query, limit });
+                return { ok: true, data: outcome };
+            }
             const tool = await findAuthorized(context, input.name);
             // Not found OR not authorized → both reject; execution is never a way around discovery filtering.
             if (!tool) {
@@ -272,6 +517,7 @@ export const createToolRegistry = (config) => {
             return { ok: true, data: value };
         },
     };
+    return api;
     /** Spill an oversize success payload to blob storage and reference it. */
     async function maybeSpill(context, result) {
         if (!result.ok || result.spilledOutputRef !== undefined)

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

package/dist/usage/rate-limit.js

@@ -0,0 +1,131 @@
+/**
+ * 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 { AgentPlatformError } from "../core/errors.js";
+/** The window a moment belongs to. Pure, so every process agrees without coordinating. */
+export const windowStartMs = (atMs, windowSeconds) => {
+    if (!Number.isFinite(atMs))
+        throw new AgentPlatformError({ code: "invalid_input", message: "rate limit: `at` must be a finite number of milliseconds", retryable: false });
+    if (!Number.isInteger(windowSeconds) || windowSeconds <= 0)
+        throw new AgentPlatformError({
+            code: "invalid_input",
+            message: `rate limit: windowSeconds must be a positive integer, got ${windowSeconds}`,
+            retryable: false,
+        });
+    const span = windowSeconds * 1_000;
+    return Math.floor(atMs / span) * span;
+};
+export const createRateLimitGuard = (deps) => {
+    const now = deps.now ?? Date.now;
+    return {
+        async admit(context) {
+            const policy = await deps.policyFor(context);
+            /**
+             * Unlimited, and this is the branch that matters most on the day this ships — AC-7.
+             *
+             * No policy, or a `max` of zero, means unlimited rather than deny-everything. A deployment that upgrades
+             * into this feature and has configured nothing must keep working; the alternative is an outage caused by
+             * adding a safety feature, which is how safety features get removed.
+             */
+            if (policy === undefined || policy.max <= 0)
+                return { admitted: true, remaining: Number.POSITIVE_INFINITY, resetsAt: new Date(now()).toISOString() };
+            const at = now();
+            const start = windowStartMs(at, policy.windowSeconds);
+            const resetsAtMs = start + policy.windowSeconds * 1_000;
+            const resetsAt = new Date(resetsAtMs).toISOString();
+            const used = await deps.store.consume({
+                tenantId: context.tenantId,
+                windowStartMs: start,
+                windowSeconds: policy.windowSeconds,
+            });
+            if (used <= policy.max)
+                return { admitted: true, remaining: policy.max - used, resetsAt };
+            const refusal = {
+                admitted: false,
+                limit: policy.max,
+                windowSeconds: policy.windowSeconds,
+                used,
+                resetsAt,
+                // At least a millisecond: a window that has just closed must not tell a client to retry in zero, which
+                // reads as "immediately" and puts it straight back into the same refusal.
+                retryAfterMs: Math.max(1, resetsAtMs - at),
+                message: `This workspace has used ${used} of ${policy.max} runs allowed per ${policy.windowSeconds}s. ` +
+                    `It resets at ${resetsAt}.`,
+            };
+            await deps.observer?.onRefusal(context, refusal);
+            return refusal;
+        },
+        /** Throws the refusal, for a caller that would rather not branch. Same decision, different ergonomics. */
+        async assertAdmitted(context) {
+            const decision = await this.admit(context);
+            if (!decision.admitted)
+                throw new AgentPlatformError({
+                    code: "admission_rate_limited",
+                    message: decision.message,
+                    /**
+                     * Retryable, and `retryAfterMs` is what makes that honest.
+                     *
+                     * The window resets, so a client that treated this as permanent would give up on a workspace that is
+                     * fine in a second. What must **not** happen is the engine's retry loop absorbing it — and it cannot:
+                     * this is thrown at admission, before a run exists, so `decideRetry` never sees it. The distinct error
+                     * code is what keeps it that way if the call site ever moves.
+                     */
+                    retryable: true,
+                    retryAfterMs: decision.retryAfterMs,
+                    details: {
+                        retryAfter: decision.resetsAt,
+                        retryAfterMs: decision.retryAfterMs,
+                        limit: decision.limit,
+                        used: decision.used,
+                        windowSeconds: decision.windowSeconds,
+                    },
+                });
+            return decision;
+        },
+    };
+};
+//# sourceMappingURL=rate-limit.js.map

package/dist/usage/recorder.js

@@ -49,6 +49,9 @@ export const createUsageRecorder = (config) => {
         return computeModelCostMinorUnits(pricing, {
             inputTokens: estimate.inputTokens,
             outputTokens: estimate.maxOutputTokens,
+            // Cache-aware when the caller said so — task #247. Absent means assume none, which over-reserves; that is
+            // the safe direction for a spend limit and is what this always did.
+            ...(estimate.cachedInputTokens === undefined ? {} : { cachedInputTokens: estimate.cachedInputTokens }),
         });
     };
     return {