@cortexmemory/cli 0.27.3 → 0.27.4

package/templates/vercel-ai-quickstart/app/api/auth/login/route.ts

@@ -7,25 +7,69 @@
 import { getCortex } from "@/lib/cortex";
 import { verifyPassword, generateSessionToken } from "@/lib/password";
 
+/**
+ * Validates login request body structure.
+ * Returns validated credentials or null if invalid.
+ */
+function validateLoginBody(
+  body: unknown
+): { username: string; password: string } | null {
+  if (typeof body !== "object" || body === null) {
+    return null;
+  }
+
+  const record = body as Record<string, unknown>;
+
+  // Validate username field exists and is a non-empty string
+  const hasValidUsername =
+    "username" in record &&
+    typeof record.username === "string" &&
+    record.username.length > 0 &&
+    record.username.length <= 256;
+
+  // Validate password field exists and is a non-empty string
+  const hasValidPassword =
+    "password" in record &&
+    typeof record.password === "string" &&
+    record.password.length > 0 &&
+    record.password.length <= 1024;
+
+  if (!hasValidUsername || !hasValidPassword) {
+    return null;
+  }
+
+  return {
+    username: record.username as string,
+    password: record.password as string,
+  };
+}
+
+/**
+ * Safely extracts an error message for logging without exposing user data.
+ */
+function getSafeErrorMessage(error: unknown): string {
+  if (error instanceof Error) {
+    // Only include error name and a sanitized message
+    // Avoid logging full stack traces which may contain user data
+    return `${error.name}: ${error.message.slice(0, 200)}`;
+  }
+  return "Unknown error";
+}
+
 export async function POST(req: Request) {
   try {
     const body = await req.json();
-    const { username, password } = body;
 
-    // Validate input
-    if (!username || typeof username !== "string") {
+    // Validate input structure before extracting values
+    const credentials = validateLoginBody(body);
+    if (!credentials) {
       return Response.json(
-        { error: "Username is required" },
+        { error: "Username and password are required" },
         { status: 400 }
       );
     }
 
-    if (!password || typeof password !== "string") {
-      return Response.json(
-        { error: "Password is required" },
-        { status: 400 }
-      );
-    }
+    const { username, password } = credentials;
 
     const cortex = getCortex();
     const sanitizedUsername = username.toLowerCase();
@@ -73,7 +117,8 @@ export async function POST(req: Request) {
       sessionToken,
     });
   } catch (error) {
-    console.error("[Login Error]", error);
+    // Log sanitized error to prevent log injection
+    console.error("[Login Error]", getSafeErrorMessage(error));
 
     return Response.json(
       { error: "Failed to authenticate" },

package/templates/vercel-ai-quickstart/app/api/chat/route.ts

@@ -122,45 +122,100 @@ function generateTitle(message: string): string {
   return title;
 }
 
+/**
+ * Normalize messages to ensure they have the `parts` array format
+ * expected by AI SDK v6's convertToModelMessages.
+ *
+ * Handles:
+ * - Messages with `content` string (legacy format) -> converts to `parts` array
+ * - Messages with `role: "agent"` -> converts to `role: "assistant"`
+ * - Messages already in v6 format -> passes through unchanged
+ */
+function normalizeMessages(messages: unknown[]): unknown[] {
+  return messages.map((msg: unknown) => {
+    const m = msg as Record<string, unknown>;
+
+    // Normalize role: "agent" -> "assistant"
+    let role = m.role as string;
+    if (role === "agent") {
+      role = "assistant";
+    }
+
+    // Ensure parts array exists
+    let parts = m.parts as Array<{ type: string; text?: string }> | undefined;
+    if (!parts) {
+      // Convert content string to parts array
+      const content = m.content as string | undefined;
+      if (content) {
+        parts = [{ type: "text", text: content }];
+      } else {
+        parts = [];
+      }
+    }
+
+    return {
+      ...m,
+      role,
+      parts,
+    };
+  });
+}
+
+/**
+ * Extract text from a message (handles both content string and parts array)
+ */
+function getMessageText(message: { content?: string; parts?: Array<{ type: string; text?: string }> }): string {
+  if (typeof message.content === "string") {
+    return message.content;
+  }
+  if (message.parts && Array.isArray(message.parts)) {
+    return message.parts
+      .filter((part) => part.type === "text" && part.text)
+      .map((part) => part.text)
+      .join("");
+  }
+  return "";
+}
+
 export async function POST(req: Request) {
   try {
     const body = await req.json();
     const { messages, memorySpaceId, userId, conversationId: providedConversationId } = body;
 
+    // Validate messages array exists
+    if (!messages || !Array.isArray(messages)) {
+      return new Response(
+        JSON.stringify({ error: "messages array is required" }),
+        { status: 400, headers: { "Content-Type": "application/json" } },
+      );
+    }
+
     // Generate conversation ID if not provided (new chat)
     const conversationId = providedConversationId || 
       `conv-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
     const isNewConversation = !providedConversationId;
 
+    // Normalize messages to ensure they have the `parts` array format
+    // expected by AI SDK v6's convertToModelMessages
+    const normalizedMessages = normalizeMessages(messages);
+
     // Convert UIMessage[] from useChat to ModelMessage[] for streamText
     // Note: In AI SDK v6+, convertToModelMessages may return a Promise
-    const modelMessagesResult = convertToModelMessages(messages);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const modelMessagesResult = convertToModelMessages(normalizedMessages as any);
     const modelMessages =
       modelMessagesResult instanceof Promise
         ? await modelMessagesResult
         : modelMessagesResult;
 
     // Get the first user message for title generation
-    // AI SDK v5+ uses `parts` array instead of `content` string
     const firstUserMessage = messages.find((m: { role: string }) => m.role === "user") as {
       role: string;
       content?: string;
       parts?: Array<{ type: string; text?: string }>;
     } | undefined;
     
-    let messageText = "";
-    if (firstUserMessage) {
-      if (typeof firstUserMessage.content === "string") {
-        // Legacy format: content is a string
-        messageText = firstUserMessage.content;
-      } else if (firstUserMessage.parts && Array.isArray(firstUserMessage.parts)) {
-        // AI SDK v5+ format: extract text from parts array
-        messageText = firstUserMessage.parts
-          .filter((part) => part.type === "text" && part.text)
-          .map((part) => part.text)
-          .join("");
-      }
-    }
+    const messageText = firstUserMessage ? getMessageText(firstUserMessage) : "";
 
     // Use createUIMessageStream to send both LLM text and layer events
     return createUIMessageStreamResponse({

package/templates/vercel-ai-quickstart/app/api/chat-v6/route.ts

@@ -0,0 +1,333 @@
+/**
+ * Chat API Route (AI SDK v6 Style)
+ *
+ * This route uses AI SDK v6's patterns while maintaining full Cortex Memory
+ * capabilities including:
+ * - Memory recall (reading past memories)
+ * - Memory storage (saving new conversations)
+ * - Fact extraction (extracting knowledge from conversations)
+ * - Belief revision (superseding outdated facts)
+ * - Layer observer (real-time UI updates)
+ *
+ * The key difference from v5 is using v6's cleaner APIs, but the memory
+ * infrastructure is identical to ensure feature parity.
+ */
+
+import { createCortexMemoryAsync } from "@cortexmemory/vercel-ai-provider";
+import type {
+  LayerObserver,
+  CortexMemoryConfig,
+} from "@cortexmemory/vercel-ai-provider";
+import { openai, createOpenAI } from "@ai-sdk/openai";
+import {
+  streamText,
+  embed,
+  convertToModelMessages,
+  createUIMessageStream,
+  createUIMessageStreamResponse,
+} from "ai";
+import { getCortex } from "@/lib/cortex";
+
+// Create OpenAI client for embeddings
+const openaiClient = createOpenAI({ apiKey: process.env.OPENAI_API_KEY });
+
+// System prompt for the assistant
+const SYSTEM_PROMPT = `You are a helpful AI assistant with long-term memory powered by Cortex.
+
+Your capabilities:
+- You remember everything users tell you across conversations
+- You can recall facts, preferences, and context from past interactions
+- You naturally reference what you've learned about the user
+
+Behavior guidelines:
+- When you remember something from a previous conversation, mention it naturally
+- If asked about something you learned, reference it specifically
+- Be conversational and friendly
+- Help demonstrate the memory system by showing what you remember`;
+
+/**
+ * Create Cortex Memory config - IDENTICAL to v5 route for feature parity
+ */
+function getCortexMemoryConfig(
+  memorySpaceId: string,
+  userId: string,
+  conversationId: string,
+  layerObserver?: LayerObserver
+): CortexMemoryConfig {
+  return {
+    convexUrl: process.env.CONVEX_URL!,
+    memorySpaceId,
+
+    // User identification
+    userId,
+    userName: "Demo User",
+
+    // Agent identification
+    agentId: "cortex-memory-agent",
+    agentName: "Cortex v6 Assistant",
+
+    // Conversation ID for chat history isolation
+    conversationId,
+
+    // Enable graph memory sync
+    enableGraphMemory: process.env.CORTEX_GRAPH_SYNC === "true",
+
+    // Enable fact extraction - CRITICAL for memory to work!
+    enableFactExtraction: process.env.CORTEX_FACT_EXTRACTION === "true",
+
+    // Belief Revision - handles fact updates and supersessions
+    beliefRevision: {
+      enabled: true,
+      slotMatching: true,
+      llmResolution: true,
+    },
+
+    // Embedding provider for semantic matching
+    embeddingProvider: {
+      generate: async (text: string) => {
+        const result = await embed({
+          model: openaiClient.embedding("text-embedding-3-small"),
+          value: text,
+        });
+        return result.embedding;
+      },
+    },
+
+    // Streaming enhancements
+    streamingOptions: {
+      storePartialResponse: true,
+      progressiveFactExtraction: true,
+      enableAdaptiveProcessing: true,
+    },
+
+    // Memory recall configuration
+    memorySearchLimit: 20,
+
+    // Real-time layer tracking
+    layerObserver,
+
+    // Debug in development
+    debug: process.env.NODE_ENV === "development",
+  };
+}
+
+/**
+ * Normalize messages to AI SDK v6 UIMessage format
+ */
+function normalizeMessages(messages: unknown[]): unknown[] {
+  return messages.map((msg: unknown) => {
+    const m = msg as Record<string, unknown>;
+
+    // Normalize role: "agent" -> "assistant"
+    let role = m.role as string;
+    if (role === "agent") {
+      role = "assistant";
+    }
+
+    // Ensure parts array exists
+    let parts = m.parts as Array<{ type: string; text?: string }> | undefined;
+    if (!parts) {
+      const content = m.content as string | undefined;
+      if (content) {
+        parts = [{ type: "text", text: content }];
+      } else {
+        parts = [];
+      }
+    }
+
+    return {
+      ...m,
+      role,
+      parts,
+    };
+  });
+}
+
+/**
+ * Extract text from a message
+ */
+function getMessageText(message: {
+  content?: string;
+  parts?: Array<{ type: string; text?: string }>;
+}): string {
+  if (typeof message.content === "string") {
+    return message.content;
+  }
+  if (message.parts && Array.isArray(message.parts)) {
+    return message.parts
+      .filter((part) => part.type === "text" && part.text)
+      .map((part) => part.text)
+      .join("");
+  }
+  return "";
+}
+
+/**
+ * Generate a title from the first user message
+ */
+function generateTitle(message: string): string {
+  let title = message.slice(0, 50);
+  if (message.length > 50) {
+    const lastSpace = title.lastIndexOf(" ");
+    if (lastSpace > 20) {
+      title = title.slice(0, lastSpace);
+    }
+    title += "...";
+  }
+  return title;
+}
+
+export async function POST(req: Request) {
+  try {
+    const body = await req.json();
+    const {
+      messages,
+      memorySpaceId = "quickstart-demo",
+      userId = "demo-user",
+      conversationId: providedConversationId,
+    } = body;
+
+    // Validate messages array exists
+    if (!messages || !Array.isArray(messages)) {
+      return new Response(
+        JSON.stringify({ error: "messages array is required" }),
+        { status: 400, headers: { "Content-Type": "application/json" } }
+      );
+    }
+
+    // Generate conversation ID if not provided
+    const conversationId =
+      providedConversationId ||
+      `conv-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    const isNewConversation = !providedConversationId;
+
+    // Normalize messages for convertToModelMessages
+    const normalizedMessages = normalizeMessages(messages);
+
+    // Convert to model messages
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const modelMessagesResult = convertToModelMessages(normalizedMessages as any);
+    const modelMessages =
+      modelMessagesResult instanceof Promise
+        ? await modelMessagesResult
+        : modelMessagesResult;
+
+    // Get first user message for title
+    const firstUserMessage = messages.find(
+      (m: { role: string }) => m.role === "user"
+    ) as {
+      role: string;
+      content?: string;
+      parts?: Array<{ type: string; text?: string }>;
+    } | undefined;
+
+    const messageText = firstUserMessage ? getMessageText(firstUserMessage) : "";
+
+    // Use createUIMessageStreamResponse - same as v5 for full memory support
+    return createUIMessageStreamResponse({
+      stream: createUIMessageStream({
+        execute: async ({ writer }) => {
+          // Create layer observer for real-time UI updates
+          const layerObserver: LayerObserver = {
+            onOrchestrationStart: (orchestrationId) => {
+              writer.write({
+                type: "data-orchestration-start",
+                data: { orchestrationId },
+                transient: true,
+              });
+            },
+            onLayerUpdate: (event) => {
+              writer.write({
+                type: "data-layer-update",
+                data: {
+                  layer: event.layer,
+                  status: event.status,
+                  timestamp: event.timestamp,
+                  latencyMs: event.latencyMs,
+                  data: event.data,
+                  error: event.error,
+                  revisionAction: event.revisionAction,
+                  supersededFacts: event.supersededFacts,
+                },
+                transient: true,
+              });
+            },
+            onOrchestrationComplete: (summary) => {
+              writer.write({
+                type: "data-orchestration-complete",
+                data: {
+                  orchestrationId: summary.orchestrationId,
+                  totalLatencyMs: summary.totalLatencyMs,
+                  createdIds: summary.createdIds,
+                },
+                transient: true,
+              });
+            },
+          };
+
+          // Build config with observer
+          const config = getCortexMemoryConfig(
+            memorySpaceId,
+            userId,
+            conversationId,
+            layerObserver
+          );
+
+          // Create memory-augmented model - THIS handles both recall AND storage!
+          const cortexMemory = await createCortexMemoryAsync(config);
+
+          // Stream response with automatic memory integration
+          const result = streamText({
+            model: cortexMemory(openai("gpt-4o-mini")),
+            messages: modelMessages,
+            system: SYSTEM_PROMPT,
+          });
+
+          // Merge LLM stream into UI message stream
+          writer.merge(result.toUIMessageStream());
+
+          // Create conversation if new
+          if (isNewConversation && messageText) {
+            try {
+              const cortex = getCortex();
+              await cortex.conversations.create({
+                memorySpaceId,
+                conversationId,
+                type: "user-agent",
+                participants: {
+                  userId,
+                  agentId: "cortex-memory-agent",
+                },
+                metadata: { title: generateTitle(messageText) },
+              });
+
+              // Send conversation update to client
+              writer.write({
+                type: "data-conversation-update",
+                data: {
+                  conversationId,
+                  title: generateTitle(messageText),
+                },
+                transient: true,
+              });
+            } catch (error) {
+              console.error("Failed to create conversation:", error);
+            }
+          }
+        },
+      }),
+    });
+  } catch (error) {
+    console.error("[Chat v6 API Error]", error);
+
+    return new Response(
+      JSON.stringify({
+        error: error instanceof Error ? error.message : "Unknown error",
+      }),
+      {
+        status: 500,
+        headers: { "Content-Type": "application/json" },
+      }
+    );
+  }
+}

package/templates/vercel-ai-quickstart/app/page.tsx

@@ -1,8 +1,9 @@
 "use client";
 
 import dynamic from "next/dynamic";
-import { useState, useCallback } from "react";
+import { useState, useCallback, useEffect } from "react";
 import { useLayerTracking } from "@/lib/layer-tracking";
+import { detectVersions, type VersionInfo } from "@/lib/versions";
 import { AuthProvider, useAuth } from "@/components/AuthProvider";
 import { AdminSetup } from "@/components/AdminSetup";
 import { LoginScreen } from "@/components/LoginScreen";
@@ -52,6 +53,7 @@ function MainContent() {
   const { isLoading, isAdminSetup, isAuthenticated, user } = useAuth();
   const [memorySpaceId, setMemorySpaceId] = useState("quickstart-demo");
   const [currentConversationId, setCurrentConversationId] = useState<string | null>(null);
+  const [versions, setVersions] = useState<VersionInfo | null>(null);
   const {
     layers,
     isOrchestrating,
@@ -60,6 +62,11 @@ function MainContent() {
     resetLayers,
   } = useLayerTracking();
 
+  // Detect SDK versions on mount
+  useEffect(() => {
+    detectVersions().then(setVersions);
+  }, []);
+
   // Handle new chat
   const handleNewChat = useCallback(() => {
     setCurrentConversationId(null);
@@ -109,7 +116,7 @@ function MainContent() {
 
   // Main authenticated interface
   return (
-    <main className="min-h-screen flex flex-col">
+    <main className="h-screen flex flex-col overflow-hidden">
       {/* Header */}
       <header className="border-b border-white/10 px-6 py-4">
         <div className="flex items-center justify-between">
@@ -151,6 +158,7 @@ function MainContent() {
             memorySpaceId={memorySpaceId}
             userId={userId}
             conversationId={currentConversationId}
+            apiEndpoint={versions?.aiSdkMajor === 6 ? "/api/chat-v6" : "/api/chat"}
             onOrchestrationStart={startOrchestration}
             onLayerUpdate={updateLayer}
             onReset={resetLayers}
@@ -185,9 +193,15 @@ function MainContent() {
       <footer className="border-t border-white/10 px-6 py-3">
         <div className="flex items-center justify-between text-sm text-gray-500">
           <div className="flex items-center gap-4">
-            <span>Cortex SDK v0.24.0</span>
+            <span>Cortex SDK {versions ? `v${versions.cortexSdk}` : "..."}</span>
             <span>•</span>
-            <span>Vercel AI SDK v5</span>
+            <span>Vercel AI SDK {versions?.aiSdk ?? "..."}</span>
+            {versions?.aiSdkMajor === 6 && (
+              <>
+                <span>•</span>
+                <span className="text-cortex-400">Using ToolLoopAgent</span>
+              </>
+            )}
           </div>
           <a
             href="https://cortexmemory.dev/docs"

package/templates/vercel-ai-quickstart/components/ChatInterface.tsx

@@ -26,6 +26,8 @@ interface ChatInterfaceProps {
   memorySpaceId: string;
   userId: string;
   conversationId: string | null;
+  /** API endpoint for chat - defaults to /api/chat, use /api/chat-v6 for AI SDK v6 */
+  apiEndpoint?: string;
   onOrchestrationStart?: () => void;
   onLayerUpdate?: (
     layer: MemoryLayer,
@@ -44,6 +46,7 @@ export function ChatInterface({
   memorySpaceId,
   userId,
   conversationId,
+  apiEndpoint = "/api/chat",
   onOrchestrationStart,
   onLayerUpdate,
   onReset,
@@ -71,7 +74,7 @@ export function ChatInterface({
   const transport = useMemo(
     () =>
       new DefaultChatTransport({
-        api: "/api/chat",
+        api: apiEndpoint,
         // Use a function to get body so it reads latest conversationId from ref
         body: () => ({
           memorySpaceId,
@@ -79,7 +82,7 @@ export function ChatInterface({
           conversationId: conversationIdRef.current,
         }),
       }),
-    [memorySpaceId, userId], // Note: conversationId removed - ref handles updates
+    [apiEndpoint, memorySpaceId, userId], // Note: conversationId removed - ref handles updates
   );
 
   // Handle layer data parts from the stream

package/templates/vercel-ai-quickstart/jest.config.js

@@ -1,9 +1,10 @@
 /**
  * Jest Configuration for Vercel AI Quickstart
  *
- * Two test projects:
+ * Three test projects:
  * - unit: Fast unit tests with mocked dependencies
  * - integration: Integration tests for API routes with mocked SDK
+ * - e2e: End-to-end tests with real Cortex backend (requires CONVEX_URL, OPENAI_API_KEY)
  */
 
 const baseConfig = {
@@ -41,5 +42,11 @@ module.exports = {
       testMatch: ["<rootDir>/tests/integration/**/*.test.ts"],
       testTimeout: 30000,
     },
+    {
+      ...baseConfig,
+      displayName: "e2e",
+      testMatch: ["<rootDir>/tests/e2e/**/*.test.ts"],
+      testTimeout: 120000, // 2 minutes for real network calls
+    },
   ],
 };