@kognitivedev/vercel-ai-provider 0.2.22 → 0.2.28

package/src/index.ts

@@ -4,7 +4,21 @@ import {
     generateText as aiGenerateText,
     type LanguageModel,
 } from "ai";
-import { randomUUID } from "crypto";
+import { MemoryClient } from "@kognitivedev/memory";
+import { createTopicMemoryTool, TOPIC_MEMORY_TOOL_ID } from "@kognitivedev/tools";
+import {
+    normalizeAutomaticThreadTitleConfig,
+    buildRemoteLogPayload,
+    buildRemoteRunPayload,
+    buildRemoteTraceFinishPayload,
+    buildRemoteTracePreviews,
+    buildRemoteTraceStartPayload,
+    createRemoteExecutionContext,
+    isSessionScopedExecution,
+    isModerationError,
+    normalizeRemoteUsage,
+    type AutomaticThreadTitleConfig,
+} from "@kognitivedev/shared";
 import { createPromptHubClient } from "@kognitivedev/prompthub";
 export { renderTemplate, type TemplateVariables } from "./template";
 import { renderTemplate } from "./template";
@@ -108,12 +122,18 @@ export interface PromptConfig {
     tag?: string;
 }
 
-export type CLStreamTextOptions = Omit<Parameters<typeof aiStreamText>[0], 'system' | 'prompt'> & {
-    prompt: PromptConfig;
+export interface CognitiveToolOptions {
+    autoTopicMemoryTool?: boolean;
+}
+
+export type CLStreamTextOptions = Omit<Parameters<typeof aiStreamText>[0], 'prompt'> & {
+    prompt?: PromptConfig;
+    kognitive?: CognitiveToolOptions;
 };
 
-export type CLGenerateTextOptions = Omit<Parameters<typeof aiGenerateText>[0], 'system' | 'prompt'> & {
-    prompt: PromptConfig;
+export type CLGenerateTextOptions = Omit<Parameters<typeof aiGenerateText>[0], 'prompt'> & {
+    prompt?: PromptConfig;
+    kognitive?: CognitiveToolOptions;
 };
 
 export interface LogConversationPayload {
@@ -140,6 +160,8 @@ export interface LogConversationPayload {
     durationMs?: number;
     tools?: Array<{ name: string; description?: string; parameters?: Record<string, unknown> }>;
     agentRunId?: string;
+    turnId?: string;
+    turnIndex?: number;
     metadata?: Record<string, unknown>;
     spans?: Array<{
         spanKey: string;
@@ -153,6 +175,11 @@ export interface LogConversationPayload {
         errorMessage?: string;
         metadata?: Record<string, unknown>;
     }>;
+    automaticTitle?: AutomaticThreadTitleConfig;
+}
+
+interface LogConversationResult {
+    generatedTitle: string | null;
 }
 
 export type CognitiveLayer = CLModelWrapper & {
@@ -162,7 +189,7 @@ export type CognitiveLayer = CLModelWrapper & {
         slug: string,
         userId?: string | { userId?: string; tag?: string }
     ) => Promise<CachedPrompt>;
-    logConversation: (payload: LogConversationPayload) => Promise<void>;
+    logConversation: (payload: LogConversationPayload) => Promise<LogConversationResult | null>;
     triggerProcessing: (userId: string, sessionId: string) => void;
     clearSessionCache: (sessionKey?: string) => void;
 };
@@ -181,24 +208,6 @@ export interface CachedPrompt {
     variant?: "control" | "variant";
 }
 
-function getContentText(content: any): string {
-    if (typeof content === "string") {
-        if (content.includes("data:image/") && content.includes("base64,")) return "[Image]";
-        return content;
-    }
-    if (!Array.isArray(content)) return "";
-
-    return content.map((part) => {
-        if (!part || typeof part !== "object") return "";
-        if (typeof part.text === "string") return part.text;
-        if (part.type === "tool-call" && typeof part.toolName === "string") return `Called ${part.toolName}`;
-        if (part.type === "tool-result") return "Received tool result";
-        if (part.type === "image" || part.type === "image_url") return "[Image]";
-        if (part.type === "file") return "[File]";
-        return "";
-    }).filter(Boolean).join(" ");
-}
-
 /**
  * Unwraps V2/V3 ToolResultOutput discriminated union to a displayable value.
  * Stream ToolResult uses plain `result` (passthrough), while prompt ToolResultPart
@@ -223,16 +232,6 @@ function extractOutputValue(raw: unknown): unknown {
     }
 }
 
-function buildTracePreviews(messages: any[]): { requestPreview: string; responsePreview: string } {
-    const request = [...messages].reverse().find((message) => message?.role === "user");
-    const response = [...messages].reverse().find((message) => message?.role === "assistant");
-
-    return {
-        requestPreview: request ? getContentText(request.content).slice(0, 220) : "No request captured",
-        responsePreview: response ? getContentText(response.content).slice(0, 240) : "No response captured",
-    };
-}
-
 function buildTraceSpansFromMessages(messages: any[]): Array<{
     spanKey: string;
     parentSpanKey?: string;
@@ -328,6 +327,174 @@ 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; tag?: string; abTestId?: string; variant?: "control" | "variant" }>();
 
+function toAISDKTopicMemoryTool(
+    userId: string,
+    baseUrl: string,
+    apiKey: string,
+): Record<string, unknown> {
+    const tool = createTopicMemoryTool({ apiKey, baseUrl });
+
+    return {
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+        execute: async (input: unknown) => {
+            const result = await tool.execute(input as any, {
+                abortSignal: new AbortController().signal,
+                resourceId: { userId },
+                metadata: undefined,
+                emit: () => {},
+            });
+
+            return tool.toModelOutput ? tool.toModelOutput(result) : result;
+        },
+    };
+}
+
+function withAutoInjectedTools(
+    params: Record<string, unknown>,
+    session: { userId: string; projectId?: string; sessionId?: string } | undefined,
+    baseUrl: string,
+    apiKey: string,
+    options?: CognitiveToolOptions,
+): Record<string, unknown> {
+    if (!options?.autoTopicMemoryTool || !isValidId(session?.userId)) {
+        return params;
+    }
+
+    const existingTools = params.tools;
+    if (existingTools && (typeof existingTools !== "object" || Array.isArray(existingTools))) {
+        return params;
+    }
+
+    const toolSet = { ...((existingTools as Record<string, unknown> | undefined) ?? {}) };
+    if (TOPIC_MEMORY_TOOL_ID in toolSet) {
+        return params;
+    }
+
+    toolSet[TOPIC_MEMORY_TOOL_ID] = toAISDKTopicMemoryTool(session.userId, baseUrl, apiKey);
+    return {
+        ...params,
+        tools: toolSet,
+    };
+}
+
+export function toMessageEventStream(
+    result: { fullStream: AsyncIterable<any> },
+): ReadableStream<{ event: string; data: unknown }> {
+    return new ReadableStream({
+        async start(controller) {
+            try {
+                for await (const chunk of result.fullStream) {
+                    if (chunk.type === "text-delta" && chunk.delta) {
+                        controller.enqueue({
+                            event: "messages",
+                            data: { token: chunk.delta },
+                        });
+                        continue;
+                    }
+
+                    if (chunk.type === "tool-call") {
+                        controller.enqueue({
+                            event: "messages",
+                            data: {
+                                type: "tool-call",
+                                id: chunk.toolCallId,
+                                name: chunk.toolName,
+                                input: chunk.input,
+                            },
+                        });
+                        continue;
+                    }
+
+                    if (chunk.type === "tool-result") {
+                        controller.enqueue({
+                            event: "messages",
+                            data: {
+                                type: "tool-result",
+                                id: chunk.toolCallId,
+                                name: chunk.toolName,
+                                result: chunk.result,
+                            },
+                        });
+                        continue;
+                    }
+
+                    if (chunk.type === "error") {
+                        controller.enqueue({
+                            event: "debug",
+                            data: {
+                                type: "error",
+                                message: chunk.error instanceof Error ? chunk.error.message : String(chunk.error),
+                            },
+                        });
+                    }
+                }
+            } finally {
+                controller.close();
+            }
+        },
+    });
+}
+
+export function toGeneratedMessageEventStream(
+    result: {
+        text?: string;
+        toolCalls?: Array<{ toolCallId?: string; toolName?: string; input?: unknown }>;
+        toolResults?: Array<{ toolCallId?: string; toolName?: string; output?: unknown; result?: unknown; isError?: boolean }>;
+        steps?: Array<{
+            toolCalls?: Array<{ toolCallId?: string; toolName?: string; input?: unknown }>;
+            toolResults?: Array<{ toolCallId?: string; toolName?: string; output?: unknown; result?: unknown; isError?: boolean }>;
+        }>;
+    },
+): ReadableStream<{ event: string; data: unknown }> {
+    return new ReadableStream({
+        start(controller) {
+            const steps = result.steps?.length
+                ? result.steps
+                : [{
+                    toolCalls: result.toolCalls,
+                    toolResults: result.toolResults,
+                }];
+
+            for (const step of steps) {
+                for (const toolCall of step.toolCalls ?? []) {
+                    controller.enqueue({
+                        event: "messages",
+                        data: {
+                            type: "tool-call",
+                            id: toolCall.toolCallId,
+                            name: toolCall.toolName ?? "tool",
+                            input: toolCall.input,
+                        },
+                    });
+                }
+
+                for (const toolResult of step.toolResults ?? []) {
+                    controller.enqueue({
+                        event: "messages",
+                        data: {
+                            type: "tool-result",
+                            id: toolResult.toolCallId,
+                            name: toolResult.toolName ?? "tool",
+                            result: toolResult.output ?? toolResult.result,
+                            ...(toolResult.isError ? { isError: true } : {}),
+                        },
+                    });
+                }
+            }
+
+            if (result.text) {
+                controller.enqueue({
+                    event: "messages",
+                    data: { token: result.text },
+                });
+            }
+
+            controller.close();
+        },
+    });
+}
+
 /**
  * Check if any system message already contains a <MemoryContext> block.
  */
@@ -357,6 +524,11 @@ export function createCognitiveLayer(config: {
     // Default to 'info' log level
     const logLevel = clConfig.logLevel || 'info';
     const logger = createLogger(logLevel);
+    const memoryClient = new MemoryClient({
+        apiKey: clConfig.apiKey,
+        baseUrl,
+        logger: logger as any,
+    });
 
     const authHeaders = {
         "Content-Type": "application/json",
@@ -368,6 +540,23 @@ export function createCognitiveLayer(config: {
         apiKey: clConfig.apiKey,
         logger,
     });
+    const sessionTurnIndexes = new Map<string, number>();
+
+    const reserveTurnIndex = (
+        agentName: string,
+        userId: string | undefined,
+        sessionId: string | undefined,
+        requestedRunScope?: string,
+    ): number | undefined => {
+        if (!isValidId(userId) || !isValidId(sessionId) || !isSessionScopedExecution(requestedRunScope, sessionId ? "session" : "invocation")) {
+            return undefined;
+        }
+
+        const key = `${agentName}:${getSessionKey(userId, sessionId)}`;
+        const nextIndex = sessionTurnIndexes.get(key) ?? 0;
+        sessionTurnIndexes.set(key, nextIndex + 1);
+        return nextIndex;
+    };
 
     const resolvePrompt = async (slug: string, userIdOrOptions?: string | { userId?: string; tag?: string }): Promise<CachedPrompt> => {
         const userId = typeof userIdOrOptions === "string"
@@ -409,7 +598,7 @@ export function createCognitiveLayer(config: {
 
     const logConversation = async (payload: LogConversationPayload) => {
         try {
-            await fetch(`${baseUrl}/api/cognitive/log`, {
+            const response = await fetch(`${baseUrl}/api/cognitive/log`, {
                 method: "POST",
                 headers: authHeaders,
                 body: JSON.stringify({
@@ -418,18 +607,74 @@ export function createCognitiveLayer(config: {
                     timestamp: new Date().toISOString(),
                 }),
             });
+            if (!response.ok) {
+                logger.warn("Log failed", { status: response.status });
+                return null;
+            }
+            const data = await response.json().catch(() => null) as { generatedTitle?: unknown } | null;
+            return {
+                generatedTitle: typeof data?.generatedTitle === "string" ? data.generatedTitle : null,
+            };
         } catch (e) {
             logger.error("Log failed", e);
+            return null;
         }
     };
 
-    const triggerProcessing = (userId: string, sessionId: string) => {
-        const run = () => {
-            fetch(`${baseUrl}/api/cognitive/process`, {
+    const postAgentRun = async (payload: Record<string, unknown>) => {
+        try {
+            const response = await fetch(`${baseUrl}/api/cognitive/agent-run`, {
+                method: "POST",
+                headers: authHeaders,
+                body: JSON.stringify(payload),
+            });
+            if (!response.ok) {
+                logger.warn("Agent run request failed", { status: response.status });
+                return null;
+            }
+            return await response.json().catch(() => null);
+        } catch (e) {
+            logger.error("Agent run request failed", e);
+            return null;
+        }
+    };
+
+    const postTraceEvents = async (payload: Record<string, unknown>) => {
+        try {
+            const response = await fetch(`${baseUrl}/api/cognitive/trace-events`, {
                 method: "POST",
                 headers: authHeaders,
-                body: JSON.stringify({ userId, sessionId }),
-            }).catch(e => logger.error("Process trigger failed", e));
+                body: JSON.stringify(payload),
+            });
+            if (!response.ok) {
+                logger.warn("Trace events request failed", { status: response.status });
+                return null;
+            }
+            return await response.json().catch(() => null);
+        } catch (e) {
+            logger.error("Trace events request failed", e);
+            return null;
+        }
+    };
+
+    const appendLiveTraceEvents = async (payload: {
+        traceDbId?: string;
+        traceId: string;
+        sessionDbId?: string;
+        events: Array<{ eventType: string; spanKey?: string; status?: string; payload?: Record<string, unknown> }>;
+    }) => {
+        await postTraceEvents({
+            traceDbId: payload.traceDbId,
+            traceId: payload.traceId,
+            sessionDbId: payload.sessionDbId,
+            events: payload.events,
+        });
+    };
+
+    const triggerProcessing = (userId: string, sessionId: string) => {
+        const run = () => {
+            memoryClient.triggerProcessing(userId, sessionId)
+                .catch((e) => logger.error("Process trigger failed", e));
         };
 
         if (processDelay > 0) {
@@ -462,6 +707,33 @@ export function createCognitiveLayer(config: {
         return { nextParams, messages: updated, mode: "prepend-system" };
     };
 
+    const getKognitiveProviderConfig = (params: any): Record<string, unknown> | undefined => {
+        const providerOptionsKognitive = params?.providerOptions?.kognitive;
+        if (providerOptionsKognitive && typeof providerOptionsKognitive === "object") {
+            return providerOptionsKognitive as Record<string, unknown>;
+        }
+
+        const providerMetadataKognitive = params?.providerMetadata?.kognitive;
+        if (providerMetadataKognitive && typeof providerMetadataKognitive === "object") {
+            return providerMetadataKognitive as Record<string, unknown>;
+        }
+
+        return undefined;
+    };
+
+    const resolveRequestedRunScope = (params: any): string | undefined => {
+        const direct = typeof params?.runScope === "string" ? params.runScope : undefined;
+        const kognitiveConfig = getKognitiveProviderConfig(params);
+        const providerMetadataScope = typeof kognitiveConfig?.runScope === "string"
+            ? kognitiveConfig.runScope
+            : undefined;
+        return direct ?? providerMetadataScope;
+    };
+
+    const resolveAutomaticTitleConfig = (params: any): AutomaticThreadTitleConfig | undefined => {
+        return normalizeAutomaticThreadTitleConfig(getKognitiveProviderConfig(params)?.automaticTitle);
+    };
+
     const buildMiddleware = (userId: string | undefined, projectId: string | undefined, sessionId: string | undefined, modelId: string) => ({
         specificationVersion: 'v3' as const,
         async transformParams({ params }: { params: any }) {
@@ -484,68 +756,38 @@ export function createCognitiveLayer(config: {
             // 3) Fetch snapshot only if not cached
             if (systemPromptToAdd === undefined) {
                 try {
-                    const url = `${baseUrl}/api/cognitive/snapshot?userId=${userId}`;
                     logger.debug("Fetching snapshot from backend", {
                         userId,
                         sessionId,
-                        url,
+                        url: `${baseUrl}/api/cognitive/snapshot?userId=${userId}`,
                         baseUrl,
                         apiKeyHint: maskSecret(clConfig.apiKey),
                     });
-                    const res = await fetch(url, {
-                        headers: { "Authorization": `Bearer ${clConfig.apiKey}` },
-                    });
-                    logger.debug("Snapshot response received", {
+                    const snapshot = await memoryClient.getSnapshot(userId);
+                    const systemBlock = snapshot?.systemBlock || "";
+                    const userContextBlock = snapshot?.userContextBlock || "";
+                    const topicIndexBlock = snapshot?.topicIndexBlock || "";
+                    const topicContextBlock = snapshot?.topicContextBlock || "";
+                    systemPromptToAdd = snapshot ? memoryClient.buildMemoryBlock(snapshot) : "";
+
+                    sessionSnapshots.set(sessionKey, systemPromptToAdd);
+
+                    logger.info("Snapshot fetched and cached", {
                         userId,
                         sessionId,
-                        status: res.status,
-                        ok: res.ok,
-                        contentType: res.headers.get("content-type"),
+                        sessionKey,
+                        systemLen: systemBlock.length,
+                        userLen: userContextBlock.length,
+                        topicIndexLen: topicIndexBlock.length,
+                        topicContextLen: topicContextBlock.length,
+                    });
+                    logger.debug("Full snapshot data", {
+                        systemBlock,
+                        userContextBlock,
+                        topicIndexBlock,
+                        topicContextBlock,
+                        rawData: snapshot,
                     });
-                    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,
-                            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 {
-                        const body = await res.text();
-                        logger.warn("Snapshot fetch failed", { status: res.status });
-                        logger.debug("Snapshot response body preview", {
-                            userId,
-                            projectId,
-                            sessionId,
-                            status: res.status,
-                            bodyPreview: previewText(body),
-                        });
-                        systemPromptToAdd = "";
-                        sessionSnapshots.set(sessionKey, systemPromptToAdd);
-                    }
                 } catch (e) {
                     logger.warn("Failed to fetch snapshot", e);
                     systemPromptToAdd = "";
@@ -576,10 +818,86 @@ ${userContextBlock || "None"}
 
         async wrapGenerate({ doGenerate, params }: { doGenerate: any; params: any }) {
             const startedAt = new Date();
+            const requestedRunScope = resolveRequestedRunScope(params);
+            const remoteAgentName = clConfig.appId ?? modelId;
+            const turnIndex = reserveTurnIndex(remoteAgentName, userId, sessionId, requestedRunScope);
+            const remoteExecution = createRemoteExecutionContext({
+                agentName: remoteAgentName,
+                sessionId,
+                requestedRunScope,
+                runId: getKognitiveProviderConfig(params)?.agentRunId as string | undefined,
+                turnIndex,
+            });
+            const traceId = remoteExecution.traceId;
+            let liveTraceDbId: string | undefined;
+            if (isValidId(userId) && isValidId(sessionId)) {
+                const messagesInput = (params as any).prompt || (params as any).messages || [];
+                const { requestPreview } = buildRemoteTracePreviews(messagesInput);
+                await postAgentRun(buildRemoteRunPayload({
+                    execution: remoteExecution,
+                    userId,
+                    sessionId,
+                    modelId,
+                    status: "running",
+                    inputPreview: requestPreview,
+                    startedAt: startedAt.toISOString(),
+                    metadata: {
+                        appId: clConfig.appId,
+                    },
+                    sessionMetadata: {
+                        kind: "chat",
+                        agentName: remoteExecution.agentName,
+                    },
+                }));
+            }
+            if (isValidId(userId) && isValidId(sessionId) && isValidId(projectId)) {
+                const messagesInput = (params as any).prompt || (params as any).messages || [];
+                const { requestPreview } = buildRemoteTracePreviews(messagesInput);
+                const traceResponse = await postTraceEvents(buildRemoteTraceStartPayload({
+                    execution: remoteExecution,
+                    userId,
+                    projectId,
+                    sessionId,
+                    requestPreview,
+                    modelId,
+                    metadata: {
+                        appId: clConfig.appId,
+                    },
+                    startedAt: startedAt.toISOString(),
+                }));
+                liveTraceDbId = typeof traceResponse?.traceDbId === "string" ? traceResponse.traceDbId : undefined;
+            }
             let result;
             try {
                 result = await doGenerate();
             } catch (err) {
+                const errorMessage = err instanceof Error ? err.message : String(err);
+                if (liveTraceDbId) {
+                    await postTraceEvents(buildRemoteTraceFinishPayload({
+                        execution: remoteExecution,
+                        traceDbId: liveTraceDbId,
+                        state: "error",
+                        responsePreview: errorMessage.slice(0, 240),
+                        durationMs: Date.now() - startedAt.getTime(),
+                        errorMessage,
+                    }));
+                }
+                if (isValidId(userId) && isValidId(sessionId)) {
+                    await postAgentRun(buildRemoteRunPayload({
+                        execution: remoteExecution,
+                        userId,
+                        sessionId,
+                        modelId,
+                        status: "failed",
+                        errorMessage,
+                        durationMs: Date.now() - startedAt.getTime(),
+                        startedAt: startedAt.toISOString(),
+                        completedAt: new Date().toISOString(),
+                        metadata: {
+                            appId: clConfig.appId,
+                        },
+                    }));
+                }
                 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;
@@ -589,7 +907,7 @@ ${userContextBlock || "None"}
                 const endedAt = new Date();
                 const sessionKey = getSessionKey(userId, sessionId);
                 const promptMeta = sessionPromptMetadata.get(sessionKey);
-                const agentRunId = (params as any)?.providerMetadata?.kognitive?.agentRunId as string | undefined;
+                const automaticTitle = resolveAutomaticTitleConfig(params);
 
                 const messagesInput = (params as any).prompt || (params as any).messages || [];
 
@@ -619,11 +937,39 @@ ${userContextBlock || "None"}
                     ? [{ role: "assistant", content: assistantParts }]
                     : [];
                 const finalMessages = [...messagesInput, ...assistantMessage];
-                const { requestPreview, responsePreview } = buildTracePreviews(finalMessages);
+                const { requestPreview, responsePreview } = buildRemoteTracePreviews(finalMessages);
                 const spans = buildTraceSpansFromMessages(finalMessages);
                 const toolDefs = extractToolDefinitions(params);
+                const usage = normalizeRemoteUsage(result.usage);
+
+                await postAgentRun(buildRemoteRunPayload({
+                    execution: remoteExecution,
+                    userId,
+                    sessionId,
+                    modelId,
+                    status: "completed",
+                    inputPreview: requestPreview,
+                    outputPreview: responsePreview,
+                    inputTokens: usage.inputTokens,
+                    outputTokens: usage.outputTokens,
+                    cachedInputTokens: usage.cachedInputTokens,
+                    durationMs: endedAt.getTime() - startedAt.getTime(),
+                    startedAt: startedAt.toISOString(),
+                    completedAt: endedAt.toISOString(),
+                    metadata: {
+                        appId: clConfig.appId,
+                        ...(promptMeta?.tag && { promptTag: promptMeta.tag }),
+                        ...(promptMeta?.abTestId && { abTestId: promptMeta.abTestId }),
+                        ...(promptMeta?.variant && { variant: promptMeta.variant }),
+                    },
+                    sessionMetadata: {
+                        kind: "chat",
+                        agentName: remoteExecution.agentName,
+                    },
+                }));
 
-                logConversation({
+                const logResult = await logConversation(buildRemoteLogPayload({
+                    execution: remoteExecution,
                     userId,
                     sessionId,
                     messages: finalMessages,
@@ -638,8 +984,6 @@ ${userContextBlock || "None"}
                         variant: promptMeta.variant,
                     }),
                     ...(toolDefs && { tools: toolDefs }),
-                    ...(agentRunId && { agentRunId }),
-                    traceId: randomUUID(),
                     requestPreview,
                     responsePreview,
                     state: "completed",
@@ -648,24 +992,111 @@ ${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 }),
+                        ...(promptMeta?.tag && { promptTag: promptMeta.tag }),
+                        ...(promptMeta?.abTestId && { abTestId: promptMeta.abTestId }),
+                        ...(promptMeta?.variant && { variant: promptMeta.variant }),
                     },
                     spans,
-                }).then(() => triggerProcessing(userId, sessionId));
+                    automaticTitle,
+                }) as unknown as LogConversationPayload);
+                if (logResult) {
+                    triggerProcessing(userId, sessionId);
+                }
+
+                await postTraceEvents(buildRemoteTraceFinishPayload({
+                    execution: remoteExecution,
+                    traceDbId: liveTraceDbId,
+                    state: "completed",
+                    responsePreview,
+                    durationMs: endedAt.getTime() - startedAt.getTime(),
+                    usage: result.usage,
+                }));
             }
 
             return result;
         },
         async wrapStream({ doStream, params }: { doStream: any; params: any }) {
             const startedAt = new Date();
-            const traceId = randomUUID();
+            const requestedRunScope = resolveRequestedRunScope(params);
+            const remoteAgentName = clConfig.appId ?? modelId;
+            const turnIndex = reserveTurnIndex(remoteAgentName, userId, sessionId, requestedRunScope);
+            const remoteExecution = createRemoteExecutionContext({
+                agentName: remoteAgentName,
+                sessionId,
+                requestedRunScope,
+                runId: getKognitiveProviderConfig(params)?.agentRunId as string | undefined,
+                turnIndex,
+            });
+            const traceId = remoteExecution.traceId;
+            let liveTraceDbId: string | undefined;
+            if (isValidId(userId) && isValidId(sessionId)) {
+                const messagesInput = (params as any).prompt || (params as any).messages || [];
+                const { requestPreview } = buildRemoteTracePreviews(messagesInput);
+                await postAgentRun(buildRemoteRunPayload({
+                    execution: remoteExecution,
+                    userId,
+                    sessionId,
+                    modelId,
+                    status: "running",
+                    inputPreview: requestPreview,
+                    startedAt: startedAt.toISOString(),
+                    metadata: {
+                        appId: clConfig.appId,
+                    },
+                    sessionMetadata: {
+                        kind: "chat",
+                        agentName: remoteExecution.agentName,
+                    },
+                }));
+            }
+            if (isValidId(userId) && isValidId(sessionId) && isValidId(projectId)) {
+                const messagesInput = (params as any).prompt || (params as any).messages || [];
+                const { requestPreview } = buildRemoteTracePreviews(messagesInput);
+                const traceResponse = await postTraceEvents(buildRemoteTraceStartPayload({
+                    execution: remoteExecution,
+                    userId,
+                    projectId,
+                    sessionId,
+                    requestPreview,
+                    modelId,
+                    metadata: {
+                        appId: clConfig.appId,
+                    },
+                    startedAt: startedAt.toISOString(),
+                }));
+                liveTraceDbId = typeof traceResponse?.traceDbId === "string" ? traceResponse.traceDbId : undefined;
+            }
             let result;
             try {
                 logger.debug("Starting doStream with params", JSON.stringify(params, null, 2));
                 result = await doStream();
             } catch (err) {
+                if (liveTraceDbId) {
+                    await postTraceEvents(buildRemoteTraceFinishPayload({
+                        execution: remoteExecution,
+                        traceDbId: liveTraceDbId,
+                        state: "error",
+                        responsePreview: err instanceof Error ? err.message.slice(0, 240) : "Stream failed",
+                        durationMs: Date.now() - startedAt.getTime(),
+                        errorMessage: err instanceof Error ? err.message : String(err),
+                    }));
+                }
+                if (isValidId(userId) && isValidId(sessionId)) {
+                    await postAgentRun(buildRemoteRunPayload({
+                        execution: remoteExecution,
+                        userId,
+                        sessionId,
+                        modelId,
+                        status: "failed",
+                        errorMessage: err instanceof Error ? err.message : String(err),
+                        durationMs: Date.now() - startedAt.getTime(),
+                        startedAt: startedAt.toISOString(),
+                        completedAt: new Date().toISOString(),
+                        metadata: {
+                            appId: clConfig.appId,
+                        },
+                    }));
+                }
                 console.log((err as TypeError).cause)
                 console.log((err as TypeError).stack)
                 logger.error("doStream failed", err);
@@ -676,7 +1107,7 @@ ${userContextBlock || "None"}
             if (isValidId(userId) && isValidId(sessionId)) {
                 const sessionKey = getSessionKey(userId, sessionId);
                 const promptMeta = sessionPromptMetadata.get(sessionKey);
-                const agentRunId = (params as any)?.providerMetadata?.kognitive?.agentRunId as string | undefined;
+                const automaticTitle = resolveAutomaticTitleConfig(params);
 
                 const messagesInput = (params as any).prompt || (params as any).messages || [];
                 const resultMessages = (result as any)?.response?.messages;
@@ -686,7 +1117,10 @@ ${userContextBlock || "None"}
 
                 let streamUsage: Record<string, unknown> | undefined;
                 let accumulatedText = '';
+                let pendingProgressDelta = '';
+                let lastProgressAt = Date.now();
                 const toolCallInputs = new Map<string, { toolName: string; chunks: string[] }>();
+                const startedToolCalls = new Set<string>();
                 const completedToolCalls: any[] = [];
                 const completedToolResults: any[] = [];
 
@@ -695,6 +1129,23 @@ ${userContextBlock || "None"}
                     transform(chunk, controller) {
                         if (chunk.type === 'text-delta') {
                             accumulatedText += chunk.delta;
+                            pendingProgressDelta += chunk.delta;
+                            if (liveTraceDbId && pendingProgressDelta && (pendingProgressDelta.length >= 80 || Date.now() - lastProgressAt >= 250)) {
+                                void appendLiveTraceEvents({
+                                    traceDbId: liveTraceDbId,
+                                    traceId,
+                                    events: [{
+                                        eventType: "assistant.progress",
+                                        status: "active",
+                                        payload: {
+                                            text: pendingProgressDelta,
+                                            preview: previewText(accumulatedText),
+                                        },
+                                    }],
+                                });
+                                pendingProgressDelta = '';
+                                lastProgressAt = Date.now();
+                            }
                         }
                         if (chunk.type === 'finish' && chunk.usage) {
                             streamUsage = chunk.usage;
@@ -702,6 +1153,23 @@ ${userContextBlock || "None"}
                         // Capture tool-call stream chunks (V2/V3 shared types)
                         if (chunk.type === 'tool-input-start') {
                             toolCallInputs.set(chunk.id, { toolName: chunk.toolName, chunks: [] });
+                            if (liveTraceDbId && !startedToolCalls.has(chunk.id)) {
+                                startedToolCalls.add(chunk.id);
+                                void appendLiveTraceEvents({
+                                    traceDbId: liveTraceDbId,
+                                    traceId,
+                                    events: [{
+                                        eventType: "tool.started",
+                                        spanKey: chunk.id,
+                                        status: "active",
+                                        payload: {
+                                            toolCallId: chunk.id,
+                                            toolName: chunk.toolName,
+                                            inputPreview: "",
+                                        },
+                                    }],
+                                });
+                            }
                         }
                         if (chunk.type === 'tool-input-delta') {
                             const entry = toolCallInputs.get(chunk.id);
@@ -714,6 +1182,29 @@ ${userContextBlock || "None"}
                                 toolName: chunk.toolName,
                                 input: chunk.input,
                             });
+                            if (!toolCallInputs.has(chunk.toolCallId)) {
+                                toolCallInputs.set(chunk.toolCallId, {
+                                    toolName: chunk.toolName,
+                                    chunks: typeof chunk.input === "string" ? [chunk.input] : [],
+                                });
+                            }
+                            if (liveTraceDbId && !startedToolCalls.has(chunk.toolCallId)) {
+                                startedToolCalls.add(chunk.toolCallId);
+                                void appendLiveTraceEvents({
+                                    traceDbId: liveTraceDbId,
+                                    traceId,
+                                    events: [{
+                                        eventType: "tool.started",
+                                        spanKey: chunk.toolCallId,
+                                        status: "active",
+                                        payload: {
+                                            toolCallId: chunk.toolCallId,
+                                            toolName: chunk.toolName,
+                                            inputPreview: typeof chunk.input === "string" ? previewText(chunk.input) : "",
+                                        },
+                                    }],
+                                });
+                            }
                         }
                         if (chunk.type === 'tool-result') {
                             completedToolResults.push({
@@ -722,11 +1213,41 @@ ${userContextBlock || "None"}
                                 toolName: chunk.toolName,
                                 result: chunk.result,
                             });
+                            if (liveTraceDbId) {
+                                void appendLiveTraceEvents({
+                                    traceDbId: liveTraceDbId,
+                                    traceId,
+                                    events: [{
+                                        eventType: "tool.completed",
+                                        spanKey: chunk.toolCallId,
+                                        status: "completed",
+                                        payload: {
+                                            toolCallId: chunk.toolCallId,
+                                            toolName: chunk.toolName,
+                                            outputPreview: previewText(JSON.stringify(chunk.result)),
+                                        },
+                                    }],
+                                });
+                            }
                         }
                         controller.enqueue(chunk);
                     },
                     async flush() {
                         const endedAt = new Date();
+                        if (liveTraceDbId && pendingProgressDelta) {
+                            await appendLiveTraceEvents({
+                                traceDbId: liveTraceDbId,
+                                traceId,
+                                events: [{
+                                    eventType: "assistant.progress",
+                                    status: "active",
+                                    payload: {
+                                        text: pendingProgressDelta,
+                                        preview: previewText(accumulatedText),
+                                    },
+                                }],
+                            });
+                        }
 
                         // Finalize any tool calls from incremental input chunks
                         for (const [id, entry] of toolCallInputs) {
@@ -753,14 +1274,40 @@ ${userContextBlock || "None"}
                             allMessages.push({ role: "tool", content: completedToolResults });
                         }
 
-                        const { requestPreview, responsePreview } = buildTracePreviews(allMessages);
+                        const { requestPreview, responsePreview } = buildRemoteTracePreviews(allMessages);
                         const spans = buildTraceSpansFromMessages(allMessages);
                         const toolDefs = extractToolDefinitions(params);
+                        const usage = normalizeRemoteUsage(streamUsage);
 
-                        // Fire-and-forget: do not await so the stream closes immediately,
-                        // allowing the AI SDK's multi-step continuation logic to proceed.
-                        logConversation({
-                        userId,
+                        await postAgentRun(buildRemoteRunPayload({
+                            execution: remoteExecution,
+                            userId,
+                            sessionId,
+                            modelId,
+                            status: "completed",
+                            inputPreview: requestPreview,
+                            outputPreview: responsePreview,
+                            inputTokens: usage.inputTokens,
+                            outputTokens: usage.outputTokens,
+                            cachedInputTokens: usage.cachedInputTokens,
+                            durationMs: endedAt.getTime() - startedAt.getTime(),
+                            startedAt: startedAt.toISOString(),
+                            completedAt: endedAt.toISOString(),
+                            metadata: {
+                                appId: clConfig.appId,
+                                ...(promptMeta?.tag && { promptTag: promptMeta.tag }),
+                                ...(promptMeta?.abTestId && { abTestId: promptMeta.abTestId }),
+                                ...(promptMeta?.variant && { variant: promptMeta.variant }),
+                            },
+                            sessionMetadata: {
+                                kind: "chat",
+                                agentName: remoteExecution.agentName,
+                            },
+                        }));
+
+                        const logResult = await logConversation(buildRemoteLogPayload({
+                            execution: remoteExecution,
+                            userId,
                             sessionId,
                             messages: allMessages,
                             modelId,
@@ -774,8 +1321,6 @@ ${userContextBlock || "None"}
                                 variant: promptMeta.variant,
                             }),
                             ...(toolDefs && { tools: toolDefs }),
-                            ...(agentRunId && { agentRunId }),
-                            traceId,
                             requestPreview,
                             responsePreview,
                             state: "completed",
@@ -789,8 +1334,36 @@ ${userContextBlock || "None"}
                                 ...(promptMeta?.variant && { variant: promptMeta.variant }),
                             },
                             spans,
-                        }).then(() => triggerProcessing(userId, sessionId))
-                          .catch((e) => logger.error("Stream log failed", e));
+                            automaticTitle,
+                        }) as unknown as LogConversationPayload);
+                        if (logResult) {
+                            triggerProcessing(userId, sessionId);
+                        }
+                        if (logResult?.generatedTitle) {
+                            const currentProviderMetadata = result.providerMetadata && typeof result.providerMetadata === "object"
+                                ? result.providerMetadata as Record<string, unknown>
+                                : {};
+                            const currentKognitiveMetadata = currentProviderMetadata.kognitive
+                                && typeof currentProviderMetadata.kognitive === "object"
+                                ? currentProviderMetadata.kognitive as Record<string, unknown>
+                                : {};
+                            result.providerMetadata = {
+                                ...currentProviderMetadata,
+                                kognitive: {
+                                    ...currentKognitiveMetadata,
+                                    generatedTitle: logResult.generatedTitle,
+                                },
+                            };
+                        }
+
+                        await postTraceEvents(buildRemoteTraceFinishPayload({
+                            execution: remoteExecution,
+                            traceDbId: liveTraceDbId,
+                            state: "completed",
+                            responsePreview,
+                            durationMs: endedAt.getTime() - startedAt.getTime(),
+                            usage: streamUsage,
+                        }));
                     }
                 });
 
@@ -865,25 +1438,30 @@ ${userContextBlock || "None"}
     };
 
     const clStreamText = async (options: CLStreamTextOptions) => {
-        const { prompt: promptConfig, ...rest } = options;
-
-    const session = (options.model as any)[SESSION_KEY] as { userId: string; projectId?: string; sessionId?: string } | undefined;
+        const { prompt: promptConfig, kognitive, ...rest } = options;
+        const session = (options.model as any)[SESSION_KEY] as { userId: string; projectId?: string; sessionId?: string } | undefined;
 
         // Resolve and interpolate prompt (graceful fallback on failure)
         let resolved: CachedPrompt | null = null;
-        try {
-            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);
+        if (promptConfig?.slug) {
+            try {
+                resolved = await resolvePrompt(promptConfig.slug, {
+                    userId: session?.userId,
+                    tag: promptConfig.tag,
+                });
+            } catch (err) {
+                if (isModerationError(err)) {
+                    throw err;
+                }
+                logger.warn(`Failed to resolve prompt "${promptConfig.slug}", streaming without system prompt.`, err);
+            }
         }
 
-        let system: string | undefined;
+        let system = typeof rest.system === "string" ? rest.system : undefined;
         if (resolved) {
-            system = promptConfig.variables
-                ? renderTemplate(resolved.content, promptConfig.variables)
+            const resolvedPromptConfig = promptConfig!;
+            system = resolvedPromptConfig.variables
+                ? renderTemplate(resolved.content, resolvedPromptConfig.variables)
                 : resolved.content;
 
             // Store prompt metadata for the session (read by middleware during logging)
@@ -900,40 +1478,52 @@ ${userContextBlock || "None"}
             }
 
             logger.info("cl.streamText called", {
-                slug: promptConfig.slug,
+                slug: resolvedPromptConfig.slug,
                 version: resolved.version,
                 systemLength: system.length,
             });
-        } else {
+        } else if (promptConfig?.slug) {
             logger.info("cl.streamText called without resolved prompt", {
                 slug: promptConfig.slug,
             });
         }
 
         const model = resolveModel(options.model, resolved?.gatewaySlug);
-        return aiStreamText({ ...rest, model, ...(system && { system }) } as any);
+        const nextParams = withAutoInjectedTools(
+            { ...rest, model, ...(system && { system }) },
+            session,
+            baseUrl,
+            clConfig.apiKey,
+            kognitive,
+        );
+        return aiStreamText(nextParams as any);
     };
 
     const clGenerateText = async (options: CLGenerateTextOptions) => {
-        const { prompt: promptConfig, ...rest } = options;
-
-    const session = (options.model as any)[SESSION_KEY] as { userId: string; projectId?: string; sessionId?: string } | undefined;
+        const { prompt: promptConfig, kognitive, ...rest } = options;
+        const session = (options.model as any)[SESSION_KEY] as { userId: string; projectId?: string; sessionId?: string } | undefined;
 
         // Resolve and interpolate prompt (graceful fallback on failure)
         let resolved: CachedPrompt | null = null;
-        try {
-            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);
+        if (promptConfig?.slug) {
+            try {
+                resolved = await resolvePrompt(promptConfig.slug, {
+                    userId: session?.userId,
+                    tag: promptConfig.tag,
+                });
+            } catch (err) {
+                if (isModerationError(err)) {
+                    throw err;
+                }
+                logger.warn(`Failed to resolve prompt "${promptConfig.slug}", generating without system prompt.`, err);
+            }
         }
 
-        let system: string | undefined;
+        let system = typeof rest.system === "string" ? rest.system : undefined;
         if (resolved) {
-            system = promptConfig.variables
-                ? renderTemplate(resolved.content, promptConfig.variables)
+            const resolvedPromptConfig = promptConfig!;
+            system = resolvedPromptConfig.variables
+                ? renderTemplate(resolved.content, resolvedPromptConfig.variables)
                 : resolved.content;
 
             // Store prompt metadata for the session (read by middleware during logging)
@@ -950,18 +1540,25 @@ ${userContextBlock || "None"}
             }
 
             logger.info("cl.generateText called", {
-                slug: promptConfig.slug,
+                slug: resolvedPromptConfig.slug,
                 version: resolved.version,
                 systemLength: system.length,
             });
-        } else {
+        } else if (promptConfig?.slug) {
             logger.info("cl.generateText called without resolved prompt", {
                 slug: promptConfig.slug,
             });
         }
 
         const model = resolveModel(options.model, resolved?.gatewaySlug);
-        return aiGenerateText({ ...rest, model, ...(system && { system }) } as any);
+        const nextParams = withAutoInjectedTools(
+            { ...rest, model, ...(system && { system }) },
+            session,
+            baseUrl,
+            clConfig.apiKey,
+            kognitive,
+        );
+        return aiGenerateText(nextParams as any);
     };
 
     // Return the model wrapper function with streamText/generateText attached
@@ -975,9 +1572,13 @@ ${userContextBlock || "None"}
             if (sessionKey) {
                 sessionSnapshots.delete(sessionKey);
                 sessionPromptMetadata.delete(sessionKey);
+                for (const key of sessionTurnIndexes.keys()) {
+                    if (key.endsWith(`:${sessionKey}`)) sessionTurnIndexes.delete(key);
+                }
             } else {
                 sessionSnapshots.clear();
                 sessionPromptMetadata.clear();
+                sessionTurnIndexes.clear();
             }
         },
     });