flock-core 0.5.0b63__tar.gz → 0.5.0b65__tar.gz

{flock_core-0.5.0b63 → flock_core-0.5.0b65}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flock-core
-Version: 0.5.0b63
+Version: 0.5.0b65
 Summary: Add your description here
 Author-email: Andre Ratzenberger <andre.ratzenberger@whiteduck.de>
 License-File: LICENSE
@@ -9,6 +9,7 @@ Requires-Dist: devtools>=0.12.2
 Requires-Dist: dspy==3.0.0
 Requires-Dist: duckdb>=1.1.0
 Requires-Dist: fastapi>=0.117.1
+Requires-Dist: hanging-threads>=2.0.7
 Requires-Dist: httpx>=0.28.1
 Requires-Dist: litellm==1.75.3
 Requires-Dist: loguru>=0.7.3

flock_core-0.5.0b65/docs/bugfixes/websocket-streaming-deadlock-fix.md

@@ -0,0 +1,203 @@
+# WebSocket Streaming Deadlock Fix
+
+## Issue Description
+
+**Symptom**: When using the dashboard UI, agent execution would freeze (deadlock) when the agent called MCP tools during streaming, particularly with filesystem operations. The issue did NOT occur when running via CLI without the dashboard.
+
+**Affected Component**: `src/flock/engines/dspy_engine.py` - streaming execution with WebSocket broadcasting
+
+## Root Cause Analysis
+
+### The Deadlock Scenario
+
+The deadlock occurred due to a **circular wait condition** in the async event loop:
+
+1. **Agent starts streaming** tokens via WebSocket: `await ws_manager.broadcast(event)`
+2. **Agent calls an MCP tool** (e.g., filesystem read) - this is an `await` operation
+3. **WebSocket send buffer fills up** because the client can't process messages fast enough
+4. **`broadcast()` blocks** waiting for `client.send_text(message)` to complete (500ms timeout)
+5. **Client is blocked** waiting for the agent to finish
+6. **Agent can't continue** because it's waiting for `broadcast()` to return
+
+This creates a **circular dependency**:
+```
+Streaming loop → await broadcast() → await client.send_text() → 
+  → client waiting for response → agent waiting to send → 
+    → agent blocked on MCP tool → deadlock!
+```
+
+### Why It Only Happened with Dashboard
+
+- **CLI mode**: No WebSocket, streaming goes directly to console (no blocking I/O to client)
+- **Dashboard mode**: WebSocket adds network I/O and client buffering, creating blocking points
+
+### Key Code Pattern (Before Fix)
+
+```python
+async for value in stream_generator:
+    if isinstance(value, StatusMessage):
+        # ... process token ...
+        
+        # BLOCKING: Waits for WebSocket to complete send
+        await ws_manager.broadcast(event)  # ← DEADLOCK HERE
+        
+    # ... later ...
+    
+    # MCP tool call happens here
+    result = await server.call_tool(...)  # ← Can't reach if blocked above
+```
+
+## The Fix
+
+### Solution: Non-Blocking WebSocket Broadcasts
+
+Changed all `await ws_manager.broadcast(event)` calls inside the streaming loop to **fire-and-forget** using `asyncio.create_task()`:
+
+```python
+# Before (blocking)
+await ws_manager.broadcast(event)
+
+# After (non-blocking)
+task = asyncio.create_task(ws_manager.broadcast(event))
+ws_broadcast_tasks.add(task)
+task.add_done_callback(ws_broadcast_tasks.discard)
+```
+
+### Changes Made
+
+**File**: `src/flock/engines/dspy_engine.py`
+
+1. **Added asyncio import**:
+   ```python
+   import asyncio
+   ```
+
+2. **Track background tasks** to prevent garbage collection:
+   ```python
+   # Track background WebSocket broadcast tasks to prevent garbage collection
+   ws_broadcast_tasks: set[asyncio.Task] = set()
+   ```
+
+3. **Updated all broadcast calls** (4 locations in streaming loop):
+   - `StatusMessage` handling (line ~625)
+   - `StreamResponse` handling (line ~670)
+   - `ModelResponseStream` handling (line ~715)
+   - Final `Prediction` handling (lines ~745, ~760)
+
+### Why This Works
+
+1. **Breaks the circular wait**: Streaming loop doesn't wait for WebSocket sends to complete
+2. **Maintains order**: Tasks are created in sequence, AsyncIO scheduler maintains order
+3. **Prevents garbage collection**: Tasks stored in set until completion
+4. **Graceful error handling**: Errors in broadcast don't crash the streaming loop
+5. **Timeout still applies**: WebSocket still has 500ms timeout per client (in broadcast method)
+
+## Testing
+
+### Before Fix
+```bash
+# This would deadlock when agent calls filesystem tool
+uv run python examples/03-the-dashboard/test_streaming_fix.py
+# Result: Hangs indefinitely when tool is called
+```
+
+### After Fix
+```bash
+# Should complete successfully
+uv run python examples/03-the-dashboard/test_streaming_fix.py
+# Result: Streams tokens, calls tool, completes normally
+```
+
+### Verification Steps
+
+1. **Start dashboard example** with MCP filesystem tools
+2. **Publish artifact** that triggers agent with tool calls
+3. **Observe streaming**: Should see tokens streaming in real-time
+4. **Tool execution**: Agent should call filesystem tools without freezing
+5. **Completion**: Agent should finish and display final output
+
+## Related Code
+
+### WebSocket Timeout Protection
+
+The WebSocket broadcast already had timeout protection (500ms per client):
+
+```python
+# In src/flock/dashboard/websocket.py
+send_tasks = [
+    asyncio.wait_for(client.send_text(message), timeout=0.5)  # 500ms timeout
+    for client in clients_list
+]
+results = await asyncio.gather(*send_tasks, return_exceptions=True)
+```
+
+This timeout prevented infinite hangs on individual client sends, but didn't prevent the streaming loop from blocking.
+
+### MCP Tool Execution
+
+MCP tools are async operations that can take time:
+
+```python
+# In src/flock/mcp/tool.py
+async def func(*args, **kwargs):
+    result = await server.call_tool(
+        agent_id=self.agent_id,
+        run_id=self.run_id,
+        name=self.name,
+        arguments=kwargs,
+    )
+    return self._convert_mcp_tool_result(result)
+```
+
+When streaming loop blocks on `await broadcast()`, it can't reach tool execution.
+
+## Lessons Learned
+
+### Async Programming Gotchas
+
+1. **Never block in a loop that generates async events**: Use `create_task()` for background operations
+2. **Always track background tasks**: Prevents garbage collection and allows cleanup
+3. **WebSocket I/O is a blocking point**: Even with timeouts, can create circular waits
+4. **Test with real network conditions**: CLI vs Dashboard revealed the issue
+
+### Best Practices Applied
+
+1. ✅ **Fire-and-forget for broadcasts**: Don't wait for all clients to receive
+2. ✅ **Task tracking**: Prevent garbage collection with set + done_callback
+3. ✅ **Timeout protection**: Already in place at WebSocket level (500ms)
+4. ✅ **Error isolation**: try/except around each broadcast creation
+5. ✅ **Sequence preservation**: Tasks maintain order in AsyncIO scheduler
+
+## Impact
+
+### Fixed
+- ✅ Dashboard streaming works with MCP tool calls
+- ✅ No more deadlocks during agent execution
+- ✅ Real-time token streaming continues during tool execution
+
+### No Regressions
+- ✅ CLI mode still works (no WebSocket = no change)
+- ✅ Streaming order preserved (AsyncIO guarantees)
+- ✅ Error handling unchanged (try/except still catches failures)
+- ✅ Client timeout protection still active (500ms per client)
+
+## Future Considerations
+
+### Potential Improvements
+
+1. **Backpressure handling**: Could monitor `ws_broadcast_tasks` size and pause streaming if queue gets too large
+2. **Broadcast batching**: Could batch multiple tokens into single broadcast for efficiency
+3. **Client-side buffering**: Could implement client-side buffer to handle burst traffic
+4. **Metrics**: Could track broadcast task queue size and completion time
+
+### Architecture Decision
+
+**Decision**: Use fire-and-forget for WebSocket broadcasts during streaming
+**Rationale**: Streaming must not block on network I/O; client displays are eventually consistent
+**Trade-off**: Slight delay in UI updates vs. preventing deadlocks (clear win for preventing deadlocks)
+
+## Version
+
+- **Fixed in**: v0.5.0b64 (or current version)
+- **Issue discovered**: October 9, 2025
+- **Fix applied**: October 9, 2025

flock_core-0.5.0b65/docs/guides/mcp-roots.md

@@ -0,0 +1,416 @@
+# MCP Root/Mount Point Feature
+
+## Overview
+
+The MCP Root/Mount Point feature allows you to control which filesystem directories MCP servers can access on a **per-agent, per-server** basis. This provides fine-grained security and isolation for agents working with filesystem tools.
+
+## Key Features
+
+✨ **Server-Specific Mounts**: Different mount points for different MCP servers
+🔒 **Per-Agent Isolation**: Each agent can have its own directory restrictions
+🎯 **Explicit API**: Clear syntax showing which mounts apply to which servers
+🔄 **Backward Compatible**: Old `.mount()` API still works (with deprecation warning)
+
+## Architecture
+
+### How It Works
+
+1. **Agent Definition**: Use `.with_mcps({server: [paths]})` to specify mount points per server
+2. **Runtime**: Server-specific mount points are passed to the MCP client manager
+3. **Client Creation**: Each (agent_id, run_id) gets isolated MCP client with server-specific roots
+4. **Server Notification**: Client notifies each MCP server only about roots relevant to it
+
+### Protocol Flow
+
+```
+Agent.with_mcps({"filesystem": ["/workspace/src"]})
+    ↓
+Manager.get_tools_for_agent(server_mounts={"filesystem": ["/workspace/src"]})
+    ↓
+For each server:
+    Manager.get_client(server_name, mount_points=["/workspace/src"])
+    ↓
+    Client.__init__ (sets current_roots from config.mount_points)
+    ↓
+    Client._perform_initial_handshake()
+    ↓
+    client_session.send_roots_list_changed()  [Notify server]
+    ↓
+    Server calls list_roots_callback()  [Request roots]
+    ↓
+    Callback returns ListRootsResult(roots=["/workspace/src"])  [Provide roots]
+```
+
+## Usage
+
+### Basic Example - Single Server
+
+```python
+from flock.orchestrator import Flock
+from flock.mcp import StdioServerParameters
+
+flock = Flock(model="openai/gpt-4")
+
+# Register MCP server with roots feature
+flock.add_mcp(
+    name="filesystem",
+    connection_params=StdioServerParameters(
+        command="npx",
+        args=["-y", "@modelcontextprotocol/server-filesystem"]
+    ),
+    enable_roots_feature=True
+)
+
+# Agent with server-specific mount points
+(
+    flock.agent("src_agent")
+    .with_mcps({"filesystem": ["/workspace/src"]})  # ← Explicit server + mounts
+    .consumes(Request)
+    .publishes(Response)
+)
+```
+
+### Multiple Mount Points for One Server
+
+```python
+# Agent with multiple mount points for a single server
+(
+    flock.agent("multi_dir_agent")
+    .with_mcps({
+        "filesystem": ["/data", "/logs", "/config"]  # Multiple directories
+    })
+    .consumes(Request)
+    .publishes(Response)
+)
+```
+
+### Multiple Servers with Different Mounts
+
+```python
+# Register multiple MCP servers
+flock.add_mcp(name="filesystem", connection_params=..., enable_roots_feature=True)
+flock.add_mcp(name="github", connection_params=..., enable_roots_feature=True)
+
+# Agent using multiple servers with different mount points
+(
+    flock.agent("multi_server_agent")
+    .with_mcps({
+        "filesystem": ["/workspace/src", "/data"],  # Filesystem mounts
+        "github": ["/workspace/.git"],              # GitHub mounts
+    })
+    .consumes(Request)
+    .publishes(Response)
+)
+```
+
+### Mixed Format (Backward Compatible)
+
+```python
+# Some servers with mounts, others without
+(
+    flock.agent("mixed_agent")
+    .with_mcps([
+        {"filesystem": ["/workspace/src"]},  # With mounts
+        "github",                             # No mounts (unrestricted)
+    ])
+    .consumes(Request)
+    .publishes(Response)
+)
+```
+
+### No Mount Restrictions
+
+```python
+# Agent with no mount restrictions (full access)
+(
+    flock.agent("unrestricted_agent")
+    .with_mcps(["filesystem"])  # String format = no restrictions
+    .consumes(Request)
+    .publishes(Response)
+)
+```
+
+## API Reference
+
+### MCPServerConfig (TypedDict)
+
+```python
+class MCPServerConfig(TypedDict, total=False):
+    """Configuration for MCP server assignment to an agent.
+
+    All fields are optional. If omitted, no restrictions apply.
+
+    Attributes:
+        roots: Filesystem paths this server can access.
+               Empty list or omitted = no mount restrictions.
+        tool_whitelist: Tool names the agent can use from this server.
+                       Empty list or omitted = all tools available.
+    """
+    roots: list[str]
+    tool_whitelist: list[str]
+```
+
+### AgentBuilder.with_mcps()
+
+```python
+def with_mcps(
+    self,
+    servers: Iterable[str] | dict[str, MCPServerConfig] | list[str | dict[str, MCPServerConfig]]
+) -> AgentBuilder:
+    """Assign MCP servers to agent with optional server-specific mount points.
+
+    Args:
+        servers: One of:
+            - List of server names (strings) - no specific mounts
+            - Dict mapping server names to MCPServerConfig - with restrictions
+            - Mixed list of strings and dicts for flexibility
+
+    Returns:
+        AgentBuilder for method chaining
+
+    Raises:
+        ValueError: If any server name is not registered
+        TypeError: If invalid server specification format
+
+    Examples:
+        # Simple: no mount restrictions
+        agent.with_mcps(["filesystem", "github"])
+
+        # Server-specific mounts and tool whitelist
+        agent.with_mcps({
+            "filesystem": {
+                "roots": ["/workspace/src", "/data"],
+                "tool_whitelist": ["read_file", "write_file"]
+            },
+            "github": {}  # No restrictions for github
+        })
+
+        # Mixed format
+        agent.with_mcps([
+            "github",  # No mounts
+            {"filesystem": {"roots": ["/workspace/src"]}}  # With mounts
+        ])
+    """
+```
+
+### AgentBuilder.mount() [Deprecated]
+
+```python
+def mount(
+    self,
+    paths: str | list[str],
+    *,
+    validate: bool = False
+) -> AgentBuilder:
+    """Mount agent in specific directories for MCP root access.
+    
+    .. deprecated:: 0.2.0
+        Use `.with_mcps({"server_name": ["/path"]})` instead.
+        
+    Args:
+        paths: Single path or list of paths to mount
+        validate: If True, validate that paths exist
+        
+    Returns:
+        AgentBuilder for method chaining
+    """
+```
+
+### Flock.add_mcp()
+
+```python
+def add_mcp(
+    self,
+    name: str,
+    connection_params: ServerParameters,
+    *,
+    enable_roots_feature: bool = True,
+    mount_points: list[str] | None = None,  # Global default
+    ...
+) -> Flock:
+    """Register MCP server with optional global mount points."""
+```
+
+## Security Considerations
+
+### Best Practices
+
+1. **Principle of Least Privilege**: Only mount directories agents actually need
+2. **Server-Specific Mounts**: Use dict format to be explicit about which server gets which mounts
+3. **Agent-Specific Mounts**: Prefer per-agent mounts over global defaults
+4. **Avoid Root Access**: Never mount `/` unless absolutely necessary
+
+### Example: Secure File Processing
+
+```python
+# ❌ BAD: All servers get unrestricted access
+(
+    flock.agent("file_processor")
+    .with_mcps(["filesystem", "github"])  # Both have unrestricted access
+    .consumes(FileRequest)
+    .publishes(FileData)
+)
+
+# ✅ GOOD: Each server gets only what it needs
+(
+    flock.agent("file_processor")
+    .with_mcps({
+        "filesystem": ["/data/input"],  # Filesystem only reads from input
+        "github": ["/workspace/.git"],  # GitHub only accesses git directory
+    })
+    .consumes(FileRequest)
+    .publishes(FileData)
+)
+
+# ✅ BETTER: Separate agents with minimal permissions
+(
+    flock.agent("file_reader")
+    .with_mcps({"filesystem": ["/data/input"]})  # Read only
+    .consumes(FileRequest)
+    .publishes(FileData)
+)
+
+(
+    flock.agent("file_writer")
+    .with_mcps({"filesystem": ["/data/output"]})  # Write only
+    .consumes(FileData)
+    .publishes(FileResult)
+)
+```
+
+## Implementation Details
+
+### Server-Specific Mount Points
+
+Each server only receives the mount points specified for it:
+
+```python
+agent.with_mcps({
+    "filesystem": ["/workspace/src"],
+    "github": ["/workspace/.git"],
+})
+
+# When connecting to "filesystem" → roots = ["/workspace/src"]
+# When connecting to "github" → roots = ["/workspace/.git"]
+# Each server only knows about its own roots
+```
+
+### Per-(agent_id, run_id) Isolation
+
+Each unique (agent_id, run_id) pair gets its own isolated MCP client connection with server-specific mount points:
+
+```python
+# Same agent, different runs = different clients with same mounts
+await orchestrator.invoke(agent, request_1)  # run_id=123 → client_1 (filesystem: ["/src"])
+await orchestrator.invoke(agent, request_2)  # run_id=456 → client_2 (filesystem: ["/src"])
+```
+
+### Mount Point Precedence
+
+1. **Agent-level server-specific mounts** (highest priority): `agent.with_mcps({"server": ["/path"]})`
+2. **Server-level defaults**: `add_mcp(mount_points=["/path"])`
+3. **No restrictions** (lowest priority): No mounts specified
+
+### MCPRoot Format
+
+Mount points are converted to `MCPRoot` objects:
+
+```python
+# Input
+mount_points = ["/workspace/src", "/data"]
+
+# Converted to
+[
+    MCPRoot(uri="file:///workspace/src", name="src"),
+    MCPRoot(uri="file:///data", name="data")
+]
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**Issue**: Agent can't access files despite mount
+```python
+# Check if roots feature is enabled for the server
+flock.add_mcp(
+    name="filesystem",
+    connection_params=...,
+    enable_roots_feature=True  # ← Must be True
+)
+
+# Check if mounts are specified correctly
+agent.with_mcps({
+    "filesystem": ["/workspace/src"]  # ← Correct server name
+})
+```
+
+**Issue**: Wrong server getting mount points
+```python
+# ❌ BAD: Typo in server name
+agent.with_mcps({
+    "filesytem": ["/workspace/src"]  # Typo!
+})
+
+# ✅ GOOD: Correct server name
+agent.with_mcps({
+    "filesystem": ["/workspace/src"]  # Must match add_mcp() name
+})
+```
+
+**Issue**: Mount points not taking effect
+```python
+# Ensure mounts are specified in with_mcps() call
+agent = (
+    flock.agent("my_agent")
+    .with_mcps({"filesystem": ["/path"]})  # ← Mounts here, not separate
+    .consumes(Request)
+    .publishes(Response)
+)
+```
+
+### Debug Logging
+
+Enable debug logging to see root notifications:
+
+```python
+import logging
+
+logging.basicConfig(level=logging.DEBUG)
+
+# Look for these log messages:
+# INFO: Setting 2 mount point(s) for server 'filesystem' (agent=my_agent, run=123): ['file:///path1', 'file:///path2']
+# DEBUG: Notifying server 'filesystem' of 2 root(s): ['file:///path1', 'file:///path2']
+```
+
+### Migration from Deprecated API
+
+```python
+# OLD (deprecated)
+agent.with_mcps(["filesystem"]).mount("/workspace/src")
+
+# NEW (recommended)
+agent.with_mcps({"filesystem": ["/workspace/src"]})
+
+# Migration for multiple servers
+# OLD
+agent.with_mcps(["filesystem", "github"]).mount(["/workspace/src", "/data"])
+
+# NEW (specify per server)
+agent.with_mcps({
+    "filesystem": ["/workspace/src", "/data"],
+    "github": []  # Or omit if no mounts needed
+})
+```
+
+## Examples
+
+See working examples in:
+- [`examples/showcase/07_mcp_roots.py`](../examples/showcase/07_mcp_roots.py) - Complete demonstration
+- [`examples/showcase/04_mcp_tools.py`](../examples/showcase/04_mcp_tools.py) - Basic MCP usage
+
+## Related Documentation
+
+- [MCP Protocol Specification](https://spec.modelcontextprotocol.io/)
+- [Flock MCP Architecture](./mcp-architecture.md)
+- [Agent Builder API](./agent-builder.md)