@kognitivedev/vercel-ai-provider 0.2.5 → 0.2.7

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @kognitivedev/vercel-ai-provider
 
+## 0.2.7
+
+### Patch Changes
+
+- release
+
+- Updated dependencies []:
+  - @kognitivedev/prompthub@0.1.5
+  - @kognitivedev/shared@0.2.7
+
+## 0.2.6
+
+### Patch Changes
+
+- release
+
+- Updated dependencies []:
+  - @kognitivedev/prompthub@0.1.4
+  - @kognitivedev/shared@0.2.6
+
 ## 0.2.5
 
 ### Patch Changes

package/README.md

@@ -109,7 +109,6 @@ type CognitiveLayer = CLModelWrapper & {
     resolvePrompt: (slug: string) => Promise<CachedPrompt>;
     logConversation: (payload: LogConversationPayload) => Promise<void>;
     triggerProcessing: (userId: string, projectId: string, sessionId: string) => void;
-    clearPromptCache: () => void;
     clearSessionCache: (sessionKey?: string) => void;
 };
 ```
@@ -503,16 +502,6 @@ cl.triggerProcessing("user-123", "my-project", "session-abc");
 
 ---
 
-### `cl.clearPromptCache()`
-
-Clears all cached prompts, forcing the next `resolvePrompt` call to fetch fresh data from the backend.
-
-```typescript
-cl.clearPromptCache();
-```
-
----
-
 ### `cl.clearSessionCache(sessionKey?)`
 
 Clears cached memory snapshots. Pass a specific session key (`"userId:projectId:sessionId"`) to clear one session, or omit to clear all.

package/dist/__tests__/cognitive-layer-extra.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/cognitive-layer-extra.test.js

@@ -0,0 +1,209 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const aiMocks = vitest_1.vi.hoisted(() => ({
+    wrapLanguageModel: vitest_1.vi.fn(({ model }) => model),
+    streamText: vitest_1.vi.fn(async (options) => ({ options })),
+    generateText: vitest_1.vi.fn(async (options) => ({ options })),
+}));
+const promptHubMocks = vitest_1.vi.hoisted(() => ({
+    resolvePrompt: vitest_1.vi.fn(),
+}));
+vitest_1.vi.mock("ai", () => ({
+    wrapLanguageModel: aiMocks.wrapLanguageModel,
+    streamText: aiMocks.streamText,
+    generateText: aiMocks.generateText,
+}));
+vitest_1.vi.mock("@kognitivedev/prompthub", () => ({
+    createPromptHubClient: vitest_1.vi.fn(() => ({
+        resolvePrompt: promptHubMocks.resolvePrompt,
+    })),
+}));
+const index_1 = require("../index");
+function makeLayer(overrides) {
+    return (0, index_1.createCognitiveLayer)({
+        provider: (modelId) => ({ modelId }),
+        clConfig: Object.assign({ apiKey: "test-api-key", baseUrl: "https://backend.example", projectId: "project-1", processDelayMs: 0, logLevel: "debug" }, overrides),
+    });
+}
+(0, vitest_1.describe)("createCognitiveLayer extras", () => {
+    (0, vitest_1.beforeEach)(() => {
+        aiMocks.wrapLanguageModel.mockClear();
+        aiMocks.streamText.mockClear();
+        aiMocks.generateText.mockClear();
+        promptHubMocks.resolvePrompt.mockReset();
+    });
+    (0, vitest_1.afterEach)(() => {
+        vitest_1.vi.restoreAllMocks();
+    });
+    (0, vitest_1.it)("resolves prompts and renders variables", async () => {
+        promptHubMocks.resolvePrompt.mockResolvedValue({
+            promptId: "prompt-1",
+            slug: "welcome",
+            version: 4,
+            content: "Hello {{name}}",
+            fetchedAt: Date.now(),
+            gatewaySlug: "gateway-a",
+        });
+        const warnSpy = vitest_1.vi.spyOn(console, "warn").mockImplementation(() => { });
+        const logSpy = vitest_1.vi.spyOn(console, "log").mockImplementation(() => { });
+        const cl = makeLayer();
+        const model = cl("mock-model", {
+            userId: "user-1",
+            projectId: "project-1",
+            sessionId: "session-1",
+        });
+        await cl.streamText({
+            model,
+            messages: [{ role: "user", content: "Hi" }],
+            prompt: { slug: "welcome", variables: { name: "Ada" } },
+        });
+        (0, vitest_1.expect)(promptHubMocks.resolvePrompt).toHaveBeenCalledWith({
+            slug: "welcome",
+            userId: "user-1",
+            tag: undefined,
+        });
+        (0, vitest_1.expect)(aiMocks.streamText).toHaveBeenCalledWith(vitest_1.expect.objectContaining({
+            system: "Hello Ada",
+            model: vitest_1.expect.objectContaining({ modelId: "mock-model" }),
+        }));
+        (0, vitest_1.expect)(warnSpy).toHaveBeenCalledWith(vitest_1.expect.stringContaining("Gateway config found but no providerFactory provided"));
+        (0, vitest_1.expect)(logSpy).toHaveBeenCalled();
+        cl.clearSessionCache("user-1:project-1:session-1");
+        cl.clearSessionCache();
+    });
+    (0, vitest_1.it)("uses a gateway model when providerFactory is available", async () => {
+        promptHubMocks.resolvePrompt.mockResolvedValue({
+            promptId: "prompt-2",
+            slug: "gateway",
+            version: 1,
+            content: "Prompt body",
+            fetchedAt: Date.now(),
+            gatewaySlug: "gateway-a",
+        });
+        const providerFactory = vitest_1.vi.fn(() => vitest_1.vi.fn((modelId) => ({ modelId })));
+        const cl = makeLayer({ providerFactory });
+        const model = cl("mock-model", {
+            userId: "user-1",
+            projectId: "project-1",
+            sessionId: "session-1",
+        });
+        await cl.generateText({
+            model,
+            messages: [{ role: "user", content: "Hi" }],
+            prompt: { slug: "gateway" },
+        });
+        (0, vitest_1.expect)(providerFactory).toHaveBeenCalledWith("https://backend.example/api/cognitive/gateway/gateway-a", "test-api-key");
+        (0, vitest_1.expect)(aiMocks.generateText).toHaveBeenCalledWith(vitest_1.expect.objectContaining({
+            model: vitest_1.expect.objectContaining({ modelId: "gateway-model" }),
+            system: "Prompt body",
+        }));
+    });
+    (0, vitest_1.it)("passes prompt tag and stores tag/ab metadata in logging payload", async () => {
+        var _a, _b, _c, _d;
+        const backendResponse = {
+            promptId: "prompt-4",
+            slug: "tagged-welcome",
+            version: 2,
+            content: "Tagged {{name}}",
+            fetchedAt: Date.now(),
+            gatewaySlug: null,
+            tag: "production",
+            abTestId: "ab-test-1",
+            variant: "variant",
+        };
+        promptHubMocks.resolvePrompt.mockResolvedValue(backendResponse);
+        const fetchSpy = vitest_1.vi
+            .spyOn(globalThis, "fetch")
+            .mockResolvedValue(new Response(JSON.stringify({ ok: true }), { status: 201 }));
+        const cl = makeLayer();
+        const model = cl("mock-model", {
+            userId: "user-2",
+            projectId: "project-1",
+            sessionId: "session-2",
+        });
+        await cl.generateText({
+            model,
+            messages: [{ role: "user", content: "Hi {{name}}" }],
+            prompt: { slug: "welcome", tag: "production", variables: { name: "Ada" } },
+        });
+        await Promise.resolve();
+        (0, vitest_1.expect)(promptHubMocks.resolvePrompt).toHaveBeenCalledWith({
+            slug: "welcome",
+            userId: "user-2",
+            tag: "production",
+        });
+        (0, vitest_1.expect)(fetchSpy).toHaveBeenCalledWith("https://backend.example/api/cognitive/log", vitest_1.expect.objectContaining({
+            method: "POST",
+            headers: vitest_1.expect.objectContaining({
+                "Content-Type": "application/json",
+                Authorization: "Bearer test-api-key",
+            }),
+            body: vitest_1.expect.stringContaining('"promptSlug":"tagged-welcome"'),
+        }));
+        const logCall = fetchSpy.mock.calls.find(([url]) => String(url).includes("api/cognitive/log"));
+        (0, vitest_1.expect)(logCall).toBeDefined();
+        const calledWithBody = JSON.parse(logCall[1].body);
+        (0, vitest_1.expect)(calledWithBody.promptSlug).toBe("tagged-welcome");
+        (0, vitest_1.expect)(calledWithBody.promptVersion).toBe(2);
+        (0, vitest_1.expect)(calledWithBody.promptId).toBe("prompt-4");
+        (0, vitest_1.expect)(calledWithBody.tag).toBe("production");
+        (0, vitest_1.expect)(calledWithBody.abTestId).toBe("ab-test-1");
+        (0, vitest_1.expect)(calledWithBody.variant).toBe("variant");
+        (0, vitest_1.expect)((_a = calledWithBody.metadata) === null || _a === void 0 ? void 0 : _a.appId).toBeUndefined();
+        (0, vitest_1.expect)((_b = calledWithBody.metadata) === null || _b === void 0 ? void 0 : _b.promptTag).toBe("production");
+        (0, vitest_1.expect)((_c = calledWithBody.metadata) === null || _c === void 0 ? void 0 : _c.abTestId).toBe("ab-test-1");
+        (0, vitest_1.expect)((_d = calledWithBody.metadata) === null || _d === void 0 ? void 0 : _d.variant).toBe("variant");
+        fetchSpy.mockRestore();
+    });
+    (0, vitest_1.it)("falls back to the original model when gateway model creation fails", async () => {
+        promptHubMocks.resolvePrompt.mockResolvedValue({
+            promptId: "prompt-3",
+            slug: "gateway",
+            version: 1,
+            content: "Prompt body",
+            fetchedAt: Date.now(),
+            gatewaySlug: "gateway-a",
+        });
+        const errorSpy = vitest_1.vi.spyOn(console, "error").mockImplementation(() => { });
+        const cl = makeLayer({
+            providerFactory: () => {
+                throw new Error("gateway failure");
+            },
+        });
+        const model = cl("mock-model", {
+            userId: "user-1",
+            projectId: "project-1",
+            sessionId: "session-1",
+        });
+        await cl.streamText({
+            model,
+            messages: [{ role: "user", content: "Hi" }],
+            prompt: { slug: "gateway" },
+        });
+        (0, vitest_1.expect)(errorSpy).toHaveBeenCalledWith(vitest_1.expect.stringContaining("Failed to create gateway model, falling back to original"), vitest_1.expect.any(Error));
+        (0, vitest_1.expect)(aiMocks.streamText).toHaveBeenCalledWith(vitest_1.expect.objectContaining({
+            model: vitest_1.expect.objectContaining({ modelId: "mock-model" }),
+        }));
+    });
+    (0, vitest_1.it)("falls back cleanly when prompt resolution fails", async () => {
+        promptHubMocks.resolvePrompt.mockRejectedValue(new Error("not found"));
+        const warnSpy = vitest_1.vi.spyOn(console, "warn").mockImplementation(() => { });
+        const cl = makeLayer();
+        const model = cl("mock-model", {
+            userId: "user-1",
+            projectId: "project-1",
+            sessionId: "session-1",
+        });
+        await cl.generateText({
+            model,
+            messages: [{ role: "user", content: "Hi" }],
+            prompt: { slug: "missing" },
+        });
+        (0, vitest_1.expect)(warnSpy).toHaveBeenCalledWith(vitest_1.expect.stringContaining('Failed to resolve prompt "missing", generating without system prompt.'), vitest_1.expect.any(Error));
+        (0, vitest_1.expect)(aiMocks.generateText).toHaveBeenCalledWith(vitest_1.expect.objectContaining({
+            model: vitest_1.expect.objectContaining({ modelId: "mock-model" }),
+        }));
+        (0, vitest_1.expect)(aiMocks.generateText.mock.calls[0][0]).not.toHaveProperty("system");
+    });
+});

package/dist/index.d.ts

@@ -38,6 +38,7 @@ export type CLModelWrapper = (modelId: string, settings?: {
 export interface PromptConfig {
     slug: string;
     variables?: Record<string, string | boolean>;
+    tag?: string;
 }
 export type CLStreamTextOptions = Omit<Parameters<typeof aiStreamText>[0], 'system' | 'prompt'> & {
     prompt: PromptConfig;
@@ -56,6 +57,9 @@ export interface LogConversationPayload {
     promptSlug?: string;
     promptVersion?: number;
     promptId?: string;
+    tag?: string;
+    abTestId?: string;
+    variant?: "control" | "variant";
     traceId?: string;
     parentSpanId?: string;
     requestPreview?: string;
@@ -87,10 +91,12 @@ export interface LogConversationPayload {
 export type CognitiveLayer = CLModelWrapper & {
     streamText: (options: CLStreamTextOptions) => Promise<ReturnType<typeof aiStreamText>>;
     generateText: (options: CLGenerateTextOptions) => ReturnType<typeof aiGenerateText>;
-    resolvePrompt: (slug: string, userId?: string) => Promise<CachedPrompt>;
+    resolvePrompt: (slug: string, userId?: string | {
+        userId?: string;
+        tag?: string;
+    }) => Promise<CachedPrompt>;
     logConversation: (payload: LogConversationPayload) => Promise<void>;
     triggerProcessing: (userId: string, projectId: string, sessionId: string) => void;
-    clearPromptCache: () => void;
     clearSessionCache: (sessionKey?: string) => void;
 };
 export interface CachedPrompt {
@@ -100,6 +106,9 @@ export interface CachedPrompt {
     content: string;
     fetchedAt: number;
     gatewaySlug?: string;
+    tag?: string;
+    abTestId?: string;
+    variant?: "control" | "variant";
 }
 export declare function createCognitiveLayer(config: {
     provider: any;

package/dist/index.js

@@ -214,15 +214,21 @@ function createCognitiveLayer(config) {
         apiKey: clConfig.apiKey,
         logger,
     });
-    const resolvePrompt = async (slug, userId) => {
+    const resolvePrompt = async (slug, userIdOrOptions) => {
         var _a;
+        const userId = typeof userIdOrOptions === "string"
+            ? userIdOrOptions
+            : userIdOrOptions === null || userIdOrOptions === void 0 ? void 0 : userIdOrOptions.userId;
+        const tag = typeof userIdOrOptions === "string"
+            ? undefined
+            : userIdOrOptions === null || userIdOrOptions === void 0 ? void 0 : userIdOrOptions.tag;
         logger.debug("Resolving prompt from backend", {
             slug,
             userId,
             baseUrl,
             apiKeyHint: maskSecret(clConfig.apiKey),
         });
-        const data = await promptClient.resolvePrompt({ slug, userId });
+        const data = await promptClient.resolvePrompt({ slug, userId, tag });
         const entry = {
             promptId: data.promptId,
             slug: data.slug,
@@ -230,6 +236,9 @@ function createCognitiveLayer(config) {
             content: data.content,
             fetchedAt: Date.now(),
             gatewaySlug: data.gatewaySlug,
+            tag: data.tag,
+            abTestId: data.abTestId,
+            variant: data.variant,
         };
         logger.debug("Prompt resolved payload", {
             slug,
@@ -444,10 +453,11 @@ ${userContextBlock || "None"}
                     promptSlug: promptMeta.promptSlug,
                     promptVersion: promptMeta.promptVersion,
                     promptId: promptMeta.promptId,
+                    tag: promptMeta.tag,
+                    abTestId: promptMeta.abTestId,
+                    variant: promptMeta.variant,
                 })), (toolDefs && { tools: toolDefs })), (agentRunId && { agentRunId })), { traceId: (0, crypto_1.randomUUID)(), requestPreview,
-                    responsePreview, state: "completed", startedAt: startedAt.toISOString(), endedAt: endedAt.toISOString(), durationMs: endedAt.getTime() - startedAt.getTime(), metadata: {
-                        appId: clConfig.appId,
-                    }, spans })).then(() => triggerProcessing(userId, projectId, sessionId));
+                    responsePreview, state: "completed", startedAt: startedAt.toISOString(), endedAt: endedAt.toISOString(), durationMs: endedAt.getTime() - startedAt.getTime(), metadata: Object.assign(Object.assign(Object.assign({ appId: clConfig.appId }, ((promptMeta === null || promptMeta === void 0 ? void 0 : promptMeta.tag) && { promptTag: promptMeta.tag })), ((promptMeta === null || promptMeta === void 0 ? void 0 : promptMeta.abTestId) && { abTestId: promptMeta.abTestId })), ((promptMeta === null || promptMeta === void 0 ? void 0 : promptMeta.variant) && { variant: promptMeta.variant })), spans })).then(() => triggerProcessing(userId, projectId, sessionId));
             }
             return result;
         },
@@ -552,11 +562,12 @@ ${userContextBlock || "None"}
                             promptSlug: promptMeta.promptSlug,
                             promptVersion: promptMeta.promptVersion,
                             promptId: promptMeta.promptId,
+                            tag: promptMeta.tag,
+                            abTestId: promptMeta.abTestId,
+                            variant: promptMeta.variant,
                         })), (toolDefs && { tools: toolDefs })), (agentRunId && { agentRunId })), { traceId,
                             requestPreview,
-                            responsePreview, state: "completed", startedAt: startedAt.toISOString(), endedAt: endedAt.toISOString(), durationMs: endedAt.getTime() - startedAt.getTime(), metadata: {
-                                appId: clConfig.appId,
-                            }, spans })).then(() => triggerProcessing(userId, projectId, sessionId))
+                            responsePreview, state: "completed", startedAt: startedAt.toISOString(), endedAt: endedAt.toISOString(), durationMs: endedAt.getTime() - startedAt.getTime(), metadata: Object.assign(Object.assign(Object.assign({ appId: clConfig.appId }, ((promptMeta === null || promptMeta === void 0 ? void 0 : promptMeta.tag) && { promptTag: promptMeta.tag })), ((promptMeta === null || promptMeta === void 0 ? void 0 : promptMeta.abTestId) && { abTestId: promptMeta.abTestId })), ((promptMeta === null || promptMeta === void 0 ? void 0 : promptMeta.variant) && { variant: promptMeta.variant })), spans })).then(() => triggerProcessing(userId, projectId, sessionId))
                             .catch((e) => logger.error("Stream log failed", e));
                     }
                 });
@@ -621,7 +632,10 @@ ${userContextBlock || "None"}
         // Resolve and interpolate prompt (graceful fallback on failure)
         let resolved = null;
         try {
-            resolved = await resolvePrompt(promptConfig.slug, session === null || session === void 0 ? void 0 : session.userId);
+            resolved = await resolvePrompt(promptConfig.slug, {
+                userId: session === null || session === void 0 ? void 0 : session.userId,
+                tag: promptConfig.tag,
+            });
         }
         catch (err) {
             logger.warn(`Failed to resolve prompt "${promptConfig.slug}", streaming without system prompt.`, err);
@@ -638,6 +652,9 @@ ${userContextBlock || "None"}
                     promptSlug: resolved.slug,
                     promptVersion: resolved.version,
                     promptId: resolved.promptId,
+                    tag: resolved.tag,
+                    abTestId: resolved.abTestId,
+                    variant: resolved.variant,
                 });
             }
             logger.info("cl.streamText called", {
@@ -660,7 +677,10 @@ ${userContextBlock || "None"}
         // Resolve and interpolate prompt (graceful fallback on failure)
         let resolved = null;
         try {
-            resolved = await resolvePrompt(promptConfig.slug, session === null || session === void 0 ? void 0 : session.userId);
+            resolved = await resolvePrompt(promptConfig.slug, {
+                userId: session === null || session === void 0 ? void 0 : session.userId,
+                tag: promptConfig.tag,
+            });
         }
         catch (err) {
             logger.warn(`Failed to resolve prompt "${promptConfig.slug}", generating without system prompt.`, err);
@@ -677,6 +697,9 @@ ${userContextBlock || "None"}
                     promptSlug: resolved.slug,
                     promptVersion: resolved.version,
                     promptId: resolved.promptId,
+                    tag: resolved.tag,
+                    abTestId: resolved.abTestId,
+                    variant: resolved.variant,
                 });
             }
             logger.info("cl.generateText called", {
@@ -700,7 +723,6 @@ ${userContextBlock || "None"}
         resolvePrompt,
         logConversation,
         triggerProcessing,
-        clearPromptCache: () => promptClient.clearPromptCache(),
         clearSessionCache: (sessionKey) => {
             if (sessionKey) {
                 sessionSnapshots.delete(sessionKey);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kognitivedev/vercel-ai-provider",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "publishConfig": {
@@ -13,8 +13,8 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@kognitivedev/prompthub": "^0.1.3",
-    "@kognitivedev/shared": "^0.2.5"
+    "@kognitivedev/prompthub": "^0.1.5",
+    "@kognitivedev/shared": "^0.2.7"
   },
   "peerDependencies": {
     "ai": "^5.0.0 || ^6.0.0"

package/src/__tests__/cognitive-layer-extra.test.ts

@@ -0,0 +1,270 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import type { LanguageModel } from "ai";
+
+const aiMocks = vi.hoisted(() => ({
+    wrapLanguageModel: vi.fn(({ model }: { model: unknown }) => model),
+    streamText: vi.fn(async (options: Record<string, unknown>) => ({ options })),
+    generateText: vi.fn(async (options: Record<string, unknown>) => ({ options })),
+}));
+
+const promptHubMocks = vi.hoisted(() => ({
+    resolvePrompt: vi.fn(),
+}));
+
+vi.mock("ai", () => ({
+    wrapLanguageModel: aiMocks.wrapLanguageModel,
+    streamText: aiMocks.streamText,
+    generateText: aiMocks.generateText,
+}));
+
+vi.mock("@kognitivedev/prompthub", () => ({
+    createPromptHubClient: vi.fn(() => ({
+        resolvePrompt: promptHubMocks.resolvePrompt,
+    })),
+}));
+
+import { createCognitiveLayer } from "../index";
+
+function makeLayer(overrides?: {
+    providerFactory?: (baseURL: string, apiKey: string) => (modelId: string) => LanguageModel;
+}) {
+    return createCognitiveLayer({
+        provider: (modelId: string) => ({ modelId }),
+        clConfig: {
+            apiKey: "test-api-key",
+            baseUrl: "https://backend.example",
+            projectId: "project-1",
+            processDelayMs: 0,
+            logLevel: "debug",
+            ...overrides,
+        },
+    });
+}
+
+describe("createCognitiveLayer extras", () => {
+    beforeEach(() => {
+        aiMocks.wrapLanguageModel.mockClear();
+        aiMocks.streamText.mockClear();
+        aiMocks.generateText.mockClear();
+        promptHubMocks.resolvePrompt.mockReset();
+    });
+
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+
+    it("resolves prompts and renders variables", async () => {
+        promptHubMocks.resolvePrompt.mockResolvedValue({
+            promptId: "prompt-1",
+            slug: "welcome",
+            version: 4,
+            content: "Hello {{name}}",
+            fetchedAt: Date.now(),
+            gatewaySlug: "gateway-a",
+        });
+
+        const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+        const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+        const cl = makeLayer();
+        const model = cl("mock-model", {
+            userId: "user-1",
+            projectId: "project-1",
+            sessionId: "session-1",
+        });
+
+        await cl.streamText({
+            model,
+            messages: [{ role: "user", content: "Hi" }],
+            prompt: { slug: "welcome", variables: { name: "Ada" } },
+        } as any);
+
+        expect(promptHubMocks.resolvePrompt).toHaveBeenCalledWith({
+            slug: "welcome",
+            userId: "user-1",
+            tag: undefined,
+        });
+        expect(aiMocks.streamText).toHaveBeenCalledWith(
+            expect.objectContaining({
+                system: "Hello Ada",
+                model: expect.objectContaining({ modelId: "mock-model" }),
+            })
+        );
+        expect(warnSpy).toHaveBeenCalledWith(
+            expect.stringContaining("Gateway config found but no providerFactory provided")
+        );
+        expect(logSpy).toHaveBeenCalled();
+        cl.clearSessionCache("user-1:project-1:session-1");
+        cl.clearSessionCache();
+    });
+
+    it("uses a gateway model when providerFactory is available", async () => {
+        promptHubMocks.resolvePrompt.mockResolvedValue({
+            promptId: "prompt-2",
+            slug: "gateway",
+            version: 1,
+            content: "Prompt body",
+            fetchedAt: Date.now(),
+            gatewaySlug: "gateway-a",
+        });
+
+        const providerFactory = vi.fn(() => vi.fn((modelId: string) => ({ modelId } as unknown as LanguageModel)));
+        const cl = makeLayer({ providerFactory });
+        const model = cl("mock-model", {
+            userId: "user-1",
+            projectId: "project-1",
+            sessionId: "session-1",
+        });
+
+        await cl.generateText({
+            model,
+            messages: [{ role: "user", content: "Hi" }],
+            prompt: { slug: "gateway" },
+        } as any);
+
+        expect(providerFactory).toHaveBeenCalledWith(
+            "https://backend.example/api/cognitive/gateway/gateway-a",
+            "test-api-key"
+        );
+        expect(aiMocks.generateText).toHaveBeenCalledWith(
+            expect.objectContaining({
+                model: expect.objectContaining({ modelId: "gateway-model" }),
+                system: "Prompt body",
+            })
+        );
+    });
+
+    it("passes prompt tag and stores tag/ab metadata in logging payload", async () => {
+        const backendResponse = {
+            promptId: "prompt-4",
+            slug: "tagged-welcome",
+            version: 2,
+            content: "Tagged {{name}}",
+            fetchedAt: Date.now(),
+            gatewaySlug: null,
+            tag: "production",
+            abTestId: "ab-test-1",
+            variant: "variant" as const,
+        };
+        promptHubMocks.resolvePrompt.mockResolvedValue(backendResponse);
+
+        const fetchSpy = vi
+            .spyOn(globalThis, "fetch")
+            .mockResolvedValue(new Response(JSON.stringify({ ok: true }), { status: 201 }));
+
+        const cl = makeLayer();
+        const model = cl("mock-model", {
+            userId: "user-2",
+            projectId: "project-1",
+            sessionId: "session-2",
+        });
+
+        await cl.generateText({
+            model,
+            messages: [{ role: "user", content: "Hi {{name}}" }],
+            prompt: { slug: "welcome", tag: "production", variables: { name: "Ada" } },
+        } as any);
+
+        await Promise.resolve();
+        expect(promptHubMocks.resolvePrompt).toHaveBeenCalledWith({
+            slug: "welcome",
+            userId: "user-2",
+            tag: "production",
+        });
+        expect(fetchSpy).toHaveBeenCalledWith(
+            "https://backend.example/api/cognitive/log",
+            expect.objectContaining({
+                method: "POST",
+                headers: expect.objectContaining({
+                    "Content-Type": "application/json",
+                    Authorization: "Bearer test-api-key",
+                }),
+                body: expect.stringContaining('"promptSlug":"tagged-welcome"'),
+            })
+        );
+
+        const logCall = fetchSpy.mock.calls.find(
+            ([url]) => String(url).includes("api/cognitive/log"),
+        );
+        expect(logCall).toBeDefined();
+        const calledWithBody = JSON.parse(logCall![1]!.body as string);
+        expect(calledWithBody.promptSlug).toBe("tagged-welcome");
+        expect(calledWithBody.promptVersion).toBe(2);
+        expect(calledWithBody.promptId).toBe("prompt-4");
+        expect(calledWithBody.tag).toBe("production");
+        expect(calledWithBody.abTestId).toBe("ab-test-1");
+        expect(calledWithBody.variant).toBe("variant");
+        expect(calledWithBody.metadata?.appId).toBeUndefined();
+        expect(calledWithBody.metadata?.promptTag).toBe("production");
+        expect(calledWithBody.metadata?.abTestId).toBe("ab-test-1");
+        expect(calledWithBody.metadata?.variant).toBe("variant");
+
+        fetchSpy.mockRestore();
+    });
+
+    it("falls back to the original model when gateway model creation fails", async () => {
+        promptHubMocks.resolvePrompt.mockResolvedValue({
+            promptId: "prompt-3",
+            slug: "gateway",
+            version: 1,
+            content: "Prompt body",
+            fetchedAt: Date.now(),
+            gatewaySlug: "gateway-a",
+        });
+
+        const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+        const cl = makeLayer({
+            providerFactory: () => {
+                throw new Error("gateway failure");
+            },
+        });
+        const model = cl("mock-model", {
+            userId: "user-1",
+            projectId: "project-1",
+            sessionId: "session-1",
+        });
+
+        await cl.streamText({
+            model,
+            messages: [{ role: "user", content: "Hi" }],
+            prompt: { slug: "gateway" },
+        } as any);
+
+        expect(errorSpy).toHaveBeenCalledWith(
+            expect.stringContaining("Failed to create gateway model, falling back to original"),
+            expect.any(Error)
+        );
+        expect(aiMocks.streamText).toHaveBeenCalledWith(
+            expect.objectContaining({
+                model: expect.objectContaining({ modelId: "mock-model" }),
+            })
+        );
+    });
+
+    it("falls back cleanly when prompt resolution fails", async () => {
+        promptHubMocks.resolvePrompt.mockRejectedValue(new Error("not found"));
+        const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+        const cl = makeLayer();
+        const model = cl("mock-model", {
+            userId: "user-1",
+            projectId: "project-1",
+            sessionId: "session-1",
+        });
+
+        await cl.generateText({
+            model,
+            messages: [{ role: "user", content: "Hi" }],
+            prompt: { slug: "missing" },
+        } as any);
+
+        expect(warnSpy).toHaveBeenCalledWith(
+            expect.stringContaining('Failed to resolve prompt "missing", generating without system prompt.'),
+            expect.any(Error)
+        );
+        expect(aiMocks.generateText).toHaveBeenCalledWith(
+            expect.objectContaining({
+                model: expect.objectContaining({ modelId: "mock-model" }),
+            })
+        );
+        expect(aiMocks.generateText.mock.calls[0][0]).not.toHaveProperty("system");
+    });
+});

package/src/index.ts

@@ -105,6 +105,7 @@ export type CLModelWrapper = (
 export interface PromptConfig {
     slug: string;
     variables?: Record<string, string | boolean>;
+    tag?: string;
 }
 
 export type CLStreamTextOptions = Omit<Parameters<typeof aiStreamText>[0], 'system' | 'prompt'> & {
@@ -126,6 +127,9 @@ export interface LogConversationPayload {
     promptSlug?: string;
     promptVersion?: number;
     promptId?: string;
+    tag?: string;
+    abTestId?: string;
+    variant?: "control" | "variant";
     traceId?: string;
     parentSpanId?: string;
     requestPreview?: string;
@@ -154,10 +158,12 @@ export interface LogConversationPayload {
 export type CognitiveLayer = CLModelWrapper & {
     streamText: (options: CLStreamTextOptions) => Promise<ReturnType<typeof aiStreamText>>;
     generateText: (options: CLGenerateTextOptions) => ReturnType<typeof aiGenerateText>;
-    resolvePrompt: (slug: string, userId?: string) => Promise<CachedPrompt>;
+    resolvePrompt: (
+        slug: string,
+        userId?: string | { userId?: string; tag?: string }
+    ) => Promise<CachedPrompt>;
     logConversation: (payload: LogConversationPayload) => Promise<void>;
     triggerProcessing: (userId: string, projectId: string, sessionId: string) => void;
-    clearPromptCache: () => void;
     clearSessionCache: (sessionKey?: string) => void;
 };
 
@@ -170,6 +176,9 @@ export interface CachedPrompt {
     content: string;
     fetchedAt: number;
     gatewaySlug?: string;
+    tag?: string;
+    abTestId?: string;
+    variant?: "control" | "variant";
 }
 
 function getContentText(content: any): string {
@@ -309,7 +318,7 @@ const MEMORY_TAG_REGEX = /<MemoryContext>/i;
 const SESSION_KEY = Symbol.for("cl:session");
 
 // Session key → prompt metadata (populated by cl.streamText/cl.generateText, read by middleware)
-const sessionPromptMetadata = new Map<string, { promptSlug: string; promptVersion: number; promptId: string }>();
+const sessionPromptMetadata = new Map<string, { promptSlug: string; promptVersion: number; promptId: string; tag?: string; abTestId?: string; variant?: "control" | "variant" }>();
 
 /**
  * Check if any system message already contains a <MemoryContext> block.
@@ -352,7 +361,13 @@ export function createCognitiveLayer(config: {
         logger,
     });
 
-    const resolvePrompt = async (slug: string, userId?: string): Promise<CachedPrompt> => {
+    const resolvePrompt = async (slug: string, userIdOrOptions?: string | { userId?: string; tag?: string }): Promise<CachedPrompt> => {
+        const userId = typeof userIdOrOptions === "string"
+            ? userIdOrOptions
+            : userIdOrOptions?.userId;
+        const tag = typeof userIdOrOptions === "string"
+            ? undefined
+            : userIdOrOptions?.tag;
         logger.debug("Resolving prompt from backend", {
             slug,
             userId,
@@ -360,7 +375,7 @@ export function createCognitiveLayer(config: {
             apiKeyHint: maskSecret(clConfig.apiKey),
         });
 
-        const data = await promptClient.resolvePrompt({ slug, userId });
+        const data = await promptClient.resolvePrompt({ slug, userId, tag });
         const entry: CachedPrompt = {
             promptId: data.promptId,
             slug: data.slug,
@@ -368,6 +383,9 @@ export function createCognitiveLayer(config: {
             content: data.content,
             fetchedAt: Date.now(),
             gatewaySlug: data.gatewaySlug,
+            tag: data.tag,
+            abTestId: data.abTestId,
+            variant: data.variant,
         };
         logger.debug("Prompt resolved payload", {
             slug,
@@ -611,6 +629,9 @@ ${userContextBlock || "None"}
                         promptSlug: promptMeta.promptSlug,
                         promptVersion: promptMeta.promptVersion,
                         promptId: promptMeta.promptId,
+                        tag: promptMeta.tag,
+                        abTestId: promptMeta.abTestId,
+                        variant: promptMeta.variant,
                     }),
                     ...(toolDefs && { tools: toolDefs }),
                     ...(agentRunId && { agentRunId }),
@@ -623,6 +644,9 @@ ${userContextBlock || "None"}
                     durationMs: endedAt.getTime() - startedAt.getTime(),
                     metadata: {
                         appId: clConfig.appId,
+                                ...(promptMeta?.tag && { promptTag: promptMeta.tag }),
+                                ...(promptMeta?.abTestId && { abTestId: promptMeta.abTestId }),
+                                ...(promptMeta?.variant && { variant: promptMeta.variant }),
                     },
                     spans,
                 }).then(() => triggerProcessing(userId, projectId, sessionId));
@@ -742,6 +766,9 @@ ${userContextBlock || "None"}
                                 promptSlug: promptMeta.promptSlug,
                                 promptVersion: promptMeta.promptVersion,
                                 promptId: promptMeta.promptId,
+                                tag: promptMeta.tag,
+                                abTestId: promptMeta.abTestId,
+                                variant: promptMeta.variant,
                             }),
                             ...(toolDefs && { tools: toolDefs }),
                             ...(agentRunId && { agentRunId }),
@@ -754,6 +781,9 @@ ${userContextBlock || "None"}
                             durationMs: endedAt.getTime() - startedAt.getTime(),
                             metadata: {
                                 appId: clConfig.appId,
+                                ...(promptMeta?.tag && { promptTag: promptMeta.tag }),
+                                ...(promptMeta?.abTestId && { abTestId: promptMeta.abTestId }),
+                                ...(promptMeta?.variant && { variant: promptMeta.variant }),
                             },
                             spans,
                         }).then(() => triggerProcessing(userId, projectId, sessionId))
@@ -839,7 +869,10 @@ ${userContextBlock || "None"}
         // Resolve and interpolate prompt (graceful fallback on failure)
         let resolved: CachedPrompt | null = null;
         try {
-            resolved = await resolvePrompt(promptConfig.slug, session?.userId);
+            resolved = await resolvePrompt(promptConfig.slug, {
+                userId: session?.userId,
+                tag: promptConfig.tag,
+            });
         } catch (err) {
             logger.warn(`Failed to resolve prompt "${promptConfig.slug}", streaming without system prompt.`, err);
         }
@@ -857,6 +890,9 @@ ${userContextBlock || "None"}
                     promptSlug: resolved.slug,
                     promptVersion: resolved.version,
                     promptId: resolved.promptId,
+                    tag: resolved.tag,
+                    abTestId: resolved.abTestId,
+                    variant: resolved.variant,
                 });
             }
 
@@ -883,7 +919,10 @@ ${userContextBlock || "None"}
         // Resolve and interpolate prompt (graceful fallback on failure)
         let resolved: CachedPrompt | null = null;
         try {
-            resolved = await resolvePrompt(promptConfig.slug, session?.userId);
+            resolved = await resolvePrompt(promptConfig.slug, {
+                userId: session?.userId,
+                tag: promptConfig.tag,
+            });
         } catch (err) {
             logger.warn(`Failed to resolve prompt "${promptConfig.slug}", generating without system prompt.`, err);
         }
@@ -901,6 +940,9 @@ ${userContextBlock || "None"}
                     promptSlug: resolved.slug,
                     promptVersion: resolved.version,
                     promptId: resolved.promptId,
+                    tag: resolved.tag,
+                    abTestId: resolved.abTestId,
+                    variant: resolved.variant,
                 });
             }
 
@@ -926,7 +968,6 @@ ${userContextBlock || "None"}
         resolvePrompt,
         logConversation,
         triggerProcessing,
-        clearPromptCache: () => promptClient.clearPromptCache(),
         clearSessionCache: (sessionKey?: string) => {
             if (sessionKey) {
                 sessionSnapshots.delete(sessionKey);