@projectaria/cf-agents 0.1.1 → 0.1.2

package/dist/AriaAgent.js

@@ -1,756 +0,0 @@
-/**
- * ARIA Agent - Cloudflare Agents integration with proper memory primitives
- *
- * Memory Architecture:
- * 1. Session: Current conversation thread with chronological messages
- * 2. State: Temporary data within the current conversation (working memory)
- * 3. Memory: Searchable, cross-session information (knowledge base)
- *
- * AI SDK 6.0 Message Types (matching agents@0.3.3):
- * - UIMessage: Format with UI metadata (id, role, parts)
- * - ModelMessage: Format expected by LLM models
- * - convertToModelMessages: Converts UIMessage[] to ModelMessage[]
- */
-import { AIChatAgent } from "agents/ai-chat-agent";
-import { nanoid } from "nanoid";
-import { batchAriaToChat, batchChatToAria, extractConversationSummary, } from "./message-converter";
-/**
- * Default configuration
- */
-const DEFAULT_CONFIG = {
-    historyLimit: 50,
-    enableMemory: true,
-    memoryRetentionMs: 30 * 24 * 60 * 60 * 1000, // 30 days
-    trackTransitions: true,
-    generateSessionId: () => crypto.randomUUID(),
-};
-/**
- * ARIA Agent extending AIChatAgent
- *
- * Provides:
- * - Session management with conversation history
- * - State management (working memory) for session-local data
- * - Memory layer for cross-session knowledge
- * - Flow orchestration integration
- * - Multi-turn conversation support
- */
-export class AriaAgent extends AIChatAgent {
-    config;
-    flowDefinitions;
-    constructor(ctx, env) {
-        super(ctx, env);
-        this.config = { ...DEFAULT_CONFIG };
-        this.flowDefinitions = new Map();
-        // Create ARIA-specific tables
-        this.initializeTables();
-    }
-    /**
-     * Initialize ARIA-specific database tables
-     */
-    initializeTables() {
-        // Memory table for cross-session knowledge
-        this.sql `
-      create table if not exists aria_memory (
-        id text primary key,
-        session_id text,
-        key text not null,
-        value text not null,
-        type text not null check(type in ('preference', 'fact', 'context', 'entity', 'custom')),
-        created_at integer default (unixepoch()),
-        last_accessed_at integer default (unixepoch()),
-        access_count integer default 1,
-        embedding text,
-        metadata text
-      )
-    `;
-        this.sql `create index if not exists idx_memory_session
-      on aria_memory(session_id)`;
-        this.sql `create index if not exists idx_memory_key
-      on aria_memory(key)`;
-        this.sql `create index if not exists idx_memory_type
-      on aria_memory(type)`;
-        // Flow transitions table for tracking execution history
-        this.sql `
-      create table if not exists aria_flow_transitions (
-        id text primary key,
-        flow_id text not null,
-        from_node_id text,
-        to_node_id text not null,
-        transitioned_at integer default (unixepoch()),
-        metadata text
-      )
-    `;
-        this.sql `create index if not exists idx_flow_transitions_flow
-      on aria_flow_transitions(flow_id, transitioned_at)`;
-        // Session history table (in addition to AIChatAgent's messages)
-        this.sql `
-      create table if not exists aria_session_events (
-        id text primary key,
-        event_type text not null,
-        event_data text,
-        occurred_at integer default (unixepoch())
-      )
-    `;
-    }
-    /**
-     * Initial state when no session exists
-     */
-    initialState = {
-        workingMemory: {},
-        activeFlowId: undefined,
-        activeNodeId: undefined,
-        historyLimit: DEFAULT_CONFIG.historyLimit,
-    };
-    // ============================================================
-    // SESSION MANAGEMENT
-    // ============================================================
-    /**
-     * Get the current session
-     * Session = Current conversation thread with chronological messages
-     */
-    getSession() {
-        const state = this.state;
-        return {
-            id: this.name,
-            messages: batchChatToAria(this.messages),
-            activeFlow: state.activeFlowId && state.activeNodeId
-                ? {
-                    flowId: state.activeFlowId,
-                    currentNodeId: state.activeNodeId,
-                    enteredAt: Date.now(),
-                }
-                : undefined,
-            historyLimit: state.historyLimit,
-            createdAt: this.getCreatedAt(),
-            updatedAt: Date.now(),
-        };
-    }
-    /**
-     * Get session creation time from storage
-     */
-    getCreatedAt() {
-        const row = this.sql `
-      select min(created_at) as created_at from aria_session_events
-    `;
-        return row?.[0]?.created_at || Date.now();
-    }
-    /**
-     * Record a session event for tracking
-     */
-    recordSessionEvent(eventType, eventData) {
-        this.sql `
-      insert into aria_session_events (id, event_type, event_data)
-      values (${nanoid()}, ${eventType}, ${JSON.stringify(eventData)})
-    `;
-    }
-    // ============================================================
-    // STATE MANAGEMENT (Session-Local Data)
-    // ============================================================
-    /**
-     * Get working memory (state within current conversation)
-     * Examples: shopping cart items, user preferences mentioned in this session
-     */
-    getWorkingMemory() {
-        return this.state.workingMemory || {};
-    }
-    /**
-     * Set a value in working memory
-     */
-    setWorkingMemory(key, value) {
-        const current = this.getWorkingMemory();
-        this.setState({
-            ...this.state,
-            workingMemory: {
-                ...current,
-                [key]: value,
-            },
-        });
-    }
-    /**
-     * Clear all working memory
-     */
-    clearWorkingMemory() {
-        this.setState({
-            ...this.state,
-            workingMemory: {},
-        });
-    }
-    /**
-     * Handle state updates (called by Cloudflare Agents framework)
-     * This is triggered whenever setState is called, either from the server or from a connected client.
-     *
-     * Use cases:
-     * - React state synchronization via useAgent hook
-     * - Logging state changes
-     * - Triggering side effects on state changes
-     *
-     * @param state - The updated state
-     * @param source - "server" if update came from the agent, or a Connection object if from a client
-     */
-    onStateUpdate(state, source) {
-        // Record state change for debugging/auditing
-        this.recordSessionEvent("state_update", {
-            source: source === "server" ? "server" : "client",
-            workingMemoryKeys: Object.keys(state.workingMemory || {}),
-            activeFlowId: state.activeFlowId,
-            activeNodeId: state.activeNodeId,
-        });
-    }
-    // ============================================================
-    // MEMORY LAYER (Cross-Session Knowledge)
-    // ============================================================
-    /**
-     * Store a memory for cross-session retrieval
-     * Memory = Searchable, cross-session information (knowledge base)
-     */
-    storeMemory(memory) {
-        const id = nanoid();
-        const now = Date.now();
-        this.sql `
-      insert into aria_memory (
-        id, session_id, key, value, type,
-        created_at, last_accessed_at, access_count, metadata
-      )
-      values (
-        ${id},
-        ${memory.sessionId ?? null},
-        ${memory.key},
-        ${JSON.stringify(memory.value)},
-        ${memory.type},
-        ${Math.floor(now / 1000)},
-        ${Math.floor(now / 1000)},
-        1,
-        ${memory.metadata ? JSON.stringify(memory.metadata) : null}
-      )
-    `;
-        return id;
-    }
-    /**
-     * Search memory by query
-     * Returns relevant memories across all sessions
-     */
-    searchMemories(query) {
-        const limit = query.limit || 10;
-        let rows = [];
-        // Use different queries based on search criteria
-        // Note: SQLite tagged template literals don't support dynamic queries
-        if (query.query && query.types && query.types.length > 0) {
-            // Search with text and type filter
-            const typeList = query.types.join(",");
-            const searchPattern = `%${query.query}%`;
-            rows = this.sql `
-        select * from aria_memory 
-        where key like ${searchPattern}
-        and type in (${typeList})
-        order by access_count desc, last_accessed_at desc 
-        limit ${limit}
-      ` || [];
-        }
-        else if (query.query) {
-            // Search with text only
-            const searchPattern = `%${query.query}%`;
-            rows = this.sql `
-        select * from aria_memory 
-        where key like ${searchPattern}
-        order by access_count desc, last_accessed_at desc 
-        limit ${limit}
-      ` || [];
-        }
-        else if (query.types && query.types.length > 0) {
-            // Search with type filter only
-            const typeList = query.types.join(",");
-            rows = this.sql `
-        select * from aria_memory 
-        where type in (${typeList})
-        order by access_count desc, last_accessed_at desc 
-        limit ${limit}
-      ` || [];
-        }
-        else {
-            // Get all memories
-            rows = this.sql `
-        select * from aria_memory 
-        order by access_count desc, last_accessed_at desc 
-        limit ${limit}
-      ` || [];
-        }
-        return rows.map((row) => ({
-            memory: {
-                id: row.id,
-                sessionId: row.session_id,
-                key: row.key,
-                value: JSON.parse(row.value),
-                type: row.type,
-                createdAt: row.created_at * 1000,
-                lastAccessedAt: row.last_accessed_at * 1000,
-                accessCount: row.access_count,
-                metadata: row.metadata ? JSON.parse(row.metadata) : undefined,
-            },
-            score: Math.min(1, row.access_count / 10), // Simple relevance score
-            relevance: row.access_count > 5 ? "high" : row.access_count > 2 ? "medium" : "low",
-        }));
-    }
-    /**
-     * Get a specific memory by key
-     */
-    getMemory(key) {
-        const rows = this.sql `
-      select * from aria_memory where key = ${key} limit 1
-    `;
-        if (!rows || rows.length === 0) {
-            return null;
-        }
-        return {
-            id: key,
-            sessionId: null,
-            key,
-            value: JSON.parse(rows[0].value),
-            type: rows[0].type,
-            createdAt: Date.now(),
-            lastAccessedAt: Date.now(),
-            accessCount: 1,
-        };
-    }
-    /**
-     * Update memory access (increments access count and updates timestamp)
-     */
-    updateMemoryAccess(key) {
-        this.sql `
-      update aria_memory
-      set access_count = access_count + 1, last_accessed_at = ${Math.floor(Date.now() / 1000)}
-      where key = ${key}
-    `;
-    }
-    /**
-     * Clean up old memories based on retention policy
-     */
-    cleanupOldMemories() {
-        const cutoff = Math.floor((Date.now() - this.config.memoryRetentionMs) / 1000);
-        this.sql `delete from aria_memory where created_at < ${cutoff}`;
-    }
-    // ============================================================
-    // FLOW ORCHESTRATION
-    // ============================================================
-    /**
-     * Register a flow definition
-     */
-    registerFlow(flow) {
-        this.flowDefinitions.set(flow.id, flow);
-    }
-    /**
-     * Record a flow transition
-     */
-    recordFlowTransition(flowId, fromNodeId, toNodeId, metadata) {
-        if (!this.config.trackTransitions) {
-            return;
-        }
-        this.sql `
-      insert into aria_flow_transitions (id, flow_id, from_node_id, to_node_id, metadata)
-      values (${nanoid()}, ${flowId}, ${fromNodeId}, ${toNodeId}, ${metadata ? JSON.stringify(metadata) : null})
-    `;
-        this.setState({
-            ...this.state,
-            activeFlowId: flowId,
-            activeNodeId: toNodeId,
-        });
-    }
-    /**
-     * Get flow transition history
-     */
-    getFlowHistory(flowId, limit = 100) {
-        let query = "select * from aria_flow_transitions";
-        if (flowId) {
-            query += ` where flow_id = ${flowId}`;
-        }
-        query += ` order by transitioned_at desc limit ${limit}`;
-        const rows = this.sql `
-      ${query}
-    `;
-        return (rows || []).map((row) => ({
-            id: row.id,
-            flowId: row.flow_id,
-            fromNodeId: row.from_node_id,
-            toNodeId: row.to_node_id,
-            transitionedAt: row.transitioned_at * 1000,
-            metadata: row.metadata ? JSON.parse(row.metadata) : undefined,
-        }));
-    }
-    // ============================================================
-    // MESSAGE HANDLING
-    // ============================================================
-    /**
-     * Handle incoming chat messages
-     * This is where ARIA's flow orchestration would be integrated
-     */
-    async onChatMessage(onFinish, options) {
-        // Record session event
-        this.recordSessionEvent("message_received", {
-            messageCount: this.messages.length,
-            workingMemoryKeys: Object.keys(this.getWorkingMemory()),
-        });
-        // Get current session
-        const session = this.getSession();
-        // Get conversation context from memory
-        const relevantMemories = this.searchMemories({
-            query: session.messages[session.messages.length - 1]?.content || "",
-            limit: 5,
-            types: ["context", "entity", "preference"],
-        });
-        // Build system prompt with context
-        const systemPrompt = this.buildSystemPrompt(session, relevantMemories);
-        // Here you would integrate ARIA's flow orchestration
-        // For now, return a basic response
-        // TODO: Integrate with @projectaria/aria VoltRuntime
-        // Example: Save learned facts to memory
-        const summary = extractConversationSummary(session.messages);
-        for (const topic of summary.topics.slice(0, 3)) {
-            this.storeMemory({
-                sessionId: session.id,
-                key: topic,
-                value: { mentioned: true, count: 1 },
-                type: "context",
-            });
-        }
-        // Call parent implementation
-        return super.onChatMessage(onFinish, options);
-    }
-    /**
-     * Build system prompt with conversation context
-     */
-    buildSystemPrompt(session, memories) {
-        const parts = [
-            "You are a helpful AI assistant.",
-            "You have access to conversation history and can recall information from previous conversations.",
-        ];
-        // Add active flow context
-        if (session.activeFlow) {
-            parts.push(`\nCurrent flow: ${session.activeFlow.flowId} (node: ${session.activeFlow.currentNodeId})`);
-        }
-        // Add working memory context
-        const workingMemory = this.getWorkingMemory();
-        if (Object.keys(workingMemory).length > 0) {
-            parts.push("\nCurrent session data:");
-            for (const [key, value] of Object.entries(workingMemory)) {
-                parts.push(`  - ${key}: ${JSON.stringify(value)}`);
-            }
-        }
-        // Add memory context
-        if (memories.length > 0) {
-            parts.push("\nRelevant information from previous conversations:");
-            for (const memory of memories) {
-                parts.push(`  - ${memory.memory.key}: ${JSON.stringify(memory.memory.value)}`);
-                this.updateMemoryAccess(memory.memory.key);
-            }
-        }
-        return parts.join("\n");
-    }
-    // ============================================================
-    // ARIA AGENT INTEGRATION
-    // ============================================================
-    /**
-     * Run an ARIA agent with persistence
-     * This method allows you to use ARIA's createAgent() with persistent memory
-     *
-     * @param agent - The ARIA agent created via createAgent()
-     * @param input - The user input
-     * @returns The agent response with persisted session state
-     */
-    async runAriaAgent(agent, input) {
-        // Get current session from persistent storage
-        const currentSession = this.getSession();
-        // Convert to ARIA AgentSession format
-        const ariaSession = {
-            sessionId: currentSession.id,
-            conversationId: currentSession.id,
-            history: batchAriaToChat(currentSession.messages),
-            workingMemory: this.getWorkingMemory(),
-            context: new Map(),
-            createdAt: new Date(currentSession.createdAt).toISOString(),
-            updatedAt: new Date(currentSession.updatedAt).toISOString(),
-        };
-        // Search for relevant memories
-        const relevantMemories = this.searchMemories({
-            query: input,
-            limit: 5,
-            types: ["preference", "fact", "context", "entity"],
-        });
-        // Build enhanced prompt with context
-        const prompt = this.buildAriaAgentPrompt(currentSession, relevantMemories, this.getWorkingMemory());
-        // Run the ARIA agent
-        // Note: systemPrompt should be passed via the agent config, not metadata
-        const result = await agent.generateText({
-            input,
-            session: ariaSession,
-        });
-        // Persist working memory changes
-        if (result.session) {
-            const stateBefore = JSON.stringify(ariaSession.workingMemory);
-            const stateAfter = JSON.stringify(result.session.workingMemory);
-            if (stateBefore !== stateAfter) {
-                // Merge the updated working memory into our persistent state
-                const currentWorkingMemory = this.getWorkingMemory();
-                const updatedWorkingMemory = {
-                    ...currentWorkingMemory,
-                    ...result.session.workingMemory,
-                };
-                this.setState({
-                    ...this.state,
-                    workingMemory: updatedWorkingMemory,
-                });
-            }
-            // Extract and store memories from the conversation
-            await this.extractAndStoreMemories(result.session);
-        }
-        return {
-            text: result.text,
-            session: result.session,
-        };
-    }
-    /**
-     * Stream an ARIA agent response with persistence
-     *
-     * @param agent - The ARIA agent created via createAgent()
-     * @param input - The user input
-     * @returns Stream result with session
-     */
-    async streamAriaAgent(agent, input) {
-        // Get current session from persistent storage
-        const currentSession = this.getSession();
-        // Convert to ARIA AgentSession format
-        const ariaSession = {
-            sessionId: currentSession.id,
-            conversationId: currentSession.id,
-            history: batchAriaToChat(currentSession.messages),
-            workingMemory: this.getWorkingMemory(),
-            context: new Map(),
-            createdAt: new Date(currentSession.createdAt).toISOString(),
-            updatedAt: new Date(currentSession.updatedAt).toISOString(),
-        };
-        // Search for relevant memories
-        const relevantMemories = this.searchMemories({
-            query: input,
-            limit: 5,
-            types: ["preference", "fact", "context", "entity"],
-        });
-        // Build enhanced prompt with context
-        const prompt = this.buildAriaAgentPrompt(currentSession, relevantMemories, this.getWorkingMemory());
-        // Stream the ARIA agent response
-        // Note: systemPrompt should be passed via the agent config, not metadata
-        const result = await agent.streamText({
-            input,
-            session: ariaSession,
-        });
-        // Note: For streaming, we need to handle persistence after the stream completes
-        // This is typically done in the onFinish callback
-        if (result.usage) {
-            result.usage.then(async () => {
-                await this.extractAndStoreMemories(ariaSession);
-            });
-        }
-        return {
-            fullStream: result.fullStream,
-            textStream: result.textStream,
-            usage: result.usage,
-        };
-    }
-    /**
-     * Build ARIA agent prompt with context from session and memories
-     */
-    buildAriaAgentPrompt(session, memories, workingMemory) {
-        const parts = ["You are a helpful AI assistant with memory."];
-        // Add working memory/state context
-        if (Object.keys(workingMemory).length > 0) {
-            parts.push("\n📋 Current Session Data:");
-            for (const [key, value] of Object.entries(workingMemory)) {
-                parts.push(`  ${key}: ${JSON.stringify(value)}`);
-            }
-        }
-        // Add memories from past conversations
-        if (memories.length > 0) {
-            parts.push("\n💭 Relevant Information from Past Conversations:");
-            for (const memoryResult of memories) {
-                const { memory } = memoryResult;
-                parts.push(`  [${memory.type}] ${memory.key}: ${JSON.stringify(memory.value)}`);
-                // Update access count for relevance tracking
-                this.updateMemoryAccess(memory.key);
-            }
-        }
-        return parts.join("\n");
-    }
-    /**
-     * Extract and store memories from ARIA agent conversation
-     */
-    async extractAndStoreMemories(ariaSession) {
-        const conversation = ariaSession.history;
-        // Analyze each message for memory extraction
-        for (const message of conversation) {
-            if (message.role === "user") {
-                // Extract text content
-                const text = message.parts
-                    .filter((p) => p.type === "text")
-                    .map((p) => p.text)
-                    .join(" ");
-                const content = text.toLowerCase();
-                // Detect preferences
-                if (content.includes("prefer") ||
-                    content.includes("like") ||
-                    content.includes("want")) {
-                    const prefKey = this.extractPreferenceKey(text);
-                    if (prefKey) {
-                        this.storeMemory({
-                            sessionId: ariaSession.sessionId,
-                            key: prefKey,
-                            value: { stated: text, timestamp: Date.now() },
-                            type: "preference",
-                        });
-                    }
-                }
-                // Detect facts
-                if (content.includes("my name is") ||
-                    content.includes("i live in") ||
-                    content.includes("i am a")) {
-                    const factKey = this.extractFactKey(text);
-                    if (factKey) {
-                        this.storeMemory({
-                            sessionId: null, // Global memory
-                            key: factKey,
-                            value: { stated: text, timestamp: Date.now() },
-                            type: "fact",
-                        });
-                    }
-                }
-            }
-        }
-    }
-    /**
-     * Extract preference key from message content
-     */
-    extractPreferenceKey(content) {
-        const lower = content.toLowerCase();
-        if (lower.includes("dark mode"))
-            return "pref:theme:dark";
-        if (lower.includes("light mode"))
-            return "pref:theme:light";
-        if (lower.includes("email updates"))
-            return "pref:email-updates";
-        if (lower.includes("notifications"))
-            return "pref:notifications";
-        // Pattern matching
-        const preferMatch = content.match(/i (?:prefer|like|want) (.+?)(?:\.|,|!|$)/i);
-        if (preferMatch) {
-            return `pref:custom:${preferMatch[1].trim().toLowerCase()}`;
-        }
-        return null;
-    }
-    /**
-     * Extract fact key from message content
-     */
-    extractFactKey(content) {
-        const lower = content.toLowerCase();
-        if (lower.includes("my name is")) {
-            const name = content.match(/name is (\w+)/i)?.[1];
-            return name ? `fact:name:${name}` : null;
-        }
-        if (lower.includes("i live in")) {
-            const location = content.match(/live in (\w+(?: \w+)*)/i)?.[1];
-            return location ? `fact:location:${location}` : null;
-        }
-        if (lower.includes("i am a")) {
-            const role = content.match(/i am a (\w+(?: \w+)*)/i)?.[1];
-            return role ? `fact:role:${role}` : null;
-        }
-        return null;
-    }
-    // ============================================================
-    // LIFECYCLE
-    // ============================================================
-    /**
-     * Called when agent starts
-     */
-    async onStart() {
-        this.recordSessionEvent("session_started", {
-            agentName: this.name,
-            timestamp: Date.now(),
-        });
-        // Cleanup old memories periodically
-        this.cleanupOldMemories();
-    }
-    /**
-     * Called when a client connects
-     */
-    async onConnect(connection, ctx) {
-        this.recordSessionEvent("client_connected", {
-            connectionId: connection.id,
-        });
-        return super.onConnect(connection, ctx);
-    }
-    /**
-     * Cleanup when destroyed
-     */
-    async destroy() {
-        // Record session end
-        this.recordSessionEvent("session_ended", {
-            messageCount: this.messages.length,
-            finalWorkingMemory: this.getWorkingMemory(),
-        });
-        // Drop ARIA tables
-        this.sql `drop table if exists aria_memory`;
-        this.sql `drop table if exists aria_flow_transitions`;
-        this.sql `drop table if exists aria_session_events`;
-        await super.destroy();
-    }
-    // ============================================================
-    // HTTP ENDPOINTS
-    // ============================================================
-    /**
-     * Handle HTTP requests
-     */
-    async onRequest(request) {
-        const url = new URL(request.url);
-        // GET /session - Get current session
-        if (url.pathname === "/session" && request.method === "GET") {
-            return Response.json(this.getSession());
-        }
-        // GET /working-memory - Get working memory
-        if (url.pathname === "/working-memory" && request.method === "GET") {
-            return Response.json(this.getWorkingMemory());
-        }
-        // PUT /working-memory - Set working memory value
-        if (url.pathname === "/working-memory" && request.method === "PUT") {
-            const body = await request.json();
-            this.setWorkingMemory(body.key, body.value);
-            return Response.json({ success: true });
-        }
-        // GET /memory - Search memories
-        if (url.pathname === "/memory" && request.method === "GET") {
-            const query = url.searchParams.get("q");
-            const type = url.searchParams.get("type");
-            const limit = parseInt(url.searchParams.get("limit") || "10", 10);
-            const results = this.searchMemories({
-                query: query || undefined,
-                types: type ? [type] : undefined,
-                limit,
-            });
-            return Response.json(results);
-        }
-        // POST /memory - Store memory
-        if (url.pathname === "/memory" && request.method === "POST") {
-            const body = await request.json();
-            const id = this.storeMemory(body);
-            return Response.json({ id, success: true });
-        }
-        // GET /flow-history - Get flow transition history
-        if (url.pathname === "/flow-history" && request.method === "GET") {
-            const flowId = url.searchParams.get("flowId") || undefined;
-            const limit = parseInt(url.searchParams.get("limit") || "100", 10);
-            return Response.json(this.getFlowHistory(flowId, limit));
-        }
-        // GET /summary - Get conversation summary
-        if (url.pathname === "/summary" && request.method === "GET") {
-            const summary = extractConversationSummary(batchChatToAria(this.messages));
-            return Response.json(summary);
-        }
-        return super.onRequest(request);
-    }
-}
-//# sourceMappingURL=AriaAgent.js.map