@absolutejs/mcp 0.22.0 → 0.24.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.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
+
+- **Preserve saved credit work results in identical text and structured host responses** (`createCreditWorkResult`)
+
 ## 0.22.0 — 2026-09-13
 
 ### Added

package/README.md

@@ -437,3 +437,47 @@ on the Change Date.
 ## Interactive MCP Apps
 
 `createBillingApps()` adds reusable read-only credit, usage and receipt views with the official browser SDK. Apps capability negotiation, guarded resources and text fallbacks live in the package. See [MCP Apps](docs/mcp-apps.md) for integration, session migration, CSP restrictions and host validation boundaries.
+
+### Saved credit-work results
+
+Use `createCreditWorkResult(requestId, work)` for initial completion, duplicate
+requests and read-only recovery. Pass the account-bound saved `budget`, `charged`,
+`status` and `result`; extra database fields are not projected. Both MCP `content`
+and `structuredContent` carry the same JSON envelope:
+
+```json
+{
+  "requestId": "proposal-1",
+  "status": "completed",
+  "maxCredits": 1,
+  "creditsCharged": 0,
+  "result": { "actionId": "action-1", "status": "proposed" }
+}
+```
+
+Read the tool outcome under `result`; the outer `status` describes credit work,
+not action approval or delivery. Saved JSON is decoded once; plain text remains
+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,29 @@
 	"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": [
+				{
+					"kind": "added",
+					"summary": "Preserve saved credit work results in identical text and structured host responses",
+					"symbols": [
+						"createCreditWorkResult"
+					]
+				}
+			],
+			"date": "2026-09-13",
+			"version": "0.23.0"
+		},
 		{
 			"changes": [
 				{

package/dist/index.js

@@ -2853,6 +2853,84 @@ Provide a stable requestId and the maximum service credits this work may charge.
     }
   };
 };
+// src/creditWorkResult.ts
+var savedResult = (value) => {
+  if (value === null)
+    return null;
+  try {
+    return JSON.parse(value);
+  } catch {
+    return value;
+  }
+};
+var createCreditWorkResult = (requestId, work) => {
+  if (typeof requestId !== "string" || !requestId || requestId.length > 128 || !Number.isSafeInteger(work.budget) || work.budget < 0 || !Number.isSafeInteger(work.charged) || work.charged < 0 || work.charged > work.budget || !["running", "completed", "failed"].includes(work.status) || work.result !== null && typeof work.result !== "string")
+    throw new Error("Invalid saved credit work");
+  const summary = {
+    requestId,
+    status: work.status,
+    maxCredits: work.budget,
+    creditsCharged: work.charged,
+    result: savedResult(work.result),
+    ...work.result === null ? {
+      message: "No saved result is available. Poll get_credit_work with the same requestId; do not restart it with a new ID."
+    } : {}
+  };
+  return {
+    content: [{ type: "text", text: JSON.stringify(summary) }],
+    structuredContent: summary,
+    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,
@@ -2863,11 +2941,14 @@ export {
   budgetedMcpTool,
   clientSupportsMcpApps,
   createActionWorkflowTools,
+  createBackgroundWorkResult,
+  createBackgroundWorkTools,
   createBillingApps,
   createBillingManagementTool,
   createBillingReportTools,
   createCheckoutHandoffTool,
   createCreditBalanceTool,
+  createCreditWorkResult,
   createMcpAuthorizationRequest,
   createMcpClient,
   createMcpHandler,

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/creditWorkResult.d.ts

@@ -0,0 +1,13 @@
+import type { McpToolResult } from "./types";
+/** Public projection of account-bound, persisted work. Never pass an unfiltered
+ * database row or provider response as the saved result. */
+export type McpCreditWorkSnapshot = {
+    budget: number;
+    charged: number;
+    status: "running" | "completed" | "failed";
+    result: string | null;
+};
+/** Keep text-only and structured-only hosts on the same result contract. This
+ * pure formatter never starts, retries, approves, or settles work. Use it for
+ * initial completion, duplicate requests, and read-only recovery alike. */
+export declare const createCreditWorkResult: (requestId: string, work: McpCreditWorkSnapshot) => McpToolResult;

package/dist/src/index.d.ts

@@ -52,4 +52,6 @@ export { createBillingApps } from "./billingApps";
 export { createWorkflowApps } from "./workflowApps";
 export { createWorkflowTools, projectSetupStatus, projectWorkPreview, type McpSetupStatus, type McpWorkPreview, type McpWorkPreviewRequest, } from "./workflowTools";
 export { createSetupSelectionTools, projectSetupSelection, type SetupSelection, type SetupConfirmation, type SetupOption, } from "./setupSelection";
-export { createActionWorkflowTools, projectActionReview, projectActionJob, type ActionReview, type ActionConfirmation, type ActionJob } from "./actionWorkflow";
+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.22.0"
+  "version": "0.24.0"
 }