@absolutejs/ai 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -6,6 +6,12 @@ This file is generated by `absolute-changelog` from the entries in
 `changelog/`. Edit an entry, not this file — and add new ones under
 `changelog/unreleased/`.
 
+## 0.6.0 — 2026-10-20
+
+### Added
+
+- **Load tools on demand (deferLoading, through Anthropic tool search) and clear old tool results past a threshold (toolResultClearing); both cross the provider proxy** (`AIToolResultClearing`, `AIToolDefinition`, `AIProviderToolDefinition`, `AIProviderStreamParams`, `StreamAIOptions`)
+
 ## 0.5.0 — 2026-10-19
 
 ### Breaking

package/changelog.json

@@ -2,6 +2,23 @@
 	"contract": 1,
 	"name": "@absolutejs/ai",
 	"releases": [
+		{
+			"changes": [
+				{
+					"kind": "added",
+					"summary": "Load tools on demand (deferLoading, through Anthropic tool search) and clear old tool results past a threshold (toolResultClearing); both cross the provider proxy",
+					"symbols": [
+						"AIToolResultClearing",
+						"AIToolDefinition",
+						"AIProviderToolDefinition",
+						"AIProviderStreamParams",
+						"StreamAIOptions"
+					]
+				}
+			],
+			"date": "2026-10-20",
+			"version": "0.6.0"
+		},
 		{
 			"changes": [
 				{

package/dist/ai/index.js

@@ -478,6 +478,7 @@ var sendMessage = async (socket, message) => {
   return true;
 };
 var buildToolDefinitions = (tools) => Object.entries(tools).map(([name, def]) => ({
+  ...def.deferLoading ? { deferLoading: true } : {},
   description: def.description,
   input_schema: def.input,
   name
@@ -670,6 +671,7 @@ var processToolTurn = async (socket, options, state, messageId, conversationId,
     model: options.model,
     promptCaching: options.promptCaching,
     providerOptions: options.providerOptions,
+    toolResultClearing: options.toolResultClearing,
     reasoning: options.reasoning,
     signal,
     systemPrompt: options.systemPrompt,
@@ -760,6 +762,7 @@ var processStream = async (socket, options, messages, messageId, conversationId,
     model: options.model,
     promptCaching: options.promptCaching,
     providerOptions: options.providerOptions,
+    toolResultClearing: options.toolResultClearing,
     reasoning: options.reasoning,
     signal,
     systemPrompt: options.systemPrompt,
@@ -929,6 +932,7 @@ var withHeartbeat = async function* (source, signal, intervalMs) {
   }
 };
 var buildToolDefinitions2 = (tools) => Object.entries(tools).map(([name, def]) => ({
+  ...def.deferLoading ? { deferLoading: true } : {},
   description: def.description,
   input_schema: def.input,
   name
@@ -1193,6 +1197,7 @@ var streamTurns = async function* (options, renderers, messages, signal, startTi
         reasoning: options.reasoning,
         signal,
         systemPrompt: options.systemPrompt,
+        toolResultClearing: options.toolResultClearing,
         tools: toolDefs
       }, options.contextPolicy, (prepared) => {
         turnState.currentMessages = prepared.messages;
@@ -1805,6 +1810,7 @@ var mergeUsage = (left, right) => {
   };
 };
 var toProviderTools = (tools) => Object.entries(tools).map(([name, definition]) => ({
+  ...definition.deferLoading ? { deferLoading: true } : {},
   description: definition.description,
   input_schema: definition.input,
   name
@@ -2296,6 +2302,7 @@ var wireParams = (params) => ({
   ...params.systemPrompt === undefined ? {} : { systemPrompt: params.systemPrompt },
   ...params.temperature === undefined ? {} : { temperature: params.temperature },
   ...params.toolChoice === undefined ? {} : { toolChoice: params.toolChoice },
+  ...params.toolResultClearing === undefined ? {} : { toolResultClearing: params.toolResultClearing },
   ...params.tools === undefined ? {} : { tools: params.tools },
   ...params.topP === undefined ? {} : { topP: params.topP }
 });
@@ -6716,10 +6723,32 @@ var mapMessage = (msg) => ({
   role: msg.role === "system" ? "user" : msg.role
 });
 var mapToolDefinition2 = (tool) => ({
+  ...tool.deferLoading ? { defer_loading: true } : {},
   description: tool.description,
   input_schema: tool.input_schema,
   name: tool.name
 });
+var TOOL_SEARCH_TOOL = {
+  name: "tool_search_tool_bm25",
+  type: "tool_search_tool_bm25_20251119"
+};
+var CONTEXT_MANAGEMENT_BETA = "context-management-2025-06-27";
+var contextManagementFor = (clearing) => ({
+  edits: [
+    {
+      ...clearing.clearAtLeastInputTokens === undefined ? {} : {
+        clear_at_least: {
+          type: "input_tokens",
+          value: clearing.clearAtLeastInputTokens
+        }
+      },
+      ...clearing.excludeTools?.length ? { exclude_tools: [...clearing.excludeTools] } : {},
+      ...clearing.keepToolUses === undefined ? {} : { keep: { type: "tool_uses", value: clearing.keepToolUses } },
+      trigger: { type: "input_tokens", value: clearing.triggerInputTokens },
+      type: "clear_tool_uses_20250919"
+    }
+  ]
+});
 var requestOptionsFor = (params) => {
   const raw = params.providerOptions?.anthropic;
   if (raw === undefined)
@@ -6828,16 +6857,20 @@ var buildRequestBody3 = (params, configuredMax, configCaching) => {
     ] : params.systemPrompt;
   }
   const clientTools = params.tools?.map(mapToolDefinition2) ?? [];
-  if (clientTools.length > 0) {
-    if (caching) {
-      clientTools[clientTools.length - 1] = {
-        ...clientTools[clientTools.length - 1],
-        cache_control: { type: "ephemeral" }
-      };
-    }
+  const deferring = clientTools.some((tool) => tool.defer_loading === true);
+  const lastLoaded = clientTools.findLastIndex((tool) => tool.defer_loading !== true);
+  if (caching && lastLoaded >= 0) {
+    clientTools[lastLoaded] = {
+      ...clientTools[lastLoaded],
+      cache_control: { type: "ephemeral" }
+    };
   }
   const serverTools = (options.serverTools ?? []).map(mapServerTool);
-  const tools = [...clientTools, ...serverTools];
+  const tools = [
+    ...clientTools,
+    ...deferring ? [TOOL_SEARCH_TOOL] : [],
+    ...serverTools
+  ];
   if (tools.length > 0) {
     body.tools = tools;
     if (params.toolChoice === "auto" || params.toolChoice === "none") {
@@ -6851,6 +6884,9 @@ var buildRequestBody3 = (params, configuredMax, configCaching) => {
   if (params.stopSequences && params.stopSequences.length > 0) {
     body.stop_sequences = params.stopSequences;
   }
+  if (params.toolResultClearing) {
+    body.context_management = contextManagementFor(params.toolResultClearing);
+  }
   const mode = params.reasoning && params.reasoning.effort !== "none" ? anthropicReasoningMode(params.model) : "none";
   if (params.reasoning?.effort === "none")
     body.thinking = { type: "disabled" };
@@ -7297,6 +7333,11 @@ var fetchAndStream = async function* (baseUrl, config, params, configuredMax, pr
   const suppliedHeaders = typeof config.headers === "function" ? await config.headers(params) : config.headers ?? {};
   const requestHeaders = new Headers(suppliedHeaders);
   requestHeaders.set("Content-Type", "application/json");
+  if (body.context_management !== undefined) {
+    const betas = (requestHeaders.get("anthropic-beta") ?? "").split(",").map((beta) => beta.trim()).filter(Boolean);
+    if (!betas.includes(CONTEXT_MANAGEMENT_BETA))
+      requestHeaders.set("anthropic-beta", [...betas, CONTEXT_MANAGEMENT_BETA].join(","));
+  }
   if (config.authStyle === "bearer") {
     requestHeaders.set("Authorization", `Bearer ${token}`);
   } else {
@@ -7365,7 +7406,12 @@ var anthropic = (config) => {
     const hosted = tools.filter((tool) => isRecord5(tool) && typeof tool.type === "string" && /^(web_search_|web_fetch_|code_execution_|bash_code_execution_|text_editor_code_execution_|tool_search_tool_)/u.test(tool.type));
     const scope = hosted.length > 0 || body.mcp_servers !== undefined ? "caller-input" : "request";
     if (hosted.length > 0) {
-      const clientTools = tools.filter((tool) => !hosted.includes(tool));
+      const clientTools = tools.filter((tool) => !hosted.includes(tool)).map((tool) => {
+        if (!isRecord5(tool) || tool.defer_loading === undefined)
+          return tool;
+        const { defer_loading: _deferred, ...loaded } = tool;
+        return loaded;
+      });
       if (clientTools.length)
         counted.tools = clientTools;
       else
@@ -9197,5 +9243,5 @@ export {
   xai
 };
 
-//# debugId=94F48F9A5CBF872A64756E2164756E21
+//# debugId=9A889A121344253764756E2164756E21
 //# sourceMappingURL=index.js.map