@frontmcp/sdk 0.7.2 → 0.8.0

package/elicitation/flows/elicitation-result.flow.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Elicitation Result Flow
+ *
+ * Flow for handling incoming elicitation results from the client.
+ * Provides hook points for middleware/plugins to intercept result processing.
+ *
+ * @module elicitation/flows/elicitation-result.flow
+ */
+import { FlowBase, FlowRunOptions } from '../../common';
+import { z } from 'zod';
+import type { ElicitResult } from '../elicitation.types';
+import type { PendingElicitRecord } from '../store';
+declare const inputSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+    result: z.ZodObject<{
+        action: z.ZodEnum<{
+            accept: "accept";
+            cancel: "cancel";
+            decline: "decline";
+        }>;
+        content: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+declare const outputSchema: z.ZodObject<{
+    handled: z.ZodBoolean;
+    elicitId: z.ZodOptional<z.ZodString>;
+    result: z.ZodType<ElicitResult | undefined>;
+}, z.core.$strip>;
+declare const stateSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+    action: z.ZodEnum<{
+        accept: "accept";
+        cancel: "cancel";
+        decline: "decline";
+    }>;
+    content: z.ZodOptional<z.ZodUnknown>;
+    pendingRecord: z.ZodType<PendingElicitRecord | undefined>;
+    elicitResult: z.ZodType<ElicitResult | undefined>;
+    handled: z.ZodDefault<z.ZodBoolean>;
+    output: z.ZodOptional<z.ZodObject<{
+        handled: z.ZodBoolean;
+        elicitId: z.ZodOptional<z.ZodString>;
+        result: z.ZodType<ElicitResult | undefined>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+declare const plan: {
+    readonly pre: ["parseInput"];
+    readonly execute: ["lookupPending", "validateContent", "buildResult", "publishResult"];
+    readonly finalize: ["finalize"];
+};
+declare global {
+    interface ExtendFlows {
+        'elicitation:result': FlowRunOptions<ElicitationResultFlow, typeof plan, typeof inputSchema, typeof outputSchema, typeof stateSchema>;
+    }
+}
+declare const name: "elicitation:result";
+/**
+ * Flow for handling elicitation results.
+ *
+ * This flow handles the processing of elicitation results:
+ * 1. Parse and validate input
+ * 2. Lookup pending record by session ID
+ * 3. Build the result object
+ * 4. Publish result via store (for distributed routing)
+ *
+ * The local handling (clearing timeouts, resolving promises) is still
+ * done by the transport adapter for performance.
+ */
+export default class ElicitationResultFlow extends FlowBase<typeof name> {
+    logger: import("../../common").FrontMcpLogger;
+    parseInput(): Promise<void>;
+    lookupPending(): Promise<void>;
+    validateContent(): Promise<void>;
+    buildResult(): Promise<void>;
+    publishResult(): Promise<void>;
+    finalize(): Promise<void>;
+}
+export { ElicitationResultFlow };
+//# sourceMappingURL=elicitation-result.flow.d.ts.map

package/elicitation/flows/elicitation-result.flow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"elicitation-result.flow.d.ts","sourceRoot":"","sources":["../../../src/elicitation/flows/elicitation-result.flow.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAQ,QAAQ,EAAyB,cAAc,EAAE,MAAM,cAAc,CAAC;AACrF,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,YAAY,EAAgB,MAAM,sBAAsB,CAAC;AACvE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAKpD,QAAA,MAAM,WAAW;;;;;;;;;;iBAQf,CAAC;AAEH,QAAA,MAAM,YAAY;;;YAMc,CAAC,CAAC,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC;iBACjE,CAAC;AAEH,QAAA,MAAM,WAAW;;;;;;;;mBAIsB,CAAC,CAAC,OAAO,CAAC,mBAAmB,GAAG,SAAS,CAAC;kBAC3C,CAAC,CAAC,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC;;;;;gBARzC,CAAC,CAAC,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC;;iBAWjE,CAAC;AAEH,QAAA,MAAM,IAAI;;;;CAI2B,CAAC;AAEtC,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,WAAW;QACnB,oBAAoB,EAAE,cAAc,CAClC,qBAAqB,EACrB,OAAO,IAAI,EACX,OAAO,WAAW,EAClB,OAAO,YAAY,EACnB,OAAO,WAAW,CACnB,CAAC;KACH;CACF;AAED,QAAA,MAAM,IAAI,EAAG,oBAA6B,CAAC;AAG3C;;;;;;;;;;;GAWG;AAQH,MAAM,CAAC,OAAO,OAAO,qBAAsB,SAAQ,QAAQ,CAAC,OAAO,IAAI,CAAC;IACtE,MAAM,wCAAmD;IAGnD,UAAU;IAkBV,aAAa;IAoBb,eAAe;IAyCf,WAAW;IAkBX,aAAa;IA+Bb,QAAQ;CAaf;AAED,OAAO,EAAE,qBAAqB,EAAE,CAAC"}

package/elicitation/flows/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Elicitation Flows
+ *
+ * Flow-based architecture for elicitation with hook support.
+ *
+ * @module elicitation/flows
+ */
+export { default as ElicitationRequestFlow, ElicitationRequestFlow as ElicitRequestFlow, } from './elicitation-request.flow';
+export { default as ElicitationResultFlow, ElicitationResultFlow as ElicitResultFlow } from './elicitation-result.flow';
+//# sourceMappingURL=index.d.ts.map

package/elicitation/flows/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/elicitation/flows/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,OAAO,IAAI,sBAAsB,EACjC,sBAAsB,IAAI,iBAAiB,GAC5C,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,OAAO,IAAI,qBAAqB,EAAE,qBAAqB,IAAI,gBAAgB,EAAE,MAAM,2BAA2B,CAAC"}

package/elicitation/helpers/elicit.helper.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Elicit Helper
+ *
+ * Extracted helper function for performing elicitation from context classes.
+ * This removes duplication between ToolContext and AgentContext.
+ *
+ * @module elicitation/helpers/elicit.helper
+ */
+import { ZodType } from 'zod';
+import type { ClientCapabilities } from '../../notification';
+import type { ElicitResult, ElicitOptions } from '../elicitation.types';
+import type { FrontMcpContext } from '../../context';
+/**
+ * Transport interface for elicitation.
+ * Matches the shape exposed by FrontMcpContext.
+ */
+export interface ElicitTransport {
+    elicit<S extends ZodType>(message: string, requestedSchema: S, options?: ElicitOptions): Promise<ElicitResult<S extends ZodType<infer O> ? O : unknown>>;
+}
+/**
+ * Dependencies required by the elicit helper.
+ */
+export interface ElicitHelperDeps {
+    /** Session ID for the current request */
+    sessionId: string | undefined;
+    /** Function to get client capabilities for the session */
+    getClientCapabilities: (sessionId: string) => ClientCapabilities | undefined;
+    /** Function to get the FrontMcpContext (may be unavailable) */
+    tryGetContext: () => FrontMcpContext | undefined;
+    /** Entry name for fallback context (tool name or agent name) */
+    entryName: string;
+    /** Entry input for fallback context (tool input or agent input) */
+    entryInput: unknown;
+    /**
+     * Whether elicitation is enabled in a server configuration.
+     * When false, calls to elicit() will throw ElicitationDisabledError.
+     * @default false
+     */
+    elicitationEnabled?: boolean;
+}
+/**
+ * Perform an elicitation request.
+ *
+ * This helper encapsulates the common elicitation logic shared between
+ * ToolContext and AgentContext.
+ *
+ * @param deps - Dependencies for the elicitation
+ * @param message - Message to display to the user
+ * @param requestedSchema - Zod schema for the expected response
+ * @param options - Elicitation options (mode, ttl, elicitationId)
+ * @returns The elicitation result
+ *
+ * @throws {ElicitationDisabledError} If elicitation is disabled in server configuration
+ * @throws {ElicitationNotSupportedError} If no session is available
+ * @throws {ElicitationNotSupportedError} If transport is not available
+ * @throws {ElicitationFallbackRequired} If client doesn't support elicitation (caught by flow)
+ */
+export declare function performElicit<S extends ZodType>(deps: ElicitHelperDeps, message: string, requestedSchema: S, options?: ElicitOptions): Promise<ElicitResult<S extends ZodType<infer O> ? O : unknown>>;
+/**
+ * Generate a unique elicitation ID using cryptographically strong UUID.
+ *
+ * @returns A unique elicitation ID
+ */
+export declare function generateElicitationId(): string;
+//# sourceMappingURL=elicit.helper.d.ts.map

package/elicitation/helpers/elicit.helper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"elicit.helper.d.ts","sourceRoot":"","sources":["../../../src/elicitation/helpers/elicit.helper.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,OAAO,EAAK,MAAM,KAAK,CAAC;AAGjC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAE7D,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAGxE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAErD;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,CAAC,SAAS,OAAO,EACtB,OAAO,EAAE,MAAM,EACf,eAAe,EAAE,CAAC,EAClB,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,YAAY,CAAC,CAAC,SAAS,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CACpE;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,yCAAyC;IACzC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAE9B,0DAA0D;IAC1D,qBAAqB,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,kBAAkB,GAAG,SAAS,CAAC;IAE7E,+DAA+D;IAC/D,aAAa,EAAE,MAAM,eAAe,GAAG,SAAS,CAAC;IAEjD,gEAAgE;IAChE,SAAS,EAAE,MAAM,CAAC;IAElB,mEAAmE;IACnE,UAAU,EAAE,OAAO,CAAC;IAEpB;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,aAAa,CAAC,CAAC,SAAS,OAAO,EACnD,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE,MAAM,EACf,eAAe,EAAE,CAAC,EAClB,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,YAAY,CAAC,CAAC,SAAS,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,CAkDjE;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,CAE9C"}

package/elicitation/helpers/extend-output-schema.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Output Schema Extension Utility
+ *
+ * Extends tool output schemas to include the elicitation fallback response type.
+ * This allows tools to return either their normal output OR an elicitation pending
+ * response when the client doesn't support the standard elicitation protocol.
+ */
+/**
+ * Extend a tool's output schema to include the elicitation fallback response type.
+ *
+ * When elicitation is enabled, tools may return an elicitation pending response
+ * instead of their normal output. This function wraps the original schema in a
+ * `oneOf` union to allow either response type.
+ *
+ * @param originalSchema - The tool's original output schema (may be undefined)
+ * @returns Extended schema that allows either the original output or elicitation fallback
+ *
+ * @example
+ * // Original schema:
+ * { type: 'object', properties: { result: { type: 'string' } } }
+ *
+ * // Extended schema:
+ * {
+ *   oneOf: [
+ *     { type: 'object', properties: { result: { type: 'string' } } },
+ *     { type: 'object', properties: { elicitationPending: { ... } }, required: ['elicitationPending'] }
+ *   ]
+ * }
+ */
+export declare function extendOutputSchemaForElicitation(originalSchema: Record<string, unknown> | undefined): Record<string, unknown>;
+//# sourceMappingURL=extend-output-schema.d.ts.map

package/elicitation/helpers/extend-output-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extend-output-schema.d.ts","sourceRoot":"","sources":["../../../src/elicitation/helpers/extend-output-schema.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,gCAAgC,CAC9C,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAClD,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAsCzB"}

package/elicitation/helpers/fallback.helper.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Elicitation Fallback Helpers
+ *
+ * Handles fallback logic when clients don't support native MCP elicitation.
+ * Used by CallToolFlow to choose between waiting and fire-and-forget patterns.
+ *
+ * @module elicitation/helpers/fallback.helper
+ */
+import type { FrontMcpLogger } from '../../common';
+import type { Scope } from '../../scope';
+import { ElicitationFallbackRequired } from '../../errors';
+/**
+ * Dependencies required by fallback handler functions.
+ */
+export interface FallbackHandlerDeps {
+    /** The scope instance with notification service and elicitation store */
+    scope: Scope;
+    /** Session ID for the current request */
+    sessionId: string;
+    /** Logger for diagnostic output */
+    logger: FrontMcpLogger;
+}
+/**
+ * Check if notifications can be delivered to this session.
+ *
+ * Returns true if the client is registered with at least one defined capability,
+ * indicating it's a full MCP client that can process notifications.
+ * Clients with empty capabilities (e.g., `{}`) or all-undefined values are
+ * assumed to be minimal clients that cannot process notification-based flows.
+ *
+ * @param scope - The scope with notification service
+ * @param sessionId - The session to check
+ * @returns true if notifications can be delivered
+ */
+export declare function canDeliverNotifications(scope: Scope, sessionId: string): boolean;
+/**
+ * Send a fallback notification to inform the LLM about elicitation requirements.
+ *
+ * This notification tells the LLM to call the `sendElicitationResult` tool
+ * with the collected user input.
+ *
+ * @param deps - Dependencies including scope, sessionId, and logger
+ * @param error - The ElicitationFallbackRequired error with elicitation details
+ */
+export declare function sendFallbackNotification(deps: FallbackHandlerDeps, error: ElicitationFallbackRequired): void;
+/**
+ * Handle elicitation fallback using the waiting pattern.
+ *
+ * For streamable-http with notification support:
+ * 1. Send notification with fallback instructions BEFORE waiting
+ * 2. Subscribe to pub/sub channel for the result
+ * 3. Wait for result with timeout
+ * 4. Return the actual tool result (not fallback instructions)
+ *
+ * @param deps - Dependencies including scope, sessionId, and logger
+ * @param error - The ElicitationFallbackRequired error with elicitation details
+ * @returns Promise that resolves with the tool result when sendElicitationResult is called
+ */
+export declare function handleWaitingFallback(deps: FallbackHandlerDeps, error: ElicitationFallbackRequired): Promise<unknown>;
+//# sourceMappingURL=fallback.helper.d.ts.map

package/elicitation/helpers/fallback.helper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fallback.helper.d.ts","sourceRoot":"","sources":["../../../src/elicitation/helpers/fallback.helper.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAGzC,OAAO,EAAE,2BAA2B,EAAgC,MAAM,cAAc,CAAC;AAUzF;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,yEAAyE;IACzE,KAAK,EAAE,KAAK,CAAC;IACb,yCAAyC;IACzC,SAAS,EAAE,MAAM,CAAC;IAClB,mCAAmC;IACnC,MAAM,EAAE,cAAc,CAAC;CACxB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAMhF;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,mBAAmB,EAAE,KAAK,EAAE,2BAA2B,GAAG,IAAI,CAqB5G;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,mBAAmB,EACzB,KAAK,EAAE,2BAA2B,GACjC,OAAO,CAAC,OAAO,CAAC,CA2FlB"}

package/elicitation/helpers/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Elicitation Helpers Module
+ *
+ * Helper functions for elicitation that can be used by context classes.
+ *
+ * @module elicitation/helpers
+ */
+export { performElicit, generateElicitationId, type ElicitHelperDeps, type ElicitTransport } from './elicit.helper';
+export { extendOutputSchemaForElicitation } from './extend-output-schema';
+export { validateElicitationContent, type ElicitationValidationResult } from './validate-elicitation-content';
+export { canDeliverNotifications, sendFallbackNotification, handleWaitingFallback, type FallbackHandlerDeps, } from './fallback.helper';
+//# sourceMappingURL=index.d.ts.map

package/elicitation/helpers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/elicitation/helpers/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,aAAa,EAAE,qBAAqB,EAAE,KAAK,gBAAgB,EAAE,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACpH,OAAO,EAAE,gCAAgC,EAAE,MAAM,wBAAwB,CAAC;AAC1E,OAAO,EAAE,0BAA0B,EAAE,KAAK,2BAA2B,EAAE,MAAM,gCAAgC,CAAC;AAC9G,OAAO,EACL,uBAAuB,EACvB,wBAAwB,EACxB,qBAAqB,EACrB,KAAK,mBAAmB,GACzB,MAAM,mBAAmB,CAAC"}

package/elicitation/helpers/validate-elicitation-content.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Elicitation Content Validation Helper
+ *
+ * Validates elicitation result content against the stored JSON Schema.
+ * Uses zod-from-json-schema for JSON Schema to Zod conversion.
+ *
+ * @module elicitation/helpers/validate-elicitation-content
+ */
+/**
+ * Validation result interface.
+ */
+export interface ElicitationValidationResult {
+    /** Whether validation succeeded */
+    success: boolean;
+    /** Validation errors (if any) */
+    errors?: Array<{
+        path: string[];
+        message: string;
+    }>;
+}
+/**
+ * Validate elicitation content against a JSON Schema.
+ *
+ * This function converts the JSON Schema to a Zod schema and validates
+ * the content against it.
+ *
+ * @param content - The content to validate
+ * @param jsonSchema - The JSON Schema to validate against
+ * @returns Validation result with success flag and optional errors
+ *
+ * @example
+ * ```typescript
+ * const result = validateElicitationContent(
+ *   { name: 'John', age: '30' }, // age should be number
+ *   {
+ *     type: 'object',
+ *     properties: {
+ *       name: { type: 'string' },
+ *       age: { type: 'number' }
+ *     },
+ *     required: ['name', 'age']
+ *   }
+ * );
+ *
+ * if (!result.success) {
+ *   console.log(result.errors);
+ *   // [{ path: ['age'], message: 'Expected number, received string' }]
+ * }
+ * ```
+ */
+export declare function validateElicitationContent(content: unknown, jsonSchema: Record<string, unknown>): ElicitationValidationResult;
+//# sourceMappingURL=validate-elicitation-content.d.ts.map

package/elicitation/helpers/validate-elicitation-content.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-elicitation-content.d.ts","sourceRoot":"","sources":["../../../src/elicitation/helpers/validate-elicitation-content.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C,mCAAmC;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,iCAAiC;IACjC,MAAM,CAAC,EAAE,KAAK,CAAC;QACb,IAAI,EAAE,MAAM,EAAE,CAAC;QACf,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC,CAAC;CACJ;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,OAAO,EAChB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAClC,2BAA2B,CA4B7B"}

package/elicitation/hooks/elicitation.hooks.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Elicitation Hook Decorators
+ *
+ * Provides type-safe hook decorators for intercepting elicitation flows.
+ *
+ * @module elicitation/hooks/elicitation.hooks
+ */
+/**
+ * Hook decorators for the elicitation:request flow.
+ *
+ * Use these decorators in plugins or middleware to intercept
+ * elicitation request processing at various stages.
+ *
+ * @example
+ * ```typescript
+ * import { ElicitationRequestHook } from '@frontmcp/sdk/elicitation';
+ *
+ * class MyPlugin {
+ *   @ElicitationRequestHook.Will('storePendingRecord')
+ *   async beforeStorePending(state) {
+ *     // Modify state before storing
+ *   }
+ *
+ *   @ElicitationRequestHook.Did('finalize')
+ *   async afterFinalize(state) {
+ *     // React to completed elicitation request
+ *   }
+ * }
+ * ```
+ */
+export declare const ElicitationRequestHook: {
+    Stage: (stage: "finalize" | "parseInput" | "validateRequest" | "generateElicitId" | "storePendingRecord" | "buildRequestParams", opts?: import("../../common").HookOptions<import("../flows").ElicitationRequestFlow>) => MethodDecorator;
+    Will: (stage: "finalize" | "parseInput" | "validateRequest" | "generateElicitId" | "storePendingRecord" | "buildRequestParams", opts?: import("../../common").HookOptions<import("../flows").ElicitationRequestFlow>) => MethodDecorator;
+    Did: (stage: "finalize" | "parseInput" | "validateRequest" | "generateElicitId" | "storePendingRecord" | "buildRequestParams", opts?: import("../../common").HookOptions<import("../flows").ElicitationRequestFlow>) => MethodDecorator;
+    Around: (stage: "finalize" | "parseInput" | "validateRequest" | "generateElicitId" | "storePendingRecord" | "buildRequestParams", opts?: import("../../common").HookOptions<import("../flows").ElicitationRequestFlow>) => MethodDecorator;
+};
+/**
+ * Hook decorators for the elicitation:result flow.
+ *
+ * Use these decorators in plugins or middleware to intercept
+ * elicitation result processing at various stages.
+ *
+ * @example
+ * ```typescript
+ * import { ElicitationResultHook } from '@frontmcp/sdk/elicitation';
+ *
+ * class MyPlugin {
+ *   @ElicitationResultHook.Will('publishResult')
+ *   async beforePublish(state) {
+ *     // Validate or transform result before publishing
+ *   }
+ *
+ *   @ElicitationResultHook.Did('finalize')
+ *   async afterFinalize(state) {
+ *     // Log or audit completed result handling
+ *   }
+ * }
+ * ```
+ */
+export declare const ElicitationResultHook: {
+    Stage: (stage: "finalize" | "parseInput" | "lookupPending" | "validateContent" | "buildResult" | "publishResult", opts?: import("../../common").HookOptions<import("../flows").ElicitationResultFlow>) => MethodDecorator;
+    Will: (stage: "finalize" | "parseInput" | "lookupPending" | "validateContent" | "buildResult" | "publishResult", opts?: import("../../common").HookOptions<import("../flows").ElicitationResultFlow>) => MethodDecorator;
+    Did: (stage: "finalize" | "parseInput" | "lookupPending" | "validateContent" | "buildResult" | "publishResult", opts?: import("../../common").HookOptions<import("../flows").ElicitationResultFlow>) => MethodDecorator;
+    Around: (stage: "finalize" | "parseInput" | "lookupPending" | "validateContent" | "buildResult" | "publishResult", opts?: import("../../common").HookOptions<import("../flows").ElicitationResultFlow>) => MethodDecorator;
+};
+//# sourceMappingURL=elicitation.hooks.d.ts.map

package/elicitation/hooks/elicitation.hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"elicitation.hooks.d.ts","sourceRoot":"","sources":["../../../src/elicitation/hooks/elicitation.hooks.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,sBAAsB;;;;;CAA4D,CAAC;AAEhG;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,qBAAqB;;;;;CAA0D,CAAC"}

package/elicitation/hooks/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Elicitation Hooks
+ *
+ * Hook decorators for intercepting elicitation flows.
+ *
+ * @module elicitation/hooks
+ */
+export { ElicitationRequestHook, ElicitationResultHook } from './elicitation.hooks';
+//# sourceMappingURL=index.d.ts.map

package/elicitation/hooks/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/elicitation/hooks/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC"}

package/elicitation/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Elicitation Module
+ *
+ * MCP elicitation support for requesting interactive user input
+ * from clients during tool or agent execution.
+ *
+ * Uses @frontmcp/utils storage for unified backend support:
+ * - Memory: For development and single-node deployments
+ * - Redis: For distributed/multi-node production deployments
+ * - Upstash: For edge deployments with pub/sub support
+ *
+ * Note: Vercel KV is NOT supported (no pub/sub capability).
+ */
+export * from './elicitation.types';
+export { ELICITATION_FALLBACK_JSON_SCHEMA, type ElicitationFallbackResponse } from './elicitation-fallback.schema';
+export * from './store';
+export * from './helpers';
+//# sourceMappingURL=index.d.ts.map

package/elicitation/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/elicitation/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,cAAc,qBAAqB,CAAC;AAGpC,OAAO,EAAE,gCAAgC,EAAE,KAAK,2BAA2B,EAAE,MAAM,+BAA+B,CAAC;AAGnH,cAAc,SAAS,CAAC;AAGxB,cAAc,WAAW,CAAC"}

package/elicitation/send-elicitation-result.tool.d.ts

@@ -0,0 +1,18 @@
+/**
+ * SendElicitationResult System Tool
+ *
+ * System tool for submitting user responses for pending elicitation requests.
+ * Used as a fallback for MCP clients that don't support the standard elicitation protocol.
+ *
+ * Flow:
+ * 1. Tool calls elicit() -> client doesn't support elicitation -> ElicitationFallbackRequired thrown
+ * 2. CallToolFlow catches error, stores pending context, returns instructions to LLM
+ * 3. LLM asks user for input, then calls this tool with the response
+ * 4. This tool stores the resolved result and re-invokes the original tool
+ * 5. Original tool's elicit() returns the pre-resolved result immediately
+ */
+/**
+ * Check if a tool name is the sendElicitationResult system tool.
+ */
+export declare function isSendElicitationResultTool(toolName: string): boolean;
+//# sourceMappingURL=send-elicitation-result.tool.d.ts.map

package/elicitation/send-elicitation-result.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"send-elicitation-result.tool.d.ts","sourceRoot":"","sources":["../../src/elicitation/send-elicitation-result.tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAqLH;;GAEG;AACH,wBAAgB,2BAA2B,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAErE"}

package/elicitation/store/elicitation-encryption.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Elicitation Store Encryption
+ *
+ * Session-based encryption for elicitation store data.
+ * Uses HKDF-SHA256 for key derivation and AES-256-GCM for encryption.
+ *
+ * Security Model:
+ * - Each session gets a unique encryption key derived from sessionId + server secret
+ * - Only requests with the actual sessionId can decrypt the elicitation data
+ * - Zero-knowledge: Server storage contains only encrypted blobs
+ *
+ * @module elicitation/store/elicitation-encryption
+ */
+import { type EncBlob } from '@frontmcp/utils';
+/**
+ * Encrypted blob structure for elicitation storage.
+ * Re-exports EncBlob from @frontmcp/utils for consistency.
+ */
+export type ElicitationEncryptedBlob = EncBlob;
+/**
+ * Configuration for elicitation encryption.
+ */
+export interface ElicitationEncryptionConfig {
+    /**
+     * Whether encryption is enabled.
+     * @default true in production, false in development
+     */
+    enabled: boolean;
+    /**
+     * Server secret for key derivation.
+     * Falls back to MCP_ELICITATION_SECRET or MCP_SESSION_SECRET env vars.
+     */
+    secret?: string;
+}
+/**
+ * Get the base secret for elicitation encryption.
+ * Checks environment variables in order of specificity.
+ *
+ * @returns The secret string, or null if not configured
+ */
+export declare function getElicitationSecret(): string | null;
+/**
+ * Check if elicitation encryption is available.
+ * Returns true if a secret is configured via environment variables.
+ */
+export declare function isElicitationEncryptionAvailable(): boolean;
+/**
+ * Derive a session-specific encryption key using HKDF-SHA256.
+ *
+ * Key derivation:
+ * - IKM (Input Key Material): serverSecret + sessionId
+ * - Salt: "elicitation-store-v1"
+ * - Info: "elicit:{sessionId}"
+ * - Output: 32-byte (256-bit) key for AES-256-GCM
+ *
+ * This ensures each session gets a unique key that:
+ * 1. Cannot be derived without knowing the server secret
+ * 2. Is deterministic for a given sessionId (same key on all nodes)
+ * 3. Is cryptographically isolated from other sessions
+ *
+ * @param sessionId - The session ID to derive a key for
+ * @param secret - Optional secret override (defaults to env var)
+ * @returns 32-byte encryption key
+ * @throws Error if no secret is available
+ */
+export declare function deriveElicitationKey(sessionId: string, secret?: string): Promise<Uint8Array>;
+/**
+ * Encrypt elicitation data using session-derived key.
+ *
+ * Uses AES-256-GCM for authenticated encryption:
+ * - 12-byte random IV
+ * - 16-byte authentication tag
+ * - Ciphertext
+ *
+ * @param data - Data to encrypt (will be JSON serialized)
+ * @param sessionId - Session ID for key derivation
+ * @param secret - Optional secret override
+ * @returns Encrypted blob
+ */
+export declare function encryptElicitationData<T>(data: T, sessionId: string, secret?: string): Promise<ElicitationEncryptedBlob>;
+/**
+ * Decrypt elicitation data using session-derived key.
+ *
+ * @param blob - Encrypted blob to decrypt
+ * @param sessionId - Session ID for key derivation
+ * @param secret - Optional secret override
+ * @returns Decrypted and parsed value, or null if decryption fails
+ */
+export declare function decryptElicitationData<T>(blob: ElicitationEncryptedBlob, sessionId: string, secret?: string): Promise<T | null>;
+/**
+ * Serialize encrypted blob to a string for storage.
+ */
+export declare function serializeElicitationBlob(blob: ElicitationEncryptedBlob): string;
+/**
+ * Deserialize a string back to encrypted blob.
+ * Returns null if the string is not a valid encrypted blob.
+ */
+export declare function deserializeElicitationBlob(str: string): ElicitationEncryptedBlob | null;
+/**
+ * Check if a value is an encrypted blob.
+ * Used for migration: detecting encrypted vs. plaintext data.
+ */
+export declare function isEncryptedBlob(value: unknown): value is ElicitationEncryptedBlob;
+/**
+ * Encrypt and serialize in one step.
+ *
+ * @param data - Data to encrypt
+ * @param sessionId - Session ID for key derivation
+ * @param secret - Optional secret override
+ * @returns Serialized encrypted blob string
+ */
+export declare function encryptAndSerialize<T>(data: T, sessionId: string, secret?: string): Promise<string>;
+/**
+ * Deserialize and decrypt in one step.
+ *
+ * @param str - Serialized encrypted blob string
+ * @param sessionId - Session ID for key derivation
+ * @param secret - Optional secret override
+ * @returns Decrypted value, or null if decryption fails
+ */
+export declare function deserializeAndDecrypt<T>(str: string, sessionId: string, secret?: string): Promise<T | null>;
+/**
+ * Try to decrypt stored data.
+ *
+ * Similar to deserializeAndDecrypt but accepts parsed value directly.
+ * Useful when the storage layer already parsed the JSON.
+ *
+ * @param value - Stored value (must be encrypted blob)
+ * @param sessionId - Session ID for key derivation
+ * @param secret - Optional secret override
+ * @returns Decrypted value, or null if not encrypted or decryption fails
+ */
+export declare function tryDecryptStoredValue<T>(value: unknown, sessionId: string, secret?: string): Promise<T | null>;
+//# sourceMappingURL=elicitation-encryption.d.ts.map

package/elicitation/store/elicitation-encryption.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"elicitation-encryption.d.ts","sourceRoot":"","sources":["../../../src/elicitation/store/elicitation-encryption.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAOL,KAAK,OAAO,EACb,MAAM,iBAAiB,CAAC;AAMzB;;;GAGG;AACH,MAAM,MAAM,wBAAwB,GAAG,OAAO,CAAC;AAE/C;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C;;;OAGG;IACH,OAAO,EAAE,OAAO,CAAC;IAEjB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAmBD;;;;;GAKG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,GAAG,IAAI,CAOpD;AAED;;;GAGG;AACH,wBAAgB,gCAAgC,IAAI,OAAO,CAE1D;AAMD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAmBlG;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAsB,sBAAsB,CAAC,CAAC,EAC5C,IAAI,EAAE,CAAC,EACP,SAAS,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,wBAAwB,CAAC,CAanC;AAED;;;;;;;GAOG;AACH,wBAAsB,sBAAsB,CAAC,CAAC,EAC5C,IAAI,EAAE,wBAAwB,EAC9B,SAAS,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAenB;AAMD;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,wBAAwB,GAAG,MAAM,CAE/E;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,MAAM,GAAG,wBAAwB,GAAG,IAAI,CAUvF;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,wBAAwB,CAajF;AAMD;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAGzG;AAED;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAMjH;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,qBAAqB,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAKpH"}