@sendinel/mcp-server 1.0.104 → 1.0.106

package/build/auth.js

@@ -75,6 +75,7 @@ export async function validateKey(key) {
         scopes: row.scopes,
         toolGroups: resolveToolGroupsForPlan(plan, row.tool_groups),
         approvalMode: row.approval_mode ?? 'standard',
+        actsAsUserId: row.acts_as_user_id ?? null,
     };
 }
 export async function authenticateBearer(token, overrideProjectId) {

package/build/index.js

@@ -7,7 +7,9 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import express from 'express';
-import { registerAllTools, SENDINEL_SERVER_INSTRUCTIONS } from './server.js';
+import { registerAllTools, SENDINEL_SERVER_INSTRUCTIONS, isAgentConnection, isTesterConnection } from './server.js';
+import { installApprovalElicitation } from './lib/approval-elicitation.js';
+import { createHumanApprovalCallback } from './lib/approval-human-callback.js';
 import { registerAllPrompts } from './prompts.js';
 import { runWithClient } from './db.js';
 import { initProjectClient, resolveProjectClientStrict, TenantResolutionError } from './byod-client.js';
@@ -38,6 +40,10 @@ async function runStdio() {
     }
     registerAllTools(server, { toolGroups, scopes });
     registerAllPrompts(server, { toolGroups, scopes });
+    if (!isAgentConnection(info.scopes) && !isTesterConnection(info.scopes)) {
+        installApprovalElicitation(server, { projectId: info.projectId, userId: info.actsAsUserId,
+            createHumanDecision: createHumanApprovalCallback });
+    }
     const t = new StdioServerTransport();
     await server.connect(t);
     process.stderr.write('Sendinel MCP server running (stdio)\n');

package/build/lib/action-approvals.d.ts

@@ -46,9 +46,13 @@ export interface ApprovalResult {
     approve_via: string;
     /** One-tap approval page; works on a phone and needs no project switching (#3661). */
     approve_url: string;
+    preview_text: string;
+    decision_status: 'decision_pending' | 'approved' | 'rejected';
     message: string;
 }
 export declare function approvalPageUrl(approvalId: string): string;
+/** SHA-256 over JSON-compatible params, with recursive stable key ordering. */
+export declare function approvalPayloadHash(action: string, params: unknown): string;
 /**
  * Request human approval for an action. Creates a pending approval token
  * and returns instructions for the agent to wait.

package/build/lib/action-approvals.js

@@ -1,7 +1,10 @@
-import { triggerChangeSummary, decodeHtmlEntities, stripHtmlComments } from '@sendinel/domain';
+import { createHash } from 'node:crypto';
+import { buildApprovalPreview, isHumanApprovalChannel, triggerChangeSummary, decodeHtmlEntities, stripHtmlComments } from '@sendinel/domain';
 import { db, requestContext } from '../db.js';
 import { getProjectId } from '../project.js';
+import { captureApprovalSnapshot, withoutApprovalSnapshot } from './approval-snapshot.js';
 import { fireWebhookEvent } from './webhook-events.js';
+import { elicitApproval } from './approval-elicitation.js';
 /**
  * Action approval tiers:
  *
@@ -303,11 +306,15 @@ function normalizeApprovalParams(value) {
     if (value && typeof value === 'object') {
         return Object.fromEntries(Object.entries(value)
             .filter(([, entryValue]) => entryValue !== undefined)
-            .sort(([a], [b]) => a.localeCompare(b))
+            .sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)
             .map(([key, entryValue]) => [key, normalizeApprovalParams(entryValue)]));
     }
     return value;
 }
+/** SHA-256 over JSON-compatible params, with recursive stable key ordering. */
+export function approvalPayloadHash(action, params) {
+    return createHash('sha256').update(JSON.stringify(normalizeApprovalParams({ action, params }))).digest('hex');
+}
 function approvalParamsEqual(expected, actual) {
     return JSON.stringify(normalizeApprovalParams(expected)) === JSON.stringify(normalizeApprovalParams(actual));
 }
@@ -318,9 +325,18 @@ function approvalParamsEqual(expected, actual) {
 export async function requestApproval(action, params, apiKeyId, channelContext, display) {
     const tier = getApprovalTier(action, params);
     const summary = buildApprovalSummary(action, params, display);
-    const expiresAt = new Date(Date.now() + 30 * 60 * 1000).toISOString();
+    const expiresAt = new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString();
     const { channel, verified } = channelContext ?? currentChannelContext();
     const actor = requestContext();
+    // Ignore any model-supplied reserved field; freeze facts read by the server.
+    const cleanParams = withoutApprovalSnapshot(params);
+    const snapshot = await captureApprovalSnapshot(action, cleanParams, getProjectId());
+    const payload = cleanParams.payload;
+    if (action === 'send_broadcast' && Array.isArray(payload?.contact_ids) && Array.isArray(snapshot.contact_ids) &&
+        !approvalParamsEqual({ ids: [...payload.contact_ids].sort() }, { ids: snapshot.contact_ids })) {
+        throw new Error('Approval audience changed while preparing the preview. Request a new approval.');
+    }
+    const frozenParams = { ...cleanParams, __approval_snapshot: snapshot };
     const { data, error } = await db()
         .from('action_approvals')
         .insert({
@@ -330,7 +346,8 @@ export async function requestApproval(action, params, apiKeyId, channelContext,
         agent_label: actor?.agentLabel ?? null,
         action,
         tier,
-        params,
+        params: frozenParams,
+        payload_hash: approvalPayloadHash(action, frozenParams),
         summary,
         expires_at: expiresAt,
         channel,
@@ -346,7 +363,7 @@ export async function requestApproval(action, params, apiKeyId, channelContext,
         resource_id: params.resource_id ?? params.campaign_id ?? params.contact_id ?? null,
         requested_by: apiKeyId ?? null,
     }, getProjectId()).catch(() => { });
-    return {
+    return elicitApproval({
         requires_approval: true,
         approval_id: data.id,
         tier,
@@ -355,8 +372,9 @@ export async function requestApproval(action, params, apiKeyId, channelContext,
         expires_at: expiresAt,
         approve_via: 'Open approve_url (works on a phone) or Dashboard → Settings → Pending Approvals',
         approve_url: approvalPageUrl(data.id),
-        message: `This action requires human approval. A notification has been sent to your dashboard. Approval ID: ${data.id}. Check status with: poll this approval_id, or wait for the webhook callback (event: approval.decided). Token expires in 30 minutes.`,
-    };
+        preview_text: buildApprovalPreview({ action, params: frozenParams, summary }).plain_summary,
+        message: `This action requires human approval. A notification has been sent to your dashboard. Approval ID: ${data.id}. Check status with: poll this approval_id, or wait for the webhook callback (event: approval.decided). Token expires in 24 hours.`,
+    }, { action, params: frozenParams, summary }, getProjectId());
 }
 /**
  * Check if an approval token has been approved.
@@ -365,7 +383,7 @@ export async function requestApproval(action, params, apiKeyId, channelContext,
 export async function checkApproval(approvalId, options = {}) {
     const { data, error } = await db()
         .from('action_approvals')
-        .select('action, status, decided_by, decided_via, expires_at, used_at, params')
+        .select('action, status, decided_by, decided_via, expires_at, used_at, params, payload_hash, requested_at')
         .eq('id', approvalId)
         .eq('project_id', getProjectId())
         .maybeSingle();
@@ -374,17 +392,29 @@ export async function checkApproval(approvalId, options = {}) {
     if (options.action && data.action !== options.action) {
         return { approved: false, status: 'action_mismatch' };
     }
-    if (options.params && !approvalParamsEqual(options.params, data.params)) {
+    if (options.consume && data.payload_hash) {
+        if (!options.action || !options.params)
+            return { approved: false, status: 'payload_required' };
+        if (approvalPayloadHash(options.action, { ...withoutApprovalSnapshot(options.params), ...(data.params?.__approval_snapshot ? { __approval_snapshot: data.params.__approval_snapshot } : {}) }) !== data.payload_hash ||
+            approvalPayloadHash(data.action, data.params) !== data.payload_hash) {
+            return { approved: false, status: 'payload_changed_after_approval' };
+        }
+    }
+    if (options.params && !approvalParamsEqual(withoutApprovalSnapshot(options.params), withoutApprovalSnapshot(data.params))) {
         return { approved: false, status: 'params_mismatch' };
     }
-    // Check expiry
-    if (data.status === 'pending' && new Date(data.expires_at) < new Date()) {
-        await db()
-            .from('action_approvals')
-            .update({ status: 'expired' })
-            .eq('id', approvalId);
+    // Approved tokens expire too. Invalid timestamps fail closed. Older rows may have a
+    // shorter lifetime; no row can authorize an apply more than 24 hours after its request.
+    const requested = data.requested_at == null ? null : Date.parse(data.requested_at);
+    const expiry = Math.min(Date.parse(data.expires_at), requested == null ? Infinity : requested + 24 * 60 * 60 * 1000);
+    if (!Number.isFinite(expiry) || (requested != null && !Number.isFinite(requested)) || expiry <= Date.now()) {
         return { approved: false, status: 'expired' };
     }
+    if (data.used_at || data.status === 'used')
+        return { approved: false, status: 'consumed' };
+    if (data.status === 'approved' && !isHumanApprovalChannel(data.decided_via)) {
+        return { approved: false, status: 'human_decision_required' };
+    }
     if (data.status !== 'approved' || !options.consume) {
         if (data.used_at)
             return { approved: false, status: 'consumed' };
@@ -394,15 +424,33 @@ export async function checkApproval(approvalId, options = {}) {
             decided_by: data.decided_by,
         };
     }
-    const { data: claimed, error: claimError } = await db()
+    if (data.params?.__approval_snapshot) {
+        try {
+            const current = await captureApprovalSnapshot(data.action, withoutApprovalSnapshot(data.params), getProjectId());
+            if (!approvalParamsEqual(current, data.params.__approval_snapshot)) {
+                return { approved: false, status: 'target_changed_after_approval' };
+            }
+        }
+        catch {
+            return { approved: false, status: 'target_revalidation_failed' };
+        }
+    }
+    if (expiry <= Date.now())
+        return { approved: false, status: 'expired' };
+    const claimQuery = db()
         .from('action_approvals')
         .update({ status: 'used', used_at: new Date().toISOString() })
         .eq('id', approvalId)
         .eq('project_id', getProjectId())
         .eq('status', 'approved')
         .is('used_at', null)
-        .select('decided_by')
-        .maybeSingle();
+        .eq('expires_at', data.expires_at)
+        .gt('expires_at', new Date().toISOString())
+        .eq('decided_via', data.decided_via)
+        .eq('params', JSON.stringify(data.params))
+        .gt('requested_at', new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString());
+    const boundClaim = data.payload_hash ? claimQuery.eq('payload_hash', data.payload_hash) : claimQuery.is('payload_hash', null);
+    const { data: claimed, error: claimError } = await boundClaim.select('decided_by').maybeSingle();
     if (claimError || !claimed) {
         return { approved: false, status: 'consumed' };
     }

package/build/lib/approval-capabilities.d.ts

@@ -0,0 +1,17 @@
+export declare const MCP_APP_EXTENSION = "io.modelcontextprotocol/ui";
+export declare const MCP_APP_MIME_TYPE = "text/html;profile=mcp-app";
+export type ApprovalClientCapabilities = Readonly<{
+    elicitation_form: boolean;
+    elicitation_url: boolean;
+    mcp_app: boolean;
+}>;
+export type ApprovalChannelAvailable = 'mcp_app' | 'mcp_elicitation_form' | 'mcp_elicitation_url' | 'plain_text';
+/** Reads only declared initialize capabilities. No user agent or client-name guessing. */
+export declare function probeApprovalCapabilities(declared: unknown): ApprovalClientCapabilities;
+export declare function rememberApprovalCapabilities(session: object, declared: unknown): ApprovalClientCapabilities;
+export declare function approval_channel_available(session: object): ApprovalChannelAvailable;
+/** Each SDK Server is a session boundary, including stateless HTTP request instances. */
+export declare function installApprovalCapabilityProbe(session: {
+    oninitialized?: () => void;
+    getClientCapabilities(): unknown;
+}): void;

package/build/lib/approval-capabilities.js

@@ -0,0 +1,40 @@
+export const MCP_APP_EXTENSION = 'io.modelcontextprotocol/ui';
+export const MCP_APP_MIME_TYPE = 'text/html;profile=mcp-app';
+const sessions = new WeakMap();
+const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value) ? value : null;
+/** Reads only declared initialize capabilities. No user agent or client-name guessing. */
+export function probeApprovalCapabilities(declared) {
+    const capabilities = object(declared);
+    const elicitation = object(capabilities?.elicitation);
+    const extensions = object(capabilities?.extensions);
+    const app = object(extensions?.[MCP_APP_EXTENSION]);
+    return Object.freeze({
+        // The MCP spec defines elicitation:{} as form support for older clients.
+        elicitation_form: !!elicitation && (Object.keys(elicitation).length === 0 || !!object(elicitation.form)),
+        elicitation_url: !!object(elicitation?.url),
+        mcp_app: !!app && Array.isArray(app.mimeTypes) && app.mimeTypes.includes(MCP_APP_MIME_TYPE),
+    });
+}
+export function rememberApprovalCapabilities(session, declared) {
+    const capabilities = probeApprovalCapabilities(declared);
+    sessions.set(session, capabilities);
+    return capabilities;
+}
+export function approval_channel_available(session) {
+    const capabilities = sessions.get(session);
+    if (capabilities?.mcp_app)
+        return 'mcp_app';
+    if (capabilities?.elicitation_form)
+        return 'mcp_elicitation_form';
+    if (capabilities?.elicitation_url)
+        return 'mcp_elicitation_url';
+    return 'plain_text';
+}
+/** Each SDK Server is a session boundary, including stateless HTTP request instances. */
+export function installApprovalCapabilityProbe(session) {
+    const previous = session.oninitialized;
+    session.oninitialized = () => {
+        rememberApprovalCapabilities(session, session.getClientCapabilities());
+        previous?.call(session);
+    };
+}

package/build/lib/approval-elicitation.d.ts

@@ -0,0 +1,46 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { RequestId } from '@modelcontextprotocol/sdk/types.js';
+type Decision = 'approve' | 'reject';
+type HumanCallback = {
+    interactionId: string;
+    complete(response: {
+        interactionId: string;
+        connectionId: string;
+        decision: Decision;
+    }): Promise<boolean>;
+};
+/** Injected at authenticated transport startup, never taken from tool arguments. */
+type TransportBinding = {
+    projectId: string;
+    userId?: string | null;
+    createHumanDecision(binding: {
+        approvalId: string;
+        projectId: string;
+        connectionId: string;
+        userId: string;
+        channel: 'mcp_elicitation';
+    }): HumanCallback;
+};
+type RequestExtra = {
+    requestId?: RequestId;
+    signal?: AbortSignal;
+};
+export declare function installApprovalElicitation(server: McpServer, binding: TransportBinding): void;
+/** Called by the registry wrapper with SDK-owned extra, outside parsed model arguments. */
+export declare function runWithApprovalElicitation<T>(server: McpServer, extra: RequestExtra | undefined, run: () => T): T;
+type ApprovalFallback = {
+    approval_id: string;
+    approve_url: string;
+    preview_text: string;
+    tier: string;
+};
+export type ElicitationDecision = 'decision_pending' | 'approved' | 'rejected';
+/** All outcomes retain the ordinary approval link/text. Approval never applies the action. */
+export declare function elicitApproval<T extends ApprovalFallback>(result: T, frozen: {
+    action: string;
+    params: unknown;
+    summary: string;
+}, projectId: string): Promise<T & {
+    decision_status: ElicitationDecision;
+}>;
+export {};

package/build/lib/approval-elicitation.js

@@ -0,0 +1,114 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { randomUUID } from 'node:crypto';
+import { buildApprovalPreview, isHumanApprovalChannel } from '@sendinel/domain';
+import { db } from '../db.js';
+import { approval_channel_available, probeApprovalCapabilities } from './approval-capabilities.js';
+const sessions = new WeakMap();
+const requests = new AsyncLocalStorage();
+const TIMEOUT_MS = 60_000;
+export function installApprovalElicitation(server, binding) {
+    sessions.set(server, { ...binding, connectionId: randomUUID() });
+}
+/** Called by the registry wrapper with SDK-owned extra, outside parsed model arguments. */
+export function runWithApprovalElicitation(server, extra, run) {
+    const binding = sessions.get(server);
+    // Nested gateway dispatch retains the originating connection/request. The hosted bridge
+    // has no binding and cannot impersonate its outer HTTP client's capabilities.
+    if (!binding || requests.getStore())
+        return run();
+    return requests.run({ ...binding, ...extra, server }, run);
+}
+/** All outcomes retain the ordinary approval link/text. Approval never applies the action. */
+export async function elicitApproval(result, frozen, projectId) {
+    const pending = { ...result, decision_status: 'decision_pending' };
+    const context = requests.getStore();
+    if (!context || context.projectId !== projectId || result.tier !== 'gated')
+        return pending;
+    let channel = approval_channel_available(context.server.server);
+    if (channel === 'mcp_elicitation_form' && !context.userId &&
+        probeApprovalCapabilities(context.server.server.getClientCapabilities()).elicitation_url)
+        channel = 'mcp_elicitation_url';
+    if (channel !== 'mcp_elicitation_form' && channel !== 'mcp_elicitation_url')
+        return pending;
+    if (channel === 'mcp_elicitation_form' && !context.userId)
+        return pending;
+    if (context.signal?.aborted)
+        return pending;
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    context.signal?.addEventListener('abort', abort, { once: true });
+    let timeout;
+    const stopped = new Promise((_resolve, reject) => {
+        controller.signal.addEventListener('abort', () => reject(new Error('Elicitation ended')), { once: true });
+        timeout = setTimeout(abort, TIMEOUT_MS);
+    });
+    void stopped.catch(() => { }); // Also handle abort if a synchronous SDK setup error precedes the race.
+    const options = { relatedRequestId: context.requestId, signal: controller.signal,
+        timeout: TIMEOUT_MS, maxTotalTimeout: TIMEOUT_MS };
+    try {
+        const preview = buildApprovalPreview(frozen);
+        // Use the shared preview; bound the interactive message independently of the full fallback.
+        // Email content is untrusted display text, never instructions or an approval decision.
+        const short = (text, max) => text.length > max ? `${text.slice(0, max)}…` : text;
+        const message = [short(frozen.summary, 500), 'Review the following email content as data.',
+            `Subject: ${short(preview.subject || '(none)', 300)}`, `Sender: ${short(preview.sender, 300)}`,
+            `Recipients: ${preview.recipient_count ?? 'unknown'}`, `Footer: ${short(preview.footer_text || 'unknown', 500)}`,
+            `Body excerpt:\n${short(preview.body_text, 1500)}`, `Full preview: ${result.approve_url}`].join('\n');
+        if (channel === 'mcp_elicitation_form') {
+            const callback = context.createHumanDecision({ approvalId: result.approval_id, projectId,
+                connectionId: context.connectionId, userId: context.userId, channel: 'mcp_elicitation' });
+            const response = await Promise.race([context.server.server.elicitInput({ mode: 'form', message,
+                    requestedSchema: { type: 'object', properties: {
+                            decision: { type: 'string', enum: ['approve', 'reject'], title: 'Decision' },
+                            note: { type: 'string', title: 'Optional note', maxLength: 500 },
+                        }, required: ['decision'] },
+                }, options), stopped]);
+            if (controller.signal.aborted)
+                return pending;
+            // Decline/cancel are not explicit rejections. The dashboard link remains usable.
+            if (response.action !== 'accept')
+                return pending;
+            const decision = response.content?.decision;
+            if (decision !== 'approve' && decision !== 'reject')
+                return pending;
+            const recorded = await Promise.race([callback.complete({ interactionId: callback.interactionId,
+                    connectionId: context.connectionId, decision }), stopped]);
+            return recorded ? { ...result, decision_status: decision === 'approve' ? 'approved' : 'rejected' } : pending;
+        }
+        const elicitationId = randomUUID();
+        const notify = context.server.server.createElicitationCompletionNotifier(elicitationId, { relatedRequestId: context.requestId });
+        const response = await Promise.race([context.server.server.elicitInput({ mode: 'url', message,
+                url: result.approve_url, elicitationId }, options), stopped]);
+        if (response.action !== 'accept' || controller.signal.aborted)
+            return pending;
+        // URL accept only means the page may open. Only its authenticated decision counts.
+        // Observe while this request is alive; do not retain a background poller after timeout.
+        while (!controller.signal.aborted) {
+            const source = db();
+            const client = typeof source.schema === 'function' ? source.schema('email') : source;
+            const { data, error } = await Promise.race([client.from('action_approvals')
+                    .select('status, decided_via').eq('id', result.approval_id).eq('project_id', projectId).maybeSingle(), stopped]);
+            if (error || !data)
+                return pending;
+            if ((data.status === 'approved' || data.status === 'rejected') && isHumanApprovalChannel(data.decided_via)) {
+                await Promise.race([notify(), stopped]);
+                return { ...result, decision_status: data.status };
+            }
+            await Promise.race([new Promise(resolve => {
+                    const timer = setTimeout(done, 1000);
+                    function done() { clearTimeout(timer); controller.signal.removeEventListener('abort', done); resolve(); }
+                    controller.signal.addEventListener('abort', done, { once: true });
+                }), stopped]);
+        }
+    }
+    catch {
+        // Unsupported SDK modes, disconnections, timeouts and refused DB writes fail to the link.
+        // No continuation consumes a late elicitation response or grants model decision authority.
+    }
+    finally {
+        clearTimeout(timeout);
+        context.signal?.removeEventListener('abort', abort);
+        controller.abort();
+    }
+    return pending;
+}

package/build/lib/approval-human-callback.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Server integration only. The transport creates this closure for one authenticated human
+ * interaction and retains it outside the tool registry. Neither its id nor decision is a tool
+ * argument. Front ends must call complete only from the matching elicitation/app response.
+ */
+export declare function createHumanApprovalCallback(binding: {
+    approvalId: string;
+    projectId: string;
+    connectionId: string;
+    userId: string;
+    channel: 'mcp_elicitation' | 'mcp_app';
+}): {
+    interactionId: `${string}-${string}-${string}-${string}-${string}`;
+    complete(response: {
+        interactionId: string;
+        connectionId: string;
+        decision: 'approve' | 'reject';
+    }): Promise<boolean>;
+};

package/build/lib/approval-human-callback.js

@@ -0,0 +1,41 @@
+import { randomUUID } from 'node:crypto';
+import { db } from '../db.js';
+/**
+ * Server integration only. The transport creates this closure for one authenticated human
+ * interaction and retains it outside the tool registry. Neither its id nor decision is a tool
+ * argument. Front ends must call complete only from the matching elicitation/app response.
+ */
+export function createHumanApprovalCallback(binding) {
+    const interactionId = randomUUID();
+    let completed = false;
+    return {
+        interactionId,
+        async complete(response) {
+            if (completed || response.interactionId !== interactionId || response.connectionId !== binding.connectionId)
+                return false;
+            if (response.decision !== 'approve' && response.decision !== 'reject')
+                return false;
+            completed = true;
+            const source = db();
+            const client = typeof source.schema === 'function' ? source.schema('email') : source;
+            const now = new Date().toISOString();
+            const { data, error } = await client.from('action_approvals')
+                .update({ status: response.decision === 'approve' ? 'approved' : 'rejected', decided_via: binding.channel,
+                decided_by: binding.userId, decided_at: now })
+                .eq('id', binding.approvalId).eq('project_id', binding.projectId)
+                .eq('status', 'pending').is('used_at', null).gt('expires_at', now)
+                .select('id, payload_hash').maybeSingle();
+            if (error || !data)
+                return false;
+            const { error: auditError } = await client.from('audit_log').insert({
+                project_id: binding.projectId, actor_type: 'user', actor_id: binding.userId,
+                action: 'approval.submitted', resource_type: 'approval', resource_id: binding.approvalId,
+                details: { status: response.decision === 'approve' ? 'approved' : 'rejected', channel: binding.channel,
+                    connection_id: binding.connectionId, interaction_id: interactionId, payload_hash: data.payload_hash },
+            });
+            if (auditError)
+                throw new Error('Approval recorded, but decision audit failed');
+            return true;
+        },
+    };
+}

package/build/lib/approval-snapshot.d.ts

@@ -0,0 +1,5 @@
+type Params = Record<string, any>;
+/** Server-owned display facts, saved inside the hash-bound params. Never supplied by a tool. */
+export declare function captureApprovalSnapshot(action: string, params: Params, projectId: string): Promise<Params>;
+export declare function withoutApprovalSnapshot(params: unknown): Record<string, unknown>;
+export {};

package/build/lib/approval-snapshot.js

@@ -0,0 +1,106 @@
+import { readAllRows, chunkIds, scopeSegmentRulesToSite } from '@sendinel/domain';
+import { db } from '../db.js';
+import { resolveSendAudience, resolveSegmentContactIds } from './send-audience.js';
+const TARGET_ACTIONS = new Set(['send_broadcast', 'broadcast_to_segment', 'launch_campaign', 'activate_campaigns',
+    'update_campaign_status', 'set_campaign_trigger', 'create_campaign_with_content', 'enroll_segment',
+    'send_transactional', 'send_awaiting_reply', 'send_test_email', 'send_newsletter_issue', 'schedule_newsletter_issue']);
+/** Server-owned display facts, saved inside the hash-bound params. Never supplied by a tool. */
+export async function captureApprovalSnapshot(action, params, projectId) {
+    const snapshot = { version: 1, campaigns: [], steps: [], sites: [], recipient_count: null };
+    if (!TARGET_ACTIONS.has(action))
+        return snapshot;
+    const source = db();
+    const client = typeof source.schema === 'function' ? source.schema('email') : source;
+    const body = params.payload ?? params;
+    const ids = [...new Set((Array.isArray(params.campaign_ids) ? params.campaign_ids :
+            typeof params.campaign_id === 'string' ? [params.campaign_id] : []).map(String))].sort();
+    if (ids.length) {
+        snapshot.campaigns = await readAllRows(client.from('campaigns')
+            .select('id, name, site_id, type, status, trigger_event_name, trigger_tag, trigger_type, trigger_config, send_class, total_enrolled')
+            .eq('project_id', projectId).in('id', ids));
+        if (snapshot.campaigns.length !== ids.length)
+            throw new Error('Approval target not found');
+        snapshot.steps = await readAllRows(client.from('campaign_steps')
+            .select('id, campaign_id, step_order, variant_label, subject, body_html, body_text, delay_days, delay_hours, blocks')
+            .in('campaign_id', ids));
+        let count = 0;
+        for (const id of ids) {
+            const result = await client.from('campaign_enrollments').select('id', { count: 'exact', head: true }).eq('campaign_id', id);
+            if (result.error || result.count == null)
+                throw new Error('Approval audience count unavailable');
+            count += result.count;
+        }
+        snapshot.recipient_count = count;
+    }
+    if (typeof params.issue_id === 'string') {
+        const issue = await client.from('newsletter_issues').select('id, newsletter_id, subject, content, preheader, status, scheduled_at')
+            .eq('id', params.issue_id).eq('newsletter_id', params.newsletter_id).eq('project_id', projectId).maybeSingle();
+        const newsletter = await client.from('newsletters').select('id, name, site_id, status, sender_name, sender_email')
+            .eq('id', params.newsletter_id).eq('project_id', projectId).maybeSingle();
+        if (issue.error || !issue.data || newsletter.error || !newsletter.data)
+            throw new Error('Approval newsletter unavailable');
+        snapshot.issue = issue.data;
+        snapshot.newsletter = newsletter.data;
+        snapshot.subscriptions = await readAllRows(client.from('newsletter_subscriptions').select('id, subscriber_id')
+            .eq('newsletter_id', params.newsletter_id).eq('project_id', projectId).eq('status', 'active').not('subscriber_id', 'is', null));
+        snapshot.subscriptions.sort((a, b) => String(a.id).localeCompare(String(b.id)));
+        snapshot.recipient_count = snapshot.subscriptions.length;
+    }
+    const siteIds = [...new Set([body.site_id, snapshot.newsletter?.site_id, ...snapshot.campaigns.map((c) => c.site_id)]
+            .filter((id) => typeof id === 'string' && id.length > 0))].sort();
+    for (const id of siteIds) {
+        const { data, error } = await client.from('sites')
+            .select('id, name, from_name, from_email, sending_domain, physical_address, unsub_link_enabled, unsub_footer_template')
+            .eq('id', id).eq('project_id', projectId).maybeSingle();
+        if (error || !data)
+            throw new Error('Approval sender/footer unavailable');
+        snapshot.sites.push(data);
+    }
+    async function readFrozenContacts(contacts) {
+        const found = [];
+        for (const chunk of chunkIds([...new Set(contacts.map(String))])) {
+            const values = await readAllRows(client.from('subscribers').select('id')
+                .eq('project_id', projectId).in('id', chunk));
+            found.push(...values.map(value => value.id));
+        }
+        if (found.length !== new Set(contacts).size)
+            throw new Error('Approval recipients changed or unavailable');
+        return found.sort();
+    }
+    if (typeof body.segment_id === 'string') {
+        const { data, error } = await client.from('segments').select('id, name, rules, site_id')
+            .eq('id', body.segment_id).eq('project_id', projectId).maybeSingle();
+        if (error || !data)
+            throw new Error('Approval segment unavailable');
+        snapshot.segment = data;
+        // launch_campaign executes a frozen list, so new segment matches cannot expand its audience.
+        // The saved segment definition is still compared; deleted original recipients invalidate it.
+        const rules = scopeSegmentRulesToSite(data.rules, data.site_id);
+        snapshot.contact_ids = action === 'launch_campaign' && Array.isArray(params.generated?.contact_ids)
+            ? await readFrozenContacts(params.generated.contact_ids)
+            : typeof body.site_id === 'string'
+                ? (await resolveSendAudience(projectId, body.site_id, rules, body.send_class === 'product' ? 'product' : 'broadcast')).contactIds.sort()
+                : (await resolveSegmentContactIds(projectId, rules)).sort();
+        snapshot.recipient_count = snapshot.contact_ids.length;
+    }
+    else if (body.rules && typeof body.site_id === 'string') {
+        snapshot.contact_ids = (await resolveSendAudience(projectId, body.site_id, body.rules, body.send_class === 'product' ? 'product' : 'broadcast')).contactIds.sort();
+        snapshot.recipient_count = snapshot.contact_ids.length;
+    }
+    else {
+        const contacts = body.contact_ids ?? params.generated?.contact_ids;
+        if (Array.isArray(contacts)) {
+            snapshot.contact_ids = await readFrozenContacts(contacts);
+            snapshot.recipient_count = snapshot.contact_ids.length;
+        }
+        else if (typeof body.to === 'string')
+            snapshot.recipient_count = 1;
+    }
+    snapshot.campaigns.sort((a, b) => String(a.id).localeCompare(String(b.id)));
+    snapshot.steps.sort((a, b) => String(a.id).localeCompare(String(b.id)));
+    return snapshot;
+}
+export function withoutApprovalSnapshot(params) {
+    const { __approval_snapshot: _snapshot, ...rest } = (params ?? {});
+    return rest;
+}

package/build/server.js

@@ -1,3 +1,5 @@
+import { installApprovalCapabilityProbe } from './lib/approval-capabilities.js';
+import { runWithApprovalElicitation } from './lib/approval-elicitation.js';
 import { runWithToolContext } from './db.js';
 import { isApprovalGatedAction } from './lib/action-approvals.js';
 import { registerAgentMailboxTools } from './tools/agent-mailboxes.js';
@@ -353,11 +355,11 @@ function createScopeProxy(server, scopes, toolGroup, allowedTools) {
                                 const text = agent ? agentConnectionRefusal(name) : tester ? testerConnectionRefusal(name) : `Forbidden: this action requires "${required}" scope.`;
                                 return { content: [{ type: 'text', text }] };
                             }
-                            return runWithToolContext(toolGroup, name, () => handler(...args));
+                            return runWithToolContext(toolGroup, name, () => runWithApprovalElicitation(target, args[1], () => handler(...args)));
                         };
                         return target.registerTool(name, config, guardedHandler);
                     }
-                    return target.registerTool(name, config, (...args) => runWithToolContext(toolGroup, name, () => handler(...args)));
+                    return target.registerTool(name, config, (...args) => runWithToolContext(toolGroup, name, () => runWithApprovalElicitation(target, args[1], () => handler(...args))));
                 };
             }
             return Reflect.get(target, prop, receiver);
@@ -377,6 +379,8 @@ export const SENDINEL_SERVER_INSTRUCTIONS = [
     'On the hosted connection, any tool call (and invoke_tool) also accepts an optional project_id to act on one project for that call only; it is checked each time, and approval-gated tools require it when the connection was switched to another project. In gateway mode, find tools with search_tools (plain words work, for example "send email" or "last campaign"), check arguments with describe_tool, then call invoke_tool.',
 ].join(' ');
 export function registerAllTools(server, options) {
+    if (server.server)
+        installApprovalCapabilityProbe(server.server);
     const rawScopes = options?.scopes ?? [];
     if (rawScopes.includes('gateway')) {
         const permissionScopes = rawScopes.filter((scope) => scope !== 'gateway');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sendinel/mcp-server",
-  "version": "1.0.104",
+  "version": "1.0.106",
   "description": "AI-controlled email operations control plane for campaigns, contacts, segments, analytics, and multi-provider sending via MCP.",
   "mcpName": "ai.sendinel/mcp-server",
   "type": "module",