@absolutejs/mcp 0.23.0 → 0.24.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.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,16 @@
 	"contract": 1,
 	"name": "@absolutejs/mcp",
 	"releases": [
+		{
+			"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,55 @@ 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 start = options.start;
+  if (start)
+    tools.start_background_work = budgetedMcpTool({
+      tool: {
+        description: `${options.description} 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 +2941,8 @@ export {
   budgetedMcpTool,
   clientSupportsMcpApps,
   createActionWorkflowTools,
+  createBackgroundWorkResult,
+  createBackgroundWorkTools,
   createBillingApps,
   createBillingManagementTool,
   createBillingReportTools,

package/dist/src/backgroundWork.d.ts

@@ -0,0 +1,21 @@
+import { type McpCreditWorkRequest } from "./budgetedTool";
+import type { McpTool, McpToolRegistry, McpToolResult } from "./types";
+/** 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"];
+    start?: (request: McpCreditWorkRequest) => Promise<McpBackgroundWorkSnapshot>;
+    read: (requestId: string) => Promise<McpBackgroundWorkSnapshot | null>;
+}) => McpToolRegistry;

package/dist/src/index.d.ts

@@ -54,3 +54,4 @@ 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";

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.24.0"
 }