@frontmcp/sdk 0.5.1 → 0.6.1

package/src/common/types/options/transport.options.d.ts

@@ -0,0 +1,148 @@
+import { z } from 'zod';
+import { SessionMode, TransportIdMode, PlatformMappingEntry, PlatformDetectionConfig, platformDetectionConfigSchema } from './session.options';
+export type { SessionMode, TransportIdMode, PlatformMappingEntry, PlatformDetectionConfig };
+/**
+ * Transport persistence configuration
+ * Enables session persistence to Redis and automatic transport recreation after server restart
+ */
+export declare const transportPersistenceConfigSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    redis: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+        provider: z.ZodLiteral<"redis">;
+        host: z.ZodString;
+        port: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+        password: z.ZodOptional<z.ZodString>;
+        db: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+        tls: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        keyPrefix: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        defaultTtlMs: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    }, z.core.$strip>, z.ZodObject<{
+        provider: z.ZodLiteral<"vercel-kv">;
+        url: z.ZodOptional<z.ZodString>;
+        token: z.ZodOptional<z.ZodString>;
+        keyPrefix: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        defaultTtlMs: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    }, z.core.$strip>, z.ZodPipe<z.ZodObject<{
+        host: z.ZodString;
+        port: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+        password: z.ZodOptional<z.ZodString>;
+        db: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+        tls: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        keyPrefix: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        defaultTtlMs: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    }, z.core.$strip>, z.ZodTransform<{
+        provider: "redis";
+        host: string;
+        port: number;
+        db: number;
+        tls: boolean;
+        keyPrefix: string;
+        defaultTtlMs: number;
+        password?: string | undefined;
+    }, {
+        host: string;
+        port: number;
+        db: number;
+        tls: boolean;
+        keyPrefix: string;
+        defaultTtlMs: number;
+        password?: string | undefined;
+    }>>]>>;
+    defaultTtlMs: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+/**
+ * Transport options schema
+ * Consolidates transport protocol config + session lifecycle config
+ */
+export declare const transportOptionsSchema: z.ZodObject<{
+    sessionMode: z.ZodDefault<z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"stateful">, z.ZodLiteral<"stateless">, z.ZodFunction<z.core.$ZodFunctionArgs, z.core.$ZodFunctionOut>]>>>;
+    transportIdMode: z.ZodDefault<z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"uuid">, z.ZodLiteral<"jwt">, z.ZodFunction<z.core.$ZodFunctionArgs, z.core.$ZodFunctionOut>]>>>;
+    platformDetection: z.ZodOptional<z.ZodObject<{
+        mappings: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            pattern: z.ZodUnion<readonly [z.ZodString, z.ZodCustom<RegExp, RegExp>]>;
+            platform: z.ZodEnum<{
+                unknown: "unknown";
+                continue: "continue";
+                openai: "openai";
+                claude: "claude";
+                gemini: "gemini";
+                cursor: "cursor";
+                cody: "cody";
+                "generic-mcp": "generic-mcp";
+                "ext-apps": "ext-apps";
+            }>;
+        }, z.core.$strip>>>;
+        customOnly: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    }, z.core.$strip>>;
+    enableLegacySSE: z.ZodDefault<z.ZodBoolean>;
+    enableSseListener: z.ZodDefault<z.ZodBoolean>;
+    enableStreamableHttp: z.ZodDefault<z.ZodBoolean>;
+    enableStatelessHttp: z.ZodDefault<z.ZodBoolean>;
+    enableStatefulHttp: z.ZodDefault<z.ZodBoolean>;
+    requireSessionForStreamable: z.ZodDefault<z.ZodBoolean>;
+    persistence: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        redis: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+            provider: z.ZodLiteral<"redis">;
+            host: z.ZodString;
+            port: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+            password: z.ZodOptional<z.ZodString>;
+            db: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+            tls: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+            keyPrefix: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+            defaultTtlMs: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+        }, z.core.$strip>, z.ZodObject<{
+            provider: z.ZodLiteral<"vercel-kv">;
+            url: z.ZodOptional<z.ZodString>;
+            token: z.ZodOptional<z.ZodString>;
+            keyPrefix: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+            defaultTtlMs: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+        }, z.core.$strip>, z.ZodPipe<z.ZodObject<{
+            host: z.ZodString;
+            port: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+            password: z.ZodOptional<z.ZodString>;
+            db: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+            tls: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+            keyPrefix: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+            defaultTtlMs: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+        }, z.core.$strip>, z.ZodTransform<{
+            provider: "redis";
+            host: string;
+            port: number;
+            db: number;
+            tls: boolean;
+            keyPrefix: string;
+            defaultTtlMs: number;
+            password?: string | undefined;
+        }, {
+            host: string;
+            port: number;
+            db: number;
+            tls: boolean;
+            keyPrefix: string;
+            defaultTtlMs: number;
+            password?: string | undefined;
+        }>>]>>;
+        defaultTtlMs: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * Transport options type (with defaults applied)
+ */
+export type TransportOptions = z.infer<typeof transportOptionsSchema>;
+/**
+ * Transport options input type (for user configuration)
+ */
+export type TransportOptionsInput = z.input<typeof transportOptionsSchema>;
+/**
+ * Transport persistence configuration type
+ */
+export type TransportPersistenceConfig = z.infer<typeof transportPersistenceConfigSchema>;
+/**
+ * Transport persistence configuration input type
+ */
+export type TransportPersistenceConfigInput = z.input<typeof transportPersistenceConfigSchema>;
+/**
+ * Platform detection configuration type
+ */
+export type PlatformDetectionConfigType = z.infer<typeof platformDetectionConfigSchema>;

package/src/common/types/options/transport.options.js

@@ -0,0 +1,121 @@
+"use strict";
+// common/types/options/transport.options.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.transportOptionsSchema = exports.transportPersistenceConfigSchema = void 0;
+const zod_1 = require("zod");
+const redis_options_1 = require("./redis.options");
+const session_options_1 = require("./session.options");
+// ============================================
+// TRANSPORT PERSISTENCE (from auth.transport.recreation)
+// ============================================
+/**
+ * Transport persistence configuration
+ * Enables session persistence to Redis and automatic transport recreation after server restart
+ */
+exports.transportPersistenceConfigSchema = zod_1.z.object({
+    /**
+     * Enable transport persistence to Redis
+     * When enabled, sessions are persisted to Redis and transports can be recreated after restart
+     * @default false
+     */
+    enabled: zod_1.z.boolean().default(false),
+    /**
+     * Redis configuration for session storage
+     * If omitted when enabled=true, uses top-level redis config
+     * Note: Validation for redis presence happens at runtime when persistence is used
+     */
+    redis: redis_options_1.redisOptionsSchema.optional(),
+    /**
+     * Default TTL for stored session metadata (milliseconds)
+     * @default 3600000 (1 hour)
+     */
+    defaultTtlMs: zod_1.z.number().int().positive().default(3600000),
+});
+// ============================================
+// TRANSPORT OPTIONS (unified config)
+// ============================================
+/**
+ * Transport options schema
+ * Consolidates transport protocol config + session lifecycle config
+ */
+exports.transportOptionsSchema = zod_1.z.object({
+    // ============================================
+    // Session Lifecycle (from session.options.ts)
+    // ============================================
+    /**
+     * Defines how the session lifecycle and nested tokens are managed.
+     *
+     * Modes:
+     * - `'stateful'`: Session and nested tokens are stored in a server-side store (e.g., Redis).
+     * - `'stateless'`: All session data (including nested tokens) is embedded within a signed/encrypted JWT.
+     *
+     * @default 'stateful'
+     */
+    sessionMode: zod_1.z
+        .union([zod_1.z.literal('stateful'), zod_1.z.literal('stateless'), zod_1.z.function()])
+        .optional()
+        .default('stateful'),
+    /**
+     * Defines how the Transport ID is generated, verified, and used across sessions.
+     *
+     * Modes:
+     * - `'uuid'`: Generates a random UUID per session.
+     * - `'jwt'`: Uses a signed JWT for stateless sessions, signed with a generated session key.
+     *
+     * @default 'uuid'
+     */
+    transportIdMode: zod_1.z
+        .union([zod_1.z.literal('uuid'), zod_1.z.literal('jwt'), zod_1.z.function()])
+        .optional()
+        .default('uuid'),
+    /**
+     * Configuration for detecting the AI platform from MCP client info.
+     * Allows custom mappings to override or supplement the default keyword-based detection.
+     */
+    platformDetection: session_options_1.platformDetectionConfigSchema.optional(),
+    // ============================================
+    // Transport Protocols (from auth.transport)
+    // ============================================
+    /**
+     * Enable legacy SSE transport (old HTTP+SSE protocol)
+     * @default false
+     */
+    enableLegacySSE: zod_1.z.boolean().default(false),
+    /**
+     * Enable SSE listener for server-initiated messages (GET /mcp with Accept: text/event-stream)
+     * @default true
+     */
+    enableSseListener: zod_1.z.boolean().default(true),
+    /**
+     * Enable streamable HTTP transport (POST with SSE response)
+     * @default true
+     */
+    enableStreamableHttp: zod_1.z.boolean().default(true),
+    /**
+     * Enable stateless HTTP mode (requests without session ID)
+     * When enabled, allows requests without prior initialize
+     * Uses shared singleton transport for anonymous, per-token singleton for authenticated
+     * @default false
+     */
+    enableStatelessHttp: zod_1.z.boolean().default(false),
+    /**
+     * Enable stateful HTTP transport (JSON-only responses)
+     * @default false
+     */
+    enableStatefulHttp: zod_1.z.boolean().default(false),
+    /**
+     * Require session ID for streamable HTTP (non-stateless mode)
+     * When false, streamable HTTP requests don't require prior initialize
+     * @default true
+     */
+    requireSessionForStreamable: zod_1.z.boolean().default(true),
+    // ============================================
+    // Transport Persistence
+    // ============================================
+    /**
+     * Transport persistence configuration
+     * When enabled, sessions are persisted to Redis and transports can be recreated after server restart
+     */
+    persistence: exports.transportPersistenceConfigSchema.optional(),
+});
+//# sourceMappingURL=transport.options.js.map

package/src/common/types/options/transport.options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.options.js","sourceRoot":"","sources":["../../../../../src/common/types/options/transport.options.ts"],"names":[],"mappings":";AAAA,4CAA4C;;;AAE5C,6BAAwB;AACxB,mDAAqD;AACrD,uDAO2B;AAK3B,+CAA+C;AAC/C,yDAAyD;AACzD,+CAA+C;AAE/C;;;GAGG;AACU,QAAA,gCAAgC,GAAG,OAAC,CAAC,MAAM,CAAC;IACvD;;;;OAIG;IACH,OAAO,EAAE,OAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;IAEnC;;;;OAIG;IACH,KAAK,EAAE,kCAAkB,CAAC,QAAQ,EAAE;IAEpC;;;OAGG;IACH,YAAY,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC;CAC3D,CAAC,CAAC;AAEH,+CAA+C;AAC/C,qCAAqC;AACrC,+CAA+C;AAE/C;;;GAGG;AACU,QAAA,sBAAsB,GAAG,OAAC,CAAC,MAAM,CAAC;IAC7C,+CAA+C;IAC/C,8CAA8C;IAC9C,+CAA+C;IAE/C;;;;;;;;OAQG;IACH,WAAW,EAAE,OAAC;SACX,KAAK,CAAC,CAAC,OAAC,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,OAAC,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,OAAC,CAAC,QAAQ,EAAE,CAAC,CAAC;SACpE,QAAQ,EAAE;SACV,OAAO,CAAC,UAAU,CAAC;IAEtB;;;;;;;;OAQG;IACH,eAAe,EAAE,OAAC;SACf,KAAK,CAAC,CAAC,OAAC,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,OAAC,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,OAAC,CAAC,QAAQ,EAAE,CAAC,CAAC;SAC1D,QAAQ,EAAE;SACV,OAAO,CAAC,MAAM,CAAC;IAElB;;;OAGG;IACH,iBAAiB,EAAE,+CAA6B,CAAC,QAAQ,EAAE;IAE3D,+CAA+C;IAC/C,4CAA4C;IAC5C,+CAA+C;IAE/C;;;OAGG;IACH,eAAe,EAAE,OAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;IAE3C;;;OAGG;IACH,iBAAiB,EAAE,OAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC;IAE5C;;;OAGG;IACH,oBAAoB,EAAE,OAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC;IAE/C;;;;;OAKG;IACH,mBAAmB,EAAE,OAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;IAE/C;;;OAGG;IACH,kBAAkB,EAAE,OAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;IAE9C;;;;OAIG;IACH,2BAA2B,EAAE,OAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC;IAEtD,+CAA+C;IAC/C,wBAAwB;IACxB,+CAA+C;IAE/C;;;OAGG;IACH,WAAW,EAAE,wCAAgC,CAAC,QAAQ,EAAE;CACzD,CAAC,CAAC","sourcesContent":["// common/types/options/transport.options.ts\n\nimport { z } from 'zod';\nimport { redisOptionsSchema } from './redis.options';\nimport {\n  SessionMode,\n  TransportIdMode,\n  PlatformMappingEntry,\n  PlatformDetectionConfig,\n  platformMappingEntrySchema,\n  platformDetectionConfigSchema,\n} from './session.options';\n\n// Re-export session types for convenience (these are the canonical definitions)\nexport type { SessionMode, TransportIdMode, PlatformMappingEntry, PlatformDetectionConfig };\n\n// ============================================\n// TRANSPORT PERSISTENCE (from auth.transport.recreation)\n// ============================================\n\n/**\n * Transport persistence configuration\n * Enables session persistence to Redis and automatic transport recreation after server restart\n */\nexport const transportPersistenceConfigSchema = z.object({\n  /**\n   * Enable transport persistence to Redis\n   * When enabled, sessions are persisted to Redis and transports can be recreated after restart\n   * @default false\n   */\n  enabled: z.boolean().default(false),\n\n  /**\n   * Redis configuration for session storage\n   * If omitted when enabled=true, uses top-level redis config\n   * Note: Validation for redis presence happens at runtime when persistence is used\n   */\n  redis: redisOptionsSchema.optional(),\n\n  /**\n   * Default TTL for stored session metadata (milliseconds)\n   * @default 3600000 (1 hour)\n   */\n  defaultTtlMs: z.number().int().positive().default(3600000),\n});\n\n// ============================================\n// TRANSPORT OPTIONS (unified config)\n// ============================================\n\n/**\n * Transport options schema\n * Consolidates transport protocol config + session lifecycle config\n */\nexport const transportOptionsSchema = z.object({\n  // ============================================\n  // Session Lifecycle (from session.options.ts)\n  // ============================================\n\n  /**\n   * Defines how the session lifecycle and nested tokens are managed.\n   *\n   * Modes:\n   * - `'stateful'`: Session and nested tokens are stored in a server-side store (e.g., Redis).\n   * - `'stateless'`: All session data (including nested tokens) is embedded within a signed/encrypted JWT.\n   *\n   * @default 'stateful'\n   */\n  sessionMode: z\n    .union([z.literal('stateful'), z.literal('stateless'), z.function()])\n    .optional()\n    .default('stateful'),\n\n  /**\n   * Defines how the Transport ID is generated, verified, and used across sessions.\n   *\n   * Modes:\n   * - `'uuid'`: Generates a random UUID per session.\n   * - `'jwt'`: Uses a signed JWT for stateless sessions, signed with a generated session key.\n   *\n   * @default 'uuid'\n   */\n  transportIdMode: z\n    .union([z.literal('uuid'), z.literal('jwt'), z.function()])\n    .optional()\n    .default('uuid'),\n\n  /**\n   * Configuration for detecting the AI platform from MCP client info.\n   * Allows custom mappings to override or supplement the default keyword-based detection.\n   */\n  platformDetection: platformDetectionConfigSchema.optional(),\n\n  // ============================================\n  // Transport Protocols (from auth.transport)\n  // ============================================\n\n  /**\n   * Enable legacy SSE transport (old HTTP+SSE protocol)\n   * @default false\n   */\n  enableLegacySSE: z.boolean().default(false),\n\n  /**\n   * Enable SSE listener for server-initiated messages (GET /mcp with Accept: text/event-stream)\n   * @default true\n   */\n  enableSseListener: z.boolean().default(true),\n\n  /**\n   * Enable streamable HTTP transport (POST with SSE response)\n   * @default true\n   */\n  enableStreamableHttp: z.boolean().default(true),\n\n  /**\n   * Enable stateless HTTP mode (requests without session ID)\n   * When enabled, allows requests without prior initialize\n   * Uses shared singleton transport for anonymous, per-token singleton for authenticated\n   * @default false\n   */\n  enableStatelessHttp: z.boolean().default(false),\n\n  /**\n   * Enable stateful HTTP transport (JSON-only responses)\n   * @default false\n   */\n  enableStatefulHttp: z.boolean().default(false),\n\n  /**\n   * Require session ID for streamable HTTP (non-stateless mode)\n   * When false, streamable HTTP requests don't require prior initialize\n   * @default true\n   */\n  requireSessionForStreamable: z.boolean().default(true),\n\n  // ============================================\n  // Transport Persistence\n  // ============================================\n\n  /**\n   * Transport persistence configuration\n   * When enabled, sessions are persisted to Redis and transports can be recreated after server restart\n   */\n  persistence: transportPersistenceConfigSchema.optional(),\n});\n\n// ============================================\n// TYPE EXPORTS\n// ============================================\n\n/**\n * Transport options type (with defaults applied)\n */\nexport type TransportOptions = z.infer<typeof transportOptionsSchema>;\n\n/**\n * Transport options input type (for user configuration)\n */\nexport type TransportOptionsInput = z.input<typeof transportOptionsSchema>;\n\n/**\n * Transport persistence configuration type\n */\nexport type TransportPersistenceConfig = z.infer<typeof transportPersistenceConfigSchema>;\n\n/**\n * Transport persistence configuration input type\n */\nexport type TransportPersistenceConfigInput = z.input<typeof transportPersistenceConfigSchema>;\n\n/**\n * Platform detection configuration type\n */\nexport type PlatformDetectionConfigType = z.infer<typeof platformDetectionConfigSchema>;\n"]}

package/src/common/utils/global-config.utils.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Global Configuration Utilities
+ *
+ * Helper functions for plugins to access global configuration from @FrontMcp decorator.
+ */
+import type { FrontMcpConfigType } from '../metadata';
+import type { RedisOptions } from '../types';
+/**
+ * Extract store configuration from global FrontMcp configuration.
+ *
+ * This helper is used by plugins that want to use the global redis/store
+ * configuration instead of requiring explicit configuration.
+ *
+ * @param pluginName - Name of the plugin requesting the config (for error messages)
+ * @param config - The FrontMcp configuration object
+ * @returns The redis/store configuration
+ * @throws GlobalConfigNotFoundError if redis is not configured
+ *
+ * @example
+ * ```typescript
+ * // In plugin dynamicProviders:
+ * static dynamicProviders = (options: MyPluginOptions) => {
+ *   if (options.type === 'global-store') {
+ *     return [{
+ *       provide: MyStoreToken,
+ *       inject: () => [FrontMcpConfig],
+ *       useFactory: (config: FrontMcpConfigType) => {
+ *         const storeConfig = getGlobalStoreConfig('MyPlugin', config);
+ *         return new MyStoreProvider(storeConfig);
+ *       },
+ *     }];
+ *   }
+ * };
+ * ```
+ */
+export declare function getGlobalStoreConfig(pluginName: string, config: FrontMcpConfigType): RedisOptions;

package/src/common/utils/global-config.utils.js

@@ -0,0 +1,44 @@
+"use strict";
+/**
+ * Global Configuration Utilities
+ *
+ * Helper functions for plugins to access global configuration from @FrontMcp decorator.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getGlobalStoreConfig = getGlobalStoreConfig;
+const errors_1 = require("../../errors");
+/**
+ * Extract store configuration from global FrontMcp configuration.
+ *
+ * This helper is used by plugins that want to use the global redis/store
+ * configuration instead of requiring explicit configuration.
+ *
+ * @param pluginName - Name of the plugin requesting the config (for error messages)
+ * @param config - The FrontMcp configuration object
+ * @returns The redis/store configuration
+ * @throws GlobalConfigNotFoundError if redis is not configured
+ *
+ * @example
+ * ```typescript
+ * // In plugin dynamicProviders:
+ * static dynamicProviders = (options: MyPluginOptions) => {
+ *   if (options.type === 'global-store') {
+ *     return [{
+ *       provide: MyStoreToken,
+ *       inject: () => [FrontMcpConfig],
+ *       useFactory: (config: FrontMcpConfigType) => {
+ *         const storeConfig = getGlobalStoreConfig('MyPlugin', config);
+ *         return new MyStoreProvider(storeConfig);
+ *       },
+ *     }];
+ *   }
+ * };
+ * ```
+ */
+function getGlobalStoreConfig(pluginName, config) {
+    if (!config.redis) {
+        throw new errors_1.GlobalConfigNotFoundError(pluginName, 'redis');
+    }
+    return config.redis;
+}
+//# sourceMappingURL=global-config.utils.js.map

package/src/common/utils/global-config.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"global-config.utils.js","sourceRoot":"","sources":["../../../../src/common/utils/global-config.utils.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;AAkCH,oDAKC;AAnCD,yCAAyD;AAEzD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,SAAgB,oBAAoB,CAAC,UAAkB,EAAE,MAA0B;IACjF,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;QAClB,MAAM,IAAI,kCAAyB,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IAC3D,CAAC;IACD,OAAO,MAAM,CAAC,KAAK,CAAC;AACtB,CAAC","sourcesContent":["/**\n * Global Configuration Utilities\n *\n * Helper functions for plugins to access global configuration from @FrontMcp decorator.\n */\n\nimport type { FrontMcpConfigType } from '../metadata';\nimport type { RedisOptions } from '../types';\nimport { GlobalConfigNotFoundError } from '../../errors';\n\n/**\n * Extract store configuration from global FrontMcp configuration.\n *\n * This helper is used by plugins that want to use the global redis/store\n * configuration instead of requiring explicit configuration.\n *\n * @param pluginName - Name of the plugin requesting the config (for error messages)\n * @param config - The FrontMcp configuration object\n * @returns The redis/store configuration\n * @throws GlobalConfigNotFoundError if redis is not configured\n *\n * @example\n * ```typescript\n * // In plugin dynamicProviders:\n * static dynamicProviders = (options: MyPluginOptions) => {\n *   if (options.type === 'global-store') {\n *     return [{\n *       provide: MyStoreToken,\n *       inject: () => [FrontMcpConfig],\n *       useFactory: (config: FrontMcpConfigType) => {\n *         const storeConfig = getGlobalStoreConfig('MyPlugin', config);\n *         return new MyStoreProvider(storeConfig);\n *       },\n *     }];\n *   }\n * };\n * ```\n */\nexport function getGlobalStoreConfig(pluginName: string, config: FrontMcpConfigType): RedisOptions {\n  if (!config.redis) {\n    throw new GlobalConfigNotFoundError(pluginName, 'redis');\n  }\n  return config.redis;\n}\n"]}

package/src/common/utils/index.d.ts

@@ -1,2 +1,3 @@
 export * from './decide-request-intent.utils';
 export * from './path.utils';
+export * from './global-config.utils';

package/src/common/utils/index.js

@@ -3,4 +3,5 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const tslib_1 = require("tslib");
 tslib_1.__exportStar(require("./decide-request-intent.utils"), exports);
 tslib_1.__exportStar(require("./path.utils"), exports);
+tslib_1.__exportStar(require("./global-config.utils"), exports);
 //# sourceMappingURL=index.js.map

package/src/common/utils/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/common/utils/index.ts"],"names":[],"mappings":";;;AAAA,wEAA6C;AAC7C,uDAA4B","sourcesContent":["export * from './decide-request-intent.utils'\nexport * from './path.utils'"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/common/utils/index.ts"],"names":[],"mappings":";;;AAAA,wEAA8C;AAC9C,uDAA6B;AAC7B,gEAAsC","sourcesContent":["export * from './decide-request-intent.utils';\nexport * from './path.utils';\nexport * from './global-config.utils';\n"]}

package/src/completion/flows/complete.flow.d.ts

@@ -4,15 +4,11 @@ declare const inputSchema: z.ZodObject<{
     request: z.ZodObject<{
         method: z.ZodLiteral<"completion/complete">;
         params: z.ZodObject<{
-            task: z.ZodOptional<z.ZodObject<{
-                ttl: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodNull]>>;
-                pollInterval: z.ZodOptional<z.ZodNumber>;
-            }, z.core.$loose>>;
             _meta: z.ZodOptional<z.ZodObject<{
                 progressToken: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
                 "io.modelcontextprotocol/related-task": z.ZodOptional<z.ZodObject<{
                     taskId: z.ZodString;
-                }, z.core.$loose>>;
+                }, z.core.$strip>>;
             }, z.core.$loose>>;
             ref: z.ZodUnion<readonly [z.ZodObject<{
                 type: z.ZodLiteral<"ref/prompt">;
@@ -28,15 +24,16 @@ declare const inputSchema: z.ZodObject<{
             context: z.ZodOptional<z.ZodObject<{
                 arguments: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
             }, z.core.$strip>>;
-        }, z.core.$loose>;
+        }, z.core.$strip>;
     }, z.core.$strip>;
     ctx: z.ZodUnknown;
 }, z.core.$strip>;
 declare const outputSchema: z.ZodObject<{
     _meta: z.ZodOptional<z.ZodObject<{
+        progressToken: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
         "io.modelcontextprotocol/related-task": z.ZodOptional<z.ZodObject<{
             taskId: z.ZodString;
-        }, z.core.$loose>>;
+        }, z.core.$strip>>;
     }, z.core.$loose>>;
     completion: z.ZodObject<{
         values: z.ZodArray<z.ZodString>;
@@ -58,9 +55,10 @@ declare const stateSchema: z.ZodObject<{
     }, z.core.$strip>;
     output: z.ZodObject<{
         _meta: z.ZodOptional<z.ZodObject<{
+            progressToken: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
             "io.modelcontextprotocol/related-task": z.ZodOptional<z.ZodObject<{
                 taskId: z.ZodString;
-            }, z.core.$loose>>;
+            }, z.core.$strip>>;
         }, z.core.$loose>>;
         completion: z.ZodObject<{
             values: z.ZodArray<z.ZodString>;

package/src/context/frontmcp-context-storage.d.ts

@@ -0,0 +1,94 @@
+/**
+ * FrontMcpContextStorage - AsyncLocalStorage wrapper for unified context
+ *
+ * Provides concurrent-safe context propagation using Node.js AsyncLocalStorage.
+ * Access through DI only - never use static imports to access the storage directly.
+ *
+ * @example
+ * ```typescript
+ * // In a flow or middleware
+ * const storage = this.get(FrontMcpContextStorage);
+ * await storage.runFromHeaders(request.headers, {
+ *   sessionId: sessionId,
+ *   scopeId: scope.id,
+ * }, async () => {
+ *   // All code here can access the context via DI
+ *   const ctx = this.get(FRONTMCP_CONTEXT);
+ * });
+ * ```
+ */
+import { FrontMcpContext, FrontMcpContextArgs } from './frontmcp-context';
+import { AuthInfo } from '@modelcontextprotocol/sdk/server/auth/types.js';
+/**
+ * FrontMcpContextStorage provides unified context via AsyncLocalStorage.
+ *
+ * This is a GLOBAL-scoped provider because it manages the storage itself,
+ * not the per-context data. The actual FrontMcpContext is accessed via
+ * the FRONTMCP_CONTEXT token which is CONTEXT-scoped.
+ */
+export declare class FrontMcpContextStorage {
+    /**
+     * Run a callback with a new FrontMcpContext.
+     *
+     * @param args - Arguments to create the context
+     * @param fn - Async function to run with the context
+     * @returns Result of the callback
+     */
+    run<T>(args: FrontMcpContextArgs, fn: () => T | Promise<T>): T | Promise<T>;
+    /**
+     * Run with context extracted from HTTP headers.
+     *
+     * Automatically parses trace context from headers using W3C Trace Context
+     * specification with fallback to x-frontmcp-trace-id.
+     *
+     * @param headers - HTTP headers
+     * @param args - Additional context args (sessionId, scopeId)
+     * @param fn - Async function to run
+     * @returns Result of the callback
+     */
+    runFromHeaders<T>(headers: Record<string, unknown>, args: Omit<FrontMcpContextArgs, 'traceContext' | 'metadata'>, fn: () => T | Promise<T>): T | Promise<T>;
+    /**
+     * Run with an existing FrontMcpContext.
+     *
+     * Useful when you need to propagate an existing context to a new async scope.
+     *
+     * @param context - Existing FrontMcpContext
+     * @param fn - Async function to run
+     * @returns Result of the callback
+     */
+    runWithContext<T>(context: FrontMcpContext, fn: () => T | Promise<T>): T | Promise<T>;
+    /**
+     * Get the current FrontMcpContext.
+     *
+     * @returns Current context or undefined if not in a context scope
+     */
+    getStore(): FrontMcpContext | undefined;
+    /**
+     * Get the current FrontMcpContext, throwing if not available.
+     *
+     * @throws Error if not in a context scope
+     */
+    getStoreOrThrow(): FrontMcpContext;
+    /**
+     * Check if currently running within a context.
+     *
+     * @returns True if a FrontMcpContext is available
+     */
+    hasContext(): boolean;
+    /**
+     * Update the authInfo in the current context.
+     *
+     * This mutates the existing context in place to preserve internal state
+     * (marks, store, sessionMetadata) while updating auth info.
+     *
+     * @param authInfo - Auth info fields to set/update (merged with existing)
+     * @param fn - Function to run after update
+     * @returns Result of the callback
+     */
+    updateAuthInfo<T>(authInfo: Partial<AuthInfo>, fn: () => T | Promise<T>): T | Promise<T>;
+}
+/**
+ * Alias for backward compatibility.
+ * @deprecated Use FrontMcpContextStorage instead
+ */
+export { FrontMcpContextStorage as ContextStorage };