@abinnovision/payloadcms-mcpx 2.0.0-beta.8 → 2.0.0

package/dist/api-keys/capability-matrix.mjs

@@ -1,47 +1,25 @@
-import { CAPABILITIES_FIELD, canCreate, canPublish, canWrite, isLiveWrite } from "../capabilities.mjs";
+import { CAPABILITIES_FIELD, STORED_OPERATIONS } from "../capabilities.mjs";
 //#region src/api-keys/capability-matrix.ts
 /**
 * The group's `admin.description`, rendered by the matrix in Payload's
-* description slot. It explains both markings in the table: an unticked box
-* and a dash.
-*/ const CAPABILITIES_DESCRIPTION = "What this key may do. An unticked box is a refusal, and a dash means the plugin config does not expose that operation at all.";
-/**
-* The operations a collection or global can expose. The generated checkboxes
-* and the matrix column headers share this wording.
-*/ const CAPABILITY_OPERATIONS = [
-	{
-		id: "read",
-		label: "Read",
-		description: "Describe, find and read."
-	},
-	{
-		id: "write",
-		label: "Write",
-		description: "Create, patch and validate drafts."
-	},
-	{
-		id: "publish",
-		label: "Publish",
-		description: "Promote the current draft to what the public sees."
-	}
-];
-const UPLOAD_HINT = "Files are uploaded in the admin panel.";
-const LIVE_HINT = "Writes go live immediately.";
-const hintFor = (entity) => {
-	const hints = [canWrite(entity) && !canCreate(entity) ? UPLOAD_HINT : void 0, isLiveWrite(entity) ? LIVE_HINT : void 0].filter((hint) => hint !== void 0);
-	return hints.length > 0 ? { hint: hints.join(" ") } : {};
-};
+* description slot. It explains how to read the controls.
+*/ const CAPABILITIES_DESCRIPTION = "What this key may do. Each level includes the ones before it, and a missing segment means the plugin config does not expose it. A shield means this key's user approves each call.";
 const toRow = (entity) => ({
 	fieldName: entity.fieldName,
-	label: entity.slug,
+	slug: entity.slug,
 	read: entity.read,
-	write: canWrite(entity),
-	publish: canPublish(entity),
-	...hintFor(entity)
+	write: entity.write,
+	publish: entity.publish,
+	delete: entity.delete,
+	deleteUnattended: entity.deleteUnattended,
+	...entity.liveWrite ? { live: true } : {}
 });
 /**
+* The operations a row exposes, in stored order.
+*/ const rowOperations = (row) => STORED_OPERATIONS.filter((operation) => row[operation.id]);
+/**
 * The single description of what the config exposes. `createCapabilityFields`
-* and the admin component both draw from it, so a cell cannot appear without a
+* and the admin component both draw from it, so a control cannot appear without a
 * field behind it.
 */ const createCapabilityMatrix = (options) => ({
 	collections: options.collections.map(toRow),
@@ -53,6 +31,8 @@ const toRow = (entity) => ({
 });
 const cellPath = (basePath, namespace, fieldName, operation) => `${basePath}.${namespace}.${fieldName}.${operation}`;
 const toolPath = (basePath, name) => `${basePath}.tools.${name}`;
-/** Every path the matrix can address, in a stable order. */ const capabilityPaths = (matrix, basePath = CAPABILITIES_FIELD) => [...["collections", "globals"].flatMap((namespace) => matrix[namespace].flatMap((row) => CAPABILITY_OPERATIONS.filter((operation) => row[operation.id]).map((operation) => cellPath(basePath, namespace, row.fieldName, operation.id)))), ...matrix.tools.map((tool) => toolPath(basePath, tool.name))];
+/**
+* Every path the matrix can address, in a stable order.
+*/ const capabilityPaths = (matrix, basePath = CAPABILITIES_FIELD) => [...["collections", "globals"].flatMap((namespace) => matrix[namespace].flatMap((row) => rowOperations(row).map((operation) => cellPath(basePath, namespace, row.fieldName, operation.id)))), ...matrix.tools.map((tool) => toolPath(basePath, tool.name))];
 //#endregion
-export { CAPABILITIES_DESCRIPTION, CAPABILITY_OPERATIONS, capabilityPaths, cellPath, createCapabilityMatrix, toolPath };
+export { CAPABILITIES_DESCRIPTION, capabilityPaths, cellPath, createCapabilityMatrix, rowOperations, toolPath };

package/dist/api-keys/collection.mjs

@@ -1,11 +1,12 @@
-import { createCapabilityFields, createKeyFields, withSetupGuideTab } from "./fields.mjs";
+import { SERVER_ONLY, createCapabilityFields, createConfirmationFields, createKeyFields, withKeyTabs } from "./fields.mjs";
 import { generateApiKey, hashApiKey } from "./key.mjs";
 //#region src/api-keys/collection.ts
 /**
 * Generates the key on create and keeps the lookup index in step with it.
 * Runs after field `beforeValidate` fallbacks, so on update `data.apiKey` is the
 * decrypted plaintext of the stored key.
-*/ const keyBeforeChange = ({ data, operation, req }) => {
+*/ const keyBeforeChange = ({ context, data, operation, req }) => {
+	if (context["mcpxTouch"]) return data;
 	if (operation === "create" && typeof data["apiKey"] !== "string") data["apiKey"] = generateApiKey();
 	if (typeof data["apiKey"] === "string") data["apiKeyIndex"] = hashApiKey(req.payload.secret, data["apiKey"]);
 	return data;
@@ -27,7 +28,12 @@ import { generateApiKey, hashApiKey } from "./key.mjs";
 		admin: {
 			group: "MCP",
 			useAsTitle: "label",
-			description: "Keys for MCP clients. Each key acts as its user and may only do what its capabilities allow."
+			description: "Keys for MCP clients. Each key acts as its user and may only do what its capabilities allow.",
+			...options.setupGuide && { components: { edit: { beforeDocumentControls: [{
+				path: "@abinnovision/payloadcms-mcpx/admin",
+				exportName: "McpxSetupGuide",
+				clientProps: { endpointPath: options.endpointPath }
+			}] } } }
 		},
 		access: {
 			create: isUser,
@@ -36,22 +42,15 @@ import { generateApiKey, hashApiKey } from "./key.mjs";
 			delete: ownKeysOnly
 		},
 		hooks: { beforeChange: [keyBeforeChange] },
-		fields: withSetupGuideTab([
-			{
-				name: "user",
-				type: "relationship",
-				relationTo: userCollection,
-				required: true,
-				access: {
-					create: () => false,
-					update: () => false
-				},
-				defaultValue: ({ req }) => isUser({ req }) ? req.user?.id : void 0,
-				admin: { description: "The user this key acts as." }
-			},
-			...createKeyFields(),
-			...createCapabilityFields(options)
-		], options)
+		fields: [...createConfirmationFields(options), ...withKeyTabs([{
+			name: "user",
+			type: "relationship",
+			relationTo: userCollection,
+			required: true,
+			access: SERVER_ONLY,
+			defaultValue: ({ req }) => isUser({ req }) ? req.user?.id : void 0,
+			admin: { description: "The user this key acts as." }
+		}, ...createKeyFields()], createCapabilityFields(options))]
 	};
 };
 //#endregion

package/dist/api-keys/confirmation-view.mjs

@@ -0,0 +1,7 @@
+//#region src/api-keys/confirmation-view.ts
+/**
+* Path of the confirmations endpoints below the plugin's endpoint path.
+*/ const CONFIRMATIONS_PATH = "/confirmations";
+const DECISIONS = ["approved", "rejected"];
+//#endregion
+export { CONFIRMATIONS_PATH, DECISIONS };

package/dist/api-keys/fields.mjs

@@ -1,5 +1,5 @@
 import { CAPABILITIES_FIELD } from "../capabilities.mjs";
-import { CAPABILITIES_DESCRIPTION, CAPABILITY_OPERATIONS, createCapabilityMatrix } from "./capability-matrix.mjs";
+import { CAPABILITIES_DESCRIPTION, createCapabilityMatrix, rowOperations } from "./capability-matrix.mjs";
 //#region src/api-keys/fields.ts
 const encryptKey = ({ req, value }) => typeof value === "string" ? req.payload.encrypt(value) : value;
 const decryptKey = ({ req, value }) => {
@@ -16,7 +16,24 @@ const checkbox = (name, description) => ({
 	defaultValue: false,
 	admin: { description }
 });
-const SETUP_GUIDE_FIELD = "setupGuide";
+/**
+* Access for fields only the server writes.
+*/ const SERVER_ONLY = {
+	create: () => false,
+	update: () => false
+};
+const adminField = (name, exportName, options) => ({
+	name,
+	type: "ui",
+	admin: {
+		disableListColumn: true,
+		components: { Field: {
+			path: "@abinnovision/payloadcms-mcpx/admin",
+			exportName,
+			clientProps: { endpointPath: options.endpointPath }
+		} }
+	}
+});
 /**
 * Fields every key carries. Key generation and the HMAC index live in the
 * collection-level `beforeChange` hook (see `collection.ts`), because sibling
@@ -34,13 +51,28 @@ const SETUP_GUIDE_FIELD = "setupGuide";
 		defaultValue: true,
 		admin: { description: "Disabled keys are refused without revoking them." }
 	},
+	{
+		name: "expiresAt",
+		type: "date",
+		admin: {
+			date: { pickerAppearance: "dayAndTime" },
+			description: "Refused from this time on. Leave empty for no expiry."
+		}
+	},
+	{
+		name: "lastUsedAt",
+		type: "date",
+		access: SERVER_ONLY,
+		admin: {
+			readOnly: true,
+			date: { pickerAppearance: "dayAndTime" },
+			description: "Updated at most once an hour."
+		}
+	},
 	{
 		name: "apiKey",
 		type: "text",
-		access: {
-			create: () => false,
-			update: () => false
-		},
+		access: SERVER_ONLY,
 		admin: {
 			readOnly: true,
 			description: "Generated when the key is created. Send it as `Authorization: Bearer <key>`."
@@ -58,34 +90,27 @@ const SETUP_GUIDE_FIELD = "setupGuide";
 	}
 ];
 /**
-* Wraps the key fields and the setup guide in unnamed tabs, so wide snippets
+* The pending calls of the key, above everything else on its edit view, where
+* a collection exposes `delete`. The component renders nothing while none is
+* pending and never touches the form, so deciding does not mark the key
+* modified.
+*/ const createConfirmationFields = (options) => options.confirmations ? [adminField("confirmations", "McpxConfirmations", options)] : [];
+/**
+* Wraps the key fields and the capabilities in unnamed tabs, so wide tables
 * get the full form width. Named tabs would nest the data and move
 * `capabilities` off the document root, which capability resolution reads.
-*
-* The guide tab only shows on update: on create there is no key to hand out.
-*/ const withSetupGuideTab = (keyFields, options) => {
-	if (!options.setupGuide) return keyFields;
+*/ const withKeyTabs = (keyFields, capabilityFields) => {
+	const tabs = [{
+		label: "Key",
+		fields: keyFields
+	}];
+	if (capabilityFields.length > 0) tabs.push({
+		label: "Capabilities",
+		fields: capabilityFields
+	});
 	return [{
 		type: "tabs",
-		tabs: [{
-			label: "Key",
-			fields: keyFields
-		}, {
-			label: "Connect a client",
-			admin: { condition: (_data, _siblingData, { operation }) => operation === "update" },
-			fields: [{
-				name: SETUP_GUIDE_FIELD,
-				type: "ui",
-				admin: {
-					disableListColumn: true,
-					components: { Field: {
-						path: "@abinnovision/payloadcms-mcpx/admin",
-						exportName: "McpxSetupGuide",
-						clientProps: { endpointPath: options.endpointPath }
-					} }
-				}
-			}]
-		}]
+		tabs
 	}];
 };
 /**
@@ -102,29 +127,18 @@ const SETUP_GUIDE_FIELD = "setupGuide";
 	const entityGroups = (rows) => rows.map((row) => ({
 		name: row.fieldName,
 		type: "group",
-		label: row.label,
-		fields: CAPABILITY_OPERATIONS.filter((operation) => row[operation.id]).map((operation) => checkbox(operation.id, operation.description))
+		label: row.slug,
+		fields: rowOperations(row).map((operation) => checkbox(operation.id, operation.description))
 	}));
-	const collectionGroups = entityGroups(matrix.collections);
-	const globalGroups = entityGroups(matrix.globals);
-	const toolCheckboxes = matrix.tools.map((tool) => checkbox(tool.name, tool.description));
 	const groups = [
-		...collectionGroups.length > 0 ? [{
-			name: "collections",
-			type: "group",
-			fields: collectionGroups
-		}] : [],
-		...globalGroups.length > 0 ? [{
-			name: "globals",
-			type: "group",
-			fields: globalGroups
-		}] : [],
-		...toolCheckboxes.length > 0 ? [{
-			name: "tools",
-			type: "group",
-			fields: toolCheckboxes
-		}] : []
-	];
+		["collections", entityGroups(matrix.collections)],
+		["globals", entityGroups(matrix.globals)],
+		["tools", matrix.tools.map((tool) => checkbox(tool.name, tool.description))]
+	].filter(([, fields]) => fields.length > 0).map(([name, fields]) => ({
+		name,
+		type: "group",
+		fields
+	}));
 	if (groups.length === 0) return [];
 	return [{
 		name: CAPABILITIES_FIELD,
@@ -136,7 +150,7 @@ const SETUP_GUIDE_FIELD = "setupGuide";
 				exportName: "McpxCapabilityMatrix",
 				clientProps: {
 					matrix,
-					withinTab: options.setupGuide
+					withinTab: true
 				}
 			} }
 		},
@@ -144,4 +158,4 @@ const SETUP_GUIDE_FIELD = "setupGuide";
 	}];
 };
 //#endregion
-export { createCapabilityFields, createKeyFields, withSetupGuideTab };
+export { SERVER_ONLY, createCapabilityFields, createConfirmationFields, createKeyFields, withKeyTabs };

package/dist/auth/resolve.mjs

@@ -2,16 +2,20 @@ import { isPlainObject } from "../guards.mjs";
 import { hashApiKey } from "../api-keys/key.mjs";
 //#region src/auth/resolve.ts
 const BEARER = /^Bearer\s+(\S+)\s*$/i;
-const relationId = (value) => {
-	if (typeof value === "string" || typeof value === "number") return value;
-	if (typeof value === "object" && value !== null && "id" in value) return value.id;
+const LAST_USED_INTERVAL_MS = 36e5;
+const toTime = (value) => typeof value === "string" || value instanceof Date ? new Date(value).getTime() : NaN;
+const isId = (value) => typeof value === "string" || typeof value === "number";
+/**
+* The id of a relationship value, populated or not.
+*/ const relationId = (value) => {
+	if (isId(value)) return value;
+	return isPlainObject(value) && isId(value["id"]) ? value["id"] : void 0;
 };
 const parseBearer = (headers) => {
 	const header = headers.get("authorization");
 	if (!header) return null;
 	return BEARER.exec(header.trim())?.[1] ?? null;
 };
-const isId = (value) => typeof value === "string" || typeof value === "number";
 /**
 * Whether a resolved auth, from the default or a custom resolver, may become
 * `req.user`: a user of the configured user collection with an id, and a key id.
@@ -20,31 +24,14 @@ const isId = (value) => typeof value === "string" || typeof value === "number";
 	return isId(auth["user"]["id"]) && auth["user"]["collection"] === options.userCollection && isId(auth["apiKeyId"]);
 };
 /**
-* Resolves the bearer key of a request to the user it acts as.
-*
-* The key is looked up by its HMAC index, the same way Payload resolves its own
-* API keys. A missing, unknown, disabled or orphaned key yields `null`; nothing
-* here throws, so the handler alone decides how a refusal looks.
-*/ const resolveApiKeyAuth = async (req, options) => {
-	const key = parseBearer(req.headers);
-	if (key === null) return null;
-	const { payload } = req;
-	const { docs } = await payload.find({
-		collection: options.apiKeysSlug,
-		where: { apiKeyIndex: { equals: hashApiKey(payload.secret, key) } },
-		limit: 1,
-		pagination: false,
-		depth: 0,
-		overrideAccess: true,
-		select: {
-			enabled: true,
-			user: true,
-			capabilities: true
-		}
-	});
-	const keyDoc = docs[0];
+* The checks a key passes once it is looked up: enabled, not expired, and its
+* user exists, is verified and is not locked out. Yields the user it acts as,
+* or `null`.
+*/ const checkApiKey = async (req, options, keyDoc) => {
 	const userId = relationId(keyDoc?.user);
 	if (!keyDoc || keyDoc.enabled !== true || userId === void 0) return null;
+	if (toTime(keyDoc.expiresAt) <= Date.now()) return null;
+	const { payload } = req;
 	const userCollection = payload.collections[options.userCollection];
 	const lookup = {
 		collection: options.userCollection,
@@ -61,8 +48,7 @@ const isId = (value) => typeof value === "string" || typeof value === "number";
 		showHiddenFields: true,
 		select: { lockUntil: true }
 	})]);
-	const storedLock = lock?.["lockUntil"];
-	const lockUntil = typeof storedLock === "string" || storedLock instanceof Date ? new Date(storedLock).getTime() : NaN;
+	const lockUntil = toTime(lock?.["lockUntil"]);
 	if (!user || user["_verified"] === false || lockUntil > Date.now()) return null;
 	return {
 		user: {
@@ -74,5 +60,68 @@ const isId = (value) => typeof value === "string" || typeof value === "number";
 		capabilities: keyDoc.capabilities
 	};
 };
+const KEY_SELECT = {
+	enabled: true,
+	user: true,
+	capabilities: true,
+	expiresAt: true
+};
+/**
+* The user the key `id` acts as, or `null`, under the same checks as the
+* bearer lookup.
+*/ const resolveApiKeyById = async (req, options, id) => {
+	const keyDoc = await req.payload.findByID({
+		collection: options.apiKeysSlug,
+		id,
+		depth: 0,
+		overrideAccess: true,
+		disableErrors: true,
+		select: KEY_SELECT
+	});
+	return await checkApiKey(req, options, keyDoc ?? void 0);
+};
+/**
+* Resolves the bearer key of a request to the user it acts as.
+*
+* The key is looked up by its HMAC index, the same way Payload resolves its own
+* API keys. A missing, unknown, disabled or orphaned key yields `null`; nothing
+* here throws, so the handler alone decides how a refusal looks.
+*/ const resolveApiKeyAuth = async (req, options) => {
+	const key = parseBearer(req.headers);
+	if (key === null) return null;
+	const { payload } = req;
+	const { docs } = await payload.find({
+		collection: options.apiKeysSlug,
+		where: { apiKeyIndex: { equals: hashApiKey(payload.secret, key) } },
+		limit: 1,
+		pagination: false,
+		depth: 0,
+		overrideAccess: true,
+		select: {
+			...KEY_SELECT,
+			lastUsedAt: true
+		}
+	});
+	const keyDoc = docs[0];
+	const auth = await checkApiKey(req, options, keyDoc);
+	if (!auth || !keyDoc) return null;
+	const lastUsed = toTime(keyDoc.lastUsedAt);
+	if (Number.isNaN(lastUsed) || Date.now() - lastUsed > LAST_USED_INTERVAL_MS) try {
+		await payload.update({
+			collection: options.apiKeysSlug,
+			id: keyDoc.id,
+			data: { lastUsedAt: (/* @__PURE__ */ new Date()).toISOString() },
+			overrideAccess: true,
+			depth: 0,
+			context: { mcpxTouch: true }
+		});
+	} catch (error) {
+		payload.logger.warn({
+			err: error,
+			msg: "[payloadcms-mcpx] Could not record the last use of an MCP API key."
+		});
+	}
+	return auth;
+};
 //#endregion
-export { isValidAuthResult, parseBearer, resolveApiKeyAuth };
+export { checkApiKey, isValidAuthResult, parseBearer, relationId, resolveApiKeyAuth, resolveApiKeyById };

package/dist/capabilities.d.mts

@@ -0,0 +1,2 @@
+import "./types.mjs";
+import "./options.mjs";

package/dist/capabilities.mjs

@@ -1,17 +1,63 @@
 import { isPlainObject } from "./guards.mjs";
 //#region src/capabilities.ts
-/** Group field holding the capability checkboxes on an API key document. */ const CAPABILITIES_FIELD = "capabilities";
-/** Covers draft and live writes; {@link isLiveWrite} separates them. */ const canWrite = (entity) => entity.write !== false;
-/** The config lets MCP change live content and a draft exists to promote. */ const canPublish = (entity) => entity.write === "live" && entity.hasDrafts;
 /**
-* An upload document is a file, and no tool here carries one. Its own fields
-* stay patchable; the first version is made in the admin panel.
-*/ const canCreate = (entity) => canWrite(entity) && !entity.isUpload;
+* Group field holding the capability checkboxes on an API key document.
+*/ const CAPABILITIES_FIELD = "capabilities";
 /**
-* Without drafts there is no draft stage, so every write is live.
-*/ const isLiveWrite = (entity) => entity.write === "live" && !entity.hasDrafts;
+* The operations a collection or global can expose. The generated checkboxes
+* and the matrix segments share this wording. `requires` names the
+* operation a grant depends on, which the server and the matrix both enforce.
+*/ const CAPABILITY_OPERATIONS = [
+	{
+		id: "read",
+		label: "Read",
+		description: "Describe, find and read."
+	},
+	{
+		id: "write",
+		label: "Write",
+		description: "Create, patch and validate drafts.",
+		requires: "read"
+	},
+	{
+		id: "publish",
+		label: "Publish",
+		description: "Promote the current draft to what the public sees.",
+		requires: "write"
+	},
+	{
+		id: "delete",
+		label: "Delete",
+		description: "Delete documents. Each one is approved by this key's user in the admin panel, unless the config allows trashing directly and this key is set to.",
+		requires: "read"
+	}
+];
+/**
+* Stored as a checkbox of its own but drawn as the approval shield of the Delete
+* control.
+*/ const DELETE_UNATTENDED = {
+	id: "deleteUnattended",
+	label: "Trash directly",
+	description: "Move documents to trash without asking this key's user.",
+	requires: "delete"
+};
+/**
+* Every operation with a stored checkbox: the capability operations plus
+* the unattended delete. Each follows the one it requires, which the resolve
+* loop depends on.
+*/ const STORED_OPERATIONS = [...CAPABILITY_OPERATIONS, DELETE_UNATTENDED];
+/**
+* The operations in one run of the access levels, each requiring the one
+* before it. Delete is chosen separately.
+*/ const ACCESS_CHAIN = CAPABILITY_OPERATIONS.filter((operation) => operation.id !== "delete");
+/**
+* What an operation depends on. `resolveCapabilities` discards a grant whose
+* prerequisite is off.
+*/ const requiresOf = (operation) => {
+	const found = STORED_OPERATIONS.find((candidate) => candidate.id === operation);
+	return found && "requires" in found ? found.requires : void 0;
+};
 const flag = (group, name) => isPlainObject(group) && group[name] === true;
-const publishFlag = (entity, group) => canPublish(entity) && flag(group, "write") && flag(group, "publish");
 /**
 * Capabilities in force for a key: the plugin config decides what can exist,
 * the key's checkboxes decide what does. A missing checkbox is `false`, so keys
@@ -22,11 +68,18 @@ const publishFlag = (entity, group) => canPublish(entity) && flag(group, "write"
 		const resolved = {};
 		for (const entity of entities) {
 			const group = isPlainObject(namespaceGroup) ? namespaceGroup[entity.fieldName] : void 0;
-			resolved[entity.slug] = {
-				read: entity.read && flag(group, "read"),
-				write: canWrite(entity) && flag(group, "write"),
-				publish: publishFlag(entity, group)
+			const granted = {
+				read: false,
+				write: false,
+				publish: false,
+				delete: false,
+				deleteUnattended: false
 			};
+			for (const { id } of STORED_OPERATIONS) {
+				const needs = requiresOf(id);
+				granted[id] = entity[id] && flag(group, id) && (needs === void 0 || granted[needs]);
+			}
+			resolved[entity.slug] = granted;
 		}
 		return resolved;
 	};
@@ -47,8 +100,9 @@ const publishFlag = (entity, group) => canPublish(entity) && flag(group, "write"
 	return {
 		readable: slugsWith("read"),
 		writable: slugsWith("write"),
-		publishable: slugsWith("publish")
+		publishable: slugsWith("publish"),
+		deletable: slugsWith("delete")
 	};
 };
 //#endregion
-export { CAPABILITIES_FIELD, canCreate, canPublish, canWrite, isLiveWrite, resolveCapabilities, scopeSlugs };
+export { ACCESS_CHAIN, CAPABILITIES_FIELD, CAPABILITY_OPERATIONS, STORED_OPERATIONS, requiresOf, resolveCapabilities, scopeSlugs };

package/dist/define-tool.d.mts

@@ -1,19 +1,23 @@
-import { McpxAnyTool, McpxTool, McpxToolScope } from "./types.mjs";
+import { McpxAnyTool, McpxTool, McpxToolConfirm, McpxToolDefinition, McpxToolScope } from "./types.mjs";
 import { z } from "zod";
 //#region src/define-tool.d.ts
-/** Fixed shape; arguments inferred from it. */
-export declare function defineMcpxTool<Shape extends z.ZodRawShape>(tool: McpxTool<Shape> & {
+/**
+ * Fixed shape; arguments inferred from it.
+ */
+export declare function defineMcpxTool<Shape extends z.ZodRawShape, Confirm extends McpxToolConfirm | undefined = undefined>(tool: McpxToolDefinition<Shape, z.infer<z.ZodObject<Shape>>, Confirm> & {
   inputSchema?: Shape;
 }): McpxTool<Shape>;
-/** Per-request shape returned as an object literal; arguments inferred from it. */
-export declare function defineMcpxTool<Shape extends z.ZodRawShape>(tool: McpxTool<Shape> & {
+/**
+ * Per-request shape returned as an object literal; arguments inferred from it.
+ */
+export declare function defineMcpxTool<Shape extends z.ZodRawShape, Confirm extends McpxToolConfirm | undefined = undefined>(tool: McpxToolDefinition<Shape, z.infer<z.ZodObject<Shape>>, Confirm> & {
   inputSchema: (scope: McpxToolScope) => Shape;
 }): McpxAnyTool;
 /**
  * Per-request shape built from helpers that erase to `z.ZodRawShape`, as the
  * builtins do. Nothing to infer from, so state the arguments instead.
  */
-export declare function defineMcpxTool<Args>(tool: McpxTool<z.ZodRawShape, Args> & {
+export declare function defineMcpxTool<Args, Confirm extends McpxToolConfirm | undefined = undefined>(tool: McpxToolDefinition<z.ZodRawShape, Args, Confirm> & {
   inputSchema: (scope: McpxToolScope) => z.ZodRawShape;
 }): McpxAnyTool;
 //#endregion

package/dist/define-tool.mjs

@@ -1,6 +1,13 @@
+import { z } from "zod";
 //#region src/define-tool.ts
 function defineMcpxTool(tool) {
 	return tool;
 }
+/**
+* Strict, so an unknown argument is rejected by name instead of stripped.
+*/ const toolInputSchema = (tool, scope) => z.strictObject(typeof tool.inputSchema === "function" ? tool.inputSchema(scope) : tool.inputSchema ?? {});
+/**
+* A tool that does not decide for itself is gated by its own checkbox.
+*/ const isToolEnabled = (tool, scope) => tool.isEnabled ? tool.isEnabled(scope) : scope.capabilities.tools[tool.name] === true;
 //#endregion
-export { defineMcpxTool };
+export { defineMcpxTool, isToolEnabled, toolInputSchema };