@kognitivedev/vercel-ai-provider 0.1.5 → 0.1.7

package/src/index.ts

@@ -1,5 +1,9 @@
-import { wrapLanguageModel } from "ai";
-import { LanguageModelV2 } from "@ai-sdk/provider";
+import {
+    wrapLanguageModel,
+    streamText as aiStreamText,
+    generateText as aiGenerateText,
+    type LanguageModel,
+} from "ai";
 
 /**
  * Log levels for controlling verbosity of CognitiveLayer logging.
@@ -11,6 +15,12 @@ import { LanguageModelV2 } from "@ai-sdk/provider";
  */
 export type LogLevel = 'none' | 'error' | 'warn' | 'info' | 'debug';
 
+function isValidId(value: string | undefined | null): value is string {
+    if (value == null || typeof value !== "string") return false;
+    const trimmed = value.trim();
+    return trimmed !== "" && trimmed !== "null" && trimmed !== "undefined";
+}
+
 const LOG_LEVEL_PRIORITY: Record<LogLevel, number> = {
     none: 0,
     error: 1,
@@ -50,10 +60,10 @@ function createLogger(logLevel: LogLevel) {
 }
 
 export interface CognitiveLayerConfig {
-    appId: string;
-    defaultAgentId?: string;
+    apiKey: string;
+    appId?: string;
+    projectId?: string;
     baseUrl?: string;
-    apiKey?: string;
     /**
      * Delay in milliseconds before triggering memory processing after a response.
      * Set to 0 to disable automatic processing.
@@ -62,21 +72,77 @@ export interface CognitiveLayerConfig {
     processDelayMs?: number;
     /**
      * Log level for controlling verbosity of CognitiveLayer logging.
-     * - 'none': No logging
-     * - 'error': Only errors
-     * - 'warn': Errors and warnings  
-     * - 'info': Errors, warnings, and info messages
-     * - 'debug': All messages including detailed snapshot data
      * Default: 'info'
      */
     logLevel?: LogLevel;
+    /**
+     * Factory for creating a provider that routes through a gateway URL.
+     */
+    providerFactory?: (baseURL: string, apiKey: string) => (modelId: string) => LanguageModel;
 }
 
 export type CLModelWrapper = (
     modelId: string,
-    settings?: { userId?: string; agentId?: string; sessionId?: string },
+    settings?: { userId?: string; projectId?: string; sessionId?: string },
     providerOptions?: Record<string, unknown>
-) => LanguageModelV2;
+) => LanguageModel;
+
+export interface PromptConfig {
+    slug: string;
+    variables?: Record<string, string>;
+}
+
+export type CLStreamTextOptions = Omit<Parameters<typeof aiStreamText>[0], 'system' | 'prompt'> & {
+    prompt: PromptConfig;
+};
+
+export type CLGenerateTextOptions = Omit<Parameters<typeof aiGenerateText>[0], 'system' | 'prompt'> & {
+    prompt: PromptConfig;
+};
+
+export interface LogConversationPayload {
+    userId: string;
+    projectId: string;
+    sessionId: string;
+    messages: any[];
+    memorySystemPrompt?: string;
+    modelId?: string;
+    usage?: Record<string, unknown>;
+    promptSlug?: string;
+    promptVersion?: number;
+    promptId?: string;
+}
+
+export type CognitiveLayer = CLModelWrapper & {
+    streamText: (options: CLStreamTextOptions) => Promise<ReturnType<typeof aiStreamText>>;
+    generateText: (options: CLGenerateTextOptions) => ReturnType<typeof aiGenerateText>;
+    resolvePrompt: (slug: string) => Promise<CachedPrompt>;
+    logConversation: (payload: LogConversationPayload) => Promise<void>;
+    triggerProcessing: (userId: string, projectId: string, sessionId: string) => void;
+    clearPromptCache: () => void;
+    clearSessionCache: (sessionKey?: string) => void;
+};
+
+// ─── Prompt Cache ────────────────────────────────────────────────────
+
+export interface CachedPrompt {
+    promptId: string;
+    slug: string;
+    version: number;
+    content: string;
+    fetchedAt: number;
+    gatewaySlug?: string;
+}
+
+const PROMPT_CACHE_TTL_MS = 60_000; // 1 minute
+
+/**
+ * Interpolate {{variable}} placeholders in a template string.
+ * Unmatched variables are left as-is.
+ */
+function interpolateTemplate(content: string, variables: Record<string, string>): string {
+    return content.replace(/\{\{(\w+)\}\}/g, (_, key) => variables[key] ?? `{{${key}}}`);
+}
 
 // Session-scoped snapshot cache: sessionKey → formatted memory block
 const sessionSnapshots = new Map<string, string>();
@@ -84,6 +150,12 @@ const sessionSnapshots = new Map<string, string>();
 // Regex to detect if memory has already been injected
 const MEMORY_TAG_REGEX = /<MemoryContext>/i;
 
+// Symbol-keyed property to track session settings on model objects
+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 }>();
+
 /**
  * Check if any system message already contains a <MemoryContext> block.
  */
@@ -105,7 +177,7 @@ function hasExistingMemoryInjection(messages: any[]): boolean {
 export function createCognitiveLayer(config: {
     provider: any;
     clConfig: CognitiveLayerConfig;
-}): CLModelWrapper {
+}): CognitiveLayer {
     const { provider, clConfig } = config;
     const baseUrl = clConfig.baseUrl || "http://localhost:3001";
     // Default to 500ms delay to allow DB writes to settle
@@ -114,18 +186,48 @@ export function createCognitiveLayer(config: {
     const logLevel = clConfig.logLevel || 'info';
     const logger = createLogger(logLevel);
 
-    const logConversation = async (payload: {
-        userId: string;
-        agentId: string;
-        sessionId: string;
-        messages: any[];
-        memorySystemPrompt?: string;
-        modelId?: string;
-    }) => {
+    const authHeaders = {
+        "Content-Type": "application/json",
+        "Authorization": `Bearer ${clConfig.apiKey}`,
+    };
+
+    // Prompt cache: slug → CachedPrompt
+    const promptCache = new Map<string, CachedPrompt>();
+
+    const resolvePrompt = async (slug: string): Promise<CachedPrompt> => {
+        const cached = promptCache.get(slug);
+        if (cached && Date.now() - cached.fetchedAt < PROMPT_CACHE_TTL_MS) {
+            logger.debug("Using cached prompt", { slug, version: cached.version });
+            return cached;
+        }
+
+        const res = await fetch(`${baseUrl}/api/cognitive/prompt?slug=${encodeURIComponent(slug)}`, {
+            headers: { "Authorization": `Bearer ${clConfig.apiKey}` },
+        });
+        if (!res.ok) {
+            const body = await res.text();
+            throw new Error(`Failed to resolve prompt "${slug}": ${res.status} ${body}`);
+        }
+
+        const data = await res.json();
+        const entry: CachedPrompt = {
+            promptId: data.promptId,
+            slug: data.slug,
+            version: data.version,
+            content: data.content,
+            fetchedAt: Date.now(),
+            gatewaySlug: data.gatewaySlug,
+        };
+        promptCache.set(slug, entry);
+        logger.info("Prompt resolved", { slug, version: entry.version });
+        return entry;
+    };
+
+    const logConversation = async (payload: LogConversationPayload) => {
         try {
             await fetch(`${baseUrl}/api/cognitive/log`, {
                 method: "POST",
-                headers: { "Content-Type": "application/json" },
+                headers: authHeaders,
                 body: JSON.stringify({
                     ...payload,
                     type: "conversation",
@@ -137,12 +239,12 @@ export function createCognitiveLayer(config: {
         }
     };
 
-    const triggerProcessing = (userId: string, agentId: string, sessionId: string) => {
+    const triggerProcessing = (userId: string, projectId: string, sessionId: string) => {
         const run = () => {
             fetch(`${baseUrl}/api/cognitive/process`, {
                 method: "POST",
-                headers: { "Content-Type": "application/json" },
-                body: JSON.stringify({ userId, agentId, sessionId }),
+                headers: authHeaders,
+                body: JSON.stringify({ userId, sessionId }),
             }).catch(e => logger.error("Process trigger failed", e));
         };
 
@@ -157,185 +259,358 @@ export function createCognitiveLayer(config: {
         params: any,
         incomingMessages: any[],
         memoryPrompt: string
-    ): { nextParams: any; messages: any[]; mode: "overwrite-param" | "overwrite-first-system" | "prepend-system" } => {
+    ): { nextParams: any; messages: any[]; mode: "overwrite-first-system" | "prepend-system" } => {
         const nextParams = { ...params };
 
-        // 1) If caller provided a top-level system prompt, overwrite it.
-        if (nextParams.system) {
-            nextParams.system = memoryPrompt;
-            return { nextParams, messages: incomingMessages, mode: "overwrite-param" };
-        }
-
-        // 2) If first message is system, replace its content.
+        // 1) If first message is system, append memory to its content (without mutating original).
         if (incomingMessages.length > 0 && incomingMessages[0]?.role === "system") {
-            const updated = [...incomingMessages];
-            let systemMessage = updated[0];
-            if(typeof systemMessage.content === "string") systemMessage.content = systemMessage + "\n\n" + memoryPrompt;
-            updated[0] = { ...updated[0], ...systemMessage };
+            const original = incomingMessages[0];
+            const updatedContent =
+                typeof original.content === "string"
+                    ? original.content + "\n\n" + memoryPrompt
+                    : memoryPrompt;
+            const updated = [{ ...original, content: updatedContent }, ...incomingMessages.slice(1)];
             return { nextParams, messages: updated, mode: "overwrite-first-system" };
         }
 
-        // 3) Otherwise prepend a system message.
+        // 2) Otherwise prepend a system message.
         const updated = [{ role: "system", content: memoryPrompt }, ...incomingMessages];
         return { nextParams, messages: updated, mode: "prepend-system" };
     };
 
-    return (
-        modelId: string,
-        settings?: { userId?: string; agentId?: string; sessionId?: string },
-        providerOptions?: Record<string, unknown>
-    ) => {
-        // Pass provider options through to the underlying provider
-        const model = (
-            providerOptions
-                ? provider(modelId, providerOptions)
-                : provider(modelId)
-        ) as LanguageModelV2;
-        const userId = settings?.userId;
-        const agentId = settings?.agentId || clConfig.defaultAgentId || "default";
-        const sessionId = settings?.sessionId;
-        const sessionMissing = !!userId && !sessionId;
-
-        if (sessionMissing) {
-            logger.warn("sessionId is required to log and process memories; skipping logging until provided.");
-        }
+    const buildMiddleware = (userId: string | undefined, projectId: string, sessionId: string | undefined, modelId: string) => ({
+        specificationVersion: 'v3' as const,
+        async transformParams({ params }: { params: any }) {
+            if (!isValidId(userId)) return params;
 
-        return wrapLanguageModel({
-            model,
-            middleware: {
-                async transformParams({ params }) {
-                    if (!userId) return params;
+            const incomingMessages = Array.isArray((params as any).prompt)
+                ? (params as any).prompt
+                : [];
 
-                    const incomingMessages = Array.isArray((params as any).prompt)
-                        ? (params as any).prompt
-                        : [];
+            // 1) Check if memory is already injected in messages
+            if (hasExistingMemoryInjection(incomingMessages)) {
+                logger.debug("Memory already injected, skipping");
+                return params;
+            }
 
-                    // 1) Check if memory is already injected in messages
-                    if (hasExistingMemoryInjection(incomingMessages)) {
-                        logger.debug("Memory already injected, skipping");
-                        return params;
-                    }
+            // 2) Check session cache
+            const sessionKey = `${userId}:${projectId}:${sessionId || "default"}`;
+            let systemPromptToAdd = sessionSnapshots.get(sessionKey);
 
-                    // 2) Check session cache
-                    const sessionKey = `${userId}:${agentId}:${sessionId || "default"}`;
-                    let systemPromptToAdd = sessionSnapshots.get(sessionKey);
-
-                    // 3) Fetch snapshot only if not cached
-                    if (systemPromptToAdd === undefined) {
-                        try {
-                            const url = `${baseUrl}/api/cognitive/snapshot?userId=${userId}&agentId=${agentId}&appId=${clConfig.appId}`;
-                            const res = await fetch(url);
-                            if (res.ok) {
-                                const data = await res.json();
-                                const systemBlock = data.systemBlock || "";
-                                const userContextBlock = data.userContextBlock || "";
-                                systemPromptToAdd =
-                                    systemBlock !== "" || userContextBlock !== ""
-                                        ? `
+            // 3) Fetch snapshot only if not cached
+            if (systemPromptToAdd === undefined) {
+                try {
+                    const url = `${baseUrl}/api/cognitive/snapshot?userId=${userId}`;
+                    const res = await fetch(url, {
+                        headers: { "Authorization": `Bearer ${clConfig.apiKey}` },
+                    });
+                    if (res.ok) {
+                        const data = await res.json();
+                        const systemBlock = data.systemBlock || "";
+                        const userContextBlock = data.userContextBlock || "";
+                        systemPromptToAdd =
+                            systemBlock !== "" || userContextBlock !== ""
+                                ? `
 <MemoryContext>
 Use the following memory to stay consistent. Prefer UserContext facts for answers; AgentHeuristics guide style, safety, and priorities.
 ${systemBlock || "None"}
 ${userContextBlock || "None"}
 </MemoryContext>
-                                `.trim()
-                                        : "";
-
-                                // Cache the snapshot for this session
-                                sessionSnapshots.set(sessionKey, systemPromptToAdd);
-
-                                logger.info("Snapshot fetched and cached", {
-                                    userId,
-                                    agentId,
-                                    sessionId,
-                                    sessionKey,
-                                    systemLen: systemBlock.length,
-                                    userLen: userContextBlock.length,
-                                });
-                                // At debug level, log the full snapshot data
-                                logger.debug("Full snapshot data", {
-                                    systemBlock,
-                                    userContextBlock,
-                                    rawData: data,
-                                });
-                            } else {
-                                logger.warn("Snapshot fetch failed", { status: res.status });
-                                systemPromptToAdd = "";
-                                sessionSnapshots.set(sessionKey, systemPromptToAdd);
-                            }
-                        } catch (e) {
-                            logger.warn("Failed to fetch snapshot", e);
-                            systemPromptToAdd = "";
-                            sessionSnapshots.set(sessionKey, systemPromptToAdd);
-                        }
+                            `.trim()
+                                : "";
+
+                        // Cache the snapshot for this session
+                        sessionSnapshots.set(sessionKey, systemPromptToAdd);
+
+                        logger.info("Snapshot fetched and cached", {
+                            userId,
+                            projectId,
+                            sessionId,
+                            sessionKey,
+                            systemLen: systemBlock.length,
+                            userLen: userContextBlock.length,
+                        });
+                        // At debug level, log the full snapshot data
+                        logger.debug("Full snapshot data", {
+                            systemBlock,
+                            userContextBlock,
+                            rawData: data,
+                        });
                     } else {
-                        logger.debug("Using cached snapshot for session", { sessionKey });
+                        logger.warn("Snapshot fetch failed", { status: res.status });
+                        systemPromptToAdd = "";
+                        sessionSnapshots.set(sessionKey, systemPromptToAdd);
                     }
+                } catch (e) {
+                    logger.warn("Failed to fetch snapshot", e);
+                    systemPromptToAdd = "";
+                    sessionSnapshots.set(sessionKey, systemPromptToAdd);
+                }
+            } else {
+                logger.debug("Using cached snapshot for session", { sessionKey });
+            }
 
-                    if (!systemPromptToAdd) {
-                        return { ...params, messages: incomingMessages };
-                    }
+            if (!systemPromptToAdd) {
+                return params;
+            }
 
-                    const { nextParams, messages: messagesWithMemory } = withMemorySystemPrompt(
-                        params,
-                        incomingMessages,
-                        systemPromptToAdd
-                    );
+            const { nextParams, messages: messagesWithMemory } = withMemorySystemPrompt(
+                params,
+                incomingMessages,
+                systemPromptToAdd
+            );
 
-                    logger.info("Injecting memory system prompt", {
-                        sessionKey,
-                        promptLength: systemPromptToAdd.length,
-                    });
-                    logger.debug("Injected prompt content", { systemPromptToAdd });
+            logger.info("Injecting memory system prompt", {
+                sessionKey,
+                promptLength: systemPromptToAdd.length,
+            });
+            logger.debug("Injected prompt content", { systemPromptToAdd });
 
-                    return { ...nextParams, prompt: messagesWithMemory };
-                },
+            return { ...nextParams, prompt: messagesWithMemory };
+        },
 
-                async wrapGenerate({ doGenerate, params }) {
-                    const result = await doGenerate();
+        async wrapGenerate({ doGenerate, params }: { doGenerate: any; params: any }) {
+            let result;
+            try {
+                result = await doGenerate();
+            } catch (err) {
+                logger.error("doGenerate failed", err);
+                logger.error("doGenerate params.prompt", JSON.stringify((params as any).prompt?.map((m: any) => ({ role: m.role, contentType: typeof m.content, contentLength: Array.isArray(m.content) ? m.content.length : undefined })), null, 2));
+                throw err;
+            }
 
-                    if (userId && sessionId) {
-                        const messagesInput = (params as any).messages || (params as any).prompt || [];
-                        const resultMessages = (result as any)?.response?.messages;
-                        const assistantMessage = (result as any)?.text
-                            ? [{ role: "assistant", content: [{ type: "text", text: (result as any).text }] }]
-                            : [];
-                        const finalMessages = Array.isArray(resultMessages) && resultMessages.length > 0
-                            ? resultMessages
-                            : [...messagesInput, ...assistantMessage];
+            if (isValidId(userId) && isValidId(sessionId)) {
+                const sessionKey = `${userId}:${projectId}:${sessionId}`;
+                const promptMeta = sessionPromptMetadata.get(sessionKey);
+
+                const messagesInput = (params as any).messages || (params as any).prompt || [];
+                const resultMessages = (result as any)?.response?.messages;
+                const assistantMessage = (result as any)?.text
+                    ? [{ role: "assistant", content: [{ type: "text", text: (result as any).text }] }]
+                    : [];
+                const finalMessages = Array.isArray(resultMessages) && resultMessages.length > 0
+                    ? resultMessages
+                    : [...messagesInput, ...assistantMessage];
+
+                logConversation({
+                    userId,
+                    projectId,
+                    sessionId,
+                    messages: finalMessages,
+                    modelId,
+                    usage: result.usage,
+                    ...(promptMeta && {
+                        promptSlug: promptMeta.promptSlug,
+                        promptVersion: promptMeta.promptVersion,
+                        promptId: promptMeta.promptId,
+                    }),
+                }).then(() => triggerProcessing(userId, projectId, sessionId));
+            }
 
-                        logConversation({
-                            userId,
-                            agentId,
-                            sessionId,
-                            messages: finalMessages,
-                            modelId,
-                        }).then(() => triggerProcessing(userId, agentId, sessionId));
-                    }
+            return result;
+        },
+        async wrapStream({ doStream, params }: { doStream: any; params: any }) {
+            let result;
+            try {
+                logger.debug("Starting doStream with params", JSON.stringify(params, null, 2));
+                result = await doStream();
+            } catch (err) {
+                console.log((err as TypeError).cause)
+                console.log((err as TypeError).stack)
+                logger.error("doStream failed", err);
+
+                throw err;
+            }
+
+            if (isValidId(userId) && isValidId(sessionId)) {
+                const sessionKey = `${userId}:${projectId}:${sessionId}`;
+                const promptMeta = sessionPromptMetadata.get(sessionKey);
+
+                const messagesInput = (params as any).messages || (params as any).prompt || [];
+                const resultMessages = (result as any)?.response?.messages;
+                const finalMessages = Array.isArray(resultMessages) && resultMessages.length > 0
+                    ? resultMessages
+                    : messagesInput;
 
-                    return result;
-                },
-                async wrapStream({ doStream, params }) {
-                    const result = await doStream();
+                let streamUsage: Record<string, unknown> | undefined;
+                let accumulatedText = '';
 
-                    if (userId && sessionId) {
-                        const messagesInput = (params as any).messages || (params as any).prompt || [];
-                        const resultMessages = (result as any)?.response?.messages;
-                        const finalMessages = Array.isArray(resultMessages) && resultMessages.length > 0
-                            ? resultMessages
-                            : messagesInput;
+                const originalStream = result.stream;
+                const transformStream = new TransformStream({
+                    transform(chunk, controller) {
+                        if (chunk.type === 'text-delta') {
+                            accumulatedText += chunk.delta;
+                        }
+                        if (chunk.type === 'finish' && chunk.usage) {
+                            streamUsage = chunk.usage;
+                        }
+                        controller.enqueue(chunk);
+                    },
+                    flush() {
+                        const allMessages = accumulatedText
+                            ? [...finalMessages, { role: "assistant", content: [{ type: "text", text: accumulatedText }] }]
+                            : finalMessages;
 
                         logConversation({
                             userId,
-                            agentId,
+                            projectId,
                             sessionId,
-                            messages: finalMessages,
+                            messages: allMessages,
                             modelId,
-                        }).then(() => triggerProcessing(userId, agentId, sessionId));
+                            usage: streamUsage,
+                            ...(promptMeta && {
+                                promptSlug: promptMeta.promptSlug,
+                                promptVersion: promptMeta.promptVersion,
+                                promptId: promptMeta.promptId,
+                            }),
+                        }).then(() => triggerProcessing(userId, projectId, sessionId));
                     }
+                });
 
-                    return result;
-                }
+                result.stream = originalStream.pipeThrough(transformStream);
+            }
+
+            return result;
+        }
+    });
+
+    const resolveModel = (originalModel: LanguageModel, gatewaySlug?: string): LanguageModel => {
+        if (!gatewaySlug || !clConfig.providerFactory) {
+            if (gatewaySlug && !clConfig.providerFactory) {
+                logger.warn("Gateway config found but no providerFactory provided");
             }
+            return originalModel;
+        }
+
+        try {
+            const gatewayURL = `${baseUrl}/api/cognitive/gateway/${gatewaySlug}`;
+            const modelId = (originalModel as any).modelId || 'default';
+            const rawModel = clConfig.providerFactory(gatewayURL, clConfig.apiKey)(modelId);
+
+            const session = (originalModel as any)[SESSION_KEY];
+            if (!session) return rawModel as LanguageModel;
+
+            const wrapped = wrapLanguageModel({
+                model: rawModel as any,
+                middleware: buildMiddleware(session.userId, session.projectId, session.sessionId, modelId) as any,
+            });
+            (wrapped as any)[SESSION_KEY] = session;
+            return wrapped as LanguageModel;
+        } catch (err) {
+            logger.error("Failed to create gateway model, falling back to original", err);
+            return originalModel;
+        }
+    };
+
+    const clWrapper: CLModelWrapper = (
+        modelId: string,
+        settings?: { userId?: string; projectId?: string; sessionId?: string },
+        providerOptions?: Record<string, unknown>
+    ) => {
+        // Pass provider options through to the underlying provider
+        const model = (
+            providerOptions
+                ? provider(modelId, providerOptions)
+                : provider(modelId)
+        ) as LanguageModel;
+        const userId = settings?.userId;
+        const projectId = settings?.projectId || clConfig.projectId || "default";
+        const sessionId = settings?.sessionId;
+        const sessionMissing = isValidId(userId) && !isValidId(sessionId);
+
+        if (sessionMissing) {
+            logger.warn("sessionId is required to log and process memories; skipping logging until provided.");
+        }
+
+        const wrappedModel = wrapLanguageModel({
+            model: model as any,
+            middleware: buildMiddleware(userId, projectId, sessionId, modelId) as any,
+        }) as LanguageModel;
+
+        // Track session settings on the model for use in cl.streamText/cl.generateText
+        if (isValidId(userId) && isValidId(sessionId)) {
+            (wrappedModel as any)[SESSION_KEY] = { userId, projectId, sessionId };
+        }
+
+        return wrappedModel;
+    };
+
+    const clStreamText = async (options: CLStreamTextOptions) => {
+        const { prompt: promptConfig, ...rest } = options;
+
+        // Resolve and interpolate prompt
+        const resolved = await resolvePrompt(promptConfig.slug);
+        const system = promptConfig.variables
+            ? interpolateTemplate(resolved.content, promptConfig.variables)
+            : resolved.content;
+
+        // Store prompt metadata for the session (read by middleware during logging)
+        const session = (options.model as any)[SESSION_KEY] as { userId: string; projectId: string; sessionId: string } | undefined;
+        if (session) {
+            const sessionKey = `${session.userId}:${session.projectId}:${session.sessionId}`;
+            sessionPromptMetadata.set(sessionKey, {
+                promptSlug: resolved.slug,
+                promptVersion: resolved.version,
+                promptId: resolved.promptId,
+            });
+        }
+
+        logger.info("cl.streamText called", {
+            slug: promptConfig.slug,
+            version: resolved.version,
+            systemLength: system.length,
+        });
+
+        const model = resolveModel(options.model, resolved.gatewaySlug);
+        return aiStreamText({ ...rest, model, system } as any);
+    };
+
+    const clGenerateText = async (options: CLGenerateTextOptions) => {
+        const { prompt: promptConfig, ...rest } = options;
+
+        // Resolve and interpolate prompt
+        const resolved = await resolvePrompt(promptConfig.slug);
+        const system = promptConfig.variables
+            ? interpolateTemplate(resolved.content, promptConfig.variables)
+            : resolved.content;
+
+        // Store prompt metadata for the session (read by middleware during logging)
+        const session = (options.model as any)[SESSION_KEY] as { userId: string; projectId: string; sessionId: string } | undefined;
+        if (session) {
+            const sessionKey = `${session.userId}:${session.projectId}:${session.sessionId}`;
+            sessionPromptMetadata.set(sessionKey, {
+                promptSlug: resolved.slug,
+                promptVersion: resolved.version,
+                promptId: resolved.promptId,
+            });
+        }
+
+        logger.info("cl.generateText called", {
+            slug: promptConfig.slug,
+            version: resolved.version,
+            systemLength: system.length,
         });
+
+        const model = resolveModel(options.model, resolved.gatewaySlug);
+        return aiGenerateText({ ...rest, model, system } as any);
     };
+
+    // Return the model wrapper function with streamText/generateText attached
+    return Object.assign(clWrapper, {
+        streamText: clStreamText,
+        generateText: clGenerateText,
+        resolvePrompt,
+        logConversation,
+        triggerProcessing,
+        clearPromptCache: () => promptCache.clear(),
+        clearSessionCache: (sessionKey?: string) => {
+            if (sessionKey) {
+                sessionSnapshots.delete(sessionKey);
+                sessionPromptMetadata.delete(sessionKey);
+            } else {
+                sessionSnapshots.clear();
+                sessionPromptMetadata.clear();
+            }
+        },
+    });
 }