@absolutejs/mcp 0.13.0 → 0.14.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.14.0 — 2026-09-11
+
+### Added
+
+- **Add explicit credit-budget envelopes for durable prepaid MCP work**
+
 ## 0.13.0 — 2026-09-11
 
 ### Added

package/README.md

@@ -423,3 +423,7 @@ deployments can route discovery through `@absolutejs/egress`.
 
 Business Source License 1.1 — see [LICENSE](./LICENSE). Converts to Apache 2.0
 on the Change Date.
+
+### Budgeted prepaid work
+
+`budgetedMcpTool({ tool, execute })` adds a stable work ID, an explicit maximum-credit budget, and a `paid_access` commerce requirement. The executor must bind the account and use durable claims and settlement (for example `@absolutejs/billing/credit-work`). Only wrap tools whose effects and metering finish inside the execution scope. Deferred jobs need a durable budget handoff. Task-required, authorization-mapped, and already commerce-tagged tools are rejected rather than silently changing their enforcement contracts.

package/changelog.json

@@ -2,6 +2,16 @@
 	"contract": 1,
 	"name": "@absolutejs/mcp",
 	"releases": [
+		{
+			"changes": [
+				{
+					"kind": "added",
+					"summary": "Add explicit credit-budget envelopes for durable prepaid MCP work"
+				}
+			],
+			"date": "2026-09-11",
+			"version": "0.14.0"
+		},
 		{
 			"changes": [
 				{

package/dist/index.js

@@ -1964,12 +1964,50 @@ var createPostgresMcpSessionStore = ({
     }
   };
 };
+// src/budgetedTool.ts
+var budgetedMcpTool = (options) => {
+  const { tool } = options;
+  if (tool.authorization || tool.commerce || tool.coaz || tool.taskSupport === "required")
+    throw new Error("Budget wrapping needs an ordinary tool; preserve its authorization and commerce contract separately");
+  return {
+    ...tool,
+    annotations: { ...tool.annotations, readOnlyHint: false },
+    outputSchema: undefined,
+    commerce: { action: "paid_access", categories: ["usage_credits"] },
+    taskSupport: "forbidden",
+    description: `${tool.description}
+Provide a stable requestId and the maximum service credits this work may charge. Retry with the same ID and exact input to retrieve existing work; never invent a new ID to retry an uncertain effect.`,
+    inputSchema: {
+      type: "object",
+      additionalProperties: false,
+      required: ["requestId", "maxCredits", "input"],
+      properties: {
+        requestId: { type: "string", minLength: 1, maxLength: 128 },
+        maxCredits: {
+          type: "integer",
+          minimum: 1,
+          maximum: Number.MAX_SAFE_INTEGER
+        },
+        input: tool.inputSchema
+      }
+    },
+    handler: async (args, context) => {
+      if (args === null || typeof args !== "object" || Array.isArray(args))
+        throw new Error("Invalid credit work request");
+      const { requestId, maxCredits, input } = args;
+      if (typeof requestId !== "string" || !requestId || requestId.length > 128 || typeof maxCredits !== "number" || !Number.isSafeInteger(maxCredits) || maxCredits < 1 || !("input" in args))
+        throw new Error("A request ID, positive credit budget, and input are required");
+      return options.execute({ requestId, maxCredits, input }, async () => tool.handler(input, context));
+    }
+  };
+};
 export {
   COMMERCE_POLICY_SOURCES,
   COMMERCE_POLICY_VERSION,
   FEEDBACK_INSTRUCTIONS,
   MCP_LATEST_PROTOCOL_VERSION,
   McpClientError,
+  budgetedMcpTool,
   createCreditBalanceTool,
   createMcpAuthorizationRequest,
   createMcpClient,

package/dist/manifest.js

@@ -2861,9 +2861,7 @@ var manifest = defineManifest()({
     tagline: "Let AI assistants connect to your site and use its tools."
   },
   requires: {
-    peers: [
-      { name: "elysia", range: "^2.0.0-beta.6", reason: "plugin host" }
-    ]
+    peers: [{ name: "elysia", range: "^2.0.0-beta.6", reason: "plugin host" }]
   },
   settings: Type.Object({
     instructions: Type.Optional(Type.String({

package/dist/src/budgetedTool.d.ts

@@ -0,0 +1,13 @@
+import type { McpTool, McpToolReturn } from "./types";
+export type McpCreditWorkRequest = {
+    requestId: string;
+    maxCredits: number;
+    input: unknown;
+};
+/** Wrap a synchronous tool with an explicit per-work credit budget. The executor
+ * must bind the caller, claim durable work, track usage, and persist its result.
+ * Do not wrap deferred jobs without transferring their budget to the worker. */
+export declare const budgetedMcpTool: (options: {
+    tool: McpTool;
+    execute: (request: McpCreditWorkRequest, run: () => Promise<McpToolReturn>) => Promise<McpToolReturn>;
+}) => McpTool;

package/dist/src/index.d.ts

@@ -44,3 +44,4 @@ export { createPostgresMcpSessionStore, createPostgresMcpTaskStore, mcpPostgresS
 export type { McpAgencyOptions, McpAudioContent, McpElicitAnswer, McpElicitationRequest, McpElicitBus, McpElicitResult, McpFormElicitationRequest, McpSessionStore, McpAuthResult, McpCallGate, McpCallMeta, McpContent, McpImageContent, McpPromptArgument, McpPromptDefinition, McpPrompts, McpResource, McpResourceLink, McpResources, McpServerConfig, McpServerInfo, McpTextContent, McpTask, McpTaskStatus, McpTaskStore, McpTasksOptions, McpTool, McpToolAnnotations, McpToolCallContext, McpToolContext, McpToolRegistry, McpToolResult, McpToolReturn, McpUrlElicitationRequest, } from "./types";
 export * from "./commerce";
 export { createCreditBalanceTool, type McpCreditBalance } from "./creditStatus";
+export { budgetedMcpTool, type McpCreditWorkRequest } from "./budgetedTool";

package/package.json

@@ -72,5 +72,5 @@
     "prepublishOnly": "bun run check:package"
   },
   "types": "./dist/src/index.d.ts",
-  "version": "0.13.0"
+  "version": "0.14.0"
 }