@ixo/oracle-runtime-workers 0.38.0 → 0.39.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ixo/oracle-runtime-workers",
-  "version": "0.38.0",
+  "version": "0.39.0",
   "description": "QiForge oracle runtime for Cloudflare Workers — Durable Object per user (SQLite in WASM over DO storage), Matrix E2EE gateway Durable Object, Hono HTTP/SSE shell.",
   "private": false,
   "publishConfig": {
@@ -67,8 +67,8 @@
     "protobufjs": "^7.6.5",
     "@ixo/topic-protocol": "1.0.0-rc.8",
     "survey-core": "2.3.11",
+    "@ixo/common": "1.8.0",
     "@ixo/ucan": "2.3.0",
-    "@ixo/common": "1.7.2",
     "@ixo/ixo-transaction": "0.2.0"
   },
   "devDependencies": {

package/src/channels/replies.ts

@@ -1,4 +1,5 @@
 import type { BaseMessage, MessageContent } from '@langchain/core/messages';
+import { TURN_GUIDE_NOTE_KWARG } from '../core/operating-guides';
 import {
   stripTurnTimeNote,
   TURN_TIME_NOTE_KWARG,
@@ -9,7 +10,7 @@ import type { ChannelFileNotice, ChannelReplyContext } from './contract';
  * `additional_kwargs` key holding the exact quoted-reply note a channel
  * message was sent with, so readers can take it off the stored content again
  * (see `userContent`). The note sits between the time note and what the
- * person typed: `time note \n\n reply note \n\n message`.
+ * person typed: `time note \n\n guide note \n\n reply note \n\n message`.
  */
 export const CHANNEL_REPLY_NOTE_KWARG = 'channel_reply_note';
 
@@ -84,8 +85,8 @@ export function isDeliveryNoticeMessage(message: BaseMessage): boolean {
 }
 
 /**
- * The content as the person sent it: without the runtime's time note,
- * without the quoted-reply note and without a delivery notice. Every reader
+ * The content as the person sent it: without the runtime's time and guide
+ * notes, without the quoted-reply note and without a delivery notice. Every reader
  * that treats a human message as the person's own words (the transcript,
  * memory indexing, the evidence a proposal is checked against) goes through
  * here, so quoted text or a gateway's notice is never taken for something
@@ -97,7 +98,10 @@ export function userContent(
 ): MessageContent {
   return stripTurnTimeNote(
     stripTurnTimeNote(
-      stripTurnTimeNote(content, kwargs?.[TURN_TIME_NOTE_KWARG]),
+      stripTurnTimeNote(
+        stripTurnTimeNote(content, kwargs?.[TURN_TIME_NOTE_KWARG]),
+        kwargs?.[TURN_GUIDE_NOTE_KWARG],
+      ),
       kwargs?.[CHANNEL_REPLY_NOTE_KWARG],
     ),
     kwargs?.[CHANNEL_DELIVERY_NOTICE_KWARG],

package/src/core/capability-expiry.ts

@@ -0,0 +1,62 @@
+/**
+ * How long an on-demand capability stays loaded on a thread.
+ *
+ * A loaded plugin's tools and operating guide go out with every model call,
+ * so a plugin the conversation has moved on from is paid for on every call.
+ * Taking it away changes the tool list and the system prompt, which costs a
+ * full cache miss on a warm thread: the request's whole prefix is read again
+ * at the uncached price, far more than the plugin's tools cost at the cached
+ * one. On a thread that has gone quiet long enough for the provider's cache
+ * to expire the miss has already happened, so the runtime only ever unloads
+ * a plugin on such a turn, and only one the last `maxIdleTurns` turns did not
+ * touch. The model can load it again: the capability gate's refusal says how.
+ *
+ * Use is read off the thread itself: a call to one of the plugin's tools, or
+ * a `load_capability` naming it. Nothing is stored, so a summary that
+ * condensed a plugin's last use makes it idle, which is what it is.
+ */
+import { AIMessage, type BaseMessage } from '@langchain/core/messages';
+import { z } from 'zod';
+import { LOAD_CAPABILITY_TOOL_NAME } from './meta-tools';
+import { turnOpenings } from './middlewares/turn-boundary';
+
+const loadArgs = z.object({ names: z.array(z.string()) });
+
+/** The plugins one model response touched. */
+function pluginsTouched(
+  message: AIMessage,
+  pluginOf: (toolName: string) => string | undefined,
+): string[] {
+  return (message.tool_calls ?? []).flatMap((call) => {
+    if (call.name === LOAD_CAPABILITY_TOOL_NAME) {
+      const args = loadArgs.safeParse(call.args);
+      return args.success ? args.data.names : [];
+    }
+    const plugin = pluginOf(call.name);
+    return plugin ? [plugin] : [];
+  });
+}
+
+/**
+ * Which of the `loaded` plugins no turn among the last `maxIdleTurns` of the
+ * thread touched. `messages` are the finished turns, the current one not yet
+ * among them; a thread with fewer turns than that unloads nothing.
+ */
+export function idlePlugins(input: {
+  messages: readonly BaseMessage[];
+  loaded: readonly string[];
+  pluginOf: (toolName: string) => string | undefined;
+  maxIdleTurns: number;
+}): string[] {
+  const { messages, loaded, pluginOf, maxIdleTurns } = input;
+  if (maxIdleTurns <= 0) return [];
+  const openings = turnOpenings(messages);
+  const recent = openings[openings.length - maxIdleTurns];
+  if (recent === undefined) return [];
+  const touched = new Set<string>();
+  for (const message of messages.slice(recent))
+    if (AIMessage.isInstance(message))
+      for (const plugin of pluginsTouched(message, pluginOf))
+        touched.add(plugin);
+  return loaded.filter((plugin) => !touched.has(plugin));
+}

package/src/core/capability-router.ts

@@ -1,29 +1,36 @@
 import {
   AmbiguousDecisionProviderError,
+  CAPABILITY_PRELOAD_BATCH_SIZE,
+  CAPABILITY_PRELOAD_WARM_THRESHOLD,
   CAPABILITY_ROUTER_MODES,
   CAPABILITY_ROUTE_DECISION_NAME,
   DecisionProviderUnavailableError,
-  capabilityRouteDecision,
-  decideCapabilityRoute,
+  capabilityPreloadDecision,
+  decideCapabilityPreload,
   toRoutableCapabilities,
+  type CapabilityPreloadVerdict,
   type CapabilityRouterMode,
+  type DecisionEvaluateOptions,
   type DecisionEvaluator,
   type DecisionTraceOptions,
   type RoutableCapability,
 } from '@ixo/common/ai/decisions';
-import type { Logger } from '../plugin-api/types';
-import { unmetRequirements } from './manifest';
+import type { Logger, PluginManifest } from '../plugin-api/types';
 import type { RegisteredManifest } from './registries';
 
 /**
- * Predicts, before the first model call of a turn, which on-demand plugin the
- * user's message needs and preloads that plugin's tools for the turn, so the
- * model does not spend a round trip on `load_capability`.
+ * Predicts, before the first model call of a turn, every plugin the user's
+ * message needs from what is left to load, so the model does not spend a
+ * round trip on `load_capability`. A plugin it misses is still one
+ * `load_capability` away.
  *
- * The preload is one-turn state only: it is admitted by the capability gate
- * and visible as loaded to tool handlers, but never written to the graph's
- * `loadedPlugins` channel. The router fails open — any evaluation failure
- * preloads nothing and the turn proceeds exactly as without a router.
+ * A preload is a normal load: the turn writes it to the graph's
+ * `loadedPlugins` channel and it stays until a cold turn unloads it, so the
+ * tool list changes once. It costs the cache miss a `load_capability` would,
+ * without the extra call. On a turn the provider's cache has lost anyway it
+ * costs no miss at all, which is why a warm turn asks for a higher score
+ * (`CAPABILITY_ROUTER_WARM_THRESHOLD`). The router fails open — any evaluation
+ * failure preloads nothing and the turn proceeds exactly as without a router.
  */
 export interface CapabilityRouterOptions {
   evaluator: DecisionEvaluator;
@@ -38,26 +45,23 @@ export interface CapabilityRouterOptions {
 
 export interface CapabilityRouteTurn {
   mode: CapabilityRouterMode;
-  /** Every registered manifest; the router picks the routable candidates. */
-  manifests: readonly RegisteredManifest[];
-  /** Plugins the thread has already loaded (the checkpointed channel). */
-  loaded: ReadonlySet<string>;
   /**
-   * Plugins the user's delegation leaves with nothing to use (all of their
-   * tools admin-plane and not granted): never offered to the router. A
-   * function is called only when the router actually evaluates (not when
-   * it is off, or the message is empty), so the host does not compute the
-   * set for nothing.
+   * What a `load_capability` could load right now (`createMainAgent` works
+   * this out from the turn's own tools): the plugins with an on-demand tool
+   * the thread has not loaded, `always` ones with `onDemandTools` included,
+   * that the user's delegation may use.
    */
-  hidden?: ReadonlySet<string> | (() => Promise<ReadonlySet<string>>);
-  /**
-   * The user's delegation, as `ctx.ucan.hasCapability`: a plugin whose
-   * `manifest.requires` it does not grant is never offered (the gate would
-   * refuse every one of its tools). Omitted, `requires` is not checked.
-   */
-  hasCapability?: (resource: string, action: string) => boolean;
+  candidates: readonly RegisteredManifest[];
+  /** The score a preload needs; the calibration profile's when omitted. */
+  threshold?: number;
   /** The user's message text for this turn. */
   text: string;
+  /**
+   * The thread's latest visible turns, oldest first, so a follow-up such as
+   * "send half to Bob" can be routed. Called only when the router evaluates;
+   * when it fails the router evaluates the message alone.
+   */
+  recentTurns?: () => Promise<readonly string[]>;
   requestId: string;
   /** The turn's abort signal; only an awaited (`on`) evaluation is bound to it. */
   signal?: AbortSignal;
@@ -85,35 +89,43 @@ export function capabilityRouterMode(value: unknown): CapabilityRouterMode {
   return CAPABILITY_ROUTER_MODES.find((mode) => mode === value) ?? 'off';
 }
 
+/** The score a preload needs this turn: the operator's, else the default. */
+export function preloadThreshold(
+  cold: boolean,
+  env: {
+    CAPABILITY_ROUTER_COLD_THRESHOLD?: unknown;
+    CAPABILITY_ROUTER_WARM_THRESHOLD?: unknown;
+  },
+): { threshold?: number } {
+  const set = cold
+    ? env.CAPABILITY_ROUTER_COLD_THRESHOLD
+    : env.CAPABILITY_ROUTER_WARM_THRESHOLD;
+  if (typeof set === 'number') return { threshold: set };
+  return cold ? {} : { threshold: CAPABILITY_PRELOAD_WARM_THRESHOLD };
+}
+
 /**
- * The manifests the router may choose from: effectively on-demand plugins the
- * thread has not loaded yet. `always` plugins are already bound and `silent`
- * ones are never surfaced, so predicting them is pointless; a `hidden` one
- * (no tool the user's delegation reaches), or one whose `requires` the
- * delegation (`hasCapability`) does not grant, is not even named to the
- * router.
+ * What the router reads about a plugin: its summary and the `whenToUse` lines
+ * the manifest already carries. The summary alone often leaves out what a
+ * plugin does ("retire tokens", "cancel a reminder"), and a yes/no question
+ * then scores far below the preload threshold.
  */
+function routingSummary(manifest: PluginManifest): string {
+  return manifest.whenToUse.length > 0
+    ? `${manifest.summary} Use when: ${manifest.whenToUse.join(' ')}`
+    : manifest.summary;
+}
+
+/** The Decision's view of the candidates. */
 export function routableCandidates(
-  manifests: readonly RegisteredManifest[],
-  loaded: ReadonlySet<string>,
-  hidden: ReadonlySet<string> = NOTHING,
-  hasCapability?: (resource: string, action: string) => boolean,
+  candidates: readonly RegisteredManifest[],
 ): RoutableCapability[] {
   return toRoutableCapabilities(
-    manifests
-      .filter(
-        ({ pluginName, manifest }) =>
-          (manifest.visibility ?? 'on-demand') === 'on-demand' &&
-          !loaded.has(pluginName) &&
-          !hidden.has(pluginName) &&
-          (hasCapability === undefined ||
-            unmetRequirements(manifest, hasCapability).length === 0),
-      )
-      .map(({ pluginName, manifest }) => ({
-        name: pluginName,
-        title: manifest.title,
-        summary: manifest.summary,
-      })),
+    candidates.map(({ pluginName, manifest }) => ({
+      name: pluginName,
+      title: manifest.title,
+      summary: routingSummary(manifest),
+    })),
   );
 }
 
@@ -144,6 +156,23 @@ function list(names: readonly string[]): string {
   return `[${names.join(', ')}]`;
 }
 
+/** The likeliest candidates, for refitting the threshold from real traffic. */
+function topScores(verdict: CapabilityPreloadVerdict): string {
+  return verdict.scores
+    .slice(0, 3)
+    .map(({ name, probability }) => `${name}:${probability.toFixed(2)}`)
+    .join(',');
+}
+
+/** Splits candidates into lists one Decision request can carry. */
+function batches<T>(items: readonly T[], size: number): T[][] {
+  const chunks: T[][] = [];
+  for (let start = 0; start < items.length; start += size) {
+    chunks.push(items.slice(start, start + size));
+  }
+  return chunks;
+}
+
 export function createCapabilityRouter(
   options: CapabilityRouterOptions,
 ): CapabilityRouter {
@@ -183,47 +212,51 @@ export function createCapabilityRouter(
 
   return async (turn) => {
     if (turn.mode === 'off') return NOTHING;
+    // No score reaches it: nothing to spend a Decision on.
+    if ((turn.threshold ?? 0) > 1) return NOTHING;
     const text = turn.text.trim();
     if (!text) return NOTHING;
-    let hidden: ReadonlySet<string> | undefined;
-    try {
-      hidden =
-        typeof turn.hidden === 'function' ? await turn.hidden() : turn.hidden;
-    } catch (error) {
-      // Fail open like any other router failure: no preload this turn.
-      logger.warn(
-        `[capability-router] request=${turn.requestId} mode=${turn.mode} status=fallback reason=${errorName(error)} (hidden plugins unavailable)`,
-      );
-      return NOTHING;
-    }
-    const capabilities = routableCandidates(
-      turn.manifests,
-      turn.loaded,
-      hidden,
-      turn.hasCapability,
-    );
+    const capabilities = routableCandidates(turn.candidates);
     if (capabilities.length === 0) return NOTHING;
 
-    // The turn is prepared from a checkpoint read without its messages, so
-    // the router sees the current message only; `recentTurns` stays empty.
-    const input = { text, recentTurns: [], capabilities };
     const { requestId } = turn;
+    let recentTurns: string[] = [];
+    const evaluateAll = async (options?: DecisionEvaluateOptions) => {
+      try {
+        recentTurns = [...((await turn.recentTurns?.()) ?? [])];
+      } catch (error) {
+        logger.warn(
+          `[capability-router] request=${requestId} mode=${turn.mode} status=degraded reason=${errorName(error)} (recent turns unavailable)`,
+        );
+      }
+      return Promise.all(
+        batches(capabilities, CAPABILITY_PRELOAD_BATCH_SIZE).map((batch) =>
+          evaluator.evaluate(
+            capabilityPreloadDecision,
+            { text, recentTurns, capabilities: batch },
+            options,
+          ),
+        ),
+      );
+    };
 
     if (turn.mode === 'shadow') {
       const started = now();
       background(
-        evaluator
-          .evaluate(capabilityRouteDecision, input, turn.trace)
-          .then((evaluation) => {
-            const verdict = decideCapabilityRoute(evaluation, capabilities);
+        evaluateAll(turn.trace)
+          .then((evaluations) => {
+            const verdict = decideCapabilityPreload(
+              evaluations,
+              capabilities,
+              turn.threshold,
+            );
             logger.log(
               `[capability-router-shadow] request=${requestId} status=ok ` +
-                `needsCapability=${verdict.needsCapability.toFixed(2)} ` +
-                `capability=${verdict.capability ?? '-'} ` +
-                `capabilityConfidence=${verdict.capabilityConfidence?.toFixed(2) ?? '-'} ` +
-                `wouldPreload=${list(verdict.preload)} reason=${verdict.reason} ` +
+                `top=${topScores(verdict)} ` +
+                `wouldPreload=${list(verdict.preload)} ` +
+                `threshold=${turn.threshold ?? 'profile'} ` +
                 `calibrationProfile=${verdict.calibrationProfileRef ?? '-'} ` +
-                `latencyMs=${now() - started} provider=${evaluation.provider} model=${evaluation.model}`,
+                `latencyMs=${now() - started} provider=${evaluations[0]?.provider} model=${evaluations[0]?.model}`,
             );
             turn.onShadowVerdict?.(verdict.preload);
           })
@@ -240,25 +273,23 @@ export function createCapabilityRouter(
       return NOTHING;
     }
 
+    const started = now();
     try {
-      const evaluation = await evaluator.evaluate(
-        capabilityRouteDecision,
-        input,
-        {
-          ...turn.trace,
-          ...(turn.signal && { signal: turn.signal }),
-        },
+      const evaluations = await evaluateAll({
+        ...turn.trace,
+        ...(turn.signal && { signal: turn.signal }),
+      });
+      const verdict = decideCapabilityPreload(
+        evaluations,
+        capabilities,
+        turn.threshold,
       );
-      const verdict = decideCapabilityRoute(evaluation, capabilities);
-      if (verdict.preload.length === 0) {
-        logger.debug?.(
-          `[capability-router] request=${requestId} mode=on status=none reason=${verdict.reason} candidates=${capabilities.length}`,
-        );
-        return NOTHING;
-      }
       logger.log(
-        `[capability-router] request=${requestId} preloaded=${list(verdict.preload)} candidates=${capabilities.length}`,
+        `[capability-router] request=${requestId} mode=on status=${verdict.preload.length > 0 ? 'ok' : 'none'} ` +
+          `preloaded=${list(verdict.preload)} top=${topScores(verdict)} threshold=${turn.threshold ?? 'profile'} ` +
+          `candidates=${capabilities.length} recentTurns=${recentTurns.length} latencyMs=${now() - started}`,
       );
+      if (verdict.preload.length === 0) return NOTHING;
       return new Set(verdict.preload);
     } catch (error) {
       if (unavailable(error)) {

package/src/core/context-budget.ts

@@ -12,12 +12,23 @@
  *   - `pruneAtTokens`      — above this, old tool results are demoted to
  *                            one-liners in the request (no model call, no
  *                            state change) before the model sees them;
+ *   - `staleResultTurns`   — on a turn that opens after `cacheColdMs` of
+ *                            quiet, tool results older than this many turns
+ *                            leave the request (`read_result` reads them
+ *                            back). Whatever the window: this is about what
+ *                            a call costs, not about what fits;
  *   - `resultCapChars`     — a tool result larger than this is stored whole
  *                            and the model sees head + tail + a handle;
  *   - `requestCapTokens`   — a request that is still larger than this after
  *                            pruning is refused instead of sent to fail;
  *   - `outputReserveTokens`— the room left for the reply.
  *
+ * A large window says nothing about what a request should cost, so the
+ * fractions are bounded in tokens too (`summarizeMaxTokens`, `pruneMaxTokens`,
+ * `resultCapMaxChars`): a million-token window would otherwise never condense
+ * a thread that long ago stopped being worth re-sending, and would pass the
+ * 272k-token point where providers such as OpenAI double the price.
+ *
  * Token counts are chars/4 estimates (`estimateTokensApprox`), never billing.
  */
 import type { Logger } from '../plugin-api/types';
@@ -30,12 +41,34 @@ export const CHARS_PER_TOKEN = 4;
 export interface ContextKnobs {
   /** Fraction of the window at which the history is summarized (default 0.6). */
   summarizeFraction: number;
+  /** Ceiling on the summarize threshold in tokens, whatever the window (default 200,000). */
+  summarizeMaxTokens: number;
   /** Fraction of the window above which old tool results are pruned per request (default 0.35). */
   pruneFraction: number;
+  /** Ceiling on the prune threshold in tokens, whatever the window (default 100,000). */
+  pruneMaxTokens: number;
+  /**
+   * Finished turns whose tool results stay whole when a cold turn trims the
+   * older ones out of the request (default 2; 0 never trims).
+   */
+  staleResultTurns: number;
+  /**
+   * Quiet time after which a turn counts as cold: the provider's prompt
+   * cache is gone, so changing the prefix costs nothing. Default 2,100,000
+   * (35 minutes): on `gpt-5.6-luna`, Bedrock and OpenAI routes alike, a prefix
+   * left idle for 20 minutes still hit and one left for 35 missed. 0 makes
+   * every turn cold.
+   */
+  cacheColdMs: number;
+  /**
+   * Turns an on-demand capability stays loaded without being used (default
+   * 3). It is unloaded on the first cold turn after that; 0 never unloads.
+   */
+  pluginIdleTurns: number;
   /** Fraction of the window one tool result may occupy before it is capped (default 0.12). */
   resultCapFraction: number;
   /**
-   * Ceiling on the result cap in chars (default 200,000 ≈ 50k tokens): a
+   * Ceiling on the result cap in chars (default 64,000 ≈ 16k tokens): a
    * million-token window does not make a half-megabyte tool result a good
    * idea — the rest stays reachable through `read_result`.
    */
@@ -52,9 +85,14 @@ export interface ContextKnobs {
 
 export const DEFAULT_CONTEXT_KNOBS: ContextKnobs = {
   summarizeFraction: 0.6,
+  summarizeMaxTokens: 200_000,
   pruneFraction: 0.35,
+  pruneMaxTokens: 100_000,
+  staleResultTurns: 2,
+  cacheColdMs: 2_100_000,
+  pluginIdleTurns: 3,
   resultCapFraction: 0.12,
-  resultCapMaxChars: 200_000,
+  resultCapMaxChars: 64_000,
   requestFraction: 0.95,
   outputReserveTokens: 8_000,
   keepMessages: 10,
@@ -66,6 +104,9 @@ export interface ContextBudget {
   origin: ContextWindowResolution['origin'];
   summarizeAtTokens: number;
   pruneAtTokens: number;
+  staleResultTurns: number;
+  cacheColdMs: number;
+  pluginIdleTurns: number;
   resultCapChars: number;
   requestCapTokens: number;
   outputReserveTokens: number;
@@ -118,10 +159,37 @@ export function contextKnobs(
       'CONTEXT_SUMMARIZE_FRACTION',
       DEFAULT_CONTEXT_KNOBS.summarizeFraction,
     ),
+    summarizeMaxTokens:
+      int(
+        'CONTEXT_SUMMARIZE_MAX_TOKENS',
+        DEFAULT_CONTEXT_KNOBS.summarizeMaxTokens,
+        1_000,
+      ) ?? DEFAULT_CONTEXT_KNOBS.summarizeMaxTokens,
     pruneFraction: fraction(
       'CONTEXT_PRUNE_FRACTION',
       DEFAULT_CONTEXT_KNOBS.pruneFraction,
     ),
+    pruneMaxTokens:
+      int(
+        'CONTEXT_PRUNE_MAX_TOKENS',
+        DEFAULT_CONTEXT_KNOBS.pruneMaxTokens,
+        1_000,
+      ) ?? DEFAULT_CONTEXT_KNOBS.pruneMaxTokens,
+    staleResultTurns:
+      int(
+        'CONTEXT_STALE_RESULT_TURNS',
+        DEFAULT_CONTEXT_KNOBS.staleResultTurns,
+        0,
+      ) ?? DEFAULT_CONTEXT_KNOBS.staleResultTurns,
+    cacheColdMs:
+      int('CONTEXT_CACHE_COLD_MS', DEFAULT_CONTEXT_KNOBS.cacheColdMs, 0) ??
+      DEFAULT_CONTEXT_KNOBS.cacheColdMs,
+    pluginIdleTurns:
+      int(
+        'CONTEXT_PLUGIN_IDLE_TURNS',
+        DEFAULT_CONTEXT_KNOBS.pluginIdleTurns,
+        0,
+      ) ?? DEFAULT_CONTEXT_KNOBS.pluginIdleTurns,
     resultCapFraction: fraction(
       'CONTEXT_RESULT_CAP_FRACTION',
       DEFAULT_CONTEXT_KNOBS.resultCapFraction,
@@ -199,11 +267,13 @@ export function contextBudgetFor(
   );
   const summarizeAtTokens = Math.min(
     Math.floor(window * knobs.summarizeFraction),
+    knobs.summarizeMaxTokens,
     requestCapTokens,
     summaryInputTokens,
   );
   const pruneAtTokens = Math.min(
     Math.floor(window * knobs.pruneFraction),
+    knobs.pruneMaxTokens,
     summarizeAtTokens,
   );
   return {
@@ -212,6 +282,9 @@ export function contextBudgetFor(
     origin: resolution.origin,
     summarizeAtTokens,
     pruneAtTokens,
+    staleResultTurns: knobs.staleResultTurns,
+    cacheColdMs: knobs.cacheColdMs,
+    pluginIdleTurns: knobs.pluginIdleTurns,
     resultCapChars: Math.min(
       Math.floor(window * knobs.resultCapFraction) * CHARS_PER_TOKEN,
       knobs.resultCapMaxChars,
@@ -226,11 +299,50 @@ export function contextBudgetFor(
   };
 }
 
-/** chars/4 over a message's content, whatever its shape. */
+/**
+ * What one image block costs the model, whatever its byte size. Providers
+ * bill an image by its pixels, not by its base64: every one the runtime
+ * sends is scaled to a 1568 px long edge by the provider (or before, by the
+ * `IMAGES` binding), which is at most ~3,300 tokens on the costliest
+ * provider formula (width × height / 750). Counting the base64 at chars/4
+ * instead made one resized phone photo look like ~128k tokens, enough for
+ * the context guard to refuse the turn on a model with a smaller window.
+ */
+export const IMAGE_BLOCK_TOKENS = 3_300;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * An image content block in any of the shapes a message carries: the
+ * LangChain data block the attachments build (`type: 'image'` with `data`
+ * or `url`) or the OpenAI chat shape (`type: 'image_url'`). File blocks are
+ * not images: a document's cost does follow its size, and native documents
+ * are kept small (`NATIVE_DOCUMENT_MAX_BYTES`).
+ */
+function isImageBlock(block: unknown): boolean {
+  return (
+    isRecord(block) && (block.type === 'image' || block.type === 'image_url')
+  );
+}
+
+/**
+ * chars/4 over a message's content, whatever its shape; each image block
+ * counts {@link IMAGE_BLOCK_TOKENS} instead of its base64.
+ */
 export function estimateContentTokens(content: unknown): number {
   if (typeof content === 'string') return estimateTokensApprox(content);
   if (content == null) return 0;
   try {
+    if (Array.isArray(content) && content.some(isImageBlock)) {
+      const images = content.filter(isImageBlock).length;
+      const rest = content.filter((block) => !isImageBlock(block));
+      return (
+        images * IMAGE_BLOCK_TOKENS +
+        (rest.length ? estimateTokensApprox(JSON.stringify(rest)) : 0)
+      );
+    }
     return estimateTokensApprox(JSON.stringify(content));
   } catch {
     return 0;
@@ -282,5 +394,5 @@ export function messageToolCallTokens(
 }
 
 export function describeBudget(b: ContextBudget): string {
-  return `model=${b.model} window=${b.windowTokens} (${b.origin}) summarizeAt=${b.summarizeAtTokens} pruneAt=${b.pruneAtTokens} resultCap=${b.resultCapChars}c requestCap=${b.requestCapTokens} reserve=${b.outputReserveTokens} summaryInput=${b.summaryInputTokens}`;
+  return `model=${b.model} window=${b.windowTokens} (${b.origin}) summarizeAt=${b.summarizeAtTokens} pruneAt=${b.pruneAtTokens} staleTurns=${b.staleResultTurns} coldMs=${b.cacheColdMs} pluginIdle=${b.pluginIdleTurns} resultCap=${b.resultCapChars}c requestCap=${b.requestCapTokens} reserve=${b.outputReserveTokens} summaryInput=${b.summaryInputTokens}`;
 }