@webdecoy/ai-protection 0.1.0-alpha.17 → 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.17 @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).
@@ -161,9 +167,17 @@ Discovery uses schema-3 reports on the existing reporting endpoint; deploy a
 compatible hosted runtime first. Old runtimes reject these optional reports
 without affecting tool listing. Reporting has bounded pending work and a deadline,
 never blocks authorization, and does not retry. Call `await handler.flush()` at a
-host shutdown/lifecycle boundary to drain pending discovery reports; it does not
-wait for active tool calls or action reports. Abruptly terminated hosts can lose
-reports. Discovery advertisements never increment tool action or request counts.
+host shutdown/lifecycle boundary to drain discovery and tool-action reports already
+queued when flush begins. From alpha.18, the action reporting queue is shared by
+all calls on one handler and is bounded by `sharedRuntime.maxPendingReports`
+(default 100); discovery uses a separately bounded queue. Full queues drop reports
+without retrying or blocking tool execution.
+
+Stop accepting new requests and let active tools complete or cancel before the
+final flush. Flush does not wait for running tools, future reports, arbitrary
+`onEvent`/`onReport` callbacks or dashboard persistence. Reporting deadlines still
+apply; an unavailable/timeout/drop is not delivery success. Abruptly terminated
+hosts can lose reports. Discovery advertisements never increment tool action or request counts.
 
 
 ### Calls before discovery (alpha.8+)

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.d.mts

@@ -44,6 +44,6 @@ export interface ProtectedMCPOptions {
  */
 export function createProtectedMCPHandler(options: ProtectedMCPOptions):
   ((request: IncomingMessage, response: ServerResponse) => Promise<void>) & {
-    /** Drain pending discovery reports at shutdown. Does not wait for running tools. */
+    /** Drain already queued discovery/action reports within reporting deadlines. Does not wait for running tools, future reports or observer callbacks. */
     flush(): Promise<void>;
   };

package/mcp.mjs

@@ -50,7 +50,11 @@ export function createProtectedMCPHandler(options) {
     if (options.discovery) for (const [name, tool] of Object.entries(tools))
         tool.toolSchema = Object.freeze({serverId:options.discovery.serverId,hash:hashes[name],...(decoys.has(name)?{decoy:decoys.get(name)}:{effect:inferToolEffect(name,tool.inputSchema,tool.annotations),permissions:Object.freeze({schema:1,required_scopes:tool.requiredScopes.length,application_authorization:true,additional_policy:typeof tool.policy==='function'})})});
     // Validate after discovery supplies the schema required by tool pauses.
-    createActionProtection({ policyVersion: options.policyVersion, authenticate: options.authenticate, actions: tools, sharedRuntime: options.sharedRuntime });
+    if (typeof options.authenticate !== 'function') throw Error('Invalid MCP authenticator');
+    // One bounded reporting runtime per handler. The caller is passed per run,
+    // never held in mutable shared request state. HTTP authentication stays above
+    // dispatch; the action boundary independently validates and snapshots it.
+    const guard = createActionProtection({ policyVersion: options.policyVersion, authenticate: caller => caller, actions: tools, sharedRuntime: options.sharedRuntime, onEvent: options.onEvent });
     const runtime = options.sharedRuntime && { ...options.sharedRuntime };
     const serverId = options.discovery?.serverId;
     const catalogReporter = options.discovery ? createReporter({
@@ -177,7 +181,6 @@ export function createProtectedMCPHandler(options) {
                 res.end();
                 return;
             }
-            const guard = createActionProtection({ policyVersion: options.policyVersion, authenticate: () => caller, actions: tools, sharedRuntime: options.sharedRuntime, onEvent: options.onEvent });
             // Scope escalation belongs at HTTP level, before the SDK opens an SSE stream.
             if (message.method === 'tools/call' && typeof message.params?.name === 'string') {
                 const definition = Object.hasOwn(tools, message.params.name) ? tools[message.params.name] : undefined;
@@ -185,7 +188,7 @@ export function createProtectedMCPHandler(options) {
                     // Run the same admission path for its sanitized denial evidence. It cannot
                     // dispatch with a missing required scope, regardless of discovery results.
                     try {
-                        await guard.run(message.params.name, {}, null, { signal: disconnected.signal });
+                        await guard.run(message.params.name, {}, caller, { signal: disconnected.signal });
                     }
                     catch (e) {
                         if (!(e instanceof ActionDenied))
@@ -224,20 +227,26 @@ 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 ?? {}), null, { 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();
-                    void guard.flush();
                 }
             });
             await server.connect(transport);
@@ -250,5 +259,5 @@ export function createProtectedMCPHandler(options) {
                 res.destroy();
         }
     };
-    return Object.assign(handle, { flush: async () => { await catalogReporter?.flush(); } });
+    return Object.assign(handle, { flush: async () => { await Promise.all([catalogReporter?.flush(), guard.flush()]); } });
 }

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.17",
+  "version": "0.1.0-alpha.19",
   "exports": {
     "./fetch": {
       "types": "./fetch.d.mts",