@ixo/oracle-runtime-workers 0.13.0 → 0.16.0

package/src/core/manifest.ts

@@ -49,8 +49,35 @@ export const pluginManifestSchema: z.ZodType<PluginManifest> = z.object({
   category: manifestCategorySchema.optional(),
   visibility: manifestVisibilitySchema.optional(),
   stability: manifestStabilitySchema.optional(),
+  requires: z
+    .array(z.object({ resource: z.string().min(1), action: z.string().min(1) }))
+    .optional(),
 });
 
+/** A UCAN capability a plugin's manifest requires of the user's delegation. */
+export type CapabilityRequirement = NonNullable<
+  PluginManifest['requires']
+>[number];
+
+/** The manifest's requirements the user's delegation does not meet (empty when usable). */
+export function unmetRequirements(
+  manifest: Pick<PluginManifest, 'requires'>,
+  hasCapability: (resource: string, action: string) => boolean,
+): CapabilityRequirement[] {
+  return (manifest.requires ?? []).filter(
+    (r) => !hasCapability(r.resource, r.action),
+  );
+}
+
+/** `can` on `with` pairs for a message: "`*` on `ixo:filesystem`, …". */
+export function describeRequirements(
+  requirements: readonly CapabilityRequirement[],
+): string {
+  return requirements
+    .map((r) => `\`${r.action}\` on \`${r.resource}\``)
+    .join(', ');
+}
+
 // ── Validator ───────────────────────────────────────────────────────────────
 
 /** Result of validating a single plugin manifest. */
@@ -289,6 +316,13 @@ export function estimateTokensApprox(text: string): number {
   return Math.ceil(text.length / 4);
 }
 
+/**
+ * Size above which a plugin's `operatingGuide` is reported at boot (chars/4
+ * tokens). The guide rides in the system prompt of every turn that has the
+ * plugin loaded; the bundled flows guide is about 2,000.
+ */
+export const OPERATING_GUIDE_WARN_TOKENS = 3_000;
+
 function formatExample(ex: ManifestExample): string {
   const argSummary =
     ex.args && Object.keys(ex.args).length > 0

package/src/core/meta-tools.ts

@@ -3,9 +3,39 @@ import { Command } from '@langchain/langgraph';
 import { ToolMessage } from '@langchain/core/messages';
 import { tool } from '../plugin-api/tool-helper';
 import type { PluginManifest, PluginTool } from '../plugin-api/types';
-import type { ManifestRegistry, ToolRegistry } from './registries';
+import {
+  describeRequirements,
+  unmetRequirements,
+  type CapabilityRequirement,
+} from './manifest';
+import type { ManifestRegistry, ToolSummarySource } from './registries';
+import { withoutWithheldExamples, type TurnToolAccess } from './tool-access';
 import { acquireToolLock } from './utils';
 
+export const LOAD_CAPABILITY_TOOL_NAME = 'load_capability';
+export const LIST_CAPABILITIES_TOOL_NAME = 'list_capabilities';
+/** Names of the tools `buildMetaTools` returns. */
+export const META_TOOL_NAMES: readonly string[] = [
+  LOAD_CAPABILITY_TOOL_NAME,
+  LIST_CAPABILITIES_TOOL_NAME,
+];
+
+/**
+ * The part of the turn's `resolveTurnToolAccess` result the meta-tools read:
+ * computed once per build from the same delegation their `ctx` carries.
+ */
+export type MetaToolAccess = Pick<
+  TurnToolAccess<never>,
+  'withheldToolNames' | 'hiddenPlugins'
+> & {
+  /**
+   * Plugins available this turn only through the capability router's
+   * preload: usable, but their operating guide is not in the system prompt,
+   * so `load_capability` still returns it.
+   */
+  preloadedOnly?: ReadonlySet<string>;
+};
+
 // ── list_capabilities ───────────────────────────────────────────────────────
 
 /**
@@ -27,6 +57,11 @@ interface CapabilityListing {
   loaded: boolean;
   category?: PluginManifest['category'];
   tags: string[];
+  /**
+   * Present only when the user's authorization does not grant what the
+   * plugin requires: it cannot be loaded or used until they re-authorize.
+   */
+  unavailable?: { missing: CapabilityRequirement[] };
 }
 
 /**
@@ -34,10 +69,13 @@ interface CapabilityListing {
  *
  * Returns one entry per loaded plugin, with a `loaded` flag that combines
  * the boot-time always-on plugins (`visibility === 'always'`) with the set
- * of plugins the agent has explicitly loaded for this thread.
+ * of plugins the agent has explicitly loaded for this thread. A plugin left
+ * with nothing by the turn's tool planes (`access.hiddenPlugins`) is not
+ * listed at all; one whose `requires` are unmet is listed as `unavailable`.
  */
 export function buildListCapabilitiesTool(
   manifestRegistry: ManifestRegistry,
+  access: MetaToolAccess,
 ): PluginTool {
   return tool(
     async (args, ctx) => {
@@ -54,13 +92,19 @@ export function buildListCapabilitiesTool(
         if (visibility === 'silent' && !includeSilent) continue;
         if (visibility === 'on-demand' && !includeOnDemand) continue;
 
+        if (access.hiddenPlugins.has(pluginName)) continue;
+
+        const missing = unmetRequirements(manifest, ctx.ucan.hasCapability);
         out.push({
           name: pluginName,
           summary: manifest.summary,
           visibility,
-          loaded: visibility === 'always' || loadedSet.has(pluginName),
+          loaded:
+            missing.length === 0 &&
+            (visibility === 'always' || loadedSet.has(pluginName)),
           category: manifest.category,
           tags: manifest.tags ?? [],
+          ...(missing.length > 0 ? { unavailable: { missing } } : {}),
         });
       }
       ctx.logger.debug?.(
@@ -72,7 +116,7 @@ export function buildListCapabilitiesTool(
       return JSON.stringify(out);
     },
     {
-      name: 'list_capabilities',
+      name: LIST_CAPABILITIES_TOOL_NAME,
       description: 'List all available capabilities and their summaries.',
       schema: listCapabilitiesSchema,
     },
@@ -103,6 +147,18 @@ interface LoadCapabilityResult extends PluginManifest {
   alreadyAvailable: boolean;
   /** One entry per tool the plugin contributes. */
   tools: ToolDetail[];
+  /**
+   * The plugin's working rules (`OraclePlugin.operatingGuide`), present when
+   * this call loaded it or the router only preloaded it, once per turn. A
+   * plugin loaded on the thread (or `always` visible) has it in the system
+   * prompt, so it is not repeated.
+   */
+  operatingGuide?: string;
+  /**
+   * Present when the plugin was NOT loaded because the user's authorization
+   * does not grant what it requires (`manifest.requires`).
+   */
+  refused?: { missing: CapabilityRequirement[]; reason: string };
 }
 
 /**
@@ -113,13 +169,22 @@ interface LoadCapabilityResult extends PluginManifest {
  * cannot be invoked in parallel — concurrent calls throw immediately.
  *
  * Behavior per name:
- *  - Unknown plugin → throws, instructing the agent to call
- *    `list_capabilities` first.
+ *  - Unknown plugin, or one the turn's tool planes left with nothing
+ *    (`access.hiddenPlugins`, answered exactly like an unknown one) →
+ *    throws, instructing the agent to call `list_capabilities` first.
  *  - `silent` plugin → throws (silent plugins are not agent-loadable).
+ *  - Plugin whose `requires` the user's delegation does not grant →
+ *    included in the result with `refused` (what is missing) and not
+ *    loaded; the rest of the batch is unaffected.
  *  - Plugin already loaded, or visibility is `always` → included in result
  *    with `alreadyAvailable: true` (no state change for that plugin).
  *  - Otherwise → added to the `loadedPlugins` state update.
  *
+ * The tool list and `examples` leave out the tools the turn withholds
+ * (`access.withheldToolNames`). A plugin this call loads, or one the router
+ * only preloaded, comes with its `operatingGuide` when it has one — once per
+ * turn; a refused one never does.
+ *
  * Return value:
  *  - If all requested plugins were already available: returns the result
  *    array directly (no state change).
@@ -129,8 +194,12 @@ interface LoadCapabilityResult extends PluginManifest {
  */
 export function buildLoadCapabilityTool(
   manifestRegistry: ManifestRegistry,
-  toolRegistry: ToolRegistry,
+  toolSource: ToolSummarySource,
+  access: MetaToolAccess,
 ): PluginTool {
+  // Guides this tool already returned: the tool is built per turn, and the
+  // context it reads does not see a load made earlier in the same turn.
+  const guidesReturned = new Set<string>();
   return tool(
     async (args, ctx) => {
       const { names } = loadCapabilitySchema.parse(args);
@@ -145,7 +214,7 @@ export function buildLoadCapabilityTool(
             .collect()
             .find((m) => m.pluginName === name);
 
-          if (!entry) {
+          if (!entry || access.hiddenPlugins.has(name)) {
             throw new Error(
               `Capability "${name}" does not exist. Call list_capabilities first to discover available plugins.`,
             );
@@ -157,8 +226,29 @@ export function buildLoadCapabilityTool(
             );
           }
 
-          const tools: ToolDetail[] = toolRegistry
+          const missing = unmetRequirements(
+            entry.manifest,
+            ctx.ucan.hasCapability,
+          );
+          if (missing.length > 0) {
+            results.push({
+              ...withoutWithheldExamples(
+                entry.manifest,
+                access.withheldToolNames,
+              ),
+              alreadyAvailable: false,
+              tools: [],
+              refused: {
+                missing,
+                reason: `The user's authorization for this oracle does not grant ${describeRequirements(missing)}, which "${name}" requires, so it was not loaded. Tell the user; they can re-authorize the oracle with that permission and ask again.`,
+              },
+            });
+            continue;
+          }
+
+          const tools: ToolDetail[] = toolSource
             .toolSummariesForPlugin(name)
+            .filter((t) => !access.withheldToolNames.has(t.name))
             .map((t) => ({
               name: t.name,
               description: t.description,
@@ -168,15 +258,32 @@ export function buildLoadCapabilityTool(
           const alwaysVisible = entry.manifest.visibility === 'always';
           const alreadyAvailable = alreadyLoaded || alwaysVisible;
 
-          results.push({ ...entry.manifest, alreadyAvailable, tools });
+          const guideInPrompt =
+            alreadyAvailable && access.preloadedOnly?.has(name) !== true;
+          const guide =
+            guideInPrompt || guidesReturned.has(name)
+              ? undefined
+              : manifestRegistry.operatingGuide(name);
+          if (guide) guidesReturned.add(name);
+          results.push({
+            ...withoutWithheldExamples(
+              entry.manifest,
+              access.withheldToolNames,
+            ),
+            alreadyAvailable,
+            tools,
+            ...(guide ? { operatingGuide: guide } : {}),
+          });
 
           if (!alreadyAvailable) {
             newToLoad.push(name);
           }
         }
 
+        // Text, never the bare array: LangChain would pass an array of
+        // objects through as the message's content blocks.
         if (newToLoad.length === 0) {
-          return results;
+          return JSON.stringify(results);
         }
 
         const update: Record<string, unknown> = {
@@ -196,7 +303,7 @@ export function buildLoadCapabilityTool(
       }
     },
     {
-      name: 'load_capability',
+      name: LOAD_CAPABILITY_TOOL_NAME,
       description:
         "Load one or more capabilities for the rest of this conversation. Pass all capabilities you need in a single call — batching is preferred over multiple calls. The response is an array of plugin manifests plus tool lists; after this call, the new capabilities' tools are usable on the next model step.",
       schema: loadCapabilitySchema,
@@ -207,12 +314,15 @@ export function buildLoadCapabilityTool(
 // ── Bundle ──────────────────────────────────────────────────────────────────
 
 /**
- * Inputs for `buildMetaTools`. The runtime passes its already-collected
- * registries; the meta-tools read manifests and tool descriptors from them.
+ * Inputs for `buildMetaTools`. The runtime passes the manifest registry and
+ * the turn's own collected tools (`turnToolSummaries`); a `ToolRegistry`
+ * also satisfies `toolRegistry`, but lists boot-time tools only.
  */
 export interface BuildMetaToolsOptions {
   manifestRegistry: ManifestRegistry;
-  toolRegistry: ToolRegistry;
+  toolRegistry: ToolSummarySource;
+  /** The turn's tool-plane result (`resolveTurnToolAccess`). */
+  toolAccess: MetaToolAccess;
 }
 
 /**
@@ -224,9 +334,9 @@ export interface BuildMetaToolsOptions {
  *  - `list_capabilities` — list every visible plugin with status flags.
  */
 export function buildMetaTools(opts: BuildMetaToolsOptions): PluginTool[] {
-  const { manifestRegistry, toolRegistry } = opts;
+  const { manifestRegistry, toolRegistry, toolAccess } = opts;
   return [
-    buildLoadCapabilityTool(manifestRegistry, toolRegistry),
-    buildListCapabilitiesTool(manifestRegistry),
+    buildLoadCapabilityTool(manifestRegistry, toolRegistry, toolAccess),
+    buildListCapabilitiesTool(manifestRegistry, toolAccess),
   ];
 }

package/src/core/middlewares/capability-gate.ts

@@ -1,10 +1,24 @@
+import { ToolMessage } from '@langchain/core/messages';
 import { type AgentMiddleware, createMiddleware } from 'langchain';
 import { z } from 'zod';
 import type { Logger, PluginManifest } from '../../plugin-api/types';
+import { describeRequirements, type CapabilityRequirement } from '../manifest';
 import { NOOP_LOGGER } from '../utils';
 
 type Visibility = NonNullable<PluginManifest['visibility']>;
 
+/** `response_metadata` key the gate sets on its refusals (never sent to a provider). */
+const REFUSED = 'capabilityGateRefused';
+
+/**
+ * A ToolMessage the gate produced instead of running the tool. The tool never
+ * ran, so it is not a failure: the repetition guard must let the same call
+ * through once the capability is loaded.
+ */
+export function isCapabilityGateRefusal(message: ToolMessage): boolean {
+  return message.response_metadata?.[REFUSED] === true;
+}
+
 export interface CapabilityGateMiddlewareOptions {
   /**
    * Tool name → contributing plugin name. Tools absent from this map
@@ -18,29 +32,81 @@ export interface CapabilityGateMiddlewareOptions {
    * middleware does not need access to the registries at runtime.
    */
   visibilityByToolName: Map<string, Visibility>;
+  /**
+   * Plugins the capability router preloaded for this turn. Their on-demand
+   * tools pass the gate as if loaded, without touching `state.loadedPlugins`.
+   */
+  preloadedPlugins?: ReadonlySet<string>;
+  /**
+   * Plugin name → the `manifest.requires` capabilities the user's delegation
+   * does not grant. Such a plugin's tools are hidden and refused whatever
+   * their visibility, loaded or preloaded.
+   */
+  unmetRequirements?: ReadonlyMap<string, readonly CapabilityRequirement[]>;
+  /**
+   * Tool names the turn withholds (`resolveTurnToolAccess`): admin tools the
+   * user's delegation does not grant, never bound. A call naming one is
+   * refused without saying what it is, and not as a load refusal: loading
+   * cannot make it available.
+   */
+  withheldToolNames?: ReadonlySet<string>;
   /** Optional logger; defaults to a no-op. */
   logger?: Logger;
 }
 
 /**
- * Gates on-demand plugin tools (and sub-agents-as-tools) per model call.
+ * Gates on-demand plugin tools (and sub-agents-as-tools) on both sides of
+ * the model.
  *
- * All plugin tools are bound to the agent at compile time. This middleware
- * runs on every model invocation: it reads `state.loadedPlugins` and trims
- * the request's `tools` array down to what the agent should actually see at
- * this point in the conversation.
+ * All plugin tools are bound to the agent at compile time. On every model
+ * invocation this middleware reads `state.loadedPlugins` and trims the
+ * request's `tools` array down to what the agent should see at this point
+ * in the conversation. Because they are all bound, the tool node would still
+ * run a call to a hidden tool — one named from an earlier thread, guessed,
+ * or planted by injected text — so every tool call is checked against the
+ * same rule before it runs, and a hidden one is answered with an error
+ * instead of executing.
  *
  * Why a middleware: `createAgent({ tools })` freezes the bound list, so
  * `load_capability` updating state mid-run would otherwise have no effect
  * until the next request rebuilt the agent. Filtering inside `wrapModelCall`
  * lets a load decision take effect on the very next LLM call.
+ *
+ * This is capability discovery, not authorization: any non-silent plugin can
+ * be loaded with `load_capability`. What the gate guarantees is that an
+ * on-demand tool runs only after that load (or the turn's preload) is
+ * visible in the thread.
  */
 export const createCapabilityGateMiddleware = (
   options: CapabilityGateMiddlewareOptions,
 ): AgentMiddleware => {
-  const { pluginByToolName, visibilityByToolName } = options;
+  const { pluginByToolName, visibilityByToolName, preloadedPlugins } = options;
   const logger = options.logger ?? NOOP_LOGGER;
 
+  /** What the user's authorization lacks for `toolName`'s plugin, or null. */
+  const unmetFor = (
+    toolName: string,
+  ): { plugin: string; missing: readonly CapabilityRequirement[] } | null => {
+    const plugin = pluginByToolName.get(toolName);
+    if (!plugin) return null;
+    const missing = options.unmetRequirements?.get(plugin);
+    return missing && missing.length > 0 ? { plugin, missing } : null;
+  };
+
+  /** The plugin that has to be loaded before `toolName` may be seen or run; null when it is open. */
+  const gatingPlugin = (
+    toolName: string,
+    loaded: ReadonlySet<string>,
+  ): string | null => {
+    const plugin = pluginByToolName.get(toolName);
+    if (!plugin) return null;
+    const viz = visibilityByToolName.get(toolName) ?? 'on-demand';
+    if (viz === 'always' || viz === 'silent') return null;
+    if (loaded.has(plugin) || preloadedPlugins?.has(plugin) === true)
+      return null;
+    return plugin;
+  };
+
   return createMiddleware({
     name: 'CapabilityGateMiddleware',
     stateSchema: z.object({
@@ -57,20 +123,72 @@ export const createCapabilityGateMiddleware = (
         // `unknown`. Narrow at runtime; unknown-named tools pass through.
         const name = typeof t.name === 'string' ? t.name : undefined;
         if (!name) return true;
-        const plugin = pluginByToolName.get(name);
-        if (!plugin) return true;
-        const viz = visibilityByToolName.get(name) ?? 'on-demand';
-        if (viz === 'always' || viz === 'silent') return true;
-        return loaded.has(plugin);
+        return (
+          options.withheldToolNames?.has(name) !== true &&
+          unmetFor(name) === null &&
+          gatingPlugin(name, loaded) === null
+        );
       });
 
       if (filtered.length !== request.tools.length) {
         logger.log(
-          `[CapabilityGateMiddleware] exposed ${filtered.length}/${request.tools.length} tools; loadedPlugins=${Array.from(loaded).join(',') || '∅'}`,
+          `[CapabilityGateMiddleware] exposed ${filtered.length}/${request.tools.length} tools; loadedPlugins=${Array.from(loaded).join(',') || '∅'}` +
+            (preloadedPlugins?.size
+              ? ` preloadedPlugins=${Array.from(preloadedPlugins).join(',')}`
+              : ''),
         );
       }
 
       return handler({ ...request, tools: filtered });
     },
+    // The state here is the one the tool node runs with, so a load made by
+    // an earlier step of this run counts; a `load_capability` issued in the
+    // same model response as the gated call does not (both run on the state
+    // from before either), and the model is told to call again.
+    wrapToolCall: (request, handler) => {
+      const name = request.toolCall.name;
+      if (options.withheldToolNames?.has(name)) {
+        logger.warn(
+          `[CapabilityGateMiddleware] refused a call to ${name}: an admin tool the user's delegation does not grant`,
+        );
+        return new ToolMessage({
+          content: `Tool "${name}" is not available in this conversation, so the call was not run.`,
+          tool_call_id: request.toolCall.id ?? '',
+          name,
+          status: 'error',
+        });
+      }
+      const unmet = unmetFor(name);
+      if (unmet) {
+        logger.warn(
+          `[CapabilityGateMiddleware] refused a call to ${name}: the user's authorization does not grant ${describeRequirements(unmet.missing)} ('${unmet.plugin}' requires it)`,
+        );
+        return new ToolMessage({
+          content:
+            `Tool "${name}" was not run: it belongs to the "${unmet.plugin}" capability, which requires ${describeRequirements(unmet.missing)}, and the user's authorization for this oracle does not grant it. ` +
+            'Tell the user; they can re-authorize the oracle with that permission and ask again.',
+          tool_call_id: request.toolCall.id ?? '',
+          name,
+          status: 'error',
+        });
+      }
+      const plugin = gatingPlugin(
+        name,
+        new Set<string>(request.state.loadedPlugins ?? []),
+      );
+      if (plugin === null) return handler(request);
+      logger.warn(
+        `[CapabilityGateMiddleware] refused a call to ${name}: capability '${plugin}' is not loaded in this thread`,
+      );
+      return new ToolMessage({
+        content:
+          `Tool "${name}" is not available: it belongs to the "${plugin}" capability, which is not loaded in this conversation, so the call was not run. ` +
+          `If the user's request needs it, call load_capability with names ["${plugin}"] first, then call the tool again.`,
+        tool_call_id: request.toolCall.id ?? '',
+        name,
+        status: 'error',
+        response_metadata: { [REFUSED]: true },
+      });
+    },
   });
 };

package/src/core/middlewares/context-guard.ts

@@ -14,7 +14,8 @@
  *      fail at the provider.
  *   3. **Overflow recovery.** When the provider rejects the request anyway,
  *      the limit it names is learned (the window is lowered for good), the
- *      request is pruned hard, and it is retried once.
+ *      request is pruned hard, and it is retried once — only when the prune
+ *      made it strictly smaller; an unchanged request is never sent twice.
  *
  * Token counts are chars/4 estimates; the thresholds leave the slack for it.
  */
@@ -26,7 +27,12 @@ import {
 import { convertToOpenAITool } from '@langchain/core/utils/function_calling';
 import { type AgentMiddleware, createMiddleware } from 'langchain';
 import type { Logger } from '../../plugin-api/types';
-import { estimateContentTokens, type ContextBudget } from '../context-budget';
+import {
+  estimateContentTokens,
+  messageContentTokens,
+  messageToolCallTokens,
+  type ContextBudget,
+} from '../context-budget';
 import { isContextOverflowError } from '../context-window';
 import { NOOP_LOGGER } from '../utils';
 import { cappedMetaOf } from './result-cap';
@@ -156,13 +162,52 @@ export function estimateRequestTokens(input: {
 }): number {
   let tokens = input.systemTokens + input.schemaTokens;
   for (const m of input.messages) {
-    tokens += estimateContentTokens(m.content) + 4;
+    tokens += messageContentTokens(m) + 4;
     if (AIMessage.isInstance(m) && m.tool_calls?.length)
-      tokens += estimateContentTokens(m.tool_calls);
+      tokens += messageToolCallTokens(m, m.tool_calls);
   }
   return tokens;
 }
 
+/**
+ * Tool-schema sizes, kept across turns. Every turn binds fresh tool objects,
+ * but a plugin's tool keeps its schema object for the life of the isolate,
+ * and what a tool sends is fixed by that schema, its name and its
+ * description: the size is kept per schema object, then per name and
+ * description. A tool without a schema object is sized per tool object.
+ */
+const schemaSizes = new WeakMap<object, Map<string, number>>();
+const entrySizes = new WeakMap<object, number>();
+
+function schemaTokensOf(tools: readonly unknown[]): number {
+  let total = 0;
+  for (const entry of tools) {
+    if (!entry || typeof entry !== 'object') continue;
+    const schema: unknown =
+      'schema' in entry ? Reflect.get(entry, 'schema') : undefined;
+    const sizes =
+      schema && typeof schema === 'object'
+        ? (schemaSizes.get(schema) ??
+          schemaSizes.set(schema, new Map()).get(schema))
+        : undefined;
+    const key = `${String(Reflect.get(entry, 'name'))}\n${String(Reflect.get(entry, 'description'))}`;
+    let n = sizes ? sizes.get(key) : entrySizes.get(entry);
+    if (n === undefined) {
+      try {
+        n = estimateContentTokens(
+          'schema' in entry ? convertToOpenAITool(entry as never) : entry,
+        );
+      } catch {
+        n = 0;
+      }
+      if (sizes) sizes.set(key, n);
+      else entrySizes.set(entry, n);
+    }
+    total += n;
+  }
+  return total;
+}
+
 export function createContextGuardMiddleware(
   options: ContextGuardOptions,
 ): AgentMiddleware {
@@ -177,26 +222,6 @@ export function createContextGuardMiddleware(
       );
     }
   };
-  const schemaTokensCache = new WeakMap<object, number>();
-  const schemaTokensOf = (tools: unknown[]): number => {
-    let total = 0;
-    for (const entry of tools) {
-      if (!entry || typeof entry !== 'object') continue;
-      let n = schemaTokensCache.get(entry);
-      if (n === undefined) {
-        try {
-          n = estimateContentTokens(
-            'schema' in entry ? convertToOpenAITool(entry as never) : entry,
-          );
-        } catch {
-          n = 0;
-        }
-        schemaTokensCache.set(entry, n);
-      }
-      total += n;
-    }
-    return total;
-  };
   return createMiddleware({
     name: 'ContextGuardMiddleware',
     wrapModelCall: async (request, handler) => {
@@ -254,7 +279,13 @@ export function createContextGuardMiddleware(
           kind: 'overflow-retry',
           ...(learned !== undefined ? { learnedWindow: learned } : {}),
         });
+        const before = tokens;
         shrink(PRUNE_HARD, 'overflow', 'after the provider overflow');
+        if (tokens >= before)
+          throw new ContextOverflowError(
+            "The conversation no longer fits the model's context window and nothing more could be trimmed. Start a new session.",
+            error,
+          );
         try {
           return await handler({ ...request, messages });
         } catch (retryError) {

package/src/core/middlewares/index.ts

@@ -2,8 +2,15 @@ export { createCapabilityGateMiddleware } from './capability-gate';
 export type { CapabilityGateMiddlewareOptions } from './capability-gate';
 export { createToolValidationMiddleware } from './tool-validation';
 export type { ToolValidationMiddlewareOptions } from './tool-validation';
-export { createToolRepetitionGuardMiddleware } from './tool-repetition-guard';
-export type { ToolRepetitionGuardMiddlewareOptions } from './tool-repetition-guard';
+export {
+  createToolRepetitionGuardMiddleware,
+  DEFAULT_REPETITION_CAPS,
+  repetitionCapsFromEnv,
+} from './tool-repetition-guard';
+export type {
+  RepetitionCaps,
+  ToolRepetitionGuardMiddlewareOptions,
+} from './tool-repetition-guard';
 export {
   createSummarizationMiddleware,
   isSummarizationMessage,
@@ -21,3 +28,14 @@ export { createPageContextMiddleware } from './page-context';
 export type { PageContextMiddlewareOptions } from './page-context';
 export { createSafetyGuardrailMiddleware } from './safety-guardrail';
 export type { SafetyGuardrailMiddlewareOptions } from './safety-guardrail';
+export {
+  createToolExecutionMiddleware,
+  isUncertainOutcome,
+  operationKey,
+  uncertainWriteToolResult,
+} from './tool-execution';
+export type {
+  ToolExecutionOptions,
+  WriteClaim,
+  WriteClaimStore,
+} from './tool-execution';