Feature - Enable Streaming Capabilities For Tool Calls That Send Real-Time Notificaitons

CLAUDE.md

@@ -0,0 +1,182 @@
+# Flowise Codebase Guide
+
+## Project Overview
+
+Flowise is a visual flow-based tool for building LLM-powered applications, agents, and chatbots. It uses a node-based interface similar to Node-RED but specialized for AI workflows.
+
+**Architecture**: TypeScript monorepo (PNPM + Turbo) with three main packages:
+- `packages/components/` - Core node components and business logic 
+- `packages/server/` - Express backend with APIs and database
+- `packages/ui/` - React frontend with visual flow builder
+
+## Key Development Patterns
+
+### 1. Node Development Pattern
+
+All nodes follow a standardized interface in `packages/components/src/Interface.ts`:
+
+```typescript
+interface INode {
+    label: string           // Display name
+    name: string           // Unique identifier  
+    type: string           // Node category
+    version: number        // Version for compatibility
+    category: string       // UI grouping
+    baseClasses: string[]  // Output types
+    inputs: INodeParams[]  // Input configuration
+    outputs?: INodeOutputsValue[]
+    init?(nodeData: INodeData): Promise<any>
+    run?(nodeData: INodeData): Promise<any>
+}
+```
+
+**Node Categories**:
+- Agents, ChatModels, Tools, VectorStores, DocumentLoaders, Memory, Chains, AgentFlow
+
+### 2. Streaming Architecture
+
+Real-time updates use `IServerSideEventStreamer` interface with events like:
+- `streamTokenEvent()` - Token-by-token LLM responses
+- `streamToolEvent()` - Tool execution notifications  
+- `streamAgentReasoningEvent()` - Agent thought processes
+- `streamCustomEvent()` - Custom event types
+
+**Pattern**: Agents and chains receive `sseStreamer` via `options.sseStreamer` and call appropriate stream methods.
+
+### 3. Tool Integration Pattern
+
+Tools can be:
+- **Custom Functions**: User-defined JavaScript with Zod schema validation
+- **API Tools**: HTTP request wrappers (GET, POST, etc.)
+- **Chain Tools**: Embedded chatflows as tools
+- **MCP Tools**: Model Context Protocol integrations
+- **Service Tools**: Platform integrations (Google, GitHub, Slack)
+
+Tools receive runtime context via `RunnableConfig` parameter containing `chatId`, `sseStreamer`, etc.
+
+### 4. Agent Patterns
+
+**Traditional Agents**: Single LLM with tools (ReAct, Conversational)
+**Multi-Agent**: Supervisor-worker coordination patterns
+**AgentFlow v2**: Visual node-based agent orchestration with:
+- Conditional branching
+- Loops and iteration  
+- State management
+- Human-in-the-loop
+
+### 5. Database and API Patterns
+
+**TypeORM** entities in `/server/src/database/entities/`
+**RESTful APIs** with Express middleware for auth, rate limiting
+**Queue system** using BullMQ for background processing
+**WebSocket/SSE** for real-time communication
+
+## File Organization
+
+```
+packages/
+├── components/
+│   ├── nodes/           # All node implementations
+│   │   ├── agents/      # Agent nodes
+│   │   ├── tools/       # Tool integrations (including MCP)
+│   │   ├── chatmodels/  # LLM integrations
+│   │   └── chains/      # LangChain chains
+│   └── src/
+│       ├── Interface.ts # Core interfaces
+│       └── handler.ts   # Execution handlers
+├── server/
+│   ├── src/controllers/ # API endpoints
+│   ├── src/utils/       # SSEStreamer, buildChatflow
+│   └── src/database/    # Database entities and migrations
+└── ui/
+    ├── src/views/       # Page components
+    ├── src/api/         # API client functions
+    └── src/store/       # Redux store
+```
+
+## Development Guidelines
+
+### Adding New Nodes
+1. Create node file in appropriate `/nodes/` category
+2. Implement `INode` interface with `init()` and/or `run()` methods
+3. Export in `/components/src/index.ts`
+4. Add to category mapping in `/server/src/utils/buildChatflow.ts`
+
+### Adding Streaming Support
+1. Extract `sseStreamer` from `options.sseStreamer`
+2. Extract `chatId` from `options.chatId` or config
+3. Call appropriate `stream*Event()` methods during execution
+4. Use `streamCustomEvent()` for custom notification types
+
+### Working with Tools
+1. Tools are LangChain-compatible functions created with `tool()` helper
+2. Use Zod schemas for input validation
+3. Access runtime context via second `config` parameter
+4. Return string responses that get passed back through agent layer
+
+### MCP (Model Context Protocol) Pattern
+- MCP tools in `/nodes/tools/MCP/` create LangChain tool wrappers
+- Each tool call creates new MCP client connection
+- Notifications received via client event handlers
+- Currently notifications only logged to console (opportunity for enhancement)
+
+## Common Patterns
+
+### Error Handling
+- Use try/catch blocks in async operations
+- Return descriptive error messages as strings
+- Log errors for debugging but don't expose sensitive data
+
+### Configuration Management  
+- Use environment variables for external service configs
+- Store sensitive data in credentials system
+- Support both local and external credential storage
+
+### Testing Strategy
+- Component testing for individual nodes
+- Integration testing for complete flows
+- Use test databases for server tests
+- Mock external APIs in tests
+
+## Key Integration Points
+
+### UI to Server Communication
+- REST APIs for CRUD operations
+- WebSocket/SSE for real-time streaming
+- File uploads for document processing
+
+### Server to Components
+- Node execution via `run()` methods
+- Streaming via `IServerSideEventStreamer` 
+- State management through memory systems
+
+### External Integrations
+- LangChain ecosystem compatibility
+- OpenAI/Anthropic/Google API integrations
+- Vector database connections
+- Third-party service APIs (GitHub, Slack, etc.)
+
+## Current Development Focus Areas
+
+1. **AgentFlow v2**: Enhanced visual agent orchestration
+2. **Multi-agent systems**: Coordination and communication patterns
+3. **Real-time streaming**: Enhanced user feedback and monitoring
+4. **MCP integrations**: Model Context Protocol tool ecosystem
+5. **Enterprise features**: Workspaces, analytics, usage tracking
+
+## Troubleshooting Common Issues
+
+### Streaming Not Working
+- Check if `sseStreamer` is properly extracted from options
+- Verify `chatId` is available in context
+- Ensure streaming is enabled in flow configuration
+
+### Tool Execution Failures
+- Validate input schemas with Zod
+- Check credential configuration and permissions
+- Review tool return value format (should be string)
+
+### Node Not Appearing in UI
+- Verify node is exported in `/components/src/index.ts`
+- Check category mapping in buildChatflow.ts
+- Ensure node follows `INode` interface correctly

docs/api-testing/.gitignore

@@ -0,0 +1,22 @@
+# Dependencies
+node_modules/
+
+# Build outputs
+dist/
+*.tsbuildinfo
+
+# Logs
+*.log
+npm-debug.log*
+
+# Runtime files
+.env
+.env.local
+
+# IDE files
+.vscode/
+.idea/
+
+# OS files
+.DS_Store
+Thumbs.db

docs/api-testing/README.md

@@ -0,0 +1,138 @@
+# Flowise API Testing Documentation
+
+This folder contains testing scripts and documentation for Flowise API endpoints.
+
+## Available Tests
+
+### 1. Session Integration Test (Recommended)
+
+Complete end-to-end test that validates the full session workflow:
+1. Sends predictions with custom session ID
+2. Retrieves all messages for that session  
+3. Asserts messages exist and are correctly associated
+
+**File**: `session-integration-test.ts`
+
+```bash
+npm run test:session-integration
+```
+
+**What it tests**:
+- Custom session ID handling via `overrideConfig`
+- Message persistence in database
+- Session-based message retrieval
+- Message ordering and timestamps
+- Session ID consistency across requests
+
+### 2. Chat Message Retrieval by Session
+
+Test retrieving all messages for a specific session using the existing chat message endpoint.
+
+**Endpoint**: `GET /api/v1/chatmessage/{chatflowId}?sessionId={sessionId}`
+
+**Features**:
+- Retrieve all messages for a specific session
+- Filter by chat type, memory type, date range
+- Includes parsed response data (sourceDocuments, agentReasoning, etc.)
+- Supports pagination
+
+#### Basic Usage
+
+```typescript
+// Get all messages for a session
+const messages = await getSessionMessages(CHATFLOW_ID, SESSION_ID);
+
+// With additional filters
+const messages = await getSessionMessages(CHATFLOW_ID, SESSION_ID, {
+    chatType: ['EXTERNAL'],
+    memoryType: 'BufferMemory',
+    startDate: '2025-01-01',
+    endDate: '2025-12-31'
+});
+```
+
+#### Response Format
+
+```json
+[
+    {
+        "id": "message-uuid",
+        "role": "userMessage",
+        "chatflowid": "chatflow-uuid",
+        "content": "Hello, how are you?",
+        "chatId": "chat-uuid",
+        "sessionId": "session-uuid",
+        "memoryType": "BufferMemory",
+        "createdDate": "2025-08-28T14:30:45.123Z",
+        "sourceDocuments": [...],
+        "agentReasoning": [...],
+        "usedTools": [...],
+        "fileUploads": [...],
+        "artifacts": [...]
+    },
+    {
+        "id": "message-uuid-2",
+        "role": "apiMessage",
+        "content": "I'm doing well, thank you!",
+        // ... other fields
+    }
+]
+```
+
+### 2. Prediction API Testing
+
+Test the prediction API with both streaming and non-streaming modes.
+
+**Features**:
+- Non-streaming predictions
+- Streaming predictions with real-time token output
+- Error handling and response parsing
+- Timestamp validation (new feature)
+
+## Test Files
+
+- `chat-message-test.ts` - Session message retrieval tests
+- `prediction-test.ts` - Prediction API tests (streaming & non-streaming)
+- `config.ts` - Shared configuration and utilities
+
+## Setup
+
+1. Update configuration in `config.ts`:
+   ```typescript
+   export const FLOWISE_BASE_URL = 'https://your-flowise-instance.com';
+   export const CHATFLOW_ID = 'your-chatflow-id';
+   export const API_KEY = 'your-api-key'; // Optional
+   ```
+
+2. Install dependencies:
+   ```bash
+   npm install node-fetch @types/node typescript ts-node
+   ```
+
+3. Run tests:
+   ```bash
+   # Session message tests
+   npx ts-node chat-message-test.ts
+
+   # Prediction API tests
+   npx ts-node prediction-test.ts
+   ```
+
+## Authentication
+
+If your Flowise instance requires authentication, set the `API_KEY` in config.ts. The test scripts will automatically include it in the Authorization header.
+
+## Error Handling
+
+All test scripts include comprehensive error handling:
+- Network errors
+- HTTP error responses
+- JSON parsing errors
+- Streaming connection issues
+
+## Notes
+
+- The session message endpoint requires a valid `chatflowId` even when filtering by `sessionId`
+- Streaming responses use Server-Sent Events (SSE) format
+- All timestamps are in ISO 8601 format (UTC)
+- Response data includes parsed JSON fields (sourceDocuments, agentReasoning, etc.)