@absolutejs/mcp 0.24.0 → 0.25.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.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

package/changelog.json

@@ -2,6 +2,20 @@
 	"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": [
 				{

package/dist/index.js

@@ -2917,11 +2917,32 @@ var createBackgroundWorkTools = (options) => {
       }
     }
   };
+  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} 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.`,
+        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");

package/dist/src/backgroundWork.d.ts

@@ -1,5 +1,11 @@
 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";
@@ -16,6 +22,7 @@ export declare const createBackgroundWorkResult: (requestId: string, work: McpBa
 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

@@ -55,3 +55,4 @@ export { createSetupSelectionTools, projectSetupSelection, type 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.24.0"
+  "version": "0.25.0"
 }