@absolutejs/ai 0.6.0 → 0.6.1

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.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

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,25 @@
 	"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": [
 				{

package/dist/ai/index.js

@@ -2751,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;
@@ -3122,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" },
@@ -3628,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;
@@ -9160,6 +9232,7 @@ export {
   aiChat,
   alibaba,
   anthropic,
+  backgroundWorkNextAction,
   chartCard,
   choiceCard,
   configureProviderResilience,
@@ -9223,6 +9296,7 @@ export {
   planCard,
   prepareAITextInput,
   prepareAITextInputStep,
+  prepareFormSubmission,
   providerStatusPage,
   remoteProvider,
   renderChartSvg,
@@ -9243,5 +9317,5 @@ export {
   xai
 };
 
-//# debugId=9A889A121344253764756E2164756E21
+//# debugId=75EDBEC482A1645464756E2164756E21
 //# sourceMappingURL=index.js.map