@webdecoy/ai-protection 0.1.0-alpha.18 → 0.1.0-alpha.19

package/MCP.md

@@ -11,7 +11,7 @@ resource authorization.
 Available in `0.1.0-alpha.5` and later compatible alpha releases:
 
 ```sh
-npm install @webdecoy/ai-protection@0.1.0-alpha.18 @modelcontextprotocol/sdk@1.31.0
+npm install @webdecoy/ai-protection@0.1.0-alpha.19 @modelcontextprotocol/sdk@1.31.0
 ```
 
 Requires Node 22.22.3+ and MCP SDK **1.31.0**. The MCP SDK is an optional peer, so
@@ -115,6 +115,12 @@ have unknown work. Never retry writes without application/provider idempotency.
   for its runtime prerequisite and application-enforced bounds. Full product
   acceptance remains separate from this adapter's tested contract.
 
+From alpha.19, every tool result also carries `_meta["webdecoy.com/action"].actionId`:
+allowed results (merged with your own `_meta`), denials and failed callbacks alike.
+It is the action ID on that call's reported evidence, so the caller or an operator
+can find the exact action in the dashboard. It is a random identifier per call and
+carries no identity, arguments or result content.
+
 This is an explicit tools integration, not transparent protection of an existing
 whole MCP server. See the [MCP transport specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports)
 and [authorization specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization).

package/actions.d.mts

@@ -115,4 +115,4 @@ export function createActionProtection<T>(options: {
   actions: Record<string, ActionDefinition>;
   /** Local best-effort observer. sharedRuntime enables independent hosted reporting. */
   onEvent?(event: ActionEvent): void | Promise<void>;
-}): {flush():Promise<void>;run(action: string, args: ActionInput, authenticationContext: T, options?: {signal?: AbortSignal}): Promise<unknown>};
+}): {flush():Promise<void>;run(action: string, args: ActionInput, authenticationContext: T, options?: {signal?: AbortSignal; /** Receives this invocation's action ID before any check runs. */ onAction?(actionId: string): void}): Promise<unknown>};

package/actions.mjs

@@ -82,8 +82,10 @@ export function createActionProtection(options) {
   if (!actions.size || actions.size > 128) throw Error('Expected 1–128 actions');
   const runtime=prepareActionRuntime(options,actions);
   let pendingEvents = 0;
-  return Object.freeze({flush:async()=>{await runtime?.flush();},async run(name, input, authenticationContext, {signal} = {}) {
+  return Object.freeze({flush:async()=>{await runtime?.flush();},async run(name, input, authenticationContext, {signal, onAction} = {}) {
     const actionId = randomUUID();
+    // Lets an adapter return the action ID to its caller; never affects the decision.
+    try { onAction?.(actionId); } catch {}
     // Unknown caller-controlled action strings are never placed in evidence.
     const action = actions.get(name), eventAction = action ? name : 'unregistered';
     let attempted = false,completed=false,lease,work,callerEvidence;

package/mcp.mjs

@@ -227,16 +227,23 @@ export function createProtectedMCPHandler(options) {
                     throw new McpError(ErrorCode.InvalidParams, 'Tool unavailable');
                 running.started = true;
                 const signal = AbortSignal.any([extra.signal, disconnected.signal, running.controller.signal]);
+                // The action ID matches this call's reported evidence, so the caller can find it in the dashboard.
+                let actionId;
+                const action = () => ({ 'webdecoy.com/action': { actionId } });
                 try {
-                    return await guard.run(request.params.name, (request.params.arguments ?? {}), caller, { signal });
+                    const result = await guard.run(request.params.name, (request.params.arguments ?? {}), caller, { signal, onAction: id => { actionId = id; } });
+                    if (!result || typeof result !== 'object' || Array.isArray(result))
+                        return result;
+                    const meta = result._meta && typeof result._meta === 'object' && !Array.isArray(result._meta) ? result._meta : {};
+                    return { ...result, _meta: { ...meta, ...action() } };
                 }
                 catch (e) {
                     if (signal.aborted)
                         throw new McpError(ErrorCode.InternalError, 'Request cancelled');
                     if (e instanceof ActionDenied)
                         return { isError: true, content: [{ type: 'text', text: `Action denied: ${e.reason}` }],
-                            _meta: { 'webdecoy.com/action-error': { reason: e.reason, status: e.status, ...(e.retryAfterSeconds ? { retryAfterSeconds: e.retryAfterSeconds } : {}) } } };
-                    return { isError: true, content: [{ type: 'text', text: 'Action failed; outcome may be unknown' }] };
+                            _meta: { ...action(), 'webdecoy.com/action-error': { reason: e.reason, status: e.status, ...(e.retryAfterSeconds ? { retryAfterSeconds: e.retryAfterSeconds } : {}) } } };
+                    return { isError: true, content: [{ type: 'text', text: 'Action failed; outcome may be unknown' }], _meta: action() };
                 }
                 finally {
                     cleanup();

package/package.json

@@ -11,7 +11,7 @@
     "test:types": "tsc --strict --noEmit --module nodenext --target es2022 test/types.mts test/mcp-types.mts",
     "test:workers": "node --test test/workers/*.test.mjs"
   },
-  "version": "0.1.0-alpha.18",
+  "version": "0.1.0-alpha.19",
   "exports": {
     "./fetch": {
       "types": "./fetch.d.mts",