@combycode/llm-sdk 2.0.1 → 2.1.0

package/dist/index.js

@@ -2703,12 +2703,15 @@ var NetworkEngine = class {
   hooks;
   fetchFn;
   connectFn;
+  /** Engine-wide retry policy, inherited by every queue created from here. */
+  defaultRetry;
   settings = /* @__PURE__ */ new Map();
   queues = /* @__PURE__ */ new Map();
   constructor(config) {
     this.hooks = config?.hooks ?? new HookBus();
     this.fetchFn = config?.fetch ?? globalThis.fetch.bind(globalThis);
     this.connectFn = config?.connect ?? defaultConnectFn;
+    this.defaultRetry = config?.retry;
     if (config?.queues) {
       for (const [name, settings] of Object.entries(config.queues)) {
         this.settings.set(name, settings);
@@ -2790,12 +2793,18 @@ var NetworkEngine = class {
       ...FALLBACK_LIMITS,
       ...settings.limits
     };
+    const retry = this.defaultRetry || settings.retry ? {
+      ...this.defaultRetry,
+      ...settings.retry,
+      ...this.defaultRetry?.backoff || settings.retry?.backoff ? { backoff: { ...this.defaultRetry?.backoff, ...settings.retry?.backoff } } : {},
+      ...this.defaultRetry?.perKind || settings.retry?.perKind ? { perKind: { ...this.defaultRetry?.perKind, ...settings.retry?.perKind } } : {}
+    } : void 0;
     const config = {
       queueName,
       fetch: this.fetchFn,
       hooks: this.hooks,
       limits,
-      retry: settings.retry,
+      retry,
       queue: settings.queue
     };
     queue = new QueueState(config);
@@ -2872,6 +2881,62 @@ function ensureAdditionalProperties(schema) {
   }
   return result;
 }
+var ANTHROPIC_UNSUPPORTED = /* @__PURE__ */ new Set([
+  "minimum",
+  "maximum",
+  "exclusiveMinimum",
+  "exclusiveMaximum",
+  "multipleOf",
+  "maxItems"
+]);
+function strictSupport(schema, dialect) {
+  const visit = (node, path) => {
+    if (!node || typeof node !== "object" || Array.isArray(node)) return null;
+    const n = node;
+    const at = path || "(root)";
+    if (typeof n.$ref === "string") return `${at}: '$ref' cannot be verified without resolution`;
+    if (dialect === "anthropic") {
+      for (const key of Object.keys(n)) {
+        if (ANTHROPIC_UNSUPPORTED.has(key)) return `${at}: '${key}' is not supported under strict`;
+      }
+    }
+    const props = n.properties;
+    if (n.additionalProperties !== void 0 && n.additionalProperties !== false) {
+      return `${at}: 'additionalProperties' must be false under strict`;
+    }
+    if (dialect === "openai") {
+      if (n.type === "object" && props === void 0) {
+        return `${at}: an object schema with no 'properties' cannot be strict (a free-form object is not expressible)`;
+      }
+    }
+    if (props && typeof props === "object") {
+      if (dialect === "openai") {
+        const required = new Set(Array.isArray(n.required) ? n.required : []);
+        const missing = Object.keys(props).filter((k) => !required.has(k));
+        if (missing.length > 0) return `${at}: ${missing.join(", ")} not listed in 'required'`;
+      }
+      for (const [key, val] of Object.entries(props)) {
+        const r = visit(val, path ? `${path}.${key}` : key);
+        if (r) return r;
+      }
+    }
+    for (const key of ["items", "additionalProperties"]) {
+      const r = visit(n[key], path ? `${path}.${key}` : key);
+      if (r) return r;
+    }
+    for (const key of ["anyOf", "oneOf", "allOf"]) {
+      const branches = n[key];
+      if (!Array.isArray(branches)) continue;
+      for (const [i, sub] of branches.entries()) {
+        const r = visit(sub, `${at}.${key}[${i}]`);
+        if (r) return r;
+      }
+    }
+    return null;
+  };
+  const reason = visit(schema, "");
+  return reason ? { ok: false, reason } : { ok: true };
+}
 
 // src/llm/providers/anthropic/catalog.json
 var catalog_default = {
@@ -25985,12 +26050,16 @@ var AnthropicAdapter = class {
           }
           return null;
         }
+        const strict = t.strict === true;
+        const params = ensureAdditionalProperties(t.parameters);
         const tool = {
           name: t.name,
           description: t.description,
-          input_schema: t.parameters
+          // Only the strict path was measured with `additionalProperties: false`
+          // applied; without strict the schema goes out untouched, as before.
+          input_schema: strict ? params : t.parameters
         };
-        if (t.strict) tool.strict = true;
+        if (strict) tool.strict = true;
         if ((t.cache || shouldCacheTools) && i === req.tools.length - 1) {
           tool.cache_control = { type: "ephemeral" };
         }
@@ -28039,15 +28108,19 @@ var OpenAIAdapter = class {
       };
     }
     if (req.tools?.length) {
-      body.tools = req.tools.filter(isFunctionTool).map((t) => ({
-        type: "function",
-        function: {
-          name: t.name,
-          description: t.description,
-          parameters: t.parameters,
-          ...t.strict ? { strict: true } : {}
-        }
-      }));
+      body.tools = req.tools.filter(isFunctionTool).map((t) => {
+        const params = ensureAdditionalProperties(t.parameters);
+        const strict = t.strict === true;
+        return {
+          type: "function",
+          function: {
+            name: t.name,
+            description: t.description,
+            parameters: strict ? params : t.parameters,
+            ...strict ? { strict: true } : {}
+          }
+        };
+      });
     }
     if (req.toolChoice) {
       if (typeof req.toolChoice === "string") body.tool_choice = req.toolChoice;
@@ -28057,12 +28130,14 @@ var OpenAIAdapter = class {
       body.reasoning = { effort: req.thinking.effort ?? "medium" };
     }
     if (req.structured) {
+      const schema = ensureAdditionalProperties(req.structured.schema);
+      const strict = req.structured.strict ?? strictSupport(schema, "openai").ok;
       body.response_format = {
         type: "json_schema",
         json_schema: {
           name: req.structured.name ?? "response",
-          schema: req.structured.schema,
-          strict: req.structured.strict ?? true
+          schema: strict ? schema : req.structured.schema,
+          strict
         }
       };
     }
@@ -28962,12 +29037,13 @@ var OpenAIResponsesAdapter = class {
     if (req.tools?.length) {
       body.tools = req.tools.map((t) => {
         if (isFunctionTool(t)) {
+          const params = ensureAdditionalProperties(t.parameters);
           return {
             type: "function",
             name: t.name,
             description: t.description,
-            parameters: ensureAdditionalProperties(t.parameters),
-            strict: t.strict ?? true,
+            parameters: params,
+            strict: t.strict ?? strictSupport(params, "openai").ok,
             // Programmatic tool calling (Responses): who may call it + return schema.
             ...t.allowedCallers ? { allowed_callers: t.allowedCallers } : {},
             ...t.outputSchema ? { output_schema: t.outputSchema } : {}
@@ -28988,12 +29064,13 @@ var OpenAIResponsesAdapter = class {
       }
     }
     if (req.structured) {
+      const schema = ensureAdditionalProperties(req.structured.schema);
       body.text = {
         format: {
           type: "json_schema",
           name: req.structured.name ?? "response",
-          schema: ensureAdditionalProperties(req.structured.schema),
-          strict: req.structured.strict ?? true
+          schema,
+          strict: req.structured.strict ?? strictSupport(schema, "openai").ok
         }
       };
     }
@@ -30587,7 +30664,9 @@ var LAYER_MEMORY = "memory";
 var LAYER_CHAT_FACTS = "chat.facts";
 var LAYER_EXECUTOR_TOOL_EXAMPLES = "executor.tool-examples";
 var LAYER_CONTEXT_GUARD_SUMMARY = "context-guard.summary";
+var LAYER_LAZY_TOOLS = "agentloop.lazy-tools";
 var PRIORITY_AGENTLOOP_SYSTEM = 10;
+var PRIORITY_LAZY_TOOLS = 20;
 var PRIORITY_LEGACY_SYSTEM = 50;
 var PRIORITY_AGENTLOOP_CONTEXT = 100;
 var PRIORITY_MEMORY = 200;
@@ -30605,6 +30684,17 @@ function writeAgentLoopSystem(registry, text, owner) {
     owner
   });
 }
+function writeLazyToolsProtocol(registry, active, owner) {
+  if (!active) {
+    registry.remove(LAYER_LAZY_TOOLS);
+    return;
+  }
+  registry.set(
+    LAYER_LAZY_TOOLS,
+    "Not all of your tools are listed. Use `tool_search` to find the ones you need \u2014 it returns their exact names and full argument schemas \u2014 then run them with `call_tool`. Search for every capability the request needs in ONE call, passing several queries. If the result reports a query as unmatched, search again with different words before answering; never answer as if a capability you could not find does not matter.",
+    { priority: PRIORITY_LAZY_TOOLS, tags: ["system"], owner }
+  );
+}
 function writeAgentLoopContext(registry, text, owner) {
   if (!text) {
     registry.remove(LAYER_AGENTLOOP_CONTEXT);
@@ -30956,6 +31046,175 @@ ${text}` : text;
   }
 };
 
+// src/agent/lazy-tools.ts
+var DEFAULT_LIMIT = 5;
+var MAX_LIMIT = 20;
+var DEFAULT_MAX_SEARCHES = 5;
+var LAZY_SEARCH_TOOL = "tool_search";
+var LAZY_CALL_TOOL = "call_tool";
+var STOP_WORDS = /* @__PURE__ */ new Set([
+  "the",
+  "a",
+  "an",
+  "of",
+  "for",
+  "to",
+  "in",
+  "on",
+  "and",
+  "or",
+  "is",
+  "it",
+  "that",
+  "this",
+  "with",
+  "return",
+  "returns",
+  "my",
+  "me",
+  "do",
+  "we",
+  "i",
+  "how",
+  "many",
+  "much",
+  "what",
+  "when",
+  "has",
+  "have",
+  "need",
+  "any",
+  "get",
+  "can",
+  "you",
+  "are",
+  "was",
+  "been",
+  "does",
+  "did",
+  "should",
+  "from",
+  "by",
+  "at",
+  "as",
+  "be"
+]);
+function tokenize(s) {
+  return s.toLowerCase().split(/[^a-z0-9]+/).filter((w) => w.length > 2 && !STOP_WORDS.has(w));
+}
+var isFn = (t) => "name" in t;
+var nameOf = (t) => isFn(t.definition) ? t.definition.name : "";
+function rankTools(query, candidates, limit) {
+  const q = new Set(tokenize(query));
+  if (q.size === 0) return [];
+  const scored = [];
+  for (const tool of candidates) {
+    const def = tool.definition;
+    if (!isFn(def)) continue;
+    const props = Object.keys(
+      def.parameters?.properties ?? {}
+    );
+    let score = 0;
+    for (const w of tokenize(`${def.name} ${def.description ?? ""} ${props.join(" ")}`)) {
+      if (q.has(w)) score++;
+    }
+    for (const w of tokenize(def.name)) if (q.has(w)) score += 2;
+    if (score > 0) scored.push({ tool, score });
+  }
+  return scored.sort((a, b) => b.score - a.score).slice(0, limit).map((s) => s.tool);
+}
+function createLazyTools(deps) {
+  const limit = Math.min(deps.config.limit ?? DEFAULT_LIMIT, MAX_LIMIT);
+  const maxSearches = deps.config.maxSearches ?? DEFAULT_MAX_SEARCHES;
+  const search = {
+    definition: {
+      type: "function",
+      name: LAZY_SEARCH_TOOL,
+      description: "Find the tools you need. Returns their exact names and full argument schemas. Pass every capability you need as a separate query in one call.",
+      parameters: {
+        type: "object",
+        properties: {
+          queries: {
+            type: "array",
+            items: { type: "string" },
+            description: "One phrase per capability you need, in your own words."
+          }
+        },
+        required: ["queries"]
+      }
+    },
+    execute: async (args) => {
+      deps.state.searches++;
+      if (deps.state.searches > maxSearches) {
+        return JSON.stringify({
+          error: `Search budget exhausted (${maxSearches} searches per run). Use the tools you already found.`
+        });
+      }
+      const raw = args.queries;
+      const queries = (Array.isArray(raw) ? raw : [raw]).filter((q) => typeof q === "string" && q.trim().length > 0);
+      if (queries.length === 0) {
+        return JSON.stringify({ tools: [], error: "Pass at least one query string in `queries`." });
+      }
+      const candidates = deps.lazyTools();
+      const hits = /* @__PURE__ */ new Map();
+      const unmatched = [];
+      for (const q of queries) {
+        const found = rankTools(q, candidates, limit);
+        if (found.length === 0) unmatched.push(q);
+        for (const t of found) hits.set(nameOf(t), t);
+      }
+      deps.onSearch?.({ queries, matched: [...hits.keys()], unmatched });
+      return JSON.stringify({
+        tools: [...hits.values()].map((t) => t.definition),
+        ...unmatched.length > 0 ? {
+          unmatched,
+          hint: "These queries matched no tool. Search again for them using different words, or tell the user the capability is unavailable."
+        } : {}
+      });
+    }
+  };
+  const call = {
+    definition: {
+      type: "function",
+      name: LAZY_CALL_TOOL,
+      description: "Call one tool returned by tool_search. Pass its exact name and its own arguments as `input`. To use several tools, call this several times in the same turn.",
+      parameters: {
+        type: "object",
+        properties: {
+          name: { type: "string", description: "Exact tool name from tool_search." },
+          input: {
+            type: "object",
+            description: "That tool's own arguments, as an object.",
+            additionalProperties: true
+          }
+        },
+        required: ["name", "input"]
+      }
+    },
+    execute: async (args, ctx) => {
+      const name = String(args.name ?? "");
+      const target = deps.lazyTools().find((t) => nameOf(t) === name);
+      if (!target) {
+        if (deps.eagerNames().includes(name)) {
+          return `"${name}" is already available as a normal tool \u2014 call it directly, not through ${LAZY_CALL_TOOL}.`;
+        }
+        return `No tool named "${name}". Call ${LAZY_SEARCH_TOOL} first and use a name exactly as returned.`;
+      }
+      const input = args.input;
+      if (input !== void 0 && (typeof input !== "object" || input === null || Array.isArray(input))) {
+        return `\`input\` must be an object of ${name}'s arguments, not ${Array.isArray(input) ? "an array" : typeof input}.`;
+      }
+      return target.execute(input ?? {}, ctx);
+    }
+  };
+  return [search, call];
+}
+function unwrapLazyCall(toolName, args) {
+  if (toolName !== LAZY_CALL_TOOL) return null;
+  const inner = args.name;
+  return typeof inner === "string" && inner.length > 0 ? inner : null;
+}
+
 // src/agent/tool-key.ts
 function toolKey(tool) {
   return isFunctionTool(tool.definition) ? tool.definition.name : tool.definition.type;
@@ -31222,6 +31481,13 @@ var AgentLoop = class _AgentLoop {
   _systemThunk = null;
   _context;
   _tools;
+  _lazyConfig = {};
+  /** Per-run search budget, reset at the start of every run. */
+  _lazyState = { searches: 0 };
+  /** Installed on the first `lazy` registration and never removed, so the declared tool
+   *  array stays byte-identical for the life of the conversation — which is the entire
+   *  reason the design is cheap. */
+  _lazyInstalled = false;
   _history;
   _reports = [];
   _metadata = {};
@@ -31269,6 +31535,7 @@ var AgentLoop = class _AgentLoop {
     this._checkpoint = config.checkpoint ?? null;
     this._collisionPolicy = config.toolNameCollisionPolicy ?? "warn";
     this._reflectRetry = config.reflectAndRetry ? new ReflectAndRetryPolicy(config.reflectAndRetry) : null;
+    this._lazyConfig = config.lazyTools ?? {};
     this._tools = /* @__PURE__ */ new Map();
     for (const t of config.tools ?? []) {
       this.registerTool(t);
@@ -31283,6 +31550,7 @@ var AgentLoop = class _AgentLoop {
     this.id = this._history.id;
     writeAgentLoopSystem(this._history.registry, this._system, "agent-loop");
     writeAgentLoopContext(this._history.registry, this._context, "agent-loop");
+    this.syncLazyProtocol();
     this.hooks.emitSync("onAgentCreate", {
       agentId: this.id,
       clientId: this.client.id,
@@ -31369,6 +31637,7 @@ var AgentLoop = class _AgentLoop {
       });
     }
     this._tools.set(key, tool);
+    if (tool.lazy) this.installLazyTools();
   }
   removeTool(name) {
     this._tools.delete(name);
@@ -32019,22 +32288,61 @@ var AgentLoop = class _AgentLoop {
       metrics,
       trace: runTrace
     });
+    const inner = unwrapLazyCall(tc.name, tc.arguments);
     reports.push({
       callId: tc.id,
-      toolName: tc.name,
+      toolName: inner ?? tc.name,
       arguments: tc.arguments,
       resultSizeBytes: resultStr.length,
       latencyMs,
       skipped: false,
       error: null,
       metrics: Object.fromEntries(metrics),
+      ...inner ? { discoveredVia: "search" } : {},
       ...customData !== void 0 ? { customData } : {}
     });
     return { type: "tool_result", id: tc.id, content: resultStr };
   }
-  /** Merge agent's tool definitions with caller-provided tools (caller wins on conflict). */
+  /** Declare `tool_search` + `call_tool`, once, on the first lazy registration.
+   *
+   *  They go through `registerTool` like anything else, so the collision policy covers
+   *  them and there is no second registry to keep in sync. They are never removed: the
+   *  declared array must stay identical for the whole conversation or the cached prefix
+   *  is invalidated, which is the cost the feature exists to avoid. */
+  installLazyTools() {
+    if (this._lazyInstalled) return;
+    this._lazyInstalled = true;
+    for (const t of createLazyTools({
+      lazyTools: () => [...this._tools.values()].filter((t2) => t2.lazy),
+      eagerNames: () => [...this._tools.entries()].filter(([, t2]) => !t2.lazy).map(([key]) => key),
+      state: this._lazyState,
+      config: this._lazyConfig,
+      onSearch: (info) => {
+        void this.hooks.emit("onToolSearch", { agentId: this.id, ...info });
+      }
+    })) {
+      this.registerTool(t);
+    }
+    this.syncLazyProtocol();
+  }
+  /** Publish (or remove) the "your tools are not all listed" layer.
+   *
+   *  Separate from `installLazyTools` because tools are registered in the constructor
+   *  BEFORE `_history` exists, and the layer lives in the history's registry. The
+   *  constructor calls this again once history is built.
+   *
+   *  The model has no reason to suspect a tool it cannot see, and the failure without
+   *  this is quiet — it answers from whatever it did find. Measured at 8/12 and 9/12
+   *  without the protocol, 18/18 with it, same tasks and same ranker. */
+  syncLazyProtocol() {
+    if (!this._history) return;
+    writeLazyToolsProtocol(this._history.registry, this._lazyInstalled, "agent-loop");
+  }
+  /** Merge agent's tool definitions with caller-provided tools (caller wins on conflict).
+   *
+   *  Lazy tools are registered but NOT declared — that filter is the whole mechanism. */
   toolDefinitions(options) {
-    const own = [...this._tools.values()].map((t) => t.definition);
+    const own = [...this._tools.values()].filter((t) => !t.lazy).map((t) => t.definition);
     if (options.tools) return [...own, ...options.tools];
     return own.length > 0 ? own : void 0;
   }
@@ -32044,6 +32352,7 @@ var AgentLoop = class _AgentLoop {
     this._running = true;
     this._stopRequested = false;
     this._abortController = new AbortController();
+    this._lazyState.searches = 0;
     if (this._systemThunk) {
       const next = await this._systemThunk();
       if (next !== this._system) {
@@ -33017,9 +33326,16 @@ function summarize(entries) {
     reasoning: 0,
     total: 0,
     tokens: { input: 0, output: 0, cached: 0, cacheWrite: 0, reasoning: 0 },
-    entries: entries.length
+    entries: entries.length,
+    unpriced: 0,
+    unpricedModels: []
   };
   for (const e of entries) {
+    if (e.cost.source === "unknown") {
+      s.unpriced++;
+      const key = `${e.provider}/${e.model}`;
+      if (!s.unpricedModels.includes(key)) s.unpricedModels.push(key);
+    }
     s.input += e.cost.input;
     s.output += e.cost.output;
     s.cacheRead += e.cost.cacheRead;
@@ -33045,6 +33361,8 @@ var CostCollector = class {
   budgets = [];
   triggeredThresholds = /* @__PURE__ */ new Map();
   _runningTotal = 0;
+  /** Models already reported as unpriced, so the warning fires once rather than per call. */
+  warnedUnpriced = /* @__PURE__ */ new Set();
   watchedAgents = /* @__PURE__ */ new Set();
   unsub = null;
   unsubMedia = null;
@@ -33177,6 +33495,7 @@ var CostCollector = class {
     };
     this.ledger.push(entry);
     this._runningTotal += cost.total;
+    this.noteIfUnpriced(entry);
     this.hooks.emitSync("onCostEntry", { entry, runningTotal: this._runningTotal });
     this.checkBudgets(entry);
   }
@@ -33222,9 +33541,31 @@ var CostCollector = class {
     };
     this.ledger.push(entry);
     this._runningTotal += cost.total;
+    this.noteIfUnpriced(entry);
     this.hooks.emitSync("onCostEntry", { entry, runningTotal: this._runningTotal });
     this.checkBudgets(entry);
   }
+  /** A total of exactly 0 because the model is not in the catalog reads identically to a
+   *  total of 0 because the call was free — and it silently under-counts every budget
+   *  and report built on it. `source: 'unknown'` already records the difference per
+   *  entry, but nothing aggregated it, so a whole benchmark run once reported $0.00000
+   *  for a live provider and looked like a free arm.
+   *
+   *  Fires once per provider/model: an unpriced model is a configuration fact, not a
+   *  per-request event, and repeating it on every call would train the reader to ignore
+   *  it. Free calls are priced 'calculated' with an explicit note, so they stay silent. */
+  noteIfUnpriced(entry) {
+    if (entry.cost.source !== "unknown") return;
+    const key = `${entry.provider}/${entry.model}`;
+    if (this.warnedUnpriced.has(key)) return;
+    this.warnedUnpriced.add(key);
+    this.hooks.emitSync("onWarning", {
+      source: "cost",
+      code: "unpriced_model",
+      message: `No catalog pricing for ${key} \u2014 its cost is reported as 0, which is not the same as free. Check the model id against the catalog, or add pricing for it.`,
+      details: { provider: entry.provider, model: entry.model }
+    });
+  }
   checkBudgets(entry) {
     for (const budget of this.budgets) {
       if (!matchesScope(entry, budget.scope)) continue;
@@ -34269,7 +34610,7 @@ function createEngine(config = {}) {
   const persistence = resolvePersistence(config.persistence);
   const cache2 = resolveCache(config.cache);
   const catalog = resolveCatalog(config.catalog);
-  const network = new NetworkEngine({ hooks, fetch: config.fetch });
+  const network = new NetworkEngine({ hooks, fetch: config.fetch, retry: config.retry, queues: config.queues });
   const fetchBound = (req, options) => network.fetch(req, options);
   const fetchStreamBound = (req, options) => network.fetchStream(req, options);
   const connectBound = (req) => network.connect(req);
@@ -37562,6 +37903,7 @@ function defineTool(input) {
     if (!optional.has(key)) required.push(key);
   }
   return {
+    ...input.lazy ? { lazy: true } : {},
     definition: {
       name: input.name,
       description: input.description,
@@ -38050,7 +38392,14 @@ async function complete(opts) {
         temperature: opts.temperature
       });
       res = await loop.complete(input, {
-        structured: opts.structured
+        structured: opts.structured,
+        providerOptions: opts.providerOptions,
+        audio: opts.audio,
+        outputModalities: opts.outputModalities,
+        serviceTier,
+        cache: opts.cache,
+        topK: opts.topK,
+        seed: opts.seed
       });
     } else {
       res = await llm.complete(input, {
@@ -38061,12 +38410,16 @@ async function complete(opts) {
         providerOptions: opts.providerOptions,
         audio: opts.audio,
         outputModalities: opts.outputModalities,
-        serviceTier
+        serviceTier,
+        cache: opts.cache,
+        topK: opts.topK,
+        seed: opts.seed
       });
     }
     const result = {
       text: res.text,
       response: res,
+      ...res.error ? { error: res.error } : {},
       // Bound to this call's client (same provider/model/key/engine).
       retrieveFile: (file) => llm.retrieveFile(file),
       streamFile: (file) => llm.streamFile(file)
@@ -38412,10 +38765,21 @@ var McpResultCache = class {
     }
     return hit.value;
   }
-  /** Store only when the server actually asked for it. Returns whether anything was stored. */
+  /** Store only when the server actually asked for it. Returns whether anything was stored.
+   *
+   *  A non-positive `ttlMs` is an instruction, not a missing value: the server is saying *do not
+   *  reuse this*. Any entry already held under that key is dropped, so the next `get` re-fetches.
+   *  Without the eviction the hint is inert — a server that first said "cache for 60s" and then
+   *  says "stale now" would keep being answered from the stale entry for the rest of the original
+   *  TTL. Absent hints are different and must stay different: they carry no instruction, so an
+   *  existing entry is left alone and pre-2026 servers behave exactly as before. */
   set(key, value, hints, now = Date.now()) {
     const ttl = hints?.ttlMs;
-    if (typeof ttl !== "number" || !Number.isFinite(ttl) || ttl <= 0) return false;
+    if (typeof ttl === "number" && Number.isFinite(ttl) && ttl <= 0) {
+      this.entries.delete(key);
+      return false;
+    }
+    if (typeof ttl !== "number" || !Number.isFinite(ttl)) return false;
     this.entries.set(key, {
       value,
       expiresAt: now + ttl,
@@ -39573,11 +39937,23 @@ function mcpPromptToMessages(result) {
 }
 function mcpToolToAgentTool(client, tool, namespace, opts = {}) {
   return {
+    ...opts.lazy ? { lazy: true } : {},
     definition: {
       type: "function",
       name: `${namespace}__${tool.name}`,
       description: tool.description ?? tool.title ?? tool.name,
-      parameters: tool.inputSchema ?? { type: "object", properties: {} }
+      parameters: tool.inputSchema ?? { type: "object", properties: {} },
+      // MCP publishes a schema for the tool's structured output and OpenAI
+      // Responses accepts one (`output_schema`), so the model can reason over the
+      // shape it will get back.
+      //
+      // Gated on `validateOutput` because declaring it is a PROMISE, not a hint:
+      // the provider then requires the result to be JSON matching the schema, so
+      // the tool result changes from prose to structured data. Forwarding it
+      // unconditionally would silently reshape every existing MCP tool result —
+      // and did, until a live round trip through OpenAI Responses failed. Anyone
+      // asking for output validation has already opted into that contract.
+      ...opts.validateOutput && tool.outputSchema ? { outputSchema: tool.outputSchema } : {}
     },
     execute: async (args, ctx) => {
       const res = await client.callTool(tool.name, args, ctx.trace);
@@ -39585,6 +39961,9 @@ function mcpToolToAgentTool(client, tool, namespace, opts = {}) {
         const errors = validateJsonSchema(tool.outputSchema, res.structuredContent);
         if (errors.length > 0) return `Tool output failed schema validation: ${errors.slice(0, 5).join("; ")}`;
       }
+      if (opts.validateOutput && tool.outputSchema && res.structuredContent !== void 0 && !res.isError) {
+        return JSON.stringify(res.structuredContent);
+      }
       return mcpContentToResult(res);
     }
   };
@@ -40321,7 +40700,9 @@ async function connectMcp(config, opts = {}) {
   const refresh = async (c) => {
     const defs = await c.listTools();
     tools.length = 0;
-    for (const d of defs) tools.push(mcpToolToAgentTool(c, d, ns, { validateOutput: opts.validateOutput }));
+    for (const d of defs) {
+      tools.push(mcpToolToAgentTool(c, d, ns, { validateOutput: opts.validateOutput, lazy: opts.lazy }));
+    }
   };
   const sampler = opts.sampling ? samplingHandler(opts.sampling) : null;
   const capabilities = {};
@@ -42853,6 +43234,8 @@ export {
   LAYER_EXECUTOR_TOOL_EXAMPLES,
   LAYER_LEGACY_SYSTEM,
   LAYER_MEMORY,
+  LAZY_CALL_TOOL,
+  LAZY_SEARCH_TOOL,
   LLMClient,
   LLMError,
   LLM_DEF_KEY,
@@ -42980,6 +43363,7 @@ export {
   defineLLMTool,
   defineTool,
   delegate,
+  describeTool,
   discoverMetadata,
   dispatch,
   embed,
@@ -43041,6 +43425,7 @@ export {
   parseSSEStream,
   parseToolId,
   pcmToWav,
+  rankTools,
   readFactsLayer,
   reflectionGuidance,
   refreshTokens,
@@ -43058,7 +43443,9 @@ export {
   selectVariant,
   shellGlob,
   sniffImageMime,
+  strictSupport,
   submitBatch,
+  toolKey,
   transcribe,
   trimReplacer,
   tryParseToolId,