@absolutejs/ai 0.5.0 → 0.6.1

package/CHANGELOG.md

@@ -6,6 +6,18 @@ 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.1 — 2026-10-20
+
+### Added
+
+- **Add typed forms and shared task next actions for top-up continuation** (`FormField`, `formCard`, `parseFormSpec`, `prepareFormSubmission`, `FormSubmission`, `BackgroundWorkCard`, `backgroundWorkNextAction`)
+
+## 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/README.md

@@ -575,3 +575,18 @@ can prevent `done`, and no adapter can reconstruct usage the provider never sent
 `onUsage` still reports only complete usage, once per instrumented stream. Keep
 credit reservations separate from charges and reconcile unknown outcomes in the
 host application. The package does not invent token counts or decide billing policy.
+
+### Typed forms and background work
+
+Form fields support `valueType` (`string`, `number`, `integer`, `boolean`). For a
+numeric dropdown use `type: "select", options: ["3", "10"], valueType: "integer"`.
+All hosts should call `prepareFormSubmission(form, values)` before invoking the
+bound tool: it returns typed input or field errors without discarding answers.
+The host must still validate the complete tool schema and apply authorization.
+Legacy dropdowns retain string values; migrate numeric fields explicitly.
+
+`BackgroundWorkCard` and `backgroundWorkNextAction` provide framework-neutral
+progress/CTA semantics. A funding pause offers Add credits; only confirmed
+funding changes it to Continue research. Completed work offers View results;
+uncertain work offers Check status, never replay. The host persists the work ID,
+polls or subscribes to actual progress, and binds actions to authenticated routes.

package/changelog.json

@@ -2,6 +2,42 @@
 	"contract": 1,
 	"name": "@absolutejs/ai",
 	"releases": [
+		{
+			"changes": [
+				{
+					"kind": "added",
+					"summary": "Add typed forms and shared task next actions for top-up continuation",
+					"symbols": [
+						"FormField",
+						"formCard",
+						"parseFormSpec",
+						"prepareFormSubmission",
+						"FormSubmission",
+						"BackgroundWorkCard",
+						"backgroundWorkNextAction"
+					]
+				}
+			],
+			"date": "2026-10-20",
+			"version": "0.6.1"
+		},
+		{
+			"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 }
 });
@@ -2744,6 +2751,11 @@ var parseFormField = (raw) => {
   if (!name || !label || !type)
     return null;
   const field = { label, name, type };
+  if (raw.valueType !== undefined) {
+    if (!["string", "number", "integer", "boolean"].includes(String(raw.valueType)))
+      return null;
+    field.valueType = raw.valueType;
+  }
   const placeholder = cleanString(raw.placeholder, LABEL_MAX_CHARS);
   if (placeholder)
     field.placeholder = placeholder;
@@ -3115,6 +3127,11 @@ var formCard = {
               items: { type: "string" },
               type: "array"
             },
+            valueType: {
+              enum: ["string", "number", "integer", "boolean"],
+              type: "string",
+              description: "Submitted scalar type, especially integer for numeric select options"
+            },
             placeholder: { type: "string" },
             required: { type: "boolean" },
             type: { enum: [...FORM_FIELD_TYPES], type: "string" },
@@ -3621,6 +3638,68 @@ var renderChartSvg = (spec, options = {}) => {
   const body = spec.type === "donut" ? donutSvg(spec, frame) : cartesianSvg(spec, frame);
   return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${width} ${height}" role="img" aria-label="${escapeXml(spec.title)}" font-family="${FONT}"><rect width="${width}" height="${height}" fill="${theme.surface}" rx="12"/>${spec.type === "donut" ? headerSvg({ ...spec, series: [] }, frame) : headerSvg(spec, frame)}${body}</svg>`;
 };
+// src/ai/ui/formSubmission.ts
+var prepareFormSubmission = (form, values) => {
+  const input = { ...form.submit.input };
+  const errors = {};
+  for (const field of form.fields) {
+    if (["__proto__", "constructor", "prototype"].includes(field.name)) {
+      errors.form = "Invalid field name";
+      continue;
+    }
+    const raw = values[field.name];
+    if (raw === undefined || raw === null || typeof raw === "string" && !raw.trim()) {
+      if (field.required)
+        errors[field.name] = "This field is required";
+      continue;
+    }
+    if (field.type === "select" && !field.options?.includes(String(raw))) {
+      errors[field.name] = "Choose one of the available options";
+      continue;
+    }
+    const type = field.valueType ?? (field.type === "number" ? "number" : field.type === "checkbox" ? "boolean" : "string");
+    let value = raw;
+    if (type === "number" || type === "integer") {
+      value = typeof raw === "number" ? raw : typeof raw === "string" && /^[+-]?(?:\d+\.?\d*|\.\d+)(?:e[+-]?\d+)?$/iu.test(raw.trim()) ? Number(raw) : NaN;
+      if (typeof value !== "number" || !Number.isFinite(value) || type === "integer" && !Number.isSafeInteger(value)) {
+        errors[field.name] = type === "integer" ? "Enter a whole number" : "Enter a number";
+        continue;
+      }
+    } else if (type === "boolean") {
+      if (![true, false, "true", "false"].includes(raw)) {
+        errors[field.name] = "Choose yes or no";
+        continue;
+      }
+      value = raw === true || raw === "true";
+      if (field.type === "checkbox" && field.required && !value) {
+        errors[field.name] = "This field is required";
+        continue;
+      }
+    } else {
+      if (typeof raw !== "string") {
+        errors[field.name] = "Enter text";
+        continue;
+      }
+      value = field.type === "password" ? raw : raw.trim();
+    }
+    input[field.name] = value;
+  }
+  return Object.keys(errors).length ? { ok: false, errors } : { ok: true, input };
+};
+// src/ai/ui/backgroundWork.ts
+var backgroundWorkNextAction = (work) => {
+  if (!work.workId || !Number.isSafeInteger(work.totalSteps) || work.totalSteps < 1 || !Number.isSafeInteger(work.completedSteps) || work.completedSteps < 0 || work.completedSteps > work.totalSteps)
+    throw new Error("Invalid background work progress");
+  if (work.status === "completed")
+    return { kind: "view_results", label: "View results" };
+  if (work.status === "paused" && work.pauseReason === "funding")
+    return work.fundingConfirmed ? { kind: "continue", label: "Continue research" } : { kind: "top_up", label: "Add credits" };
+  if (work.status === "unknown")
+    return { kind: "check_status", label: "Check status" };
+  if (work.hasResults)
+    return { kind: "view_results", label: "View saved results" };
+  return { kind: "check_status", label: "Check status" };
+};
 // src/ai/conversationManager.ts
 var NOT_FOUND2 = -1;
 var TITLE_MAX_LENGTH2 = 80;
@@ -6716,10 +6795,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 +6929,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 +6956,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 +7405,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 +7478,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
@@ -9114,6 +9232,7 @@ export {
   aiChat,
   alibaba,
   anthropic,
+  backgroundWorkNextAction,
   chartCard,
   choiceCard,
   configureProviderResilience,
@@ -9177,6 +9296,7 @@ export {
   planCard,
   prepareAITextInput,
   prepareAITextInputStep,
+  prepareFormSubmission,
   providerStatusPage,
   remoteProvider,
   renderChartSvg,
@@ -9197,5 +9317,5 @@ export {
   xai
 };
 
-//# debugId=94F48F9A5CBF872A64756E2164756E21
+//# debugId=75EDBEC482A1645464756E2164756E21
 //# sourceMappingURL=index.js.map