@ixo/oracle-runtime-workers 0.38.0 → 0.40.1

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

@@ -1,18 +1,30 @@
 /**
  * Keeps every model request inside the model's window.
  *
- * Three layers, all on the request only (graph state and the transcript are
+ * Four layers, all on the request only (graph state and the transcript are
  * never rewritten here):
  *
- *   1. **Pressure pruning.** Above `pruneAtTokens` (35% of the window), tool
- *      results outside the kept tail are demoted to one-line placeholders
- *      (a capped result keeps its `read_result` handle) and results whose
- *      text is identical to a later one are replaced by a back-reference.
- *      No model call, no storage — Hermes' deterministic passes.
- *   2. **The hard cap.** A request still above `requestCapTokens` after a
+ *   1. **Stale results.** On a turn that opens after `cacheColdMs` of quiet,
+ *      tool results older than the last `staleResultTurns` finished turns
+ *      become one-line stubs naming how to read them back. Rewriting an old
+ *      message costs a cache miss on every byte after it, and on some routes
+ *      on the whole request, so the line only moves when the provider's
+ *      cache has expired anyway: between two cold turns it stays put and the
+ *      request keeps its prefix, call after call. The line is computed from
+ *      the messages alone, so a resumed attempt draws the same one.
+ *   2. **Pressure pruning.** Above `pruneAtTokens`, tool results outside the
+ *      kept tail are demoted to one-line placeholders (a capped result keeps
+ *      its `read_result` handle) and results whose text is identical to a
+ *      later one are replaced by a back-reference. No model call, no
+ *      storage — Hermes' deterministic passes. The tail moves with every
+ *      message, so past this threshold the cache is given up for size.
+ *
+ * Neither of the first two touches the load result of a plugin that is still
+ * loaded: it is how the model knows the plugin's rules (`operating-guides.ts`).
+ *   3. **The hard cap.** A request still above `requestCapTokens` after a
  *      harder prune is refused with a clear error instead of being sent to
  *      fail at the provider.
- *   3. **Overflow recovery.** When the provider rejects the request anyway,
+ *   4. **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 — only when the prune
  *      made it strictly smaller; an unchanged request is never sent twice.
@@ -34,8 +46,10 @@ import {
   type ContextBudget,
 } from '../context-budget';
 import { isContextOverflowError } from '../context-window';
+import { usageCarriedBy } from '../operating-guides';
 import { NOOP_LOGGER } from '../utils';
 import { cappedMetaOf } from './result-cap';
+import { turnOpenings } from './turn-boundary';
 
 export class ContextOverflowError extends Error {
   readonly retryable = false;
@@ -57,7 +71,7 @@ export class ContextOverflowError extends Error {
 export type ContextGuardEvent =
   | {
       kind: 'prune';
-      stage: 'soft' | 'hard' | 'overflow';
+      stage: 'stale' | 'soft' | 'hard' | 'overflow';
       pruned: number;
       beforeTokens: number;
       afterTokens: number;
@@ -74,6 +88,11 @@ export interface ContextGuardOptions {
   onOverflow?: (error: unknown) => Promise<number | undefined>;
   /** Observes every prune, overflow retry and refusal (never throws into the turn). */
   onEvent?: (event: ContextGuardEvent) => void;
+  /**
+   * The longest chunk `read_result` returns, when the tool is bound this
+   * turn: a stale-result stub then says how to read the result back.
+   */
+  readResultChars?: number;
   logger?: Logger;
 }
 
@@ -98,15 +117,10 @@ function textOf(content: unknown): string {
 
 function placeholder(
   message: ToolMessage,
-  text: string,
-  reason: 'pruned' | 'duplicate',
+  reason: 'pruned' | 'duplicate' | 'stale',
+  body: string,
 ): ToolMessage {
   const name = message.name ?? 'tool';
-  const meta = cappedMetaOf(message);
-  const body =
-    reason === 'duplicate'
-      ? `[${name} result: identical to a later ${name} result, omitted]`
-      : `[${name} result (${text.length} characters) pruned from context${meta?.id ? `; the full result is saved as ${meta.id} — read_result({ id: "${meta.id}" }) reads it` : ''}]`;
   return new ToolMessage({
     ...(message.id ? { id: message.id } : {}),
     tool_call_id: message.tool_call_id,
@@ -117,6 +131,79 @@ function placeholder(
   });
 }
 
+function prunedBody(message: ToolMessage, text: string): string {
+  const name = message.name ?? 'tool';
+  const meta = cappedMetaOf(message);
+  return `[${name} result (${text.length} characters) pruned from context${meta?.id ? `; the full result is saved as ${meta.id} — read_result({ id: "${meta.id}" }) reads it` : ''}]`;
+}
+
+/** When the message that opens a turn was sent; `NaN` for one that does not say. */
+function sentAt(message: BaseMessage | undefined): number {
+  const timestamp = message?.additional_kwargs?.timestamp;
+  return typeof timestamp === 'string' ? Date.parse(timestamp) : Number.NaN;
+}
+
+/**
+ * Index before which tool results are stale: the start of the turns kept
+ * whole on the latest cold turn. 0 when no cold turn has that many turns
+ * behind it. A turn is cold when it opens at least `coldGapMs` after the one
+ * before it. Pure over the messages: until the next cold turn every call
+ * finds the same index, so the request's prefix does not change.
+ */
+export function staleResultCutoff(
+  messages: readonly BaseMessage[],
+  keepTurns: number,
+  coldGapMs: number,
+): number {
+  if (keepTurns <= 0) return 0;
+  const openings = turnOpenings(messages);
+  for (let turn = openings.length - 1; turn >= Math.max(keepTurns, 1); turn--) {
+    const opening = openings[turn];
+    const previous = openings[turn - 1];
+    if (opening === undefined || previous === undefined) continue;
+    if (sentAt(messages[opening]) - sentAt(messages[previous]) >= coldGapMs)
+      return openings[turn - keepTurns] ?? 0;
+  }
+  return 0;
+}
+
+/**
+ * Tool results before `cutoff` → stubs. Pure: new message objects with the
+ * same ids and the same text on every call, the input untouched.
+ */
+export function trimStaleResults(
+  messages: BaseMessage[],
+  cutoff: number,
+  options: {
+    demoteMinChars: number;
+    readResultChars?: number;
+    keep?: (message: ToolMessage) => boolean;
+  },
+): { messages: BaseMessage[]; pruned: number } {
+  if (cutoff <= 0) return { messages, pruned: 0 };
+  const out = [...messages];
+  let pruned = 0;
+  for (let i = 0; i < cutoff; i += 1) {
+    const m = messages[i];
+    if (!m || !ToolMessage.isInstance(m) || options.keep?.(m)) continue;
+    const text = textOf(m.content);
+    if (text.length <= options.demoteMinChars) continue;
+    const name = m.name ?? 'tool';
+    const id = cappedMetaOf(m)?.id ?? m.tool_call_id;
+    const how =
+      options.readResultChars === undefined
+        ? 'call the tool again if you need it'
+        : `read_result({ id: "${id}", length: ${options.readResultChars} }) reads it back`;
+    out[i] = placeholder(
+      m,
+      'stale',
+      `[${name} result from an earlier turn (${text.length} characters) removed from context; ${how}]`,
+    );
+    pruned += 1;
+  }
+  return { messages: out, pruned };
+}
+
 /**
  * Old tool results → one-liners; duplicates → back-references. The last
  * `keepTail` messages are returned as they are. Pure: new message objects
@@ -125,6 +212,7 @@ function placeholder(
 export function pruneToolResults(
   messages: BaseMessage[],
   options: PruneOptions,
+  keep?: (message: ToolMessage) => boolean,
 ): { messages: BaseMessage[]; pruned: number } {
   const cutoff = Math.max(0, messages.length - options.keepTail);
   const out = [...messages];
@@ -134,20 +222,25 @@ export function pruneToolResults(
   const seenLater = new Set<string>();
   for (let i = messages.length - 1; i >= 0; i -= 1) {
     const m = messages[i]!;
-    if (!ToolMessage.isInstance(m)) continue;
+    if (!ToolMessage.isInstance(m) || keep?.(m)) continue;
     const text = textOf(m.content);
     if (i >= cutoff) {
       if (text.length >= 40) seenLater.add(text);
       continue;
     }
     if (text.length >= 40 && seenLater.has(text)) {
-      out[i] = placeholder(m, text, 'duplicate');
+      const name = m.name ?? 'tool';
+      out[i] = placeholder(
+        m,
+        'duplicate',
+        `[${name} result: identical to a later ${name} result, omitted]`,
+      );
       pruned += 1;
       continue;
     }
     if (text.length >= 40) seenLater.add(text);
     if (text.length > options.demoteMinChars) {
-      out[i] = placeholder(m, text, 'pruned');
+      out[i] = placeholder(m, 'pruned', prunedBody(m, text));
       pruned += 1;
     }
   }
@@ -213,6 +306,8 @@ export function createContextGuardMiddleware(
 ): AgentMiddleware {
   const logger = options.logger ?? NOOP_LOGGER;
   const { budget } = options;
+  // The guard lives for one turn and the stale line for many calls: one event.
+  let staleReported = false;
   const emit = (event: ContextGuardEvent): void => {
     try {
       options.onEvent?.(event);
@@ -231,15 +326,53 @@ export function createContextGuardMiddleware(
       const schemaTokens = schemaTokensOf(request.tools ?? []);
       const size = (messages: BaseMessage[]) =>
         estimateRequestTokens({ systemTokens, schemaTokens, messages });
-      let messages = request.messages;
+      const keep = (message: ToolMessage): boolean => {
+        const carried = usageCarriedBy(message);
+        if (carried.length === 0) return false;
+        const loaded: unknown = request.state.loadedPlugins;
+        return (
+          Array.isArray(loaded) &&
+          carried.some((plugin) => loaded.includes(plugin))
+        );
+      };
+      const stale = trimStaleResults(
+        request.messages,
+        staleResultCutoff(
+          request.messages,
+          budget.staleResultTurns,
+          budget.cacheColdMs,
+        ),
+        {
+          demoteMinChars: PRUNE_SOFT.demoteMinChars,
+          keep,
+          ...(options.readResultChars !== undefined
+            ? { readResultChars: options.readResultChars }
+            : {}),
+        },
+      );
+      let messages = stale.messages;
       let tokens = size(messages);
+      if (stale.pruned > 0 && !staleReported) {
+        staleReported = true;
+        const before = size(request.messages);
+        logger.log(
+          `[context] stale results: trimmed ${stale.pruned} tool result(s), ~${before} → ~${tokens} tokens`,
+        );
+        emit({
+          kind: 'prune',
+          stage: 'stale',
+          pruned: stale.pruned,
+          beforeTokens: before,
+          afterTokens: tokens,
+        });
+      }
       const shrink = (
         opts: PruneOptions,
         stage: 'soft' | 'hard' | 'overflow',
         why: string,
       ): void => {
         const before = tokens;
-        const result = pruneToolResults(messages, opts);
+        const result = pruneToolResults(messages, opts, keep);
         messages = result.messages;
         tokens = size(messages);
         if (result.pruned > 0) {

package/src/core/middlewares/result-cap.ts

@@ -128,7 +128,7 @@ export function truncateHeadTail(
   return `${text.slice(0, head)}\n\n… [${text.length - head - tail} characters omitted] …\n\n${text.slice(text.length - tail)}${capFooter(meta, head, tail)}`;
 }
 
-function contentToText(content: unknown): string {
+export function contentToText(content: unknown): string {
   if (typeof content === 'string') return content;
   try {
     return JSON.stringify(content) ?? '';

package/src/core/middlewares/summarization.ts

@@ -7,6 +7,7 @@ import {
 } from '@langchain/core/messages';
 import { type AgentMiddleware, summarizationMiddleware } from 'langchain';
 import type { Logger } from '../../plugin-api/types';
+import { usageCarriedBy } from '../operating-guides';
 import type { TurnBudget } from '../turn-budget';
 import {
   carriedCallsOfTurn,
@@ -273,6 +274,14 @@ export const createSummarizationMiddleware = (
       options.logger?.log(
         `[summarization] condensed the history: ${state.messages.length} messages → a summary + ${messages.length - 2} kept`,
       );
+      // A plugin's usage goes with the messages that carried it, and the next
+      // turn sends it again (operating-guides.ts).
+      return {
+        ...update,
+        capabilityUsage: {
+          replace: messages.filter(isBaseMessageLike).flatMap(usageCarriedBy),
+        },
+      };
     }
     return update;
   };

package/src/core/middlewares/tool-marks.ts

@@ -30,6 +30,7 @@ import {
   SystemMessage,
   ToolMessage,
 } from '@langchain/core/messages';
+import { Command } from '@langchain/langgraph';
 import { type AgentMiddleware, createMiddleware } from 'langchain';
 import type { ToolEffect, ToolMark } from '../../do/run-store';
 import type { Logger } from '../../plugin-api/types';
@@ -155,10 +156,18 @@ export function toolEffectOf(tool: {
   return startsWithReadVerb(bare) ? 'read' : 'write';
 }
 
-/** Whether a tool call's output is an error result (`ToolMessage` status `error`). */
+/**
+ * Whether a tool call's output is an error result: a `ToolMessage` with status
+ * `error`, alone or inside a graph command's update (the capability gate's
+ * refusal, which also loads the capability).
+ */
 export function isErrorResult(output: unknown): boolean {
   if (ToolMessage.isInstance(output)) return output.status === 'error';
-  return false;
+  if (!(output instanceof Command)) return false;
+  const { update } = output;
+  if (!update || Array.isArray(update) || !('messages' in update)) return false;
+  const { messages } = update;
+  return Array.isArray(messages) && messages.some(isErrorResult);
 }
 
 export function createToolMarksMiddleware(

package/src/core/middlewares/tool-repetition-guard.ts

@@ -20,6 +20,28 @@ export interface RepetitionCaps {
 
 export const DEFAULT_REPETITION_CAPS: RepetitionCaps = { reads: 5, writes: 1 };
 
+/**
+ * Tools that only find other tools; a model alternating between them never trips the identical-call cap.
+ * `load_capability` is not one: it is how a gated tool becomes callable.
+ */
+export const DISCOVERY_TOOL_NAMES: ReadonlySet<string> = new Set([
+  'list_capabilities',
+  'list_skills',
+  'search_skills',
+]);
+
+function discoveryCallsInTurn(messages: readonly BaseMessage[]): number {
+  let count = 0;
+  for (let i = turnStart(messages); i < messages.length; i++) {
+    const msg = messages[i];
+    if (msg instanceof ToolMessage && DISCOVERY_TOOL_NAMES.has(msg.name ?? ''))
+      count += 1;
+  }
+  return count;
+}
+/** Discovery calls a turn may make, whatever their arguments. */
+export const MAX_DISCOVERY_CALLS = 6;
+
 /**
  * Parse `TURN_MAX_IDENTICAL_READS` / `TURN_MAX_IDENTICAL_WRITES`; anything
  * that is not a positive number keeps its default (as `turnLimitsFromEnv`).
@@ -99,6 +121,18 @@ export const createToolRepetitionGuardMiddleware = (
 
   return createMiddleware({
     name: 'ToolRepetitionGuardMiddleware',
+    // A model can keep calling a refused tool forever; once the turn spent its searches, it no longer sees them.
+    wrapModelCall: (request, handler) => {
+      if (
+        discoveryCallsInTurn(request.state.messages ?? []) < MAX_DISCOVERY_CALLS
+      )
+        return handler(request);
+      const tools = request.tools.filter(
+        (t) =>
+          !(typeof t.name === 'string' && DISCOVERY_TOOL_NAMES.has(t.name)),
+      );
+      return handler({ ...request, tools });
+    },
     wrapToolCall: async (toolCallRequest, handler) => {
       const { toolCall, state } = toolCallRequest;
       const toolName = toolCall.name ?? toolCallRequest.tool?.name;
@@ -109,6 +143,26 @@ export const createToolRepetitionGuardMiddleware = (
       const opening = turnStart(messages);
       const start = Math.max(opening, messages.length - lookback, 0);
       const argsById = toolCallArgsById(messages, start);
+
+      if (DISCOVERY_TOOL_NAMES.has(toolName)) {
+        const discovered = discoveryCallsInTurn(messages);
+        if (discovered >= MAX_DISCOVERY_CALLS) {
+          logger.warn(
+            `Repetition guard: ${toolName} refused after ${discovered} discovery calls this turn`,
+          );
+          return new ToolMessage({
+            content: [
+              `You have already searched capabilities and skills ${discovered} times in this turn, so \`${toolName}\` was NOT run.`,
+              '',
+              'Stop searching. Act with the tools you already have: read their descriptions and call the one that fits the request,',
+              'or tell the user what you could not find and ask them what they want.',
+            ].join('\n'),
+            tool_call_id: toolCall.id ?? '',
+            name: toolName,
+            status: 'error',
+          });
+        }
+      }
       // The turn's calls a mid-turn summary condensed away (oldest first):
       // only while the lookback still reaches the summary.
       const openingMessage = messages[opening];
@@ -121,7 +175,13 @@ export const createToolRepetitionGuardMiddleware = (
           call.name === toolName && canonicalArgsKey(call.args) === argsKey,
       );
 
-      const failedInTurn = (priorError: string): ToolMessage => {
+      const failedInTurn = (failure: string): ToolMessage => {
+        // A refusal of this guard is not quoted inside the next one, or each repeat nests every earlier one.
+        const priorError = /was NOT (called|run) again|was NOT run\b/.test(
+          failure,
+        )
+          ? `This guard already refused it: \`${toolName}\` reached its limit in this turn.`
+          : failure;
         logger.warn(
           `Repetition guard: short-circuiting duplicate failed call to ${toolName}`,
           { toolName, priorError },

package/src/core/middlewares/turn-boundary.ts

@@ -90,23 +90,33 @@ export function turnCarryOf(
 }
 
 /**
- * Index of the message that opens the current turn: the latest human
- * message other than the ones the runtime writes itself, or a summary that
- * carries the calls of a turn it condensed mid-way. 0 when there is none.
+ * A turn opens at a human message other than the ones the runtime writes
+ * itself, or at a summary that carries the calls of a turn it condensed
+ * mid-way.
  */
+function opensTurn(message: BaseMessage | undefined): boolean {
+  if (!message || !HumanMessage.isInstance(message)) return false;
+  if (isSummarizationMessage(message))
+    return turnCarryOf(message) !== undefined;
+  return !isAttachmentViewMessage(message);
+}
+
+/** Index of the message that opens the current turn; 0 when there is none. */
 export function turnStart(messages: readonly BaseMessage[]): number {
-  for (let i = messages.length - 1; i >= 0; i--) {
-    const message = messages[i];
-    if (!message || !HumanMessage.isInstance(message)) continue;
-    if (isSummarizationMessage(message)) {
-      if (turnCarryOf(message) !== undefined) return i;
-      continue;
-    }
-    if (!isAttachmentViewMessage(message)) return i;
-  }
+  for (let i = messages.length - 1; i >= 0; i--)
+    if (opensTurn(messages[i])) return i;
   return 0;
 }
 
+/** The indexes of every turn-opening message, oldest first. */
+export function turnOpenings(messages: readonly BaseMessage[]): number[] {
+  const openings: number[] = [];
+  messages.forEach((message, index) => {
+    if (opensTurn(message)) openings.push(index);
+  });
+  return openings;
+}
+
 function resultText(message: ToolMessage): string {
   const { content } = message;
   const text =

package/src/core/operating-guides.ts

@@ -0,0 +1,126 @@
+/**
+ * Where what the model needs to use a loaded plugin reaches it: the plugin's
+ * usage (`summary`, `whenToUse`, `whenNotToUse`, `examples`, the tool names)
+ * and its operating guide.
+ *
+ * A guide in the system prompt is the cheapest place for it: cached like the
+ * rest of the prefix, it survives summaries and trimming. But any change to
+ * the system prompt costs a full cache miss on the next call, so the guides
+ * in the prompt only change on a cold turn, when that miss has already
+ * happened (`CONTEXT_CACHE_COLD_MS`). The set the prompt carries is recorded
+ * on the thread (the graph's `promptGuides` channel) and held until then.
+ *
+ * Usage, and a guide outside the prompt, go at the tail of the messages, which
+ * keeps the cache: in the result of the load that brought the plugin
+ * (`load_capability`, the capability gate), or as a note on the turn's message
+ * when nothing called a load (a router preload, the editor context) or a
+ * summary has condensed that result away. The thread records which plugins it
+ * still carries in the graph's `capabilityUsage` channel, so a turn needs no
+ * read of the messages to know, and the messages that carry them say so in
+ * `USAGE_CARRIED_KWARG`: the context guard keeps them while the plugin is
+ * loaded, and a summary keeps the record of the ones it did not condense.
+ */
+import type { BaseMessage } from '@langchain/core/messages';
+import { OPERATING_GUIDES_HEADING } from './prompt-composer';
+
+/** `additional_kwargs` key listing the plugins whose usage a message carries. */
+export const USAGE_CARRIED_KWARG = 'capability_usage';
+
+/** `additional_kwargs` key holding the exact note a user message was sent with. */
+export const TURN_GUIDE_NOTE_KWARG = 'turn_guide_note';
+
+/** The plugins whose usage `message` carries. */
+export function usageCarriedBy(message: BaseMessage): string[] {
+  const carried: unknown = message.additional_kwargs?.[USAGE_CARRIED_KWARG];
+  return Array.isArray(carried)
+    ? carried.filter((name) => typeof name === 'string')
+    : [];
+}
+
+/**
+ * The note a turn's message carries for plugins that have no load result in
+ * the thread: what `load_capability` would have returned for them.
+ */
+export function renderGuideNote(loads: readonly unknown[]): string {
+  return `[From the runtime, not the user: these capabilities are loaded and in your tool list.]\n\n${OPERATING_GUIDES_HEADING}\n\n${JSON.stringify(loads)}`;
+}
+
+/** What the thread records about its prompt, and whether the prompt may change. */
+export interface PromptCacheState {
+  /** The provider's cache has expired (or never held this thread). */
+  cold: boolean;
+  /**
+   * The plugins whose guides the prompt carried on the thread's last turn.
+   * Undefined on a thread from before this was recorded, whose prompt carried
+   * every loaded plugin's guide.
+   */
+  promptGuides?: readonly string[];
+  /**
+   * The plugins whose usage the thread's messages carry. Undefined on a thread
+   * from before this was recorded, which counts as carrying what it loaded.
+   */
+  capabilityUsage?: readonly string[];
+}
+
+export interface UsableGuide {
+  pluginName: string;
+  guide: string;
+}
+
+export interface CapabilityPlan {
+  /** The guides of this turn's system prompt, in the order they were given. */
+  inPrompt: UsableGuide[];
+  /** Loaded plugins whose usage the thread does not carry: for the turn's message. */
+  onMessage: string[];
+  /** The new value of the `promptGuides` channel, when it is decided now. */
+  promptGuides?: string[];
+  /** The new value of the `capabilityUsage` channel, when it changes. */
+  capabilityUsage?: string[];
+}
+
+function sameMembers(a: readonly string[], b: ReadonlySet<string>): boolean {
+  return a.length === b.size && a.every((name) => b.has(name));
+}
+
+/**
+ * Decides where each plugin's guide and usage go this turn. `always` plugins
+ * have their guides in the prompt on every turn. Without a `cache` every turn
+ * counts as cold.
+ */
+export function planCapabilityContext(input: {
+  guides: readonly UsableGuide[];
+  /** The plugins loaded on the thread when the turn was built. */
+  loaded: ReadonlySet<string>;
+  /** The same, before this turn added to it. */
+  priorLoaded: ReadonlySet<string>;
+  /** Whether this delegation can use the plugin at all. */
+  usable: (pluginName: string) => boolean;
+  alwaysVisible: (pluginName: string) => boolean;
+  cache?: PromptCacheState;
+}): CapabilityPlan {
+  const { guides, loaded, priorLoaded, usable, alwaysVisible, cache } = input;
+  const cold = !cache || cache.cold;
+  const recorded = cold ? loaded : new Set(cache.promptGuides ?? priorLoaded);
+  const carried = new Set(cache?.capabilityUsage ?? priorLoaded);
+  const onMessage = [...loaded].filter(
+    (pluginName) => usable(pluginName) && !carried.has(pluginName),
+  );
+  const capabilityUsage = new Set(
+    [...loaded].filter(
+      (pluginName) => carried.has(pluginName) || onMessage.includes(pluginName),
+    ),
+  );
+  return {
+    inPrompt: guides.filter(
+      ({ pluginName }) => alwaysVisible(pluginName) || recorded.has(pluginName),
+    ),
+    onMessage,
+    ...(cold || cache.promptGuides === undefined
+      ? { promptGuides: [...recorded] }
+      : {}),
+    ...(cache?.capabilityUsage !== undefined &&
+    sameMembers(cache.capabilityUsage, capabilityUsage)
+      ? {}
+      : { capabilityUsage: [...capabilityUsage] }),
+  };
+}

package/src/core/plugins/skills/skills-tools.ts

@@ -55,46 +55,21 @@ export interface MergedSkill {
   createdAt?: string;
 }
 
-const LIST_DESCRIPTION = `List available skills from the IXO skills registry — the caller's **published** private skills first, then public registry skills.
+const LIST_DESCRIPTION = `List skills: the caller's published private skills first, then the public IXO registry. Each entry has title, description, path (absolute sandbox path of the skill folder), source ("private" | "public") and cid. load_skill and sandbox_run take the cid; never use it as a file path.`;
 
-Each entry includes:
-- title: skill name
-- description: skill description
-- path: absolute sandbox path to the skill folder
-- source: "private" (your published skill) or "public" (registry)
-- cid: required by load_skill and by sandbox_run (when the run depends on the skill). Never use a CID as a file path.`;
-
-const SEARCH_DESCRIPTION = `Search the caller's published skills and the public IXO registry by query.
-
-Matching published (private) skills come first, then public registry results. Each entry includes title, description, path, source ("private" | "public"), and cid.`;
+const SEARCH_DESCRIPTION = `Search the caller's published skills, then the public IXO registry. Entries as in list_skills. Running a skill takes load_skill and sandbox_run, from the sandbox capability.`;
 
 const listSchema = z.object({
-  limit: z
-    .number()
-    .min(1)
-    .max(100)
-    .optional()
-    .describe('Optional: number of skills to return (1-100, default: 20).'),
-  offset: z
-    .number()
-    .min(0)
-    .optional()
-    .describe('Optional: pagination offset (default: 0).'),
+  limit: z.number().min(1).max(100).optional().describe('Default 20.'),
+  offset: z.number().min(0).optional(),
 });
 
 const searchSchema = z.object({
   q: z
     .string()
     .min(1, 'Search query is required')
-    .describe(
-      'Search query (e.g. "pptx", "invoice", "presentation", "docx"). Required.',
-    ),
-  limit: z
-    .number()
-    .min(1)
-    .max(50)
-    .optional()
-    .describe('Optional: max results to return (1-50, default: 10).'),
+    .describe('E.g. "pptx", "invoice".'),
+  limit: z.number().min(1).max(50).optional().describe('Default 10.'),
 });
 
 function normalizeRegistryCapsule(capsule: Capsule): MergedSkill {

package/src/core/plugins/skills/skills.plugin.ts

@@ -33,9 +33,7 @@ const manifest: PluginManifest = {
     'User asks "what skills are available?" or "what can you do?".',
     'User asks the agent to find a skill for a specific task ("a skill for invoices", "is there a skill for KYC?").',
   ],
-  whenNotToUse: [
-    'Executing a skill — this runtime only lists and searches the registry.',
-  ],
+  whenNotToUse: ['Running a skill: that takes the `sandbox` capability.'],
   examples: [
     {
       user: 'Do you have a skill that can generate an invoice?',
@@ -46,6 +44,9 @@ const manifest: PluginManifest = {
   tags: ['skills', 'capsules', 'registry', 'ucan'],
   category: 'data',
   visibility: 'always',
+  brief: 'browse every skill, without a search term',
+  // `search_skills` stays bound; listing the whole registry is rare.
+  onDemandTools: ['list_skills'],
   stability: 'stable',
 };