@absolutejs/mcp 0.23.0 → 0.25.0

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.25.0 — 2026-09-13
+
+### Added
+
+- **Add estimate-based background work admission while preserving exact-ID recovery and hard charge caps.** (`McpBackgroundWorkEstimate`, `createBackgroundWorkTools`)
+
+## 0.24.0 — 2026-09-13
+
+### Added
+
+- **Add durable background work launch and read-only recovery tools with matching text and structured progress.**
+
 ## 0.23.0 — 2026-09-13
 
 ### Added

package/README.md

@@ -461,3 +461,23 @@ a string, and serialized MCP results remain nested without discarding content.
 The formatter never retries work. A missing saved result carries a same-ID polling
 instruction. Bind account identity and authorization before retrieving the saved
 work; this helper does not authorize access or filter the tool's saved payload.
+
+## Budgeted background work
+
+`createBackgroundWorkTools({ description, inputSchema, start, read })` exposes
+`start_background_work` with a stable requestId and maximum service credits, plus
+read-only `get_background_work` recovery. Omit `start` to support recovery at zero
+credits or while rollout is disabled. Account ownership must come from the
+authenticated caller, never tool arguments.
+
+The start adapter must atomically reserve credits, bind immutable work and enqueue
+a durable job; duplicate IDs must return existing work and reject changed input or
+budget. The read adapter returns public results and accounting only, without
+starting, settling or retrying work. `createBackgroundWorkResult` projects the
+same progress, results and spend in text and structured content for broad host
+support. In uncertain states, retain the reservation and do not create a new ID
+to repeat work.
+
+Start is classified as `paid_access`; recovery is `entitlement_status`. Existing
+commerce host reviews and account/client restrictions still apply. These tools
+do not enable embedded checkout or override any host's commerce rules.

package/changelog.json

@@ -2,6 +2,30 @@
 	"contract": 1,
 	"name": "@absolutejs/mcp",
 	"releases": [
+		{
+			"changes": [
+				{
+					"kind": "added",
+					"summary": "Add estimate-based background work admission while preserving exact-ID recovery and hard charge caps.",
+					"symbols": [
+						"McpBackgroundWorkEstimate",
+						"createBackgroundWorkTools"
+					]
+				}
+			],
+			"date": "2026-09-13",
+			"version": "0.25.0"
+		},
+		{
+			"changes": [
+				{
+					"kind": "added",
+					"summary": "Add durable background work launch and read-only recovery tools with matching text and structured progress."
+				}
+			],
+			"date": "2026-09-13",
+			"version": "0.24.0"
+		},
 		{
 			"changes": [
 				{

package/dist/index.js

@@ -2882,6 +2882,76 @@ var createCreditWorkResult = (requestId, work) => {
     isError: work.status === "failed"
   };
 };
+// src/backgroundWork.ts
+var createBackgroundWorkResult = (requestId, work) => {
+  if (!requestId || requestId.length > 128 || !Number.isSafeInteger(work.budget) || work.budget < 1 || !Number.isSafeInteger(work.charged) || work.charged < 0 || work.charged > work.budget || !Number.isSafeInteger(work.totalSteps) || work.totalSteps < 1 || !Array.isArray(work.results) || work.results.length > work.totalSteps || typeof work.settled !== "boolean" || !["queued", "running", "completed", "stopped", "failed", "unknown"].includes(work.status))
+    throw new Error("Invalid background work snapshot");
+  const summary = {
+    requestId,
+    status: work.status,
+    maxCredits: work.budget,
+    creditsCharged: work.charged,
+    settled: work.settled,
+    totalSteps: work.totalSteps,
+    completedSteps: work.results.length,
+    results: work.results,
+    message: work.status === "unknown" ? "A step has an uncertain outcome. Saved results remain available; credits stay held pending reconciliation. Do not start another job to retry it." : "Read get_background_work with this requestId to recover saved progress and spend. Reading never starts or repeats work."
+  };
+  return { content: [{ type: "text", text: JSON.stringify(summary) }], structuredContent: summary, isError: work.status === "failed" || work.status === "unknown" };
+};
+var createBackgroundWorkTools = (options) => {
+  const tools = {
+    get_background_work: {
+      description: "Recover this account's saved background work, partial results and credit spend. Read-only; available without credits. Never restarts a provider call.",
+      annotations: { readOnlyHint: true },
+      commerce: { action: "entitlement_status", categories: ["usage_credits"] },
+      inputSchema: { type: "object", additionalProperties: false, required: ["requestId"], properties: { requestId: { type: "string", minLength: 1, maxLength: 128 } } },
+      handler: async (args) => {
+        const requestId = args && typeof args === "object" && !Array.isArray(args) ? Reflect.get(args, "requestId") : undefined;
+        if (typeof requestId !== "string" || !requestId || requestId.length > 128)
+          throw new Error("A request ID is required");
+        const work = await options.read(requestId);
+        if (!work)
+          return { content: [{ type: "text", text: "No background work found for this account and request ID." }], isError: true };
+        return createBackgroundWorkResult(requestId, work);
+      }
+    }
+  };
+  const estimate = options.estimate;
+  if (estimate)
+    tools.estimate_background_work = {
+      description: "Estimate service credits for a background plan without reserving credits or starting work. The minimum admits one step; the total estimates the whole plan. Actual usage varies. Get the user's approval for the maximum before starting; never silently increase it.",
+      annotations: { readOnlyHint: true },
+      commerce: { action: "paid_access", categories: ["usage_credits"] },
+      inputSchema: options.inputSchema,
+      handler: async (input) => {
+        const value = await estimate(input);
+        if (![value.minimumCredits, value.estimatedCredits, value.totalSteps].every(Number.isSafeInteger) || value.minimumCredits < 1 || value.estimatedCredits < value.minimumCredits || value.totalSteps < 1 || typeof value.assumptions !== "string" || !value.assumptions)
+          throw new Error("Invalid background work estimate");
+        const summary = {
+          minimumCredits: value.minimumCredits,
+          estimatedCredits: value.estimatedCredits,
+          totalSteps: value.totalSteps,
+          assumptions: value.assumptions,
+          message: "Estimate only, not a quote or guarantee. No credits reserved and no work started. Admission is checked again at start and before each step; work can stop with partial results. The approved maximum charge is never increased."
+        };
+        return { content: [{ type: "text", text: JSON.stringify(summary) }], structuredContent: summary };
+      }
+    };
+  const start = options.start;
+  if (start)
+    tools.start_background_work = budgetedMcpTool({
+      tool: {
+        description: `${options.description} Use estimate_background_work when available before asking for a budget. Launch bounded background work only after the user agrees to the plan and maximum credits. Return the requestId promptly; poll get_background_work for progress.`,
+        inputSchema: options.inputSchema,
+        handler: async () => {
+          throw new Error("Background work must use durable dispatch");
+        }
+      },
+      execute: async (request) => createBackgroundWorkResult(request.requestId, await start(request))
+    });
+  return tools;
+};
 export {
   COMMERCE_POLICY_SOURCES,
   COMMERCE_POLICY_VERSION,
@@ -2892,6 +2962,8 @@ export {
   budgetedMcpTool,
   clientSupportsMcpApps,
   createActionWorkflowTools,
+  createBackgroundWorkResult,
+  createBackgroundWorkTools,
   createBillingApps,
   createBillingManagementTool,
   createBillingReportTools,

package/dist/src/backgroundWork.d.ts

@@ -0,0 +1,28 @@
+import { type McpCreditWorkRequest } from "./budgetedTool";
+import type { McpTool, McpToolRegistry, McpToolResult } from "./types";
+export type McpBackgroundWorkEstimate = {
+    minimumCredits: number;
+    estimatedCredits: number;
+    totalSteps: number;
+    assumptions: string;
+};
+/** Public output only. Adapters must scope reads to the authenticated account. */
+export type McpBackgroundWorkSnapshot = {
+    status: "queued" | "running" | "completed" | "stopped" | "failed" | "unknown";
+    budget: number;
+    charged: number;
+    settled: boolean;
+    totalSteps: number;
+    results: unknown[];
+};
+export declare const createBackgroundWorkResult: (requestId: string, work: McpBackgroundWorkSnapshot) => McpToolResult;
+/** Durable dispatch is the adapter's responsibility: atomically reserve, bind
+ * and enqueue before returning. Start must deduplicate exact IDs/input/budget.
+ * Omit start to expose account recovery without allowing new paid work. */
+export declare const createBackgroundWorkTools: (options: {
+    description: string;
+    inputSchema: McpTool["inputSchema"];
+    estimate?: (input: unknown) => Promise<McpBackgroundWorkEstimate>;
+    start?: (request: McpCreditWorkRequest) => Promise<McpBackgroundWorkSnapshot>;
+    read: (requestId: string) => Promise<McpBackgroundWorkSnapshot | null>;
+}) => McpToolRegistry;

package/dist/src/index.d.ts

@@ -54,3 +54,5 @@ export { createWorkflowTools, projectSetupStatus, projectWorkPreview, type McpSe
 export { createSetupSelectionTools, projectSetupSelection, type SetupSelection, type SetupConfirmation, type SetupOption, } from "./setupSelection";
 export { createActionWorkflowTools, projectActionReview, projectActionJob, type ActionReview, type ActionConfirmation, type ActionJob, } from "./actionWorkflow";
 export { createCreditWorkResult, type McpCreditWorkSnapshot, } from "./creditWorkResult";
+export { createBackgroundWorkTools, createBackgroundWorkResult, type McpBackgroundWorkSnapshot } from "./backgroundWork";
+export type { McpBackgroundWorkEstimate } from "./backgroundWork";

package/docs/commerce-host-rules.md

@@ -368,3 +368,18 @@ bounded work until their reservation and recovery lifecycle is implemented.
 This documentation update changes no runtime API, profile, feature flag or
 published package version. It is available in the shared repository and will
 ship with the next package release through the existing documentation allowlist.
+
+### Background research estimates
+
+`createBackgroundWorkTools({ estimate, start, read, ... })` optionally exposes
+`estimate_background_work`. Its adapter returns minimum credits for one step,
+estimated total credits, total steps and explicit assumptions. Public output is
+identical in text and structured hosts, and omits adapter-private fields. No
+provider work or reservation belongs in the estimate adapter.
+
+Estimates use `paid_access` commerce policy, so a restricted host cannot use this
+as a pricing/purchase workaround. Obtain user agreement to the exact plan and
+maximum before start. Server-side start must reevaluate admission atomically;
+never silently raise a maximum. Saved-work reads remain separate and credit-free.
+An estimate is advisory, not an expiring quote or guaranteed cost. Bind input,
+account and maximum durably; exact-ID recovery must not depend on current pricing.

package/package.json

@@ -90,5 +90,5 @@
     "canary:checkout": "bun canary/checkout.ts"
   },
   "types": "./dist/src/index.d.ts",
-  "version": "0.23.0"
+  "version": "0.25.0"
 }