@nextsparkjs/core 0.1.0-beta.3 → 0.1.0-beta.4

package/templates/contents/plugins/langchain/lib/agent-helpers.ts

@@ -1,201 +0,0 @@
-/**
- * ============================================================================
- * AGENT HELPERS FACTORY
- * ============================================================================
- *
- * Provides utility functions for working with agent configurations.
- * Themes define their agents in langchain.config.ts, then use these helpers.
- *
- * USAGE:
- * ```typescript
- * // In theme's langchain.config.ts
- * import { createAgentHelpers } from '@/plugins/langchain/lib/agent-helpers'
- *
- * export const AGENTS = { ... }
- * export const helpers = createAgentHelpers(AGENTS)
- * // or destructure: export const { getAgentConfig, getAgentTools } = createAgentHelpers(AGENTS)
- * ```
- *
- * ============================================================================
- */
-
-import type {
-    AgentDefinition,
-    AgentContext,
-    SessionConfig,
-    ToolDefinition,
-    ThemeLangChainConfig,
-} from '../types/langchain.types'
-
-/**
- * Agent helpers interface - all utilities for working with agent configs
- */
-export interface AgentHelpers {
-    /** Get complete configuration for an agent */
-    getAgentConfig: (agentName: string) => AgentDefinition | undefined
-
-    /** Get model configuration (provider, model, temperature) */
-    getAgentModelConfig: (agentName: string) => Partial<{
-        provider: 'openai' | 'anthropic' | 'ollama'
-        model: string
-        temperature: number
-    }> | undefined
-
-    /** Get tools for an agent with runtime context */
-    getAgentTools: (agentName: string, context: AgentContext) => ToolDefinition<any>[]
-
-    /** Get system prompt name (to be loaded from .md file) */
-    getAgentPromptName: (agentName: string) => string | undefined
-
-    /** Get session configuration for an agent (TTL, maxMessages) */
-    getAgentSessionConfig: (agentName: string) => SessionConfig | undefined
-
-    /** Get enrichContext function for an agent */
-    getAgentEnrichContext: (agentName: string) => ((context: AgentContext) => Promise<AgentContext>) | undefined
-
-    /** Check if an agent is configured */
-    hasAgent: (agentName: string) => boolean
-
-    /** Get all configured agent names */
-    getAgentNames: () => string[]
-}
-
-/**
- * Create agent helper functions bound to a specific agents configuration.
- *
- * @param agents - Record of agent name to AgentDefinition
- * @param defaults - Optional default values for provider/model/temperature
- * @returns Object with all helper functions
- *
- * @example
- * ```typescript
- * const AGENTS = {
- *     'single-agent': {
- *         provider: 'ollama',
- *         model: 'llama3.2:3b',
- *         temperature: 0.3,
- *         systemPrompt: 'single-agent',
- *         createTools: (ctx) => [...tools],
- *     },
- * }
- *
- * const helpers = createAgentHelpers(AGENTS)
- * const config = helpers.getAgentConfig('single-agent')
- * const tools = helpers.getAgentTools('single-agent', { userId, teamId })
- * ```
- */
-export function createAgentHelpers(
-    agents: Record<string, AgentDefinition>,
-    defaults?: {
-        provider?: 'openai' | 'anthropic' | 'ollama'
-        model?: string
-        temperature?: number
-    }
-): AgentHelpers {
-    return {
-        /**
-         * Get complete configuration for an agent
-         */
-        getAgentConfig(agentName: string): AgentDefinition | undefined {
-            return agents[agentName]
-        },
-
-        /**
-         * Get model configuration for an agent (provider, model, temperature)
-         */
-        getAgentModelConfig(agentName: string): Partial<{
-            provider: 'openai' | 'anthropic' | 'ollama'
-            model: string
-            temperature: number
-        }> | undefined {
-            const agent = agents[agentName]
-            if (!agent) {
-                // Fall back to defaults if provided
-                if (defaults?.provider) {
-                    return {
-                        provider: defaults.provider,
-                        model: defaults.model,
-                        temperature: defaults.temperature,
-                    }
-                }
-                return undefined
-            }
-
-            return {
-                provider: agent.provider,
-                model: agent.model,
-                temperature: agent.temperature,
-            }
-        },
-
-        /**
-         * Get tools for an agent with runtime context
-         */
-        getAgentTools(
-            agentName: string,
-            context: AgentContext
-        ): ToolDefinition<any>[] {
-            const agent = agents[agentName]
-            if (!agent?.createTools) {
-                return []
-            }
-            return agent.createTools(context) as ToolDefinition<any>[]
-        },
-
-        /**
-         * Get system prompt name for an agent
-         * Returns the prompt name to be loaded from .md file
-         */
-        getAgentPromptName(agentName: string): string | undefined {
-            const agent = agents[agentName]
-            return agent?.systemPrompt
-        },
-
-        /**
-         * Get session configuration for an agent (TTL, maxMessages)
-         */
-        getAgentSessionConfig(agentName: string): SessionConfig | undefined {
-            const agent = agents[agentName]
-            return agent?.sessionConfig
-        },
-
-        /**
-         * Get enrichContext function for an agent
-         */
-        getAgentEnrichContext(
-            agentName: string
-        ): ((context: AgentContext) => Promise<AgentContext>) | undefined {
-            const agent = agents[agentName]
-            return agent?.enrichContext
-        },
-
-        /**
-         * Check if an agent is configured
-         */
-        hasAgent(agentName: string): boolean {
-            return agentName in agents
-        },
-
-        /**
-         * Get all configured agent names
-         */
-        getAgentNames(): string[] {
-            return Object.keys(agents)
-        },
-    }
-}
-
-/**
- * Create helpers from a full ThemeLangChainConfig
- * Convenience function that extracts agents and defaults
- */
-export function createHelpersFromConfig(config: ThemeLangChainConfig): AgentHelpers {
-    return createAgentHelpers(
-        config.agents || {},
-        {
-            provider: config.defaultProvider,
-            model: config.defaultModel,
-            temperature: config.defaultTemperature,
-        }
-    )
-}

package/templates/contents/plugins/langchain/lib/db-memory-store.ts

@@ -1,417 +0,0 @@
-/**
- * Database Memory Store for LangChain
- *
- * Persistent storage for conversation history using PostgreSQL.
- * Supports multi-tenancy with userId + teamId + sessionId isolation.
- * Supports multiple conversations per user with no expiration by default.
- */
-
-import { BaseMessage, HumanMessage } from '@langchain/core/messages'
-import { queryWithRLS, mutateWithRLS, query } from '@nextsparkjs/core/lib/db'
-import {
-    serializeMessages,
-    deserializeMessages,
-    type SerializedMessage,
-} from './message-serializer'
-import type { AgentContext, SessionConfig } from '../types/langchain.types'
-
-/**
- * Conversation/Session information returned by list and get operations
- */
-export interface ConversationInfo {
-    sessionId: string
-    name: string | null
-    messageCount: number
-    firstMessage: string | null
-    isPinned: boolean
-    createdAt: Date
-    updatedAt: Date
-}
-
-/**
- * Conversation limits
- */
-export const CONVERSATION_LIMITS = {
-    MAX_CONVERSATIONS: 50,
-    MAX_MESSAGES_PER_CONVERSATION: 50,
-} as const
-
-const DEFAULT_MAX_MESSAGES = CONVERSATION_LIMITS.MAX_MESSAGES_PER_CONVERSATION
-const DEFAULT_TTL_HOURS: number | null = null // No expiration by default
-
-/**
- * Row type from database
- */
-interface SessionRow {
-    id: string
-    userId: string
-    teamId: string
-    sessionId: string
-    name: string | null
-    isPinned: boolean
-    messages: SerializedMessage[]
-    maxMessages: number
-    expiresAt: Date | null
-    createdAt: Date
-    updatedAt: Date
-}
-
-/**
- * Generate a new session ID
- */
-export function generateSessionId(userId: string): string {
-    return `${userId}-${Date.now()}`
-}
-
-/**
- * Extract first human message content from serialized messages
- */
-function getFirstHumanMessage(messages: SerializedMessage[]): string | null {
-    const humanMessage = messages.find((m) => m.type === 'human')
-    if (!humanMessage) return null
-
-    const content = humanMessage.content
-    if (typeof content === 'string') {
-        return content.slice(0, 100) // Truncate to 100 chars
-    }
-    return null
-}
-
-/**
- * Database-backed memory store with full multi-tenancy support
- */
-export const dbMemoryStore = {
-    /**
-     * Get messages for a session
-     */
-    getMessages: async (
-        sessionId: string,
-        context: AgentContext
-    ): Promise<BaseMessage[]> => {
-        const { userId, teamId } = context
-
-        const result = await queryWithRLS<SessionRow>(
-            `SELECT messages
-             FROM public."langchain_sessions"
-             WHERE "userId" = $1 AND "teamId" = $2 AND "sessionId" = $3
-             AND ("expiresAt" IS NULL OR "expiresAt" > now())`,
-            [userId, teamId, sessionId],
-            userId
-        )
-
-        if (!result.length) return []
-
-        return deserializeMessages(result[0].messages)
-    },
-
-    /**
-     * Get full session info (not just messages)
-     */
-    getSession: async (
-        sessionId: string,
-        context: AgentContext
-    ): Promise<ConversationInfo | null> => {
-        const { userId, teamId } = context
-
-        const result = await queryWithRLS<SessionRow>(
-            `SELECT "sessionId", name, "isPinned", messages, "createdAt", "updatedAt"
-             FROM public."langchain_sessions"
-             WHERE "userId" = $1 AND "teamId" = $2 AND "sessionId" = $3
-             AND ("expiresAt" IS NULL OR "expiresAt" > now())`,
-            [userId, teamId, sessionId],
-            userId
-        )
-
-        if (!result.length) return null
-
-        const row = result[0]
-        return {
-            sessionId: row.sessionId,
-            name: row.name,
-            messageCount: row.messages.length,
-            firstMessage: getFirstHumanMessage(row.messages),
-            isPinned: row.isPinned,
-            createdAt: row.createdAt,
-            updatedAt: row.updatedAt,
-        }
-    },
-
-    /**
-     * Add messages to a session (upsert with sliding window)
-     * Auto-generates name from first message if not set
-     *
-     * OPTIMIZED: Uses a single query with CTE instead of 3 separate queries
-     * - Reads existing messages, combines with new, applies sliding window
-     * - All done atomically in PostgreSQL
-     */
-    addMessages: async (
-        sessionId: string,
-        messages: BaseMessage[],
-        context: AgentContext,
-        config: SessionConfig = {}
-    ): Promise<void> => {
-        const { userId, teamId } = context
-        const maxMessages = config.maxMessages || DEFAULT_MAX_MESSAGES
-        const ttlHours = config.ttlHours === undefined ? DEFAULT_TTL_HOURS : config.ttlHours
-
-        // Serialize new messages
-        const newMessagesSerialized = serializeMessages(messages)
-
-        // Auto-generate name from first human message
-        let autoName: string | null = null
-        if (messages.length > 0) {
-            const firstHuman = messages.find((m) => m instanceof HumanMessage)
-            if (firstHuman) {
-                const content = firstHuman.content
-                if (typeof content === 'string') {
-                    autoName = content.slice(0, 50) // First 50 chars
-                }
-            }
-        }
-
-        // Calculate expiresAt
-        const expiresAt = ttlHours !== null
-            ? new Date(Date.now() + ttlHours * 60 * 60 * 1000)
-            : null
-
-        // Single atomic query: read existing + combine + sliding window + upsert
-        // Uses CTE to:
-        // 1. Get existing messages (or empty array)
-        // 2. Combine with new messages
-        // 3. Apply sliding window (keep last N messages)
-        // 4. Upsert the result
-        await mutateWithRLS(
-            `WITH existing_session AS (
-                SELECT messages, name
-                FROM public."langchain_sessions"
-                WHERE "userId" = $1 AND "teamId" = $2 AND "sessionId" = $3
-            ),
-            combined AS (
-                SELECT COALESCE((SELECT messages FROM existing_session), '[]'::jsonb) || $4::jsonb as all_msgs
-            ),
-            windowed AS (
-                SELECT COALESCE(
-                    (
-                        SELECT jsonb_agg(value ORDER BY ordinality)
-                        FROM (
-                            SELECT value, ordinality
-                            FROM combined, jsonb_array_elements(all_msgs) WITH ORDINALITY
-                        ) sub
-                        WHERE ordinality > jsonb_array_length((SELECT all_msgs FROM combined)) - $5
-                    ),
-                    $4::jsonb
-                ) as final_msgs
-            )
-            INSERT INTO public."langchain_sessions"
-                (id, "userId", "teamId", "sessionId", messages, "maxMessages", "expiresAt", name)
-            SELECT
-                gen_random_uuid()::text, $1, $2, $3,
-                (SELECT final_msgs FROM windowed),
-                $5, $6,
-                COALESCE((SELECT name FROM existing_session), $7)
-            ON CONFLICT ("userId", "teamId", "sessionId")
-            DO UPDATE SET
-                messages = EXCLUDED.messages,
-                "expiresAt" = COALESCE(public."langchain_sessions"."expiresAt", EXCLUDED."expiresAt"),
-                name = COALESCE(public."langchain_sessions".name, EXCLUDED.name),
-                "updatedAt" = now()`,
-            [userId, teamId, sessionId, JSON.stringify(newMessagesSerialized), maxMessages, expiresAt, autoName],
-            userId
-        )
-    },
-
-    /**
-     * Create a new empty session/conversation
-     */
-    createSession: async (
-        context: AgentContext,
-        name?: string
-    ): Promise<{ sessionId: string; createdAt: Date }> => {
-        const { userId, teamId } = context
-        const sessionId = generateSessionId(userId)
-
-        const result = await queryWithRLS<{ sessionId: string; createdAt: Date }>(
-            `INSERT INTO public."langchain_sessions"
-             (id, "userId", "teamId", "sessionId", messages, name)
-             VALUES (gen_random_uuid()::text, $1, $2, $3, '[]'::jsonb, $4)
-             RETURNING "sessionId", "createdAt"`,
-            [userId, teamId, sessionId, name || null],
-            userId
-        )
-
-        return result[0]
-    },
-
-    /**
-     * Rename a session
-     */
-    renameSession: async (
-        sessionId: string,
-        name: string,
-        context: AgentContext
-    ): Promise<void> => {
-        const { userId, teamId } = context
-
-        await mutateWithRLS(
-            `UPDATE public."langchain_sessions"
-             SET name = $4, "updatedAt" = now()
-             WHERE "userId" = $1 AND "teamId" = $2 AND "sessionId" = $3`,
-            [userId, teamId, sessionId, name],
-            userId
-        )
-    },
-
-    /**
-     * Toggle pin status of a session
-     */
-    togglePinSession: async (
-        sessionId: string,
-        isPinned: boolean,
-        context: AgentContext
-    ): Promise<void> => {
-        const { userId, teamId } = context
-
-        await mutateWithRLS(
-            `UPDATE public."langchain_sessions"
-             SET "isPinned" = $4, "updatedAt" = now()
-             WHERE "userId" = $1 AND "teamId" = $2 AND "sessionId" = $3`,
-            [userId, teamId, sessionId, isPinned],
-            userId
-        )
-    },
-
-    /**
-     * Count sessions for a user (for limit enforcement)
-     */
-    countSessions: async (context: AgentContext): Promise<number> => {
-        const { userId, teamId } = context
-
-        const result = await queryWithRLS<{ count: string }>(
-            `SELECT COUNT(*)::text as count
-             FROM public."langchain_sessions"
-             WHERE "userId" = $1 AND "teamId" = $2
-             AND ("expiresAt" IS NULL OR "expiresAt" > now())`,
-            [userId, teamId],
-            userId
-        )
-
-        return parseInt(result[0]?.count || '0', 10)
-    },
-
-    /**
-     * Get oldest session (for suggesting deletion when limit reached)
-     */
-    getOldestSession: async (
-        context: AgentContext
-    ): Promise<ConversationInfo | null> => {
-        const { userId, teamId } = context
-
-        const result = await queryWithRLS<SessionRow>(
-            `SELECT "sessionId", name, "isPinned", messages, "createdAt", "updatedAt"
-             FROM public."langchain_sessions"
-             WHERE "userId" = $1 AND "teamId" = $2
-             AND ("expiresAt" IS NULL OR "expiresAt" > now())
-             AND "isPinned" = false
-             ORDER BY "updatedAt" ASC
-             LIMIT 1`,
-            [userId, teamId],
-            userId
-        )
-
-        if (!result.length) return null
-
-        const row = result[0]
-        return {
-            sessionId: row.sessionId,
-            name: row.name,
-            messageCount: row.messages.length,
-            firstMessage: getFirstHumanMessage(row.messages),
-            isPinned: row.isPinned,
-            createdAt: row.createdAt,
-            updatedAt: row.updatedAt,
-        }
-    },
-
-    /**
-     * Clear/delete a session
-     */
-    clearSession: async (
-        sessionId: string,
-        context: AgentContext
-    ): Promise<void> => {
-        const { userId, teamId } = context
-
-        await mutateWithRLS(
-            `DELETE FROM public."langchain_sessions"
-             WHERE "userId" = $1 AND "teamId" = $2 AND "sessionId" = $3`,
-            [userId, teamId, sessionId],
-            userId
-        )
-    },
-
-    /**
-     * Clean up expired sessions (run periodically)
-     * Only cleans sessions with expiresAt set and expired.
-     * Sessions with expiresAt = NULL are never cleaned up.
-     */
-    cleanup: async (): Promise<number> => {
-        const result = await query<{ id: string }>(
-            `DELETE FROM public."langchain_sessions"
-             WHERE "expiresAt" IS NOT NULL AND "expiresAt" < now()
-             RETURNING id`
-        )
-
-        return result.rowCount
-    },
-
-    /**
-     * Get all sessions for a user in a team
-     * Returns sessions sorted by: pinned first, then by updatedAt desc
-     */
-    listSessions: async (
-        context: AgentContext
-    ): Promise<ConversationInfo[]> => {
-        const { userId, teamId } = context
-
-        const result = await queryWithRLS<SessionRow>(
-            `SELECT "sessionId", name, "isPinned", messages, "createdAt", "updatedAt"
-             FROM public."langchain_sessions"
-             WHERE "userId" = $1 AND "teamId" = $2
-             AND ("expiresAt" IS NULL OR "expiresAt" > now())
-             ORDER BY "isPinned" DESC, "updatedAt" DESC`,
-            [userId, teamId],
-            userId
-        )
-
-        return result.map((row) => ({
-            sessionId: row.sessionId,
-            name: row.name,
-            messageCount: row.messages.length,
-            firstMessage: getFirstHumanMessage(row.messages),
-            isPinned: row.isPinned,
-            createdAt: row.createdAt,
-            updatedAt: row.updatedAt,
-        }))
-    },
-
-    /**
-     * Extend session TTL (deprecated - sessions now have no expiration by default)
-     * @deprecated Use for legacy support only
-     */
-    extendSession: async (
-        sessionId: string,
-        context: AgentContext,
-        ttlHours: number = 24
-    ): Promise<void> => {
-        const { userId, teamId } = context
-        const expiresAt = new Date(Date.now() + ttlHours * 60 * 60 * 1000)
-
-        await mutateWithRLS(
-            `UPDATE public."langchain_sessions"
-             SET "expiresAt" = $4, "updatedAt" = now()
-             WHERE "userId" = $1 AND "teamId" = $2 AND "sessionId" = $3`,
-            [userId, teamId, sessionId, expiresAt],
-            userId
-        )
-    },
-}

package/templates/contents/plugins/langchain/lib/graph/index.ts

@@ -1,58 +0,0 @@
-/**
- * LangGraph Orchestrator - Main Export (GENERIC)
- *
- * Explicit state machine for multi-agent orchestration.
- * Replaces inefficient ReAct loops with deterministic graph flow.
- *
- * GENERIC ARCHITECTURE:
- * - Plugin exports generic interfaces (AgentTool, OrchestratorConfig)
- * - Theme provides tool implementations and configuration
- * - No hardcoded entity knowledge in plugin
- */
-
-// Generic types (NEW)
-export type {
-    AgentTool,
-    OrchestratorConfig,
-    GenericHandlerResult,
-} from './types'
-
-// Core types
-export type {
-    OrchestratorState,
-    Intent,
-    IntentType,
-    IntentAction,
-    RouterOutput,
-    HandlerResults,
-    GraphConfig,
-    RouterRoute,
-    PostHandlerRoute,
-    HandlerNodeFn,
-    ModelConfig,
-    SystemIntentType,
-} from './types'
-
-// Deprecated types (backward compatibility)
-export type {
-    TaskHandlerResult,
-    CustomerHandlerResult,
-    PageHandlerResult,
-    TaskData,
-    CustomerData,
-    PageData,
-    HandlerFactories,
-} from './types'
-
-export { createInitialState, DEFAULT_GRAPH_CONFIG } from './types'
-
-// Graph
-export { createOrchestratorGraph, invokeOrchestrator } from './orchestrator-graph'
-
-// Router node factory (NEW - replaces direct routerNode export)
-export { createRouterNode } from './nodes/router'
-
-// Core nodes
-export { combinerNode } from './nodes/combiner'
-
-// Handler nodes are theme-specific - themes must provide implementations via OrchestratorConfig